emacs 0.21.0

Rust library for creating Emacs's dynamic modules
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
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208

use std::borrow::BorrowMut;

use emacs_module::emacs_value;
use emacs_macros;

use crate::{Env, Value, Result, IntoLisp, global::{GlobalRef, OnceGlobalRef}};

// TODO: Seal this trait, for safety reasons.
pub unsafe trait IntoLispArgs<'e> {
    type LispArgs: BorrowMut<[emacs_value]>;

    fn into_lisp_args(self, env: &'e Env) -> Result<Self::LispArgs>;
}

impl<'e> Value<'e> {
    /// Calls this value with the given arguments. An error is signaled if it is actually not a
    /// Lisp's callable.
    ///
    /// `args` should be an array/slice of `Value`, or a tuple of different types, each implementing
    /// [`IntoLisp`].
    ///
    /// # Examples
    ///
    /// ```
    /// # use emacs::{defun, Value, Result, Vector};
    /// #[defun]
    /// fn mapc_enumerate_vec(function: Value, vector: Vector) -> Result<()> {
    ///     for (nth, elem) in vector.into_iter().enumerate() {
    ///         function.call((nth, elem))?;
    ///     }
    ///     Ok(())
    /// }
    /// ```
    ///
    /// [`IntoLisp`]: trait.IntoLisp.html
    #[inline]
    pub fn call<A>(self, args: A) -> Result<Value<'e>> where A: IntoLispArgs<'e> {
        // Safety: The returned value is explicitly protected.
        unsafe { self.call_unprotected(args).map(|v| v.protect()) }
    }

    /// Like [`call`], except that the returned `Value` is not protected against
    /// Emacs GC's [bug #31238], which caused [issue #2].
    ///
    /// # Safety
    ///
    /// This can be used as an optimization, in situations when the returned `Value` is unused,
    /// or when its usage is shorter than the lifespan of the underlying Lisp object.
    ///
    /// [`call`]: #method.call
    /// [bug #31238]: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=31238
    /// [issue #2]: https://github.com/ubolonton/emacs-module-rs/issues/2
    #[allow(unused_unsafe)]
    pub unsafe fn call_unprotected<A>(self, args: A) -> Result<Value<'e>> where A: IntoLispArgs<'e> {
        let env = self.env;
        let mut lisp_args = args.into_lisp_args(env)?;
        let lisp_args: &mut [emacs_value] = lisp_args.borrow_mut();
        let ptr = lisp_args.as_mut_ptr();
        let length = lisp_args.len() as isize;
        // Safety:
        // - ptr comes from a locally-owned value.
        // - length is ensured to be valid by IntoLispArgs implementation.
        unsafe_raw_call_value_unprotected!(env, funcall, self.raw, length, ptr)
    }
}

pub trait IntoLispCallable<'e> {
    fn into_lisp_callable(self, env: &'e Env) -> Result<Value<'e>>;
}

impl Env {
    /// Calls a Lisp function, passing the given arguments.
    ///
    /// - `func` should be a string, or a Lisp's callable [`Value`] (in which case [`func.call`]
    /// is preferable). An error is signaled otherwise.
    /// - `args` should be an array/slice of [`Value`], or a tuple of different types, each
    /// implementing [`IntoLisp`].
    ///
    /// # Examples
    ///
    /// ```
    /// # use emacs::{defun, Value, Result, Vector};
    /// #[defun]
    /// fn listify_vec(vector: Vector) -> Result<Value> {
    ///     let env = vector.value().env;
    ///     let mut args = vec![];
    ///     for elem in vector {
    ///         args.push(elem)
    ///     }
    ///     env.call("list", &args)
    /// }
    /// ```
    ///
    /// [`Value`]: struct.Value.html
    /// [`func.call`]: struct.Value.html#method.call
    /// [`IntoLisp`]: trait.IntoLisp.html
    #[inline]
    pub fn call<'e, F, A>(&'e self, func: F, args: A) -> Result<Value<'_>>
        where
            F: IntoLispCallable<'e>,
            A: IntoLispArgs<'e>,
    {
        func.into_lisp_callable(self)?.call(args)
    }

    /// Like [`call`], except that the returned [`Value`] is not protected against
    /// Emacs GC's [bug #31238], which caused [issue #2].
    ///
    /// # Safety
    ///
    /// This can be used as an optimization, in situations when the returned [`Value`] is unused,
    /// or when its usage is shorter than the lifespan of the underlying Lisp object.
    ///
    /// [`call`]: #method.call
    /// [`Value`]: struct.Value.html
    /// [bug #31238]: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=31238
    /// [issue #2]: https://github.com/ubolonton/emacs-module-rs/issues/2
    #[inline]
    pub unsafe fn call_unprotected<'e, F, A>(&'e self, func: F, args: A) -> Result<Value<'_>>
        where
            F: IntoLispCallable<'e>,
            A: IntoLispArgs<'e>,
    {
        func.into_lisp_callable(self)?.call_unprotected(args)
    }
}

impl GlobalRef {
    /// Calls this reference's value with the given arguments. An error is signaled if it is
    /// actually not a Lisp's callable.
    ///
    /// `args` should be an array/slice of `Value`, or a tuple of different types, each implementing
    /// [`IntoLisp`].
    ///
    /// [`IntoLisp`]: trait.IntoLisp.html
    #[inline]
    pub fn call<'e, A>(&'e self, env: &'e Env, args: A) -> Result<Value<'_>>
        where
            A: IntoLispArgs<'e>,
    {
        self.bind(env).call(args)
    }

    /// Like [`call`], except that the returned [`Value`] is not protected against
    /// Emacs GC's [bug #31238], which caused [issue #2].
    ///
    /// # Safety
    ///
    /// This can be used as an optimization, in situations when the returned [`Value`] is unused,
    /// or when its usage is shorter than the lifespan of the underlying Lisp object.
    ///
    /// [`call`]: #method.call
    /// [`Value`]: struct.Value.html
    /// [bug #31238]: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=31238
    /// [issue #2]: https://github.com/ubolonton/emacs-module-rs/issues/2
    #[inline]
    pub unsafe fn call_unprotected<'e, A>(&'e self, env: &'e Env, args: A) -> Result<Value<'_>>
        where
            A: IntoLispArgs<'e>,
    {
        self.bind(env).call_unprotected(args)
    }
}

// We can implement IntoLispArgs for IntoLisp types (after breaking up this implementation).
// However, that would prevent implementing IntoLisp for arrays and tuples. It is a choice between
// the convenience of not having to use (,) when calling functions with 1 argument, and the
// convenience of not having to use .into_lisp(env)? when returning an array/tuple from a #[defun].
// TODO: Check again when specialization lands: https://github.com/rust-lang/rust/issues/31844.
unsafe impl<'e, T: AsRef<[Value<'e>]> + ?Sized> IntoLispArgs<'e> for &T {
    type LispArgs = Vec<emacs_value>;

    fn into_lisp_args(self, _: &'e Env) -> Result<Self::LispArgs> {
        Ok(self.as_ref().iter().map(|v| v.raw).collect())
    }
}

emacs_macros::impl_lisp_args_for_tuples!(12);

emacs_macros::impl_lisp_args_for_arrays!(12);

impl<'e> IntoLispCallable<'e> for Value<'e> {
    #[inline(always)]
    fn into_lisp_callable(self, _: &'e Env) -> Result<Value<'e>> {
        Ok(self)
    }
}

impl<'e, T: AsRef<str>> IntoLispCallable<'e> for T {
    #[inline(always)]
    fn into_lisp_callable(self, env: &'e Env) -> Result<Value<'e>> {
        env.intern(self.as_ref())
    }
}

impl<'e> IntoLispCallable<'e> for &'e GlobalRef {
    #[inline(always)]
    fn into_lisp_callable(self, env: &'e Env) -> Result<Value<'e>> {
        self.bind(env).into_lisp_callable(env)
    }
}

impl<'e> IntoLispCallable<'e> for &'e OnceGlobalRef {
    #[inline(always)]
    fn into_lisp_callable(self, env: &'e Env) -> Result<Value<'e>> {
        self.bind(env).into_lisp_callable(env)
    }
}