/*

 * pass_validation_linking.rs

 *

 * The pass that will validate properties of the AST statements (one is not

 * allowed to nest synchronous statements, instantiating components occurs in

 * the right places, etc.) and expressions (assignments may not occur in

 * arbitrary expressions).

 *

 * Furthermore, this pass will also perform "linking", in the sense of: some AST

 * nodes have something to do with one another, so we link them up in this pass

 * (e.g. setting the parents of expressions, linking the control flow statements

 * like `continue` and `break` up to the respective loop statement, etc.).

 *

 * There are several "confusing" parts about this pass:

 *

 * Setting expression parents: this is the simplest one. The pass struct acts

 * like a little state machine. When visiting an expression it will set the

 * "parent expression" field of the pass to itself, then visit its child. The

 * child will look at this "parent expression" field to determine its parent.

 *

 * Setting the `next` statement: the AST is a tree, but during execution we walk

 * a linear path through all statements. So where appropriate a statement may

 * set the "previous statement" field of the pass to itself. When visiting the

 * subsequent statement it will check this "previous statement", and if set, it

 * will link this previous statement up to itself. Not every statement has a

 * previous statement. Hence there are two patterns that occur: assigning the

 * `next` value, then clearing the "previous statement" field. And assigning the

 * `next` value, and then putting the current statement's ID in the "previous

 * statement" field. Because it is so common, this file contain two macros that

 * perform that operation.

 *

 * To make storing types for polymorphic procedures simpler and more efficient,

 * we assign to each expression in the procedure a unique ID. This is what the

 * "next expression index" field achieves. Each expression simply takes the

 * current value, and then increments this counter.

 */

use crate::collections::{ScopedBuffer};

use crate::protocol::ast::*;

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

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

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

use super::visitor::{

    BUFFER_INIT_CAPACITY,

    Ctx,

    Visitor,

    VisitorResult

};

use crate::protocol::parser::ModuleCompilationPhase;

#[derive(PartialEq, Eq)]

enum DefinitionType {

    Primitive(ComponentDefinitionId),

    Composite(ComponentDefinitionId),

    Function(FunctionDefinitionId)

}

impl DefinitionType {

    fn is_primitive(&self) -> bool { if let Self::Primitive(_) = self { true } else { false } }

    fn is_composite(&self) -> bool { if let Self::Composite(_) = self { true } else { false } }

    fn is_function(&self) -> bool { if let Self::Function(_) = self { true } else { false } }

    fn definition_id(&self) -> DefinitionId {

        match self {

            DefinitionType::Primitive(v) => v.upcast(),

            DefinitionType::Composite(v) => v.upcast(),

            DefinitionType::Function(v) => v.upcast(),

        }

    }

}

/// This particular visitor will go through the entire AST in a recursive manner

/// and check if all statements and expressions are legal (e.g. no "return"

/// statements in component definitions), and will link certain AST nodes to

/// their appropriate targets (e.g. goto statements, or function calls).

///

/// This visitor will not perform control-flow analysis (e.g. making sure that

/// each function actually returns) and will also not perform type checking. So

/// the linking of function calls and component instantiations will be checked

/// and linked to the appropriate definitions, but the return types and/or

/// arguments will not be checked for validity.

pub(crate) struct PassValidationLinking {

    // Traversal state, all valid IDs if inside a certain AST element. Otherwise

    // `id.is_invalid()` returns true.

    in_sync: SynchronousStatementId,

    in_while: WhileStatementId, // to resolve labeled continue/break

    in_select_guard: SelectStatementId, // for detection/rejection of builtin calls

    in_select_arm: u32,

    in_test_expr: StatementId, // wrapping if/while stmt id

    in_binding_expr: BindingExpressionId, // to resolve variable expressions

    in_binding_expr_lhs: bool,

    // Traversal state, current scope (which can be used to find the parent

    // scope) and the definition variant we are considering.

    cur_scope: Scope,

    def_type: DefinitionType,

    // "Trailing" traversal state, set be child/prev stmt/expr used by next one

    prev_stmt: StatementId,

    expr_parent: ExpressionParent,

    // Set by parent to indicate that child expression must be assignable. The

    // child will throw an error if it is not assignable. The stored span is

    // used for the error's position

    must_be_assignable: Option<InputSpan>,

    // Keeping track of relative positions and unique IDs.

    relative_pos_in_block: i32, // of statements: to determine when variables are visible

    next_expr_index: i32, // to arrive at a unique ID for all expressions within a definition

    // Various temporary buffers for traversal. Essentially working around

    // Rust's borrowing rules since it cannot understand we're modifying AST

    // members but not the AST container.

    variable_buffer: ScopedBuffer<VariableId>,

    definition_buffer: ScopedBuffer<DefinitionId>,

    statement_buffer: ScopedBuffer<StatementId>,

    expression_buffer: ScopedBuffer<ExpressionId>,

}

impl PassValidationLinking {

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

        Self{

            in_sync: SynchronousStatementId::new_invalid(),

            in_while: WhileStatementId::new_invalid(),

            in_select_guard: SelectStatementId::new_invalid(),

            in_select_arm: 0,

            in_test_expr: StatementId::new_invalid(),

            in_binding_expr: BindingExpressionId::new_invalid(),

            in_binding_expr_lhs: false,

            cur_scope: Scope::Definition(DefinitionId::new_invalid()),

            prev_stmt: StatementId::new_invalid(),

            expr_parent: ExpressionParent::None,

            def_type: DefinitionType::Function(FunctionDefinitionId::new_invalid()),

            must_be_assignable: None,

            relative_pos_in_block: 0,

            next_expr_index: 0,

            variable_buffer: ScopedBuffer::with_capacity(128),

            definition_buffer: ScopedBuffer::with_capacity(128),

            statement_buffer: ScopedBuffer::with_capacity(BUFFER_INIT_CAPACITY),

            expression_buffer: ScopedBuffer::with_capacity(BUFFER_INIT_CAPACITY),

        }

    }

    fn reset_state(&mut self) {

        self.in_sync = SynchronousStatementId::new_invalid();

        self.in_while = WhileStatementId::new_invalid();

        self.in_test_expr = StatementId::new_invalid();

        self.in_binding_expr = BindingExpressionId::new_invalid();

        self.in_binding_expr_lhs = false;

        self.cur_scope = Scope::Definition(DefinitionId::new_invalid());

        self.def_type = DefinitionType::Function(FunctionDefinitionId::new_invalid());

        self.prev_stmt = StatementId::new_invalid();

        self.expr_parent = ExpressionParent::None;

        self.must_be_assignable = None;

        self.relative_pos_in_block = 0;

        self.next_expr_index = 0

    }

}

macro_rules! assign_then_erase_next_stmt {

    ($self:ident, $ctx:ident, $stmt_id:expr) => {

        if !$self.prev_stmt.is_invalid() {

            $ctx.heap[$self.prev_stmt].link_next($stmt_id);

            $self.prev_stmt = StatementId::new_invalid();

        }

    }

}

macro_rules! assign_and_replace_next_stmt {

    ($self:ident, $ctx:ident, $stmt_id:expr) => {

        if !$self.prev_stmt.is_invalid() {

            $ctx.heap[$self.prev_stmt].link_next($stmt_id);

        }

        $self.prev_stmt = $stmt_id;

    }

}

impl Visitor for PassValidationLinking {

    fn visit_module(&mut self, ctx: &mut Ctx) -> VisitorResult {

        debug_assert_eq!(ctx.module().phase, ModuleCompilationPhase::TypesAddedToTable);

        let root = &ctx.heap[ctx.module().root_id];

        let section = self.definition_buffer.start_section_initialized(&root.definitions);

        for definition_id in section.iter_copied() {

            self.visit_definition(ctx, definition_id)?;

        }

        section.forget();

        ctx.module_mut().phase = ModuleCompilationPhase::ValidatedAndLinked;

        Ok(())

    }

    //--------------------------------------------------------------------------

    // Definition visitors

    //--------------------------------------------------------------------------

    fn visit_component_definition(&mut self, ctx: &mut Ctx, id: ComponentDefinitionId) -> VisitorResult {

        self.reset_state();

        self.def_type = match &ctx.heap[id].variant {

            ComponentVariant::Primitive => DefinitionType::Primitive(id),

            ComponentVariant::Composite => DefinitionType::Composite(id),

        };

        self.cur_scope = Scope::Definition(id.upcast());

        self.expr_parent = ExpressionParent::None;

        // Visit parameters and assign a unique scope ID

        let definition = &ctx.heap[id];

        let body_id = definition.body;

        let section = self.variable_buffer.start_section_initialized(&definition.parameters);

        for variable_idx in 0..section.len() {

            let variable_id = section[variable_idx];

            let variable = &mut ctx.heap[variable_id];

            variable.unique_id_in_scope = variable_idx as i32;

        }

        section.forget();

        // Visit statements in component body

        self.visit_block_stmt(ctx, body_id)?;

        // Assign total number of expressions and assign an in-block unique ID

        // to each of the locals in the procedure.

        ctx.heap[id].num_expressions_in_body = self.next_expr_index;

        self.visit_definition_and_assign_local_ids(ctx, id.upcast());

        Ok(())

    }

    fn visit_function_definition(&mut self, ctx: &mut Ctx, id: FunctionDefinitionId) -> VisitorResult {

        self.reset_state();

        // Set internal statement indices

        self.def_type = DefinitionType::Function(id);

        self.cur_scope = Scope::Definition(id.upcast());

        self.expr_parent = ExpressionParent::None;

        // Visit parameters and assign a unique scope ID

        let definition = &ctx.heap[id];

        let body_id = definition.body;

        let section = self.variable_buffer.start_section_initialized(&definition.parameters);

        for variable_idx in 0..section.len() {

            let variable_id = section[variable_idx];

            let variable = &mut ctx.heap[variable_id];

            variable.unique_id_in_scope = variable_idx as i32;

        }

        section.forget();

        // Visit statements in function body

        self.visit_block_stmt(ctx, body_id)?;

        // Assign total number of expressions and assign an in-block unique ID

        // to each of the locals in the procedure.

        ctx.heap[id].num_expressions_in_body = self.next_expr_index;

        self.visit_definition_and_assign_local_ids(ctx, id.upcast());

        Ok(())

    }

    //--------------------------------------------------------------------------

    // Statement visitors

    //--------------------------------------------------------------------------

    fn visit_block_stmt(&mut self, ctx: &mut Ctx, id: BlockStatementId) -> VisitorResult {

        self.visit_block_stmt_with_hint(ctx, id, None)

    }

    fn visit_local_memory_stmt(&mut self, ctx: &mut Ctx, id: MemoryStatementId) -> VisitorResult {

        let stmt = &ctx.heap[id];

        let expr_id = stmt.initial_expr;

        assign_and_replace_next_stmt!(self, ctx, id.upcast().upcast());

        debug_assert_eq!(self.expr_parent, ExpressionParent::None);

        self.expr_parent = ExpressionParent::Memory(id);

        self.visit_assignment_expr(ctx, expr_id)?;

        self.expr_parent = ExpressionParent::None;

        Ok(())

    }

    fn visit_local_channel_stmt(&mut self, ctx: &mut Ctx, id: ChannelStatementId) -> VisitorResult {

        assign_and_replace_next_stmt!(self, ctx, id.upcast().upcast());

        Ok(())

    }

    fn visit_labeled_stmt(&mut self, ctx: &mut Ctx, id: LabeledStatementId) -> VisitorResult {

        let body_id = ctx.heap[id].body;

        self.visit_stmt(ctx, body_id)?;

        Ok(())

    }

    fn visit_if_stmt(&mut self, ctx: &mut Ctx, id: IfStatementId) -> VisitorResult {

        let if_stmt = &ctx.heap[id];

        let end_if_id = if_stmt.end_if;

        let test_expr_id = if_stmt.test;

        let true_stmt_id = if_stmt.true_body;

        let false_stmt_id = if_stmt.false_body;

        // Visit test expression

        debug_assert_eq!(self.expr_parent, ExpressionParent::None);

        debug_assert!(self.in_test_expr.is_invalid());

        self.in_test_expr = id.upcast();

        self.expr_parent = ExpressionParent::If(id);

        self.visit_expr(ctx, test_expr_id)?;

        self.in_test_expr = StatementId::new_invalid();

        self.expr_parent = ExpressionParent::None;

        // Visit true and false branch. Executor chooses next statement based on

        // test expression, not on if-statement itself. Hence the if statement

        // does not have a static subsequent statement.

        assign_then_erase_next_stmt!(self, ctx, id.upcast());

        self.visit_block_stmt(ctx, true_stmt_id)?;

        assign_then_erase_next_stmt!(self, ctx, end_if_id.upcast());

        if let Some(false_id) = false_stmt_id {

            self.visit_block_stmt(ctx, false_id)?;

            assign_then_erase_next_stmt!(self, ctx, end_if_id.upcast());

        }

        self.prev_stmt = end_if_id.upcast();

        Ok(())

    }

    fn visit_while_stmt(&mut self, ctx: &mut Ctx, id: WhileStatementId) -> VisitorResult {

        let stmt = &ctx.heap[id];

        let end_while_id = stmt.end_while;

        let test_expr_id = stmt.test;

        let body_stmt_id = stmt.body;

        let old_while = self.in_while;

        self.in_while = id;

        // Visit test expression

        debug_assert_eq!(self.expr_parent, ExpressionParent::None);

        debug_assert!(self.in_test_expr.is_invalid());

        self.in_test_expr = id.upcast();

        self.expr_parent = ExpressionParent::While(id);

        self.visit_expr(ctx, test_expr_id)?;

        self.in_test_expr = StatementId::new_invalid();

        // Link up to body statement

        assign_then_erase_next_stmt!(self, ctx, id.upcast());

        self.expr_parent = ExpressionParent::None;

        self.visit_block_stmt(ctx, body_stmt_id)?;

        self.in_while = old_while;

        // Link final entry in while's block statement back to the while. The

        // executor will go to the end-while statement if the test expression

        // is false, so put that in as the new previous stmt

        assign_then_erase_next_stmt!(self, ctx, id.upcast());

        self.prev_stmt = end_while_id.upcast();

        Ok(())

    }

    fn visit_break_stmt(&mut self, ctx: &mut Ctx, id: BreakStatementId) -> VisitorResult {

        // Resolve break target

        let target_end_while = {

            let stmt = &ctx.heap[id];

            let target_while_id = self.resolve_break_or_continue_target(ctx, stmt.span, &stmt.label)?;

            let target_while = &ctx.heap[target_while_id];

            debug_assert!(!target_while.end_while.is_invalid());

            target_while.end_while

        };

        assign_then_erase_next_stmt!(self, ctx, id.upcast());

        let stmt = &mut ctx.heap[id];

        stmt.target = Some(target_end_while);

        Ok(())

    }

    fn visit_continue_stmt(&mut self, ctx: &mut Ctx, id: ContinueStatementId) -> VisitorResult {

        // Resolve continue target

        let target_while_id = {

            let stmt = &ctx.heap[id];

            self.resolve_break_or_continue_target(ctx, stmt.span, &stmt.label)?

        };

        assign_then_erase_next_stmt!(self, ctx, id.upcast());

        let stmt = &mut ctx.heap[id];

        stmt.target = Some(target_while_id);

        Ok(())

    }

    fn visit_synchronous_stmt(&mut self, ctx: &mut Ctx, id: SynchronousStatementId) -> VisitorResult {

        // Check for validity of synchronous statement

        let sync_stmt = &ctx.heap[id];

        let end_sync_id = sync_stmt.end_sync;

        let cur_sync_span = sync_stmt.span;

        if !self.in_sync.is_invalid() {

            // Nested synchronous statement

            let old_sync_span = ctx.heap[self.in_sync].span;

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, cur_sync_span, "Illegal nested synchronous statement"

            ).with_info_str_at_span(

                &ctx.module().source, old_sync_span, "It is nested in this synchronous statement"

            ));

        }

        if !self.def_type.is_primitive() {

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, cur_sync_span,

                "synchronous statements may only be used in primitive components"

            ));

        }

        // Synchronous statement implicitly moves to its block

        assign_then_erase_next_stmt!(self, ctx, id.upcast());

        let sync_body = ctx.heap[id].body;

        debug_assert!(self.in_sync.is_invalid());

        self.in_sync = id;

        self.visit_block_stmt_with_hint(ctx, sync_body, Some(id))?;

        assign_and_replace_next_stmt!(self, ctx, end_sync_id.upcast());

        self.in_sync = SynchronousStatementId::new_invalid();

        Ok(())

    }

    fn visit_fork_stmt(&mut self, ctx: &mut Ctx, id: ForkStatementId) -> VisitorResult {

        let fork_stmt = &ctx.heap[id];

        let end_fork_id = fork_stmt.end_fork;

        let left_body_id = fork_stmt.left_body;

        let right_body_id = fork_stmt.right_body;

        // Fork statements may only occur inside sync blocks

        if self.in_sync.is_invalid() {

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, fork_stmt.span,

                "Forking may only occur inside sync blocks"

            ));

        }

        // Visit the respective bodies. Like the if statement, a fork statement

        // does not have a single static subsequent statement. It forks and then

        // each fork has a different next statement.

        assign_then_erase_next_stmt!(self, ctx, id.upcast());

        self.visit_block_stmt(ctx, left_body_id)?;

        assign_then_erase_next_stmt!(self, ctx, end_fork_id.upcast());

        if let Some(right_body_id) = right_body_id {

            self.visit_block_stmt(ctx, right_body_id)?;

            assign_then_erase_next_stmt!(self, ctx, end_fork_id.upcast());

        }

        self.prev_stmt = end_fork_id.upcast();

        Ok(())

    }

    fn visit_select_stmt(&mut self, ctx: &mut Ctx, id: SelectStatementId) -> VisitorResult {

        let select_stmt = &ctx.heap[id];

        let end_select_id = select_stmt.end_select;

        // Select statements may only occur inside sync blocks

        if self.in_sync.is_invalid() {

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, select_stmt.span,

                "select statements may only occur inside sync blocks"

            ));

        }

        if !self.def_type.is_primitive() {

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, select_stmt.span,

                "select statements may only be used in primitive components"

            ));

        }

        // Visit the various arms in the select block

        let mut case_stmt_ids = self.statement_buffer.start_section();

        let num_cases = select_stmt.cases.len();

        for case in &select_stmt.cases {

            // Note: we add both to the buffer, retrieve them later in indexed

            // fashion

            case_stmt_ids.push(case.guard);

            case_stmt_ids.push(case.block.upcast());

        }

        assign_then_erase_next_stmt!(self, ctx, id.upcast());

        // Link up the "Select" with the "EndSelect". If there are no cases then

        // runtime should pick the "EndSelect" immediately.

        for idx in 0..num_cases {

            let base_idx = 2 * idx;

            let guard_id     = case_stmt_ids[base_idx    ];

            let arm_block_id = case_stmt_ids[base_idx + 1];

            // Visit the guard of this arm

            debug_assert!(self.in_select_guard.is_invalid());

            self.in_select_guard = id;

            self.in_select_arm = idx as u32;

            self.visit_stmt(ctx, guard_id)?;

            self.in_select_guard = SelectStatementId::new_invalid();

            // If the arm declares a variable, then add it to the variables of

            // this arm's code block

            match &ctx.heap[guard_id] {

                Statement::Local(LocalStatement::Memory(stmt)) => {

                    debug_assert_eq!(ctx.heap[arm_block_id].as_block().this.upcast(), arm_block_id); // backwards way of saying arm_block_id is a BlockStatementId

                    let block_stmt = BlockStatementId(arm_block_id);

                    let block_scope =  Scope::Regular(block_stmt);

                    self.checked_at_single_scope_add_local(ctx, block_scope, -1, stmt.variable)?;

                },

                Statement::Expression(_) => {},

                _ => unreachable!(), // just to be sure the parser produced the expected AST

            }

            // Visit the code associated with the guard

            self.visit_stmt(ctx, arm_block_id)?;

            assign_then_erase_next_stmt!(self, ctx, end_select_id.upcast());

        }

        self.in_select_guard = SelectStatementId::new_invalid();

        self.prev_stmt = end_select_id.upcast();

        Ok(())

    }

    fn visit_return_stmt(&mut self, ctx: &mut Ctx, id: ReturnStatementId) -> VisitorResult {

        // Check if "return" occurs within a function

        let stmt = &ctx.heap[id];

        if !self.def_type.is_function() {

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, stmt.span,

                "return statements may only appear in function bodies"

            ));

        }

        // If here then we are within a function

        assign_then_erase_next_stmt!(self, ctx, id.upcast());

        debug_assert_eq!(self.expr_parent, ExpressionParent::None);

        debug_assert_eq!(ctx.heap[id].expressions.len(), 1);

        self.expr_parent = ExpressionParent::Return(id);

        self.visit_expr(ctx, ctx.heap[id].expressions[0])?;

        self.expr_parent = ExpressionParent::None;

        Ok(())

    }

    fn visit_goto_stmt(&mut self, ctx: &mut Ctx, id: GotoStatementId) -> VisitorResult {

        let target_id = self.find_label(ctx, &ctx.heap[id].label)?;

        ctx.heap[id].target = Some(target_id);

        let target = &ctx.heap[target_id];

        if self.in_sync != target.in_sync {

            // We can only goto the current scope or outer scopes. Because

            // nested sync statements are not allowed we must be inside a sync

            // statement.

            debug_assert!(!self.in_sync.is_invalid());

            let goto_stmt = &ctx.heap[id];

            let sync_stmt = &ctx.heap[self.in_sync];

            return Err(

                ParseError::new_error_str_at_span(&ctx.module().source, goto_stmt.span, "goto may not escape the surrounding synchronous block")

                .with_info_str_at_span(&ctx.module().source, target.label.span, "this is the target of the goto statement")

                .with_info_str_at_span(&ctx.module().source, sync_stmt.span, "which will jump past this statement")

            );

        }

        assign_then_erase_next_stmt!(self, ctx, id.upcast());

        Ok(())

    }

    fn visit_new_stmt(&mut self, ctx: &mut Ctx, id: NewStatementId) -> VisitorResult {

        // Make sure the new statement occurs inside a composite component

        if !self.def_type.is_composite() {

            let new_stmt = &ctx.heap[id];

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, new_stmt.span,

                "instantiating components may only be done in composite components"

            ));

        }

        // Recurse into call expression (which will check the expression parent

        // to ensure that the "new" statment instantiates a component)

        let call_expr_id = ctx.heap[id].expression;

        assign_and_replace_next_stmt!(self, ctx, id.upcast());

        debug_assert_eq!(self.expr_parent, ExpressionParent::None);

        self.expr_parent = ExpressionParent::New(id);

        self.visit_call_expr(ctx, call_expr_id)?;

        self.expr_parent = ExpressionParent::None;

        Ok(())

    }

    fn visit_expr_stmt(&mut self, ctx: &mut Ctx, id: ExpressionStatementId) -> VisitorResult {

        let expr_id = ctx.heap[id].expression;

        assign_and_replace_next_stmt!(self, ctx, id.upcast());

        debug_assert_eq!(self.expr_parent, ExpressionParent::None);

        self.expr_parent = ExpressionParent::ExpressionStmt(id);

        self.visit_expr(ctx, expr_id)?;

        self.expr_parent = ExpressionParent::None;

        Ok(())

    }

    //--------------------------------------------------------------------------

    // Expression visitors

    //--------------------------------------------------------------------------

    fn visit_assignment_expr(&mut self, ctx: &mut Ctx, id: AssignmentExpressionId) -> VisitorResult {

        let upcast_id = id.upcast();

        let assignment_expr = &mut ctx.heap[id];

        // Although we call assignment an expression to simplify the compiler's

        // code (mainly typechecking), we disallow nested use in expressions

        match self.expr_parent {

            // Look at us: lying through our teeth while providing error messages.

            ExpressionParent::Memory(_) => {},

            ExpressionParent::ExpressionStmt(_) => {},

            _ => {

                let assignment_span = assignment_expr.full_span;

                return Err(ParseError::new_error_str_at_span(

                    &ctx.module().source, assignment_span,

                    "assignments are statements, and cannot be used in expressions"

                ))

            },

        }

        let left_expr_id = assignment_expr.left;

        let right_expr_id = assignment_expr.right;

        let old_expr_parent = self.expr_parent;

        assignment_expr.parent = old_expr_parent;

        assignment_expr.unique_id_in_definition = self.next_expr_index;

        self.next_expr_index += 1;

        self.expr_parent = ExpressionParent::Expression(upcast_id, 0);

        self.must_be_assignable = Some(assignment_expr.operator_span);

        self.visit_expr(ctx, left_expr_id)?;

        self.expr_parent = ExpressionParent::Expression(upcast_id, 1);

        self.must_be_assignable = None;

        self.visit_expr(ctx, right_expr_id)?;

        self.expr_parent = old_expr_parent;

        Ok(())

    }

    fn visit_binding_expr(&mut self, ctx: &mut Ctx, id: BindingExpressionId) -> VisitorResult {

        let upcast_id = id.upcast();

        // Check for valid context of binding expression

        if let Some(span) = self.must_be_assignable {

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, span, "cannot assign to the result from a binding expression"

            ));

        }

        if self.in_test_expr.is_invalid() {

            let binding_expr = &ctx.heap[id];

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, binding_expr.full_span,

                "binding expressions can only be used inside the testing expression of 'if' and 'while' statements"

            ));

        }

        if !self.in_binding_expr.is_invalid() {

            let binding_expr = &ctx.heap[id];

            let previous_expr = &ctx.heap[self.in_binding_expr];

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, binding_expr.full_span,

                "nested binding expressions are not allowed"

            ).with_info_str_at_span(

                &ctx.module().source, previous_expr.operator_span,

                "the outer binding expression is found here"

            ));

        }

        let mut seeking_parent = self.expr_parent;

        loop {

            // Perform upward search to make sure only LogicalAnd is applied to

            // the binding expression

            let valid = match seeking_parent {

                ExpressionParent::If(_) | ExpressionParent::While(_) => {

                    // Every parent expression (if any) were LogicalAnd.

                    break;

                }

                ExpressionParent::Expression(parent_id, _) => {

                    let parent_expr = &ctx.heap[parent_id];

                    match parent_expr {

                        Expression::Binary(parent_expr) => {

                            // Set new parent to continue the search. Otherwise

                            // halt and provide an error using the current

                            // parent.

                            if parent_expr.operation == BinaryOperator::LogicalAnd {

                                seeking_parent = parent_expr.parent;

                                true

                            } else {

                                false

                            }

                        },

                        _ => false,

                    }

                },

                _ => unreachable!(), // nested under if/while, so always expressions as parents

            };

            if !valid {

                let binding_expr = &ctx.heap[id];

                let parent_expr = &ctx.heap[seeking_parent.as_expression()];

                return Err(ParseError::new_error_str_at_span(

                    &ctx.module().source, binding_expr.full_span,

                    "only the logical-and operator (&&) may be applied to binding expressions"

                ).with_info_str_at_span(

                    &ctx.module().source, parent_expr.operation_span(),

                    "this was the disallowed operation applied to the result from a binding expression"

                ));

            }

        }

        // Perform all of the index/parent assignment magic

        let binding_expr = &mut ctx.heap[id];

        let old_expr_parent = self.expr_parent;

        binding_expr.parent = old_expr_parent;

        binding_expr.unique_id_in_definition = self.next_expr_index;

        self.next_expr_index += 1;

        self.in_binding_expr = id;

        // Perform preliminary check on children: binding expressions only make

        // sense if the left hand side is just a variable expression, or if it

        // is a literal of some sort. The typechecker will take care of the rest

        let bound_to_id = binding_expr.bound_to;

        let bound_from_id = binding_expr.bound_from;

        match &ctx.heap[bound_to_id] {

            // Variables may not be binding variables, and literals may

            // actually not contain binding variables. But in that case we just

            // perform an equality check.

            Expression::Variable(_) => {}

            Expression::Literal(_) => {},

            _ => {

                let binding_expr = &ctx.heap[id];

                return Err(ParseError::new_error_str_at_span(

                    &ctx.module().source, binding_expr.operator_span,

                    "the left hand side of a binding expression may only be a variable or a literal expression"

                ));

            },

        }

        // Visit the children themselves

        self.in_binding_expr_lhs = true;

        self.expr_parent = ExpressionParent::Expression(upcast_id, 0);

        self.visit_expr(ctx, bound_to_id)?;

        self.in_binding_expr_lhs = false;

        self.expr_parent = ExpressionParent::Expression(upcast_id, 1);

        self.visit_expr(ctx, bound_from_id)?;

        self.expr_parent = old_expr_parent;

        self.in_binding_expr = BindingExpressionId::new_invalid();

        Ok(())

    }

    fn visit_conditional_expr(&mut self, ctx: &mut Ctx, id: ConditionalExpressionId) -> VisitorResult {

        let upcast_id = id.upcast();

        let conditional_expr = &mut ctx.heap[id];

        if let Some(span) = self.must_be_assignable {

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, span, "cannot assign to the result from a conditional expression"

            ))

        }

        let test_expr_id = conditional_expr.test;

        let true_expr_id = conditional_expr.true_expression;

        let false_expr_id = conditional_expr.false_expression;

        let old_expr_parent = self.expr_parent;

        conditional_expr.parent = old_expr_parent;

        conditional_expr.unique_id_in_definition = self.next_expr_index;

        self.next_expr_index += 1;

        self.expr_parent = ExpressionParent::Expression(upcast_id, 0);

        self.visit_expr(ctx, test_expr_id)?;

        self.expr_parent = ExpressionParent::Expression(upcast_id, 1);

        self.visit_expr(ctx, true_expr_id)?;

        self.expr_parent = ExpressionParent::Expression(upcast_id, 2);

        self.visit_expr(ctx, false_expr_id)?;

        self.expr_parent = old_expr_parent;

        Ok(())

    }

    fn visit_binary_expr(&mut self, ctx: &mut Ctx, id: BinaryExpressionId) -> VisitorResult {

        let upcast_id = id.upcast();

        let binary_expr = &mut ctx.heap[id];

        if let Some(span) = self.must_be_assignable {

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, span, "cannot assign to the result from a binary expression"

            ))

        }

        let left_expr_id = binary_expr.left;

        let right_expr_id = binary_expr.right;

        let old_expr_parent = self.expr_parent;

        binary_expr.parent = old_expr_parent;

        binary_expr.unique_id_in_definition = self.next_expr_index;

        self.next_expr_index += 1;

        self.expr_parent = ExpressionParent::Expression(upcast_id, 0);

        self.visit_expr(ctx, left_expr_id)?;

        self.expr_parent = ExpressionParent::Expression(upcast_id, 1);

        self.visit_expr(ctx, right_expr_id)?;

        self.expr_parent = old_expr_parent;

        Ok(())

    }

    fn visit_unary_expr(&mut self, ctx: &mut Ctx, id: UnaryExpressionId) -> VisitorResult {

        let unary_expr = &mut ctx.heap[id];

        let expr_id = unary_expr.expression;

        if let Some(span) = self.must_be_assignable {

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, span, "cannot assign to the result from a unary expression"

            ))

        }

        let old_expr_parent = self.expr_parent;

        unary_expr.parent = old_expr_parent;

        unary_expr.unique_id_in_definition = self.next_expr_index;

        self.next_expr_index += 1;

        self.expr_parent = ExpressionParent::Expression(id.upcast(), 0);

        self.visit_expr(ctx, expr_id)?;

        self.expr_parent = old_expr_parent;

        Ok(())

    }

    fn visit_indexing_expr(&mut self, ctx: &mut Ctx, id: IndexingExpressionId) -> VisitorResult {

        let upcast_id = id.upcast();

        let indexing_expr = &mut ctx.heap[id];

        let subject_expr_id = indexing_expr.subject;

        let index_expr_id = indexing_expr.index;

        let old_expr_parent = self.expr_parent;

        indexing_expr.parent = old_expr_parent;

        indexing_expr.unique_id_in_definition = self.next_expr_index;

        self.next_expr_index += 1;

        self.expr_parent = ExpressionParent::Expression(upcast_id, 0);

        self.visit_expr(ctx, subject_expr_id)?;

        let old_assignable = self.must_be_assignable.take();

        self.expr_parent = ExpressionParent::Expression(upcast_id, 1);

        self.visit_expr(ctx, index_expr_id)?;

        self.must_be_assignable = old_assignable;

        self.expr_parent = old_expr_parent;

        Ok(())

    }

    fn visit_slicing_expr(&mut self, ctx: &mut Ctx, id: SlicingExpressionId) -> VisitorResult {

        let upcast_id = id.upcast();

        let slicing_expr = &mut ctx.heap[id];

        if let Some(span) = self.must_be_assignable {

            // TODO: @Slicing

            return Err(ParseError::new_error_str_at_span(

                &ctx.module().source, span, "assignment to slices should be valid in the final language, but is currently not implemented"