DOCSEARCHbyAlgolia
Submit Docs

Porffor Documentation

repository·main·Indexed 26 days ago

https://github.com/canadahonk/porffor

Porffor is a JavaScript/TypeScript engine, compiler, and runtime that compiles code into C or native binaries. It features a comprehensive parser for JS/TS expressions, statements, and types, and supports multiple compilation targets including C source code and machine-executable binaries via system compilers (gcc, clang, zig) or embedded tcc.

Tokens
3.9K
Snippets
3
Records
35
Agent score
90%

What's inside Porffor

  1. Configure compilation targets and output

    main

    The compiler's behavior is heavily influenced by the Prefs object (imported internally) and environment variables. While the main function accepts a module name, the target and output file are typically controlled via Prefs or CLI arguments.

    Key Configuration Concepts:

    • Targeting C: If the target is set to 'c', the compiler will either write the C code to Prefs.o (if provided), print it to stdout, or use uwebsockets.writeNativeFetchPackage if Prefs.nativeFetch is enabled.
    • Targeting Native: If the target is set to 'native', the compiler invokes a system compiler (like cc, gcc, or clang) or an embedded tcc to produce an executable.
    • Compiler Selection: The system compiler can be configured via Prefs.compiler or the CC environment variable. The C++ compiler is configured via Prefs.cxx or CXX.
    • Optimization: Optimization levels can be passed via the -O flag in command line arguments (e.g., -O3).

  2. Run code snippets with -e or -p

    main
    You can execute a string of code directly without providing a file by using the -e or -p flags. When using these flags, Porffor automatically targets the native runtime and uses a temporary directory for the input and output files.

  3. Parse Variable declarations

    main

    The parseVarStatement and parseVar functions handle the parsing of variable declarations. Supported kinds include:

    • var
    • let
    • const
    • using (ECMAScript Explicit Resource Management)
    • await using (ECMAScript Explicit Resource Management)

    It supports multiple declarations separated by commas (e.g., let a = 1, b = 2;) and handles both simple identifiers and complex binding patterns (Object/Array patterns).

  4. Parse JavaScript/TypeScript statements

    main
    The parseStatement function is the primary entry point for parsing individual statements within the Porffor parser. It handles various statement types including variable declarations (let, const, var, using, await using), control flow (if, switch, for, while, do, break, continue), function declarations, class declarations, and expression statements. It also supports TypeScript-specific syntax when the ts flag is enabled.

  5. Use embedded TCC for fast native compilation

    main

    If you have tcc installed and have assigned the tcc function to globalThis.tcc, the compiler can use it for extremely fast native compilation.

    To enable this, ensure globalThis.tcc is a function that accepts (source, output_path, run_flag) and returns a status code.

  7. Parse TypeScript Class Members

    main

    The parser handles TypeScript-specific class member features including:

    • Accessibility Modifiers: public, private, protected.
    • Modifiers: readonly, override.
    • Decorators: @decorator syntax.
    • Signatures: Method signatures, index signatures, and getter/setter methods.

  8. Parse Function declarations and expressions

    main

    The parseFunction function parses function nodes. It supports:

    • FunctionDeclaration (if an identifier is provided) and FunctionExpression.
    • Generator functions (using the * syntax).
    • Async functions.
    • TypeScript type parameters and return type annotations.
    • TypeScript overload signatures (functions without bodies).
    • Parameter binding lists (including destructuring patterns).
    // Example of the resulting node structure for a function
const node = {
    type: 'FunctionDeclaration', // or 'FunctionExpression'
    start, 
    end: 0, 
    id, 
    expression: false, 
    generator, 
    async: isAsync, 
    params: null, 
    body: null
};