l0c namespace

Classes

class _TemporarySourceWriteError
Report a generated-C write failure that also retained its path.

Functions

auto compiler_identity_text() -> str
L0 Compiler (l0c) - Stage 1: Analysis and C Code Generation This is the main entry point for the L0 compiler's stage 1, which includes:
auto _scan_cli_presentation_options(Sequence argv[str]) -> Tuple[int, bool]
Return fallback verbosity and rich-log settings before --.
auto _emit_verbose_compiler_identity(argparse.Namespace args) -> None
Emit the compiler identity through the normal verbose logging path.
auto _init_env_defaults() -> None
Initialize default environment variables based on L0_HOME.
auto _load_file_lines(str path, Dict] cache[str, List[str]) -> List[str]
Load lines of a source file, using a cache to avoid redundant reads.
auto _emit_diagnostic(str message) -> None
Write one normative compiler diagnostic line to standard error.
auto print_diagnostics(AnalysisResult result) -> None
Print diagnostics from the analysis result.
auto print_diagnostic_list(List diagnostics[Diagnostic]) -> None
Print a list of diagnostics, using a file cache for source snippets.
auto print_diagnostic_with_snippet(Diagnostic diag, Dict] file_cache[str, List[str]) -> None
Print a single diagnostic, including the source line and a caret.
auto _is_valid_module_name(str module_name) -> bool
Check if a module name is valid (dot-separated identifiers).
auto build_search_paths(CompilationContext context, argparse.Namespace args) -> Optional[SourceSearchPaths]
Build source search paths from command-line arguments.
auto build_compilation_context(argparse.Namespace args) -> CompilationContext
Build a CompilationContext from command-line arguments.
_run_analysis(argparse.Namespace args) protected
Run the analysis pipeline.
auto _get_module_names(argparse.Namespace args, CompilationUnit cu) -> List[str]
Get the list of module names based on the --all-modules flag.
auto _find_cc() -> Optional[str]
Find the best available C compiler.
_compiler_flag_family(str compiler) protected
Determine the compiler family for flag selection using a simple heuristic.
auto _is_windows_host() -> bool
Return whether the current Python host is Windows.
auto _default_executable_name() -> str
Return the default build output name for the current platform.
auto _runtime_include_flags(str flag_family, str runtime_include) -> list[str]
Return compiler-family-specific runtime include flags.
auto _runtime_library_flags(str flag_family, str runtime_lib) -> list[str]
Return compiler-family-specific runtime library search-path flags.
auto _output_flags(str flag_family, Path exe_path) -> list[str]
Return compiler-family-specific output flags.
auto _validated_temporary_directory() -> Path
Resolve and validate the host temporary directory.
auto _emit_temporary_source_cleanup_failure(Path c_path) -> None
Report a compiler-temporary source retained after failed cleanup.
auto _remove_temporary_c_source(Path c_path) -> bool
Remove a generated-C temporary and report retained recovery state.
auto _write_temporary_c_source(str c_code) -> Path
Atomically create and write one anonymous generated-C source.
auto _check_entry_main_for_build(AnalysisResult result, str entry_name) -> bool
Check that the entry module defines a valid 'main' function for build/run.
auto _validate_runtime_library_path(str runtime_lib_path) -> bool
Validate that the provided runtime library path exists and is a directory.
auto _split_c_options(Optional raw_options[str]) -> List[str]
Split a raw C options string into individual compiler arguments.
auto _get_optimize_flag(str flag_family, List extra_opts[str]) -> Optional[str]
Determine the appropriate optimization flag for the compiler family.
auto _compile_generated_c(argparse.Namespace args, CompilationContext context, Path c_path, Path exe_path) -> int
Invoke the selected host compiler for one generated-C source.
auto cmd_build(argparse.Namespace args) -> int
Build an executable from an L0 module.
auto cmd_run(argparse.Namespace args) -> int
Build and run an L0 module.
auto cmd_codegen(argparse.Namespace args) -> int
Generate C code for a module.
auto cmd_check(argparse.Namespace args) -> int
Run analysis and type checking without code generation.
auto cmd_compile(argparse.Namespace args) -> int
Report that separate compilation is not implemented in Stage 1 yet.
auto cmd_ast(argparse.Namespace args) -> int
Pretty-print the parsed AST.
auto _format_token_dump_text(tok) -> str
Return token payload text for --tok output.
auto _dump_tokens_for_file(Path path, bool include_eof) -> int
Dump lexer tokens for a single file.
auto cmd_tok(argparse.Namespace args) -> int
Dump lexer tokens.
auto cmd_sym(argparse.Namespace args) -> int
Dump module-level symbol tables.
auto cmd_type(argparse.Namespace args) -> int
Dump resolved type information.
auto _add_target_args(argparse.ArgumentParser parser) -> None
Add target module/file arguments to the parser.
auto _add_all_modules_arg(argparse.ArgumentParser parser) -> None
Add the –all-modules flag to the parser.
auto _add_runtime_args(argparse.ArgumentParser parser) -> None
Add runtime-related arguments to the parser.
auto _add_codegen_arg(argparse.ArgumentParser parser) -> None
Add codegen-related arguments to the parser.
auto _split_cli_and_program_args(Sequence argv[str]) -> Tuple[List[str], List[str], bool]
Split compiler CLI arguments from program arguments.
auto _normalize_cli_argv(argparse.ArgumentParser parser, Sequence argv[str]) -> List[str]
Normalize exact short-option spellings before passing them to argparse.
auto _validate_mode_scoped_flags(argparse.ArgumentParser parser, argparse.Namespace args) -> None
Reject flags that were provided for a mode where they are not valid.
auto _validate_reserved_canonical_flags(argparse.ArgumentParser parser, argparse.Namespace args) -> None
Reject canonical compiler options whose behavior is not implemented.
auto main(Optional] argv[List[str] = None) -> None
Parse CLI arguments, dispatch the selected mode, and exit.

Variables

dict _CLI_LONG_VALUE_OPTIONS
dict _CLI_NAMESPACED_SHORT_VALUE_OPTIONS
dict _CLI_CANONICAL_SHORT_VALUE_OPTIONS
dict _CLI_OTHER_SHORT_VALUE_OPTIONS
tuple _CLI_VALUE_OPTIONS

Function documentation

str l0c::compiler_identity_text()
compiler/stage1_py/l0c.py

L0 Compiler (l0c) - Stage 1: Analysis and C Code Generation This is the main entry point for the L0 compiler's stage 1, which includes:

  • Command-line interface parsing
    • Environment variable handling for defaults
    • Building the compilation context and search paths

Return the user-facing compiler identity/version text.

Tuple[int, bool] l0c::_scan_cli_presentation_options(Sequence argv[str]) protected
compiler/stage1_py/l0c.py

Return fallback verbosity and rich-log settings before --.

Parameters
argv The complete list of command-line arguments.
Returns A tuple of (verbosity count, rich-log enabled).

Values following value-taking options are skipped even when they resemble presentation flags, matching the normalization grammar used for parsing.

None l0c::_emit_verbose_compiler_identity(argparse.Namespace args) protected
compiler/stage1_py/l0c.py

Emit the compiler identity through the normal verbose logging path.

None l0c::_init_env_defaults() protected
compiler/stage1_py/l0c.py

Initialize default environment variables based on L0_HOME.

List[str] l0c::_load_file_lines(str path, Dict] cache[str, List[str]) protected
compiler/stage1_py/l0c.py

Load lines of a source file, using a cache to avoid redundant reads.

Parameters
path Path to the source file.
cache Cache of file lines keyed by path.
Returns A list of strings representing the lines of the file.

None l0c::_emit_diagnostic(str message) protected
compiler/stage1_py/l0c.py

Write one normative compiler diagnostic line to standard error.

Parameters
message Diagnostic text without a trailing newline.

None l0c::print_diagnostics(AnalysisResult result)
compiler/stage1_py/l0c.py

Print diagnostics from the analysis result.

Parameters
result The analysis result containing diagnostics.

None l0c::print_diagnostic_list(List diagnostics[Diagnostic])
compiler/stage1_py/l0c.py

Print a list of diagnostics, using a file cache for source snippets.

Parameters
diagnostics List of diagnostics to print.

None l0c::print_diagnostic_with_snippet(Diagnostic diag, Dict] file_cache[str, List[str])
compiler/stage1_py/l0c.py

Print a single diagnostic, including the source line and a caret.

Parameters
diag The diagnostic to print.
file_cache Cache of file lines keyed by path.

bool l0c::_is_valid_module_name(str module_name) protected
compiler/stage1_py/l0c.py

Check if a module name is valid (dot-separated identifiers).

Parameters
module_name The module name to validate.
Returns True if the module name is valid, False otherwise.

Optional[SourceSearchPaths] l0c::build_search_paths(CompilationContext context, argparse.Namespace args)
compiler/stage1_py/l0c.py

Build source search paths from command-line arguments.

Parameters
context The compilation context for logging.
args Parsed command-line arguments.
Returns A SourceSearchPaths object if successful, or None if the entry name is invalid.

Handles entry path parsing and default values from environment variables.

CompilationContext l0c::build_compilation_context(argparse.Namespace args)
compiler/stage1_py/l0c.py

Build a CompilationContext from command-line arguments.

Parameters
args Parsed command-line arguments.
Returns A new CompilationContext configured based on arguments.

l0c::_run_analysis(argparse.Namespace args) protected
compiler/stage1_py/l0c.py

Run the analysis pipeline.

Parameters
args Parsed command-line arguments.
Returns A tuple of (AnalysisResult, CompilationContext, int) where the integer is the suggested exit code.

List[str] l0c::_get_module_names(argparse.Namespace args, CompilationUnit cu) protected
compiler/stage1_py/l0c.py

Get the list of module names based on the --all-modules flag.

Parameters
args Parsed command-line arguments.
cu The compilation unit.
Returns A list of module names to process.

Optional[str] l0c::_find_cc() protected
compiler/stage1_py/l0c.py

Find the best available C compiler.

Returns The compiler command if found, or None if no compiler is found.

Used in codegen and build stages if the user didn't specify one explicitly.

The search order is:

  1. L0_CC environment variable. 2. Common compiler names in PATH: tcc, gcc, clang, cc (in that order). 3. CC environment variable.

l0c::_compiler_flag_family(str compiler) protected
compiler/stage1_py/l0c.py

Determine the compiler family for flag selection using a simple heuristic.

Parameters
compiler The compiler command string.
Returns A string representing the compiler family ("tcc", "gcc", "cc", "msvc", or "unknown").

Uses pattern matching to handle cases like "gcc-10" or "clang-14" on Unix and "gcc.exe" or "clang.exe" on Windows.

bool l0c::_is_windows_host() protected
compiler/stage1_py/l0c.py

Return whether the current Python host is Windows.

str l0c::_default_executable_name() protected
compiler/stage1_py/l0c.py

Return the default build output name for the current platform.

list[str] l0c::_runtime_include_flags(str flag_family, str runtime_include) protected
compiler/stage1_py/l0c.py

Return compiler-family-specific runtime include flags.

list[str] l0c::_runtime_library_flags(str flag_family, str runtime_lib) protected
compiler/stage1_py/l0c.py

Return compiler-family-specific runtime library search-path flags.

list[str] l0c::_output_flags(str flag_family, Path exe_path) protected
compiler/stage1_py/l0c.py

Return compiler-family-specific output flags.

Path l0c::_validated_temporary_directory() protected
compiler/stage1_py/l0c.py

Resolve and validate the host temporary directory.

Returns The resolved temporary directory.
Exceptions
OSError If the directory cannot be resolved or its POSIX hierarchy is not trusted.

POSIX temporary sources are safe to pass to an external compiler only when every component in the resolved directory hierarchy is owned by root or the effective user. Group- or other-writable components must also carry the sticky bit. Windows relies on the platform temporary directory ACL.

None l0c::_emit_temporary_source_cleanup_failure(Path c_path) protected
compiler/stage1_py/l0c.py

Report a compiler-temporary source retained after failed cleanup.

Parameters
c_path Retained temporary generated-C path.

bool l0c::_remove_temporary_c_source(Path c_path) protected
compiler/stage1_py/l0c.py

Remove a generated-C temporary and report retained recovery state.

Parameters
c_path Temporary generated-C path to remove.
Returns True when the path is absent after cleanup, otherwise False.

Path l0c::_write_temporary_c_source(str c_code) protected
compiler/stage1_py/l0c.py

Atomically create and write one anonymous generated-C source.

Parameters
c_code Generated C source text.
Returns The temporary source path, closed and ready for the host compiler.
Exceptions
OSError If the path cannot be created or written.

The returned descriptor reserves the path before any generated content is written. Writing through that descriptor avoids reopening an attacker- substituted path between selection and creation.

bool l0c::_check_entry_main_for_build(AnalysisResult result, str entry_name) protected
compiler/stage1_py/l0c.py

Check that the entry module defines a valid 'main' function for build/run.

Parameters
result The analysis result.
entry_name The name of the entry module.
Returns True if a valid 'main' function is found, False otherwise.

bool l0c::_validate_runtime_library_path(str runtime_lib_path) protected
compiler/stage1_py/l0c.py

Validate that the provided runtime library path exists and is a directory.

Parameters
runtime_lib_path Path to the runtime library directory.
Returns True if the path is a directory, False otherwise.

List[str] l0c::_split_c_options(Optional raw_options[str]) protected
compiler/stage1_py/l0c.py

Split a raw C options string into individual compiler arguments.

Parameters
raw_options Raw options string, or None.
Returns A list of whitespace-delimited compiler option tokens.

Optional[str] l0c::_get_optimize_flag(str flag_family, List extra_opts[str]) protected
compiler/stage1_py/l0c.py

Determine the appropriate optimization flag for the compiler family.

Parameters
flag_family The detected compiler family string.
extra_opts List of extra C compiler options.
Returns The optimization flag string (e.g., '-O1') or None if no suitable flag is found or if the user provided explicit optimization flags.

int l0c::_compile_generated_c(argparse.Namespace args, CompilationContext context, Path c_path, Path exe_path) protected
compiler/stage1_py/l0c.py

Invoke the selected host compiler for one generated-C source.

Parameters
args Parsed build arguments.
context Active compiler context.
c_path Closed generated-C source path.
exe_path Requested executable output path.
Returns Zero when the host compiler succeeds, otherwise one.

int l0c::cmd_build(argparse.Namespace args)
compiler/stage1_py/l0c.py

Build an executable from an L0 module.

Parameters
args Parsed command-line arguments.
Returns Exit code (0 for success, non-zero for failure).

int l0c::cmd_run(argparse.Namespace args)
compiler/stage1_py/l0c.py

Build and run an L0 module.

Parameters
args Parsed command-line arguments.
Returns Exit code from the executed program or the build process.

int l0c::cmd_codegen(argparse.Namespace args)
compiler/stage1_py/l0c.py

Generate C code for a module.

Parameters
args Parsed command-line arguments.
Returns Exit code (0 for success, non-zero for failure).

int l0c::cmd_check(argparse.Namespace args)
compiler/stage1_py/l0c.py

Run analysis and type checking without code generation.

Parameters
args Parsed command-line arguments.
Returns Exit code (0 for success, non-zero for failure).

int l0c::cmd_compile(argparse.Namespace args)
compiler/stage1_py/l0c.py

Report that separate compilation is not implemented in Stage 1 yet.

Parameters
args Parsed command-line arguments.
Returns Exit code 1.

int l0c::cmd_ast(argparse.Namespace args)
compiler/stage1_py/l0c.py

Pretty-print the parsed AST.

Parameters
args Parsed command-line arguments.
Returns Exit code (0 for success, non-zero for failure).

By default, prints only the entry module. With –all-modules, prints every module in the compilation unit.

str l0c::_format_token_dump_text(tok) protected
compiler/stage1_py/l0c.py

Return token payload text for --tok output.

int l0c::_dump_tokens_for_file(Path path, bool include_eof) protected
compiler/stage1_py/l0c.py

Dump lexer tokens for a single file.

Parameters
path Path to the source file.
include_eof Whether to include the EOF token in the output.
Returns Exit code (0 for success, non-zero for failure).

int l0c::cmd_tok(argparse.Namespace args)
compiler/stage1_py/l0c.py

Dump lexer tokens.

Parameters
args Parsed command-line arguments.
Returns Exit code (0 for success, non-zero for failure).

By default, dumps tokens for the entry module only. With –all-modules, dumps tokens for all modules in the compilation unit.

int l0c::cmd_sym(argparse.Namespace args)
compiler/stage1_py/l0c.py

Dump module-level symbol tables.

Parameters
args Parsed command-line arguments.
Returns Exit code (0 for success, non-zero for failure).

By default, dumps symbols only for the entry module. With –all-modules, dumps symbols for all modules in the compilation unit.

int l0c::cmd_type(argparse.Namespace args)
compiler/stage1_py/l0c.py

Dump resolved type information.

Parameters
args Parsed command-line arguments.
Returns Exit code (0 for success, non-zero for failure).

Dumps function signatures, struct field types, enum variant payloads, and type aliases.

None l0c::_add_target_args(argparse.ArgumentParser parser) protected
compiler/stage1_py/l0c.py

Add target module/file arguments to the parser.

Parameters
parser The argument parser to update.

None l0c::_add_all_modules_arg(argparse.ArgumentParser parser) protected
compiler/stage1_py/l0c.py

Add the –all-modules flag to the parser.

Parameters
parser The argument parser to update.

None l0c::_add_runtime_args(argparse.ArgumentParser parser) protected
compiler/stage1_py/l0c.py

Add runtime-related arguments to the parser.

Parameters
parser The argument parser to update.

None l0c::_add_codegen_arg(argparse.ArgumentParser parser) protected
compiler/stage1_py/l0c.py

Add codegen-related arguments to the parser.

Parameters
parser The argument parser to update.

Tuple[List[str], List[str], bool] l0c::_split_cli_and_program_args(Sequence argv[str]) protected
compiler/stage1_py/l0c.py

Split compiler CLI arguments from program arguments.

Parameters
argv The complete list of command-line arguments.
Returns A tuple of (compiler_args, program_args, separator_present).

List[str] l0c::_normalize_cli_argv(argparse.ArgumentParser parser, Sequence argv[str]) protected
compiler/stage1_py/l0c.py

Normalize exact short-option spellings before passing them to argparse.

Parameters
parser The argument parser for reporting errors.
argv Compiler arguments before the optional -- separator.
Returns A normalized compiler argument list.

Namespaced value options support a following value or =VALUE, but not a concatenated value. Canonical -I, -L, and -l options accept attached or following values, but not =VALUE. Only -v may form a cluster.

None l0c::_validate_mode_scoped_flags(argparse.ArgumentParser parser, argparse.Namespace args) protected
compiler/stage1_py/l0c.py

Reject flags that were provided for a mode where they are not valid.

Parameters
parser The argument parser for reporting errors.
args The parsed command-line arguments.

None l0c::_validate_reserved_canonical_flags(argparse.ArgumentParser parser, argparse.Namespace args) protected
compiler/stage1_py/l0c.py

Reject canonical compiler options whose behavior is not implemented.

Parameters
parser The argument parser for reporting errors.
args The parsed command-line arguments.

None l0c::main(Optional] argv[List[str] = None)
compiler/stage1_py/l0c.py

Parse CLI arguments, dispatch the selected mode, and exit.

Parameters
argv Optional list of arguments to parse. Defaults to sys.argv[1:].

Variable documentation