From 69df1be36e9dc3643ddda3cf2555ef2964d36e27 Mon Sep 17 00:00:00 2001 From: Leon van Kammen Date: Fri, 31 Mar 2023 14:40:24 +0200 Subject: [PATCH] update documentation --- dist/xrfragment.js | 4 ++-- doc/1.0.0/url.md | 42 ++++++++++++++++++++++++++++++++++++++++ doc/RFC.md | 13 +++++++++---- src/xrfragment/Parser.hx | 18 +++++++---------- src/xrfragment/Url.hx | 11 ++++++----- test/generated/test.js | 4 ++-- 6 files changed, 68 insertions(+), 24 deletions(-) create mode 100644 doc/1.0.0/url.md diff --git a/dist/xrfragment.js b/dist/xrfragment.js index f0610d9..9b4d140 100644 --- a/dist/xrfragment.js +++ b/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; diff --git a/doc/1.0.0/url.md b/doc/1.0.0/url.md new file mode 100644 index 0000000..1cf77cc --- /dev/null +++ b/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) diff --git a/doc/RFC.md b/doc/RFC.md index ed59d80..c4e9b58 100644 --- a/doc/RFC.md +++ b/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 diff --git a/src/xrfragment/Parser.hx b/src/xrfragment/Parser.hx index 7853c1b..58451a7 100644 --- a/src/xrfragment/Parser.hx +++ b/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 { - - public static var error:String = ""; +class Parser { // # XR Fragments (key/value params) + public static var error:String = ""; // @:keep public static function parse(key:String,value:String,resultMap:haxe.DynamicAccess):Bool { - // # XR Fragments (key/value params) - // // | param | type | category | example | var Frag:Map = new Map(); // |---------|---------------|-------------------------|------------------| 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 (the gist of it) + // # XR Fragments parser if( Frag.exists(key) ){ // - if( Frag.get(key).match(value) ){ // 1. each key has a regex to validate its value-type (see regexes) - var v:Value = new Value(); - guessType(v, value); - // multiple/fallback values + if( Frag.get(key).match(value) ){ // > icanhazcode? yes, see [Parser.hx](./../src/xrfragment/Parser.hx) + var v:Value = new Value(); // + guessType(v, value); // the gist of it: + // 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(); var args:Array = value.split("|"); diff --git a/src/xrfragment/Url.hx b/src/xrfragment/Url.hx index 8a11457..81e54f2 100644 --- a/src/xrfragment/Url.hx +++ b/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 { // - var fragment:Array = qs.split("#"); // 1. fragment URI starts with `#` - var splitArray:Array = fragment[1].split('&'); // 1. fragments are split by `&` - var resultMap:haxe.DynamicAccess = {}; - for (i in 0...splitArray.length) { + var fragment:Array = qs.split("#"); // > icanhazcode? yes, see [Url.hx](./../src/xrfragment/Url.hx) + var splitArray:Array = fragment[1].split('&'); // + var resultMap:haxe.DynamicAccess = {}; // 1. fragment URI starts with `#` + 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]; diff --git a/test/generated/test.js b/test/generated/test.js index 288e0ab..d11291c 100644 --- a/test/generated/test.js +++ b/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;