update documentation

dist/xrfragment.js

@@ -133,11 +133,11 @@ xrfragment_Parser.parse = function(key,value,resultMap) {
 			}
 			resultMap[key] = v;
 		} else {
-			console.log("src/xrfragment/Parser.hx:36:","[ i ] fragment '" + key + "' has incompatible value (" + value + ")");
+			console.log("src/xrfragment/Parser.hx:32:","[ i ] fragment '" + key + "' has incompatible value (" + value + ")");
 			return false;
 		}
 	} else {
-		console.log("src/xrfragment/Parser.hx:37:","[ i ] fragment '" + key + "' does not exist or has no type defined (yet)");
+		console.log("src/xrfragment/Parser.hx:33:","[ i ] fragment '" + key + "' does not exist or has no type defined (yet)");
 		return false;
 	}
 	return true;

doc/1.0.0/url.md

@@ -0,0 +1,42 @@
+
+# Fragment (values)
+ 
+| 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` |
+
+
+# Url parser (the gist of it)
+
+1. fragment URI starts with `#`
+1. fragments are split by `&`
+1. fragment-values are urlencoded (space becomes `+` using `encodeUriComponent` e.g.)
+1. `=` is used to split fragment key/values 
+1. `|` is used to split multiple/fallback values
+1. `,` assumes 1D/2D/3D vector-values like x[,y[,z]]
+1. parseFloat(..) and parseInt(..) is applied to vector/float and int values 
+1. anything else will be treated as string-value 
+1. 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|90,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})$/`
+1. integers are detected using regex `/^[0-9]+$/`
+1. floats are detected using regex `/^[0-9]+\.[0-9]+$/`
+1. vectors are detected using regex `/[,]/` (but can also be an string referring to an entity-ID in the asset)

doc/RFC.md

@@ -1,8 +1,10 @@
 > version 1.0.0
 
-date: 2023-03-31T13:32:38+0200 (generated by `./make doc`)
+date: 2023-03-31T14:39:54+0200 (generated by `./make doc`)
 
-# URI parser (the gist of it)
+# URI parser
+
+> icanhazcode? yes, see [Url.hx](./../src/xrfragment/Url.hx)
 
 1. fragment URI starts with `#`
 1. fragments are split by `&`
@@ -18,9 +20,12 @@ date: 2023-03-31T13:32:38+0200 (generated by `./make doc`)
 | prio    | int (-10..1)  | Asset linking           | `#prio=-5` |
 
 
-# XR Fragments parser (the gist of it)         
+# XR Fragments parser
 
-1. each key has a regex to validate its value-type (see regexes)
+> icanhazcode? yes, see [Parser.hx](./../src/xrfragment/Parser.hx)
+
+the gist of it:
+1. each key has a regex to validate its value-type (see regexes) 
 1. `|` is used to split multiple/fallback values
 1. `,` assumes 1D/2D/3D vector-values like x[,y[,z]]
 1. parseFloat(..) and parseInt(..) is applied to vector/float and int values 

src/xrfragment/Parser.hx

@@ -3,26 +3,22 @@ package xrfragment;
 @:expose                                                                   // <- makes the class reachable from plain JavaScript
 @:keep                                                                     // <- avoids accidental removal by dead code elimination
 
-class Parser {
+class Parser {                                                             //  # XR Fragments (key/value params)
-
+		public static var error:String = "";                                   //   
-		public static var error:String = "";
 
     @:keep
     public static function parse(key:String,value:String,resultMap:haxe.DynamicAccess<Dynamic>):Bool {
-                                                                           //  # XR Fragments (key/value params)
-                                                                           //   
                                                                            //  | param   | type          | category                | example          |
 			var Frag:Map<String, EReg> = new Map<String, EReg>();                //  |---------|---------------|-------------------------|------------------|
 			Frag.set("pos",  Type.isVector);                                     //  | pos     | 3D vector     | HREF navigation/portals | `#pos=1,0,1` or `#pos=foo` |
 			Frag.set("prio", Type.isInt);                                        //  | prio    | int (-10..1)  | Asset linking           | `#prio=-5` |
 											                                                     //  
-
+                                                                           //  # XR Fragments parser
-                                                                           //  # XR Fragments parser (the gist of it)         
       if( Frag.exists(key) ){                                              //  
-        if( Frag.get(key).match(value) ){                                  //  1. each key has a regex to validate its value-type (see regexes)
+        if( Frag.get(key).match(value) ){                                  //  > icanhazcode? yes, see [Parser.hx](./../src/xrfragment/Parser.hx)
-          var v:Value = new Value();
+          var v:Value = new Value();                                       //  
-          guessType(v, value);
+          guessType(v, value);                                             //  the gist of it:
-          // multiple/fallback values
+          // process multiple/fallback values                              //  1. each key has a regex to validate its value-type (see regexes) 
           if( value.split("|").length > 1 ){                               //  1. `|` is used to split multiple/fallback values
             v.args = new Array<Value>();
             var args:Array<String> = value.split("|");

src/xrfragment/Url.hx

@@ -9,12 +9,13 @@ class Url {
 
 		public static var error:String = "";
 
-    @:keep                                                                 //  # URI parser (the gist of it)
+    @:keep                                                                 //  # URI parser
     public static function parse(qs:String):haxe.DynamicAccess<Dynamic> {  //  
-      var fragment:Array<String>    = qs.split("#");                       //  1. fragment URI starts with `#`
+      var fragment:Array<String>    = qs.split("#");                       //  > icanhazcode? yes, see [Url.hx](./../src/xrfragment/Url.hx)
-      var splitArray:Array<String>  = fragment[1].split('&');              //  1. fragments are split by `&`
+      var splitArray:Array<String>  = fragment[1].split('&');              //  
-      var resultMap:haxe.DynamicAccess<Dynamic> = {};
+      var resultMap:haxe.DynamicAccess<Dynamic> = {};                      //  1. fragment URI starts with `#`
-      for (i in 0...splitArray.length) {
+        for (i in 0...splitArray.length) {                                 //  1. fragments are split by `&`
+
         var splitByEqual = splitArray[i].split('=');                       //  1. `=` is used to split fragment key/values 
         var regexPlus  = ~/\+/g;                                           //  1. fragment-values are urlencoded (space becomes `+` using `encodeUriComponent` e.g.)
         var key:String = splitByEqual[0];

test/generated/test.js

@@ -303,11 +303,11 @@ xrfragment_Parser.parse = function(key,value,resultMap) {
 			}
 			resultMap[key] = v;
 		} else {
-			console.log("src/xrfragment/Parser.hx:36:","[ i ] fragment '" + key + "' has incompatible value (" + value + ")");
+			console.log("src/xrfragment/Parser.hx:32:","[ i ] fragment '" + key + "' has incompatible value (" + value + ")");
 			return false;
 		}
 	} else {
-		console.log("src/xrfragment/Parser.hx:37:","[ i ] fragment '" + key + "' does not exist or has no type defined (yet)");
+		console.log("src/xrfragment/Parser.hx:33:","[ i ] fragment '" + key + "' does not exist or has no type defined (yet)");
 		return false;
 	}
 	return true;