l0c.py
Module: l0c
Source: compiler/stage1_py/l0c.py Language: Python
Symbols
Namespace l0c
Variable l0c._CLI_LONG_VALUE_OPTIONS
1
dict l0c._CLI_LONG_VALUE_OPTIONS
Variable l0c._CLI_NAMESPACED_SHORT_VALUE_OPTIONS
1
dict l0c._CLI_NAMESPACED_SHORT_VALUE_OPTIONS
Variable l0c._CLI_CANONICAL_SHORT_VALUE_OPTIONS
1
dict l0c._CLI_CANONICAL_SHORT_VALUE_OPTIONS
Variable l0c._CLI_OTHER_SHORT_VALUE_OPTIONS
1
dict l0c._CLI_OTHER_SHORT_VALUE_OPTIONS
Variable l0c._CLI_VALUE_OPTIONS
1
tuple l0c._CLI_VALUE_OPTIONS
Function l0c.compiler_identity_text
1
str l0c.compiler_identity_text()
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.
Function l0c._scan_cli_presentation_options
1
Tuple[int, bool] l0c._scan_cli_presentation_options(Sequence[str] argv)
Return fallback verbosity and rich-log settings before – .
Values following value-taking options are skipped even when they resemble presentation flags, matching the normalization grammar used for parsing.
Parameters:
argv: The complete list of command-line arguments.
Returns: A tuple of (verbosity count, rich-log enabled).
Function l0c._emit_verbose_compiler_identity
1
None l0c._emit_verbose_compiler_identity(argparse.Namespace args)
Emit the compiler identity through the normal verbose logging path.
Function l0c._init_env_defaults
1
None l0c._init_env_defaults()
Initialize default environment variables based on L0_HOME.
Function l0c._load_file_lines
1
List[str] l0c._load_file_lines(str path, Dict[str, List[str]] cache)
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.
Function l0c._emit_diagnostic
1
None l0c._emit_diagnostic(str message)
Write one normative compiler diagnostic line to standard error.
Parameters:
message: Diagnostic text without a trailing newline.Function
l0c.print_diagnostics
1
None l0c.print_diagnostics(AnalysisResult result)
Print diagnostics from the analysis result.
Parameters:
1
None l0c.print_diagnostic_list(List[Diagnostic] diagnostics)
Print a list of diagnostics, using a file cache for source snippets.
Parameters:
1
None l0c.print_diagnostic_with_snippet(Diagnostic diag, Dict[str, List[str]] file_cache)
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.Function
l0c._is_valid_module_name
1
bool l0c._is_valid_module_name(str module_name)
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.
Function l0c.build_search_paths
1
Optional[SourceSearchPaths] l0c.build_search_paths(CompilationContext context, argparse.Namespace args)
Build source search paths from command-line arguments.
Handles entry path parsing and default values from environment variables.
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.
Function l0c.build_compilation_context
1
CompilationContext l0c.build_compilation_context(argparse.Namespace args)
Build a CompilationContext from command-line arguments.
Parameters:
args: Parsed command-line arguments.
Returns: A new CompilationContext configured based on arguments.
Function l0c._run_analysis
1
l0c._run_analysis(argparse.Namespace args)
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.
Function l0c._get_module_names
1
List[str] l0c._get_module_names(argparse.Namespace args, CompilationUnit cu)
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.
Function l0c._find_cc
1
Optional[str] l0c._find_cc()
Find the best available C compiler.
Used in codegen and build stages if the user didn’t specify one explicitly.
The search order is:
- L0_CC environment variable. 2. Common compiler names in PATH: tcc, gcc, clang, cc (in that order). 3. CC environment variable.
Returns: The compiler command if found, or None if no compiler is found.
Function l0c._compiler_flag_family
1
l0c._compiler_flag_family(str compiler)
Determine the compiler family for flag selection using a simple heuristic.
Uses pattern matching to handle cases like “gcc-10” or “clang-14” on Unix and “gcc.exe” or “clang.exe” on Windows.
Parameters:
compiler: The compiler command string.
Returns: A string representing the compiler family (“tcc”, “gcc”, “cc”, “msvc”, or “unknown”).
Function l0c._is_windows_host
1
bool l0c._is_windows_host()
Return whether the current Python host is Windows.
Function l0c._default_executable_name
1
str l0c._default_executable_name()
Return the default build output name for the current platform.
Function l0c._runtime_include_flags
1
list[str] l0c._runtime_include_flags(str flag_family, str runtime_include)
Return compiler-family-specific runtime include flags.
Function l0c._runtime_library_flags
1
list[str] l0c._runtime_library_flags(str flag_family, str runtime_lib)
Return compiler-family-specific runtime library search-path flags.
Function l0c._output_flags
1
list[str] l0c._output_flags(str flag_family, Path exe_path)
Return compiler-family-specific output flags.
Function l0c._validated_temporary_directory
1
Path l0c._validated_temporary_directory()
Resolve and validate the host temporary directory.
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.
Returns: The resolved temporary directory.
Function l0c._emit_temporary_source_cleanup_failure
1
None l0c._emit_temporary_source_cleanup_failure(Path c_path)
Report a compiler-temporary source retained after failed cleanup.
Parameters:
1
bool l0c._remove_temporary_c_source(Path c_path)
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.
Function l0c._write_temporary_c_source
1
Path l0c._write_temporary_c_source(str c_code)
Atomically create and write one anonymous generated-C source.
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.
Parameters:
c_code: Generated C source text.
Returns: The temporary source path, closed and ready for the host compiler.
Function l0c._check_entry_main_for_build
1
bool l0c._check_entry_main_for_build(AnalysisResult result, str entry_name)
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.
Function l0c._validate_runtime_library_path
1
bool l0c._validate_runtime_library_path(str runtime_lib_path)
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.
Function l0c._split_c_options
1
List[str] l0c._split_c_options(Optional[str] raw_options)
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.
Function l0c._get_optimize_flag
1
Optional[str] l0c._get_optimize_flag(str flag_family, List[str] extra_opts)
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.
Function l0c._compile_generated_c
1
int l0c._compile_generated_c(argparse.Namespace args, CompilationContext context, Path c_path, Path exe_path)
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.
Function l0c.cmd_build
1
int l0c.cmd_build(argparse.Namespace args)
Build an executable from an L0 module.
Parameters:
args: Parsed command-line arguments.
Returns: Exit code (0 for success, non-zero for failure).
Function l0c.cmd_run
1
int l0c.cmd_run(argparse.Namespace args)
Build and run an L0 module.
Parameters:
args: Parsed command-line arguments.
Returns: Exit code from the executed program or the build process.
Function l0c.cmd_codegen
1
int l0c.cmd_codegen(argparse.Namespace args)
Generate C code for a module.
Parameters:
args: Parsed command-line arguments.
Returns: Exit code (0 for success, non-zero for failure).
Function l0c.cmd_check
1
int l0c.cmd_check(argparse.Namespace args)
Run analysis and type checking without code generation.
Parameters:
args: Parsed command-line arguments.
Returns: Exit code (0 for success, non-zero for failure).
Function l0c.cmd_compile
1
int l0c.cmd_compile(argparse.Namespace args)
Report that separate compilation is not implemented in Stage 1 yet.
Parameters:
args: Parsed command-line arguments.
Returns: Exit code 1.
Function l0c.cmd_ast
1
int l0c.cmd_ast(argparse.Namespace args)
Pretty-print the parsed AST.
By default, prints only the entry module. With all-modules, prints every module in the compilation unit.
Parameters:
args: Parsed command-line arguments.
Returns: Exit code (0 for success, non-zero for failure).
Function l0c._format_token_dump_text
1
str l0c._format_token_dump_text(tok)
Return token payload text for –tok output.
Function l0c._dump_tokens_for_file
1
int l0c._dump_tokens_for_file(Path path, bool include_eof)
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).
Function l0c.cmd_tok
1
int l0c.cmd_tok(argparse.Namespace args)
Dump lexer tokens.
By default, dumps tokens for the entry module only. With all-modules, dumps tokens for all modules in the compilation unit.
Parameters:
args: Parsed command-line arguments.
Returns: Exit code (0 for success, non-zero for failure).
Function l0c.cmd_sym
1
int l0c.cmd_sym(argparse.Namespace args)
Dump module-level symbol tables.
By default, dumps symbols only for the entry module. With all-modules, dumps symbols for all modules in the compilation unit.
Parameters:
args: Parsed command-line arguments.
Returns: Exit code (0 for success, non-zero for failure).
Function l0c.cmd_type
1
int l0c.cmd_type(argparse.Namespace args)
Dump resolved type information.
Dumps function signatures, struct field types, enum variant payloads, and type aliases.
Parameters:
args: Parsed command-line arguments.
Returns: Exit code (0 for success, non-zero for failure).
Function l0c._add_target_args
1
None l0c._add_target_args(argparse.ArgumentParser parser)
Add target module/file arguments to the parser.
Parameters:
1
None l0c._add_all_modules_arg(argparse.ArgumentParser parser)
Add the all-modules flag to the parser.
Parameters:
1
None l0c._add_runtime_args(argparse.ArgumentParser parser)
Add runtime-related arguments to the parser.
Parameters:
1
None l0c._add_codegen_arg(argparse.ArgumentParser parser)
Add codegen-related arguments to the parser.
Parameters:
1
Tuple[List[str], List[str], bool] l0c._split_cli_and_program_args(Sequence[str] argv)
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).
Function l0c._normalize_cli_argv
1
List[str] l0c._normalize_cli_argv(argparse.ArgumentParser parser, Sequence[str] argv)
Normalize exact short-option spellings before passing them to argparse.
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.
Parameters:
parser: The argument parser for reporting errors.argv: Compiler arguments before the optional--separator.
Returns: A normalized compiler argument list.
Function l0c._validate_mode_scoped_flags
1
None l0c._validate_mode_scoped_flags(argparse.ArgumentParser parser, argparse.Namespace args)
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.Function
l0c._validate_reserved_canonical_flags
1
None l0c._validate_reserved_canonical_flags(argparse.ArgumentParser parser, argparse.Namespace args)
Reject canonical compiler options whose behavior is not implemented.
Parameters:
parser: The argument parser for reporting errors.args: The parsed command-line arguments.Function
l0c.main
1
None l0c.main(Optional[List[str]] argv=None)
Parse CLI arguments, dispatch the selected mode, and exit.
Parameters:
argv: Optional list of arguments to parse. Defaults to sys.argv[1:].
Class l0c::_TemporarySourceWriteError
Report a generated-C write failure that also retained its path.
Member Data l0c._TemporarySourceWriteError.retained_path
1
l0c._TemporarySourceWriteError::retained_path
Function l0c._TemporarySourceWriteError.__init__
1
l0c._TemporarySourceWriteError.__init__(self, Path retained_path)
Initialize the failure.
Parameters:
retained_path: Temporary generated-C path that could not be removed.