Skip to content
This repository was archived by the owner on May 18, 2025. It is now read-only.

Commit 91b71d7

Browse files
coderofsalvationcoderofsalvation
committed
update documentation
1 parent 5347982 commit 91b71d7

File tree

8 files changed

+120
-85
lines changed

8 files changed

+120
-85
lines changed

‎dist/xrfragment.js‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,7 @@ xrfragment_Parser.parse = function(key,value,resultMap) {
212212
Frag_h["prio"] = xrfragment_Type.isInt;
213213
Frag_h["pos"] = xrfragment_Type.isVector;
214214
Frag_h["q"] = xrfragment_Type.isString;
215+
var vec = "1,2,3";
215216
if(Object.prototype.hasOwnProperty.call(Frag_h,key)) {
216217
if(Frag_h[key].match(value)) {
217218
var v = new xrfragment_Value();
@@ -230,11 +231,11 @@ xrfragment_Parser.parse = function(key,value,resultMap) {
230231
}
231232
resultMap[key] = v;
232233
} else {
233-
console.log("src/xrfragment/Parser.hx:34:","[ i ] fragment '" + key + "' has incompatible value (" + value + ")");
234+
console.log("src/xrfragment/Parser.hx:47:","[ i ] fragment '" + key + "' has incompatible value (" + value + ")");
234235
return false;
235236
}
236237
} else {
237-
console.log("src/xrfragment/Parser.hx:35:","[ i ] fragment '" + key + "' does not exist or has no type defined (yet)");
238+
console.log("src/xrfragment/Parser.hx:48:","[ i ] fragment '" + key + "' does not exist or has no type defined (yet)");
238239
return false;
239240
}
240241
return true;

‎doc/RFC.md‎

Lines changed: 18 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,56 @@
1+
12
<link rel="stylesheet" href="style.css"/>
23
<link href="https://fonts.cdnfonts.com/css/montserrat" rel="stylesheet"/>
34
> version 1.0.0
4-
5-
date: 2023-03-31T19:59:16+0200 (generated by `./make doc`)
6-
5+
date: 2023-04-02T21:18:46+0200
76
[![Actions Status](https://github.com/coderofsalvation/xrfragment/workflows/test/badge.svg)](https://github.com/coderofsalvation/xrfragment/actions)
87

9-
10-
118
# `://foo.com/my3d.asset#pos=1,0,0&prio=-5`
129

1310
# URI parser
14-
1511
> icanhazcode? yes, see [URI.hx](https://github.com/coderofsalvation/xrfragment/blob/main/src/xrfragment/URI.hx)
1612
1713
1. fragment URI starts with `#`
1814
1. fragments are split by `&`
19-
1. `=` is used to split fragment key/values
15+
1. store key/values into a associative array or dynamic object
16+
1. loop thru each fragment
17+
1. for each fragment split on `=` to separate key/values
2018
1. fragment-values are urlencoded (space becomes `+` using `encodeUriComponent` e.g.)
2119
1. every recognized fragment key/value-pair is added to a central map/associative array/object
2220

2321
# XR Fragments (key/value params)
24-
22+
2523
> ⛁ = define in 3D asset-file (as custom property or default projection)<br>
2624
> ☇ = mutable, using navigator URI (`document.location.href` e.g.)<br>
2725
2826
| param | type | scope(s) | category | notes |
2927
|---------|---------------|-------|--------------------|---------------------------------|
30-
| prio | int (-10..1) | ⛁ | Asset loading / linking | \#static allow client to ignore lower-prio objects in the renderloop, to compensate frame-drop/cpu/gpu-overload scenario’soc/notes/prio.md |
28+
| prio | int (-10..1) | ⛁ | Asset loading / linking | \#static allow client to ignore lower-prio objects in the renderloop, to compensate frame-drop/cpu/gpu-overload scenario’s |
3129
| pos | 3D vector | ⛁ ☇ |HREF navigation/portals | |
3230
| q | string | ⛁ |Query Selector | |
3331

3432

3533
# XR Fragments parser
34+
3635
note: community parsers will prolly outperform this initial parser :)
3736
> icanhazcode? yes, see [Parser.hx](https://github.com/coderofsalvation/xrfragment/blob/main/src/xrfragment/Parser.hx)
38-
3937
the gist of it:
38+
39+
1. check if param exist
4040
1. each key has a regex to validate its value-type (see regexes)
41-
1. `|` is used to split multiple/fallback values
41+
1. extract the type
42+
1. use `|` on stringvalues, to split multiple/fallback values
43+
1. for each multiple/fallback value, guess the type
4244
1. `,` assumes 1D/2D/3D vector-values like x[,y[,z]]
4345
1. parseFloat(..) and parseInt(..) is applied to vector/float and int values
4446
1. anything else will be treated as string-value
4547
1. incompatible value-types will be dropped / not used
4648

49+
4750
> the xrfragment specification should stay simple enough
51+
4852
> for anyone to write a parser using either regexes or grammar/lexers
53+
4954
> therefore expressions/comprehensions are not supported (max wildcard/comparison operators for queries e.g.)
5055
5156
# Parser Value types
@@ -59,14 +64,13 @@ the gist of it:
5964
|float | | [-]x[.xxxx] (ieee)| #prio=-20 |
6065
|array | mixed| \|-separated | #pos=0,0,0\|90,0,0 |
6166

67+
6268
> rule for thumb: type-limitations will piggyback JSON limitations (IEEE floatsize e.g.)
69+
Regexes:
6370

6471
1. hex colors are detected using regex `/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/`
6572
1. integers are detected using regex `/^[0-9]+$/`
6673
1. floats are detected using regex `/^[0-9]+\.[0-9]+$/`
6774
1. vectors are detected using regex `/[,]/` (but can also be an string referring to an entity-ID in the asset)
6875
1. anything else is string `/.*/`
6976

70-
# Tests
71-
72-
the spec is tested with [JSON unittests](./../src/spec) consumed by [Test.hx](./../src/Test.hx) to cross-test all languages.

‎doc/generate.awk‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# a no-nonsense source-to-markdown generator which scans for:
2+
#
3+
# /**
4+
# * # foo
5+
# *
6+
# * this is markdown $(cat bar.md)
7+
# */
8+
#
9+
# var foo; // comment with 2 leading spaces is markdown too $(date)
10+
#
11+
/\$\(/ { cmd=$0;
12+
gsub(/^.*\$\(/,"",cmd);
13+
gsub(/\).*/,"",cmd);
14+
cmd | getline stdout; close(cmd);
15+
sub(/\$\(.*\)/,stdout);
16+
}
17+
/\/\*\*/ { doc=1; sub(/^.*\/\*/,""); }
18+
doc && /\*\// { doc=0;
19+
sub(/[[:space:]]*\*\/.*/,"");
20+
sub(/^[[:space:]]*\*[[:space:]]?/,"");
21+
print
22+
}
23+
doc && /^[[:space:]]*\*/ { sub(/^[[:space:]]*\*[[:space:]]?/,"");
24+
print
25+
}
26+
!doc && /\/\/ / { sub(".*// ","");
27+
sub("# ","\n# ");
28+
sub("> ","\n> ");
29+
print
30+
}

‎make‎

Lines changed: 2 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
#!/bin/sh
22
set -e
3-
VERSION=1.0.0
43

54
try(){ set +e; "$@" 2>/dev/null; set -e; }
65

@@ -32,33 +31,8 @@ tests(){
3231
}
3332

3433
doc(){
35-
{
36-
echo '<link rel="stylesheet" href="style.css"/>'
37-
echo '<link href="https://fonts.cdnfonts.com/css/montserrat" rel="stylesheet"/>'
38-
echo "> version $VERSION"
39-
echo "\ndate: $(date +"%Y-%m-%dT%H:%M:%S%z") (generated by \`./make doc\`)\n"
40-
echo "[![Actions Status](https://github.com/coderofsalvation/xrfragment/workflows/test/badge.svg)](https://github.com/coderofsalvation/xrfragment/actions)\n"
41-
{
42-
cat src/xrfragment/URI.hx
43-
cat src/xrfragment/Parser.hx
44-
} | awk '
45-
46-
/\/\/ / {
47-
gsub(".*// ","",$0);
48-
gsub("# ","\n# ",$0);
49-
if( match($0,/^#code /) ){ print "```\n"; system("cat "$2); print "```\n"; next; }
50-
if( match($0,/^#sh /) ){ $1=""; system($0); next; }
51-
if( match($0,/#include /) ) {
52-
o=$0; gsub(/.*#include/,"#include",$0); f=$2; $0=o;
53-
cmd="cat "f
54-
cmd | getline text; close(cmd)
55-
gsub(/#include \w/, text)
56-
}
57-
print $0;
58-
}
59-
60-
'
61-
} > doc/RFC.md
34+
awk -f doc/generate.awk src/xrfragment/URI.hx \
35+
src/xrfragment/Parser.hx > doc/RFC.md
6236
}
6337

6438
test -z $1 && { try rm dist/* ; haxe build.hxml; sed -i 's|.*nonlocal .*||g' dist/xrfragment.py; exit $?; }

‎src/xrfragment/Parser.hx‎

Lines changed: 42 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,45 @@
11
package xrfragment;
22

3+
/**
4+
* # XR Fragments (key/value params)
5+
*
6+
* > ⛁ = define in 3D asset-file (as custom property or default projection)<br>
7+
* > ☇ = mutable, using navigator URI (`document.location.href` e.g.)<br>
8+
*/
9+
310
@:expose // <- makes the class reachable from plain JavaScript
411
@:keep // <- avoids accidental removal by dead code elimination
5-
class Parser { // # XR Fragments (key/value params)
6-
public static var error:String = ""; //
7-
// > ⛁ = define in 3D asset-file (as custom property or default projection)<br>
8-
// > ☇ = mutable, using navigator URI (`document.location.href` e.g.)<br>
9-
@:keep //
12+
class Parser {
13+
public static var error:String = "";
14+
15+
@:keep
1016
public static function parse(key:String,value:String,resultMap:haxe.DynamicAccess<Dynamic>):Bool {
1117
var Frag:Map<String, EReg> = new Map<String, EReg>(); // | param | type | scope(s) | category | notes |
1218
// |---------|---------------|-------|--------------------|---------------------------------|
13-
Frag.set("prio", Type.isInt); // | prio | int (-10..1) | ⛁ | Asset loading / linking | #include doc/notes/prio.md |
19+
Frag.set("prio", Type.isInt); // | prio | int (-10..1) | ⛁ | Asset loading / linking | $(cat doc/notes/prio.md) |
1420

1521
Frag.set("pos", Type.isVector); // | pos | 3D vector | ⛁ ☇ |HREF navigation/portals | |
1622
Frag.set("q", Type.isString); // | q | string | ⛁ |Query Selector | |
17-
//
18-
// # XR Fragments parser
19-
if( Frag.exists(key) ){ // note: community parsers will prolly outperform this initial parser :)
20-
if( Frag.get(key).match(value) ){ // > icanhazcode? yes, see [Parser.hx](https://github.com/coderofsalvation/xrfragment/blob/main/src/xrfragment/Parser.hx)
21-
var v:Value = new Value(); //
22-
guessType(v, value); // the gist of it:
23-
// process multiple/fallback values // 1. each key has a regex to validate its value-type (see regexes)
24-
if( value.split("|").length > 1 ){ // 1. `|` is used to split multiple/fallback values
23+
var vec:String = "1,2,3"; //
24+
//if( Type.isVector(vec) ) trace("ja");
25+
/**
26+
* # XR Fragments parser
27+
*
28+
* note: community parsers will prolly outperform this initial parser :)
29+
* > icanhazcode? yes, see [Parser.hx](https://github.com/coderofsalvation/xrfragment/blob/main/src/xrfragment/Parser.hx)
30+
* the gist of it:
31+
*/
32+
if( Frag.exists(key) ){ // 1. check if param exist
33+
if( Frag.get(key).match(value) ){ // 1. each key has a regex to validate its value-type (see regexes)
34+
var v:Value = new Value();
35+
guessType(v, value); // 1. extract the type
36+
// process multiple/fallback values
37+
if( value.split("|").length > 1 ){ // 1. use `|` on stringvalues, to split multiple/fallback values
2538
v.args = new Array<Value>();
2639
var args:Array<String> = value.split("|");
2740
for( i in 0...args.length){
2841
var x:Value = new Value();
29-
guessType(x, args[i]);
42+
guessType(x, args[i]); // 1. for each multiple/fallback value, guess the type
3043
v.args.push( x );
3144
}
3245
}
@@ -40,14 +53,14 @@ class Parser { // #
4053
@:keep
4154
public static function guessType(v:Value, str:String):Void {
4255
v.string = str;
43-
if( str.split(",").length > 1){ // 1. `,` assumes 1D/2D/3D vector-values like x[,y[,z]]
44-
var xyz:Array<String> = str.split(","); // 1. parseFloat(..) and parseInt(..) is applied to vector/float and int values
45-
if( xyz.length > 0 ) v.x = Std.parseFloat(xyz[0]); // 1. anything else will be treated as string-value
46-
if( xyz.length > 1 ) v.y = Std.parseFloat(xyz[1]); // 1. incompatible value-types will be dropped / not used
47-
if( xyz.length > 2 ) v.y = Std.parseFloat(xyz[2]); //
48-
} // > the xrfragment specification should stay simple enough
49-
// > for anyone to write a parser using either regexes or grammar/lexers
50-
if( Type.isColor.match(str) ) v.color = str; // > therefore expressions/comprehensions are not supported (max wildcard/comparison operators for queries e.g.)
56+
if( str.split(",").length > 1){ /// 1. `,` assumes 1D/2D/3D vector-values like x[,y[,z]]
57+
var xyz:Array<String> = str.split(","); /// 1. parseFloat(..) and parseInt(..) is applied to vector/float and int values
58+
if( xyz.length > 0 ) v.x = Std.parseFloat(xyz[0]); /// 1. anything else will be treated as string-value
59+
if( xyz.length > 1 ) v.y = Std.parseFloat(xyz[1]); /// 1. incompatible value-types will be dropped / not used
60+
if( xyz.length > 2 ) v.y = Std.parseFloat(xyz[2]); ///
61+
} /// > the xrfragment specification should stay simple enough
62+
/// > for anyone to write a parser using either regexes or grammar/lexers
63+
if( Type.isColor.match(str) ) v.color = str; /// > therefore expressions/comprehensions are not supported (max wildcard/comparison operators for queries e.g.)
5164
if( Type.isFloat.match(str) ) v.float = Std.parseFloat(str);
5265
if( Type.isInt.match(str) ) v.int = Std.parseInt(str);
5366
}
@@ -58,8 +71,8 @@ class Parser { // #
5871
// | type | info | format | example |
5972
class Value { // |------|------|--------|----------------------------------|
6073
public var x:Float; // |vector| x,y,z| comma-separated | #pos=1,2,3 |
61-
public var y:Float; //
62-
public var z:Float; //
74+
public var y:Float;
75+
public var z:Float;
6376
public var color:String; // |string| color| FFFFFF (hex) | #fog=5m,FFAACC |
6477
public var string:String; // |string| | | #q=-sun |
6578
public var int:Int; // |int | | [-]x[xxxxx] | #price:>=100 |
@@ -68,7 +81,7 @@ class Value { // |
6881
public function new(){} //
6982
// > rule for thumb: type-limitations will piggyback JSON limitations (IEEE floatsize e.g.)
7083
}
71-
// Regexes:
84+
// Regexes:
7285
class Type { //
7386
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})$/`
7487
static public var isInt:EReg = ~/^[0-9]+$/; // 1. integers are detected using regex `/^[0-9]+$/`
@@ -77,6 +90,6 @@ class Type { //
7790
static public var isString:EReg = ~/.*/; // 1. anything else is string `/.*/`
7891
}
7992

80-
// # Tests
81-
//
82-
// the spec is tested with [JSON unittests](./../src/spec) consumed by [Test.hx](./../src/Test.hx) to cross-test all languages.
93+
/// # Tests
94+
///
95+
/// the spec is tested with [JSON unittests](./../src/spec) consumed by [Test.hx](./../src/Test.hx) to cross-test all languages.

‎src/xrfragment/URI.hx‎

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,30 @@ package xrfragment;
22

33
import xrfragment.Parser;
44

5+
/**
6+
* <link rel="stylesheet" href="style.css"/>
7+
* <link href="https://fonts.cdnfonts.com/css/montserrat" rel="stylesheet"/>
8+
* > version 1.0.0
9+
* date: $(date +"%Y-%m-%dT%H:%M:%S%z") (generated by \`./make doc\`)
10+
* [![Actions Status](https://github.com/coderofsalvation/xrfragment/workflows/test/badge.svg)](https://github.com/coderofsalvation/xrfragment/actions)
11+
*
12+
* # `://foo.com/my3d.asset#pos=1,0,0&prio=-5`
13+
*
14+
* # URI parser
15+
* > icanhazcode? yes, see [URI.hx](https://github.com/coderofsalvation/xrfragment/blob/main/src/xrfragment/URI.hx)
16+
*/
17+
518
@:expose // <- makes the class reachable from plain JavaScript
619
@:keep // <- avoids accidental removal by dead code elimination
7-
//
8-
// # `://foo.com/my3d.asset#pos=1,0,0&prio=-5`
920
class URI {
10-
@:keep // # URI parser
11-
public static function parse(qs:String):haxe.DynamicAccess<Dynamic> { //
12-
var fragment:Array<String> = qs.split("#"); // > icanhazcode? yes, see [URI.hx](https://github.com/coderofsalvation/xrfragment/blob/main/src/xrfragment/URI.hx)
13-
var splitArray:Array<String> = fragment[1].split('&'); //
14-
var resultMap:haxe.DynamicAccess<Dynamic> = {}; // 1. fragment URI starts with `#`
15-
for (i in 0...splitArray.length) { // 1. fragments are split by `&`
21+
@:keep
22+
public static function parse(qs:String):haxe.DynamicAccess<Dynamic> {
23+
var fragment:Array<String> = qs.split("#"); // 1. fragment URI starts with `#`
24+
var splitArray:Array<String> = fragment[1].split('&'); // 1. fragments are split by `&`
25+
var resultMap:haxe.DynamicAccess<Dynamic> = {}; // 1. store key/values into a associative array or dynamic object
26+
for (i in 0...splitArray.length) { // 1. loop thru each fragment
1627

17-
var splitByEqual = splitArray[i].split('='); // 1. `=` is used to split fragment key/values
28+
var splitByEqual = splitArray[i].split('='); // 1. for each fragment split on `=` to separate key/values
1829
var regexPlus = ~/\+/g; // 1. fragment-values are urlencoded (space becomes `+` using `encodeUriComponent` e.g.)
1930
var key:String = splitByEqual[0];
2031

0 commit comments

Comments
 (0)