Merge pull request #34 from judovana/0.1.9-release

0.1.9 release

README.md

@@ -33,6 +33,7 @@
           * [Editing a Matrix example](#editing-a-matrix-example)
        * [12. Finding the characteristic polynomial of a Matrix](#12-finding-the-characteristic-polynomial-of-a-matrix)
 * [Logical Calculus](#logical-calculus)
+* [Expanding Calculus](#expanding-calculus)
 * [TO BE CONTINUED](#to-be-continued)
 
 
@@ -48,7 +49,7 @@ If you need to access this library via Maven Central, do:
         <dependency>
             <groupId>com.github.gbenroscience</groupId>
             <artifactId>parser-ng</artifactId>
-            <version>0.1.8</version>
+            <version>0.1.9</version>
         </dependency>
        
 
@@ -726,8 +727,10 @@ This would give:
 ## Logical Calculus
 
 The logical expressions in math engine have theirs intentional limitations. Thus allmighty logical expression parser was added around individually evaluated Mathematical expressions which results can be later compared, and logically grouped.  The simplest way to evaluate an logical  expression in ParserNG is to use the <code>LogicalExpression</code> class.
-<code>LogicalExpression</code> is the class responsible for basic comaprsions and logica  expression parsing and evaluation. It calls <code>MathExpression</code> to ech of its basic non-logical parts
-
+<code>LogicalExpression</code> is the class responsible for basic comaprsions and logica  expression parsing and evaluation. It calls <code>MathExpression</code> to ech of its basic non-logical parts. The default <code>MathExpression</code> can be repalced by any custom implementation of <code>Solvable</code>, but it is only for highly specialized usages. Highlight, where MathExpression is using <code>()</code> for mathematical bracketing, LogicalExpression - as () can be part of underlying comapred mathematical expressiosn  uses <code>[]</code> brackets.<br>
+<br>
+In CLI, you can use -l/-L/--logic switch to work with LogicalExpression. Although it is fully compatible with MathExpression you may face unknown issue<br>
+<br>
 Do:<br>
 `LogicalExpression expr = new LogicalExpression("[1+1 < (2+0)*1 impl [ [5 == 6 || 33<(22-20)*2 ]xor [ [  5-3 < 2 or 7*(5+2)<=5 ] and 1+1 == 2]]] eq [ true && false ] ");`
 <br>
@@ -827,7 +830,7 @@ to:  true  eq  false
     is: false
 false
 ```
-Note, that logical parsser supports only dual operators, so where true|false|true is valid, 1<2<3  is invalid!
+Note, that logical parsser's comparsions supports only dual operators, so where true|false|true is valid, 1<2<3  is invalid!
 Thus:  [1<2]<3   is necessary and  even  [[true|false]|true]is recomeded to be used, For 1<2<3  exception is thrown.
 Single letter can logical operands can be used in row. So eg | have same meaning as ||. But also unluckily also eg < is same as <<
 Negation can be done by single ! strictly close attached to [; eg ![true]  is ... false. Some spaces like ! [ are actually ok to
@@ -836,6 +839,69 @@ But much less for [r=3;r<r+1 || [r<5]]", which fails and must be declared as "[r
 To avoid this, you can declare all in first dummy expression: "[r=3;r<1] || [r<r+1 || [r<5]]" which ensure theirs allocation ahead of time and do not affect the rest
 If you modify the variables, in the subseqet calls, results maybe funny. Use verbose mode to debug order
 
+## Expanding Calculus
+Very often an expressions, or CLI is called above known, huge (generated) array of values. Such can be processed via <code>ExpandingExpression</code>. Unlike  other Expressins, this one have List<String> as aditional parameters, where each member is a number. THose numbers can thenbe accessed as L0, L1...Ln. Size of the list is held in special MN variable. The index can be calucalted dynamically, like L{MN/2} - in example of four items, will expand to L2. Although `{}` and `MN` notations are powerfull, the main power is in *slices*:
+```
+Instead of numbers, you can use literalls L0, L1...L99, which you can then call by:
+Ln - vlaue of Nth number
+L2..L4 - will expand to values of L2,L3,L4 - order is hnoured
+L2.. - will expand to values of L2,L3,..Ln-1,Ln
+..L5 - will expand to values of  L0,L1...L4,L5
+where ..L5 or L2.. are order sensitive, the L{MN}..L0 or L0..L{MN} is not. But requires dynamic index evaluation
+When used as standalone, VALUES_PNG xor VALUES_IPNG  are used to pass in the space separated numbers (the I is inverted order)
+Assume VALUES_PNG='5 9 3 8', then it is the same as VALUES_IPNG='8 3 9 5'; BUt be aware, with I the L.. and ..L are a bit oposite then expected
+L0 then expand to 8; L2.. expands to 9,3,8; ' ..L2 expands to 5,9 
+L2..L4 expands to 9,5; L4..L2 expands to 5,9
+```
+ExpandingExpression calls <code>LogicalExpression</code> inside, and yet again the underlying Math evaluator is - defaulting as  <code>MathExpression</code> can be repalced by any custom implementation of <code>Solvable</code>. Highlight, where MathExpression is using <code>()</code> for mathematical bracketing, LogicalExpression ses <code>[]</code> brackets. The dynamic indexes in <code>ExpandingExpression</code> uses are wrapped in `{}`  <br>
+<br>
+In CLI, you can use -e/-E/--expanding switch to work with Expanding expressions. The array of numbers goes in via VALUES_PNG xor VALUES_IPNG variable. Although it is fully compatible with MathExpression and LogicalExpression you may face unknown issue<br>
+<br>
+Example:<br>
+```
+VALUES_PNG="1 8 5 2" java -jar target/parser-ng-0.1.9.jar -e "avg(..L{MN/2})*1.1-MN <  L0 | (L1+L{MN-1})*1.3 + MN<  L0" -v
+avg(..L{MN/2})*1.1-MN <  L0 | (L1+L{MN-1})*1.3 + MN<  L0 
+Expression : avg(..L{MN/2})*1.1-MN <L0 | (L1+L{MN-1})*1.3 + MN<L0 
+Upon       : 1,8,5,2
+As         : Ln...L1,L0
+MN         = 4
+  L indexes brackets: avg(..L{4/2})*1.1-4 <  L0 | (L1+L{4-1})*1.3 + 4<  L0 
+    Expression : 4/2
+    Expanded as: 4/2
+    is: 2.0
+    4/2 = 2 (2.0)
+  to: avg(..L 2 )*1.1-4 <  L0 | (L1+L{4-1})*1.3 + 4<  L0 
+    Expression : 4-1
+    Expanded as: 4-1
+    is: 3.0
+    4-1 = 3 (3.0)
+  to: avg(..L 2 )*1.1-4 <  L0 | (L1+L 3 )*1.3 + 4<  L0 
+Expanded as: avg(1,8 )*1.1-4 <  2 | (5+1 )*1.3 + 4<  2 
+avg(1,8 )*1.1-4 <  2 | (5+1 )*1.3 + 4<  2 
+  brackets: avg(1,8 )*1.1-4 <  2 | (5+1 )*1.3 + 4<  2 
+      evaluating logical: avg(1,8 )*1.1-4 <  2 | (5+1 )*1.3 + 4<  2 
+        evaluating comparison: avg(1,8 )*1.1-4 <  2
+          evaluating math: avg(1,8 )*1.1-4
+          is: 0.9500000000000002
+          evaluating math: 2
+          is: 2
+        ... 0.9500000000000002 < 2
+        is: true
+        evaluating comparison: (5+1 )*1.3 + 4<  2 
+          evaluating math: (5+1 )*1.3 + 4
+          is: 11.8
+          evaluating math: 2 
+          is: 2
+        ... 11.8 < 2
+        is: false
+      ... true | false
+      is: true
+  true
+is: true
+true
+```
+
+See [jenkins-report-generic-chart-column](https://github.com/judovana/jenkins-report-generic-chart-column#most-common-expressions) as real-world user of `ExpandingParser`
 
 ## TO BE CONTINUED
 And much more!

pom.xml

@@ -3,7 +3,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.github.gbenroscience</groupId>
     <artifactId>parser-ng</artifactId>
-    <version>0.1.8</version>
+    <version>0.1.9</version>
     <packaging>jar</packaging>
 
     <name>ParserNG</name>

src/main/java/math/Main.java

@@ -248,7 +248,7 @@ public static void setExpandable(boolean expandable) {
 
     public static String getVersion() {
         //todo, read from pom. See JRD how we did it
-        return "0.1.8";
+        return "0.1.9";
     }
 
     public static MultiSwitch getLogcalSwitch() {

src/main/java/parser/ExpandingExpression.java

@@ -98,10 +98,11 @@ public static String getHelp() {
         //longterm todo, repalce this static help by better help using delegated help methods from logical parser
         return "This is abstraction which allows to set with slices, rows and subset of immutable known numbers." + "\n" +
                 "Instead of numbers, you can use literalls L0, L1...L99, which you can then call by:" + "\n" +
-                "Ln - vlaue of Nth number" + "\n" +
+                "Ln - vlaue of Nth number, or in Slices" + "\n" +
                 "L2..L4 - will expand to values of L2,L3,L4 - order is hnoured" + "\n" +
                 "L2.. - will expand to values of L2,L3,..Ln-1,Ln" + "\n" +
                 "..L5 - will expand to values of  L0,L1...L4,L5" + "\n" +
+                "where ..L5 or L2.. are order sensitive, the L{MN}..L0 or L0..L{MN} is not. But requires dynamic index evaluation." + "\n" +
                 "When used as standalone, " + VALUES_PNG + " xor " + VALUES_IPNG + "  are used to pass in the space separated numbers (the I is inverted order)" + "\n" +
                 "Assume " + VALUES_PNG + "='5 9 3 8', then it is the same as " + VALUES_IPNG + "='8 3 9 5'; BUt be aware, with I the L.. and ..L are a bit oposite then expected" + "\n" +
                 "L0 then expand to 8; L2.. expands to 9,3,8; ' ..L2 expands to 5,9 " + "\n" +
@@ -113,12 +114,12 @@ public static String getHelp() {
                 "MN         = 4\n" +
                 "Expanded as: avg(60,20,80)*1.1-4 <  70 | 80*1.3 + 4<  70\n" +
                 "...indeed\n" +
-                "Dynamic calculation of L's indexes\n" +
+                "Dynamic calculation of L's indexes:\n" +
                 "Sometimes, Lx, as number is not enough, and you need to calcualte it dynamically. To do so, you can use L{}\n" +
                 "Inisde {} can be mathematical formula (including Ls, MN. or even nested {}, which will evaluate itself as number, which will be used as Lx. Eg:\n" +
                 "'avg(..L{MN/2}) < avg(L{MN/2}..)' will go to 'avg(..L1) < avg(L1..)' will go on 1 2 3 to 'avg(1,2 ) < avg(2,3) will go to 1.5<2.5 ... true'\n" +
                 "For fun try eg: VALUES_PNG='1 2 3' on 'avg(..L{L{MN/2}}) < avg(L{L{MN/2}}..)'\n" +
-                "This parser by default uses LogicalExpression interpreter, but should work directly in" + "\n" +
+                "This parser by default uses LogicalExpression interpreter, but should work directly on simple Logical or Math expressions. The LogicalExpression class canbe repalced if needed." + "\n" +
                 "In verbose mode, the expanded expression is always printed";
 
     }