README

This README documents the necessary steps to get M7 Script up and running.

What is this repository for?

  • Quick summary: M7 Script is a general-purpose parser and interpreter that processes unstructured data, including flat text, structured formats (e.g., JSON), and potentially binary data.

    • It can structure raw input (e.g., transforming text or binary data into structured formats).
    • It can interpret structured input (e.g., executing M7 Script programs).

  • Version: 0.9

Use Cases

  • Parsing & Interpretation:

    • General-Purpose Parsing: M7 can process structured and unstructured data, including text, JSON, and potentially binary formats.
    • Data Transformation: Converts raw input (e.g., log files, custom data formats) into structured outputs.

  • Implementation Specific:

    • JSON Parser: Parses JSON structures and normalizes them.
    • M7 Programming Language: Provides a lightweight, embeddable scripting language.
      • Embedded Scripting Engine: Can be integrated into PHP, JavaScript, C, and Perl.
      • Portable Code Execution: Scripts written in M7 can be executed across different environments.

Documentation

How do I get set up?

Available Options

You do not need to adjust the configuration files unless you want to design your own parser. Otherwise, the following options are available:

  • M7 Script Parsing: Parses M7 script files up to the AST level.
  • JSON Parsing: Parses JSON files and returns their structure.

Command-Line Options

M7 Script provides the following command-line options:

  --file        (optional) Path to the input file
  --from        (optional) Parsing start stage (default: source)
  --to          (optional) Parsing end stage (default: normalize)
  --lang        (optional) Specifies the language (e.g., m7, json)
  --input_type  (optional) Type of input (default: file)
  --eval        (optional) Specifies evaluation mode
  --verbose     (optional) Enables verbose output
  (stdin)       Pipe input directly from standard input using `-`

Example Commands

  • Parse JSON and return structure:
    php main.php --file=jsonTest/nested.json --verbose --to=eval --lang=json
  • Parse M7 Script and generate AST:
    php main.php --file=script/testMe.m7 --verbose --to=ast --lang=m7

Processing Stages

M7 Script processes input through the following stages:

  1. source - Initial raw input
  2. tokens - Tokenization step
  3. cst - Concrete Syntax Tree generation
  4. normalize - Cleanup and structural normalization
  5. semantic - Semantic analysis (work in progress)
  6. ast - Abstract Syntax Tree generation
  7. eval - Execution phase

Summary of Setup

  • Clone the repository and configure your environment.
  • Adjust the configuration file to set execution parameters (if needed).
  • Dependencies: M7 Script requires PHP and is self-contained with no additional libraries needed. Compatible with PHP 5.45 and later.
  • Database Configuration: Not required, but logging can be integrated with MySQL or SQLite.
  • How to run tests: Run php test.php to execute the test suite.
  • Deployment Instructions: Copy the necessary files to your server and configure execution permissions.

Contribution Guidelines

  • Writing Tests: Any tests written should include comments within the script describing the test. Clearly indicate whether the test is meant for parsing only or if it is executable.
  • Code Review: Follow best practices and submit pull requests for code changes.
  • Other Guidelines: Ensure all changes are documented and maintain backward compatibility where possible. M7 Script is designed to remain compatible with PHP 5.45 and later.

License

M7 Script version 0.9 is licensed under the Business Source License (BUSL-1.1) for a period of 5 years. This license applies only to this version. After this period, the license will be reviewed and updated accordingly. Until then, usage, modification, and distribution are subject to the terms outlined in the BUSL-1.1 license.. After this period, the license will be reviewed and updated accordingly. Until then, usage, modification, and distribution are subject to the terms outlined in the BUSL-1.1 license.

For more details, see LICENSE.

Who do I talk to?

  • Repo owner or admin: M7 Soft/Swift Ventures Inc, Henry Goss