Add literal macro

`literal!("An ascii string")` enables us to write a fixed-size,
compile-time ascii string in the same manner as we would use `b"A byte
string"` to write a fixed-size, compile-time byte string.

This is the only way to (safely) have a const ascii string.

Author: andrepd

Cargo.toml

@@ -11,6 +11,7 @@ version = "1.1.0"
 [dependencies]
 serde = { version = "1.0.25", optional = true }
 serde_test = { version = "1.0", optional = true }
+ascii_macros = { version = "1.1.0", path = "proc_macros/" }
 
 [features]
 default = ["std"]

proc_macros/Cargo.toml

@@ -0,0 +1,11 @@
+[lib]
+proc-macro = true
+
+[package]
+name = "ascii_macros"
+version = "1.1.0"
+edition = "2024"
+
+[dependencies]
+quote = "1.0.*"
+syn = "2.0.*"

proc_macros/src/lib.rs

@@ -0,0 +1,56 @@
+use proc_macro::TokenStream;
+use quote::quote;
+use syn::{LitStr, LitChar};
+
+#[proc_macro]
+pub fn literal(input: TokenStream) -> TokenStream {
+  if let Ok(str) = syn::parse(input.clone()) {
+    str_literal(str)
+  } else if let Ok(char) = syn::parse(input.clone()) {
+    char_literal(char)
+  } else {
+    quote!{ compile_error!{"Expected a string or char literal."} }.into()
+  }
+}
+
+fn str_literal(expr: LitStr) -> TokenStream {
+  let s = expr.value();
+
+  if !s.is_ascii() {
+    return quote!{ compile_error!{"String is not valid ascii."} }.into()
+  }
+
+  let chars = s.as_bytes().iter();
+  let len = s.as_bytes().len();
+
+  // SAFETY: all elements of `chars` are valid ascii, therefore casting from `u8` to `AsciiChar` is
+  // safe.
+  quote!{
+    {
+      const __LIT: &'static [::ascii::AsciiChar; #len] = &[
+        #(unsafe { ::core::mem::transmute::<u8, ::ascii::AsciiChar>(#chars) }),*
+      ];
+      __LIT
+    }
+  }.into()
+}
+
+fn char_literal(expr: LitChar) -> TokenStream {
+  let s = expr.value();
+
+  if !s.is_ascii() {
+    return quote!{ compile_error!{"Char is not valid ascii."} }.into()
+  }
+
+  let char = s as u8;
+
+  // SAFETY: `char` is an ascii byte, therefore casting from `u8` to `AsciiChar` is safe.
+  quote!{
+    {
+      const __LIT: ::ascii::AsciiChar = {
+        unsafe { ::core::mem::transmute::<u8, ::ascii::AsciiChar>(#char) }
+      };
+      __LIT
+    }
+  }.into()
+}

src/lib.rs

@@ -17,7 +17,7 @@
 //!
 //! The minimum Rust version for 1.2.\* releases is 1.56.1.
 //! Later 1.y.0 releases might require newer Rust versions, but the three most
-//! recent stable releases at the time of publishing will always be supported.  
+//! recent stable releases at the time of publishing will always be supported.
 //! For example this means that if the current stable Rust version is 1.70 when
 //! ascii 1.3.0 is released, then ascii 1.3.\* will not require a newer
 //! Rust version than 1.68.
@@ -80,3 +80,72 @@ pub use ascii_str::{Chars, CharsMut, CharsRef};
 #[cfg(feature = "alloc")]
 pub use ascii_string::{AsciiString, FromAsciiError, IntoAsciiString};
 pub use free_functions::{caret_decode, caret_encode};
+
+extern crate ascii_macros;
+
+/// Creates a `&'static [AsciiChar; N]` from a string literal, or an [`AsciiChar`] from a
+/// char literal.
+///
+/// This is identical to how a byte string literal `b"abc"` creates a `&'static [u8; N]`, and a
+/// byte char literal `b"z"` creates a `u8`.
+///
+/// This can be used in `const` contexts. If the string/char is not valid ASCII, produces
+/// a **compile-time error**.
+///
+/// # Examples
+/// ```
+/// # use ascii::{AsciiChar, AsciiStr};
+/// const HELLO: &[AsciiChar; 15] = ascii::literal!("Hello in ASCII!");
+/// assert_eq!(AsciiStr::new(HELLO).as_str(), "Hello in ASCII!");
+/// ```
+///
+/// ```
+/// # use ascii::{AsciiChar, AsciiStr};
+/// // Can also coerce to an `&'static [AsciiChar]`, just like a byte string literal can.
+/// const SLICE: &[AsciiChar] = ascii::literal!("Slice of ASCII\n");
+/// # assert_eq!(AsciiStr::new(SLICE).as_str(), "Slice of ASCII\n");
+/// ```
+///
+/// ```
+/// # use ascii::{AsciiChar, AsciiStr};
+/// // Or directly to a `&AsciiStr`.
+/// const STR: &AsciiStr = AsciiStr::new(ascii::literal!("Str of ASCII"));
+/// # assert_eq!(STR.as_str(), "Str of ASCII");
+/// ```
+///
+/// ```
+/// # use ascii::{AsciiChar, AsciiStr};
+/// // A char literal produces an `AsciiChar`.
+/// const CHAR: AsciiChar = ascii::literal!('@');
+/// # assert_eq!(CHAR, AsciiChar::At);
+/// ```
+///
+/// ```compile_fail
+/// // This doesn't compile!
+/// let oops = ascii_literal::literal!("💥");
+/// ```
+pub use ascii_macros::literal;
+
+#[allow(dead_code)]
+/// ```compile_fail
+/// let _ = ascii::literal!("kaboom 💥");
+/// ```
+fn test_literal_compile_fail_1() {}
+
+#[allow(dead_code)]
+/// ```compile_fail
+/// let _ = ascii::literal!("Torbjørn");
+/// ```
+fn test_literal_compile_fail_2() {}
+
+#[allow(dead_code)]
+/// ```compile_fail
+/// let _ = ascii::literal!('é');
+/// ```
+fn test_literal_compile_fail_3() {}
+
+#[allow(dead_code)]
+/// ```compile_fail
+/// let _ = ascii::literal!(invalid,);
+/// ```
+fn test_literal_compile_fail_4() {}

tests.rs

@@ -148,3 +148,19 @@ fn extend_from_iterator() {
     s.extend(&[AsciiChar::LineFeed]);
     assert_eq!(s, "abcabconetwothreeASCIIASCIIASCII\n");
 }
+
+#[test]
+fn literal() {
+    use ascii::literal;
+
+    const MESSAGE: &[AsciiChar; 15] = literal!("Hello in ASCII!");
+    let ascii_str: &AsciiStr = MESSAGE.into();
+    assert_eq!(ascii_str.as_str(), "Hello in ASCII!");
+
+    const EMPTY: &[AsciiChar; 0] = literal!("");
+    let ascii_str: &AsciiStr = EMPTY.into();
+    assert_eq!(ascii_str.as_str(), "");
+
+    const CHAR: AsciiChar = literal!('Z');
+    assert_eq!(CHAR.as_byte(), b'Z');
+}