finesse.script.containers module

Token and production containers for use in the tokenizer and parser.

class finesse.script.containers.Addressable[source]

Bases: object

Mixin defining interface to retrieve strings containing script lines.

abstract property bounds[source]

Container bounds.

Getter:: KatBounds for this container.

script(bounds=None)[source]

Get the script in the interval [start, stop) defined by bounds.

Lines between start and stop with no tokens are yielded as empty lines. Gaps between the columns spanned by tokens on the same line are yielded as spaces.

Parameters

boundsKatBounds, optional: Bounds within which to retrieve script. Defaults to the whole script.

Returns

str: The script.

script_lines(bounds)[source]

The script within bounds by line.

Parameters

boundsKatBounds: The bounds to retrieve script between.

Returns

list: Lines within bounds. Where bounds starts or stops mid-way through a line, only the part of the line that falls within bounds is contained in the corresponding line.

property start[source]

Start coordinate.

Getter:: The start KatCoordinate.

property stop[source]

Stop coordinate.

Getter:: The stop KatCoordinate.

class finesse.script.containers.ArgumentContainer(arguments: List[TokenContainer])[source]

Bases: TokenContainer

Mixin for containers that contain arguments.

arguments: List[TokenContainer]

property tokens[source]

Tokens contained in the container.

Getter:: list of KatToken objects within this container.

class finesse.script.containers.BaseCustomToken(lineno: int, start_index: int, stop_index: int, type: str, raw_value: Any)[source]

Bases: KatToken

A custom token.

class finesse.script.containers.ExtraTokenContainer(extra: List[KatToken])[source]

Bases: TokenContainer

Mixin for containers that contain extra tokens.

extra: List[KatToken]

property tokens[source]

Tokens contained in the container.

Getter:: list of KatToken objects within this container.

class finesse.script.containers.KatArray(extra: List[KatToken], arguments: List[TokenContainer])[source]

Bases: ArgumentContainer, ExtraTokenContainer, TokenContainer

Represents a kat script array.

class finesse.script.containers.KatBooleanToken(lineno: int, start_index: int, stop_index: int, type: str, raw_value: Any)[source]

Bases: BaseCustomToken

A boolean token.

property value[source]

class finesse.script.containers.KatBounds(start: KatCoordinate, stop: KatCoordinate)[source]

Bases: object

Kat script start and stop bounds.

This represents a block of text in a kat script file.

isempty()[source]

Whether the contents contained within the bounds is empty.

Returns

bool: True if empty, False otherwise.

lcontract(newstart)[source]

Contract start boundary.

Parameters

newstartKatCoordinate: The new start coordinate.

Returns

KatBounds: The contracted bounds.

Raises

ValueError: If newstart is not >= current start coordinate.

lexpand(newstart)[source]

Expand start boundary.

Parameters

newstartKatCoordinate: The new start coordinate.

Returns

KatBounds: The expanded bounds.

Raises

ValueError: If newstart is not <= current start coordinate.

rcontract(newstop)[source]

Contract stop boundary.

Parameters

newstopKatCoordinate: The new stop coordinate.

Returns

KatBounds: The contracted bounds.

Raises

ValueError: If newstop is not <= current stop coordinate.

rexpand(newstop)[source]

Expand stop boundary.

Parameters

newstopKatCoordinate: The new stop coordinate.

Returns

KatBounds: The expanded bounds.

Raises

ValueError: If newstop is not >= current stop coordinate.

start: KatCoordinate

stop: KatCoordinate

class finesse.script.containers.KatCoordinate(lineno: int, index: int)[source]

Bases: object

Kat script file coordinate supporting comparison operations.

compact()[source]

Compact coordinate representation.

Returns

str: Compact coordinates.

index: int

lineno: int

class finesse.script.containers.KatElement(directive: KatToken, extra: List[KatToken], arguments: List[TokenContainer], name: KatToken)[source]

Bases: ArgumentContainer, ExtraTokenContainer, KatScriptItem

Represents a parsed element statement and any corresponding arguments.

missing_argument_meta_token()[source]

A meta token at one position after that of the last argument token.

This is used to create error markers pointing to the location of missing parameters.

name: KatToken

property node_name[source]

property tokens[source]

Tokens contained in the container.

Getter:: list of KatToken objects within this container.

property unique_name_token[source]

class finesse.script.containers.KatExpression(extra: List[KatToken], arguments: List[TokenContainer], operator: KatToken)[source]

Bases: ArgumentContainer, ExtraTokenContainer, TokenContainer

Represents a kat script expression.

property lhs[source]

operator: KatToken

property rhs[source]

property tokens[source]

Tokens contained in the container.

Getter:: list of KatToken objects within this container.

class finesse.script.containers.KatFile(text: str)[source]

Bases: Addressable

Container with kat script lines (no concrete tokens).

add(string)[source]

Add string to end of file.

Parameters

stringstr: The string to add to the end of the file.

property bounds[source]

Container bounds.

Getter:: KatBounds for this container.

text: str

class finesse.script.containers.KatFixMeToken(lineno: int, start_index: int, stop_index: int, type: str, raw_value: Any)[source]

Bases: BaseCustomToken

A “fixme” token used by the unparser to represent an invalid value.

property value[source]

class finesse.script.containers.KatFunction(directive: KatToken, extra: List[KatToken], arguments: List[TokenContainer])[source]

Bases: ArgumentContainer, ExtraTokenContainer, KatScriptItem

Represents a parsed kat function statement and any corresponding arguments.

missing_argument_meta_token()[source]

A meta token at one position after that of the last argument token.

This is used to create error markers pointing to the location of missing parameters.

property name[source]

The token that represents the function name.

This is used by the error handler for invalid keyword arguments, for example.

property node_name[source]

property unique_name_token[source]

class finesse.script.containers.KatGroupedExpression(extra: List[KatToken], arguments: List[TokenContainer])[source]

Bases: ArgumentContainer, ExtraTokenContainer, TokenContainer

Represents a kat script expression group, i.e. (<expression>).

property expression[source]

class finesse.script.containers.KatKwarg(key: KatToken, equals: KatToken, value: KatToken | KatFunction | KatExpression | KatGroupedExpression | KatArray)[source]

Bases: TokenContainer

Represents a kat argument containing a key, value and ‘=’.

equals: KatToken

key: KatToken

property tokens[source]

Tokens contained in the container.

Getter:: list of KatToken objects within this container.

value: KatToken | KatFunction | KatExpression | KatGroupedExpression | KatArray

class finesse.script.containers.KatMetaToken(lineno: int, start_index: int, stop_index: int, type: str)[source]

Bases: TokenMixin

A token that may not map to a real token.

Meta tokens are employed by KatTokenizer when converting whitespace and newline tokens used as delimiters into DELIMITER. The use of a single meta token for DELIMITER in this case simplifies the parser rules.

By definition, the value of a meta token does not matter so the class doesn’t support having one. Similarly, to help prevent bugs, an exception is raised if the token is attempted to be displayed.

class finesse.script.containers.KatNoneToken(lineno: int, start_index: int, stop_index: int, type: str, raw_value: Any)[source]

Bases: BaseCustomToken

A null token.

property value[source]

class finesse.script.containers.KatNumberToken(lineno: int, start_index: int, stop_index: int, type: str, raw_value: Any)[source]

Bases: BaseCustomToken

A number token.

SI_NUMBER_PATTERN = re.compile('.*[pnumkMGT]$')

property value[source]

class finesse.script.containers.KatNumericalArray(extra: List[KatToken], arguments: List[TokenContainer])[source]

Bases: KatArray

Represents a kat script numerical array.

classmethod from_array(array)[source]: Convert array to numerical array.

class finesse.script.containers.KatScript(extra: List[KatToken], arguments: List[TokenContainer])[source]

Bases: ArgumentContainer, ExtraTokenContainer, TokenContainer

Represents a kat script.

class finesse.script.containers.KatScriptItem(directive: KatToken)[source]

Bases: TokenContainer

Represents a top level kat script item.

directive: KatToken

abstractmethod missing_argument_meta_token()[source]

A meta token at one position after that of the last argument token.

This is used to create error markers pointing to the location of missing parameters.

abstract property node_name[source]

property tokens[source]

Tokens contained in the container.

Getter:: list of KatToken objects within this container.

abstract property unique_name_token[source]

class finesse.script.containers.KatStringToken(lineno: int, start_index: int, stop_index: int, type: str, raw_value: Any)[source]

Bases: BaseCustomToken

A string token.

property value[source]

class finesse.script.containers.KatToken(lineno: int, start_index: int, stop_index: int, type: str, raw_value: Any)[source]

Bases: TokenMixin

A real token with the corresponding text’s location, type and value.

property display_value[source]

raw_value: Any

to_meta()[source]

Convert token to a meta token.

Returns

KatMetaToken: The current token, as a meta token.

to_new_position(start)[source]

Copy token, updating its start (and stop) position.

Parameters

startKatCoordinate: The token’s new start position.

Returns

KatToken: New copy of self, with updated start position.

property value[source]

classmethod with_new_type(tok, new_type)[source]

Convert token to a different type.

Parameters

tokKatToken: The token to convert.
new_typestr: The new token type.

Returns

KatToken: The kat token, copied from tok, with type new_type.

class finesse.script.containers.KatWhitespaceToken(lineno: int, start_index: int, stop_index: int, type: str, raw_value: Any)[source]

Bases: BaseCustomToken

A whitespace token.

property display_value[source]

class finesse.script.containers.TokenContainer[source]

Bases: Addressable

Container with concrete token instances.

property bounds[source]

Container bounds.

Getter:: KatBounds for this container.

property first_token[source]

First container token by coordinate.

Getter:: first KatToken within this container.

property last_token[source]

Last container token by coordinate.

Getter:: last KatToken within this container.

property sorted_tokens[source]

Tokens contained in the container, in ascending coordinate order.

Getter:: sorted list of KatToken objects within this container.

abstract property tokens[source]

Tokens contained in the container.

Getter:: list of KatToken objects within this container.

class finesse.script.containers.TokenMixin(lineno: int, start_index: int, stop_index: int, type: str)[source]

Bases: TokenContainer

A class that provides functionality shared by KatMetaToken and KatToken.

Injected this way to prevent KatToken inheriting from KatMetaToken, which would be confusing since they are both tokens, but one represent real tokens while the other does not.

property bounds[source]

Container bounds.

Getter:: KatBounds for this container.

lineno: int

start_index: int

stop_index: int

property tokens[source]

Tokens contained in the container.

Getter:: list of KatToken objects within this container.

type: str