xrfragment/doc/RFC.md

version 1.0.0

date: 2023-04-06T18:30:33+0200

XRFragment Grammar

    reserved    = gen-delims / sub-delims
    gen-delims  = "#" / "&"                      
    sub-delims  = "," / "|" / "="

Example: ://foo.com/my3d.asset#pos=1,0,0&prio=-5&t=0,100|100,200

Explanation:
| x=1,2,3 | vector/coordinate argument e.g. | | x=foo\|bar\|1\,2,3\|1.0 | the \| character is used for:
1.specifying n arguments for xrfragment x
2. fallback urls (src=https://x.co/f.gltf\|xyz://f.gltf)
3. roundrobin of values (in case provided arguments exceeds n of x for #1) when triggered by browser URI (clicking href e.g.)| | .mygroup | query-alias for class:mygroup |

Focus: hasslefree 3D vector-data (,), multi-protocol/fallback-linking & dynamic values (|), and CSS-piggybacking (.mygroup)

URI parser

icanhazcode? yes, see URI.hx

1. fragment URI starts with #
2. fragments are split by &
3. store key/values into a associative array or dynamic object
4. loop thru each fragment
5. for each fragment split on = to separate key/values
6. fragment-values are urlencoded (space becomes + using encodeUriComponent e.g.)
7. every recognized fragment key/value-pair is added to a central map/associative array/object

XR Fragments (key/value params)

⛁ = define in 3D asset-file (as custom property or default projection)
☇ = mutable, using navigator URI (document.location.href e.g.)

param	type	scope(s)	category	notes
prio	int (-10..1)	⛁	Asset loading / linking	#static allow client to ignore lower-prio objects in the renderloop, to compensate frame-drop/cpu/gpu-overload scenario’s
pos	3D vector	⛁ ☇	HREF navigation/portals
q	string	⛁	Query Selector

XR Fragments parser

note: community parsers will prolly outperform this initial parser :)

icanhazcode? yes, see Parser.hx the gist of it:

1. check if param exist
2. each key has a regex to validate its value-type (see regexes)
3. extract the type
4. use | on stringvalues, to split multiple/fallback values
5. for each multiple/fallback value, guess the type
6. , assumes 1D/2D/3D vector-values like x[,y[,z]]
7. parseFloat(..) and parseInt(..) is applied to vector/float and int values
8. anything else will be treated as string-value
9. incompatible value-types will be dropped / not used

the xrfragment specification should stay simple enough

for anyone to write a parser using either regexes or grammar/lexers

therefore expressions/comprehensions are not supported (max wildcard/comparison operators for queries e.g.)

Parser Value types

type	info	format	example
vector	x,y,z	comma-separated	#pos=1,2,3
string	color	FFFFFF (hex)	#fog=5m,FFAACC
string			#q=-sun
int		[-]x[xxxxx]	#price:>=100
float		[-]x[.xxxx] (ieee)	#prio=-20
array	mixed	|-separated	#pos=0,0,0|90,0,0

rule for thumb: type-limitations will piggyback JSON limitations (IEEE floatsize e.g.) Regexes:

1. hex colors are detected using regex /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/
2. integers are detected using regex /^[0-9]+$/
3. floats are detected using regex /^[0-9]+\.[0-9]+$/
4. vectors are detected using regex /[,]/ (but can also be an string referring to an entity-ID in the asset)
5. anything else is string /.*/