Script

This module implements a standard script interface that is easy to integrate into a build system.

`Option`

Bases: Enum

Optional features for Script class.

ATTRIBUTE	DESCRIPTION
`alignment`	Specify alignment with `-a`/`--alignment` and `--align` options.
`assembler_output`	Create assembler source file.
`assembler`	Collection to enable assembler-related options (section, assembler_output).
`binary_output`	Open output file in binary mode.
`defines`	Define preprocessor symbols with `-D` option.
`dyndep`	Enable dynamic dependency discovery with `--dyndep` and `--built-files` options.
`file_reader_preprocessor`	Enable preprocessing in FileReader.
`file_reader`	Use FileReader to read input files.
`include_directories`	Specify include directories with `-I` options.
`preprocessor`	Collection to enable preprocessor-related options (defines, file_reader, file_reader_preprocessor).
`runlength_encode`	Enable runlength encoding with `-r`/`--runlength` option.
`section`	Specify assembler section with `-s`/`--section` option.
`symbol_name`	Specify symbol name with `-n`/`--name` option.
`symbol`	Collection to enable symbol-related options (assembler, symbol_name, alignment).
`verbose`	Enable verbose output with `-v`/`--verbose` option.

`Script(description, *options)`

Bases: MessageHandler

Base class for scripts with standard interface.

PARAMETER	DESCRIPTION
`description`	Description of the script for the help message. TYPE: `str`
`options`	Optional features to enable. TYPE: `Option` DEFAULT: `()`

`assembler` `property`

Get assembler output object.

RETURNS	DESCRIPTION
`AssemblerOutput`	The assembler output object.

`dependencies` `property`

Get dependencies object.

RETURNS	DESCRIPTION
`Dependencies`	The dependencies object.

`file_reader` `property`

Get file reader object.

RETURNS	DESCRIPTION
`FileReader`	The file reader object.

`add_dependency(file)`

Add a file dependency.

This method is meant to be called by subclasses.

PARAMETER	DESCRIPTION
`file`	The dependency file. TYPE: `str`

`capture_exceptions(code)`

Run code and capture any exceptions as error messages.

Exceptions with empty messages are not reported as error messages but still mark the handler as failed.

PARAMETER	DESCRIPTION
`code`	The function to run. TYPE: `Callable[[], None]`

RETURNS	DESCRIPTION
`bool`	True if code ran without exceptions, False otherwise.

`default_output_extension()`

Get default filename extension for output files.

This method can be overridden by subclasses.

RETURNS	DESCRIPTION
`str`	The default filename extension.

`default_output_filename()`

Get default filename of final output file if not specified via -o command line option.

This method can be overridden by subclasses.

RETURNS	DESCRIPTION
`str`	The default output filename.

`error(message, file=None, position=None, position_end=None)`

Report an error and mark current script as failed.

PARAMETER	DESCRIPTION
`message`	The error message. TYPE: `str`
`file`	The file where the error occurred. TYPE: `str \| None` DEFAULT: `None`
`position`	The position in the file where the error occurred. TYPE: `Any` DEFAULT: `None`
`position_end`	The end position in the file where the error occurred. TYPE: `Any` DEFAULT: `None`

`error_from_exception(exception, omit_empty=False)`

Print message from exception.

If the exception is a FilePositionException, the file and position information will be used.

PARAMETER	DESCRIPTION
`exception`	The exception to print the message from. TYPE: `Exception`
`omit_empty`	Whether to omit messages with empty text. Handler will still be marked as failed. TYPE: `bool` DEFAULT: `False`

`execute_sub()`

Do actual processing.

This method must be implemented by subclasses.

`fail()`

Mark the message handler as failed.

`find_file(file)`

Find a file, searching the directory of the input file and include directories.

This method is meant to be called by subclasses.

PARAMETER	DESCRIPTION
`file`	Name of the file to find. TYPE: `str`

RETURNS	DESCRIPTION
`str`	The name of the found file.

RAISES	DESCRIPTION
`RuntimeError`	If the file is not found.

`find_optional_file(file)`

Find an optional file, searching the directory of the input file and include directories.

This method is meant to be called by subclasses.

PARAMETER	DESCRIPTION
`file`	Name of the file to find. TYPE: `str`

RETURNS	DESCRIPTION
`str \| None`	The name of the found file, or None if optional and the file is not found.

`get_dynamic_dependencies()`

Get list of dependencies for dynamic dependency discovery.

This method must be implemented by subclasses that use dynamic dependency discovery.

RETURNS	DESCRIPTION
`list[str]`	List of dependency filenames.

`has_failed()`

Check if the message handler has failed (errors reported).

RETURNS	DESCRIPTION
`bool`	True if the message handler has failed, False otherwise.

`info(message, file=None, position=None, position_end=None)`

Print informational message using current script.

PARAMETER	DESCRIPTION
`message`	Informational message. TYPE: `str`
`file`	The file where the message occurred. TYPE: `str \| None` DEFAULT: `None`
`position`	The position in the file where the message occurred. TYPE: `Any` DEFAULT: `None`
`position_end`	The end position in the file where the message occurred. TYPE: `Any` DEFAULT: `None`

`input_filename()`

Get filename of input file.

This method can be overridden by subclasses.

RETURNS	DESCRIPTION
`str \| None`	The input filename, or None if no input file is used.

`is_ok()`

Check if the message handler is ok (no errors reported).

RETURNS	DESCRIPTION
`bool`	True if the message handler is ok, False otherwise.

`natural_alignment()`

Get natural alignment for created object.

This method can be overridden by subclasses.

RETURNS	DESCRIPTION
`int \| None`	The natural alignment or None if not applicable.

`output_file()`

Get file object for output file.

This method is meant to be called by subclasses.

RETURNS	DESCRIPTION
`IO[Any]`	The output file object.

`output_file_name()`

Get filename of temporary output file.

This method is meant to be called by subclasses.

RETURNS	DESCRIPTION
`str`	The temporary output filename.

`output_filename()`

Get filename of final output file.

This method is meant to be called by subclasses.

RETURNS	DESCRIPTION
`str`	The output filename.

`prepare()`

Validate arguments and do other preparations. Run before output file is created.

This method can be overridden by subclasses.

`reset()`

Reset the message handler to ok.

`run()`

Run the script.

`symbol(binary, name_suffix='')`

Create assembler symbol for binary data.

This method is meant to be called by subclasses.

PARAMETER	DESCRIPTION
`binary`	The binary data. TYPE: `bytes`
`name_suffix`	Suffix to append to the symbol name. TYPE: `str` DEFAULT: `''`

`symbol_name()`

Get name of assembler symbol.

This method is meant to be called by subclasses.

RETURNS	DESCRIPTION
`str`	The symbol name.

`warning(message, file=None, position=None, position_end=None)`

Print warning using current script.

PARAMETER	DESCRIPTION
`message`	Warning message. TYPE: `str`
`file`	The file where the warning occurred. TYPE: `str \| None` DEFAULT: `None`
`position`	The position in the file where the warning occurred. TYPE: `Any` DEFAULT: `None`
`position_end`	The end position in the file where the warning occurred. TYPE: `Any` DEFAULT: `None`

Script

Option

Script(description, *options)

assembler property

dependencies property

file_reader property

add_dependency(file)

capture_exceptions(code)

default_output_extension()

default_output_filename()

error(message, file=None, position=None, position_end=None)

error_from_exception(exception, omit_empty=False)

execute_sub()

fail()

find_file(file)

find_optional_file(file)

get_dynamic_dependencies()

has_failed()

info(message, file=None, position=None, position_end=None)

input_filename()

is_ok()

natural_alignment()

output_file()

output_file_name()

output_filename()

prepare()

reset()

run()

symbol(binary, name_suffix='')

symbol_name()

warning(message, file=None, position=None, position_end=None)

`Option`

`Script(description, *options)`

`assembler` `property`

`dependencies` `property`

`file_reader` `property`

`add_dependency(file)`

`capture_exceptions(code)`

`default_output_extension()`

`default_output_filename()`

`error(message, file=None, position=None, position_end=None)`

`error_from_exception(exception, omit_empty=False)`

`execute_sub()`

`fail()`

`find_file(file)`

`find_optional_file(file)`

`get_dynamic_dependencies()`

`has_failed()`

`info(message, file=None, position=None, position_end=None)`

`input_filename()`

`is_ok()`

`natural_alignment()`

`output_file()`

`output_file_name()`

`output_filename()`

`prepare()`

`reset()`

`run()`

`symbol(binary, name_suffix='')`

`symbol_name()`

`warning(message, file=None, position=None, position_end=None)`