Mscript Interpreter
it.py – Interpreter for the Mscript language
Version: 0.7.0
Author: Momo-AUX1
Date: 2025-05-21

---

Table of Contents

• Overview
• Features
• Requirements
• Installation
• Usage
  • Interactive REPL
  • Running Scripts
• Standard Library
• Python Interoperability
• Language Grammar
• Built-in Functions
• Examples
  • Hello World
  • FFI Example
  • Python Interop Example
• Version History
• Roadmap
• Contributing
• License

---

Overview

Mscript is a small, Python-powered scripting language with braces-based blocks and built-in support for variables, arithmetic, control flow, functions, data structures, I/O, FFI, and seamless Python interop. This repository provides:

• it.py – the Lark-based interpreter
• language.def – the grammar definition
• mscript_builtins.py – core built-ins
• std/ – standard library modules written in Mscript

Visual Studio Code Extension

For enhanced language support, install the Mscript VS Code Extension from the Visual Studio Marketplace.

Features

• Variable assignment and lookup
• Arithmetic (+, -, *, /, %, **)
• Control flow: if / elif / else, while, for, break, continue
• First-class functions, with parameters and return
• Lists and dictionaries
• Module import (import "std/..." or import python)
• Exception handling: try / catch
• Built-in functions: input, print, str, int, type, file I/O, math, JSON, regex, time, environment, FFI, and more
• REPL with history
• Foreign Function Interface (FFI) to call C libraries via ctypes
• Seamless Python interop: any Python package installed via pip is immediately accessible under the python module

---

Requirements

• Python 3.7+
• Lark parser

Install Lark with:

pip install lark

---

Installation

Install via PyPI:

pip install mscript-lang

Or clone the repo:

git clone https://github.com/momo-AUX1/Mscript.git
cd mscript

---

Usage

Interactive REPL

Start the REPL with no arguments:

mscript

You'll see:

Mscript REPL 0.6.9 by Momo-AUX1 (type Ctrl-D to exit)
>>>

Type Mscript statements or expressions; results and errors print immediately.

Running Scripts

Run a .mscript file:

mscript myscript.mscript

• --version: print interpreter version and exit
• --debug: show parse tree

---

Standard Library

A collection of Mscript modules installed under std/, importable via:

import "std/module_name"

Included modules:

• datetime.mscript: today(), now(), strftime(), parse()
• ffi.mscript: load(), sym(), func(), buffer(), buffer_ptr(), offset(), read/write helpers
• json.mscript: loads(), dumps()
• math.mscript: sin(), cos(), tan(), log(), log10(), exp(), sqrt(), floor(), ceil(), pow(), constants PI, E
• platform.mscript: system(), node(), release(), version(), machine(), processor(), full()
• random.mscript: random(), seed(), randint(), uniform(), choice(), shuffle()
• re.mscript: search(), match(), findall(), sub()
• string.mscript: upper(), lower(), strip(), lstrip(), rstrip(), find(), replace(), split(), join(), substring()
• sys.mscript: argv(), getenv(), setenv(), unsetenv(), platform proxy
• time.mscript: sleep(), time()

---

Python Interoperability

Mscript exposes a special python module that proxies into Python’s ecosystem:

import python

# call built-in Python functions
hi = python.print
hi("mscript!")   # prints to stdout

# import any pip-installed package
req = python.requests.get("https://api.example.com").text
print req

• Any library installed in your Python environment (via pip install …) can be imported and used directly in Mscript using import python.
• Access modules, functions, classes, and attributes exactly as in normal Python.

---

Language Grammar

Defined in language.def (LALR):

?start: statement+

?statement: assign | index_assign | print_stmt | if_stmt | while_stmt
          | for_stmt | func_def | return_stmt | expr_stmt | import_stmt
          | break_stmt | continue_stmt | try_stmt

# (see full grammar in language.def)

---

Built-in Functions

Category	Examples
Core	input, print, str(), int(), type(), len(), keys(), values()
File I/O	read(), write(), system()
Math	_sin(), _cos(), _log(), _sqrt(), _pow()
JSON	_json_loads(), _json_dumps()
Regex	_re_search(), _re_findall(), _re_sub()
Date/Time	_date_today(), _datetime_now(), _strftime()
Env/Sys	_getenv(), _setenv(), exit()
FFI	_ffi_open(), _ffi_sym(), _ffi_buffer(), _ffi_read_uint32()
Random	_random_random(), _random_choice(), _random_shuffle()
Platform	_platform_system(), _platform_platform()

See mscript_builtins.py for full list.

---

Examples

Hello World

# hello.mscript
x = "hello world"
print str.upper(x)

Run:

mscript hello.mscript
# Output: HELLO WORLD

Foreign Function Interface (FFI)

import "std/ffi"

SDL = ffi.load("libSDL2.dylib")
SDL_Init = ffi.func(SDL, "SDL_Init", "int", ["uint"])
SDL_Quit = ffi.func(SDL, "SDL_Quit", "void", [])

if SDL_Init(32) != 0 {
    print "SDL_Init failed!"
    exit(1)
}
# ...
SDL_Quit()

Python Interop Example

import python

# use Python’s `math` module
print python.math.sqrt(2)

# HTTP request via `requests` (must be installed in your env)
resp = python.requests.get("https://httpbin.org/ip").json()
print resp["origin"]

# define function pointers directly to Mscript variables
hello = python.print

# use them as if they were our own
hello("world!")

---

Version History

• 0.6.9 – Current release (2025-05-22)
• 0.6.0 – Supporting more built-ins, enhancements to error handling
• 0.5.0 – True standard library
• 0.4.0 – Added more built-ins, try/except support
• 0.3.0 – Dotted names in functions and assignments
• 0.2.0 – Core interpreter improvements
• 0.1.0 – Initial release

---

Roadmap

• Package manager
• Expanded standard library
• Module namespace support
• Advanced debugging tools

---

License

This project is licensed under the MIT License. See LICENSE for details.