Skip to content

Commit

Permalink
tweak: Update docs to talk about code generation more broadly
Browse files Browse the repository at this point in the history
  • Loading branch information
@dhedey
dhedey committed Dec 1, 2024
1 parent 9333822 commit 89b49eb
Show file tree
Hide file tree
Showing 3 changed files with 30 additions and 29 deletions.
2 changes: 1 addition & 1 deletion Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ version = "0.1.3"
edition = "2021"
license = "MIT OR Apache-2.0"
authors = ["David Edey <[email protected]>"]
description = "An intuitive toolkit to simplify declarative macro development"
description = "An intuitive toolkit to simplify code generation development"
repository = "https://github.com/dhedey/preinterpret"
keywords = ["macros", "declarative-macros", "toolkit", "interpreter", "preprocessor"]
# Categories have to come from https://crates.io/category_slugs
Expand Down
27 changes: 14 additions & 13 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Preinterpet - The declarative macro toolkit
# Preinterpet - The code generation toolkit

[<img alt="github" src="https://img.shields.io/badge/github-dhedey/preinterpret-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/dhedey/preinterpret)
[<img alt="crates.io" src="https://img.shields.io/crates/v/preinterpret.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/preinterpret)
Expand All @@ -10,29 +10,30 @@
If updating this readme, please ensure that the rustdoc is also updated.
-->

This crate provides the `preinterpret!` macro, which works as a simple pre-processor to the token stream, and is designed for declarative macro authors.
This crate provides the `preinterpret!` macro, which works as a simple pre-processor to the token stream. It is inspired by the [quote](https://crates.io/crates/quote) and [paste](https://crates.io/crates/paste) crates, and built to empower code generation authors and declarative macro writers, bringing:

It is inspired by the [quote](https://crates.io/crates/quote) and [paste](https://crates.io/crates/paste) crates, and built for code generator / declarative macro authors to provide:

* **Heightened readability** - allowing developers to build more maintainable macros.
* **Heightened expressivity** - mitigating the need to build custom procedural macros.
* **Heightened sensibility** - helping developers avoid various declarative macro surprises.
* **Heightened readability** - making it easier to work with code generation code.
* **Heightened expressivity** - reducing boilerplate, and mitigating the need to build custom procedural macros in some cases.
* **Heightened simplicity** - helping developers avoid various declarative macro surprises.

It provides two composable features:

* Variable definition with `[!set! #variable = ... ]` and variable substition with `#variable` (think [quote](https://crates.io/crates/quote) for declarative macros)
* A toolkit of simple functions operating on token streams, literals and idents, such as `[!ident! Hello #world]` (think [paste](https://crates.io/crates/paste) but more comprehesive, and still maintained)

The `preinterpret!` macro can be used inside the output of a declarative macro, or by itself, functioning as a mini code generation tool all of its own.

```toml
[dependencies]
preinterpret = "0.1"
```

## Motivation

### Heightened readability
### Readability

The preinterpret syntax is intended to be immediately intuitive even for people not familiar with the crate. And it enables developers to make more readable macros:

* Developers can name clear concepts in their macro output, and re-use them by name, decreasing code duplication.
* Developers can use variables to subdivide logic inside the macro, without having to resort to creating lots of small, functional helper macros.

Expand Down Expand Up @@ -65,14 +66,14 @@ impl_marker_traits! {
};
```

### Heightened Expressivity
### Expressivity

Preinterpret provides a suite of composable functions to convert token streams, literals and idents. The full list is documented in the [Details](#details) section.
Preinterpret provides a suite of simple, composable commands to convert token streams, literals and idents. The full list is documented in the [Details](#details) section.

For example:

```rust
macro_rules! make_a_struct_and_getters {
macro_rules! create_struct_and_getters {
(
$name:ident { $($field:ident),* $(,)? }
) => {preinterpret::preinterpret!{
Expand All @@ -93,7 +94,7 @@ macro_rules! make_a_struct_and_getters {
}
}}
}
make_a_struct_and_getters! {
create_struct_and_getters! {
MyStruct { hello, world }
}
```
Expand Down Expand Up @@ -136,7 +137,7 @@ let count = preinterpret::preinterpret!{
Now the `preinterpret!` macro runs, resulting in `#count` equal to the token stream `0usize + 1 + 1 + 1`.
This will be improved in future releases by adding support for mathematical operations on integer literals.

### Heightened sensibility
### Heightened simplicity

Using preinterpret partially mitigates some common areas of confusion when writing declarative macros.

Expand Down
30 changes: 15 additions & 15 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
//! This crate provides the `preinterpret!` macro, which works as a simple pre-processor to the token stream, and is designed for declarative macro builders.
//! This crate provides the `preinterpret!` macro, which works as a simple pre-processor to the token stream. It is inspired by the [quote](https://crates.io/crates/quote) and [paste](https://crates.io/crates/paste) crates, and built to empower code generation authors and declarative macro writers, bringing:
//!
//! It is inspired by the [quote](https://crates.io/crates/quote) and [paste](https://crates.io/crates/paste) crates, and built for declarative macro authors to provide:
//!
//! * **Heightened readability** - allowing developers to build more maintainable macros.
//! * **Heightened expressivity** - mitigating the need to build custom procedural macros.
//! * **Heightened sensibility** - helping developers avoid various declarative macro surprises.
//! * **Heightened readability** - making it easier to work with code generation code.
//! * **Heightened expressivity** - reducing boilerplate, and mitigating the need to build custom procedural macros in some cases.
//! * **Heightened simplicity** - helping developers avoid various declarative macro surprises.
//!
//! It provides two composable features:
//!
//! * Variable definition with `[!set! #variable = ... ]` and variable substition with `#variable` (think [quote](https://crates.io/crates/quote) for declarative macros).
//! * A toolkit of simple functions operating on token streams, literals and idents, such as `[!ident! Hello #world]` (think [paste](https://crates.io/crates/paste) but more comprehesive, and still maintained).
//!
//! The `preinterpret!` macro can be used inside the output of a declarative macro, or by itself, functioning as a mini code generation tool all of its own.
//!
//! ## Motivation
//!
//! ### Heightened readability
//! ### Readability
//!
//! The preinterpret syntax is intended to be immediately intuitive even for people not familiar with the crate. And it enables developers to make more readable macros:
//! * Developers can name clear concepts in their macro output, and re-use them by name, decreasing code duplication.
//! * Developers can use variables to subdivide logic inside the macro, without having to resort to creating lots of small, functional helper macros.
//! The preinterpret syntax is intended to be immediately intuitive even for people not familiar with the crate. And it enables developers to make their code generation code more readable:
//! * Developers can name clear concepts in their output, and re-use them by name, decreasing code duplication.
//! * Developers can use variables to subdivide generation logic, without having to resort to creating lots of small, functional helper macros.
//!
//! A simple example follows, but variable substitution becomes even more useful in larger macros with more boilerplate:
//!
Expand Down Expand Up @@ -53,14 +53,14 @@
//! }
//! ```
//!
//! ### Heightened Expressivity
//! ### Expressivity
//!
//! Preinterpret provides a suite of composable functions to convert token streams, literals and idents. The full list is documented in the [Details](#details) section.
//! Preinterpret provides a suite of simple, composable commands to convert token streams, literals and idents. The full list is documented in the [Details](#details) section.
//!
//! For example:
//!
//! ```rust
//! macro_rules! make_a_struct_and_getters {
//! macro_rules! create_struct_and_getters {
//! (
//! $name:ident { $($field:ident),* $(,)? }
//! ) => {preinterpret::preinterpret!{
Expand All @@ -81,7 +81,7 @@
//! }
//! }}
//! }
//! make_a_struct_and_getters! {
//! create_struct_and_getters! {
//! MyStruct { hello, world }
//! }
//! ```
Expand Down Expand Up @@ -125,7 +125,7 @@
//! Now the `preinterpret!` macro runs, resulting in `#count` equal to the token stream `0usize + 1 + 1 + 1`.
//! This will be improved in future releases by adding support for mathematical operations on integer literals.
//!
//! ### Heightened sensibility
//! ### Simplicity
//!
//! Using preinterpret partially mitigates some common areas of confusion when writing declarative macros.
//!
Expand Down

0 comments on commit 89b49eb

Please sign in to comment.