For my two cents worth, I prefer see language definitions stated in one
of the BNF variants.
In particular, a slight modification to the Extended Backus-Naur Form
(EBNF) is my preferred "syntax description".
In EBNF, the '<' '>' '[' ']' '{' '}' '|' ';' and '+'
Special Characters have special meaning in the syntax diagrams, and if
any of these are required in the actual definitions they must be
quoted. (In actual practice, any REQUIRED characters are quoted, and
the term <quote> is frequently used to represent a real quote.
1. Definitions are terminated by a semicolon.
2. Terms or options are enclosed in angle brackets.
E.G. <new>
3. Required characters are enclosed in a pair of single quotes.
4. Optional items enclosed in square brackets.
E.G. [<item-x>]
5. Alternative choices are separated by the '|' symbol.
E.G., <alternative-A> | <alternative-B>
6. Where you have a list of items, and one or more MUST be selected,
the items are enclosed in curly brackets.
E.G. { <option1> | <option2> | <option3> }
7. Items repeating 0 or more times are followed by an ellipse (...)
More accurately, the ellipse means "may be repeated 0 or more times"
E.G. <word> ::= <letter> ...
8. Items repeating 1 or more times are followed by a '+'
E.G. <digits> ::= <digit>+
9. Where items need to be grouped they are enclosed in simple parentheses
10. When text can be displayed in color, then I prefer using color
rather than quoting required text.
Overlay_function ::= 'OVERLAY(' <new> ',' <target> [',' [<n>] [',' [<length>]
[','<pad>]]] ')'
Overlay_function ::= *OVERLAY(* <new>,<target> [,[<n>] [,[<length>]
[,<pad>]]] *)*
By the way OVERLAY(<new>,<target>,,,) is not valid according to the above
diagram.
But OVERLAY(<new>,<target>,,,<pad>) is.
- - - - -
Using the above rules, I think the following is a correct definition for "quote" in Rexx.
As it turn out, defining the term <quote> and <quotedString> in many languages are frequently the hardest - especially when you allow them to be used the way we do. (Which I like!)
<Quote> ::= { <SingleQuoteChar> | <DoubleQuoteChar> };
<QuotedString> ::= { <SingleQuoteChar> [<text>] [<DoubleQuoteChar>] [<text>]
<SingleQuoteChar> |
<DoubleQuoteChar> [<text>] [<SingleQuoteChar>] [<text>]
<DoubleQuoteChar> |
<SingleQuoteChar> [<text>] [<SingleQuoteChar><SingleQuoteChar>]
[<text>] <SingleQuoteChar> |
<DoubleQuoteChar> [<text>] [<DoubleQuoteChar><DoubleQuoteChar>]
[<text>] <DoubleQuoteChar> |
};
<SingleQuoteChar> ::= { ApostropheChar | ''' };
<DoubleQuoteChar> ::= { QuoteChar | '"' };
- - - - -
I found Mike's syntax to be very easy to read and understand, and I don't think
that the use of the square brackets to indicate optional items is going to
cause anybody reading grief, as long as we all agree on what documentation
rules we are actually going to use. Besides, unless I'm missing something, in
Rexx the square bracket is only used to indicate a specific element of an array.
Railroad Tracks?
NO! Never been able to explain them adequately to my programming students - and usually because they require multiple lines to display, it's easy to "lose your place".
BNF notation can be used to PRECISELY define a language, and if a single element requires "more than one line", then either the element is too complex, or it needs to be sub-defined for clarity. Personally, I like the use of the angle brackets in defining "terms" , because then I know what the actual "term name" is, and can expect to find a textual definition of that term a little later on in the documentation.
If we stick to a standard variation of BNF, then there are many tools that we
can use to assist us, in defining the language, and in keeping it as pure and
simple as can be. We also may find tools that we can use to assist in the
creation of actual documentation as well. Of course, we can also write a few of
those tools in Rexx, but that is another story...
- - - -
All said, I would suggest that we use a standard notation such as the Extended Backus-Naur Form as defined in ISO-14977 and
demonstrated in the wikipedia defintions at: http://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form
- - - -
/s/ Bill Turner, wb4alm
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Oorexx-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
