unnclang 0.1.3

Macro-style helpers that let UNNCLang pseudo code run through the Python interpreter

UNNCLang — A Lightweight Tool for Converting Teaching Pseudocode to Python

This is a compiler prepared for UNNC CELEN086, enabling quick testing of pseudocode provided in the course within Python.

Key Features:

• Registers “statement macros” (e.g., endif) to prevent NameErrors during runtime when using bare names;
• Preprocesses teaching syntax (like then:, otherwise, endif) into valid Python before execution;

We recommend running UNNCLang source files using the command-line tool uncl:

uncl code.uncl

Below is a brief, beginner-friendly getting started guide.

Quick Start (3 Steps)

1. Installation (recommended using a virtual environment)

git clone https://github.com/Gentle-Lijie/UNNCLang-Interpreter.git
cd UNNCLang-Interpreter
python3 -m venv .venv
source .venv/bin/activate
pip install -e 

Or (future installation from PyPI):

pip install unnclang

1. Write a minimal example code.uncl:

import unnclang

if a>1 then:
    print(“a is greater than 1”)
endif

3. Run

uncl code.uncl

# If packages aren't installed, you can also run:
python -m unnclang.cli code.uncl

If an undefined variable (e.g., a) is referenced in the source code, Python will raise a NameError. To inject variables before execution, use -s:

uncl code.uncl -s a=2

---

CLI: uncl

Usage:

uncl FILE [ -s name=value ]...

• FILE: UNNCLang source file (e.g., code.uncl);
• -s name=value: Pre-set runtime variables (can be passed multiple times).

Example:

uncl code.uncl -s a=2 -s debug=True

---

Concise Interface for Generating Automated Tests

• unnclang.run_uncl(path, set_vars=None): Reads and preprocesses files, then executes them in an isolated namespace;
• unnclang.statement_macro: Used to register statement-style macros (e.g., endif);
• unnclang.disable_builtin_macros(): Disables automatic injection into builtins (if you wish to avoid polluting the global namespace).

---

Development and Testing

• Source code is located in src/unnclang/; built-in macros reside in src/unnclang/macros/;
• Run tests:

pip install -e .[dev]
pytest

UNNCLang — 教学伪代码到 Python 的轻量工具

这是为UNNC CELEN086准备的一个编译器，以将该课程提供的伪代码快速在 Python 里运行测试。

主要特性：

• 注册“语句宏”（statement macros），例如 endif，使裸名字在运行时不会报 NameError；
• 预处理教学语法（如 then:、otherwise、endif）为合法的 Python 再执行；

推荐使用命令行工具 uncl 运行 UNNCLang 源文件：

uncl code.uncl

下面是一个简短且适合新手的上手指南。

快速开始（3 步）

1. 安装（推荐使用虚拟环境）

git clone https://github.com/Gentle-Lijie/UNNCLang-Interpreter.git
cd UNNCLang-Interpreter
python3 -m venv .venv
source .venv/bin/activate
pip install -e 

或（未来从 PyPI 安装）：

pip install unnclang

1. 写一个最小示例 code.uncl：

import unnclang

if a>1 then:
    print("a is greater than 1")
endif

3. 运行

uncl code.uncl

# 如果未安装包，也可以：
python -m unnclang.cli code.uncl

如果在源码中引用了未定义变量（例如 a），Python 会抛出 NameError。要在执行前注入变量，使用 -s：

uncl code.uncl -s a=2

---

CLI：uncl

用法：

uncl FILE [ -s name=value ]...

• FILE：UNNCLang 源文件（如 code.uncl）；
• -s name=value：预置运行时变量（可多次传入）。

示例：

uncl code.uncl -s a=2 -s debug=True

---

用于生成自动化测试的简要接口

• unnclang.run_uncl(path, set_vars=None)：读取并预处理文件，再在隔离的命名空间中执行；
• unnclang.statement_macro：用于注册 statement-style 宏（如 endif）；
• unnclang.disable_builtin_macros()：取消自动注入到 builtins（如果你不想污染全局命名空间）。

---

开发与测试

• 源码位于 src/unnclang/；内置宏放在 src/unnclang/macros/；
• 运行测试：

pip install -e .[dev]
pytest