summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Siefkes <christian@siefkes.net>2010-02-04 14:22:44 -0500
committerChristian Siefkes <christian@siefkes.net>2010-02-04 14:22:44 -0500
commite5daa58c7d8f31bf577f013a0fb78769ad89362e (patch)
tree0e879f7384a147b25165569c9f4ad7cea5491c5b
parent914f62dc7d5520c4bb7f94c7cb4a6e4150138cdd (diff)
downloadtangiblebit-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.html95
-rw-r--r--doc/formats.rst44
-rw-r--r--doc/objects.html10
-rw-r--r--doc/objects.rst10
-rw-r--r--doc/querylanguage.ebnf43
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 = &quot;0&quot; ... &quot;7&quot; .
hex_digit = &quot;0&quot; ... &quot;9&quot; | &quot;A&quot; ... &quot;F&quot; | &quot;a&quot; ... &quot;f&quot; .
int_lit = decimal_lit | octal_lit | hex_lit .
-decimal_lit = ( &quot;1&quot; ... &quot;9&quot; ) { decimal_digit } .
-octal_lit = &quot;0&quot; { octal_digit } .
+decimal_lit = ( &quot;1&quot; ... &quot;9&quot; ) { decimal_digit } | &quot;0&quot; { &quot;0&quot; } .
+octal_lit = &quot;0&quot; octal_digit { octal_digit } .
hex_lit = &quot;0&quot; ( &quot;x&quot; | &quot;X&quot; ) hex_digit { hex_digit } .
float_lit = decimals &quot;.&quot; [ decimals ] [ exponent ] |
decimals exponent |
- &quot;.&quot; decimals [ exponent ] .
+ &quot;.&quot; decimals [ exponent ] |
+ [ &quot;+&quot; | &quot;-&quot; ] &quot;NaN&quot; | [ &quot;+&quot; | &quot;-&quot; ] &quot;Inf&quot; .
decimals = decimal_digit { decimal_digit } .
exponent = ( &quot;e&quot; | &quot;E&quot; ) [ &quot;+&quot; | &quot;-&quot; ] 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 (&quot;[...]&quot;) and contain zero or
-more <em>inline list items</em>.</li>
+<li><em>Inline lists</em> are enclosed in curly brackets (&quot;{...}&quot;) 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 '&amp;' statement
+ | statement '|' statement
+ | '!' statement .
+
+logicalstatement = logicalstatement ('&lt;'|'&gt;'|'&lt;='|'=&gt;'|'=='|'!='|'~')
+ logicalstatement .
+ | value .
+ | variable .
+
+value = floatnumber | decimalnumber | hexnumber |
+ octalnumber | string .
+
+variable = identifier .
+
+tablename = identifier .
+
+identifier = UnicodeLetter { UnicodeLetter | UnicodeDigit } .
+
+floatnumber = decimals &quot;.&quot; [ decimals ] [ exponent ] |
+ decimals exponent |
+ &quot;.&quot; decimals [ exponent ] |
+ [ &quot;+&quot; | &quot;-&quot; ] &quot;nan&quot; | [ &quot;+&quot; | &quot;-&quot; ] &quot;inf&quot; .
+decimals = decimal_digit { decimal_digit } .
+exponent = ( &quot;e&quot; | &quot;E&quot; ) [ &quot;+&quot; | &quot;-&quot; ] decimals .
+
+decimalnumber = ( &quot;1&quot; ... &quot;9&quot; ) { decimal_digit } | &quot;0&quot; { &quot;0&quot; } .
+hexnumber = 0&quot; ( &quot;x&quot; | &quot;X&quot; ) hex_digit { hex_digit }.
+octalnumber = &quot;0&quot; octal_digit { octal_digit } .
+decimal_digit = &quot;0&quot; ... &quot;9&quot; .
+hex_digit = &quot;0&quot; ... &quot;9&quot; | &quot;A&quot; ... &quot;F&quot; | &quot;a&quot; ... &quot;f&quot; .
+octal_digit = &quot;0&quot; ... &quot;7&quot; .
+
+string = '&quot;' { normalchar | escapedchar } '&quot;'.
+normalchar = Char - '&quot;' - &quot;\&quot; .
+escapedchar = &quot;\&quot; Char .
+
+# Char, UnicodeLetter and UnicodeDigit are assumed to be predefined.
+# Example: materials ? (30 &lt;= shearmodulus &lt;= 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&quot; 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)