endbasic-core 0.13.0

// EndBASIC
// Copyright 2021 Julio Merino
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.

//! Symbol definitions and symbols table representation.

use crate::ast::ArgSep;
use crate::ast::ExprType;
use crate::bytecode::TaggedRegisterRef;
use crate::bytecode::VarArgTag;
use crate::mem::HeapOverflowError;
use crate::mem::{ConstantDatum, DatumPtr, Heap, HeapDatum};
use crate::reader::LineCol;
use async_trait::async_trait;
use std::borrow::Cow;
use std::fmt;
use std::io;
use std::ops::RangeInclusive;
use std::rc::Rc;
use std::str::Lines;

/// Error types for callable execution.
#[derive(Debug, thiserror::Error)]
pub enum CallError {
    /// Invalid callable argument.
    #[error("{0}")]
    Argument(String),

    /// Runtime evaluation error.
    #[error("{0}")]
    Eval(String),

    /// I/O error.
    #[error("{0}")]
    IoError(#[from] io::Error),

    /// Callable precondition failure.
    #[error("{0}")]
    Precondition(String),

    /// Indicates a syntax error only detectable at runtime.
    #[error("{0}: {1}")]
    Syntax(LineCol, String),
}

impl From<HeapOverflowError> for CallError {
    fn from(value: HeapOverflowError) -> Self {
        Self::Eval(value.to_string())
    }
}

impl CallError {
    /// Converts this call error to an upcall error with a mandatory position.
    ///
    /// If the error does not carry an origin position on its own, uses
    /// `default_pos`.
    pub(crate) fn to_upcall_error(&self, default_pos: LineCol) -> UpcallError {
        match self {
            CallError::Argument(message) => UpcallError::Argument(default_pos, message.clone()),

            CallError::Eval(message) => UpcallError::Eval(default_pos, message.clone()),

            CallError::IoError(e) => UpcallError::IoError(default_pos, e.to_string()),

            CallError::Precondition(message) => {
                UpcallError::Precondition(default_pos, message.clone())
            }

            CallError::Syntax(pos, message) => UpcallError::Syntax(*pos, message.clone()),
        }
    }
}

/// Result type for callable execution.
pub type CallResult<T> = Result<T, CallError>;

/// Error type for uncaught upcall failures.
///
/// This should be the same as `CallError` but with all error variants annotated with a position.
#[derive(Debug, thiserror::Error)]
pub enum UpcallError {
    /// Invalid callable argument at a given source location.
    #[error("{0}: {1}")]
    Argument(LineCol, String),

    /// Runtime evaluation error at a given source location.
    #[error("{0}: {1}")]
    Eval(LineCol, String),

    /// I/O error at a given source location.
    #[error("{0}: {1}")]
    IoError(LineCol, String),

    /// Callable precondition failure at a given source location.
    #[error("{0}: {1}")]
    Precondition(LineCol, String),

    /// Runtime syntax error at a specific source location.
    #[error("{0}: {1}")]
    Syntax(LineCol, String),
}

impl UpcallError {
    /// Returns the source position and message of this error.
    pub fn parts(&self) -> (LineCol, String) {
        match self {
            UpcallError::Argument(pos, message) => (*pos, message.clone()),
            UpcallError::Eval(pos, message) => (*pos, message.clone()),
            UpcallError::IoError(pos, message) => (*pos, message.clone()),
            UpcallError::Precondition(pos, message) => (*pos, message.clone()),
            UpcallError::Syntax(pos, message) => (*pos, message.clone()),
        }
    }
}

/// Syntax specification for a required scalar parameter.
#[derive(Clone, Debug, PartialEq)]
pub struct RequiredValueSyntax {
    /// The name of the parameter for help purposes.
    pub name: Cow<'static, str>,

    /// The type of the expected parameter.
    pub vtype: ExprType,
}

/// Syntax specification for a required reference parameter.
#[derive(Clone, Debug, PartialEq)]
pub struct RequiredRefSyntax {
    /// The name of the parameter for help purposes.
    pub name: Cow<'static, str>,

    /// If true, require an array reference; if false, a variable reference.
    pub require_array: bool,

    /// If true, allow references to undefined variables because the command will define them when
    /// missing.  Can only be set to true for commands, not functions, and `require_array` must be
    /// false.
    pub define_undefined: bool,
}

/// Syntax specification for an optional scalar parameter.
///
/// Optional parameters are only supported in commands.
#[derive(Clone, Debug, PartialEq)]
pub struct OptionalValueSyntax {
    /// The name of the parameter for help purposes.
    pub name: Cow<'static, str>,

    /// The type of the expected parameter.
    pub vtype: ExprType,
}

/// Specifies the type constraints for a repeated parameter.
#[derive(Clone, Debug, PartialEq)]
pub enum RepeatedTypeSyntax {
    /// Allows any value type, including empty arguments.  The values pushed onto the stack have
    /// the same semantics as those pushed by `AnyValueSyntax`.
    AnyValue,

    /// Expects a value of the given type.
    TypedValue(ExprType),

    /// Expects a reference to a variable (not an array) and allows the variables to not be defined.
    VariableRef,
}

/// Syntax specification for a repeated parameter.
///
/// The repeated parameter must appear after all singular positional parameters.
#[derive(Clone, Debug, PartialEq)]
pub struct RepeatedSyntax {
    /// The name of the parameter for help purposes.
    pub name: Cow<'static, str>,

    /// The type of the expected parameters.
    pub type_syn: RepeatedTypeSyntax,

    /// The separator to expect between the repeated parameters.  For functions, this must be the
    /// long separator (the comma).
    pub sep: ArgSepSyntax,

    /// Whether the repeated parameter must at least have one element or not.
    pub require_one: bool,

    /// Whether to allow any parameter to not be present or not.  Can only be true for commands.
    pub allow_missing: bool,
}

impl RepeatedSyntax {
    /// Formats the repeated argument syntax for help purposes into `output`.
    ///
    /// `last_singular_sep` contains the separator of the last singular argument syntax, if any,
    /// which we need to place inside of the optional group.
    fn describe(&self, output: &mut String, last_singular_sep: Option<&ArgSepSyntax>) {
        if !self.require_one {
            output.push('[');
        }

        if let Some(sep) = last_singular_sep {
            sep.describe(output);
        }

        output.push_str(&self.name);
        output.push('1');
        if let RepeatedTypeSyntax::TypedValue(vtype) = self.type_syn {
            output.push(vtype.annotation());
        }

        if self.require_one {
            output.push('[');
        }

        self.sep.describe(output);
        output.push_str("..");
        self.sep.describe(output);

        output.push_str(&self.name);
        output.push('N');
        if let RepeatedTypeSyntax::TypedValue(vtype) = self.type_syn {
            output.push(vtype.annotation());
        }

        output.push(']');
    }
}

/// Syntax specification for a parameter that accepts any scalar type.
#[derive(Clone, Debug, PartialEq)]
pub struct AnyValueSyntax {
    /// The name of the parameter for help purposes.
    pub name: Cow<'static, str>,

    /// Whether to allow the parameter to not be present or not.  Can only be true for commands.
    pub allow_missing: bool,
}

/// Specifies the expected argument separator in a callable's syntax.
#[derive(Copy, Clone, Debug, PartialEq)]
pub enum ArgSepSyntax {
    /// The argument separator must exactly be the one given.
    Exactly(ArgSep),

    /// The argument separator may be any of the ones given.
    OneOf(&'static [ArgSep]),

    /// The argument separator is the end of the call.
    End,
}

impl ArgSepSyntax {
    /// Formats the argument separator for help purposes into `output`.
    fn describe(&self, output: &mut String) {
        match self {
            ArgSepSyntax::Exactly(sep) => {
                let (text, needs_space) = sep.describe();

                if !text.is_empty() && needs_space {
                    output.push(' ');
                }
                output.push_str(text);
                if !text.is_empty() {
                    output.push(' ');
                }
            }

            ArgSepSyntax::OneOf(seps) => {
                output.push_str(" <");
                for (i, sep) in seps.iter().enumerate() {
                    let (text, _needs_space) = sep.describe();
                    output.push_str(text);
                    if i < seps.len() - 1 {
                        output.push('|');
                    }
                }
                output.push_str("> ");
            }

            ArgSepSyntax::End => (),
        };
    }
}

/// Syntax specification for a non-repeated argument.
///
/// Every item in this enum is composed of a struct that provides the details on the parameter and
/// a struct that provides the details on how this parameter is separated from the next.
#[derive(Clone, Debug, PartialEq)]
pub enum SingularArgSyntax {
    /// A required scalar value with the syntax details and the separator that follows.
    RequiredValue(RequiredValueSyntax, ArgSepSyntax),

    /// A required reference with the syntax details and the separator that follows.
    RequiredRef(RequiredRefSyntax, ArgSepSyntax),

    /// An optional scalar value with the syntax details and the separator that follows.
    OptionalValue(OptionalValueSyntax, ArgSepSyntax),

    /// A required scalar value of any type with the syntax details and the separator that follows.
    AnyValue(AnyValueSyntax, ArgSepSyntax),
}

/// Complete syntax specification for a callable's arguments.
///
/// Note that the description of function arguments is more restricted than that of commands.
/// The arguments compiler panics when these preconditions aren't met with the rationale that
/// builtin functions must never be ill-defined.
// TODO(jmmv): It might be nice to try to express these restrictions in the type system, but
// things are already too verbose as they are...
#[derive(Clone, Debug, PartialEq)]
pub(crate) struct CallableSyntax {
    /// Ordered list of singular arguments that appear before repeated arguments.
    pub(crate) singular: Cow<'static, [SingularArgSyntax]>,

    /// Details on the repeated argument allowed after singular arguments, if any.
    pub(crate) repeated: Option<Cow<'static, RepeatedSyntax>>,
}

impl CallableSyntax {
    /// Creates a new callable arguments definition from its parts defined statically in the
    /// code.
    pub(crate) fn new_static(
        singular: &'static [SingularArgSyntax],
        repeated: Option<&'static RepeatedSyntax>,
    ) -> Self {
        Self { singular: Cow::Borrowed(singular), repeated: repeated.map(Cow::Borrowed) }
    }

    /// Creates a new callable arguments definition from its parts defined dynamically at
    /// runtime.
    pub(crate) fn new_dynamic(
        singular: Vec<SingularArgSyntax>,
        repeated: Option<RepeatedSyntax>,
    ) -> Self {
        Self { singular: Cow::Owned(singular), repeated: repeated.map(Cow::Owned) }
    }

    /// Computes the range of the expected number of parameters for this syntax.
    pub(crate) fn expected_nargs(&self) -> RangeInclusive<usize> {
        let mut min = self.singular.len();
        let mut max = self.singular.len();

        if let Some(syn) = self.repeated.as_ref() {
            if syn.require_one {
                min += 1;
            }
            max = usize::MAX;
        }

        min..=max
    }

    /// Returns true if this syntax represents "no arguments".
    pub(crate) fn is_empty(&self) -> bool {
        self.singular.is_empty() && self.repeated.is_none()
    }

    /// Produces a user-friendly description of this callable syntax.
    pub(crate) fn describe(&self) -> String {
        let mut description = String::new();
        let mut last_singular_sep = None;
        for (i, s) in self.singular.iter().enumerate() {
            let sep = match s {
                SingularArgSyntax::RequiredValue(details, sep) => {
                    description.push_str(&details.name);
                    description.push(details.vtype.annotation());
                    sep
                }

                SingularArgSyntax::RequiredRef(details, sep) => {
                    description.push_str(&details.name);
                    sep
                }

                SingularArgSyntax::OptionalValue(details, sep) => {
                    description.push('[');
                    description.push_str(&details.name);
                    description.push(details.vtype.annotation());
                    description.push(']');
                    sep
                }

                SingularArgSyntax::AnyValue(details, sep) => {
                    if details.allow_missing {
                        description.push('[');
                    }
                    description.push_str(&details.name);
                    if details.allow_missing {
                        description.push(']');
                    }
                    sep
                }
            };

            if self.repeated.is_none() || i < self.singular.len() - 1 {
                sep.describe(&mut description);
            }
            if i == self.singular.len() - 1 {
                last_singular_sep = Some(sep);
            }
        }

        if let Some(syn) = &self.repeated {
            syn.describe(&mut description, last_singular_sep);
        }

        description
    }
}

/// Builder pattern for constructing a callable's metadata.
pub struct CallableMetadataBuilder {
    /// Name of the callable, stored in uppercase.
    name: Cow<'static, str>,

    /// Return type of the callable, or `None` for commands/subroutines.
    return_type: Option<ExprType>,

    /// Whether this callable requires asynchronous dispatch.
    is_async: bool,

    /// Category for grouping related callables in help messages.
    category: Option<&'static str>,

    /// Syntax specifications for the callable's arguments.
    syntaxes: Vec<CallableSyntax>,

    /// Description of the callable for documentation purposes.
    description: Option<&'static str>,
}

impl CallableMetadataBuilder {
    /// Constructs a new metadata builder with the minimum information necessary.
    ///
    /// All code except tests must populate the whole builder with details.  This is enforced at
    /// construction time, where we only allow some fields to be missing under the test
    /// configuration.
    pub fn new(name: &'static str) -> Self {
        assert!(name == name.to_ascii_uppercase(), "Callable name must be in uppercase");

        Self {
            name: Cow::Borrowed(name),
            return_type: None,
            is_async: false,
            syntaxes: vec![],
            category: None,
            description: None,
        }
    }

    /// Constructs a new metadata builder with the minimum information necessary.
    ///
    /// This is the same as `new` but using a dynamically-allocated name, which is necessary for
    /// user-defined symbols.
    pub fn new_dynamic<S: Into<String>>(name: S) -> Self {
        Self {
            name: Cow::Owned(name.into().to_ascii_uppercase()),
            return_type: None,
            is_async: false,
            syntaxes: vec![],
            category: Some("User defined"),
            description: Some("User defined symbol."),
        }
    }

    /// Sets the return type of the callable.
    pub fn with_return_type(mut self, return_type: ExprType) -> Self {
        self.return_type = Some(return_type);
        self
    }

    /// Sets whether this callable requires asynchronous dispatch.
    pub fn with_async(mut self, is_async: bool) -> Self {
        self.is_async = is_async;
        self
    }

    /// Sets the syntax specifications for this callable.
    pub fn with_syntax(
        mut self,
        syntaxes: &'static [(&'static [SingularArgSyntax], Option<&'static RepeatedSyntax>)],
    ) -> Self {
        self.syntaxes = syntaxes
            .iter()
            .map(|s| CallableSyntax::new_static(s.0, s.1))
            .collect::<Vec<CallableSyntax>>();
        self
    }

    /// Sets the syntax specifications for this callable.
    pub(crate) fn with_syntaxes<S: Into<Vec<CallableSyntax>>>(mut self, syntaxes: S) -> Self {
        self.syntaxes = syntaxes.into();
        self
    }

    /// Sets the syntax specifications for this callable.
    pub(crate) fn with_dynamic_syntax(
        self,
        syntaxes: Vec<(Vec<SingularArgSyntax>, Option<RepeatedSyntax>)>,
    ) -> Self {
        let syntaxes = syntaxes
            .into_iter()
            .map(|s| CallableSyntax::new_dynamic(s.0, s.1))
            .collect::<Vec<CallableSyntax>>();
        self.with_syntaxes(syntaxes)
    }

    /// Sets the category for this callable.  All callables with the same category name will be
    /// grouped together in help messages.
    pub fn with_category(mut self, category: &'static str) -> Self {
        self.category = Some(category);
        self
    }

    /// Sets the description for this callable.  The `description` is a collection of paragraphs
    /// separated by a single newline character, where the first paragraph is taken as the summary
    /// of the description.  The summary must be a short sentence that is descriptive enough to be
    /// understood without further details.  Empty lines (paragraphs) are not allowed.
    pub fn with_description(mut self, description: &'static str) -> Self {
        for l in description.lines() {
            assert!(!l.is_empty(), "Description cannot contain empty lines");
        }
        self.description = Some(description);
        self
    }

    /// Generates the final `CallableMetadata` object, ensuring all values are present.
    pub fn build(self) -> Rc<CallableMetadata> {
        assert!(!self.syntaxes.is_empty(), "All callables must specify a syntax");
        Rc::from(CallableMetadata {
            name: self.name,
            return_type: self.return_type,
            is_async: self.is_async,
            syntaxes: self.syntaxes,
            category: self.category.expect("All callables must specify a category"),
            description: self.description.expect("All callables must specify a description"),
        })
    }

    /// Generates the final `CallableMetadata` object, ensuring the minimal set of values are
    /// present.  Only useful for testing.
    pub fn test_build(mut self) -> Rc<CallableMetadata> {
        if self.syntaxes.is_empty() {
            self.syntaxes.push(CallableSyntax::new_static(&[], None));
        }
        Rc::from(CallableMetadata {
            name: self.name,
            return_type: self.return_type,
            is_async: self.is_async,
            syntaxes: self.syntaxes,
            category: self.category.unwrap_or(""),
            description: self.description.unwrap_or(""),
        })
    }
}

/// Representation of a callable's metadata.
///
/// The callable is expected to hold onto an instance of this object within its struct to make
/// queries fast.
#[derive(Clone, Debug, PartialEq)]
pub struct CallableMetadata {
    /// Name of the callable, stored in uppercase.
    name: Cow<'static, str>,

    /// Return type of the callable, or `None` for commands/subroutines.
    return_type: Option<ExprType>,

    /// Whether this callable requires asynchronous dispatch.
    is_async: bool,

    /// Syntax specifications for the callable's arguments.
    syntaxes: Vec<CallableSyntax>,

    /// Category for grouping related callables in help messages.
    category: &'static str,

    /// Description of the callable for documentation purposes.
    description: &'static str,
}

impl CallableMetadata {
    /// Gets the callable's name, all in uppercase.
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Gets the callable's return type.
    pub fn return_type(&self) -> Option<ExprType> {
        self.return_type
    }

    /// Gets whether this callable requires asynchronous dispatch.
    pub fn is_async(&self) -> bool {
        self.is_async
    }

    /// Gets the callable's syntax specification.
    pub fn syntax(&self) -> String {
        fn format_one(cs: &CallableSyntax) -> String {
            let mut syntax = cs.describe();
            if syntax.is_empty() {
                syntax.push_str("no arguments");
            }
            syntax
        }

        match self.syntaxes.as_slice() {
            [] => panic!("Callables without syntaxes are not allowed at construction time"),
            [one] => format_one(one),
            many => many
                .iter()
                .map(|syn| format!("<{}>", syn.describe()))
                .collect::<Vec<String>>()
                .join(" | "),
        }
    }

    /// Returns true if `sep` is valid for a function call (only `Long` and `End` are allowed because
    /// the parser only produces comma separators for function arguments).
    fn is_function_sep(sep: &ArgSepSyntax) -> bool {
        match sep {
            ArgSepSyntax::Exactly(ArgSep::Long) | ArgSepSyntax::End => true,
            ArgSepSyntax::OneOf(seps) => seps.iter().all(|s| *s == ArgSep::Long),
            _ => false,
        }
    }

    /// Checks that the syntax of a callable that returns a value only uses separators that can appear
    /// in a function call (i.e. the comma separator).  The parser only produces `ArgSep::Long` for
    /// function arguments, so any other separator in the metadata would be dead/untestable.
    fn debug_assert_function_seps(&self, syntax: &CallableSyntax) {
        if self.return_type().is_none() {
            return;
        }
        for syn in syntax.singular.iter() {
            let sep = match syn {
                SingularArgSyntax::RequiredValue(_, sep) => sep,
                SingularArgSyntax::RequiredRef(_, sep) => sep,
                SingularArgSyntax::OptionalValue(_, sep) => sep,
                SingularArgSyntax::AnyValue(_, sep) => sep,
            };
            debug_assert!(
                Self::is_function_sep(sep),
                "Function {} has a non-comma separator in its singular args syntax",
                self.name()
            );
        }
        if let Some(repeated) = syntax.repeated.as_ref() {
            debug_assert!(
                Self::is_function_sep(&repeated.sep),
                "Function {} has a non-comma separator in its repeated args syntax",
                self.name()
            );
        }
    }

    /// Finds the syntax definition that matches the given argument count.
    ///
    /// Returns an error if no syntax matches, and panics if multiple syntaxes match (which would
    /// indicate an ambiguous callable definition).
    pub(crate) fn find_syntax(&self, nargs: usize) -> Option<&CallableSyntax> {
        let mut matches = self.syntaxes.iter().filter(|s| s.expected_nargs().contains(&nargs));
        let syntax = matches.next();
        match syntax {
            Some(syntax) => {
                debug_assert!(matches.next().is_none(), "Ambiguous syntax definitions");
                if cfg!(debug_assertions) {
                    self.debug_assert_function_seps(syntax);
                }
                Some(syntax)
            }
            None => None,
        }
    }

    /// Gets the callable's category as a collection of lines.  The first line is the title of the
    /// category, and any extra lines are additional information for it.
    #[allow(unused)]
    pub fn category(&self) -> &'static str {
        self.category
    }

    /// Gets the callable's textual description as a collection of lines.  The first line is the
    /// summary of the callable's purpose.
    #[allow(unused)]
    pub fn description(&self) -> Lines<'static> {
        self.description.lines()
    }

    /// Returns true if this is a callable that takes no arguments.
    #[allow(unused)]
    pub fn is_argless(&self) -> bool {
        self.syntaxes.is_empty() || (self.syntaxes.len() == 1 && self.syntaxes[0].is_empty())
    }

    /// Returns true if this callable is a function (not a command).
    #[allow(unused)]
    pub(crate) fn is_function(&self) -> bool {
        self.return_type.is_some()
    }

    /// Returns true if this callable is user-defined.
    pub(crate) fn is_user_defined(&self) -> bool {
        self.category == "User defined"
    }
}

/// Reads a boolean from the register at `index`, asserting that `vtype` is `Boolean`.
fn deref_boolean(regs: &[u64], index: usize, vtype: ExprType) -> bool {
    assert_eq!(ExprType::Boolean, vtype);
    regs[index] != 0
}

/// Reads a double from the register at `index`, asserting that `vtype` is `Double`.
fn deref_double(regs: &[u64], index: usize, vtype: ExprType) -> f64 {
    assert_eq!(ExprType::Double, vtype);
    f64::from_bits(regs[index])
}

/// Reads an integer from the register at `index`, asserting that `vtype` is `Integer`.
fn deref_integer(regs: &[u64], index: usize, vtype: ExprType) -> i32 {
    assert_eq!(ExprType::Integer, vtype);
    regs[index] as i32
}

/// Reads a string from the register at `index`, asserting that `vtype` is `Text`.
fn deref_string<'a>(
    regs: &[u64],
    index: usize,
    vtype: ExprType,
    constants: &'a [ConstantDatum],
    heap: &'a Heap,
) -> &'a str {
    assert_eq!(ExprType::Text, vtype);
    let ptr = DatumPtr::from(regs[index]);
    ptr.resolve_string(constants, heap)
}

/// Dereferences this register reference as an array and returns its dimensions.
fn array_dimensions<'a>(regs: &'a [u64], index: usize, heap: &'a Heap) -> &'a [usize] {
    let ptr = DatumPtr::from(regs[index]);
    let heap_idx = ptr.heap_index();
    let HeapDatum::Array(a) = heap.get(heap_idx) else {
        panic!("Scalar variable does not point to an array on the heap");
    };
    &a.dimensions
}

/// An immutable reference to a variable (register) in the register file, carrying
/// its type for runtime validation of dereference operations.
pub struct RegisterRef<'a, 'vm> {
    /// The scope through which to access the register.
    scope: &'a Scope<'vm>,

    /// The absolute index of the register.
    index: usize,

    /// The type of the value pointed to.
    pub vtype: ExprType,
}

impl<'a, 'vm> RegisterRef<'a, 'vm> {
    /// Dereferences this register reference as a boolean.
    pub fn deref_boolean(&self) -> bool {
        deref_boolean(self.scope.regs, self.index, self.vtype)
    }

    /// Dereferences this register reference as a double.
    pub fn deref_double(&self) -> f64 {
        deref_double(self.scope.regs, self.index, self.vtype)
    }

    /// Dereferences this register reference as an integer.
    pub fn deref_integer(&self) -> i32 {
        deref_integer(self.scope.regs, self.index, self.vtype)
    }

    /// Dereferences this register reference as a string.
    pub fn deref_string(&self) -> &str {
        deref_string(self.scope.regs, self.index, self.vtype, self.scope.constants, self.scope.heap)
    }

    /// Dereferences this register reference as an array and returns its dimensions.
    pub fn array_dimensions(&self) -> &[usize] {
        array_dimensions(self.scope.regs, self.index, self.scope.heap)
    }
}

impl<'a, 'vm> fmt::Display for RegisterRef<'a, 'vm> {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "&[R{}]{}", self.index, self.vtype)
    }
}

/// A mutable reference to a variable (register) in the register file, carrying
/// its type for runtime validation of dereference and set operations.
pub struct RegisterRefMut<'a, 'vm> {
    /// The scope through which to access the register.
    scope: &'a mut Scope<'vm>,

    /// The absolute index of the register.
    index: usize,

    /// The type of the value pointed to.
    pub vtype: ExprType,
}

impl<'a, 'vm> RegisterRefMut<'a, 'vm> {
    /// Dereferences this register reference as a boolean.
    pub fn deref_boolean(&self) -> bool {
        deref_boolean(self.scope.regs, self.index, self.vtype)
    }

    /// Dereferences this register reference as a double.
    pub fn deref_double(&self) -> f64 {
        deref_double(self.scope.regs, self.index, self.vtype)
    }

    /// Dereferences this register reference as an integer.
    pub fn deref_integer(&self) -> i32 {
        deref_integer(self.scope.regs, self.index, self.vtype)
    }

    /// Dereferences this register reference as a string.
    pub fn deref_string(&self) -> &str {
        deref_string(self.scope.regs, self.index, self.vtype, self.scope.constants, self.scope.heap)
    }

    /// Dereferences this register reference as an array and returns its dimensions.
    pub fn array_dimensions(&self) -> &[usize] {
        array_dimensions(self.scope.regs, self.index, self.scope.heap)
    }

    /// Sets a boolean via this register reference.
    pub fn set_boolean(&mut self, b: bool) {
        assert_eq!(ExprType::Boolean, self.vtype);
        self.scope.regs[self.index] = if b { 1 } else { 0 };
    }

    /// Sets a double via this register reference.
    pub fn set_double(&mut self, d: f64) {
        assert_eq!(ExprType::Double, self.vtype);
        self.scope.regs[self.index] = d.to_bits();
    }

    /// Sets an integer via this register reference.
    pub fn set_integer(&mut self, i: i32) {
        assert_eq!(ExprType::Integer, self.vtype);
        self.scope.regs[self.index] = i as u64;
    }

    /// Sets a string via this register reference.
    pub fn set_string<S: Into<String>>(&mut self, s: S) -> CallResult<()> {
        assert_eq!(ExprType::Text, self.vtype);
        self.scope.regs[self.index] = self.scope.heap.push(HeapDatum::Text(s.into()))?;
        Ok(())
    }
}

impl<'a, 'vm> fmt::Display for RegisterRefMut<'a, 'vm> {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "&[R{}]{}", self.index, self.vtype)
    }
}

/// Arguments provided to a callable during its execution.
pub struct Scope<'a> {
    /// Slice of register values containing the callable's arguments.
    pub(crate) regs: &'a mut [u64],

    /// Reference to the constants pool for resolving constant pointers.
    pub(crate) constants: &'a [ConstantDatum],

    /// Reference to the heap for resolving heap pointers.
    pub(crate) heap: &'a mut Heap,

    /// Start of the current frame (where the arguments to the upcall start).
    pub(crate) fp: usize,

    /// Number of register slots to skip before the first argument.
    ///
    /// For commands, this is 0 because the first register slot holds the first argument.  For
    /// functions, this is 1 because the first register slot holds the return value and arguments
    /// start at slot 1.  The `get_*` methods add this offset to their register accesses so that
    /// both commands and functions can use index 0 to refer to the first argument.
    pub(crate) arg_offset: usize,

    /// Source locations of the call arguments, one per argument in encounter order.
    ///
    /// Indexed by logical argument number: `arg_linecols[0]` is the source position of the first
    /// argument.  Does not include an entry for the function return value slot.  May be shorter
    /// than the actual argument count if debug information is unavailable.
    pub(crate) arg_linecols: &'a [LineCol],

    /// Last error raised in the VM, if any.
    pub(crate) last_error: &'a Option<(LineCol, String)>,

    /// `DATA` values captured from the compiled source.
    pub(crate) data: &'a [Option<ConstantDatum>],
}

impl<'a> Scope<'a> {
    /// Returns `DATA` values captured from the compiled source in encounter order.
    pub fn data(&self) -> &[Option<ConstantDatum>] {
        self.data
    }

    /// Returns the total number of argument register slots.
    pub fn nargs(&self) -> usize {
        self.arg_linecols.len()
    }

    /// Returns the source position of the argument at `arg`.
    ///
    /// `arg` is the logical argument index, matching the `N` in `scope.get_*(N)`.
    pub fn get_pos(&self, arg: u8) -> LineCol {
        self.arg_linecols[usize::from(arg)]
    }

    /// Gets the type tag of the argument at `arg`.
    pub fn get_type(&self, arg: u8) -> VarArgTag {
        VarArgTag::parse_u64(self.regs[self.fp + self.arg_offset + (arg as usize)]).unwrap()
    }

    /// Gets the boolean value of the argument at `arg`.
    pub fn get_boolean(&self, arg: u8) -> bool {
        self.regs[self.fp + self.arg_offset + (arg as usize)] != 0
    }

    /// Gets the double value of the argument at `arg`.
    pub fn get_double(&self, arg: u8) -> f64 {
        f64::from_bits(self.regs[self.fp + self.arg_offset + (arg as usize)])
    }

    /// Gets the integer value of the argument at `arg`.
    pub fn get_integer(&self, arg: u8) -> i32 {
        self.regs[self.fp + self.arg_offset + (arg as usize)] as i32
    }

    /// Gets an immutable register reference from the argument at `arg`.
    pub fn get_ref(&self, arg: u8) -> RegisterRef<'_, 'a> {
        let tagged_ptr = self.regs[self.fp + self.arg_offset + (arg as usize)];
        let (index, vtype) = TaggedRegisterRef::from_u64(tagged_ptr).parse();
        RegisterRef { scope: self, index, vtype }
    }

    /// Gets a mutable register reference from the argument at `arg`.
    pub fn get_mut_ref(&mut self, arg: u8) -> RegisterRefMut<'_, 'a> {
        let tagged_ptr = self.regs[self.fp + self.arg_offset + (arg as usize)];
        let (index, vtype) = TaggedRegisterRef::from_u64(tagged_ptr).parse();
        RegisterRefMut { scope: self, index, vtype }
    }

    /// Gets the string value of the argument at `arg`.
    pub fn get_string(&self, arg: u8) -> &str {
        let index = self.regs[self.fp + self.arg_offset + (arg as usize)];
        let ptr = DatumPtr::from(index);
        ptr.resolve_string(self.constants, self.heap)
    }

    /// Returns the last error stored in the VM, if any.
    pub fn last_error(&self) -> Option<(LineCol, &str)> {
        self.last_error.as_ref().map(|(pos, message)| (*pos, message.as_str()))
    }

    /// Sets the return value of the function to `b`.
    ///
    /// Always returns success.  The returned value is only to support the idiomatic invocation
    /// `return scope.return_boolean(...)`.
    pub fn return_boolean(self, b: bool) -> CallResult<()> {
        self.regs[self.fp] = if b { 1 } else { 0 };
        Ok(())
    }

    /// Sets the return value of the function to `d`.
    ///
    /// Always returns success.  The returned value is only to support the idiomatic invocation
    /// `return scope.return_double(...)`.
    pub fn return_double(self, d: f64) -> CallResult<()> {
        self.regs[self.fp] = d.to_bits();
        Ok(())
    }

    /// Sets the return value of the function to `i`.
    ///
    /// Always returns success.  The returned value is only to support the idiomatic invocation
    /// `return scope.return_integer(...)`.
    pub fn return_integer(self, i: i32) -> CallResult<()> {
        self.regs[self.fp] = i as u64;
        Ok(())
    }

    /// Sets the return value of the function to `s`.
    ///
    /// Always returns success.  The returned value is only to support the idiomatic invocation
    /// `return scope.return_string(...)`.
    pub fn return_string<S: Into<String>>(self, s: S) -> CallResult<()> {
        self.regs[self.fp] = self.heap.push(HeapDatum::Text(s.into()))?;
        Ok(())
    }
}

/// A trait to define a callable that is executed by a `Machine`.
///
/// The callable themselves are immutable but they can reference mutable state.  Given that
/// EndBASIC is not threaded, it is sufficient for those references to be behind a `RefCell`
/// and/or an `Rc`.
///
/// Idiomatically, these objects need to provide a `new()` method that returns an `Rc<Callable>`, as
/// that's the type used throughout the execution engine.
#[async_trait(?Send)]
pub trait Callable {
    /// Returns the metadata for this function.
    ///
    /// The return value takes the form of a reference to force the callable to store the metadata
    /// as a struct field so that calls to this function are guaranteed to be cheap.
    fn metadata(&self) -> Rc<CallableMetadata>;

    /// Executes the callable if it is synchronous.
    fn exec(&self, _scope: Scope<'_>) -> CallResult<()> {
        unimplemented!("Must be implemented for !is_async callables")
    }

    /// Executes the callable if it is asynchronous.
    async fn async_exec(&self, _scope: Scope<'_>) -> CallResult<()> {
        unimplemented!("Must be implemented for is_async callables")
    }
}