1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

//! This is a preprocessor for the [rust-lang mdbook](https://github.com/rust-lang/mdBook) project. This allows to run arbitrary (shell) commands and include the output of these commands within the markdown file.
//!
//! # Getting started
//!
//! ```sh
//! cargo install mdbook-cmdrun
//! ```
//!
//! You also have to activate the preprocessor, put this in your `book.toml` file:
//! ```toml
//! [preprocessor.cmdrun]
//! ```
//!
//! # How to
//!
//! Let's say we have these two files:
//!
//! Markdown file: file.md
//! ```markdown
//! # Title
//!
//! <!-- cmdrun seq 1 10 -->
//!
//! <!-- cmdrun python3 script.py -->
//!
//! ```
//!
//! Python file: script.py
//! ```python
//! def main():
//!     print("## Generated subtitle")
//!     print("  This comes from the script.py file")
//!     print("  Since I'm at in a scripting language,")
//!     print("  I can compute whatever I want")
//!
//! if __name__ == "__main__":
//!     main()
//!
//! ```
//!
//! The preprocessor will call seq then python3, and will produce the resulting file:
//!
//! ```markdown
//! # Title
//!
//! 1
//! 2
//! 3
//! 4
//! 5
//! 6
//! 7
//! 8
//! 9
//! 10
//!
//! ## Generated subtitle
//!   This comes from the script.py file
//!   Since I'm at in a scripting language,
//!   I can compute whatever I want
//!
//!
//! ```
//!
//! # Details
//!
//! When the pattern `<!-- cmdrun $1 -->\n` is encountered, the command `$1` will be run using the shell `sh` like this: `sh -c $1`.
//! Also the working directory is the directory where the pattern was found (not root).
//! Any command that takes no input, but a list of command lines arguments and produce output in stdout, stderr is ignored.
//!
//! # Examples
//!
//! The following is valid:
//!
//! ````markdown
//!
//! <!-- runcmd python3 generate_table.py -->
//!
//! ```rust
//! <!-- runcmd cat program.rs -->
//! ```
//!
//! ```diff
//! <!-- runcmd diff a.rs b.rs -->
//! ```
//!
//! ```console
//! <!-- runcmd ls -l . -->
//! ```
//! ````
//!
//! Some more examples are implemented, and are used as regression tests. You can find them [here](https://github.com/FauconFan/mdbook-cmdrun/tree/master/tests/regression/).
//! At the moment of writing, there are examples using:
//! - Shell
//! - Bash script
//! - Python3
//! - Rust
//!
pub mod cmdrun;
mod utils;

pub use cmdrun::CmdRun;