Program classes

The Program classes provide a high level interface for working with PPCI. Each class represents one language / code representation. They have a common API to get reporting, compile into other program representations, and export to e.g. textual or binary representations.

Source codeIntermediateMachine code
c3 python ir wasm arm x86

Base program classes

class ppci.programs.Program(*items, previous=None, debugdb=None)

Abstract base class to represent a computer program. Subclasses represent languages (i.e. code representations), e.g. Python, IR, or X86. Program objects can be compiled into one another using the to_xx() methods.

Each instance can have multiple “items”, which can represent files or modules, and which can in some cases be bound/linked into a single object. Some Program classes also provide optimizations. Many languages can be represented in textual or binary form, and can be imported/exported as such.

Each subclass needs to implement:

  • A docstring with a brief description of the language.
  • Method _check_items(items) to test input at initialization.
  • Method _copy().
  • Method _get_report(html).

Each subclasses should implement as applicable:

  • Method optimize().
  • Export methods like as_text().
  • Import classmethods like from_text().
chain

A tuple with the names of the languages that the current object originated from.

copy()

Make a (deep) copy of the program.

get_report(html=False)

Get a textual representation of the program for introspection and debugging purposes. If html the report may be html-formatted.

items

The list of items, representing components such as files or modules.

previous(which=1)

Get a previous Program instance, or None.

Parameters:which –
  • int: Go this many steps back in the compile chain (default 1).
  • str: Get the program in the compile chain that represents the given language.
  • Program instance/class: Get the program in the compile chain that represents the given Program class.
source

The toplevel Program instance that is the source of the compile chain.

to(language, **options)

Compile this program into another representation. The tree is traversed to find the lowest cost (i.e. shortest) chain of compilers to the target language.

Experimental; use with care.

class ppci.programs.SourceCodeProgram(*items, previous=None, debugdb=None)

Base class for source code.

(i.e. intended to be read and written by humans).

get_tokens()

Get the program in the form of a series of (standardized) tokens, for the purpose of syntax highlighting.

class ppci.programs.IntermediateProgram(*items, previous=None, debugdb=None)

Base class for intermediate code representations.

These are programs that are not human readable nor machine executable.

class ppci.programs.MachineProgram(*items, previous=None, debugdb=None)

Base class for executable machine code.

run_in_process()

If the architecture of the code matches the current machine, execute the code in this Python process.

Source code programs

class ppci.programs.C3Program(*items, previous=None, debugdb=None)

C3 is a novel programming language ispired by C, but avoiding some of its contraptions.

The items in a C3Program are strings.

to_ir(includes=None, march=None, reporter=None)

Compile C3 to PPCI IR for the given architecture.

class ppci.programs.PythonProgram(*items, previous=None, debugdb=None)

Python is a dynamic programming language, which is popular due to its great balance between simpliciy and expressiveness, and a thriving community.

The items in a PythonProgram are strings.

run(namespace=None)

Run (i.e. exec()) the code in the current interpreter.

to_ir()

Compile Python to PPCI IR.

Status: very preliminary.

to_wasm()

Compile Python to WASM.

Status: can compile a subset of Python, and assumes all floats.

Intermediate programs

class ppci.programs.IrProgram(*items, previous=None, debugdb=None)

PPCI IR code is the intermediate representation used in PPCI.

optimize(level=2)

Optimize the ir program

to_arm(**options)

Compile to ARM machine code.

Status: …

to_python(**options)

Compile PPCI IR to Python. Not very efficient or pretty code, but it can be useful to test the IR code without compiling to machine code.

Status: complete: can compile the full IR spec.

to_wasm(**options)

Compile PPCI IR to WASM.

Do this by taking each ir module into a wasm module.

to_x86(**options)

Compile to X86 machine code.

Status: …

class ppci.programs.WasmProgram(*items, previous=None, debugdb=None)

WASM (a.k.a. Web Assembly) is an open standard to represent code in a compact, low level format that can be easily converterted to machine code, and run fast as well as safe.

Items in a WasmProgram are WasmModule objects.

as_bytes()

Convert to WASM binary representation.

as_hex()

Turn into a hex representation (using either the byte representation or the text representation). Raises NotImplementedError if this program does not have a binary nor textual representation.

to_ir(**options)

Compile WASM to IR.

Status: very basic.

Machine code programs

class ppci.programs.ArmProgram(*items, previous=None, debugdb=None)

Machine code for most mobile devices and e.g. the Raspberry Pi.

as_object()

Export as binary code object (bytes)

class ppci.programs.X86Program(*items, previous=None, debugdb=None)

Machine code for most common desktops and laptops.

as_elf(filename)

Export as elf file.

as_exe(filename)

Export as a system executable file.

as_object()

Export as binary code object (bytes)