[−][src]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 populatesexamples/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) toexample_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 insideexample_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. |