ESCAPE_CHAR """

```

Which are composed into the following components of an input file that do not directly contribute towards the AST:

```

// asterisk followed by any ASCII char, excluding "/", or just any ASCII char without "*"

block-comment-contents = "*" (0x00-0x2E | 0x30-0x7E) | (0x20-0x29 | 0x2B-0x7E)

block-comment = "/*" block-comment-contents* "*/"

line-comment = "//" (WSP | VCHAR)* NEWLINE

comment = block-comment | line-comment

cw = (comment | WSP | NEWLINE)*

cwb = (comment | WSP | newline)+

```

Where it should be noted that the `cw` rule allows for not encountering any of the indicated characters, while the `cwb` rule expects at least one instance.

The following operators are defined:

```

binary-operator = "||" | "&&" | 

                  "!=" | "==" | "<=" | ">=" | "<" | ">" |

                  "|" | "&" | "^" | "<<" | ">>" |

                  "+" | "-" | "*" | "/" | "%"

assign-operator = "=" |

                  "|=" | "&=" | "^=" | "<<=" | ">>=" |

                  "+=" | "-=" | "*=" | "/=" | "%="

unary-operator = "++" | "--" | "+" | "-" | "~" | "!"

```

**QUESTION**: Do we include the pre/postfix "++" and "--" operators? They were introduced in C to reduce the amount of required characters. But is still necessary?

And to define various constants in the language, we allow for the following:

```

// Various integer constants, binary, octal, decimal, or hexadecimal, with a 

// utility underscore to enhance humans reading the characters. Allowing use to

// write something like 100_000_256 or 0xDEAD_BEEF

int-bin-char = "0" | "1"

int-bin-constant = "0b" int-bin-char (int-bin-char | "_")* // 0b0100_1110

int-oct-char = "0"-"7"

int-oct-constant = "0o" int-oct-char (int-oct-char | "_")* // 0o777

int-dec-constant = DIGIT (DIGIT | "_")* //

int-hex-char = DIGIT | "a"-"f" | "A"-"F" 

int-hex-constant = "0x" int-hex-char (int-hex-char | "_")* // 0xFEFE_1337

int-constant = int-bin-constant | int-oct-constant | int-dec-constant | int-hex-constant

// Floating point numbers

//  language, but might be useful? 

float-constant = DIGIT* "." DIGIT+

// Character constants: a single character. Its element may be an escaped 

// character or a VCHAR (excluding "'" and "\")

char-element = ESCAPED_CHARS | (0x20-0x26 | 0x28-0x5B | 0x5D-0x7E) 

char-constant = "'" char-element "'"

// Same thing for strings, but these may contain 0 or more characters

str-element = ESCAPED_CHARS | (0x20-0x21 | 0x23-0x5B | 0x5D-0x7E)

str-constant = """ str-element* """

```

Note that the integer characters are forced, somewhat arbitrarily without hampering the programmer's expressiveness, to start with a valid digit. Only then may one introduce the `_` character. And non-rigorously speaking characters may not contain an unescaped `'`-character, and strings may not contain an unescaped `"`-character.

We now introduce the various identifiers that exist within the language, we make a distinction between "any identifier" and "any identifier except for the builtin ones". Because we h

```

identifier-any = ALPHA | (ALPHA | DIGIT | "_")*

keyword = 

    "composite" | "primitive" |

    type-primitive | "true" | "false" | "null" |

    "struct" | "enum" |

    "if" | "else" |

    "while" | "break" | "continue" | "return" |

    "synchronous" | "assert" |

    "goto" | "skip" | "new" | "let"

builtin = "put" | "get" | "fires" | "create" | "assert"

identifier = identifier-any WITHOUT (keyword | builtin)

// Identifier with any number of prefixed namespaces

ns-identifier = (identifier "::")* identifier

```

We then start introducing the type system. Learning from the "mistake" of C/C++ of having types like `byte` and `short` with unspecified and compiler-dependent byte-sizes (followed by everyone using `stdint.h`), we use the Rust/Zig-like `u8`, `i16`, etc. Currently we will limit the programmer to not produce integers which take up more than 64 bits. Furthermore, as one is writing network code, it would be quite neat to be able to put non-byte-aligned integers into a struct in order to directly access meaningful bits. Hence, with restrictions introduced later, we will allow for types like `i4` or `u1`. When actually retrieving them or performing computations with them we will use the next-largest byte-size to operate on them in "registers".

**Question**: Difference between u1 and bool? Do we allow assignments between them? What about i1 and bool?

As the language semantics are value-based, we are prevented from returning information from functions through its arguments. We may only return information through its (single) return value. If we consider the common case of having to parse a series of bytes into a meaningful struct, we cannot return both the struct and a value as a success indicator. For this reason, we introduce algebraic datatypes (or: tagged unions, or: enums) as well.

Lastly, since functions are currently without internal side-effects (since functions cannot perform communication with components, and there is no functionality to interact "with the outside world" from within a function), it does not make sense to introduce the "void" type, as found in C/C++ to indicate that a function doesn't return anything of importance. However, internally we will allow for a "void" type, this will allow treating builtins such as "assert" and "put" like functions while constructing and evaluating the AST.

```

// The digits 1-64, without any leading zeros allowed, to allow specifying the

// signed and unsigned integer types

number-1-64 = NZ-DIGIT | (0x31-0x35 DIGIT) | ("6" 0x30-0x34)

type-signed-int = "i" number-1-64 // i1 through i64

type-unsigned-int = "u" number-1-64 // u1 through u64

Note that, different from C-like languages, we do require semicolons to exist at the end of a pragma statement. The reason is to prevent future hacks using the "\" character to indicate an end-of-line-but-not-really-end-of-line statements.

Apart from these pragmas, we can have component definitions, type definitions and function definitions within the source file. The grammar for these may be formulated as:

```

// Annotated types and function/component arguments

type-annotation = type (cw [])?

var-declaration = type-annotation cwb identifier

params-list = "(" cw (var-declaration (cw "," cw var-declaration)*)? cw ")"

// Functions and components

function-def = type-annotation cwb identifier cw params-list cw block

composite-def = "composite" cwb identifier cw params-list cw block

primitive-def = "primitive" cwb identifier cw params-list cw block

component-def = composite-def | primitive-def

// Symbol definitions now become

symbol-def = type-union-def | type-struct-def | function-def | component-def 

```

Using these rules, we can now describe the grammar of a single file as:

```

file = cw (pragma | symbol-def)* cw

```

Of course, we currently cannot do anything useful with our grammar, hence we have to describe blocks to let the functions and component definitions do something. To do so, we proceed as:

```

// channel a->b;, or channel a -> b;

channel-decl = channel cwb identifier cw "->" cw identifier cw ";"

// int a = 5, b = 2 + 3;

memory-decl = var-declaration cw "=" cw expression (cw "," cw identifier cw "=" cw expression)* cw ";"

stmt = block |

    identifier cw ":" cw stmt | // label

    "if" cw pexpr cw stmt (cw "else" cwb stmt)? |

    "while" cw pexpr cw stmt |

    "break" (cwb identifier)? cw ";" |

    "continue" (cwb identifier)? cw ";" |

    "synchronous" stmt |

    "return" cwb identifier cw ";" |

    "goto" cwb identifier cw ";" |

    "skip" cw ";" |

    "new" cwb method-expr cw ";" |

    expr cw ";"

method-params-list = "(" cw (expr (cw "," cw expr)* )? cw ")"

method-expr = method cw method-params-list

enum-destructure-expr = "let" cw ns-identifier "::" identifier cw "(" cw identifier cw ")" cw "=" expr

enum-test-expr = ns-identifier "::" identifier cw "==" cw expr

block = "{" (cw (channel-decl | memory-decl | stmt))* cw "}"

```

Note that we have a potential collision of various expressions/statements. The following cases are of importance:

1. An empty block is written as `{}`, while an empty array construction is also written as `{}`.

2. Both function calls as enum constants feature the same construction syntax. That is: `foo::bar(expression)` may refer to a function call to `bar` in the namespace `foo`, but may also be the construction of enum `foo`'s `bar` variant (containing a value `expression`). These may be disambiguated using the type system.

3. The enumeration destructuring expression may collide with the constant enumeration literal. These may be disambiguated by looking at the inner value. If the inner value is an identifier and not yet defined as a variable, then it is a destructuring expression. Otherwise it must be interpreted as a constant enumeration. The enumeration destructuring expression must then be completed by it being a child of an binary equality operator. If not, then it is invalid syntax.

Finally, for consistency, there are additional rules to the enumeration destructuring. As a preamble: the language should allow programmers to express any kind of trickery they want, as long as it is correct. But programmers should be prevented from expressing something that is by definition incorrect/illogical. So enumeration destructuring (e.g. `Enum::Variant(bla) == expression`) should return a value with a special type (e.g. `EnumDestructureBool`) that may only reside within the testing expressions of `if` and `while` statements. Furthermore, this special boolean type only supports the logical-and (`&&`) operator. This way we prevent invalid expressions such as `if (Enum::Variant1(foo) == expr || Enum::Variant2(bar) == expr) { ... }`, but we do allow potentially valid expressions like `if (Enum::Variant1(foo) == expr_foo && Enum::Variant2(bar) == expr_bar) { ... }`.

**Question**: In the documentation for V1.0 we find the `synchronous cw (params-list cw stmt | block)` rule. Why the `params-list`?

**TODO**: Release constructions on memory declarations: as long as we have a write to it before a read we should be fine. Can be done once we add semantic analysis in order to optimize putting and getting port values.

**TODO**: Implement type inference, should be simpler once I figure out how to write a typechecker.

**TODO**: Add constants assigned in the global scope.

**TODO**: Add a runtime expression evaluator (probably before constants in global scope) to simplify expressions and/or remove impossible branches.

use std::marker::PhantomData;

use alloc::raw_vec::RawVec;

/// Entry in a freelist. Contains a generation number to ensure silly mistakes

/// using an item's index after freeing it.

struct Entry<T> {

    generation: usize,

    item: T,

}

/// Key of an item in the freelist. Contains a generation number to prevent

/// use-after-free during development.

// TODO: Two usizes are probably overkill

#[derive(Copy, Clone)]

pub struct Key<T> {

    generation: usize,

    index: usize,

    _type: PhantomData<T>,

}

/// Generic freelist structure. Item insertion/retrieval/deletion works like a

/// HashMap through keys.

pub struct FreeList<T> {

    items: *mut Entry<T>,

    capacity: usize,

    length: usize,

    free: Vec<usize>,

}

impl<T> FreeList<T> {

    pub fn new() -> Self<T> {

        std::alloc::Layout::from_size_align()

        Self{

            items: std::ptr::null_mut(),

            capacity: 0,

            length: 0,

            free: Vec::new(),

        }

    }

    pub fn with_capacity(capacity: usize) -> Self {

        alloc::

        Self{

            items: std::,

            free: Vec::with_capacity(capacity),

            length: 0,

        }

    }

    /// Inserts a new item into the freelist. Will return a key that can be used

    /// to retrieve the item and delete it.

    pub fn insert(&mut self, item: T) -> Key<T> {

        let mut generation;

        let mut index;

        if self.free.is_empty() {

            // No free elements, make sure we have enough capacity

            if self.length == self.items.capacity() {

                self.items.reserve(self.length, 1);

            }

            // Now we do

            generation = 0;

            index = self.length;

            unsafe {

                let target = self.items.ptr().add(self.length);

                std::ptr::write(&mut target.item, item);

                self.length += 1;

            }

mod string_pool;

mod scoped_buffer;

mod sets;

mod raw_vec;

// mod freelist;

pub(crate) use string_pool::{StringPool, StringRef};

pub(crate) use scoped_buffer::{ScopedBuffer, ScopedSection};

pub(crate) use sets::{DequeSet, VecSet};

pub(crate) use raw_vec::RawVec;

    fn eq(&self, other: &StringRef) -> bool {

        self.as_str() == other.as_str()

    }

}

impl Eq for StringRef<'_> {}

impl Hash for StringRef<'_> {

    fn hash<H: Hasher>(&self, state: &mut H) {

        state.write(self.as_bytes());

    }

}

struct StringPoolSlab {

    prev: *mut StringPoolSlab,

    data: Vec<u8>,

    remaining: usize,

}

impl StringPoolSlab {

    fn new(prev: *mut StringPoolSlab) -> Self {

        Self{ prev, data: Vec::with_capacity(SLAB_SIZE), remaining: SLAB_SIZE }

    }

}

/// StringPool is a ever-growing pool of strings. Strings have a maximum size

/// equal to the slab size. The slabs are essentially a linked list to maintain

/// pointer-stability of the strings themselves.

/// All `StringRef` instances are invalidated when the string pool is dropped

pub(crate) struct StringPool {

    last: *mut StringPoolSlab,

}

impl StringPool {

    pub(crate) fn new() -> Self {

        // To have some stability we just turn a box into a raw ptr.

        let initial_slab = Box::new(StringPoolSlab::new(null_mut()));

        let initial_slab = Box::into_raw(initial_slab);

        StringPool{

            last: initial_slab,

        }

    }

    /// Interns a string to the `StringPool`, returning a reference to it. The

    /// pointer owned by `StringRef` is `'static` as the `StringPool` doesn't

    /// reallocate/deallocate until dropped (which only happens at the end of

    /// the program.)

    pub(crate) fn intern(&mut self, data: &[u8]) -> StringRef<'static> {

        let data_len = data.len();

        debug_assert!(std::str::from_utf8(data).is_ok(), "string to intern is not valid UTF-8 encoded");

        let mut last = unsafe{&mut *self.last};

        if data.len() > last.remaining {

            // Doesn't fit: allocate new slab

            self.alloc_new_slab();

            last = unsafe{&mut *self.last};

        }

        // Must fit now, compute hash and put in buffer

        debug_assert!(data_len <= last.remaining);

        let range_start = last.data.len();

        last.data.extend_from_slice(data);

        last.remaining -= data_len;

        debug_assert_eq!(range_start + data_len, last.data.len());

        unsafe {

            let start = last.data.as_ptr().offset(range_start as isize);

            StringRef{ data: start, length: data_len, _phantom: PhantomData }

        }

    }

    fn alloc_new_slab(&mut self) {

        let new_slab = Box::new(StringPoolSlab::new(self.last));

        let new_slab = Box::into_raw(new_slab);

        self.last = new_slab;

    }

}

impl Drop for StringPool {

    fn drop(&mut self) {

        let mut new_slab = self.last;

        while !new_slab.is_null() {

            let cur_slab = new_slab;

            unsafe {

                new_slab = (*cur_slab).prev;

                Box::from_raw(cur_slab); // consume and deallocate

            }

        }

    }

}

// String pool cannot be cloned, and the created `StringRef` instances remain

// allocated until the end of the program, so it is always safe to send. It is

// also sync in the sense that it becomes an immutable thing after compilation,

// but lets not derive that if we would ever become a multithreaded compiler in

// the future.

unsafe impl Send for StringPool {}

use std::fmt;

use std::fmt::{Debug, Display, Formatter};

use std::ops::{Index, IndexMut};

use super::arena::{Arena, Id};

use crate::collections::StringRef;

use crate::protocol::input_source::InputSpan;

/// Helper macro that defines a type alias for a AST element ID. In this case 

/// only used to alias the `Id<T>` types.

macro_rules! define_aliased_ast_id {

    // Variant where we just defined the alias, without any indexing

    ($name:ident, $parent:ty) => {

        pub type $name = $parent;

    };

    // Variant where we define the type, and the Index and IndexMut traits

    (

        $name:ident, $parent:ty, 

        index($indexed_type:ty, $indexed_arena:ident)

    ) => {

        define_aliased_ast_id!($name, $parent);

        impl Index<$name> for Heap {

            type Output = $indexed_type;

            fn index(&self, index: $name) -> &Self::Output {

                &self.$indexed_arena[index]

            }

        }

        impl IndexMut<$name> for Heap {

            fn index_mut(&mut self, index: $name) -> &mut Self::Output {

                &mut self.$indexed_arena[index]

            }

        }

    };

    // Variant where we define type, Index(Mut) traits and an allocation function

    (

        $name:ident, $parent:ty,

        index($indexed_type:ty, $indexed_arena:ident),

        alloc($fn_name:ident)

    ) => {

        define_aliased_ast_id!($name, $parent, index($indexed_type, $indexed_arena));

        impl Heap {

            pub fn $fn_name(&mut self, f: impl FnOnce($name) -> $indexed_type) -> $name {

                self.$indexed_arena.alloc_with_id(|id| f(id))

            }

        }

    };

}

    // programmer

    Void,

    InputOrOutput,

    ArrayLike,

    IntegerLike,

    // Basic builtin

    Message,

    Bool,

    UInt8, UInt16, UInt32, UInt64,

    SInt8, SInt16, SInt32, SInt64,

    Character, String,

    // Literals (need to get concrete builtin type during typechecking)

    IntegerLiteral,

    // Marker for inference

    Inferred,

    // Builtins expecting one subsequent type

    Array,

    Input,

    Output,

    // User-defined types

    PolymorphicArgument(DefinitionId, u32), // u32 = index into polymorphic variables

    Definition(DefinitionId, u32), // u32 = number of subsequent types in the type tree.

}

impl ParserTypeVariant {

    pub(crate) fn num_embedded(&self) -> usize {

        use ParserTypeVariant::*;

        match self {

            Void | IntegerLike |

            Message | Bool |

            UInt8 | UInt16 | UInt32 | UInt64 |

            SInt8 | SInt16 | SInt32 | SInt64 |

            Character | String | IntegerLiteral |

            Inferred | PolymorphicArgument(_, _) =>

                0,

            ArrayLike | InputOrOutput | Array | Input | Output =>

                1,

            Definition(_, num) => *num as usize,

        }

    }

}

/// ParserTypeElement is an element of the type tree. An element may be

/// implicit, meaning that the user didn't specify the type, but it was set by

/// the compiler.

#[derive(Debug, Clone)]

pub struct ParserTypeElement {

    pub element_span: InputSpan, // span of this element, not including the child types

    pub variant: ParserTypeVariant,

}

/// ParserType is a specification of a type during the parsing phase and initial

/// linker/validator phase of the compilation process. These types may be

/// (partially) inferred or represent literals (e.g. a integer whose bytesize is

/// not yet determined).

///

/// Its contents are the depth-first serialization of the type tree. Each node

/// is a type that may accept polymorphic arguments. The polymorphic arguments

/// are then the children of the node.

#[derive(Debug, Clone)]

pub struct ParserType {

    pub elements: Vec<ParserTypeElement>,

    pub full_span: InputSpan,

}

impl ParserType {

    pub(crate) fn iter_embedded(&self, parent_idx: usize) -> ParserTypeIter {

        ParserTypeIter::new(&self.elements, parent_idx)

    }

}

/// Iterator over the embedded elements of a specific element.

pub struct ParserTypeIter<'a> {

    pub elements: &'a [ParserTypeElement],

    pub cur_embedded_idx: usize,

}

impl<'a> ParserTypeIter<'a> {

    fn new(elements: &'a [ParserTypeElement], parent_idx: usize) -> Self {

        debug_assert!(parent_idx < elements.len(), "parent index exceeds number of elements in ParserType");

        if elements[0].variant.num_embedded() == 0 {

            // Parent element does not have any embedded types, place

            // `cur_embedded_idx` at end so we will always return `None`

            Self{ elements, cur_embedded_idx: elements.len() }

        } else {

            // Parent element has an embedded type

            Self{ elements, cur_embedded_idx: parent_idx + 1 }

        }

    }

}

impl<'a> Iterator for ParserTypeIter<'a> {

    type Item = &'a [ParserTypeElement];

    fn next(&mut self) -> Option<Self::Item> {

}

impl Expression {

    pub fn as_variable(&self) -> &VariableExpression {

        match self {

            Expression::Variable(result) => result,

            _ => panic!("Unable to cast `Expression` to `VariableExpression`"),

        }

    }

    /// Returns operator span, function name, a binding's "let" span, etc. An

    /// indicator for the kind of expression that is being applied.

    pub fn operation_span(&self) -> InputSpan {

        match self {

            Expression::Assignment(expr) => expr.operator_span,

            Expression::Binding(expr) => expr.operator_span,

            Expression::Conditional(expr) => expr.operator_span,

            Expression::Binary(expr) => expr.operator_span,

            Expression::Unary(expr) => expr.operator_span,

            Expression::Indexing(expr) => expr.operator_span,

            Expression::Slicing(expr) => expr.slicing_span,

            Expression::Select(expr) => expr.operator_span,

            Expression::Literal(expr) => expr.span,

            Expression::Cast(expr) => expr.cast_span,

            Expression::Call(expr) => expr.func_span,

            Expression::Variable(expr) => expr.identifier.span,

        }

    }

    /// Returns the span covering the entire expression (i.e. including the

    /// spans of the arguments as well).

    pub fn full_span(&self) -> InputSpan {

        match self {

            Expression::Assignment(expr) => expr.full_span,

            Expression::Binding(expr) => expr.full_span,

            Expression::Conditional(expr) => expr.full_span,

            Expression::Binary(expr) => expr.full_span,

            Expression::Unary(expr) => expr.full_span,

            Expression::Indexing(expr) => expr.full_span,

            Expression::Slicing(expr) => expr.full_span,

            Expression::Select(expr) => expr.full_span,

            Expression::Literal(expr) => expr.span,

            Expression::Cast(expr) => expr.full_span,

            Expression::Call(expr) => expr.full_span,

            Expression::Variable(expr) => expr.identifier.span,

        }

    }

    pub fn parent(&self) -> &ExpressionParent {

        match self {

            Expression::Assignment(expr) => &expr.parent,

            Expression::Binding(expr) => &expr.parent,

            Expression::Conditional(expr) => &expr.parent,

            Expression::Binary(expr) => &expr.parent,

            Expression::Unary(expr) => &expr.parent,

            Expression::Indexing(expr) => &expr.parent,

            Expression::Slicing(expr) => &expr.parent,

            Expression::Select(expr) => &expr.parent,

            Expression::Literal(expr) => &expr.parent,

            Expression::Cast(expr) => &expr.parent,

            Expression::Call(expr) => &expr.parent,

            Expression::Variable(expr) => &expr.parent,

        }

    }

    pub fn parent_expr_id(&self) -> Option<ExpressionId> {

        if let ExpressionParent::Expression(id, _) = self.parent() {

            Some(*id)

        } else {

            None

        }

    }

    pub fn get_unique_id_in_definition(&self) -> i32 {

        match self {

            Expression::Assignment(expr) => expr.unique_id_in_definition,

            Expression::Binding(expr) => expr.unique_id_in_definition,

            Expression::Conditional(expr) => expr.unique_id_in_definition,

            Expression::Binary(expr) => expr.unique_id_in_definition,

            Expression::Unary(expr) => expr.unique_id_in_definition,

            Expression::Indexing(expr) => expr.unique_id_in_definition,

            Expression::Slicing(expr) => expr.unique_id_in_definition,

            Expression::Select(expr) => expr.unique_id_in_definition,

            Expression::Literal(expr) => expr.unique_id_in_definition,

            Expression::Cast(expr) => expr.unique_id_in_definition,

            Expression::Call(expr) => expr.unique_id_in_definition,

            Expression::Variable(expr) => expr.unique_id_in_definition,

        }

    }

}

#[derive(Debug, Clone, Copy)]

pub enum AssignmentOperator {

    Set,

    Concatenated,

    Multiplied,

    Divided,

    Remained,

    Added,

    Subtracted,

    ShiftedLeft,

    ShiftedRight,

    BitwiseAnded,

    BitwiseXored,

    BitwiseOred,

}

#[derive(Debug, Clone)]

pub struct AssignmentExpression {

    pub this: AssignmentExpressionId,

    // Parsing

    pub operator_span: InputSpan,

    pub full_span: InputSpan,

            PTV::IntegerLiteral => { target.push_str("int_literal"); },

            PTV::Inferred => { target.push_str(KW_TYPE_INFERRED_STR); },

            PTV::Array => {

                element_idx = write_element(target, heap, t, element_idx + 1);

                target.push_str("[]");

            },

            PTV::Input => {

                target.push_str(KW_TYPE_IN_PORT_STR);

                target.push('<');

                element_idx = write_element(target, heap, t, element_idx + 1);

                target.push('>');

            },

            PTV::Output => {

                target.push_str(KW_TYPE_OUT_PORT_STR);

                target.push('<');

                element_idx = write_element(target, heap, t, element_idx + 1);

                target.push('>');

            },

            PTV::PolymorphicArgument(definition_id, arg_idx) => {

                let definition = &heap[*definition_id];

                let poly_var = &definition.poly_vars()[*arg_idx as usize].value;

                target.push_str(poly_var.as_str());

            },

            PTV::Definition(definition_id, num_embedded) => {

                let definition = &heap[*definition_id];

                let definition_ident = definition.identifier().value.as_str();

                target.push_str(definition_ident);

                let num_embedded = *num_embedded;

                if num_embedded != 0 {

                    target.push('<');

                    for embedded_idx in 0..num_embedded {

                        if embedded_idx != 0 {

                            target.push(',');

                        }

                        element_idx = write_element(target, heap, t, element_idx + 1);

                    }

                    target.push('>');

                }

            }

        }

        element_idx

    }

    write_element(target, heap, t, 0);

}

fn write_concrete_type(target: &mut String, heap: &Heap, def_id: DefinitionId, t: &ConcreteType) {

    use ConcreteTypePart as CTP;

    fn write_concrete_part(target: &mut String, heap: &Heap, def_id: DefinitionId, t: &ConcreteType, mut idx: usize) -> usize {

        if idx >= t.parts.len() {

            return idx;

        }

        match &t.parts[idx] {

            CTP::Void => target.push_str("void"),

            CTP::Message => target.push_str("msg"),

            CTP::Bool => target.push_str("bool"),

            CTP::UInt8 => target.push_str(KW_TYPE_UINT8_STR),

            CTP::UInt16 => target.push_str(KW_TYPE_UINT16_STR),

            CTP::UInt32 => target.push_str(KW_TYPE_UINT32_STR),

            CTP::UInt64 => target.push_str(KW_TYPE_UINT64_STR),

            CTP::SInt8 => target.push_str(KW_TYPE_SINT8_STR),

            CTP::SInt16 => target.push_str(KW_TYPE_SINT16_STR),

            CTP::SInt32 => target.push_str(KW_TYPE_SINT32_STR),

            CTP::SInt64 => target.push_str(KW_TYPE_SINT64_STR),

            CTP::Character => target.push_str(KW_TYPE_CHAR_STR),

            CTP::String => target.push_str(KW_TYPE_STRING_STR),

            CTP::Array => {

                idx = write_concrete_part(target, heap, def_id, t, idx + 1);

                target.push_str("[]");

            },

            CTP::Slice => {

                idx = write_concrete_part(target, heap, def_id, t, idx + 1);

                target.push_str("[..]");

            }

            CTP::Input => {

                target.push_str("in<");

                idx = write_concrete_part(target, heap, def_id, t, idx + 1);

                target.push('>');

            },

            CTP::Output => {

                target.push_str("out<");

                idx = write_concrete_part(target, heap, def_id, t, idx + 1);

                target.push('>')

            },

            CTP::Instance(definition_id, num_embedded) => {

                let identifier = heap[*definition_id].identifier();

                target.push_str(identifier.value.as_str());

                target.push('<');

                for idx_embedded in 0..*num_embedded {

                    if idx_embedded != 0 {

                        target.push_str(", ");

                    }

            return match $lhs {

                Value::UInt8(v)  => { Value::Bool(*v $operator_tokens $rhs.as_uint8() ) },

                Value::UInt16(v) => { Value::Bool(*v $operator_tokens $rhs.as_uint16()) },

                Value::UInt32(v) => { Value::Bool(*v $operator_tokens $rhs.as_uint32()) },

                Value::UInt64(v) => { Value::Bool(*v $operator_tokens $rhs.as_uint64()) },

                Value::SInt8(v)  => { Value::Bool(*v $operator_tokens $rhs.as_sint8() ) },

                Value::SInt16(v) => { Value::Bool(*v $operator_tokens $rhs.as_sint16()) },

                Value::SInt32(v) => { Value::Bool(*v $operator_tokens $rhs.as_sint32()) },

                Value::SInt64(v) => { Value::Bool(*v $operator_tokens $rhs.as_sint64()) },

                _ => unreachable!("apply_binary_operator {:?} on lhs {:?} and rhs {:?}", $operator, $lhs, $rhs)

            };

        }

    }

    // We need to handle concatenate in a special way because it needs the store

    // mutably.

    if op == BO::Concatenate {

        let target_heap_pos = store.alloc_heap();

        let lhs_heap_pos;

        let rhs_heap_pos;

        let lhs = store.maybe_read_ref(lhs);

        let rhs = store.maybe_read_ref(rhs);

        let value_kind;

        match lhs {

            Value::Message(lhs_pos) => {

                lhs_heap_pos = *lhs_pos;

                rhs_heap_pos = rhs.as_message();

                value_kind = ValueKind::Message;

            },

            Value::String(lhs_pos) => {

                lhs_heap_pos = *lhs_pos;

                rhs_heap_pos = rhs.as_string();

                value_kind = ValueKind::String;

            },

            Value::Array(lhs_pos) => {

                lhs_heap_pos = *lhs_pos;

                rhs_heap_pos = rhs.as_array();

                value_kind = ValueKind::Array;

            },

            _ => unreachable!("apply_binary_operator {:?} on lhs {:?} and rhs {:?}", op, lhs, rhs)

        }

        let lhs_heap_pos = lhs_heap_pos as usize;

        let rhs_heap_pos = rhs_heap_pos as usize;

        let mut concatenated = Vec::new();

        let lhs_len = store.heap_regions[lhs_heap_pos].values.len();

        let rhs_len = store.heap_regions[rhs_heap_pos].values.len();

        concatenated.reserve(lhs_len + rhs_len);

        for idx in 0..lhs_len {

            concatenated.push(store.clone_value(store.heap_regions[lhs_heap_pos].values[idx].clone()));

        }

        for idx in 0..rhs_len {

            concatenated.push(store.clone_value(store.heap_regions[rhs_heap_pos].values[idx].clone()));

        }

        store.heap_regions[target_heap_pos as usize].values = concatenated;

        return match value_kind{

            ValueKind::Message => Value::Message(target_heap_pos),

            ValueKind::String => Value::String(target_heap_pos),

            ValueKind::Array => Value::Array(target_heap_pos),

        };

    }

    // If any of the values are references, retrieve the thing they're referring

    // to.

    let lhs = store.maybe_read_ref(lhs);

    let rhs = store.maybe_read_ref(rhs);

    match op {

        BO::Concatenate => unreachable!(),

        BO::LogicalOr => {

            return Value::Bool(lhs.as_bool() || rhs.as_bool());

        },

        BO::LogicalAnd => {

            return Value::Bool(lhs.as_bool() && rhs.as_bool());

        },

        BO::BitwiseOr        => { apply_int_op_and_return_self!(lhs, |,  op, rhs); },

        BO::BitwiseXor       => { apply_int_op_and_return_self!(lhs, ^,  op, rhs); },

        BO::BitwiseAnd       => { apply_int_op_and_return_self!(lhs, &,  op, rhs); },

        BO::Equality         => { Value::Bool(apply_equality_operator(store, lhs, rhs)) },

        BO::Inequality       => { Value::Bool(apply_inequality_operator(store, lhs, rhs)) },

        BO::LessThan         => { apply_int_op_and_return_bool!(lhs, <,  op, rhs); },

        BO::GreaterThan      => { apply_int_op_and_return_bool!(lhs, >,  op, rhs); },

        BO::LessThanEqual    => { apply_int_op_and_return_bool!(lhs, <=, op, rhs); },

        BO::GreaterThanEqual => { apply_int_op_and_return_bool!(lhs, >=, op, rhs); },

        BO::ShiftLeft        => { apply_int_op_and_return_self!(lhs, <<, op, rhs); },

        BO::ShiftRight       => { apply_int_op_and_return_self!(lhs, >>, op, rhs); },

        BO::Add              => { apply_int_op_and_return_self!(lhs, +,  op, rhs); },

        BO::Subtract         => { apply_int_op_and_return_self!(lhs, -,  op, rhs); },

        BO::Multiply         => { apply_int_op_and_return_self!(lhs, *,  op, rhs); },

        BO::Divide           => { apply_int_op_and_return_self!(lhs, /,  op, rhs); },

use crate::protocol::input_source::*;

use crate::protocol::parser::*;

use crate::protocol::type_table::*;

/// A protocol description module

pub struct Module {

    pub(crate) source: InputSource,

    pub(crate) root_id: RootId,

    pub(crate) name: Option<StringRef<'static>>,

}

/// Description of a protocol object, used to configure new connectors.

#[repr(C)]

pub struct ProtocolDescription {

    pub(crate) modules: Vec<Module>,

    pub(crate) heap: Heap,

    pub(crate) types: TypeTable,

    pub(crate) pool: Mutex<StringPool>,