harn-vm 0.8.1

Async bytecode virtual machine for the Harn programming language
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

use std::borrow::Cow;

/// Runtime kind for a registered VM builtin.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum VmBuiltinKind {
    Sync,
    Async,
}

/// Lightweight arity metadata for registered builtins.
///
/// This is descriptive metadata only. Runtime behavior still flows through
/// the existing parser/typechecker and builtin handlers.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum VmBuiltinArity {
    Exact(usize),
    Min(usize),
    Range { min: usize, max: usize },
    Variadic,
}

/// Discoverable metadata for a VM builtin.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct VmBuiltinMetadata {
    name: Cow<'static, str>,
    kind: VmBuiltinKind,
    signature: Option<Cow<'static, str>>,
    arity: Option<VmBuiltinArity>,
    category: Option<Cow<'static, str>>,
    doc: Option<Cow<'static, str>>,
}

impl VmBuiltinMetadata {
    pub fn sync(name: impl Into<Cow<'static, str>>) -> Self {
        Self::new(name, VmBuiltinKind::Sync)
    }

    pub fn async_builtin(name: impl Into<Cow<'static, str>>) -> Self {
        Self::new(name, VmBuiltinKind::Async)
    }

    pub const fn sync_static(name: &'static str) -> Self {
        Self::new_static(name, VmBuiltinKind::Sync)
    }

    pub const fn async_static(name: &'static str) -> Self {
        Self::new_static(name, VmBuiltinKind::Async)
    }

    fn new(name: impl Into<Cow<'static, str>>, kind: VmBuiltinKind) -> Self {
        Self {
            name: name.into(),
            kind,
            signature: None,
            arity: None,
            category: None,
            doc: None,
        }
    }

    const fn new_static(name: &'static str, kind: VmBuiltinKind) -> Self {
        Self {
            name: Cow::Borrowed(name),
            kind,
            signature: None,
            arity: None,
            category: None,
            doc: None,
        }
    }

    pub(crate) fn with_kind(mut self, kind: VmBuiltinKind) -> Self {
        self.kind = kind;
        self
    }

    pub fn signature_static(mut self, signature: &'static str) -> Self {
        self.signature = Some(Cow::Borrowed(signature));
        self
    }

    pub fn signature_owned(mut self, signature: impl Into<Cow<'static, str>>) -> Self {
        self.signature = Some(signature.into());
        self
    }

    pub fn arity(mut self, arity: VmBuiltinArity) -> Self {
        self.arity = Some(arity);
        self
    }

    pub fn category_static(mut self, category: &'static str) -> Self {
        self.category = Some(Cow::Borrowed(category));
        self
    }

    pub fn category_owned(mut self, category: impl Into<Cow<'static, str>>) -> Self {
        self.category = Some(category.into());
        self
    }

    pub fn doc_static(mut self, doc: &'static str) -> Self {
        self.doc = Some(Cow::Borrowed(doc));
        self
    }

    pub fn doc_owned(mut self, doc: impl Into<Cow<'static, str>>) -> Self {
        self.doc = Some(doc.into());
        self
    }

    pub fn name(&self) -> &str {
        self.name.as_ref()
    }

    pub fn kind(&self) -> VmBuiltinKind {
        self.kind
    }

    pub fn signature(&self) -> Option<&str> {
        self.signature.as_deref()
    }

    pub fn arity_metadata(&self) -> Option<VmBuiltinArity> {
        self.arity
    }

    pub fn category(&self) -> Option<&str> {
        self.category.as_deref()
    }

    pub fn doc(&self) -> Option<&str> {
        self.doc.as_deref()
    }
}