Struct libzettels::Zettel

pub struct Zettel {
    pub title: String,
    pub links: Vec<PathBuf>,
    pub followups: Vec<PathBuf>,
    pub keywords: Vec<String>,
}

A struct containing relevant data about a Zettel.

It is created by reading the necessary information from a zettel file. Libzettels assumes all zettel file contain a YAML-header containing all or most of this information.

Libzettels was designed to deal with two kinds of zettel files:

• Markdown-based zettel files
• Image-based zettel files

but it is able to handle a lot of different formats, as long as the YAML-header is present and readable (see README).

Markdown-based zettel file

A markdown-based zettel file is a markdown file with a YAML-header as defined by pandoc). Most of the information concerning the interrelations with other Zettels is read from the YAML-header. An exception is the field links, which is generated by parsing markdown links in the file (only of the "inline" syntax).
The YAML-metadata may contain additional information (like author, e.g.). However, such additional data is ignored, here.

Example

---
title:  'Some Zettel'
keywords: [example]
followups: [file2.md, file3.md]
...

Here begins the Zettel's actual content, possibly containing links to 
[other Zettels](file2.md). These links are used for internal links within 
the Zettelkasten. External links can be achieved by [reference style][id] 
links. These are ignored by the Zettelkasten. Lorem ipsum…

[id]: https://daringfireball.net/projects/markdown/syntax#link

Image-based zettel file

Image-based zettel files are a way to integrate scans of handwritten notes into the Zettelkasten. To do this, a user copies the image file to the root directory of the Zettelkasten and creates an accompanying text file containing the YAML-metadata about the interrelation to other zettels and some sort of reference to the image file. For example, such a text file could be a markdown file with a YAML-header and an image link to the image file. Because the links field can not be automatically filled with meaningful data, it needs to be set in the YAML (or it will be a empty list).

Example

---
title:  'An image-based Zettel'
keywords: [example]
followups: [file2.md, file3.md]
links: [file1.md]
...
![](imagefile.png)

See the project's README for details and other file formats as zettel files.

Fields

title: String

The title of the Zettel, as set in its YAML-metadata.

links: Vec<PathBuf>

Other Zettels this one is pointing to via Markdown-syntax.

followups: Vec<PathBuf>

Other Zettels that are considered followups to this one, as set in the YAML-metadata.

keywords: Vec<String>

Keywords applied to this Zettel, as set in the YAML-metadata.

Implementations

impl Zettel

pub fn new<T: AsRef<str>>(title: T) -> Zettel

Extended API

Creates a new Zettel by specifying its title. All other fields are empty lists.

Example

let z = Zettel::new("Example Zettel");

assert_eq!(&z.title, "Example Zettel");
assert!(&z.links.is_empty());
assert!(&z.followups.is_empty());
assert!(&z.keywords.is_empty());

pub fn from_yaml<P: AsRef<Path>>(
    yaml: &str,
    rootdir: P,
    zettelfile: P
) -> Result<Zettel, Error>

Extended API

Creates a new Zettel by deserializing it from a YAML-string. It needs references to filename and root directory in order to normalize the followup-links. Note: This only uses the metadata specified in the YAML-header of the Zettel. Thus, the field links is not populated. For that, the markdown links need to be parsed.

Example

let rootdir = Path::new("examples/Zettelkasten");
let zettelfile = rootdir.join("file1.md");
let yaml = "---
title: 'A Zettel'
keywords: [example, yaml]
followups: [file2.md]
...

Here be contents.";
let z = Zettel::from_yaml(yaml, rootdir, zettelfile.as_ref())
        .expect("Something went wrong.");

Errors

• Error::BadLink if an entry in followups or links links to a file that doesn't exist (wrapping an std::io::Error of the NotFound kind).
• Error::Io wrapping several kinds of std::io:Error.
• Error::NormalizePath if zettelfile or a link in followups or linkscan not be expressed relative to the root directory.
• Error::BadHeader when deserializing the Zettel from YAML failed.

pub fn from_file<P: AsRef<Path>>(
    zettelfile: P,
    rootdir: P
) -> Result<Zettel, Error>

Extended API

Creates a new Zettel by deserializing it from a YAML-file. It needs a reference to the root directory in order to normalize the followup-links.

Example

let rootdir = Path::new("examples/Zettelkasten");
let zettelfile = rootdir.join("file1.md");
let z = Zettel::from_file(zettelfile.as_ref(), rootdir)
        .expect("Something went wrong.");

Errors

• Error::BadLink if an entry in followups links to a file that doesn't exist (wrapping an std::io::Error of the NotFound kind).
• Error::Io wrapping various kinds of std::io::Error. Most notably of the InvalidData kind, if the file is a non-text file (e.g. an image).
• Error::NormalizePath if zettelfile or a link in `followups``can not be expressed relative to the root directory.
• Error::BadHeader when deserializing the Zettel from YAML failed.

pub fn add_link<P: AsRef<Path>>(&mut self, link: P)

Extended API

Adds a link (specified by its path relative to the root directory) to the Zettel. If the link is already present, it is not added a second time.

Example

let mut z = Zettel::new("Example Zettel");
z.add_link(Path::new("anotherfile.md"));

assert_eq!(&z.links, &vec![Path::new("anotherfile.md")]);

pub fn add_followup<P: AsRef<Path>>(&mut self, followup: P)

Extended API

Adds a followup (specified by its path relative to the root directory) to the Zettel. If the followup is already present, it is not added a second time.

Example

let mut z = Zettel::new("Example Zettel");
z.add_followup(Path::new("anotherfile.md"));

assert_eq!(&z.followups, &vec![Path::new("anotherfile.md")]);

pub fn add_keyword<T: AsRef<str>>(&mut self, keyword: T)

Extended API

Adds a keyword to the Zettel. If the keyword is already present, it is not added a second time.

Example

let mut z = Zettel::new("Example Zettel");
z.add_keyword("foo");

assert_eq!(&z.keywords, &vec![String::from("foo")]);

pub fn links_to(&self, searched_links: &HashSet<PathBuf>, all: bool) -> bool

Extended API

Checks whether or not the zettel links to one other zettel out of a list specified by searched_links (or to all of them, if the parameter all is true).

Example

let mut z = Zettel::new("Example Zettel");
z.add_link(PathBuf::from("file1.md"));
let mut searched_links = HashSet::new();
searched_links.insert(PathBuf::from("file1.md"));
searched_links.insert(PathBuf::from("file2.md"));
 
assert!(z.links_to(&searched_links, false));
assert!(!z.links_to(&searched_links, true));

Trait Implementations

impl Clone for Zettel

fn clone(&self) -> Zettel

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Zettel

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Zettel

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl PartialEq<Zettel> for Zettel

fn eq(&self, other: &Zettel) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Zettel) -> bool

This method tests for !=.

impl Serialize for Zettel

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Zettel