https://github.com/smuuf/primi
Primi language: A scripting language written in PHP.
https://github.com/smuuf/primi
interpreted-programming-language interpreter language php primi programming repl scripting scripting-language
Last synced: about 1 month ago
JSON representation
Primi language: A scripting language written in PHP.
- Host: GitHub
- URL: https://github.com/smuuf/primi
- Owner: smuuf
- License: mit
- Created: 2017-10-16T20:49:59.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-12-23T01:33:09.000Z (6 months ago)
- Last Synced: 2025-05-14T03:43:17.815Z (about 1 month ago)
- Topics: interpreted-programming-language, interpreter, language, php, primi, programming, repl, scripting, scripting-language
- Language: PHP
- Homepage:
- Size: 1.76 MB
- Stars: 125
- Watchers: 5
- Forks: 14
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Primi
A scripting language written in PHP & interpreted in PHP.
Primi is meant for PHP developers who want to allow their clients to write their own custom logic. Primi allows you (the developer) to execute untrusted code (provided simply as a string) inside a sandbox, safely separated from its surroundings.
---
Code Climate | Packagist
--- | ---
[](https://codeclimate.com/github/smuuf/primi/maintainability) [](https://codeclimate.com/github/smuuf/primi/test_coverage) | [](https://packagist.org/packages/smuuf/primi) [](https://packagist.org/packages/smuuf/primi) [](https://packagist.org/packages/smuuf/primi)
---
# Quick access
- [Language reference (syntax help)](/docs/language_reference.md)
# Rationale
Primi *- as things sometimes go in life -* began as an answer to a practical problem: I needed some general-purpose *(ie. not too much domain-specific)* scripting language that my other app's users could use to write their simple custom logic. I needed some universally usable and **primi**tive scripting thing, with familiar syntax *(`PHP-like` x `C-like` x `JS-like`)* and one that could be safely executed inside pure PHP environment *(no external depedencies on v8js, v8 and whatnot - meaning Javascript is out of the game...)*.
***Thus, Primi was (mostly as an experiment) created.***
# Installation
You can either use *Primi* as a **[standalone package](#a-standalone-installation)** `(a)` - for its development, making contributions, debugging it, or to just play with it. Or you can use *Primi* **[in your own projects](#b-as-a-library)** `(b)` by installing it as a Composer dependency.
#### You'll want either one of these:
- `git clone https://github.com/smuuf/primi.git` *(standalone use)*
- `composer require smuuf/primi` *(using Primi as a library in your own project)*
## a) Standalone installation
1. Clone this repo.
- `git clone https://github.com/smuuf/primi.git`
2. Install Composer dependencies.
- `composer install`
3. Run something with Primi CLI.
- `chmod +x ./primi && ./primi -s -c "a = 1 + 2 / 3;"`
### Convenient installation Oneliner™:
```
git clone https://github.com/smuuf/primi.git && cd primi && composer install && chmod +x ./primi && ./primi -s -c "msg = 'Primi works.';"
```
### Extra stuff:
- **Register Primi's CLI executable** for current user so typing `primi` will behave like a binary *(otherwise you'd need to write `./primi` and would have to be in the right directory)*:
```
./bin/registerbin
```
*Note: This will add an alias in .bashrc for current user.*
- **Run tests** *(tests are located inside `./tests/` directory)*:
```
./bin/test
```
- **Rebuild parser** *(when you modify Primi's grammar definitions, you will want to rebuild the parser to reflect the changes)*:
```
./bin/buildparser
```
## b) Using Primi as a library
1. First, install [Primi Composer package](https://packagist.org/packages/smuuf/primi): `composer require smuuf/primi`
2. Then use it like this:
```php
run('a = 1; b = a + 2; c = "some string"; d = c + " extra thing";');
// Get defined variables from primary context and print them.
foreach ($context->getVariables() as $name => $value) {
printf("%s (%s) ... %s\n", $name, $value::TYPE, $value->getCoreValue());
}
} catch (\Smuuf\Primi\ErrorException $e) {
die($e->getMessage());
}
```
Running this code would output:
```
a (number) ... 1
b (number) ... 3
c (string) ... some string
d (string) ... some string extra thing
```
# REPL mode
Primi provides a convenient *"sandbox"* [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) mode which is launched by executing `./primi` without any argument. You can use this for messing around with the language or to test any new stuff you might be trying to implement *(e.g. your own Primi extensions written in PHP)*.
In this mode, all statements are executed when entered and the result value of the last expression is returned. REPL commands history is preserved between separate sessions *(history is stored in `~/.primi_history` file)*.
# Language reference
The basics of the language syntax and data types are found here:
https://github.com/smuuf/primi/blob/master/docs/language_reference.md