Crate place_macro

Expand description

§Place-macro

Macros you wish you had while you were writing your non-proc macro.

This library privides some macros that make writing regural non-proc macros much simpler, readable and with less dirty tricks.

The main macro of this library is place. It is able to expand the macros in this library in reverse expansion order.

Every time I’m missing a proc macro while creating macro, I will add it here :).

§Macros

place: expands the following macros in reverse order, see below

ignore: expands to nothing
identity: expands to what is given, it bypasses the reverse order in the place macro
dollar: expands to dollar sign $
string: concats the contents into single string, see the doc
identifier: concats the contents into sintle identifier in the same way asstring
head: expands to the first token
tail: expands to all but the first token
start: expands to all but the last token
last: expands to the last token
reverse: expands to the tokens in reverse order
stringify: expands to string of the input
replace_newline: replaces all newlines and folowing whitespace in literal with the given literal
str_replace: replace in string literal
to_case: change the case of a identifier

§The macro `place`

Expands the other macros inside in reverse order. The macros inside that will be expanded are used with a different sintax: instead of calling a macro as string!("hello" "there") you call it as __string__("hello" "there"). One exception is the macro dollar that is called without the parenthesis: __dollar__ instead of __dollar__().

For some of the macros there are also shorter names:

__identity__ - __id__
__string__ - __str__
__dollar__ - __s__
__identifier__ - __ident__
__stringify__ - __strfy__
__replace_newline__ - __repnl__
__str_replace__ - __repstr__

The macro to_case has simplified usage, the case of the macro call will determine the case to which convert (e.g. __ToCase__(my_ident) will expand to MyIdent). Possible variants:

__TOCASE__
__tocase__
__toCase__
__ToCase__
__to_case__
__TO_CASE__
__To_Case__

§Example

The following passes:

use place_macro::place;

let res = place!(__string__(1 __string__(2 __identity__(3 __string__(4)))));
assert_eq!(res, "123__string__4");

Why is this useful?

You can generate identifiers in your macros:

use place_macro::place;

macro_rules! my_cool_macro {
    ($name:ident -> $t:ty, $body:expr) => {
        place! {
            fn __identifier__(cool_ $name)() -> $t {
                $body
            }
        }
    };
}

my_cool_macro! { foo -> &'static str, "cool!" }
// Expands to:
// ```
// fn cool_foo() -> &'static str {
//     "cool!"
// }
// ```

You can generate strings as macro parameters in your macros:

use place_macro::place;

macro_rules! my_cool_macro {
    ($name:ident -> $t:ty, $body:expr) => {
        place! {
            #[doc =
                __string__(
                    "cool function called " $name ". Returns `"
                    __stringify__($t) "`."
                )
            ]
            fn __identifier__(cool_ $name)() -> $t {
                $body
            }
        }
    };
}

my_cool_macro! { foo -> &'static str, "cool!" }
// Expands to:
// ```
// #[doc = "cool function called foo. Returns `&'static str`."]
// fn cool_foo() -> &'static str {
//     "cool!"
// }
// ```

Or you can even generate macros in your macros

use place_macro::place;

macro_rules! my_cooler_macro {
    ($t:ident) => {
        place! {
            macro_rules! __identifier__(my_ $t _macro) {
                (__dollar__ name:ident -> __dollar__ t:ty, __dollar__ body:expr) => {
                    place! {
                        #[doc =
                            __identity__(__string__)(
                                $t " function called " __dollar__ name ". Returns `"
                                __identity__(__stringify__)(__dollar__ t) "`."
                            )
                        ]
                        fn __identity__(__identifier__)($t __dollar__ name)() -> __dollar__ t {
                            __dollar__ body
                        }
                    }
                };
            }
        }
    };
}

my_cooler_macro! { cool };
my_cool_macro! { foo -> &'static str, "cool!" }
// now you have the same function as in the previous example

The last example was a little less readable, but you can see that you can do a lot with this macro.

§Links

Author: BonnyAD9
GitHub repository: BonnyAD/place_macro
Package: crates.io
Documentation: docs.rs
My Website: bonnyad9.github.io

Macros§

dollar: Expands to a single dollar sign, this has no use when it is used alone, but it can be used in the place macro
head: Expans to the first token if present
identifier: Creates a identifier in the same way as the string macro creates string literals.
identity: Returns exactly the given input
ignore: Ignores all the input, as if there was nothing
last: Expands to the last token
place: Evaluates the macros in this crate in reverse order
replace_newline: Replaces newlines and follwing whitespace in string literal with another string.
reverse: Reverses the passed tokens
start: Expands to all but the last token
str_replace: Replaces in string literal
string: Converts the input to string literal, literals are interpreted as their values, punctuation and brackets are ignored and the rest is stringified.
stringify: Should be same to the rust macro stringify
tail: Expands to all but the first token
to_case: Converts the given identifier to the given case. Second argument is the identifier and the first is string literal representing the target case. The target case can be one of: