nu-plugin 0.92.0

Functionality for building Nushell plugins
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

use super::GetPlugin;
use nu_protocol::{PluginIdentity, ShellError, Span};
use std::sync::{Arc, Weak};

/// The source of a custom value or plugin command. Includes a weak reference to the persistent
/// plugin so it can be retrieved.
///
/// This is not a public interface.
#[derive(Debug, Clone)]
#[doc(hidden)]
pub struct PluginSource {
    /// The identity of the plugin
    pub(crate) identity: Arc<PluginIdentity>,
    /// A weak reference to the persistent plugin that might hold an interface to the plugin.
    ///
    /// This is weak to avoid cyclic references, but it does mean we might fail to upgrade if
    /// the engine state lost the [`PersistentPlugin`] at some point.
    pub(crate) persistent: Weak<dyn GetPlugin>,
}

impl PluginSource {
    /// Create from an implementation of `GetPlugin`
    pub fn new(plugin: Arc<dyn GetPlugin>) -> PluginSource {
        PluginSource {
            identity: plugin.identity().clone().into(),
            persistent: Arc::downgrade(&plugin),
        }
    }

    /// Create a new fake source with a fake identity, for testing
    ///
    /// Warning: [`.persistent()`] will always return an error.
    #[cfg(test)]
    pub(crate) fn new_fake(name: &str) -> PluginSource {
        PluginSource {
            identity: PluginIdentity::new_fake(name).into(),
            persistent: Weak::<crate::PersistentPlugin>::new(),
        }
    }

    /// Try to upgrade the persistent reference, and return an error referencing `span` as the
    /// object that referenced it otherwise
    pub(crate) fn persistent(&self, span: Option<Span>) -> Result<Arc<dyn GetPlugin>, ShellError> {
        self.persistent
            .upgrade()
            .ok_or_else(|| ShellError::GenericError {
                error: format!("The `{}` plugin is no longer present", self.identity.name()),
                msg: "removed since this object was created".into(),
                span,
                help: Some("try recreating the object that came from the plugin".into()),
                inner: vec![],
            })
    }

    /// Sources are compatible if their identities are equal
    pub(crate) fn is_compatible(&self, other: &PluginSource) -> bool {
        self.identity == other.identity
    }
}

impl std::ops::Deref for PluginSource {
    type Target = PluginIdentity;

    fn deref(&self) -> &PluginIdentity {
        &self.identity
    }
}