System & CLI Usage Guide

1. Verify Environment

Verify that the CLI utility is properly installed by running the core binary command in your terminal.

langpy

2. Basic Execution

Execute localized source files directly via CLI

Create a source file using the localized extension (e.g., `.pyes` for Spanish syntax) and execute it using the base command.

# hello.pyes
definir main():
    nombre = "World"
    imprimir(f"Hello {nombre}!")

main()

langpy hello.pyes

3. Supported File Extensions

The runtime selects the appropriate keyword map based on file extensions

• Spanish (`.pyes` extension): Maps natural keywords like `definir`, `si`, `para`, `imprimir`.
• Portuguese (`.pypt` extension): Maps natural keywords like `definir`, `se`, `para`, `imprimir`.
• French (`.pyfr` extension): Maps natural keywords like `definir`, `si`, `pour`, `imprimer`.

4. Multi-File Project Architecture

Organize structured projects using standard directory layouts

Group multiple modules inside a directory using `__main__.pyes` as the primary execution entry point.

my_project/
├── __main__.pyes     # Main entry point file
├── math.pyes         # Local module or helper class
└── utils/
    ├── __init__.pyes
    └── helpers.pyes

langpy my_project/

5. Industry Bridge: Transpiling to Standard Python

Export localized code directly into clean, standard Python 3 files

When ready to transition to standard environments, generate standard `.py` files ready for any native Python 3 interpreter.

langpy transpile script.pyes

The transpiler recursively parses local directory structures, maintaining module hierarchies while generating clean Python equivalents.

# main.pyes imports utils/math.pyes:
# main.pyes           → main.py
# utils/math.pyes     → utils/math.py

6. Output Directory Specification

Separate educational source files from transpiled build outputs

Use the `--output` flag to specify a target directory for transpiled Python artifacts.

langpy transpile main.pyes --output output_dir/
langpy transpile main.pyes -o output_dir/

7. CLI Command Reference

langpy <file_or_directory>

Executes a single script or a structured project directory in real-time.

langpy script.pyes
langpy my_project/

langpy transpile

Initiates transpilation from localized keywords to standard Python code.

langpy transpile script.pyes

--output / -o

Defines the exact target directory for generated `.py` files.

langpy transpile script.pyes --output output_dir/

--force / -f

Forces overwriting of existing `.py` output files during re-transpilation.

langpy transpile script.pyes --force

--help

Displays terminal help documentation and available flag options.

langpy --help

--version

Displays the installed LangPy package version.

langpy --version

8. Native Ecosystem Interoperability

Seamlessly integrate standard libraries like NumPy, Pandas, or standard Python packages

LangPy operates as a full transpiler, enabling seamless imports of any third-party Python library alongside localized keyword control flows.

# math.pyes
definir suma(a, b):
    retornar a + b

definir resta(a, b):
    retornar a - b

# main.pyes
desde operations importar suma, resta
importar numpy como np

definir analizar_datos():
    # Call custom localized functions
    resultado = suma(10, 5)
    imprimir(f"Sum: {resultado}")
    
    # Utilize standard Python scientific stack
    datos = np.array([1, 2, 3, 4, 5])
    imprimir(f"Mean: {np.mean(datos)}")

analizar_datos()

langpy main.pyes

9. Transpiler Mechanics

LangPy selectively parses control keyword tokens, mapping them into valid Python AST nodes while leaving string literals, comments, and identifiers untouched.

1. Identifies target dictionary mapping based on file extension (`.pyes`, `.pypt`, or `.pyfr`).
2. Tokenizes source files using standard Python lexing tools.
3. Replaces mapped control structures and built-in functions with standard Python identifiers while protecting raw user strings.
4. Reconstructs valid Python 3 syntax trees.
5. Executes directly on the host system's native Python virtual machine.