Msdscript

Table of contents

1. Description
2. Geeting Started
3. User Guide
4. API Documentation

Description:

what is Msdscript:

Msdscript is a language interpreter developed by C++. It just like other programming language which be able to parse and interpret variables, basic arithmetic caculation, logic operation, function call.

what can it be used:

Msdscript can be used in two ways: as a excutable program by itself or incorporated into your application as a library.

Getting Started:

How to build as an executable program:

1. git clone https://github.com/YangQi007/msdscript.git

2. cd your file directory in your terminal

3. make

4. ./msdscript + comandline (There are more details about how to run different commandlines in User Guide)
   For example :
   ./msdscript --interp
   
   ./msdscript --step

5. In new line, type some expressions you want to parse or interpret.
   For example :
   
   type in terminal : 1 + 2
   result : 3
   
   type in terminal : (_fun (x) (x+2))(1)
   result : 3

How to build as a library incorporated into your application:

1. Download the signal file "lib.a" into your program's directory
2. clang++ -std=c++14 -o filename yourfile.cpp lib.a
   For example :
   You can download the test program "which_day.cpp" for testing the library
   
   About the test file which_day program : Although MSDscript is not a very rich language at the moment—it doesn't even have subtraction—it's not far from the the kinds of languages that are embedded in applications. For example, someone implementing a calendar program might want to have a language for advanced users to calculate dates for repeated meetings (say, more sophisticated than “every Tuesday”), and MSDscript could just about work for that.
   
   type in terminal : clang++ -std=c++14 -o which_day which_day.cpp lib.a
   type in termial : ./which_day 13
   result : 4 (which means Thursday)

User Guide:

There are two modes you can choose in msdscript :

1. Interpret mode : Evaluates the expression and return the proper value.
   The commandline is : ./msdscript --interp
   
2. Step mode : The result in this mode are exactly the same as in interp mode. The only difference between step mode and the interp mode is that in step mode the program uses heap memory to interp while in regular mode the program uses stack memory to interp.
   The commandline is : ./msdscript --step
   
3. You can also type : ./msdscript --help which can list all the commandlines you can choose.
   

Examples for expressions you can input :

Variables Expressions :

./msdscript --interp
3
3

Add Expressions :

./msdscript --interp
1 + 2
3

Multiply Expressions :

./msdscript --interp
1 * 2
2

Let Expressions :

./msdscript --interp
_let x=5 _in _let x = x+2 _in x + 1
8

Boolean Expressions :

./msdscript --interp
_if (3==(1+2)) _then 3 _else 1
3

Function Expressions :

./msdscript --interp
The function below will evaluate a factoral 10! :

_let factrl = _fun (factrl) _fun (x) _if x == 1 _then 1 _else x * factrl(factrl)(x + -1) _in factrl(factrl)(10)
3628800

Step Mode Example :

step mode should get the same result as the interpret mode showed above except in while loop function( which can cause memory leak in interp mode)
./msdscript --step
_let countdown = _fun(countdown) _fun(n) _if n == 0 _then 0 _else countdown(countdown)(n + -1) _in countdown(countdown)(1000000)
0

./msdscript --interp
_let countdown = _fun(countdown) _fun(n) _if n == 0 _then 0 _else countdown(countdown)(n + -1) _in countdown(countdown)(1000000)
segmentation fault

Run print commandline :

./msdscript --print
_let x=5 _in x+1
(_let x=5 _in (x+1))

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 provides several API functions:

class Expr:

virtual bool equals(PTR(Expr) e) = 0;
virtual PTR(Val) interp(PTR(Env) env) = 0;
virtual bool has_variable() = 0;
virtual void print(std::ostream &out) = 0;
virtual void pretty_print(std::ostream &out) = 0;
virtual void pretty_print_at(std::ostream &out,precedence_t p,long *position) = 0;
virtual void step_interp() = 0;

subclasses :
NumExpr
AddExpr
MultExpr
VarExpr
_letExpr
BoolExpr
EqualExpr
IfExpr
FunExpr
CallExpr

class Val :

virtual bool equals(PTR(Val) val) = 0;
virtual PTR(Val) add_to(PTR(Val) val) = 0;
virtual PTR(Val) mult_to(PTR(Val) val) = 0;
virtual std::string to_string() = 0;
virtual PTR(Val) call(PTR(Val) actual_arg) = 0;
virtual void call_step(PTR(Val) actual_arg, PTR(Cont) rest) = 0;

subclasses :
NumVal
BoolVal
FunVal

class Step :

static PTR(Val) interp_by_steps(PTR(Expr) e);

class Env :

virtual PTR(Val) lookup(std::string find_name) = 0;

subclasses :
EmptyEnv
ExtendedEnv

class parse :

PTR(Expr) parse_expr(std::istream &in);