=======
Summary
=======

.. contents::
   :local:
   :depth: 2

**UniversalExpressionParser** is a library for parsing expressions like the one demonstrated below into expression items for functions, literals, operators, etc.

.. sourcecode::
     :linenos:

     var z = x1*y1+x2*y2;

     var matrixMultiplicationResult = [[x1_1, x1_2, x1_3], [x2_1, x2_2, x2_3]]*[[y1_1, x1_2], [y2_1, x2_2], [y3_1, x3_2]];

     println(matrixMultiplicationResult);

     [NotNull] [PublicName("Calculate")]
     public F1(x, y) : int => 
     {
         
         /*This demos multiline
         comments that can be placed anywhere*/
         ++y /*another multiline comment*/;
         return 1.3EXP-2.7+ ++x+y*z; // Line comments.
     }

     public abstract class ::metadata{description: "Demo prefix"} ::types[T1, T2, T3] Animal
        where T1: IType1 where T2: T1, IType2 whereend
        where T3: IType3 whereend
     {    
         public abstract Move() : void;    
     }

     public class Dog : (Animal)
     {
         public override Move() : void => println("Jump");
     }




- Below is the demo code used to parse this expression:

.. sourcecode:: csharp
     :linenos:

     using OROptimizer.Diagnostics.Log;
     using TextParser;
     using UniversalExpressionParser.DemoExpressionLanguageProviders;

     namespace UniversalExpressionParser.Tests.Demos
     {
         public class SummaryDemo
         {
             private readonly IExpressionParser _expressionParser;
             private readonly IExpressionLanguageProvider _nonVerboseLanguageProvider = new NonVerboseCaseSensitiveExpressionLanguageProvider();
             private readonly IExpressionLanguageProvider _verboseLanguageProvider = new VerboseCaseInsensitiveExpressionLanguageProvider();
             private readonly IParseExpressionOptions _parseExpressionOptions = new ParseExpressionOptions();

             public SummaryDemo()
             {
                 IExpressionLanguageProviderCache expressionLanguageProviderCache = 
                     new ExpressionLanguageProviderCache(new DefaultExpressionLanguageProviderValidator());
                 
                 _expressionParser = new ExpressionParser(new TextSymbolsParserFactory(), expressionLanguageProviderCache,
                     LogHelper.Context.Log);

                 expressionLanguageProviderCache.RegisterExpressionLanguageProvider(_nonVerboseLanguageProvider);
                 expressionLanguageProviderCache.RegisterExpressionLanguageProvider(_verboseLanguageProvider);
             }
          
             public IParseExpressionResult ParseNonVerboseExpression(string expression)
             {
                 /*
                 The same instance _expressionParser of UniversalExpressionParser.IExpressionParser can be used
                 to parse multiple expressions using different instances of UniversalExpressionParser.IExpressionLanguageProvider
                 Example:

                 var parsedExpression1 = _expressionParser.ParseExpression(_nonVerboseLanguageProvider.LanguageName, "var x=2*y; f1() {++x;} f1();");
                 var parsedExpression2 = _expressionParser.ParseExpression(_verboseLanguageProvider.LanguageName, "var x=2*y; f1() BEGIN ++x;END f1();");
                 */
                 return _expressionParser.ParseExpression(_nonVerboseLanguageProvider.LanguageName, expression, _parseExpressionOptions);
             }
         }
     }


- Expression is parsed to an instance of **UniversalExpressionParser.IParseExpressionResult** by calling the method  **IParseExpressionResult ParseExpression(string expressionLanguageProviderName, string expressionText, IParseExpressionOptions parseExpressionOptions)** in **UniversalExpressionParser.IExpressionParser**.

- The interface **UniversalExpressionParser.IParseExpressionResult** (i.e., result of parsing the expression) has a property **UniversalExpressionParser.ExpressionItems.IRooxExpressionItem RootExpressionItem { get; }** that stores the root expression item of a tree structure of parsed expression items.

- The code that evaluates the parsed expression can use the following properties in **UniversalExpressionParser.ExpressionItems.IRootExpressionItem** to iterate through all parsed expression items:

   - **IEnumerable<IExpressionItemBase> AllItems { get; }**
   - **IReadOnlyList<IExpressionItemBase> Prefixes { get; }**
   - **IReadOnlyList<IKeywordExpressionItem> AppliedKeywords { get; }**
   - **IReadOnlyList<IExpressionItemBase> RegularItems { get; }**
   - **IReadOnlyList<IExpressionItemBase> Children { get; }**
   - **IReadOnlyList<IExpressionItemBase> Postfixes { get; }**
   - **IReadOnlyList<IExpressionItemBase> Prefixes { get; }**

- All expressions are parsed either to expressions items of type **UniversalExpressionParser.ExpressionItems.IExpressionItemBase** or one of its subclasses for simple expressions or to expressions items of type **UniversalExpressionParser.ExpressionItems.IComplexExpressionItem** (which is a sub-interface of UniversalExpressionParser.ExpressionItems.IExpressionItemBase) or one of its subclasses for expression items that consists of other expression items.

- Some examples simple expression items are: **UniversalExpressionParser.ExpressionItems.ICommaExpressionItem** for commas, **UniversalExpressionParser.ExpressionItems.IOpeningBraceExpressionItem** and **UniversalExpressionParser.ExpressionItems.IClosingBraceExpressionItem** for opening and closing braces "(" and ")"

- Some complex expression items are: **UniversalExpressionParser.ExpressionItems.IBracesExpressionItem** for functions like "f1 (x1, x2)", **UniversalExpressionParser.ExpressionItems.IOperatorExpressionItem** for operators like the binary operator with operands "f1(x)" and "y" in "f1(x) + y".

- All expressions are currently parsed to one of the following expression items (or intances of other sub-interfaces of these interfaces) in namespaces **UniversalExpressionParser.ExpressionItems** and **UniversalExpressionParser.ExpressionItems.Custom**: **ILiteralExpressionItem**, **ILiteralNameExpressionItem**, **IConstantTextExpressionItem**, **IConstantTextValueExpressionItem**, **INumericExpressionItem**, **INumericExpressionValueItem**, **IBracesExpressionItem**, **IOpeningBraceExpressionItem**, **IClosingBraceExpressionItem**, **ICommaExpressionItem**, **ICodeBlockExpressionItem**, **ICustomExpressionItem**, **IKeywordExpressionItem**, **ICodeBlockStartMarkerExpressionItem**, **ICodeBlockEndMarkerExpressionItem**, **ISeparatorCharacterExpressionItem**, **IOperatorExpressionItem**, **IOperatorInfoExpressionItem**, **IKeywordExpressionItem**, **UniversalExpressionParser.ExpressionItems.Custom.ICustomExpressionItem**, **IRootExpressionItem**, **IComplexExpressionItem**, **ITextExpressionItem**, **IExpressionItemBase**. The state of this expression items can be analyzed when evaluating the parsed expression.

.. raw:: html

    <a href="https://github.com/artakhak/UniversalExpressionParser/blob/main/UniversalExpressionParser.Tests/Demos/DemoExpressions/SummaryExpression.parsed"><p class="codeSnippetRefText">Click here to see the visualized instance of UniversalExpressionParser.IParseExpressionResult</p></a>

- The format of valid expressions is defined by properties and methods in interface **UniversalExpressionParser.IExpressionLanguageProvider**. The expression language name **UniversalExpressionParser.IExpressionLanguageProvider.LanguageName** of some instance **UniversalExpressionParser.IExpressionLanguageProvider** is passed as a parameter to method **ParseExpression(...)** in **UniversalExpressionParser.IExpressionParser**, as demonstrated in example above. Most of the properties and methods of this interface are demonstrated in examples in sections below.

- The default abstract implementation of this interface in this package is **UniversalExpressionParser.ExpressionLanguageProviderBase**. In most cases, this abstract class can be extended and abstract methods and properties can be implemented, rather than providing a brand new implementation of **UniversalExpressionParser.IExpressionLanguageProvider**.

- The test project **UniversalExpressionParser.Tests** in git repository has a number of tests for testing successful parsing, as well as tests for testing expressions that result in errors (see section **Error Reporting** below). These tests generate random expressions as well as generate randomly configured instances of **UniversalExpressionParser.IExpressionLanguageProvider** to validate parsing of thousands of all possible languages and expressions (see the test classes **UniversalExpressionParser.Tests.SuccessfulParseTests.ExpressionParserSuccessfulTests** and **UniversalExpressionParser.Tests.ExpressionParseErrorTests.ExpressionParseErrorTests**).

- The demo expressions and tests used to parse the demo expressions in this documentation are in folder **Demos** in test project **UniversalExpressionParser.Tests**. This documentation uses implementations of **UniversalExpressionParser.IExpressionLanguageProvider** in project **UniversalExpressionParser.DemoExpressionLanguageProviders** in **git** repository.

- The parsed expressions in this documentation (i.e., instances of **UniversalExpressionParser.ExpressionItems.IParseExpressionResult**) are visualized into xml texts, that contain values of most properties of the parsed expression. However, to make the files shorter, the visualized xml files do not include all the property values.