README

A simple interpreter made in PHP. It allows to parse an abstract language tokens and do whatever you want

Content

• What is an Interpreter
• Installation
• Usage
• Check also

What is an Interpreter

An interpreter is a piece of software which allows parse an array of tokens of any language and give them a "significance". For example you could process a function, call a service, do something funny...

As an example, imagine we have an APILexer and APIParser, which understands a metalanguage to script some instructions related with REST APIS:

$script = "
GET https://some-awesome-api.com/endpoint?token=TOKEN
PIPETO $mySuperService
SAVEDB localhost:10000
";


$lexer = new APILexer($script);
$parser = new APIParser($lexer);

$tokens = $parser->parse();

// var_dump($tokens) should be:

array(12) {
  [0]=>
  object(Token)#4 (2) {
    ["value":protected]=>
    string(3) "GET"
    ["type":protected]=>
    int(2)
  }
  [1]=>
  object(Token)#2 (2) {
    ["value":protected]=>
    string(1) " "
    ["type":protected]=>
    int(3)
  }
  [2]=>
  object(Token)#5 (2) {
    ["value":protected]=>
    string(49) "https://some-awesome-api.com/endpoint?token=TOKEN"
    ["type":protected]=>
    int(4)
  }
  [3]=>
  object(Token)#6 (2) {
    ["value":protected]=>
    string(1) "
"
    ["type":protected]=>
    int(5)
  }
  [4]=>
  object(Token)#7 (2) {
    ["value":protected]=>
    string(6) "PIPETO"
    ["type":protected]=>
    int(2)
  }
  [5]=>
  object(Token)#8 (2) {
    ["value":protected]=>
    string(1) " "
    ["type":protected]=>
    int(3)
  }
  [6]=>
  object(Token)#9 (2) {
    ["value":protected]=>
    string(15) "$mySuperService"
    ["type":protected]=>
    int(4)
  }
  [7]=>
  object(Token)#10 (2) {
    ["value":protected]=>
    string(1) "
"
    ["type":protected]=>
    int(5)
  }
  [8]=>
  object(Token)#11 (2) {
    ["value":protected]=>
    string(6) "SAVEDB"
    ["type":protected]=>
    int(2)
  }
  [9]=>
  object(Token)#12 (2) {
    ["value":protected]=>
    string(1) " "
    ["type":protected]=>
    int(3)
  }
  [10]=>
  object(Token)#13 (2) {
    ["value":protected]=>
    string(15) "localhost:10000"
    ["type":protected]=>
    int(4)
  }
  [11]=>
  object(Token)#14 (2) {
    ["value":protected]=>
    string(5) "<EOF>"
    ["type":protected]=>
    int(1)
  }
}

With these tokens we can do some kind of magic and create an Interpreter which process them. For example, we can call it: APIInterpreter.

public class APIInterpreter extends Interpreter {

    public function __construct(APIParser $parser)
    {
        parent::__construct($parser, null);

        $this
            // Allows make GET using an http client or whatever...
            ->loadFunction(new APIGetFunction(...))
            // Allows to interact with DDBB and store values
            ->loadFunction(new DBFunction(...))
            // ...whatever
    }

    protected function consume(): TokenInterface {

        $token = parent::consume();
        if(
            $token->getValue() !== Lexer::EOF_VALUE &&
            $token->getType() === YOUR_TYPE)
            //do something

        return $token;
    }

    /**
     * Execute this interpreter using the parsed tokens
     */
    public function run()
    {
        // All your tokens processing logic goes here
        $token = $this->lookahead();

        // do something with GET token and whitespace token, or whatever...

        do {
            //...
        }while(($token = $this->lookahead()));
    }

    // Write your auxiliar functions here

    /**
     * this one could parse each starting command line:
     * GET, PIPETO, SAVEDB, etc...
     */
    public function processCommand()
    {
        ...
    }

    /**
     * This one could resolve some service from PIPETO command...
     */
    public function processService()
    {
        ...
    }
}

Well that is a super simple example. You have to left your imagination work and do something special :)

Installation

composer require didix16/php-interpreter

Usage

Using the example above, I'm gonna show a simple usage to instruct the APIInterpeter how it should be acting when reading our great APIScript:

A simple script would have a structure like this:

GET https://some-awesome-api.com/endpoint?token=TOKEN
PIPETO $mySuperService
SAVEDB localhost:10000

We can identify lines, which each line is an action. Each action has a keyname, a space and a param ( it could be a list of params)

So lets say we have to identify tokens like:

T_ACTION, T_WHITESPACE, T_ARG and T_NEWLINE

<?php

// APILexer.php

use didix16\Grammar\Lexer;
use didix16\Grammar\Token;
use didix16\Interpreter\Interpreter;

// Imported an APIParser
use ...\APIParser;

public class APIGetFunction extends InterpreterFunction {

    public function __construct()
    {
        parent::__construct("GET");
    }

    public function run(...$args)
    {
        /**
         * $url = $args[0];
         * return request()->get($url)
         * or whatever
         */
    }
}

public class DBFunction extends InterpreterFunction {

    public function __construct()
    {
        parent::__construct("SAVEDB");
    }

    public function run(...$args)
    {
        /**
         * Get the data to be stored to DDBB.
         * Preprocess the data if you need it
         * 
         * return DDBB::connection($args[0])->store($data)
         */
    }
}

public class APIInterpreter extends Interpreter {

    /**
     * Hold API response result, for example or result from executed function
     */
    private $currentResult;

    public function __construct(APIParser $parser)
    {
        parent::__construct($parser, null);

        $this
            // Allows make GET using an http client or whatever...
            ->loadFunction(new APIGetFunction(...))
            // Allows to interact with DDBB and store values
            ->loadFunction(new DBFunction(...))
            // ...whatever
    }

    /**
     * Execute this interpreter using the parsed tokens
     */
    public function run()
    {
        // All your tokens processing logic goes here
        $token = $this->lookahead();

        do {
            
            switch($token->getType()){
                case APILexer::T_ACTION:
                    $this->processCommand();
                    break;
                default:
                    // ignore whitespaces and newlines
                    // arguments should never be at start of a line
                    $this->consume();
            }
                

        }while(($token = $this->lookahead()));

        // Returns something meaningful to understand that your interpreter has been finished ok
        // Or return some data if needs to
    }

    // Write your auxiliar functions here

    /**
     * this one could parse each starting command line:
     * GET, PIPETO, SAVEDB, etc...
     */
    public function processCommand()
    {
        $command = $this->consume()->getValue();
        $args = [];

        
        while($this->lookahead()->getType() !== APILexer::T_NEWLINE)
        {
            if($this->lookahead()->getType() === APILexer::T_WHITESPACE)
                $this->consume(); // ' '
            else
                $args[] = $this->processCommandArg();
        }
        $this->consume(); // consume new line

        $this->currentResult = $this->executeFunction($command, $args);
    }

    public function processCommandArg()
    {
        $value = $this->consume()->getValue();

        // make some processing of the argument if you need...
        //transform($value);
        /**
         * if $value === $mySuperService then
         * import superService or whatever
         */

        return $value;
    }

    /**
     * This one could resolve some service from PIPETO command...
     */
    public function processService()
    {
        ...
        // call the imported service and do something with previous result
        // Note that services array must be defined
        $this->services[$mySuperService]->doSomething($this->currentResult);
    }
}

Now with the interpreter, you can take some actions in function of each command. You are free to add as more commands you need.

Check also

• php-grammar - A simple library to make Lexer and Parsers to build a language.