MSDscript

Table of Contents

• Description
• Getting Started
• User Guide
• API Documentation

Description:

• What is MSDscript: MSDscript is an interpreter built upon a C++ foundation that allows for the parsing and interpreting of mathematical expressions. This includes:
• Numerical Expressions
• Variable Expressions
• Boolean Expressions
• Addition Expressions
• Multiplication Expressions
• Let Expressions
• If/Else Expressions
• Equivalence Expressions
• Function Expressions
• Call Expressions
• How it's meant to be used: MSDscript can be built and ran as a stand alone script. Users may input an expression via the command line which will be parsed and interpretted. MSDscript can also be used as an embedded language.
• Expression Precedence
• Multiplication Expression
• Addition Expression
• Equivalence Expression
• Let Expressions, If/Else Expression, Function Expressions, Call Expressions

Getting Started:

Via the command line, navigate into the directory where the MSDscript package is located. Run the following commands:

• cmake .
  Generates a Makefile in the current directory
• make
  Installs the MSDscript executable and MSDscriptLib library
• The program can be ran from the command line in the directory where the executable is located by running the following command: ./MSDscript
• The program can also be ran as a library using libMSDlibrary.a via the commandline and the following command:
  $ c++ -o project_name your_project.cpp libMSDlibrary.a

User Guide:

MSDscript can parse user input and interpret a variety of expressions.

• Numerical Expressions
• Format:
• Numbers in MSDscript may be positive or negative. MSDscript is not capable of parsing numbers that may include decimals, commas, division symbols, or spaces
• Examples:
• -5
• 100000
• 0
• Errors:
• 5,000
• 3.14159
• 1 000 000
• 1/4
• Variable Expressions
• Format:
• Variables in MSDscript consist of an unbroken string of upper or lowercase letters and containing no numerical representations or spaces
• Examples:
• x
• VAR
• hello
• Errors:
• h3ll0
• h e l l o
• Boolean Expressions
• Format:
• Boolean expressions can be interpreted using MSDscript by using _true or _false
• Examples:
• _true
• _false
• Errors:
• true
• false
• yes
• no
• Addition Expressions
• Format:
• Addition expressions can be interpreted using MSDscript by using the + operator. MSDscript is not capable of parsing or interpreting the - operator used as subtraction
• Examples:
• 2 + -3
• (2 + (-3))
• Errors:
• 2 - 3
• Subtraction will result in the following error: "Invalid input for an expression"
• Multiplication Expressions
• Format:
• Multiplication expressions can be interpreted using MSDscript by using the * operator. MSDscript is not capable of parsing or interpreting the / operator
• Examples:
• 2 * -3
• (1 * 0)
• Errors:
• 2 / 3
• Division will result in the following error: "Invalid input for an expression"
• Let Expressions
• Format:
• MSDscript can interpret Let Expressions in the following format _let (variable) = (expression) _in (expression)
• _let (variable) = (expression) assigns a variable to an expression. This assigned expression is then substituted into the expression found after _in.
• Examples:
• _let x = 5 _in x + 2
• Errors:
• let x = 5 _in x + 2
• A _ must precede let or the following error will occur: "Invalid input for an expression" or "_let expected" if used as an inner expression
• _let x = 5 in x + 2
• A _ must precede in or the following error will occur: "_in expected"
• _let x 5 _in x + 2
• A = must follow the variable for proper assignment in or the following error will occur: "equal expected"
• If/Else Expressions
• Format:
• MSDscript can interpret If/Else Expressions in the following format _if (boolean) _then (expression) _else (expression). MSDscript will return the _if expression if the boolean is true and the _else expression if the boolean is false.
• Examples:
• _if _false _then 5 _else 3
• This will result in leading to the else branch and will return 3 after interpretation
• _if 6 == 6 _then 5 _else 3
• This will result in leading to the if branch and will return 5 after interpretation
• _if 6 == _true _then 5 _else 3
• Comparing a number to a boolean will always result in _false, which would be the _else branch, and will return a 3 after interpretation
• Errors:
• _if 2 _then 5 _else 3
• A boolean expression must be after the _if. A non-boolean after _if will result in the error: "Test expression is not a boolean"
• if _true _then 5 _else 3
• A _ must precede if or the following error will occur: "Invalid input for an expression" or "_in expected" if used as an inner expression
• _if _true then 5 _else 3
• A _ must precede then or the following error will occur: "_then expected"
• _if _true _then 5 else 3
• A _ must precede else or the following error will occur: "_else expected"
• Equivalence Expressions
• Format:
• MSDscript can interpret equivalence statements using == and return a boolean. The == operation can work on any kinds of values, and is allowed to compare a boolean to a number, but only a number expression can be equivalent with a number expression, and only a boolean expression can be equivalent to a number expression. MSDscript can interpret equivalence statments involving variables if the variable have been assigned a value.
• Examples:
• 6 == 6
• This example compares a number to a number and would interp to _true
• _true == _false
• This example compares a boolean to a boolean and would interp to _false
• 1 == _true
• This example compares a number to a boolean, which will always interp to _false
• _let x = 5 _in x == x
• This example will interp to _true
• Errors:
• 6 = 6
• This will result in the following error: "2nd equal sign expected"
• x == y
• Since x and y have not been defined at this point, this will result in the following error: "free variable: x"
• Function Expressions
• Format:
• MSDscript can interpret Functions in the following format _fun ((variable)) (expression)
• Examples:
• _fun (x) x * 2
• This is similar to f(x) = x*2
• Errors:
• fun (x) x * 2
• _ must precede fun and will result in the following error: "Invalid input for an expression"
• _fun x x * 2
• the variable argument after _fun must be surrounded by parenthesis and will result in the following error: "Invalid input for an expression"
• Call Expressions
• MSDscript can use call expressions in conjunction with function expressions to pass a value into a function.
• Examples:
• (_fun (x) x * 2)(3)
• This will pass 3 in for x and result in 6 after interpretation
• Errors:
• (_fun (x) x * 2)3
• A call value must be placed within parenthesis after a function expression and will result in the following error: "Invalid input for an expression"

Comandline Arguments:

• --help
  • 'help' will show the user which arguments MSDscript can run
  • Example:
  • ./MSDscript --help (return)
    Allowed Arguments: --help, --interp, --print, --pretty-print, --test, --step
• --print
  • 'print' will print an expression without spaces and with parenthesis around the expression
  • Example:
  • ./MSDscript --print (return) 2 + 2 (ctrl+d)
    (2+2)
• --pretty-print
  • 'pretty-print' will print an expression avoiding unnecessary parenthesis assuming that operators associating to the right
  • Examples:
  • ./MSDscript --pretty-print (return) (6*2) (ctrl+d)
    6 * 2
  • ./MSDscript --pretty-print (return) (6*2)+5 (ctrl+d)
    6 * 2 + 5
  • ./MSDscript --pretty-print (return) (6*2)*5 (ctrl+d)
    (6 * 2) * 5
  • Potential Error:
  • ./MSDscript --interp (return) _let x = y in x+5 (ctrl+d)
    _in expected
• --interp
• 'interp' will return the value of an expression if possible
• Examples:
• ./MSDscript --interp (return) (6*2)+5 (ctrl+d)
  17
• ./MSDscript --interp (return) _let x = 3 _in x+5 (ctrl+d)
  8
• ./MSDscript --interp (return) 7 == 7 (ctrl+d)
  _true
• Potential Error:
• ./MSDscript --interp (return) _let x = y _in x+5 (ctrl+d)
  free variable: y
• --step
• 'step' works the same as interp but will prevent segmentation faults for recursive calls
• --test
• 'test' will run catch tests found within the code to make sure the program is working as intended

Note: Command-line programs depend on an input on end of file, so use 'ctrl+d' as opposed to 'return' when finished entering an expression and to begin the program

MSDscript Grammar

〈expr〉     = 〈comparg〉
                | 〈comparg〉==〈expr〉
            
〈comparg〉  = 〈addend〉
                | 〈addend〉+〈comparg〉
            
〈addend〉   = 〈multicand〉
                | 〈multicand〉*〈addend〉
            
〈multicand〉= 〈inner〉
                | 〈multicand〉(〈expr〉)
            
〈inner〉    = 〈number〉| (〈expr〉) |〈variable〉
                | _let〈variable〉=〈expr〉_in〈expr〉
                | _true | _false
                | _if〈expr〉_then〈expr〉_else〈expr〉
                | _fun (〈variable〉)〈expr〉

API Documentation

MSDscript Files

Core
• `cmdline.cpp, cmdline.hpp` - Contains methods necessary for command line arguments for the terminal
• `cont.cpp, cont.hpp` - Contains methods necessary for continuations within step mode interpretation
• `env.cpp, env.hpp` - Contains methods necessary for quick referencing of variables without creating new expressions
• `expr.cpp, expr.hpp` - Contains methods for expressions
• `parse.cpp, parse.hpp` - Contains methods necessary for parsing an input or string
• `step.cpp, step.hpp` - Contains methods necessary for step interpretation which prevents seg faults in large recursive expressions
• `val.cpp, val.hpp` - Contains methods necessary for values

Helper
• `main.cpp` - Runs the commandline code. Can be used for testing with editing the scheme.
• `pointer.h` - Allows for the switching between shared and regular pointers.

Tests
• `catch.h` - Used to run the tests found through various cpp codes.

Expr Functions
• `equals(PTR(Expr)a)`
• Returns a boolean to determine if two expressions are equivalent.
• `PTR(Val) interp(PTR(Env) env)`
• Returns a PTR(Val) which represents the interpreted expression
• `void print(std::ostream& output)`
• Returns void. Used to print an expression to an output stream.
• `void pretty_print(std::ostream& output)`
• Returns void. Used to print an expression avoiding unnecessary parenthesis assuming that operators are associating to the right to an output stream.
• `void step_interp()`
• Returns void. Used to interpret recursive expressions without causing a segmentation fault.

Expr Subtypes
• `NumExpr` - Represents numeric expressions
• `AddExpr` - Represents addition expressions
• `MultExpr` - Represents a multiplication expression
• `VarExpr` - Represents a variable expression
• `LetExpr` - Represents a let expression
• `BoolExpr` - Represents a boolean expression
• `IfExpr` - Represents an else/if expression
• `EqExpr` - Represents an equivalence expression
• `FunExpr` - Represents a function expression
• `CallExpr` - Represents a call to a function expression

Val Functions
• `equals(PTR(Val) v)`
• Returns a boolean to determine if two values are equivalent.
• `PTR(Val) add_to(PTR(Val) rhs)`
• Returns a PTR(Val) of the addition result of the calling value to the parameter value.
• `mult_to(PTR(Val) rhs)`
• Returns a PTR(Val) of the multiplication result of the calling value to the parameter value.
• `print(std::ostream& outstream)`
• Returns void. Used to print a value to an output stream.
• `is_true()`
• Returns a boolean whether the calling value is _true.

Val Subtypes
• `NumVal` - Represents a number value
• `BoolVal` - Represents a boolean value
• `FunVal` - Represents a function value

Parsing Expressions
MSDscript can parse expressions by utilizing the `parse()` function.
• `PTR(Expr) parse(std::istream &in)` takes an input stream and will return `PTR(Expr)` which is a pointer to an expression. This function is used in the command line to parse user input into an expression.
• `PTR(Expr) parse_str(std::istream &in)` takes a string and will return `PTR(Expr)` which is a pointer to an expression.

Interpretting Expressions
MSDscript can interpret expressions by utilizing the `interp()` function.
• `interp_by_steps(PTR(Expr) e)` takes an expression and returns `PTR(Val)` which is the interpreted value