AST¶

Root class¶

class trlc.ast.Node(location)¶

Bases: object

Base class for all AST items.

Attribute location:: source location
Type:: Location

abstract dump(indent=0)¶

Visualise the parse tree.

This can be called for any Node or Symbol_Table, and can be very helpful for debugging or understanding the parse tree. The dump methods will produce output like this:

Symbol_Table
   Builtin_Boolean
   Builtin_Integer
   Builtin_Decimal
   Builtin_String
   Builtin_Markup_String
   Package bar
      Symbol_Table
         Record_Type MyType
            Composite_Component name
               Optional: False
               Type: String
            Checks
               Error 'description is too short'
                  Anchor: description
                  Binary Binary_Operator.COMP_GT Expression
                     Type: Boolean
                     Unary Unary_Operator.STRING_LENGTH Expression
                        Type: Integer
                        Name Reference to description
                     Integer Literal 10
   Package instances
      Symbol_Table
         Record_Object SomeThing
            Type: MyType
            Field description: "Potato"
   Builtin_Function endswith
   Builtin_Function len
   Builtin_Function matches
   Builtin_Function startswith
   Builtin_Function oneof

Entities¶

class trlc.ast.Entity(name, location)¶

Bases: Node

Base class for all entities.

An entity is a concrete object (with a name) for which we need to allocate memory. Examples of entities are types and record objects.

Attribute name:: unqualified name of the entity
Type:: str

class trlc.ast.Builtin_Function(name, arity, arity_at_least=False)¶

Bases: Entity

Builtin functions.

These are auto-generated by the Source_Manager.

Attribute arity:: number of parameters
Type:: int
Attribute arity_at_least:: when true, arity indicates a lower bound
Type:: bool

class trlc.ast.Package(name, location, builtin_stab, declared_late)¶

Bases: Entity

Packages.

A package is declared when it is first encountered (in either a rsl or trlc file). A package contains all symbols declared in it, both types and record objects. A package is not associated with just a single file, it can be spread over multiple files.

Attribute declared_late:: indicates if this package is declared in a trlc file
Type:: bool
Attribute symbols:: symbol table of the package
Type:: Symbol_Table

class trlc.ast.Section(name, location, parent)¶

Bases: Entity

A section for readability

This represents a section construct in TRLC files to group record objects together:

section "Foo" {
        ^^^^^ parent section
   section "Bar" {
           ^^^^^ section

Attribute parent:: the parent section or None
Type:: Section

class trlc.ast.Typed_Entity(name, location, n_typ)¶

Bases: Entity

Base class for entities with a type.

A typed entity is a concrete object (with a name and TRLC type) for which we need to allocate memory. Examples of typed entities are record objects and components.

Attribute n_typ:: type of the entity
Type:: Type

class trlc.ast.Quantified_Variable(name, location, n_typ)¶

Bases: Typed_Entity

Variable used in quantified expression.

A quantified expression declares and binds a variable, for which we need a named entity. For example in:

(forall x in array => x > 1)
        ^

We represent this first x as a Quantified_Variable, the second x will be an ordinary Name_Reference.

Attribute typ:: type of the variable (i.e. element type of the array)
Type:: Type

class trlc.ast.Composite_Component(name, description, location, member_of, n_typ, optional)¶

Bases: Typed_Entity

Component in a record or tuple.

When declaring a composite type, for each component an entity is declared:

type|tuple T {
   foo "blah" optional Boolean
   ^1  ^2     ^3       ^4

Attribute description:: optional text (see 2) for this component, or None
Type:: str
Attribute member_of:: a link back to the containing record or tuple; for inherited fields this refers back to the original base record type
Type:: Composite_Type
Attribute optional:: indicates if the component can be null or not (see 3)
Type:: bool

class trlc.ast.Enumeration_Literal_Spec(name, description, location, enum)¶

Bases: Typed_Entity

Declared literal in an enumeration declaration.

Note that for literals mentioned later in record object declarations, we use Enumeration_Literal. Literal specs are used here:

enum ASIL {
   QM "not safety related"
   ^1 ^2

Attribute description:: the optional user-supplied description, or None
Type:: str

class trlc.ast.Record_Object(name, location, n_typ, section, n_package)¶

Bases: Typed_Entity

A declared instance of a record type.

This is going to be the bulk of all entities created by TRLC:

section "Potato" {
        ^5
  Requirement PotatoReq {
  ^1          ^2
      component1 = 42
      ^3           ^4

Note that the name (see 2) and type (see 1) of the object is provided by the name attribute of the Typed_Entity base class.

Attribute field:: the specific values for all components (see 3 and 4)
Type:: dict[str, Expression]
Attribute section:: None or the section this record is contained in (see 5)
Type:: Section
Attribute n_package:: The package in which this record is declared in
Type:: Section

The actual type of expressions in the field attribute are limited to:

Literal
Unary_Expression
Array_Aggregate
Tuple_Aggregate
Record_Reference
Implicit_Null

fully_qualified_name()¶

Return the FQN for this type (i.e. PACKAGE.NAME)

Returns:: the object’s full name
Return type:: str

to_python_dict()¶

Return an evaluated and simplified object for Python.

For example it might provide:

{"foo" : [1, 2, 3],
 "bar" : None,
 "baz" : "value"}

This is a function especially designed for the Python API. The name of the object itself is not in this returned dictionary.

Miscellaneous¶

class trlc.ast.Compilation_Unit(file_name)¶

Bases: Node

Special node to represent the concrete file structure

Attribute package:: the main package this file declares or contributes to
Type:: Package
Attribute imports:: package imported by this file
Type:: list[Package]
Attribute items:: list of
Type:: list[Node]

class trlc.ast.Check_Block(location, n_typ)¶

Bases: Node

Node representing check blocks

Semantically this has no meaning, but it’s nice to have some kind of similar representation to how it’s in the file.

Attribute n_typ:: composite type for which the checks apply
Type:: Composite_Type
Attribute checks:: list of checks
Type:: list[Check]

class trlc.ast.Check(n_type, n_expr, n_anchor, severity, t_message, extrainfo)¶

Bases: Node

User defined check

This represent a single user-defined check inside a check block:

checks T {
    a /= null implies a > 5, warning "potato", a
    ^^^^^^^^^^^^^^^^^^^^^^^1 ^2      ^3        ^4

Attribute n_type:: The tuple/record type this check applies to
Type:: Composite_Type
Attribute n_expr:: The boolean expression for the check (see 1)
Type:: Expression
Attribute n_anchor:: The (optional) record component where the message should be issued (or None) (see 4)
Type:: Composite_Component
Attribute severity:: warning, error, or fatal (see 2; also if this is not specified the default is ‘error’)
Type:: str
Attribute message:: the user-supplied message (see 3)
Type:: str

class trlc.ast.Separator(token)¶

Bases: Node

User-defined syntactic separator

For example:

separator x
          ^1

Attribute token:: token used to separate fields of the tuple
Type:: Token

Types¶

class trlc.ast.Type(name, location)¶

Bases: Entity

Abstract base class for all types.

class trlc.ast.Concrete_Type(name, location, n_package)¶

Bases: Type

Abstract base class for all non-anonymous types.

Attribute n_package:: package where this type was declared
Type:: Package

fully_qualified_name()¶

Return the FQN for this type (i.e. PACKAGE.NAME)

Returns:: the type’s full name
Return type:: str

class trlc.ast.Builtin_Type(name)¶

Bases: Type

Abstract base class for all builtin types.

class trlc.ast.Array_Type(location, element_type, loc_lower, lower_bound, loc_upper, upper_bound)¶

Bases: Type

Anonymous array type.

These are declared implicitly for each record component that has an array specifier:

foo Integer [5 .. *]
            ^

Attribute lower_bound:: minimum number of elements
Type:: int
Attribute loc_lower:: text location of the lower bound indicator
Type:: Location
Attribute upper_bound:: maximum number of elements (or None)
Type:: int
Attribute loc_upper:: text location of the upper bound indicator
Type:: Location
Attribute element_type:: type of the array elements
Type:: Type

class trlc.ast.Builtin_Numeric_Type(name)¶

Bases: Builtin_Type

Abstract base class for all builtin numeric types.

class trlc.ast.Builtin_Integer¶

Bases: Builtin_Numeric_Type

Builtin integer type.

class trlc.ast.Builtin_Decimal¶

Bases: Builtin_Numeric_Type

Builtin decimal type.

class trlc.ast.Builtin_String¶

Bases: Builtin_Type

Builtin string type.

class trlc.ast.Builtin_Boolean¶

Bases: Builtin_Type

Builtin boolean type.

class trlc.ast.Composite_Type(name, description, location, package, inherited_symbols=None)¶

Bases: Concrete_Type

Abstract base for record and tuple types, as they share some: functionality.

Attribute components:: type components (including inherited if applicable)
Type:: Symbol_Table[Composite_Component]
Attribute description:: user-supplied description of the type or None
Type:: str
Attribute checks:: used-defined checks for this type (excluding inherited checks)
Type:: list[Check]

all_components()¶

Convenience function to get a list of all components.

Return type:: list[Composite_Component]

class trlc.ast.Record_Type(name, description, location, package, n_parent, is_abstract)¶

Bases: Composite_Type

A user-defined record type.

In this example:

type T  "optional description of T" extends Root_T {
     ^1 ^2                                  ^3

Note that (1) is part of the Entity base, and (2) is part of the Composite_Type base.

Attribute parent:: root type or None, indicated by (3) above
Type:: Record_Type
Attribute frozen:: mapping of frozen components
Type:: dict[str, Expression]
Attribute is_final:: type is final (i.e. no new components may be declared)
Type:: bool
Attribute is_abstract:: type is abstract
Type:: bool

all_components()¶

Convenience function to get a list of all components.

Return type:: list[Composite_Component]

get_freezing_expression(n_component)¶

Retrieve the frozen value for a frozen component

It is an internal compiler error to call this method with a component that his not frozen.

Parameters:: n_component (Composite_Component) – a frozen component of this record type (or any of its parents)
Return type:: Expression

is_frozen(n_component)¶

Test if the given component is frozen.

Parameters:: n_component (Composite_Component) – a composite component of this record type (or any of its parents)
Return type:: bool

is_subclass_of(record_type)¶

Checks if this record type is or inherits from the given type

Parameters:: record_type (Record_Type) – check if are or extend this type
Returns:: true if we are or extend the given type
Return type:: Boolean

class trlc.ast.Tuple_Type(name, description, location, package)¶

Bases: Composite_Type

A user-defined tuple type.

In this example:

tuple T  "optional description of T" {
      ^1 ^2

Note that (1) is part of the Entity base, and (2) is part of the Composite_Type base.

Attribute separators:: list of syntactic separators.
Type:: list[Separator]

Note the list of separators will either be empty, or there will be precisely one less separator than components.

has_separators()¶: Returns true if a tuple type requires separators

iter_separators()¶: Iterate over all separators

iter_sequence()¶: Iterate over all components and separators in syntactic order

class trlc.ast.Enumeration_Type(name, description, location, package)¶

Bases: Concrete_Type

User-defined enumeration types.

For example:

enum T  "potato" {
     ^1 ^2

Attribute description:: user supplied optional description, or None
Type:: str
Attribute literals:: the literals in this enumeration
Type:: Symbol_Table[Enumeration_Literal_Spec]

Expressions¶

class trlc.ast.Expression(location, typ)¶

Bases: Node

Abstract base class for all expressions.

Attribute typ:: The type of this expression (or None for null values)
Type:: Type

abstract can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

evaluate(mh, context)¶

Evaluate the expression in the given context

The context can be None, in which case the expression is evaluated in a static context. Otherwise it must be a dictionary that maps names (such as record fields or quantified variables) to expressions.

Parameters:

mh (Message_Handler) – the message handler to use
context (dict[str, Expression]) – name mapping or None (for a static context)

Raises:

TRLC_Error – if the expression cannot be evaluated

Returns:

result of the evaluation

Return type:

Value

class trlc.ast.Implicit_Null(composite_object, composite_component)¶

Bases: Expression

Synthesised null values

When a record object or tuple aggregate is declared and an optional component or field is not specified, we synthesise an implicit null expression for this.

For example given this TRLC type:

type T {
   x optional Integer
}

And this declaration:

T Potato {}

Then the field mapping for Potato will be:

{x: Implicit_Null}

Each field will get its own implicit null. Further note that this implicit null is distinct from the explicit Null_Literal that can appear in check expressions.

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Array_Aggregate(location, typ)¶

Bases: Expression

Instances of array types

This is created when assigning to array components:

potatoes = ["picasso", "yukon gold", "sweet"]
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The type of expression that can be found in an array is somewhat limited:

Literal
Array_Aggregate
Record_Reference

Attribute value:: contents of the array
Type:: list[Expression]

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Tuple_Aggregate(location, typ)¶

Bases: Expression

Instances of a tuple

This is created when assigning to a tuple components. There are two forms, the ordinary form:

coordinate = (12.3, 40.0)
             ^^^^^^^^^^^^

And the separator form:

item = 12345@42
       ^^^^^^^^

In terms of AST there is no difference, as the separator is only syntactic sugar.

Attribute value:: contents of the tuple
Type:: dict[str, Expression]

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Record_Reference(location, name, typ, package)¶

Bases: Expression

Reference to another record object

This can appear in record object declarations:

Requirement Kitten {
    depends_on = Other_Package.Cat
                 ^1            ^2
}

Note that this is distinct from Record_Object. It is just the name; to get to the object referred to by this you can consult the target attribute.

The reason we have this indirection is that not all names can be immediately resolved on parsing in the TRLC language.

Note that while the containing package (see 1) is optional in the source language, the containing package will always be filled in in this AST node.

Attribute name:: The name of the record (see 2)
Type:: str
Attribute target:: The concrete record object referred to by (2)
Type:: Record_Object
Attribute package:: The package (see 1) supposed to contain (2)
Type:: Package

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Name_Reference(location, entity)¶

Bases: Expression

Reference to a name

Name reference to either a Composite_Component or a Quantified_Variable. The actual value of course depends on the context. See Expression.evaluate().

For example:

(forall x in potato => x > 1)
             ^1        ^2

Both indicated parts are a Name_Reference, the first one refers to a Composite_Component, and the second refers to a Quantified_Variable.

Attribute entity:: the entity named here
Type:: Composite_Component, Quantified_Variable

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Unary_Expression(mh, location, typ, operator, n_operand)¶

Bases: Expression

Expression with only one operand

This captures the following operations:

Unary_Operator.PLUS (e.g. +5)
Unary_Operator.MINUS (e.g. -5)
Unary_Operator.ABSOLUTE_VALUE (e.g. abs 42)
Unary_Operator.LOGICAL_NOT (e.g. not True)
Unary_Operator.STRING_LENGTH (e.g. len("foobar"))
Unary_Operator.ARRAY_LENGTH (e.g. len(component_name))
Unary_Operator.CONVERSION_TO_INT (e.g. Integer(5.3))
Unary_Operator.CONVERSION_TO_DECIMAL (e.g. Decimal(5))

Note that several builtin functions are mapped to unary operators.

Attribute operator:: the operation
Type:: Unary_Operator
Attribute n_operand:: the expression we operate on
Type:: Expression

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Binary_Expression(mh, location, typ, operator, n_lhs, n_rhs)¶

Bases: Expression

Expression with two operands

This captures the following operations:

Binary_Operator.LOGICAL_AND (e.g. a and b)
Binary_Operator.LOGICAL_OR (e.g. a or b)
Binary_Operator.LOGICAL_XOR (e.g. a xor b)
Binary_Operator.LOGICAL_IMPLIES (e.g. a implies b)
Binary_Operator.COMP_EQ (e.g. a == null)
Binary_Operator.COMP_NEQ (e.g. a != null)
Binary_Operator.COMP_LT (e.g. 1 < 2)
Binary_Operator.COMP_LEQ (e.g. 1 <= 2)
Binary_Operator.COMP_GT (e.g. a > b)
Binary_Operator.COMP_GEQ (e.g. a >= b)
Binary_Operator.STRING_CONTAINS (e.g. "foo" in "foobar")
Binary_Operator.STRING_STARTSWITH (e.g. startswith("foo", "f"))
Binary_Operator.STRING_ENDSWITH (e.g. endswith("foo", "o"))
Binary_Operator.STRING_REGEX (e.g. matches("foo", ".o.)
Binary_Operator.ARRAY_CONTAINS (e.g. 42 in arr)
Binary_Operator.PLUS (e.g. 42 + b or "foo" + bar)
Binary_Operator.MINUS (e.g. a - 1)
Binary_Operator.TIMES (e.g. 2 * x)
Binary_Operator.DIVIDE (e.g. x / 2)
Binary_Operator.REMAINDER (e.g. x % 2)
Binary_Operator.POWER (e.g. x ** 2)
Binary_Operator.INDEX (e.g. foo[2])

Note that several builtin functions are mapped to unary operators.

Note also that the plus operation is supported for integers, rationals and strings.

Attribute operator:: the operation
Type:: Binary_Operator
Attribute n_lhs:: the first operand
Type:: Expression
Attribute n_lhs:: the second operand
Type:: Expression

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Field_Access_Expression(mh, location, n_prefix, n_field)¶

Bases: Expression

Tuple field access

For example in:

foo.bar
^1  ^2

Attribute n_prefix:: expression with tuple type (see 1)
Type:: Expression
Attribute n_field:: a tuple field to dereference (see 2)
Type:: Composite_Component

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Range_Test(mh, location, typ, n_lhs, n_lower, n_upper)¶

Bases: Expression

Range membership test

For example in:

x in 1   ..   field+1
^lhs ^lower   ^^^^^^^upper

Note that none of these are guaranteed to be literals or names; you can have arbitrarily complex expressions here.

Attribute n_lhs:: the expression to test
Type:: Expression
Attribute n_lower:: the lower bound
Type:: Expression
Attribute n_lower:: the upper bound
Type:: Expression

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Action(mh, t_kind, n_condition, n_expression)¶

Bases: Node

An if or elseif part inside a conditional expression

Each Conditional_Expression is made up of a sequence of Actions. For example here is a single expression with two Actions:

(if x == 0 then "zero" elsif x == 1 then "one" else "lots")
 ^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^

Note that the else part is not an action, it is an attribute of the Conditional_Expression itself.

Attribute kind:: Either if or elseif
Type:: str
Attribute n_cond:: The boolean condition expression
Type:: Expression
Attribute n_expr:: The value if the condition evaluates to true
Type:: Expression

class trlc.ast.Conditional_Expression(location, if_action)¶

Bases: Expression

A conditional expression

Each Conditional_Expression is made up of a sequence of one or more Action. For example here is a single expression with two Actions:

(if x == 0 then "zero" elsif x == 1 then "one" else "lots")
 ^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^      ^^^^^^

The else expression is part of the conditional expression itself.

A conditional expression will have at least one action (the if action), and all other actions will be elsif actions. The else expression is not optional and will always be present. The types of all actions and the else expression will match.

Attribute actions:: a list of Actions
Type:: list[Action]
Attribute else_expr:: the else expression
Type:: Expression

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Quantified_Expression(mh, location, typ, universal, n_variable, n_source, n_expr)¶

Bases: Expression

A quantified expression

For example:

(forall x in array_component => x > 0)
 ^4     ^1   ^2                 ^^^^^3

A quantified expression introduces and binds a Quantified_Variable (see 1) from a specified source (see 2). When the body (see 3) is evaluated, the name of 1 is bound to each component of the source in turn.

Attribute n_var:: The quantified variable (see 1)
Type:: Quantified_Variable
Attribute n_source:: The array to iterate over (see 2)
Type:: Name_Reference
Attribute n_expr:: The body of the quantifier (see 3)
Type:: Expression
Attribute universal:: True means forall, false means exists (see 4)
Type:: Boolean

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

Literals¶

class trlc.ast.Literal(location, typ)¶

Bases: Expression

Abstract base for all Literals

Does not offer any additional features, but it’s a nice way to group together all literal types. This is useful if you want to check if you are dealing with a literal:

isinstance(my_expression, Literal)

class trlc.ast.Null_Literal(token)¶

Bases: Literal

The null literal

This can appear in check expressions:

a /= null implies a > 5
     ^^^^

Please note that this is distinct from the Implicit_Null values that appear in record objects.

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Integer_Literal(token, typ)¶

Bases: Literal

Integer literals

Note that these are always positive. A negative integer is actually a unary negation expression, operating on a positive integer literal:

x == -5

This would create the following tree:

OP_EQUALITY
   NAME_REFERENCE x
   UNARY_EXPRESSION -
      INTEGER_LITERAL 5

Attribute value:: the non-negative integer value
Type:: int

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Decimal_Literal(token, typ)¶

Bases: Literal

Decimal literals

Note that these are always positive. A negative decimal is actually a unary negation expression, operating on a positive decimal literal:

x == -5.0

This would create the following tree:

OP_EQUALITY
   NAME_REFERENCE x
   UNARY_EXPRESSION -
      DECIMAL_LITERAL 5.0

Attribute value:: the non-negative decimal value
Type:: fractions.Fraction

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.String_Literal(token, typ)¶

Bases: Literal

String literals

Note the value of the string does not include the quotation marks, and any escape sequences are fully resolved. For example:

"foo\"bar"

Will have a value of foo"bar.

Attribute value:: string content
Type:: str
Attribute references:: resolved references of a markup string
Type:: list[Record_Reference]

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Boolean_Literal(token, typ)¶

Bases: Literal

Boolean values

Attribute value:: the boolean value
Type:: bool

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

class trlc.ast.Enumeration_Literal(location, literal)¶

Bases: Literal

Enumeration values

Note that this is distinct from Enumeration_Literal_Spec. An enumeration literal is a specific mention of an enumeration member in an expression:

foo != my_enum.POTATO
       ^^^^^^^^^^^^^^

To get to the string value of the enumeration literal (i.e. POTATO here) you can get the name of the literal spec itself: enum_lit.value.name; and to get the name of the enumeration (i.e. my_enum here) you can use enum_lit.value.n_typ.name.

Attribute value:: enumeration value
Type:: Enumeration_Literal_Spec

can_be_null()¶

Test if the expression could return null

Checks the expression if it could generate a null value without raising an error. For example x could generate a null value if x is a record component that is optional. However x + 1 could not, since an error would occur earlier.

Returns:: possibility of encountering null
Return type:: bool

Evaluation¶

class trlc.ast.Value(location, value, typ)¶

Bases: object

Polymorphic value for evaluating expressions.

Any record references will be fully resolved.

Attribute location:: source location this value comes from
Type:: Location
Attribute value:: the value or None (for null values)
Type:: str, int, bool, fractions.Fraction, list[Value], Record_Reference, Enumeration_Literal_Spec
Attribute typ:: type of the value (or None for null values)
Type:: Type

Symbols and scope¶

class trlc.ast.Symbol_Table(parent=None)¶

Bases: object

Symbol table mapping names to entities

all_names()¶

All names in the symbol table

Return type:: set[str]

contains(name)¶

Tests if the given name is in the table

Parameters:: name (str) – the name to test
Return type:: bool

iter_record_objects()¶

Iterate over all record objects

Return type:: iterable[Record_Object]

iter_record_objects_by_section()¶

API for users

Retriving information about the section hierarchy for record objects Inputs: folder with trlc files where trlc files have sections, sub sections and record objects Output: Information about sections and level of sections, record objects and levels of record object

lookup_assuming(mh, name, required_subclass=None)¶

Retrieve an object from the table assuming its there

This is intended for the API specifically where you want to e.g. find some used-defined types you know are there.

Parameters:

mh (Message_Handler) – The message handler to use
name (str) – The name to search for
required_subclass (type) – If set, creates an error if the object is not an instance of the given class

Raises:

TRLC_Error – if the object is not of the required subclass

Returns:

the specified entity (or None if it does not exist)

Return type:

Entity

lookup_direct(mh, name, error_location, required_subclass=None, simplified=False)¶

Retrieve an object from the table

For example:

pkg = stab.lookup_direct(mh,
                         "potato",
                         Location("foobar.txt", 42),
                         Package)

This would search for an object named potato. If it is found, and it is a package, it is returned. If it is not a Package, then the following error is issued:

foobar.txt:42: error: Enumeration_Type potato is not a Package

If it is not found at all, then the following error is issued:

foobar.txt:42: error: unknown symbol potato

Parameters:

mh (Message_Handler) – The message handler to use
name (str) – The name to search for
error_location (Location) – Where to create the error if the name is not found
required_subclass (type) – If set, creates an error if the object is not an instance of the given class
simplified (bool) – If set, look up the given simplified name instead of the actual name

Raises:

TRLC_Error – if the name is not in the table
TRLC_Error – if the object is not of the required subclass

Returns:

the specified entity

Return type:

Entity

AST¶

Root class¶

Entities¶

Miscellaneous¶

Types¶

Expressions¶

Literals¶

Evaluation¶

Symbols and scope¶

Table of Contents

Table of Contents