p2sh 0.4.2

The p2sh Programming language interpreter
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

# p2sh

![Rust](https://github.com/binoyjayan/p2sh/actions/workflows/rust.yml/badge.svg)

🦀 🦀 🦀 Interpreter for the p2sh programming language 🦀 🦀 🦀

## Introduction

`p2sh` is a scripting language designed for packet processing. The Documentation can be found [here](./docs/README.md).
This project served as a means for me to learn Rust; therefore, some parts of the code might not adhere strictly to Rust idioms. A p2sh script can be edited using the [kilo editor](https://github.com/binoyjayan/kilo-rs/tree/main) which is tailored to recognize its syntax.

## Dependencies

The p2sh interpreter is compiled using a Rust compiler v1.65.0. Any version later than that should work.
Please visit the Rust website for installation.

## Build and test

### Run tests

It has decent test coverage for all the modules, including tests for
the scanner, parser, opcode definitions, compiler, virtual machine,
and built-ins.

```bash
cargo test
```

### Run examples

```bash
cargo run --release examples/formatting/formatted-output.p2
cargo run --release examples/algorithms/fibonacci-recursive.p2
cargo run --release examples/algorithms/fibonacci-iterative.p2
```

### Run the REPL

Run an interactive REPL loop to execute program statements
on the terminal one at a time and see the output immediately.

```bash
cargo run --release
```
```
>> 1 + 2
3
```


### Create a release build

Build release with default options

```bash
cargo build --release
```

This will create a release binary in the './target/release' directory.

### Additional build options

#### debug_print_code

The option helps building source with source code disassembly enabled.

Build with the option:

```bash
cargo build --release --features  'debug_print_code'
```

Run the REPL:

```bash
cargo run --release --features  'debug_print_code'
```
```
...

>> 1 + 2
--------- Instructions [len: 8   ] -------------------
0000 OpConstant 0
0003 OpConstant 1
0006 OpAdd
0007 OpPop
------------------------------------------------------
----------- Constants [len: 2   ] --------------------
[0] 1
[1] 2
------------------------------------------------------
3
```

Run an example:

```bash
cargo run --release --features  'debug_print_code' examples/algorithms/fibonacci-recursive.p2
```

#### debug_trace_execution

This option helps build the release for tracing program execution and
examining the state of the stack.

```bash
cargo build --release --features  'debug_trace_execution'
```

## Installation

The p2sh intepreter can be installed by copying the binary to a directory
that is in your path such as `/usr/local/bin`. Once installed, it can be
executed by running it like so

```
p2sh script.p2 <args>
```

###  shebang

A p2sh script may also be executed using a shebang.
The first line of a p2sh script must be a line that looks like this:

```
#!/usr/bin/env p2sh
```

Then, the script may be run as:

```
./script.p2 <args>
```

OR

```
/path/to/script.p2 <args>
```

## More Information

- **Examples** may be found in the  [examples](./examples) directory
- **Documentation** can be found [here](./docs)