cairo_lang_defs/

plugin.rs

use std::any::{self, Any};
use std::ops::Deref;
use std::sync::Arc;

use cairo_lang_diagnostics::Severity;
use cairo_lang_filesystem::cfg::CfgSet;
use cairo_lang_filesystem::db::Edition;
use cairo_lang_filesystem::ids::CodeMapping;
use cairo_lang_filesystem::span::TextWidth;
use cairo_lang_syntax::node::db::SyntaxGroup;
use cairo_lang_syntax::node::ids::SyntaxStablePtrId;
use cairo_lang_syntax::node::{SyntaxNode, ast};
use cairo_lang_utils::ordered_hash_set::OrderedHashSet;
use serde::{Deserialize, Serialize};
use smol_str::SmolStr;

/// A trait for arbitrary data that a macro generates along with the generated file.
#[typetag::serde]
pub trait GeneratedFileAuxData: std::fmt::Debug + Sync + Send {
    fn as_any(&self) -> &dyn Any;
    fn eq(&self, other: &dyn GeneratedFileAuxData) -> bool;
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct DynGeneratedFileAuxData(pub Arc<dyn GeneratedFileAuxData>);
impl DynGeneratedFileAuxData {
    pub fn new<T: GeneratedFileAuxData + 'static>(aux_data: T) -> Self {
        DynGeneratedFileAuxData(Arc::new(aux_data))
    }
}
impl Deref for DynGeneratedFileAuxData {
    type Target = Arc<dyn GeneratedFileAuxData>;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}
impl PartialEq for DynGeneratedFileAuxData {
    fn eq(&self, that: &DynGeneratedFileAuxData) -> bool {
        GeneratedFileAuxData::eq(&*self.0, &*that.0)
    }
}
impl Eq for DynGeneratedFileAuxData {}

/// Virtual code file generated by a plugin.
pub struct PluginGeneratedFile {
    /// Name for the virtual file. Will appear in diagnostics.
    pub name: SmolStr,
    /// Code content for the file.
    pub content: String,
    /// A code mapper, to allow more readable diagnostics that originate in plugin generated
    /// virtual files.
    pub code_mappings: Vec<CodeMapping>,
    /// Arbitrary data that the plugin generates along with the file.
    pub aux_data: Option<DynGeneratedFileAuxData>,
    /// Diagnostic note for the plugin generated file.
    /// This will be used as [`cairo_lang_diagnostics::DiagnosticNote`] on diagnostics originating
    /// from this file.
    pub diagnostics_note: Option<String>,
    /// This needs to be set to true if the plugin is unhygienic, i.e. it does not preserve
    /// variable hygiene.
    pub is_unhygienic: bool,
}

/// Result of plugin code generation.
#[derive(Default)]
pub struct PluginResult {
    /// Filename, content.
    pub code: Option<PluginGeneratedFile>,
    /// Diagnostics.
    pub diagnostics: Vec<PluginDiagnostic>,
    /// If true - the original item should be removed, if false - it should remain as is.
    pub remove_original_item: bool,
}

/// A diagnostic generated by a plugin.
#[derive(Clone, Debug, Eq, Hash, PartialEq)]
pub struct PluginDiagnostic {
    /// The stable pointer of the syntax node that caused the diagnostic.
    pub stable_ptr: SyntaxStablePtrId,
    pub message: String,
    /// The severity of the diagnostic.
    pub severity: Severity,
    /// An optional inner span inside the stable pointer that caused the diagnostic. Useful for
    /// diagnostics caused by inline macros, since the syntax of the arguments is a token tree and
    /// is not segmented into each argument.
    /// The tuple is (offset, width).
    pub inner_span: Option<(TextWidth, TextWidth)>,
}
impl PluginDiagnostic {
    pub fn error(stable_ptr: impl Into<SyntaxStablePtrId>, message: String) -> PluginDiagnostic {
        PluginDiagnostic {
            stable_ptr: stable_ptr.into(),
            message,
            severity: Severity::Error,
            inner_span: None,
        }
    }

    /// Creates a diagnostic, pointing to an inner span inside the given stable pointer.
    pub fn error_with_inner_span(
        db: &dyn SyntaxGroup,
        stable_ptr: impl Into<SyntaxStablePtrId>,
        inner_span: SyntaxNode,
        message: String,
    ) -> PluginDiagnostic {
        let stable_ptr = stable_ptr.into();
        let offset = inner_span.offset(db) - stable_ptr.lookup(db).offset(db);
        let width = inner_span.width(db);
        PluginDiagnostic {
            stable_ptr,
            message,
            severity: Severity::Error,
            inner_span: Some((offset, width)),
        }
    }

    pub fn warning(stable_ptr: impl Into<SyntaxStablePtrId>, message: String) -> PluginDiagnostic {
        PluginDiagnostic {
            stable_ptr: stable_ptr.into(),
            message,
            severity: Severity::Warning,
            inner_span: None,
        }
    }
}

/// A structure containing additional info about the current module item on which macro plugin
/// operates.
pub struct MacroPluginMetadata<'a> {
    /// Config set of the crate to which the current item belongs.
    pub cfg_set: &'a CfgSet,
    /// The possible derives declared by any plugin.
    pub declared_derives: &'a OrderedHashSet<String>,
    /// The allowed features at the macro activation site.
    pub allowed_features: &'a OrderedHashSet<SmolStr>,
    /// The edition of the crate to which the current item belongs.
    pub edition: Edition,
}

// TODO(spapini): Move to another place.
/// A trait for a macro plugin: external plugin that generates additional code for items.
pub trait MacroPlugin: std::fmt::Debug + Sync + Send + Any {
    /// Generates code for an item. If no code should be generated returns None.
    /// Otherwise, returns (virtual_module_name, module_content), and a virtual submodule
    /// with that name and content should be created.
    fn generate_code(
        &self,
        db: &dyn SyntaxGroup,
        item_ast: ast::ModuleItem,
        metadata: &MacroPluginMetadata<'_>,
    ) -> PluginResult;

    /// Attributes this plugin uses.
    /// Attributes the plugin uses without declaring here are likely to cause a compilation error
    /// for unknown attribute.
    /// Note: They may not cause a diagnostic if some other plugin declares such attribute, but
    /// plugin writers should not rely on that.
    fn declared_attributes(&self) -> Vec<String>;

    /// Derives this plugin supplies.
    /// Any derived classes the plugin supplies without declaring here are likely to cause a
    /// compilation error for unknown derive.
    /// Note: They may not cause a diagnostic if some other plugin declares such derive, but
    /// plugin writers should not rely on that.
    fn declared_derives(&self) -> Vec<String> {
        Vec::new()
    }

    /// Attributes that should mark the function as an executable.
    /// Functions marked with executable attributes will be listed
    /// in a dedicated field in the generated program.
    /// Must return a subset of `declared_attributes`.
    /// This mechanism is optional.
    fn executable_attributes(&self) -> Vec<String> {
        Vec::new()
    }

    /// Attributes that mark a type as a phantom type. Must return a subset of
    /// `declared_attributes`.
    /// This mechanism is optional.
    fn phantom_type_attributes(&self) -> Vec<String> {
        Vec::new()
    }

    /// A `TypeId` of the plugin, used to compare the concrete types
    /// of plugins given as trait objects.
    fn plugin_type_id(&self) -> any::TypeId {
        self.type_id()
    }
}

/// Result of plugin code generation.
#[derive(Default)]
pub struct InlinePluginResult {
    pub code: Option<PluginGeneratedFile>,
    /// Diagnostics.
    pub diagnostics: Vec<PluginDiagnostic>,
}

pub trait InlineMacroExprPlugin: std::fmt::Debug + Sync + Send + Any {
    /// Generates code for an item. If no code should be generated returns None.
    /// Otherwise, returns (virtual_module_name, module_content), and a virtual submodule
    /// with that name and content should be created.
    fn generate_code(
        &self,
        db: &dyn SyntaxGroup,
        item_ast: &ast::ExprInlineMacro,
        metadata: &MacroPluginMetadata<'_>,
    ) -> InlinePluginResult;

    /// Allows for the plugin to provide documentation for an inline macro.
    fn documentation(&self) -> Option<String> {
        None
    }

    /// A `TypeId` of the plugin, used to compare the concrete types
    /// of plugins given as trait objects.
    fn plugin_type_id(&self) -> any::TypeId {
        self.type_id()
    }
}

/// A trait for easier addition of macro plugins.
pub trait NamedPlugin: Default + 'static {
    const NAME: &'static str;
}