Skip to content

nik-rev/docstr

Repository files navigation

docstr

crates.io docs.rs license msrv github

This crate provides a procedural macro for ergonomically creating multi-line string literals. It is an alternative to indoc.

[dependencies]
docstr = "0.4"

Note: docstr does not have any dependencies such as syn or quote, so compile-speeds are very fast.

Usage

docstr! takes documentation comments as arguments and converts them into a string

use docstr::docstr;

let hello_world_in_c: &'static str = docstr!(
    /// #include <stdio.h>
    ///
    /// int main(int argc, char **argv) {
    ///     printf("hello world\n");
    ///     return 0;
    /// }
);

assert_eq!(hello_world_in_c, r#"#include <stdio.h>

int main(int argc, char **argv) {
    printf("hello world\n");
    return 0;
}"#)

Composition

docstr! can pass the generated string to any macro:

use docstr::docstr;

let age = 21;
let name = "Bob";
let colors = ["red", "green", "blue"];

let greeting: String = docstr!(format!
                             //^^^^^^^ the generated string is passed to `format!`
                             //        as the 1st argument
    /// Hello, my name is {name}.
    /// I am {age} years old!
    ///
    /// My favorite color is: {}

    // anything after the doc comments is passed directly at the end
    colors[1]
);
//^ above expands to: format!("...", colors[1])

assert_eq!(greeting, "Hello, my name is Bob.\nI am 21 years old!\n\nMy favorite color is: green");

Injecting arguments before the generated string is also possible.

docstr!(write! w
   /// Hello, world!
);

Expands to:

write!(w, "Hello, world!");

About

Ergonomic multi-line string literals

Resources

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT

Stars

Watchers

Forks

Packages

No packages published