prepyrus 0.1.0

Parsing and writing to MDX files for Chicago author-date citaitons using BibTeX
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

pub mod inserter;
pub mod utils;
pub mod validator;

use utils::{BiblatexUtils, CoreUtils};

/// Prepyrus is a tool for verifying and processing MDX files
/// that contain citations in Chicago author-date style and certain metadata.
///
/// ## Usage
///
/// Add the create to your `Cargo.toml` and use it as shown below:
///
/// ```toml
/// [dependencies]
/// prepyrus = "0.1"
/// ```
///
/// Main API interface is the `run_prepyrus` function. Example usage:
///
/// ```rust,ignore
/// use prepyrus::run_prepyrus;
///
/// fn main() {
///     let args: Vec<String> = std::env::args().collect();
///     if args.len() < 4 {
///         eprintln!(
///             "Expected more args. Usage: prepyrus <bibliography.bib> <target_dir_or_file> <mode>"
///         );
///         std::process::exit(1);
///     }
///
///     if let Err(e) = run_prepyrus(&args[1], &args[2], &args[3]) {
///         eprintln!("Error: {}", e);
///         std::process::exit(1);
///     }
///
///     println!("===Prepyrus completed successfully!");
/// }
/// ```
///
/// The function takes three arguments: `<bibliography.bib> <target_dir_or_file> <mode>`
/// - a bibliography file (.bib),
/// - a target directory or .mdx file,
/// - and a mode (either `verify` or `process`).
///
/// `verify` mode only verifies the citations in the MDX files against the bibliography.
///
/// **⚠️ NOTE: This mode modifies the MDX files.**  
/// `process` mode _additionally_ processes the MDX files by injecting bibliography and other details into the MDX files.
///
/// ## Description
///
/// The tool is designed to work with MDX files that contain citations in Chicago author-date style. Examples:
///
/// ```markdown
/// "...nowhere on heaven or on earth is there anything which does not contain both being and nothing in itself" (Hegel 2010, 61).
/// ```
///
/// The tool parses and verifies the citations in the MDX files against a
/// bibliography file in BibTeX format (using Biblatex).
/// If the citations are valid, the tool processes the MDX files
/// by adding a bibliography section at the end of the file.
/// It also adds author, editor, and contributor from the MDX file metadata if available.
/// Finally, it also adds a notes heading at the end if footnotes are present in the file.
///
/// The tool has two modes: `verify` and `process`.
///
/// In `verify` mode, the tool only verifies the citations in the MDX files
/// and matches them against the bibliography.  
/// In `process` mode, the tool _additionally_ processes the MDX files by injecting bibliography
/// and other details into the MDX files.
///
/// ## Limitations
///
/// The tool currently only supports citations in Chicago author-date style.
///
/// Only book entries are currently supported (plans to support more types in the future).
///
/// Only the following metadata fields are supported:
/// - author
/// - editor
/// - contributor
///
/// ## License
/// Apache-2.0
pub fn run_prepyrus(
    bib_file: &str,
    target_path: &str,
    mode: &str,
) -> Result<(), Box<dyn std::error::Error>> {
    CoreUtils::verify_arguments(&vec![
        bib_file.to_string(),
        target_path.to_string(),
        mode.to_string(),
    ]);

    let all_entries = BiblatexUtils::retrieve_bibliography_entries(bib_file)?;
    let mdx_paths = CoreUtils::extract_paths(target_path)?;

    // Phase 1: Verify MDX files
    let articles_file_data = validator::verify_mdx_files(mdx_paths.clone(), &all_entries)?;

    // Phase 2: Process MDX files (requires mode to be set to "process")
    if mode == "process" {
        inserter::process_mdx_files(articles_file_data);
    }

    Ok(())
}