tokel_engine/

session.rs

//! The evaluation context for Tokel macro expansions.
//!
//! A [`Session`] represents a single, temporary run of the Tokel engine. It holds the
//! [`Registry`] of available transformers and maintains their internal state throughout
//! the bottom-up evaluation of an abstract syntax tree.
//!
//! Because transformers can be stateful (e.g., counters or accumulators), creating a
//! fresh [`Session`] for each macro invocation ensures that state is cleanly isolated
//! and automatically dropped when the expansion is complete.

use crate::transform::Registry;

/// The execution context for a Tokel expansion.
///
/// This struct holds the active [`Registry`] and is responsible for evaluating
/// `TokelStream`s. By default, it is pre-loaded with Tokel's standard built-in
/// transformers, but it can be customized or strictly sandboxed as needed.
#[derive(Debug, Default)]
pub struct Session(Registry);

impl Session {
    /// Creates a new [`Session`] populated with the default [`Registry`].
    ///
    /// This includes all standard Tokel transformers (e.g., `identity`, `case`).
    /// This is the primary constructor used by standard `tokel::stream!` invocations.
    #[inline]
    #[must_use]
    pub fn new() -> Self {
        Self::new_with(Registry::default())
    }

    /// Creates a [`Session`] using a specific, pre-configured [`Registry`].
    ///
    /// This is useful if you want to initialize a registry, heavily customize it,
    /// and then pass it into the session for execution.
    #[inline]
    #[must_use]
    pub const fn new_with(registry: Registry) -> Self {
        Self(registry)
    }

    /// Creates a completely blank [`Session`] with an empty [`Registry`].
    ///
    /// This session will have no built-in transformers available. It is useful
    /// for creating strictly controlled, domain-specific token manipulation APIs
    /// where users are only allowed to use custom transformers you explicitly provide.
    #[inline]
    #[must_use]
    pub fn empty() -> Self {
        Self(Registry::empty())
    }

    /// Borrows the active [`Registry`] for this [`Session`].
    #[inline]
    #[must_use]
    pub const fn registry(&self) -> &Registry {
        let Self(target_value) = self;

        target_value
    }

    /// Mutably borrows the active [`Registry`] for this [`Session`].
    ///
    /// This allows you to register new custom transformers or extract state from
    /// existing ones during or after the session's lifecycle.
    #[inline]
    #[must_use]
    pub const fn registry_mut(&mut self) -> &mut Registry {
        let Self(target_value) = self;

        target_value
    }
}

#[cfg(test)]
mod tests {
    use crate::prelude::*;
    use proc_macro2::TokenStream;
    use quote::quote;

    /// A helper to assert that two token streams are syntactically identical,
    /// ignoring raw whitespace differences generated by `to_string()`.
    fn assert_streams_eq(actual: TokenStream, expected: TokenStream) {
        let actual_str = actual.to_string().replace(" ", "");
        let expected_str = expected.to_string().replace(" ", "");
        assert_eq!(
            actual_str,
            expected_str,
            "\nExpected: {}\nGot:      {}",
            expected.to_string(),
            actual.to_string()
        );
    }

    /// Reverses the token stream.
    #[derive(Debug)]
    struct DummyReverse;

    impl Transformer for DummyReverse {
        fn transform(
            &mut self,
            input: TokenStream,
            _args: TokenStream,
        ) -> Result<TokenStream, syn::Error> {
            let mut tokens: Vec<_> = input.into_iter().collect();
            tokens.reverse();

            Ok(tokens.into_iter().collect())
        }
    }

    /// Appends the provided argument to the token stream.
    #[derive(Debug)]
    struct DummyAppend;
    impl Transformer for DummyAppend {
        fn transform(
            &mut self,
            mut input: TokenStream,
            args: TokenStream,
        ) -> Result<TokenStream, syn::Error> {
            input.extend(args);
            Ok(input)
        }
    }

    /// A stateful counter that outputs the current count.
    #[derive(Default, Debug)]
    struct DummyCount(usize);
    impl Transformer for DummyCount {
        fn transform(
            &mut self,
            _input: TokenStream,
            _args: TokenStream,
        ) -> Result<TokenStream, syn::Error> {
            let count = self.0;
            self.0 += 1;
            // Output the number as a raw token
            let count_str = count.to_string();
            let lit: proc_macro2::Literal = syn::parse_str(&count_str).unwrap();
            Ok(quote!(#lit))
        }
    }

    /// A transformer that deliberately returns an error if called.
    #[derive(Debug)]
    struct DummyError;
    impl Transformer for DummyError {
        fn transform(
            &mut self,
            input: TokenStream,
            _args: TokenStream,
        ) -> Result<TokenStream, syn::Error> {
            // Find the first token to attach the error span to, or use call_site
            let span = input
                .into_iter()
                .next()
                .map(|t| t.span())
                .unwrap_or_else(proc_macro2::Span::call_site);
            Err(syn::Error::new(span, "Deliberate test error"))
        }
    }

    #[test]
    fn test_standard_rust_passthrough() {
        let mut session = Session::empty();

        let input = quote! {
            pub fn process_data(data: &[u8]) -> Result<(), Error> {
                let x = 10 + 20;
                Ok(())
            }
        };

        let ast: TokelStream = syn::parse2(input.clone()).unwrap();
        let output = ast.expand(&mut session).expect("Failed to expand");

        assert_streams_eq(output, input);
    }

    #[test]
    fn test_identity_block_resolution() {
        let mut session = Session::empty();

        // An expansion block with no transformers attached should just dissolve the `< >`
        let input = quote! {
            let val = [< 10 + 20 >];
        };

        let ast: TokelStream = syn::parse2(input).unwrap();
        let output = ast.expand(&mut session).unwrap();

        let expected = quote! {
            let val = 10 + 20;
        };

        assert_streams_eq(output, expected);
    }

    #[test]
    fn test_single_transformer_with_args() {
        let mut session = Session::empty();
        session
            .registry_mut()
            .try_insert("append", DummyAppend)
            .unwrap();

        let input = quote! {
            let word = [< hello >]:append[[ _world ]];
        };

        let ast: TokelStream = syn::parse2(input).unwrap();
        let output = ast.expand(&mut session).unwrap();

        let expected = quote! {
            let word = hello _world;
        };

        assert_streams_eq(output, expected);
    }

    #[test]
    fn test_pipeline_chaining() {
        let mut session = Session::empty();
        session
            .registry_mut()
            .try_insert("append", DummyAppend)
            .unwrap();
        session
            .registry_mut()
            .try_insert("reverse", DummyReverse)
            .unwrap();

        // Note the order of execution:
        // 1. [< a b >] resolves to `a b`
        // 2. :append[[ c ]] makes it `a b c`
        // 3. :reverse makes it `c b a`
        let input = quote! { [< a b >]:append[[c]]:reverse };

        let ast: TokelStream = syn::parse2(input).unwrap();
        let output = ast.expand(&mut session).unwrap();

        let expected = quote! { c b a };
        assert_streams_eq(output, expected);
    }

    #[test]
    fn test_deep_bottom_up_nesting() {
        let mut session = Session::empty();
        session
            .registry_mut()
            .try_insert("append", DummyAppend)
            .unwrap();
        session
            .registry_mut()
            .try_insert("reverse", DummyReverse)
            .unwrap();

        // Inner block: [< a b >]:reverse -> `b a`
        // Middle block: [< (b a) c >]:append[[d]] -> `b a c d`
        // Outer block: reverse -> `d c a b`
        let input = quote! {
            [< [< [< a b >]:reverse c >]:append[[d]] >]:reverse
        };

        let ast: TokelStream = syn::parse2(input).unwrap();
        let output = ast.expand(&mut session).unwrap();

        let expected = quote! { d c a b };
        assert_streams_eq(output, expected);
    }

    #[test]
    fn test_stateful_session_isolation() {
        let mut session = Session::empty();
        session
            .registry_mut()
            .try_insert("count", DummyCount::default())
            .unwrap();

        // Each invocation of :count should increment the internal state.
        // The order of bottom-up evaluation determines the assignment!
        let input = quote! {
            let first = [< >]:count;
            let second = [< >]:count;
            let inner_wins = [< [< >]:count >]:count;
        };

        let ast: TokelStream = syn::parse2(input).unwrap();
        let output = ast.expand(&mut session).unwrap();

        // first = 0
        // second = 1
        // inner_wins evaluates the inner block first (2), then the outer block replaces it with (3).
        let expected = quote! {
            let first = 0;
            let second = 1;
            let inner_wins = 3;
        };

        assert_streams_eq(output, expected);
    }

    #[test]
    fn test_transformer_error_propagation() {
        let mut session = Session::empty();
        session
            .registry_mut()
            .try_insert("error_out", DummyError)
            .unwrap();

        let input = quote! {
            fn good() {}
            [< bad_tokens >]:error_out
        };

        let ast: TokelStream = syn::parse2(input).unwrap();
        let result = ast.expand(&mut session);

        assert!(
            result.is_err(),
            "Engine failed to bubble up the transformer error"
        );
        assert_eq!(result.unwrap_err().to_string(), "Deliberate test error");
    }

    #[test]
    fn test_unknown_transformer_error() {
        let mut session = Session::empty();
        // Registry is intentionally empty

        let input = quote! { [< x >]:non_existent_transformer };

        let ast: TokelStream = syn::parse2(input).unwrap();
        let result = ast.expand(&mut session);

        assert!(result.is_err());
        let err_msg = result.unwrap_err().to_string();
        assert!(
            err_msg.contains("non_existent_transformer"),
            "Error message should mention the missing transformer"
        );
    }

    #[test]
    fn test_nested_arguments() {
        let mut session = Session::empty();
        session
            .registry_mut()
            .try_insert("append", DummyAppend)
            .unwrap();
        session
            .registry_mut()
            .try_insert("reverse", DummyReverse)
            .unwrap();

        // Testing that the `[[ ... ]]` arguments are ALSO evaluated as a TokelStream!
        // The argument is `[< 1 2 >]:reverse`, which evaluates to `2 1`.
        // The main block `A B` then appends `2 1`.
        let input = quote! {
            [< A B >]:append[[ [< 1 2 >]:reverse ]]
        };

        let ast: TokelStream = syn::parse2(input).unwrap();
        let output = ast.expand(&mut session).unwrap();

        let expected = quote! { A B 2 1 };
        assert_streams_eq(output, expected);
    }
}