xrfragment/doc/RFC.md

version 1.0.0

date: 2023-03-31T13:32:38+0200 (generated by ./make doc)

URI parser (the gist of it)

1. fragment URI starts with #
2. fragments are split by &
3. = is used to split fragment key/values
4. fragment-values are urlencoded (space becomes + using encodeUriComponent e.g.)
5. every recognized fragment key/value-pair is added to a central map/associative array/object

XR Fragments (key/value params)

param	type	category	example
pos	3D vector	HREF navigation/portals	#pos=1,0,1 or #pos=foo
prio	int (-10..1)	Asset linking	#prio=-5

XR Fragments parser (the gist of it)

1. each key has a regex to validate its value-type (see regexes)
2. | is used to split multiple/fallback values
3. , assumes 1D/2D/3D vector-values like x[,y[,z]]
4. parseFloat(..) and parseInt(..) is applied to vector/float and int values
5. anything else will be treated as string-value
6. 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.)

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

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

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)

Tests

the spec is tested with JSON unittests consumed by Test.hx to cross-test all languages.