diff --git a/README.md b/README.md new file mode 100644 index 0000000..e4083bd --- /dev/null +++ b/README.md @@ -0,0 +1,250 @@ +# cs-mic +CS-MIC is a .NET library written in C# designed to give developers easy access to expression parsing. For many developers, there is no need to involve complicated settings and formats. With few exposed methods and objects, CS-MIC makes basic expression solving as simple as possible with as little logic required from developers as possible. In fact, one can pull a value with only one line of code. + +*** + +## Usage + +CS-MIC follows a few basic rules when interpreting user input, but should prove to be fairly straightforward for most developers. While CS-MIC tries to ensure that the order of operations as far as it knows them (parentheses – powers, multiplication, division – addition, subtraction), there may be instances where formatting fails. If this should be noticed, please report it. + + +### Expression Parsing + +#### Operands + +`+` - Addition + +`–` - Subtraction + +`*` - Multiplication + +`/` - Division + +`^` - Raise to a power + +`%` - Modulus + +#### Tokens + +`::` - Assign a numeric value to a variable. + +`:=` - Assign an equation to a variable. + +`->` - Assigns a comma delimited array of numbers to an array variable. + +#### Comparison + +`==` - Returns ‘True’ if two values are equal to each other. + +`>` - Returns ‘True’ if a value is greater than another value. + +`<` - Returns ‘True’ if a value is less than another value. + +`>=` - Returns ‘True’ if a value is greater than or equal to another value. + +`<=` - Returns ‘True’ if a value is greater than or equal to another value. + + +#### Base Conversion + +* Decimal + * All numbers are interpreted as decimal by default. +* Binary + * Binary numbers are succeeded by a B, non case sensative. +* Hexadecimal + * Hexadecimal numbers are preceded by 0x, non case sensative. + +#### Example Input and Output + +**Input**|**Output** +:-----:|:-----: +`5 + 5` | `10` +`5 * 2` | `10` +`1 + 2 * 3` | `7` +`(1 + 2) * 3` | `9` +`5 / 2` | `2.5` +`5 / 0` | `Attempted to divide by zero.` +`2 ^ 32` | `4294967296` +`x :: 4` | `4` +`x :: 6 + 4` | `10` +`y := 2^x` | `(2^x)` + +### Scripting + +#### Rules + +* Any valid expression can be computed. +* All computation counts towards the script’s history. This means that once a variable is set inside a script, the variable will remain set until execution of the script is complete. +* Only one command can be executed per line. No token is required to end the command. +* Every code block must be opened and closed with a bracket ( { } ). The only exception is the main code block. + +#### Loops + +`while` - Executes a code block as long as a given condition evaluates to true. + +``` +while(bool expression) +{ +CODE BLOCK +} +``` + +`for` - After executing an initial condition, a code block is executed while a condition is met. A final statement is executed at the end of each iteration. + +``` +for(* expression, bool condition, * expression) +{ +CODE BLOCK +} +``` + +#### Conditionals + +`if` - Executes a code block if a given condition evaluates to true. An optional else block can follow the if block for execution if the statement evaluates as false. + +``` +if(bool expression) +{ +CODE BLOCK +} +else +{ +CODE BLOCK +} +``` + +#### Functions + +`echo` - Displays the output from the proceding expression. + +``` +echo: expression +``` + +`say` - Displays a string. + +``` +say: “string” +``` + +`display` - Combines strings and expressions to a single line in the output stack. + +``` +display: “string”, 12 * 2, “string”, sin(12) +``` + +`function` - Creates a new function with a given name, and any number of expected arguments. + +``` +function(newFunction, anyArgumentName) +{ + sin(anyArgumentName) + cos(anyArgumentName) +} +``` + +#### Comments + +* Block Tokens + * Starting token: /* + * Ending token: */ + *Any line falling between block comment tokens will be ignored by the macro builder at execution time. +* Line Tokens + * // + * Any line starting with the line token will be ignored by the macro builder at execution time. + + +**Example Script** + +``` +say: “Fibonacci Sequence” +temp :: 1 +y :: 1 +echo: y +for(x :: 1, x < 11, x :: temp + y) +{ +echo: x +temp :: y +y :: x +} +x :: 1 +say: “While Loop” +while(x < 10) +{ +if(x == 5) +{ +display: “The condition ‘x == 5’ has been met. x = “, x, “.” +} +else +{ +echo: sin(x) +} +x :: x + 1 +} +``` + +**Example Script Output** +``` +Fibonacci Sequence +1 +1 +2 +3 +5 +8 +13 +21 +34 +55 +89 +While Loop +0.841470984807897 +0.909297426825682 +0.141120008059867 +-0.756802495307928 +The condition ‘x == 5’ has been met. x = 5. +-0.279415498198926 +0.656986598718789 +0.989358246623382 +0.412118485241757 +``` + +## Built In Functions + +The following is a list of the internally recognized functions in CS-MIC: + +`sin(double expression)` + +Returns the sine value of a given expression. + +`cos(double expression)` + +Returns the cosine value of a given expression. + +`tan(double expression)` + +Returns the tangent value of a given expression. + +`round(double expression)` + +Rounds an expression to the nearest whole number. + +`sqrt(double expression)` + +Returns the square root of an expression. + +`abs(double expression)` + +Returns the absolute value of a given expression. + +`exp(double expression)` + +Returns the constant e raised to a given power. + +`log(double expression1, double expression2)` + +Returns the log of expression1 to the base of expression2 + +`precision(double expression1, int expression2)` + +Returns the value of expression1 to a given precision. For example, precision(12.3456789, 4) will return 12.3456. +