Module libzettels::examples

Module to generate a set of example files.

It provides three functions intended for application developers to

• test their application against valid data
• provide their users way to quickly try out the respective application without having to create a bunch of zettel files

All three functions take a path to a directory as an argument. They will panic if that path doesn't exist, is not a directory, isn't writable etc.

Inside the specified directory, they generate two directories with one subdirectory each:

example_config      // equivalent to user config dir, e.g. $HOME/.config
└── libzettels      // equivalent to $HOME/.config/YourApplication
examples            // somewhere in the user's files, e.g. $HOME/Documents
└── Zettelkasten    // equivalent to the user's chosen root directory

The three functions differ in how they populate these directories:

• generate_bare_examples only populates examples/Zettelkasten with a bunch of zettel files (and some other files a user might have in there). It's intended to test/try starting from scratch (i.e. let the user create a configuration and create a fresh index.)
• generate_examples_with_config also writes a configuration file (in YAML) to example_config/libzettels. It's intended to test/try creating a fresh index without going through the setup process.
• generate_examples_with_index adds a ready-made index file inside example_config/libzettels. It's intended to test/try user interaction with the Zettelkasten (e.g. querying, updating etc.)

Note to application developers:

If you pass the path to a temporary directory to these functions, make sure the actual directory lives long enough. For example, if you use the tempfile crate:

Panics - Don't do this

extern crate tempfile;
use tempfile::tempdir;
fn setup_tmp_dir() -> std::path::PathBuf {
    let tmp_dir = tempdir().expect("Failed to create tmp_dir");
    // do a lot of setup stuff
    // -- snip --
    // just return the path to our nicely prepared temp dir
    tmp_dir.path().to_path_buf()
}

fn main() {
    let dir = setup_tmp_dir();
    generate_bare_examples(dir).expect("The temporary directory no longer exists!");
}

Instead, do this

extern crate tempfile;
use tempfile::tempdir;

fn main() {
    let tmp_dir = tempdir().expect("Failed to create tmp_dir");
    generate_bare_examples(tmp_dir.path());
}

Or this

extern crate tempfile;
use tempfile::{tempdir, TempDir};

fn setup_tmp_dir() -> TempDir {
    let tmp_dir = tempdir().expect("Failed to create tmp_dir");
    // do a lot of setup stuff
    // -- snip --
    // return `TempDir` itself to keep it alive
    tmp_dir
}

fn main() {
    let tmp_dir = setup_tmp_dir();
    generate_bare_examples(tmp_dir.path());
}

Functions

generate_bare_examples	Takes the path to a directory and creates a directory structure with set of example files inside it.
generate_examples_with_config	Takes the path to a directory and creates a directory structure with set of example files and a sample config file inside it.
generate_examples_with_index	Takes the path to a directory and creates a directory structure with set of example files and a sample config file inside it, indexes the files and saves the index.