From f524513e37b70ae9cd68a6a3daba7b0b95b5fcc9 Mon Sep 17 00:00:00 2001
From: Leon van Kammen <leonvankammen@gmail.com>
Date: Thu, 30 Mar 2023 16:23:47 +0200
Subject: [PATCH] update documentation

---
 .vimrc                |  1 +
 doc/url.md            | 17 ++++++++++++++++-
 make                  |  2 +-
 src/xrfragment/Url.hx | 30 +++++++++++++++---------------
 4 files changed, 33 insertions(+), 17 deletions(-)

diff --git a/.vimrc b/.vimrc
index 4d97d1b..754ed65 100644
--- a/.vimrc
+++ b/.vimrc
@@ -1,2 +1,3 @@
+noremap <silent> <F9> :!./make doc<CR>
 noremap <silent> <F10> :!./make && echo OK && ./make tests<CR>
 noremap <silent> <F11> :!./make tests \| less<CR>
diff --git a/doc/url.md b/doc/url.md
index ff4ec65..4a4d767 100644
--- a/doc/url.md
+++ b/doc/url.md
@@ -1,3 +1,4 @@
+
 # URI Value types
 
 | type | info | format | example                          |
@@ -9,4 +10,18 @@
 |float |      | [-]x[.xxxx] (ieee)| #prio=-20
 |array | mixed| \|-separated      | #pos=0,0,0|90,0,0     |
 
-> in general type-limitations will piggyback JSON limitations (IEEE floatsize e.g.)
+> rule for thumb: type-limitations will piggyback JSON limitations (IEEE floatsize e.g.)
+
+# Url parser (the gist of it)
+
+1. fragment URI starts with `#`
+1. fragments are split by `&`
+1. fragment-values are urlencoded (` ` becomes `+` and so on)
+1. `=` is used to indicate fragmentvalues
+1. `|` is used to indicate multiple/fallback values
+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. `,` is used to detect vector 1D/2D/3D values like x[,y[,z]]
+1. anything else will be treated as string-value 
+1. last resort: inappropriate string values will be converted using parseInt/parseFloat
diff --git a/make b/make
index 6849295..645e5d0 100755
--- a/make
+++ b/make
@@ -31,7 +31,7 @@ tests(){
 }
 
 doc(){
-  extract(){ cat $1 | awk '/\/\/  / { gsub(".*//  ","",$0); print $0; }'; }
+    extract(){ cat $1 | awk '/\/\/  / { gsub(".*//  ","",$0); gsub("# ","\n# ",$0);print $0; }'; }
   extract src/xrfragment/Url.hx > doc/url.md
 }
 
diff --git a/src/xrfragment/Url.hx b/src/xrfragment/Url.hx
index f92f939..53f936b 100644
--- a/src/xrfragment/Url.hx
+++ b/src/xrfragment/Url.hx
@@ -16,19 +16,19 @@ class Value {                   //  |------|------|--------|--------------------
   public var float:Float;       //  |float |      | [-]x[.xxxx] (ieee)| #prio=-20
   public var args:Array<Value>; //  |array | mixed| \|-separated      | #pos=0,0,0|90,0,0     |
   public function new(){}       //  
-                                //  > in general type-limitations will piggyback JSON limitations (IEEE floatsize e.g.)
+                                //  > rule for thumb: type-limitations will piggyback JSON limitations (IEEE floatsize e.g.)
 }
 
 class Url {
 
-    @:keep
-    public static function parse(qs:String):haxe.DynamicAccess<Dynamic> {
-       var fragment:Array<String>    = qs.split("#");
-        var splitArray:Array<String>  = fragment[1].split('&');
-        var regexPlus  = ~/\+/g;  // Regex for replacing addition symbol with a space
+    @:keep                                                                 //  # Url parser (the gist of it)
+    public static function parse(qs:String):haxe.DynamicAccess<Dynamic> {  //  
+       var fragment:Array<String>    = qs.split("#");                      //  1. fragment URI starts with `#`
+        var splitArray:Array<String>  = fragment[1].split('&');            //  1. fragments are split by `&`
+        var regexPlus  = ~/\+/g;                                           //  1. fragment-values are urlencoded (` ` becomes `+` and so on)
         var resultMap:haxe.DynamicAccess<Dynamic> = {};
         for (i in 0...splitArray.length) {
-          var splitByEqual = splitArray[i].split('=');
+          var splitByEqual = splitArray[i].split('=');                     //  1. `=` is used to indicate fragmentvalues
           var key:String = splitByEqual[0];
           var v:Value = new Value();
 
@@ -36,8 +36,8 @@ class Url {
             var value:String = StringTools.urlDecode(regexPlus.split(splitByEqual[1]).join(" "));
             guessType(v, value);
 
-            // multiple/fallthrough values
-            if( value.split("|").length > 1 ){
+            // multiple/fallback values
+            if( value.split("|").length > 1 ){                             //  1. `|` is used to indicate multiple/fallback values
               v.args = new Array<Value>();
               var args:Array<String> = value.split("|");
               for( i in 0...args.length){
@@ -54,13 +54,13 @@ class Url {
 
     @:keep
     public static function guessType(v:Value, str:String):Void {
-      var isColor:EReg  = ~/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/;
-      var isInt:EReg    = ~/^[0-9]+$/;
-      var isFloat:EReg  = ~/^[0-9]+\.[0-9]+$/;
+      var isColor:EReg  = ~/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/;          //  1. hex colors are detected using regex `/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/`
+      var isInt:EReg    = ~/^[0-9]+$/;                                    //  1. integers are detected using regex `/^[0-9]+$/`
+      var isFloat:EReg  = ~/^[0-9]+\.[0-9]+$/;                            //  1. floats are detected using regex `/^[0-9]+\.[0-9]+$/`
       v.string = str;
-      if( str.split(",").length > 1){
-        var xyz:Array<String> = str.split(",");
-        if( xyz.length > 0 ) v.x = Std.parseFloat(xyz[0]);
+      if( str.split(",").length > 1){                                     //  1. `,` is used to detect vector 1D/2D/3D values like x[,y[,z]]
+        var xyz:Array<String> = str.split(",");                           //  1. anything else will be treated as string-value 
+        if( xyz.length > 0 ) v.x = Std.parseFloat(xyz[0]);                //  1. last resort: inappropriate string values will be converted using parseInt/parseFloat
         if( xyz.length > 1 ) v.y = Std.parseFloat(xyz[1]);
         if( xyz.length > 2 ) v.z = Std.parseFloat(xyz[2]);
       }