citeworks_cff/lib.rs
1//! [Citation File Format](https://citation-file-format.github.io) serde types and implementations.
2//!
3//! This targets CFF 1.2.0 but may not support the entire specification.
4//!
5//! The top level API mimics [serde_yaml]'s:
6//!
7//! ```
8//! let cff = citeworks_cff::from_str(r#"
9//! cff-version: 1.2.0
10//! message:
11//! If you dare use this commercial, closed-source, strangely versioned
12//! software in your research, please at least cite it as below.
13//! authors:
14//! - family-names: Vader
15//! name-suffix: né Skywalker
16//! given-names: 'Anakin "Darth"'
17//! - name: anonymous
18//! title: Opaquity
19//! version: opq-1234-XZVF-ACME-RLY
20//! date-released: 2017-02-28
21//! url: http://www.opaquity.com/
22//! contact:
23//! - name: Dark Side Software
24//! address: DS-1 Orbital Battle Station, near Scarif
25//! email: father@imperial-empire.com
26//! tel: +850 (0)123-45-666
27//! "#).unwrap();
28//!
29//! assert_eq!(
30//! cff
31//! .authors[0]
32//! .as_person()
33//! .and_then(|his| his.family_names.as_deref()),
34//! Some("Vader")
35//! );
36//! ```
37#![warn(clippy::unwrap_used, missing_docs)]
38#![deny(rust_2018_idioms)]
39#![forbid(unsafe_code)]
40
41use std::io::{Read, Write};
42
43pub use serde_yaml::Result;
44
45#[doc(inline)]
46pub use cff::{Cff, WorkType};
47#[doc(inline)]
48pub use date::Date;
49#[doc(inline)]
50pub use license::License;
51
52mod cff;
53mod date;
54pub mod identifiers;
55mod license;
56pub mod names;
57pub mod references;
58
59/// Deserialize CFF from an IO stream of YAML.
60pub fn from_reader<R>(rdr: R) -> Result<Cff>
61where
62 R: Read,
63{
64 serde_yaml::from_reader(rdr)
65}
66
67/// Deserialize CFF from bytes of YAML text.
68pub fn from_slice(v: &[u8]) -> Result<Cff> {
69 serde_yaml::from_slice(v)
70}
71
72/// Deserialize CFF from a string of YAML text.
73pub fn from_str(s: &str) -> Result<Cff> {
74 serde_yaml::from_str(s)
75}
76
77/// Serialize the given CFF as a String of YAML.
78pub fn to_string(value: &Cff) -> Result<String> {
79 serde_yaml::to_string(value)
80}
81
82/// Serialize the given CFF as a YAML byte vector.
83pub fn to_vec(value: &Cff) -> Result<Vec<u8>> {
84 serde_yaml::to_string(value).map(|v| v.into_bytes())
85}
86
87/// Serialize the given CFF as YAML into the IO stream.
88pub fn to_writer<W>(writer: W, value: &Cff) -> Result<()>
89where
90 W: Write,
91{
92 serde_yaml::to_writer(writer, value)
93}