commit 0cc98ffec7f6b7c562ad5c8c929dcb90c3620487
parent 0d5bb2ccf50e0818596c23ddd4419d73875f4a48
Author: lash <dev@holbrook.no>
Date: Wed, 27 Jul 2022 09:10:56 +0000
Complete docs
Diffstat:
5 files changed, 58 insertions(+), 21 deletions(-)
diff --git a/src/biblatex.rs b/src/biblatex.rs
@@ -42,6 +42,13 @@ fn parse_digest(entry: &Entry) -> Vec<u8> {
digest
}
+/// Read one or more metadata entries from the `bibtex` source.
+///
+/// Will return `ParseError` if any of the records are invalid.
+///
+/// # Arguments
+///
+/// * `r` - reader implementation providing the source.
pub fn read_all(mut r: impl Read) -> Result<Vec<MetaData>, ParseError> {
let mut s = String::new();
let c = r.read_to_string(&mut s);
diff --git a/src/dc/mod.rs b/src/dc/mod.rs
@@ -4,12 +4,20 @@ use biblatex::EntryType;
use std::str::FromStr;
+/// Represents the parts of the metadata schema covered by the Dublin Core vocabulary.
pub struct DCMetaData {
+ /// Title of work represented by media.
pub title: String,
+ /// Author(s) of work represented by media. Multiple authors may be specified by separating
+ /// them with comma.
pub author: String,
+ /// Type of work represented by media. Maps to bibtex entry types.
pub typ: EntryType,
+ /// Comma-separated keyword list describing the content.
pub subject: Option<String>,
+ /// MIME type of the media.
pub mime: Option<Mime>,
+ /// What language the work represented by this media file is in.
pub language: Option<LanguageIdentifier>,
}
@@ -27,11 +35,15 @@ pub const DC_XATTR_TYPE: &str = "user.dcterms:type";
pub const DC_XATTR_MEDIATYPE: &str = "user.dcterms:MediaType";
impl DCMetaData {
- pub fn new(title: &str, author: &str, typ: EntryType) -> DCMetaData {
+ /// Creates a new Dublin Core metadata part with minimal data.
+ ///
+ /// `title`, `author` and `entry_type` map to corresponding [DCMetaData](DCMetaData)
+ /// properties.
+ pub fn new(title: &str, author: &str, entry_type: EntryType) -> DCMetaData {
DCMetaData{
title: String::from(title),
author: String::from(author),
- typ: typ,
+ typ: entry_type,
subject: None,
mime: None,
language: None,
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,12 +1,28 @@
-//! kitab is a CLI tool to manage backup of media metadata information, primarily for
+//! kitab is a CLI tool to manage backup of media metadata information, primarily intended for
//! bibliographical sources.
//!
//! The tool can recursively apply metadata as extended attributes on all files in a filesystem
//! location whose digests match the respective keys of the metadata.
//!
//! Also, metadata can be imported from the same extended file attributes, as well as
-//! [bibtex](http://www.bibtex.org/Format/) and
-//! kitab's native store format.
+//! files containing [bibtex](http://www.bibtex.org/Format/) entries and
+//! entries in kitab's native store format.
+//!
+//! ## Usage examples
+//!
+//! ``` ignore;
+//! ## import rdf-turtle entries from file to store.
+//! $ kitab import source.ttl
+//!
+//! ## import bibtex entries from file to store
+//! $ kitab import source.bib
+//!
+//! ## import entries from any valid source under the given path
+//! $ kitab import /path/to/metadata_and_or_media_files
+//!
+//! ## apply metadata on files matching digests in store
+//! $ kitab apply /path/to/media_files
+//! ```
//!
//! ## Native store format
//!
@@ -20,6 +36,7 @@
//! <URN:sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae> predicate object
//! [...]
//! ```
+//! Please forgive the lack of a schema describing the data. It will follow.
//!
//! ## Store location
//!
@@ -74,6 +91,11 @@
//!
//! Without the `magic` feature, the `dcterms.MediaType` will not be included in the metadata
//! record.
+//!
+//! ## Debugging
+//!
+//! `kitab` uses [env_logger](env_logger). Loglevel can be set using the
+//! `RUST_LOG` environment variable to see what's going on when running the tool.
#![crate_name = "kitab"]
pub mod meta;
diff --git a/src/main.rs b/src/main.rs
@@ -44,13 +44,6 @@ fn args_setup() -> ArgMatches<'static> {
let mut o = App::new("kitab");
o = o.version("0.0.1");
o = o.author("Louis Holbrook <dev@holbrook.no>");
- o = o.arg(
- Arg::with_name("file")
- .long("file")
- .short("f")
- .value_name("File to match records against")
- .takes_value(true)
- );
let mut o_import = (
SubCommand::with_name("import")
.about("import information from file")
@@ -64,18 +57,18 @@ fn args_setup() -> ArgMatches<'static> {
);
o = o.subcommand(o_import);
- let mut o_scan = (
- SubCommand::with_name("scan")
+ let mut o_apply = (
+ SubCommand::with_name("apply")
.about("import information from file")
.version("0.0.1")
);
- o_scan = o_scan.arg(
+ o_apply = o_apply.arg(
Arg::with_name("PATH")
.help("Path to operate on")
.required(true)
.index(1)
);
- o = o.subcommand(o_scan);
+ o = o.subcommand(o_apply);
o.get_matches()
}
@@ -83,7 +76,7 @@ fn args_setup() -> ArgMatches<'static> {
// commands
// kitab import <file> - attempt in order import rdf, import spec
// kitab export <file> - export rdf/turtle
- // kitab scan <path> - recursively
+ // kitab apply <path> - recursively
fn resolve_directory(args: &ArgMatches) -> PathBuf {
match BaseDirs::new() {
@@ -188,7 +181,7 @@ fn exec_import_biblatex(f: &Path, index_path: &Path) -> bool {
true
}
-fn exec_scan(p: &Path, index_path: &Path) -> bool {
+fn exec_apply(p: &Path, index_path: &Path) -> bool {
for entry in WalkDir::new(&p)
.into_iter()
.filter_map(Result::ok)
@@ -251,11 +244,11 @@ fn main() {
}
let mut r = true;
- match args.subcommand_matches("scan") {
+ match args.subcommand_matches("apply") {
Some(v) => {
let p = str_to_path(v);
- info!("scan from path {:?}", &p);
- if !exec_scan(p.as_path(), index_dir.as_path()) {
+ info!("apply from path {:?}", &p);
+ if !exec_apply(p.as_path(), index_dir.as_path()) {
r = false;
}
},
diff --git a/src/store.rs b/src/store.rs
@@ -7,17 +7,20 @@ use std::fs::File;
use crate::meta::MetaData;
+/// Represents the filesystem storage location for metadata.
pub struct FileStore{
path: PathBuf,
}
impl FileStore {
+ /// Create new store.
pub fn new(p: &Path) -> Self {
FileStore{
path: p.to_path_buf(),
}
}
+ /// Generate new writer for adding / modifying a metadata entry in the store.
pub fn writer(&self, entry: &MetaData) -> impl Write {
let p = self.path.join(entry.fingerprint());
File::create(&p).unwrap()
