4 releases
0.6.1 | Aug 21, 2022 |
---|---|
0.6.0 | Mar 25, 2021 |
0.5.2 | Mar 4, 2021 |
0.5.1 | Mar 4, 2021 |
#2332 in Command line utilities
25 downloads per month
130KB
3K
SLoC
Contains (JAR file, 59KB) gradle-wrapper.jar
Yarner
A language-independent Literate Programming tool for Markdown. From Markdown documents written and structured for humans, Yarner extracts code blocks into compilable source code. It offers sufficient features and flexibility to be usable also for larger projects with numerous files and multiple languages.
Yarner works with familiar syntax, which can be further customized to suit your needs exactly. See the examples directory for full working examples using different programming languages. See the User Guide for documentation.
Features
- Macros and named code blocks
- Multiple files, multiple entrypoints
- File transclusions
- Reverse mode
- Custom plugins
- ...
See the User Guide for a complete and detailed explanation of all features.
Installation
Pre-compiled binaries
- Download the latest binaries for your platform
- Unzip somewhere
- Optional: add the parent directory of the executable to your
PATH
environmental variable
Using cargo
In case you have Rust installed, you can install with cargo
:
> cargo install yarner
Getting started
To set up a new project, use the init
sub-command. Run the following in your project's base directory:
> yarner init
This creates a file Yarner.toml
with default settings, and a file README.md
as starting point for Literate Programming.
The generated file already contains some content to get started with Yarner's basic features. For details, see the User Guide.
To build the project (extract code and create documentation), simply run:
> yarner
This creates two sub-directories, one containing the extracted code (a minimal but working Rust project), and another containing the final documentation.
Note that the contents of these directories can then be treated as usual, i.e. compiling the code with the normal compiler, or rendering Markdown to HTML or PDF.
Examples
Macros
Macros are what enables the literate program to be written in logical order for the human reader. Using Yarner, this is accomplished by naming the code blocks, and then referencing them later by "invoking" the macro.
By default, macro invocations start with // ==>
and end with a period .
. Both of these sequences can be customized to suit your needs better. The only restriction with macro invocations is that they must be the only thing on the line.
Here, we have an unnamed code block as entrypoint, and "draw" code from two other code blocks into the main function. These code blocks are named by their first line of code, starting with //-
.
The program starts in the main function. It calculates something and prints the result:
```rust
fn main() {
// ==> Calculate something.
// ==> Print the result.
}
```
The calculation does the following:
```rust
//- Calculate something
let result = 100;
```
Printing the result looks like this:
```rust
//- Print the result
println!("{}", result);
```
The rendered document looks like this:
The program starts in the main function. It calculates something and prints the result:
The calculation does the following:
Printing the result looks like this:
|
The generated code looks like this:
fn main() {
let result = 100;
println!("{}", result);
}
Entrypoints
By default, the entrypoint of the program is always the unnamed code block.
However, a code block name can be given in Yarner.toml
or passed to Yarner on the command line.
Then, instead of starting at the unnamed code block, it will start at the code block with this name.
By naming code blocks with prefix file:
followed by a relative path, multiple code files can be created
from one source file. Each code block with the file:
prefix is treated as a separate entry point.
```rust
//- file:src/lib.rs
fn say_hello() {
println!("Hello Literate Programmer!");
}
```
File transclusions and links are further features that allow for projects with multiple code, documentation and/or source files.
Configuration
Configuration is provided via a toml configuration file (default: Yarner.toml
).
A file with default configurations is generated through the init
sub-command.
See the user guide chapters configuration for details on individual settings.
Contributing
Please use the Issues for bug reports and feature suggestions. For questions and general discussion, use the Discussions.
Pull requests are welcome!
Acknowledgements
This tool is derived from foxfriends' work outline.
Dependencies
~8–19MB
~248K SLoC