overture/
macros.rs

1// Created by Sean L. on Jun. 23.
2// Last Updated by Sean L. on Jun. 23.
3// 
4// overture.rs
5// src/macros.rs
6// 
7// Makabaka1880, 2025. All rights reserved.
8
9//! A collection of macros used throughout the Overture rendering framework.
10//!
11//! These macros assist in building renderable lists, styling chains,
12//! and conveniently wrapping values in `Some`.
13
14/// This module provides a collection of procedural macros to simplify the construction
15/// of common data structures and patterns used throughout the overture crate.
16/// 
17/// # Provided Macros
18/// 
19/// - [`renderable_list!`]: Constructs a `RenderableList` from a sequence of renderable expressions,
20///   expanding to a linked-list-like structure.
21/// - [`style!`]: Builds a recursive style chain using `RenderStyle::Styled`, with a fallback to `RenderStyle::Plain`.
22/// - [`some!`]: A convenience macro for wrapping a value in `Option::Some`.
23/// 
24/// These macros are designed to improve ergonomics and reduce boilerplate when working with
25/// renderable lists, style chains, and optional values in the overture ecosystem.
26pub mod macros {
27    /// Constructs a `RenderableList` using a list of renderable expressions.
28    ///
29    /// This macro expands to a linked list-like structure using
30    /// `RenderableList::Link` and `RenderableList::Nil`.
31    ///
32    /// # Examples
33    ///
34    /// ```rust
35    /// use overture::prelude::*;
36    /// 
37    /// let list = renderable_list![
38    ///     DummyRenderable,
39    ///     DummyRenderable
40    /// ];
41    ///
42    /// match list {
43    ///     RenderableList::Link(_, _) => { /* success */ },
44    ///     _ => panic!("Expected a linked list"),
45    /// }
46    /// ```
47    #[macro_export]
48    macro_rules! renderable_list {
49        () => {
50            $crate::interfaces::containers::RenderableList::Nil
51        };
52        ($head:expr $(, $tail:expr)* $(,)?) => {
53            $crate::interfaces::containers::RenderableList::Link(
54                Box::new($head),
55                Box::new(renderable_list![$($tail),*])
56            )
57        };
58    }
59
60    /// Constructs a `RenderStyle` by chaining style elements.
61    ///
62    /// This macro builds up a recursive style chain using
63    /// `RenderStyle::Styled`, with the final fallback being `RenderStyle::Plain`.
64    ///
65    /// # Examples
66    ///
67    /// ```rust
68    /// use overture::prelude::*;
69    ///
70    /// let style_chain = style![ANSISequence::Bold, ANSISequence::Underline];
71    ///
72    /// match style_chain {
73    ///     RenderStyle::Styled(_, _) => { /* success */ },
74    ///     _ => panic!("Expected styled chain"),
75    /// }
76    /// ```
77    #[macro_export]
78    macro_rules! style {
79        () => {
80            $crate::interfaces::styling::RenderStyle::Plain
81        };
82        ($head:expr $(, $tail:expr)* $(,)?) => {
83            $crate::interfaces::styling::RenderStyle::Styled(
84                $head,
85                Box::new(style![$($tail),*])
86            )
87        };
88    }
89
90    /// A convenience macro for `Some(expr)`.
91    ///
92    /// Useful for quickly wrapping values in an `Option::Some`.
93    ///
94    /// # Examples
95    ///
96    /// ```rust
97    /// use overture::prelude::*;
98    ///
99    /// let maybe_value = some!(42);
100    /// assert_eq!(maybe_value, Some(42));
101    /// ```
102    #[macro_export]
103    macro_rules! some {
104        ($x:expr) => {
105            Option::Some($x)
106        };
107    }
108}
overture/macros.rs

overture/
macros.rs
