kitab

Unnamed repository; edit this file 'description' to name the repository.
Info | Log | Files | Refs | LICENSE

lib.rs (4076B)

      1 //! kitab is a CLI tool to manage backup of media metadata information, primarily intended for
      2 //! bibliographical sources.
      3 //!
      4 //! The tool can recursively apply metadata as extended attributes on all files in a filesystem
      5 //! location whose digests match the respective keys of the metadata.
      6 //!
      7 //! Also, metadata can be imported from the same extended file attributes, as well as
      8 //! files containing [bibtex](http://www.bibtex.org/Format/) entries and
      9 //! entries in kitab's native store format.
     10 //!
     11 //! ## Usage examples
     12 //!
     13 //! ``` ignore;
     14 //! ## import rdf-turtle entries from file to store.
     15 //! $ kitab import source.ttl
     16 //!
     17 //! ## import bibtex entries from file to store
     18 //! $ kitab import source.bib
     19 //!  
     20 //! ## import entries from any valid source under the given path
     21 //! $ kitab import /path/to/metadata_and_or_media_files
     22 //!
     23 //! ## apply metadata on files matching digests in store
     24 //! $ kitab apply /path/to/media_files
     25 //! ```
     26 //!
     27 //! ## Native store format
     28 //!
     29 //! The native data format is [rdf-turtle](https://www.w3.org/TR/turtle/), currently limited to a
     30 //! subset of the [DublinCore](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/) vocabulary.
     31 //!
     32 //! The subject of all entries is a URN specifying the digest of the matching file, in the format
     33 //! (digest hex for illustration purpose only):
     34 //!
     35 //! ``` ignore;
     36 //! <URN:sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae> predicate object
     37 //! [...]
     38 //! ```
     39 //! Please forgive the lack of a schema describing the data. It will follow.
     40 //!
     41 //! ## Store location
     42 //!
     43 //! Metadata files are stored under `~/.local/share/kitab/idx/<hex>` where `<hex>` is the
     44 //! (lowercase) digest hex matching the URN in the record.
     45 //!
     46 //! ## Supported digests
     47 //!
     48 //! * `SHA512` (native)
     49 //! * `SHA256`
     50 //!
     51 //! Metadata imported from extended attributes will use the `SHA512` digest of the file as the
     52 //! storage key.
     53 //!
     54 //! ## Example
     55 //!
     56 //! The rust crate author's [PDF
     57 //! copy](https://g33k.holbrook.no/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553) of the _Bitcoin whitepaper_ has `SHA256` hash
     58 //! `b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553`
     59 //!
     60 //! The rdf-turtle record for this document could be:
     61 //!
     62 //! ``` ignore;
     63 //! @prefix dcterms: <https://purl.org/dc/terms/> .
     64 //! @prefix dcmi: <https://purl.org/dc/dcmi/> .
     65 //!
     66 //! <URN:sha256:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553>
     67 //!     dcterms:title "Bitcoin: A Peer-to-Peer Electronic Cash System" ;
     68 //!     dcterms:subject "bitcoin,cryptocurrency,cryptography" ;
     69 //!	    dcterms:creator "Satoshi Nakamoto" ;
     70 //!	    dcterms:type "article" ;
     71 //!	    dcterms:MediaType "application/pdf" ;
     72 //!	    dcterms:language "en" .
     73 //! ```
     74 //!
     75 //! After applying the metadata to the document itself, the extended attributes could look like
     76 //! this:
     77 //!
     78 //! ``` ignore;
     79 //! $ getfattr -d pub/papers/bitcoin.pdf 
     80 //! user.dcterms:creator="Satoshi Nakamoto"
     81 //! user.dcterms:language="en"
     82 //! user.dcterms:subject="bitcoin,cryptocurrency"
     83 //! user.dcterms:title="Bitcoin: A Peer-to-Peer Electronic Cash System"
     84 //! user.dcterms:type="article"
     85 //! ```
     86 //!
     87 //! ### Optional: File magic
     88 //!
     89 //! If built with the `magic` feature, an attempt will be made to determine the media type for each
     90 //! file, and include the `dcterms:MediaType` predicate accordingly.
     91 //!
     92 //! Without the `magic` feature, the `dcterms.MediaType` will not be included in the metadata
     93 //! record.
     94 //!
     95 //! ## Debugging
     96 //!
     97 //! `kitab` uses [env_logger](env_logger). Loglevel can be set using the
     98 //! `RUST_LOG` environment variable to see what's going on when running the tool.
     99 //!
    100 //! ## Caveats
    101 //!
    102 //! For now only linux is supported.
    103 #![crate_name = "kitab"]
    104 
    105 #[cfg(not(target_os = "linux"))]
    106 compile_error!("only linux is supported for now");
    107 
    108 pub mod meta;
    109 
    110 pub mod dc;
    111 
    112 pub mod store;
    113 
    114 pub mod rdf;
    115 
    116 pub mod biblatex;
    117 
    118 pub mod error;
    119 
    120 pub mod digest;
    121 
    122 #[cfg(test)]
    123 mod tests {
    124     use env_logger;
    125 
    126     #[test]
    127     fn test_setup_env_logger() {
    128         env_logger::init();
    129     }
    130 }