Initial commit

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+github:
+- parasyte
+patreon: blipjoy

.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: '0 0 * * 0'
+jobs:
+  checks:
+    name: Check
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        rust:
+          - stable
+          - beta
+          - 1.58.0
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v3
+      - name: Install toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.rust }}
+      - name: Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: common
+      - name: Cargo check
+        run: cargo check --workspace
+
+  lints:
+    name: Lints
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v3
+      - name: Install toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: stable
+          components: clippy, rustfmt
+      - name: Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: common
+      - name: Install cargo-machete
+        run: cargo install --locked cargo-machete
+      - name: Cargo fmt
+        run: cargo fmt --all -- --check
+      - name: Cargo doc
+        run: cargo doc --workspace --no-deps
+      - name: Cargo clippy
+        run: cargo clippy --workspace --tests -- -D warnings
+      - name: Cargo machete
+        run: cargo machete
+
+  tests:
+    name: Test
+    runs-on: ubuntu-latest
+    needs: [checks, lints]
+    strategy:
+      matrix:
+        rust:
+          - stable
+          - beta
+          - 1.58.0
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v3
+      - name: Install toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.rust }}
+      - name: Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: common
+      - name: Cargo test
+        run: cargo test --workspace

.gitignore

@@ -0,0 +1,2 @@
+/target
+/Cargo.lock

Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "myn"
+description = "Minimalist Rust syntax parsing for procedural macros"
+version = "0.1.0"
+authors = ["Jay Oster <jay@kodewerx.org>"]
+edition = "2021"
+keywords = ["macros", "myn"]
+categories = ["parser-implementations", "procedural-macro-helpers"]
+license = "MIT"
+
+[dependencies]
+# No dependencies!

LICENSE

@@ -0,0 +1,18 @@
+Copyright 2023 Jay Oster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

MSRV.md

@@ -0,0 +1,11 @@
+# Minimum Supported Rust Version
+
+| `myn` version | `rustc` version |
+|---------------|-----------------|
+| (unreleased)  | `1.58.0`        |
+
+## Policy
+
+The table above will be kept up-to-date in lock-step with CI on the main branch in GitHub. It may contain information about unreleased and yanked versions. It is the user's responsibility to consult with the [`myn` versions page](https://crates.io/crates/myn/versions) on `crates.io` to verify version status.
+
+The MSRV will be chosen as the minimum version of `rustc` that can successfully pass CI, including documentation, lints, and all examples. For this reason, the minimum version _supported_ may be higher than the minimum version _required_ to compile the `myn` crate itself. See `Cargo.toml` for the minimal Rust version required to build the crate alone.

README.md

@@ -0,0 +1,21 @@
+[![Crates.io](https://img.shields.io/crates/v/myn)](https://crates.io/crates/myn "Crates.io version")
+[![Documentation](https://img.shields.io/docsrs/myn)](https://docs.rs/myn "Documentation")
+[![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)
+[![GitHub actions](https://img.shields.io/github/actions/workflow/status/parasyte/myn/ci.yml?branch=main)](https://github.com/parasyte/myn/actions "CI")
+[![GitHub activity](https://img.shields.io/github/last-commit/parasyte/myn)](https://github.com/parasyte/myn/commits "Commit activity")
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/parasyte)](https://github.com/sponsors/parasyte "Sponsors")
+
+Minimalist Rust syntax parsing for procedural macros.
+
+You can think of `myn` as a minimalist crate with similarities to [`syn`](https://docs.rs/syn). It provides utilities to help write procedural macros, but does not attempt to replicate the `syn` types or API.
+
+`myn` exists to support a very small subset of the entire Rust language syntax. Just enough to implement `#[derive]` macros on `struct`s and `enum`s, and that's about it. Everything else is currently out of scope.
+
+## Why
+
+- 100% safe Rust 🦀.
+- Write `#[derive]` macros with extremely fast compile times. See [benchmarks](./benchmark.md).
+
+## MSRV Policy
+
+The Minimum Supported Rust Version for `myn` will always be made available in the [MSRV.md](./MSRV.md) file on GitHub.

benchmarks.md

@@ -0,0 +1 @@
+# TDB

src/lib.rs

@@ -0,0 +1,32 @@
+//! Minimalist Rust syntax parsing for procedural macros.
+//!
+//! # Rationale
+//!
+//! You may wonder why this is even a thing, since `syn` already exists, is a well-supported and
+//! excellent crate, and it supports the entire gamut of Rust syntax. In short, `syn` hurts compile
+//! times and is almost certainly overkill for your use case.
+//!
+//! Instead, we prefer a "pay for what you use" model. This small surface area affords rapid compile
+//! times at the cost of being able to parse the entirety of Rust language syntax. This is right
+//! tradeoff for `#[derive]` macros where compile time is of high importance.
+//!
+//! # Where to begin
+//!
+//! `myn` works directly with [`TokenStream`], giving you tools to build your own AST without
+//! attempting to define a one-size-fits-all strongly typed AST. The [`TokenStreamExt`] extension
+//! trait turns the `TokenStream` into a [`TokenIter`].
+//!
+//! [`TokenIter`]: crate::ty::TokenIter
+//! [`TokenStream`]: proc_macro::TokenStream
+//! [`TokenStreamExt`]: crate::traits::TokenStreamExt
+
+#![forbid(unsafe_code)]
+#![deny(clippy::all)]
+#![deny(clippy::pedantic)]
+
+extern crate proc_macro;
+
+pub mod prelude;
+pub mod traits;
+pub mod ty;
+pub mod utils;

src/prelude.rs

@@ -0,0 +1,5 @@
+//! Re-exports all public items.
+
+pub use crate::traits::*;
+pub use crate::ty::*;
+pub use crate::utils::*;

src/traits.rs

@@ -0,0 +1,184 @@
+//! Extension traits.
+//!
+//! The primary trait is [`TokenIterExt`], which provides the parsers.
+
+use crate::ty::{Attribute, TokenIter};
+use crate::utils::spanned_error;
+use proc_macro::{Delimiter, Group, Ident, Literal, Punct, Span, TokenStream, TokenTree};
+
+/// An extension trait for [`TokenStream`].
+pub trait TokenStreamExt {
+    /// Turn this type into a [`TokenIter`].
+    fn into_token_iter(self) -> TokenIter;
+}
+
+/// An extension trait for [`TokenIter`].
+///
+/// This trait provides parsers and shorthand methods for common getter patterns.
+pub trait TokenIterExt: Iterator<Item = TokenTree> {
+    /// Parse the input iterator into a list of attributes.
+    ///
+    /// # Errors
+    ///
+    /// Returns a compiler error if parsing fails. The error should be inserted into the
+    /// `proc_macro` stream.
+    fn parse_attributes(&mut self) -> Result<Vec<Attribute>, TokenStream>;
+
+    /// Parse the input iterator as a type visibility modifier.
+    ///
+    /// E.g. `pub` or `pub(super)`.
+    ///
+    /// This parser currently discards the result, since it doesn't have much use in a derive macro.
+    ///
+    /// # Errors
+    ///
+    /// Returns a compiler error if parsing fails. The error should be inserted into the
+    /// `proc_macro` stream.
+    fn parse_visibility(&mut self) -> Result<(), TokenStream>;
+
+    /// Parse the input iterator as a path into a string/span pair.
+    ///
+    /// E.g. `std::collections::HashMap<i32, String>`.
+    ///
+    /// Due to current limitations in the [`Span`] API, the returned span only points at the span
+    /// for the first path segment. For example, it would be `std` in the path above.
+    ///
+    /// # Errors
+    ///
+    /// Returns a compiler error if parsing fails. The error should be inserted into the
+    /// `proc_macro` stream.
+    fn parse_path(&mut self) -> Result<(String, Span), TokenStream>;
+
+    /// Parse the input as a group, expecting the given delimiter.
+    ///
+    /// Returns the group's inner [`TokenStream`] as a [`TokenIter`] when successful.
+    ///
+    /// # Errors
+    ///
+    /// Returns a compiler error if parsing fails. The error should be inserted into the
+    /// `proc_macro` stream.
+    fn expect_group(&mut self, expect: Delimiter) -> Result<TokenIter, TokenStream>;
+
+    /// Parse the input as an identifier, expecting it to match the given string.
+    ///
+    /// # Errors
+    ///
+    /// Returns a compiler error if parsing fails. The error should be inserted into the
+    /// `proc_macro` stream.
+    fn expect_ident(&mut self, expect: &str) -> Result<(), TokenStream>;
+
+    /// Parse the input as punctuation, expecting it to match the given char.
+    ///
+    /// # Errors
+    ///
+    /// Returns a compiler error if parsing fails. The error should be inserted into the
+    /// `proc_macro` stream.
+    fn expect_punct(&mut self, expect: char) -> Result<(), TokenStream>;
+
+    /// Parse the input as a group.
+    ///
+    /// # Errors
+    ///
+    /// Returns a compiler error if parsing fails. The error should be inserted into the
+    /// `proc_macro` stream.
+    fn as_group(&mut self) -> Result<Group, TokenStream>;
+
+    /// Parse the input as an identifier.
+    ///
+    /// # Errors
+    ///
+    /// Returns a compiler error if parsing fails. The error should be inserted into the
+    /// `proc_macro` stream.
+    fn as_ident(&mut self) -> Result<Ident, TokenStream>;
+
+    /// Parse the input as a literal.
+    ///
+    /// # Errors
+    ///
+    /// Returns a compiler error if parsing fails. The error should be inserted into the
+    /// `proc_macro` stream.
+    fn as_lit(&mut self) -> Result<Literal, TokenStream>;
+
+    /// Parse the input as punctuation.
+    ///
+    /// # Errors
+    ///
+    /// Returns a compiler error if parsing fails. The error should be inserted into the
+    /// `proc_macro` stream.
+    fn as_punct(&mut self) -> Result<Punct, TokenStream>;
+}
+
+/// An extension trait for [`TokenTree`].
+pub trait TokenTreeExt {
+    /// Get a span from the given [`TokenTree`].
+    fn as_span(&self) -> Span;
+}
+
+/// An extension trait for [`Literal`].
+pub trait LiteralExt {
+    /// Parse a literal into a char.
+    ///
+    /// # Errors
+    ///
+    /// Returns a compiler error if parsing fails. The error should be inserted into the
+    /// `proc_macro` stream.
+    fn as_char(&self) -> Result<char, TokenStream>;
+
+    /// Parse a literal into a string.
+    ///
+    /// # Errors
+    ///
+    /// Returns a compiler error if parsing fails. The error should be inserted into the
+    /// `proc_macro` stream.
+    fn as_string(&self) -> Result<String, TokenStream>;
+}
+
+impl TokenStreamExt for TokenStream {
+    fn into_token_iter(self) -> TokenIter {
+        self.into_iter().peekable()
+    }
+}
+
+impl TokenTreeExt for Option<TokenTree> {
+    fn as_span(&self) -> Span {
+        match self {
+            Some(TokenTree::Group(group)) => group.span(),
+            Some(TokenTree::Ident(ident)) => ident.span(),
+            Some(TokenTree::Punct(punct)) => punct.span(),
+            Some(TokenTree::Literal(lit)) => lit.span(),
+            None => Span::call_site(),
+        }
+    }
+}
+
+impl LiteralExt for Literal {
+    fn as_char(&self) -> Result<char, TokenStream> {
+        let string = format!("{self}");
+        if !string.starts_with('\'') || !string.ends_with('\'') {
+            return Err(spanned_error("Expected char literal", self.span()));
+        }
+
+        // Strip single quotes.
+        string
+            .chars()
+            .nth(1)
+            .ok_or_else(|| spanned_error("Expected char literal", self.span()))
+    }
+
+    fn as_string(&self) -> Result<String, TokenStream> {
+        let string = format!("{self}");
+        if !string.starts_with('"') || !string.ends_with('"') {
+            return Err(spanned_error("Expected string literal", self.span()));
+        }
+
+        // Strip double quotes and escapes.
+        Ok(string[1..string.len() - 1]
+            .trim()
+            .replace(r#"\""#, r#"""#)
+            .replace(r"\n", "\n")
+            .replace(r"\r", "\r")
+            .replace(r"\t", "\t")
+            .replace(r"\'", "'")
+            .replace(r"\\", r"\"))
+    }
+}