/* File: MathEL-ebnf.txt
  //    Copyright (C) 2010  Christian Lerch, Vienna, Austria.
  //
  //    This file is part of MathEL - a mathematical expression language.
  //
  //    MathEL is free software: you can redistribute it and/or modify it under 
  //    the terms of the GNU General Public License version 3 as published by 
  //    the Free Software Foundation <http://fsf.org/>.
  //
  //    MathEL is distributed in the hope that it will be useful, but WITHOUT 
  //    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
  //    FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 
  //    for more details.
  //
  //    You should have received a copy of the GNU General Public License along 
  //    with MathEL. If not, see <http://km-works.eu/res/GPL.txt> or 
  //    <http://www.gnu.org/licenses/>.
*/

/*  ============================================
 *  Commented MathEL EBNF grammar v0.9.0026 BETA
 *  ============================================ 
    All lower-case (non-terminal) grammar symbols are defined in this EBNF grammar.
    Upper-case (terminal) grammar symbols denote token types as parsed by the MathEL lexer.
    See the MathEL Symbols and Operators Reference for the literals of these 
    token types.
    For randomly generated MathEL language examples visit 
    <http://km-works.eu/mathel-interactive/?insertRandom=true> 
 */

/*  <formulae>, the unit of translation for the MathEL translator is a <expression>,
    which is a non-empty concatenation of MathEL expressions <expr>+
 */
formulae = expression .
expression = expr+ .


/*  --------------------
 *  TOP-LEVEL STRUCTURES
 *  -------------------- 
    These top-level syntactic structures are designed to establish operator 
    precedence for division "/" and multiplication "*" as implied by arithmetics,
    which leads to minimized grouping brackets and thus more readable code.
    A MathEL expression <expr> is either a <term>, optionally followed by a 
    <tail> expression, or a possibly styled piece of text enclosed in double 
    qoutes.
    A <term> is a <factor> optionally followed by one postfix operator, like ! or '' .
    A <factor> stands for one of the four major types of MathEL constructs: symbol, 
    sub-expression, macro or directive.
 */
expr 
= term [ tail ] 
| styledText .

term = factor [ POSTFIX_OP ] .

tail 
= ( "/" expr ) 
| ( "*" expr ) .

factor 
= decoratedSymbol 
| decoratedExpression
| macro 
| directive .

/*  Directives are used to 
    1) style sub-expressions
    2) -- TBD --
 */
directive = "{%" DIRECTIVE attribute* [ ";" expression ] "%}" .
attribute = "@" name "=" '"' value '"' .

/* end of page 0 */

/*  ------
 *  MACROS
 *  ------
    Macros provide a convenient way of notation for various types of 
    complex constructs, or for constructs that otherwise cannot be 
    expressed.
 */
 
macro 
= sqrtMacro 
| rootMacro 
| fractionMacro 
| intervalMacro 
| differentialMacro 
| binominalMacro 
| multiScriptMacro
| largeOpMacro 
| functionMacro 
.


/*  Construct a square root (implied degree = 2)
 */
sqrtMacro 
= "sqrt" "(" expression ")" .


/*  Construct a root with a degree as given by the 2nd <expression>
 */
rootMacro 
= "root" "(" expression ";" expression ")" .


/*  Construct a fraction with 1st <expression> as the numerator and 2nd <expression>
    as the denominator.
 */
fractionMacro 
= "frac" "(" expression ";" expression ")" .


/*  Construct an interval expression in ISO 31-11 pure square bracket style. 
    Use either ( or ) or both to indicate intervals open to the 
    left ]a,b], to the right [a,b[, or on both sides ]a,b[ , respectively.
 */
intervalMacro 
= "ival" ( "[" | "(" ) expression ";" expression ( ")" | "]" ) .


/* Use the differentialMacro to construct either
    - a differential operator, by giving a <fractionalPart> with 1 parameter, or
    - a differential quotient, by giving a <fractionalPart> with 2 parameters, or
    - a differential, as used in an integral, by using a <decoratedSymbol> without
      parenthesis
    The optional <subSuperScript> is applied to the differential operator only.
    DD ... total, PD ... partial
 */
differentialMacro 
= ( "DD" | "PD" ) [ subSuperScript ] ( fractionalPart | decoratedSymbol ) .


fractionalPart 
= "(" expression [ ";" expression ] ")" .


/*  Construct a binominal coefficient enclosed in parenthesis
 */
binominalMacro 
= "bin" "(" expression ";" expression ")" .


/*  Construct a supported (see SYMFENCE below) symmetrically fenced expression with 
    distinct semantics
 */
symFenceMacro 
= SYMFENCE "(" expression ") .

SYMFENCE
= "abs"     /* an absolute value    */
| "norm"    /* a norm of a vector   */
| "set"     /* set constructor      */
| "seq"     /* a sequence of items  */
| "ceil"    /* ceiling              */
| "floor"   /* floor                */
.


/*  Render a <multiScriptBase> expression with optional pre/post sub/superscripts.
 */
multiScriptMacro
= "script" "(" multiScriptExpr multiScriptBase multiScriptExpr ")"
.

multiScriptExpr 
= (UNDER scriptExpr)? (OVER scriptExpr)?
.

multiScriptBase
= (simpleExpression | simpleSymbol) 
.


/*  Apply one or more possibly sub- and/or super-scripted large operators, 
    like integrals, sum, product, etc. to <expression>. If block-mode is on sub/superscripts
    will automatically be rendered as under/over-scripts.
 */
largeOpMacro 
= (LARGE_OP [ subSuperScript ])+ "[" expression "]" .


/*  Apply a named function (a function known to MathEL) or a user-defined function,
    possibly sub- and/or superscripted to a <simpleExpression>, i.e. expression without 
    sub/superscripts. In contrast to user-defined functions, named functions can be
    localized to the browser's accept-language.
 */
functionMacro 
= ( NAMED_FUNC | "$" ANY_FUNC | "$@" simpleSymbol) [ subSuperScript | DERIVATIVE ] 
  [ simpleExpression ] .

DERIVATIVE
= "'" | "''" | "'''" | "''''" .


/*
 *  SUB-EXPRESSIONS
 */
 
decoratedExpression  = simpleExpression [ subSuperScript ] .

simpleExpression 
= fencedExpression
| fencedVector
| fencedMatrix 
| symFenceMacro .


/*  An expression delimitted by matching or non-matching vertical fences 
    LFENCE and RFENCE of various kinds. [ ] fences serve as invisible grouping 
    devices and will never appear in the output.
 */
fencedExpression
= [ ACCENT_UNDER ] [ ACCENT ] "[" expression "]" 
| "(" [ expression ] ")" 
| "{" [ expression ] "}" 
| LFENCE [ expression ] RFENCE .


/*
 * VECTORS AND MATRICES
 */

/*  Vertical column vector as a handy shortcut for a (1,n)-matrix
 */
fencedVector
= "VEC" 
( "[" matrixCell { ";" matrixCell } "]"
| "(" matrixCell { ";" matrixCell } ")"
| "{" matrixCell { ";" matrixCell } "}"
| LFENCE matrixCell { ";" matrixCell } RFENCE 
) .

fencedMatrix
= "MAT" 
( "[" matrixRow+ "]"
| "(" matrixRow+ ")"
| "{" matrixRow+ "}"
| LFENCE matrixRow+ RFENCE 
) .

matrixRow = "[" matrixCell { ";" matrixCell } "]" .

matrixCell = [ expression ] .


/*
 *  SUB- AND SUPERSCRIPTS
 */
 
subSuperScript = superScript | subScript | subAndSuperScript .

/*  ^ indicates conditional superscript that may automatically morph to overscript
    depending on context. ^^ indicates forced overscript.
 */
superScript = ("^" | "^^") scriptExpr .

/*  _ indicates conditional subscript that may automatically morph to underscript
    depending on context. __ indicates forced underscript.
 */
subScript = ("_" | "__") scriptExpr .

subAndSuperScript = ("_" scriptExpr "^" scriptExpr) | ("__" scriptExpr "^^" scriptExpr).

scriptExpr = [( "+" | "-" )] simpleSymbol	 | simpleExpression | styledText.


/*
 *  SYMBOLS
 */
 
decoratedSymbol = simpleSymbol [ subSuperScript ] .

simpleSymbol = [ ACCENT_UNDER ] [ ACCENT ] styledSymbol .

styledSymbol = [ STYLE ] tokenSymbol .

tokenSymbol = miToken | mnToken | moToken .

moToken = ( INFIX_OP | "+" | "-" ) | GREEK_UC | OTHER_OP | ANY_OPER .

miToken = LATIN_LETTER | GREEK | LETTER_LIKE | ANY_IDENT .

mnToken = INTEGER [ "." INTEGER ] | NUMBER_LIKE .

styledText = [ STYLE ] TEXT .