From 8f1a22d1737fb7b76ac894108c7b3345589051ef Mon Sep 17 00:00:00 2001 From: Leon van Kammen Date: Fri, 31 Mar 2023 16:35:54 +0200 Subject: [PATCH] update documentation --- doc/RFC.md | 5 +---- make | 37 ++++++++++++++++++----------------- src/xrfragment/Parser.hx | 42 ++++++++++++++++++++-------------------- 3 files changed, 41 insertions(+), 43 deletions(-) diff --git a/doc/RFC.md b/doc/RFC.md index aa5ce32..446e487 100644 --- a/doc/RFC.md +++ b/doc/RFC.md @@ -1,6 +1,3 @@ -> version 1.0.0 - -date: 2023-03-31T15:57:18+0200 (generated by `./make doc`) ## # example URI: `://domain.com/some3d.asset#pos=1,0,0&prio=-5` @@ -24,7 +21,7 @@ date: 2023-03-31T15:57:18+0200 (generated by `./make doc`) # XR Fragments parser - +note: community parsers will prolly outperform this initial parser :) > icanhazcode? yes, see [Parser.hx](./../src/xrfragment/Parser.hx) the gist of it: diff --git a/make b/make index ea7ce9b..ddcb8d3 100755 --- a/make +++ b/make @@ -32,27 +32,28 @@ tests(){ } doc(){ - generate(){ - cat $1 | awk '/\/\/ / { - gsub(".*// ","",$0); - gsub("# ","\n# ",$0); - if( match($0,/^#code /) ){ print "```\n"; system("cat "$2); print "```\n"; next; } - if( match($0,/^#sh /) ){ $1=""; system($0); next; } - if( match($0,/#include /) ) { - o=$0; gsub(/.*#include/,"#include",$0); f=$2; $0=o; - cmd="cat "f - cmd | getline text; close(cmd) - gsub(/#include \w/, text) - } - print $0; - }' - } { echo "> version $VERSION" echo "\ndate: $(date +"%Y-%m-%dT%H:%M:%S%z") (generated by \`./make doc\`)" - generate src/xrfragment/URI.hx - generate src/xrfragment/Parser.hx - } > doc/RFC.md + cat src/xrfragment/URI.hx + cat src/xrfragment/Parser.hx + } | awk ' + + /\/\/ / { + gsub(".*// ","",$0); + gsub("# ","\n# ",$0); + if( match($0,/^#code /) ){ print "```\n"; system("cat "$2); print "```\n"; next; } + if( match($0,/^#sh /) ){ $1=""; system($0); next; } + if( match($0,/#include /) ) { + o=$0; gsub(/.*#include/,"#include",$0); f=$2; $0=o; + cmd="cat "f + cmd | getline text; close(cmd) + gsub(/#include \w/, text) + } + print $0; + } + + ' > doc/RFC.md } test -z $1 && { try rm dist/* ; haxe build.hxml; exit $?; } diff --git a/src/xrfragment/Parser.hx b/src/xrfragment/Parser.hx index f8f42aa..07fe858 100644 --- a/src/xrfragment/Parser.hx +++ b/src/xrfragment/Parser.hx @@ -4,18 +4,18 @@ package xrfragment; @:keep // <- avoids accidental removal by dead code elimination 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):Bool { - var Frag:Map = new Map(); // | param | type | category | notes | + var Frag:Map = new Map(); // | param | type | category | notes | // |---------|---------------|-------------------------|-------------------------| - Frag.set("prio", Type.isInt); // | prio | int (-10..1) | Asset loading / linking | #include doc/notes/prio.md | + Frag.set("prio", Type.isInt); // | prio | int (-10..1) | Asset loading / linking | #include doc/notes/prio.md | - Frag.set("pos", Type.isVector); // | pos | 3D vector | HREF navigation/portals | | - // + Frag.set("pos", Type.isVector); // | pos | 3D vector | HREF navigation/portals | | + // // # XR Fragments parser - if( Frag.exists(key) ){ // + if( Frag.exists(key) ){ // note: community parsers will prolly outperform this initial parser :) 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: @@ -44,7 +44,7 @@ class Parser { // # if( xyz.length > 0 ) v.x = Std.parseFloat(xyz[0]); // 1. anything else will be treated as string-value if( xyz.length > 1 ) v.y = Std.parseFloat(xyz[1]); // 1. incompatible value-types will be dropped / not used if( xyz.length > 2 ) v.y = Std.parseFloat(xyz[2]); // - } // > the xrfragment specification should stay simple enough + } // > the xrfragment specification should stay simple enough // > for anyone to write a parser using either regexes or grammar/lexers if( Type.isColor.match(str) ) v.color = str; // > therefore expressions/comprehensions are not supported (max wildcard/comparison operators for queries e.g.) if( Type.isFloat.match(str) ) v.float = Std.parseFloat(str); @@ -52,22 +52,22 @@ class Parser { // # } } - // # Parser Value types - // - // | type | info | format | example | + // # Parser Value types + // + // | type | info | format | example | class Value { // |------|------|--------|----------------------------------| - public var x:Float; // |vector| x,y,z| comma-separated | #pos=1,2,3 | - public var y:Float; // - public var z:Float; // - public var color:String; // |string| color| FFFFFF (hex) | #fog=5m,FFAACC | - public var string:String; // |string| | | #q=-sun | - public var int:Int; // |int | | [-]x[xxxxx] | #price:>=100 | - public var float:Float; // |float | | [-]x[.xxxx] (ieee)| #prio=-20 - public var args:Array; // |array | mixed| \|-separated | #pos=0,0,0|90,0,0 | - public function new(){} // - // > rule for thumb: type-limitations will piggyback JSON limitations (IEEE floatsize e.g.) + public var x:Float; // |vector| x,y,z| comma-separated | #pos=1,2,3 | + public var y:Float; // + public var z:Float; // + public var color:String; // |string| color| FFFFFF (hex) | #fog=5m,FFAACC | + public var string:String; // |string| | | #q=-sun | + public var int:Int; // |int | | [-]x[xxxxx] | #price:>=100 | + public var float:Float; // |float | | [-]x[.xxxx] (ieee)| #prio=-20 + public var args:Array; // |array | mixed| \|-separated | #pos=0,0,0|90,0,0 | + public function new(){} // + // > rule for thumb: type-limitations will piggyback JSON limitations (IEEE floatsize e.g.) } - // Regexes: + // Regexes: class Type { // static public 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})$/` static public var isInt:EReg = ~/^[0-9]+$/; // 1. integers are detected using regex `/^[0-9]+$/`