rune/compile/
meta.rs

1//! Compiler metadata for Rune.
2
3use core::fmt;
4
5#[cfg(feature = "std")]
6use std::path::Path;
7
8use crate as rune;
9use crate::alloc::borrow::Cow;
10use crate::alloc::prelude::*;
11use crate::alloc::{self, Box, Vec};
12use crate::ast;
13use crate::ast::{Span, Spanned};
14use crate::compile::attrs::Parser;
15#[cfg(feature = "doc")]
16use crate::compile::meta;
17use crate::compile::{self, ItemId, Location, MetaInfo, ModId, Pool, Visibility};
18use crate::module::{DocFunction, ModuleItemCommon};
19use crate::parse::ResolveContext;
20use crate::runtime::{Call, FieldMap, Protocol};
21use crate::{Hash, Item, ItemBuf};
22
23/// A meta reference to an item being compiled.
24#[derive(Debug, TryClone, Clone, Copy)]
25#[try_clone(copy)]
26#[non_exhaustive]
27pub struct MetaRef<'a> {
28    /// If the meta comes from the context or not.
29    pub context: bool,
30    /// The hash of a meta item.
31    pub hash: Hash,
32    /// The item being described.
33    pub item: &'a Item,
34    /// The kind of the item.
35    pub kind: &'a Kind,
36    /// The source of the meta.
37    pub source: Option<&'a SourceMeta>,
38}
39
40/// Information on a compile sourc.
41#[derive(Debug, TryClone)]
42#[non_exhaustive]
43pub struct SourceMeta {
44    /// The location of the compile source.
45    pub location: Location,
46    /// The optional path where the meta is declared.
47    #[cfg(feature = "std")]
48    #[cfg_attr(rune_docsrs, doc(cfg(feature = "std")))]
49    pub path: Option<Box<Path>>,
50}
51
52/// Doc content for a compiled item.
53#[derive(Debug, TryClone, Clone, Copy, Spanned)]
54#[try_clone(copy)]
55pub(crate) struct Doc {
56    #[rune(span)]
57    pub(crate) span: Span,
58    /// The string content of the doc comment.
59    pub(crate) doc_string: ast::LitStr,
60}
61
62impl Doc {
63    pub(crate) fn collect_from(
64        cx: ResolveContext<'_, '_>,
65        attrs: &mut Parser,
66        attributes: &[ast::Attribute],
67    ) -> compile::Result<Vec<Doc>> {
68        let docs = attrs
69            .parse_all::<crate::compile::attrs::Doc>(cx, attributes)?
70            .map(|result| {
71                result.map(|(span, doc)| Doc {
72                    span: span.span(),
73                    doc_string: doc.doc_string,
74                })
75            })
76            .try_collect::<compile::Result<_>>()??;
77
78        Ok(docs)
79    }
80}
81
82/// Metadata about a compiled unit.
83#[derive(Debug, TryClone)]
84#[non_exhaustive]
85pub(crate) struct Meta {
86    /// If the meta comes from the context or not.
87    pub(crate) context: bool,
88    /// Hash of the private metadata.
89    pub(crate) hash: Hash,
90    /// The item of the returned compile meta.
91    pub(crate) item_meta: ItemMeta,
92    /// The kind of the compile meta.
93    pub(crate) kind: Kind,
94    /// The source of the meta.
95    pub(crate) source: Option<SourceMeta>,
96    /// Hash parameters for meta.
97    pub(crate) parameters: Hash,
98}
99
100impl Meta {
101    /// Get the [Meta] which describes metadata.
102    pub(crate) fn info(&self, pool: &Pool) -> alloc::Result<MetaInfo> {
103        MetaInfo::new(&self.kind, self.hash, Some(pool.item(self.item_meta.item)))
104    }
105
106    /// Get the [MetaRef] which describes this [meta::Meta] object.
107    pub(crate) fn as_meta_ref<'a>(&'a self, pool: &'a Pool) -> MetaRef<'a> {
108        MetaRef {
109            context: self.context,
110            hash: self.hash,
111            item: pool.item(self.item_meta.item),
112            kind: &self.kind,
113            source: self.source.as_ref(),
114        }
115    }
116
117    /// Get the type hash of the base type (the one to type check for) for the
118    /// given compile meta.
119    ///
120    /// Note: Variants cannot be used for type checking, you should instead
121    /// compare them against the enum type.
122    pub(crate) fn type_hash_of(&self) -> Option<Hash> {
123        match &self.kind {
124            Kind::Type { .. } => Some(self.hash),
125            Kind::Struct {
126                enum_hash: Hash::EMPTY,
127                ..
128            } => Some(self.hash),
129            Kind::Struct { .. } => None,
130            Kind::Enum { .. } => Some(self.hash),
131            Kind::Function { .. } => Some(self.hash),
132            Kind::Closure { .. } => Some(self.hash),
133            Kind::AsyncBlock { .. } => Some(self.hash),
134            Kind::Const => None,
135            Kind::ConstFn => None,
136            Kind::Macro => None,
137            Kind::AttributeMacro => None,
138            Kind::Import { .. } => None,
139            Kind::Alias { .. } => None,
140            Kind::Module => None,
141            Kind::Trait => None,
142        }
143    }
144}
145
146/// The kind of a variant.
147#[derive(Debug, TryClone)]
148pub enum Fields {
149    /// Named fields.
150    Named(FieldsNamed),
151    /// Unnamed fields.
152    Unnamed(usize),
153    /// Empty.
154    Empty,
155}
156
157impl Fields {
158    /// Coerce into a tuple field count.
159    pub(crate) fn as_tuple(&self) -> Option<usize> {
160        match *self {
161            Fields::Unnamed(count) => Some(count),
162            Fields::Empty => Some(0),
163            _ => None,
164        }
165    }
166}
167
168/// Compile-time metadata kind about a unit.
169#[derive(Debug, TryClone)]
170#[non_exhaustive]
171pub enum Kind {
172    /// The type is completely opaque. We have no idea about what it is with the
173    /// exception of it having a type hash.
174    Type {
175        /// Hash of generic parameters.
176        parameters: Hash,
177    },
178    /// Metadata about a struct.
179    Struct {
180        /// Fields information.
181        fields: Fields,
182        /// Native constructor for this struct.
183        constructor: Option<Signature>,
184        /// Hash of generic parameters.
185        parameters: Hash,
186        /// If this is a variant, this is the type hash of the enum.
187        ///
188        /// If this is not a variant, this is [Hash::EMPTY].
189        enum_hash: Hash,
190    },
191    /// An enum item.
192    Enum {
193        /// Hash of generic parameters.
194        parameters: Hash,
195    },
196    /// A macro item.
197    Macro,
198    /// An attribute macro item.
199    AttributeMacro,
200    /// A function declaration.
201    Function {
202        /// The associated kind of the function, if it is an associated
203        /// function.
204        associated: Option<AssociatedKind>,
205        /// The hash of the trait this function is associated with.
206        trait_hash: Option<Hash>,
207        /// Native signature for this function.
208        signature: Signature,
209        /// Whether this function has a `#[test]` annotation
210        is_test: bool,
211        /// Whether this function has a `#[bench]` annotation.
212        is_bench: bool,
213        /// Hash of generic parameters.
214        parameters: Hash,
215        /// The container of the associated function.
216        #[cfg(feature = "doc")]
217        container: Option<Hash>,
218        /// Parameter types.
219        #[cfg(feature = "doc")]
220        parameter_types: Vec<Hash>,
221    },
222    /// A closure.
223    Closure {
224        /// Runtime calling convention.
225        call: Call,
226        /// If the closure moves its environment.
227        do_move: bool,
228    },
229    /// An async block.
230    AsyncBlock {
231        /// Runtime calling convention.
232        call: Call,
233        /// If the async block moves its environment.
234        do_move: bool,
235    },
236    /// The constant expression.
237    Const,
238    /// A constant function.
239    ConstFn,
240    /// Purely an import.
241    Import(Import),
242    /// A re-export.
243    Alias(Alias),
244    /// A module.
245    Module,
246    /// A trait.
247    Trait,
248}
249
250impl Kind {
251    /// Access the underlying signature of the kind, if available.
252    #[cfg(all(feature = "doc", any(feature = "languageserver", feature = "cli")))]
253    pub(crate) fn as_signature(&self) -> Option<&Signature> {
254        match self {
255            Kind::Struct { constructor, .. } => constructor.as_ref(),
256            Kind::Function { signature, .. } => Some(signature),
257            _ => None,
258        }
259    }
260
261    /// Access underlying generic parameters.
262    pub(crate) fn as_parameters(&self) -> Hash {
263        match self {
264            Kind::Function { parameters, .. } => *parameters,
265            Kind::Type { parameters, .. } => *parameters,
266            Kind::Enum { parameters, .. } => *parameters,
267            Kind::Struct { parameters, .. } => *parameters,
268            _ => Hash::EMPTY,
269        }
270    }
271
272    /// Get the associated container of the meta kind.
273    #[cfg(feature = "doc")]
274    pub(crate) fn associated_container(&self) -> Option<Hash> {
275        match *self {
276            Kind::Struct { enum_hash, .. } if enum_hash != Hash::EMPTY => Some(enum_hash),
277            Kind::Function { container, .. } => container,
278            _ => None,
279        }
280    }
281}
282
283/// An imported entry.
284#[derive(Debug, TryClone, Clone, Copy)]
285#[try_clone(copy)]
286#[non_exhaustive]
287pub struct Import {
288    /// The location of the import.
289    pub(crate) location: Location,
290    /// The item being imported.
291    pub(crate) target: ItemId,
292    /// The module in which the imports are located.
293    pub(crate) module: ModId,
294}
295
296/// A context alias.
297#[derive(Debug, TryClone)]
298pub struct Alias {
299    /// The item being aliased.
300    pub(crate) to: ItemBuf,
301}
302
303/// Metadata about named fields.
304#[derive(Debug, TryClone)]
305#[non_exhaustive]
306pub struct FieldsNamed {
307    /// Fields associated with the type.
308    pub(crate) fields: Box<[FieldMeta]>,
309}
310
311impl FieldsNamed {
312    /// Coerce into a hashmap of fields.
313    pub(crate) fn to_fields(&self) -> alloc::Result<FieldMap<Box<str>, usize>> {
314        let mut fields = crate::runtime::new_field_hash_map_with_capacity(self.fields.len())?;
315
316        for f in self.fields.iter() {
317            fields.try_insert(f.name.try_clone()?, f.position)?;
318        }
319
320        Ok(fields)
321    }
322}
323
324/// Metadata for a single named field.
325#[derive(Debug, TryClone)]
326pub struct FieldMeta {
327    /// Position of the field in its containing type declaration.
328    pub(crate) name: Box<str>,
329    /// The position of the field.
330    pub(crate) position: usize,
331}
332
333/// Item and the module that the item belongs to.
334#[derive(Debug, TryClone, Clone, Copy)]
335#[try_clone(copy)]
336#[non_exhaustive]
337pub(crate) struct ItemMeta {
338    /// The location of the item.
339    pub(crate) location: Location,
340    /// The name of the item.
341    pub(crate) item: ItemId,
342    /// The visibility of the item.
343    pub(crate) visibility: Visibility,
344    /// The module associated with the item.
345    pub(crate) module: ModId,
346    /// The impl item associated with the item.
347    pub(crate) impl_item: Option<ItemId>,
348}
349
350impl ItemMeta {
351    /// Test if the item is public (and should be exported).
352    pub(crate) fn is_public(&self, pool: &Pool) -> bool {
353        self.visibility.is_public() && pool.module(self.module).is_public(pool)
354    }
355}
356
357/// A description of a function signature.
358#[derive(Debug, TryClone)]
359pub struct Signature {
360    /// An asynchronous function.
361    #[cfg(feature = "doc")]
362    pub(crate) is_async: bool,
363    /// Arguments to the function.
364    #[cfg(feature = "doc")]
365    pub(crate) arguments: Option<Box<[DocArgument]>>,
366    /// Return type of the function.
367    #[cfg(feature = "doc")]
368    pub(crate) return_type: DocType,
369}
370
371impl Signature {
372    /// Construct a signature from context metadata.
373    #[cfg_attr(not(feature = "doc"), allow(unused_variables))]
374    pub(crate) fn from_context(
375        doc: &DocFunction,
376        common: &ModuleItemCommon,
377    ) -> alloc::Result<Self> {
378        Ok(Self {
379            #[cfg(feature = "doc")]
380            is_async: doc.is_async,
381            #[cfg(feature = "doc")]
382            arguments: context_to_arguments(
383                doc.args,
384                doc.argument_types.as_ref(),
385                common.docs.args(),
386            )?,
387            #[cfg(feature = "doc")]
388            return_type: doc.return_type.try_clone()?,
389        })
390    }
391}
392
393#[cfg(feature = "doc")]
394fn context_to_arguments(
395    args: Option<usize>,
396    types: &[meta::DocType],
397    names: &[String],
398) -> alloc::Result<Option<Box<[meta::DocArgument]>>> {
399    use core::iter;
400
401    let Some(args) = args else {
402        return Ok(None);
403    };
404
405    let len = args.max(types.len()).max(names.len()).max(names.len());
406    let mut out = Vec::try_with_capacity(len)?;
407
408    let mut types = types.iter();
409
410    let names = names
411        .iter()
412        .map(|name| Some(name.as_str()))
413        .chain(iter::repeat(None));
414
415    for (n, name) in (0..len).zip(names) {
416        let empty;
417
418        let ty = match types.next() {
419            Some(ty) => ty,
420            None => {
421                empty = meta::DocType::empty();
422                &empty
423            }
424        };
425
426        out.try_push(meta::DocArgument {
427            name: match name {
428                Some(name) => meta::DocName::Name(Box::try_from(name)?),
429                None => meta::DocName::Index(n),
430            },
431            base: ty.base,
432            generics: ty.generics.try_clone()?,
433        })?;
434    }
435
436    Ok(Some(Box::try_from(out)?))
437}
438
439/// A name inside of a document.
440#[derive(Debug, TryClone)]
441#[cfg(feature = "doc")]
442pub(crate) enum DocName {
443    /// A string name.
444    Name(Box<str>),
445    /// A numbered name.
446    Index(#[try_clone(copy)] usize),
447}
448
449#[cfg(feature = "cli")]
450impl DocName {
451    pub(crate) fn is_self(&self) -> bool {
452        match self {
453            DocName::Name(name) => name.as_ref() == "self",
454            DocName::Index(..) => false,
455        }
456    }
457}
458
459#[cfg(feature = "doc")]
460impl fmt::Display for DocName {
461    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
462        match self {
463            DocName::Name(name) => write!(f, "{name}"),
464            DocName::Index(index) if *index == 0 => write!(f, "value"),
465            DocName::Index(index) => write!(f, "value{index}"),
466        }
467    }
468}
469
470/// A description of a type.
471#[derive(Debug, TryClone)]
472#[cfg(feature = "doc")]
473pub(crate) struct DocArgument {
474    /// The name of an argument.
475    pub(crate) name: DocName,
476    /// The base type.
477    pub(crate) base: Hash,
478    /// Generic parameters.
479    pub(crate) generics: Box<[DocType]>,
480}
481
482/// A description of a type.
483#[derive(Default, Debug, TryClone)]
484pub struct DocType {
485    /// The base type.
486    #[cfg(feature = "doc")]
487    pub(crate) base: Hash,
488    /// Generic parameters.
489    #[cfg(feature = "doc")]
490    pub(crate) generics: Box<[DocType]>,
491}
492
493impl DocType {
494    /// Construct an empty type documentation.
495    pub(crate) fn empty() -> Self {
496        Self::new(Hash::EMPTY)
497    }
498
499    /// Construct type documentation.
500    #[cfg_attr(not(feature = "doc"), allow(unused_variables))]
501    pub fn with_generics<const N: usize>(
502        base: Hash,
503        generics: [DocType; N],
504    ) -> alloc::Result<Self> {
505        Ok(Self {
506            #[cfg(feature = "doc")]
507            base,
508            #[cfg(feature = "doc")]
509            generics: Box::try_from(generics)?,
510        })
511    }
512
513    /// Construct type with the specified base type.
514    #[cfg_attr(not(feature = "doc"), allow(unused_variables))]
515    pub(crate) fn new(base: Hash) -> Self {
516        Self {
517            #[cfg(feature = "doc")]
518            base,
519            #[cfg(feature = "doc")]
520            generics: Box::default(),
521        }
522    }
523}
524
525/// The kind of an associated function.
526#[derive(Debug, TryClone, PartialEq, Eq, Hash)]
527#[non_exhaustive]
528pub enum AssociatedKind {
529    /// A protocol function implemented on the type itself.
530    Protocol(&'static Protocol),
531    /// A field function with the given protocol.
532    FieldFn(&'static Protocol, Cow<'static, str>),
533    /// An index function with the given protocol.
534    IndexFn(&'static Protocol, usize),
535    /// The instance function refers to the given named instance fn.
536    Instance(Cow<'static, str>),
537}
538
539impl AssociatedKind {
540    /// Convert the kind into a hash function.
541    pub(crate) fn hash(&self, instance_type: Hash) -> Hash {
542        match self {
543            Self::Protocol(protocol) => Hash::associated_function(instance_type, protocol.hash),
544            Self::IndexFn(protocol, index) => {
545                Hash::index_function(protocol.hash, instance_type, Hash::index(*index))
546            }
547            Self::FieldFn(protocol, field) => {
548                Hash::field_function(protocol.hash, instance_type, field.as_ref())
549            }
550            Self::Instance(name) => Hash::associated_function(instance_type, name.as_ref()),
551        }
552    }
553}
554
555impl fmt::Display for AssociatedKind {
556    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
557        match self {
558            AssociatedKind::Protocol(protocol) => write!(f, "<{}>", protocol.name),
559            AssociatedKind::FieldFn(protocol, field) => {
560                write!(f, ".{field}<{}>", protocol.name)
561            }
562            AssociatedKind::IndexFn(protocol, index) => {
563                write!(f, ".{index}<{}>", protocol.name)
564            }
565            AssociatedKind::Instance(name) => write!(f, "{name}"),
566        }
567    }
568}
rune/compile/meta.rs

rune/compile/
meta.rs
