How to install the present crate // Lib.rs

Present is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install present

It will make the present command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall present uninstalls.

Adding `present` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add present

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

present = "0.2.3"

The present library will be automatically available globally. Read the present library documentation.

Back to the crate overview.

Readme

present

present is a tool that lets you interpolate the standard output of arbitrary scripts that get interpreted by the shell into your markdown documents.

Its aim is to provide a nice way to automatically update sections of your markdown documents that might be the standard output of a command, such as command-line utility help outputs or benchmarks.

Demo

Below is a short demo showcasing the main functionality of the program.

CLI

You can install the present command-line utility with the rust package manager cargo:

$ cargo install present

Below is the standard output of present --help, interpolated by the present binary itself!

Interpolate the standard output of arbitrary shell scripts into your markdown files

Usage: present [OPTIONS] [PATH]

Arguments:
  [PATH]  A file or directory path to present.

Options:
      --recursive    Recursively present markdown documents.
      --in-place     Modify documents in place.
      --interactive  Interactively present markdown documents.
      --pretty       Pretty print documents to the terminal.
      --remove       Remove commands within markdown documents.
  -h, --help         Print help information
  -V, --version      Print version information

Library

present can be used as a library by adding this line to the [dependencies] section in Cargo.toml:

present = "0.2.2"

With present, you can create a File struct by pointing it to a path. This will parse all codeblocks with the present prefix, and add them as commands to the struct. From there, you can present the file by using the File::present function, which will modify the internal content. From there, you can use the File::print or File::save functions to print the presented document to stdout or save it back to the original file.

use std::path::PathBuf;

fn main() {
  let mut file = present::File::new(PathBuf::from("README.md")).unwrap();
  file.present().unwrap();
  file.save();
}

The above snippet is tested with rustdoc. A really cool side effect of this, is that the test loads the README itself, and runs present over it. present is also used throughout the README (to get help-text and version numbers), which means that when running cargo test, the README gets automatically updated.

You can read more about using the library on docs.rs.

Examples

Below are a few examples showcasing what kind of command result interpolations present is currently able to handle.

`present foo.md --in-place`	foo ```present echo bar ```	foo ```present echo bar bar ```
`present foo.md --in-place --remove`	foo ```present echo bar ```	`foo bar`

Prior Art

This project is loosely inspired by Cog, the code generation tool. However, as mentioned above, this project's main target is markdown documents that may benefit to have certain sections automatically updated, due to being the result of a command invocation.

Installing the command-line executable

Adding present library as a dependency

Adding `present` library as a dependency