document ui functions

[xprogramari]

all the ui functions are all the backend functions, there's no distinction, and they're all documented (where function is declared) and then that is automatically generated when b6 is made, and is available via b6-api --docs

[silky]

For the tested functionality in the shell, the tests are here: shell_test.go.

You can browse that file to see a list of expressions that are at least tested. It's not complete, but I wrote a terrible grep/sed invocation to extract the main examples:

LiteralInt:
 "42"

LiteralFloat:
 "42.0"

LiteralLatLng:
 `19.4008, -99.1663`

LiteralTag:
 `#highway=path`

LiteralSearchableTagWithToken:
 `#nhs:hospital=yes`

LiteralTagWithQuotes:
 `name="The Lighterman"`

SimpleCall:
 `find-feature /n/6082053666`

Pipeline2Stages:
 `find "highway=primary" | highlight`

Group:
 `find (intersecting 19.4008, -99.1663)`

FeatureID:
 "pair 55.614929, -2.8048709 /area/openstreetmap.org/way/115912092"

NestedGroups:
 "find (intersecting (find-area /area/openstreetmap.org/way/115912092))"

ExplicitLambdaWithArg:
 `map {f -> tag f "name"} (all-areas)`

ImplicitLambda:
 `map (tag "name") (all-areas)`

ExplicitLambdaWithoutArgs:
 `with-change {-> building-access}`

RootCallWithoutArgs:
 `all-areas`

PipeineWithExplicitLambda:
 `all-areas | {a -> highlight a}`

Pipeline3Stages:
 `all-areas | filter | highlight`

QueryTagWithoutValue:
 `find [#building]`

QueryNested:
 `find [#building=yes & [#shop=supermarket | #shop=convenience]]`

CollectionLiteral:
 `{"motorway": 36.0, "primary": 32.0}`

CollectionLiteralWithImplicitKeys:
 `{"motorway", "primary"}`

This is what I wrote:

shell_test.go | grep '{"\(.*\)", \(.*\), &pb' \
 | sed 's/\s*{"\([^"]*\)", \(.*\), &pb\.NodeProto{/\1:\n \2\n/'

Perhaps with this as a start, a documentation page could be started in the ./docs.

Ideally, this documentation could actually be auto-generated from the shell_test, at the very least, if not somewhere that reflects all the functionality.

[silky]

The functions are, in theory, these:

functions := testFunctionArgCounts{
"all-areas":    0,
"area":         1,
"count-values": 1,
"find-area":    1,
"find":         1,
"find-feature": 1,
"filter":       1,
"gt":           1,
"highlight":    1,
"intersecting": 1,
"map":          2,
"pair":         2,
"tag":          2,
}

but I note that there seem to be others; i.e. add-collection. Again, this could be made more complete.

[silky]

I realise now that the functions are, in fact, all of the ones defined in the normal list of api-functions; i.e. here: https://github.com/diagonalworks/diagonal-b6/blob/main/src/diagonal.works/b6/api/functions/functions.go#L22

What remains is to document (and test!) some combinations of all the evaluations.