diff options
author | Christian Siefkes <christian@siefkes.net> | 2010-02-04 14:22:44 -0500 |
---|---|---|
committer | Christian Siefkes <christian@siefkes.net> | 2010-02-04 14:22:44 -0500 |
commit | e5daa58c7d8f31bf577f013a0fb78769ad89362e (patch) | |
tree | 0e879f7384a147b25165569c9f4ad7cea5491c5b | |
parent | 914f62dc7d5520c4bb7f94c7cb4a6e4150138cdd (diff) | |
download | tangiblebit-e5daa58c7d8f31bf577f013a0fb78769ad89362e.tar.gz tangiblebit-e5daa58c7d8f31bf577f013a0fb78769ad89362e.zip |
Query language: completed EBNF (switching to Go syntax); TDF: using {...} for inline lists to prevent confusion with [ini-style keys]; using , as inline list item separator as is usual
-rw-r--r-- | doc/formats.html | 95 | ||||
-rw-r--r-- | doc/formats.rst | 44 | ||||
-rw-r--r-- | doc/objects.html | 10 | ||||
-rw-r--r-- | doc/objects.rst | 10 | ||||
-rw-r--r-- | doc/querylanguage.ebnf | 43 |
5 files changed, 137 insertions, 65 deletions
diff --git a/doc/formats.html b/doc/formats.html index 8ce8ff6..d2e9faa 100644 --- a/doc/formats.html +++ b/doc/formats.html @@ -288,7 +288,7 @@ ul.auto-toc { <h1 class="title">Formats and Languages</h1> <p>The formats and languages used by Tangible Bit are explained in English and -formally defined in EBNF.</p> +(in some cases) formally defined in EBNF.</p> <div class="section" id="ebnf-grammar"> <h2>EBNF Grammar</h2> <p>We use the EBNF notation as used in the <a class="reference external" href="http://golang.org/doc/go_spec.html#Notation">Go Language Specification</a>, which is almost identical @@ -376,13 +376,14 @@ octal_digit = "0" ... "7" . hex_digit = "0" ... "9" | "A" ... "F" | "a" ... "f" . int_lit = decimal_lit | octal_lit | hex_lit . -decimal_lit = ( "1" ... "9" ) { decimal_digit } . -octal_lit = "0" { octal_digit } . +decimal_lit = ( "1" ... "9" ) { decimal_digit } | "0" { "0" } . +octal_lit = "0" octal_digit { octal_digit } . hex_lit = "0" ( "x" | "X" ) hex_digit { hex_digit } . float_lit = decimals "." [ decimals ] [ exponent ] | decimals exponent | - "." decimals [ exponent ] . + "." decimals [ exponent ] | + [ "+" | "-" ] "NaN" | [ "+" | "-" ] "Inf" . decimals = decimal_digit { decimal_digit } . exponent = ( "e" | "E" ) [ "+" | "-" ] decimals . @@ -431,12 +432,12 @@ by the same amount of <em>inline whitespace</em>).</li> and an <em>atom</em>.</li> <li><em>Complex items</em> are introduced by a plus sign (+), followed by <em>whitespace</em> and a <em>compound</em>.</li> -<li><em>Inline lists</em> are enclosed in brackets ("[...]") and contain zero or -more <em>inline list items</em>.</li> +<li><em>Inline lists</em> are enclosed in curly brackets ("{...}") and contain zero +or more <em>inline list items</em>.</li> <li><em>Inline list items</em> are <em>atoms</em> or <em>inline lists</em> (<em>inline lists</em> can contain nested <em>inline lists</em>, but they cannot contain <em>block lists</em> or <em>maps</em>).</li> -<li>Successive <em>inline list items</em> are separated by a semicolon (;).</li> +<li>Successive <em>inline list items</em> are separated by a comma (,).</li> <li><em>Maps</em> contain zero or more <em>pairs</em>. All <em>pairs</em> in a <em>map</em> must start at the same <em>indentation level</em> (they must be preceded by the same amount of <em>inline whitespace</em>).</li> @@ -462,20 +463,21 @@ above--octal and hexadecimal notations are not supported); <em>floats</em> are written as in Polyps (cf. the <tt class="docutils literal"><span class="pre">float_lit</span></tt> rule above).</li> <li><em>Strings</em> are sequences of zero or more Unicode characters. If a <em>strings</em> looks like an <em>atom</em> of another kinds (a <em>number</em> or <em>literal</em>) -or if it starts with an opening bracket ([) or with <em>whitespace</em>, its -first character must be <em>backslash-escaped</em>. If a <em>string</em> ends with -<em>whitespace</em>, its last character must be <em>backslash-escaped</em>--if a string -ends in a single backslash, followed by a <em>linebreak</em> or the end of the -document, that counts as a <em>backslash-escaped</em> <em>linebreak</em> at the end of -the string (it's not necessary to explicitly add an extra <em>linebreak</em>). -Plus or minus signs (+-) at the start of a string must be -<em>backslash-escaped</em> if followed by <em>whitespace</em> (to prevent confusion -with <em>lists</em>). The hash sign (#) must be escaped at the start of the -string or if preceded by <em>whitespace</em> (to prevent confusion with -<em>comments</em>). Colons (:) must be <em>backslash-escaped</em> within <em>keys</em>; -semicolons (;) must be <em>backslash-escaped</em> within <em>inline list items</em>. -Backslashes (\) must be <em>backslash-escaped</em> within all <em>strings</em>. -<em>Backslash-escaping</em> other characters is allowed, but not required.</li> +or if it starts with an opening bracket ([) or curly bracket ({) or with +<em>whitespace</em>, its first character must be <em>backslash-escaped</em>. If a +<em>string</em> ends with <em>whitespace</em>, its last character must be +<em>backslash-escaped</em>--if a string ends in a single backslash, followed by +a <em>linebreak</em> or the end of the document, that counts as a +<em>backslash-escaped</em> <em>linebreak</em> at the end of the string (it's not +necessary to explicitly add an extra <em>linebreak</em>). Plus or minus signs +(+-) at the start of a string must be <em>backslash-escaped</em> if followed by +<em>whitespace</em> (to prevent confusion with <em>lists</em>). The hash sign (#) must +be escaped at the start of the string or if preceded by <em>whitespace</em> (to +prevent confusion with <em>comments</em>). Colons (:) must be +<em>backslash-escaped</em> within <em>keys</em>; commas (,) must be <em>backslash-escaped</em> +within <em>inline list items</em>. Backslashes (\) must be <em>backslash-escaped</em> +within all <em>strings</em>. <em>Backslash-escaping</em> other characters is allowed, +but not required.</li> <li>Characters are <em>backslash-escaped</em> by writing a backslash (\) in front of the character.</li> <li><em>Complex maps</em> are <em>maps</em> that contain only <em>complex pairs</em> (i.e. <em>keys</em> @@ -528,9 +530,56 @@ start a <em>comment</em> immediately after a <em>value</em> without intervening <div class="section" id="tangible-bit-query-language-tql"> <h2>Tangible Bit Query Language (TQL)</h2> <p>Used to query for objects, locations and other items contained in the TBit -database. TODO describe</p> +database. Here's the EBNF:</p> +<pre class="literal-block"> +query = tablename '?' statement . + +statement = '(' + statement + ')' + | booleanstatement + | logicalstatement . + +booleanstatement = statement '&' statement + | statement '|' statement + | '!' statement . + +logicalstatement = logicalstatement ('<'|'>'|'<='|'=>'|'=='|'!='|'~') + logicalstatement . + | value . + | variable . + +value = floatnumber | decimalnumber | hexnumber | + octalnumber | string . + +variable = identifier . + +tablename = identifier . + +identifier = UnicodeLetter { UnicodeLetter | UnicodeDigit } . + +floatnumber = decimals "." [ decimals ] [ exponent ] | + decimals exponent | + "." decimals [ exponent ] | + [ "+" | "-" ] "nan" | [ "+" | "-" ] "inf" . +decimals = decimal_digit { decimal_digit } . +exponent = ( "e" | "E" ) [ "+" | "-" ] decimals . + +decimalnumber = ( "1" ... "9" ) { decimal_digit } | "0" { "0" } . +hexnumber = 0" ( "x" | "X" ) hex_digit { hex_digit }. +octalnumber = "0" octal_digit { octal_digit } . +decimal_digit = "0" ... "9" . +hex_digit = "0" ... "9" | "A" ... "F" | "a" ... "f" . +octal_digit = "0" ... "7" . + +string = '"' { normalchar | escapedchar } '"'. +normalchar = Char - '"' - "\" . +escapedchar = "\" Char . + +# Char, UnicodeLetter and UnicodeDigit are assumed to be predefined. +# Example: materials ? (30 <= shearmodulus <= 50) + +</pre> <ul class="simple"> -<li>Calculations: evaluate to an atom using standard operators arithmetic +<li>TODO Calculations: evaluate to an atom using standard operators arithmetic operators (+, -, *, /, %). Can contain Atoms. Grouping is used where necessary to resolve ambiguities.</li> <li>Conditions: evaluate to a Boolean using standard Boolean syntax: logical diff --git a/doc/formats.rst b/doc/formats.rst index 76799e0..7f8274a 100644 --- a/doc/formats.rst +++ b/doc/formats.rst @@ -3,7 +3,7 @@ Formats and Languages ===================== The formats and languages used by Tangible Bit are explained in English and -formally defined in EBNF. +(in some cases) formally defined in EBNF. EBNF Grammar ~~~~~~~~~~~~ @@ -72,12 +72,12 @@ Windows-INI-style "[section]" blocks (as syntactic sugar). and an *atom*. * *Complex items* are introduced by a plus sign (+), followed by *whitespace* and a *compound*. -* *Inline lists* are enclosed in brackets ("[...]") and contain zero or - more *inline list items*. +* *Inline lists* are enclosed in curly brackets ("{...}") and contain zero + or more *inline list items*. * *Inline list items* are *atoms* or *inline lists* (*inline lists* can contain nested *inline lists*, but they cannot contain *block lists* or *maps*). -* Successive *inline list items* are separated by a semicolon (;). +* Successive *inline list items* are separated by a comma (,). * *Maps* contain zero or more *pairs*. All *pairs* in a *map* must start at the same *indentation level* (they must be preceded by the same amount of *inline whitespace*). @@ -103,20 +103,21 @@ Windows-INI-style "[section]" blocks (as syntactic sugar). written as in Polyps (cf. the ``float_lit`` rule above). * *Strings* are sequences of zero or more Unicode characters. If a *strings* looks like an *atom* of another kinds (a *number* or *literal*) - or if it starts with an opening bracket ([) or with *whitespace*, its - first character must be *backslash-escaped*. If a *string* ends with - *whitespace*, its last character must be *backslash-escaped*--if a string - ends in a single backslash, followed by a *linebreak* or the end of the - document, that counts as a *backslash-escaped* *linebreak* at the end of - the string (it's not necessary to explicitly add an extra *linebreak*). - Plus or minus signs (+-) at the start of a string must be - *backslash-escaped* if followed by *whitespace* (to prevent confusion - with *lists*). The hash sign (#) must be escaped at the start of the - string or if preceded by *whitespace* (to prevent confusion with - *comments*). Colons (:) must be *backslash-escaped* within *keys*; - semicolons (;) must be *backslash-escaped* within *inline list items*. - Backslashes (\\) must be *backslash-escaped* within all *strings*. - *Backslash-escaping* other characters is allowed, but not required. + or if it starts with an opening bracket ([) or curly bracket ({) or with + *whitespace*, its first character must be *backslash-escaped*. If a + *string* ends with *whitespace*, its last character must be + *backslash-escaped*--if a string ends in a single backslash, followed by + a *linebreak* or the end of the document, that counts as a + *backslash-escaped* *linebreak* at the end of the string (it's not + necessary to explicitly add an extra *linebreak*). Plus or minus signs + (+-) at the start of a string must be *backslash-escaped* if followed by + *whitespace* (to prevent confusion with *lists*). The hash sign (#) must + be escaped at the start of the string or if preceded by *whitespace* (to + prevent confusion with *comments*). Colons (:) must be + *backslash-escaped* within *keys*; commas (,) must be *backslash-escaped* + within *inline list items*. Backslashes (\\) must be *backslash-escaped* + within all *strings*. *Backslash-escaping* other characters is allowed, + but not required. * Characters are *backslash-escaped* by writing a backslash (\\) in front of the character. * *Complex maps* are *maps* that contain only *complex pairs* (i.e. *keys* @@ -170,9 +171,12 @@ Tangible Bit Query Language (TQL) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Used to query for objects, locations and other items contained in the TBit -database. TODO describe +database. Here's the EBNF: -* Calculations: evaluate to an atom using standard operators arithmetic +.. include:: querylanguage.ebnf + :literal: + +* TODO Calculations: evaluate to an atom using standard operators arithmetic operators (+, -, \*, /, %). Can contain Atoms. Grouping is used where necessary to resolve ambiguities. * Conditions: evaluate to a Boolean using standard Boolean syntax: logical diff --git a/doc/objects.html b/doc/objects.html index efdca17..8840b0a 100644 --- a/doc/objects.html +++ b/doc/objects.html @@ -644,10 +644,10 @@ queries" in the database.</p> <p>The output describes the objects that will be created as a result of the process, if any. Output is specified in a simple declarative language:</p> <pre class="literal-block"> -object: +object:: category: WaterBoiler - achievableHeat: [60, 80, 90, 100] # a list - heatableVolume: [0..3] # a range + achievableHeat: {60, 80, 90, 100} # a list + heatableVolume: 0..3 # a range power: 700 weight: 2.8 width: 0.28 @@ -894,9 +894,9 @@ the exact values on demand.</p> <p>Example of declaring parameters:</p> <pre class="literal-block"> # leg length is between 35 cm and 80 cm -leg-length: [0.35..0.80]; +leg-length: 0.35..0.80; # six different colors are available -color: [red, green, blue, yellow, black, white]; +color: {red, green, blue, yellow, black, white}; </pre> <p>Example of selecting parameters--syntax is identical to the syntax used for defining inputs:</p> diff --git a/doc/objects.rst b/doc/objects.rst index 76c9ddb..b197797 100644 --- a/doc/objects.rst +++ b/doc/objects.rst @@ -176,10 +176,10 @@ Output The output describes the objects that will be created as a result of the process, if any. Output is specified in a simple declarative language:: - object: + object:: category: WaterBoiler - achievableHeat: [60, 80, 90, 100] # a list - heatableVolume: [0..3] # a range + achievableHeat: {60, 80, 90, 100} # a list + heatableVolume: 0..3 # a range power: 700 weight: 2.8 width: 0.28 @@ -451,9 +451,9 @@ the exact values on demand. Example of declaring parameters:: # leg length is between 35 cm and 80 cm - leg-length: [0.35..0.80]; + leg-length: 0.35..0.80; # six different colors are available - color: [red, green, blue, yellow, black, white]; + color: {red, green, blue, yellow, black, white}; Example of selecting parameters--syntax is identical to the syntax used for defining inputs:: diff --git a/doc/querylanguage.ebnf b/doc/querylanguage.ebnf index 1cc638d..51f71ae 100644 --- a/doc/querylanguage.ebnf +++ b/doc/querylanguage.ebnf @@ -1,25 +1,44 @@ -query ::= tablename '?' statement +query = tablename '?' statement . -statement ::= '(' + statement + ')' +statement = '(' + statement + ')' | booleanstatement - | logicalstatement + | logicalstatement . -booleanstatement ::= statement '&' statement +booleanstatement = statement '&' statement | statement '|' statement - | '!' statement + | '!' statement . -logicalstatement ::= logicalstatement ('<'|'>'|'<='|'=>'|'=='|'!='|'~') logicalstatement - | value - | variable +logicalstatement = logicalstatement ('<'|'>'|'<='|'=>'|'=='|'!='|'~') + logicalstatement . + | value . + | variable . -value ::= number | hexnumber | binarynumber | octalnumber | string +value = floatnumber | decimalnumber | hexnumber | + octalnumber | string . -variable ::= +variable = identifier . -tablename ::= +tablename = identifier . +identifier = UnicodeLetter { UnicodeLetter | UnicodeDigit } . +floatnumber = decimals "." [ decimals ] [ exponent ] | + decimals exponent | + "." decimals [ exponent ] | + [ "+" | "-" ] "nan" | [ "+" | "-" ] "inf" . +decimals = decimal_digit { decimal_digit } . +exponent = ( "e" | "E" ) [ "+" | "-" ] decimals . +decimalnumber = ( "1" ... "9" ) { decimal_digit } | "0" { "0" } . +hexnumber = 0" ( "x" | "X" ) hex_digit { hex_digit }. +octalnumber = "0" octal_digit { octal_digit } . +decimal_digit = "0" ... "9" . +hex_digit = "0" ... "9" | "A" ... "F" | "a" ... "f" . +octal_digit = "0" ... "7" . -materials ? (30 <= shearmodulus <= 50) +string = '"' { normalchar | escapedchar } '"'. +normalchar = Char - '"' - "\" . +escapedchar = "\" Char . +# Char, UnicodeLetter and UnicodeDigit are assumed to be predefined. +# Example: materials ? (30 <= shearmodulus <= 50) |