{"id":19269147,"url":"https://github.com/typst/hayagriva","last_synced_at":"2025-05-14T03:06:46.960Z","repository":{"id":43464807,"uuid":"299312912","full_name":"typst/hayagriva","owner":"typst","description":"Rusty bibliography management.","archived":false,"fork":false,"pushed_at":"2025-05-13T22:11:02.000Z","size":1982,"stargazers_count":434,"open_issues_count":113,"forks_count":65,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-14T00:09:13.175Z","etag":null,"topics":["bibtex","citations","cli","references","yaml"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/typst.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["typst"]}},"created_at":"2020-09-28T13:10:34.000Z","updated_at":"2025-05-13T22:11:07.000Z","dependencies_parsed_at":"2023-11-14T16:35:47.533Z","dependency_job_id":"64ea5ecf-2a54-43e0-a990-56f3afdd5517","html_url":"https://github.com/typst/hayagriva","commit_stats":{"total_commits":106,"total_committers":3,"mean_commits":"35.333333333333336","dds":"0.21698113207547165","last_synced_commit":"c1c58e44eba1733726d596025e3357c6aa56826a"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typst%2Fhayagriva","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typst%2Fhayagriva/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typst%2Fhayagriva/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typst%2Fhayagriva/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/typst","download_url":"https://codeload.github.com/typst/hayagriva/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254059500,"owners_count":22007768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bibtex","citations","cli","references","yaml"],"created_at":"2024-11-09T20:18:41.269Z","updated_at":"2025-05-14T03:06:46.942Z","avatar_url":"https://github.com/typst.png","language":"Rust","funding_links":["https://github.com/sponsors/typst"],"categories":["Rust"],"sub_categories":[],"readme":"# Hayagriva\n\n[![Build status](https://github.com/typst/hayagriva/workflows/Continuous%20integration/badge.svg)](https://github.com/typst/hayagriva/actions)\n[![Current crates.io release](https://img.shields.io/crates/v/hayagriva)](https://crates.io/crates/hayagriva)\n[![Documentation](https://img.shields.io/badge/docs.rs-hayagriva-66c2a5?labelColor=555555\u0026logoColor=white\u0026logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K)](https://docs.rs/hayagriva/)\n\nRusty bibliography management.\n\nHayagriva is a tool that can help you or your apps deal with literature and\nother media. Its features include:\n\n- Data structures for literature collections\n- Reading and writing said collections from YAML files\n- Formatting literature into reference list entries and in-text citations as\n  defined by popular style guides\n- Interoperability with BibTeX\n- Querying your literature items by type and available metadata\n\nHayagriva can be used both as a library and as a Command Line Interface (CLI).\nSkip to the [section \"Usage\"](#usage) for more information about usage in your\napplication or to the [section \"Installation\"](#installation) to learn about how\nto install and use Hayagriva on your terminal.\n\n## Supported styles\n\nHayagriva supports all styles provided in the\n[official Citation Style Language repository](https://github.com/citation-style-language/styles),\ncurrently over 2,600.\n\n## Usage\n\n```rust\nuse hayagriva::io::from_yaml_str;\n\nlet yaml = r#\"\ncrazy-rich:\n    type: Book\n    title: Crazy Rich Asians\n    author: Kwan, Kevin\n    date: 2014\n    publisher: Anchor Books\n    location: New York, NY, US\n\"#;\n\n// Parse a bibliography\nlet bib = from_yaml_str(yaml).unwrap();\nassert_eq!(bib.get(\"crazy-rich\").unwrap().date().unwrap().year, 2014);\n\n// Format the reference\nuse std::fs;\nuse hayagriva::{\n    BibliographyDriver, BibliographyRequest, BufWriteFormat,\n    CitationItem, CitationRequest,\n};\nuse hayagriva::citationberg::{LocaleFile, IndependentStyle};\n\nlet en_locale = fs::read_to_string(\"tests/data/locales-en-US.xml\").unwrap();\nlet locales = [LocaleFile::from_xml(\u0026en_locale).unwrap().into()];\n\nlet style = fs::read_to_string(\"tests/data/art-history.csl\").unwrap();\nlet style = IndependentStyle::from_xml(\u0026style).unwrap();\n\nlet mut driver = BibliographyDriver::new();\n\nfor entry in bib.iter() {\n    let items = vec![CitationItem::with_entry(entry)];\n    driver.citation(CitationRequest::from_items(items, \u0026style, \u0026locales));\n}\n\nlet result = driver.finish(BibliographyRequest {\n    style: \u0026style,\n    locale: None,\n    locale_files: \u0026locales,\n});\n\nfor cite in result.citations {\n    println!(\"{}\", cite.citation.to_string())\n}\n```\n\nTo format entries, you need to wrap them in a `CitationRequest`. Each of these\ncan reference multiple entries in their respective `CitationItem`s.\nUse these with a `BibliographyDriver` to obtain formatted citations and bibliographies.\n\nYou can either supply your own CSL files or choose from about 100 bundled\ncitation styles using the `archive` feature.\n\nIf the default features are enabled, Hayagriva supports BibTeX and BibLaTeX\nbibliographies. You can use `io::from_biblatex_str` to parse such\nbibliographies.\n\nShould you need more manual control, the library's native `Entry` struct also\noffers an implementation of the `From\u003c\u0026biblatex::Entry\u003e`-Trait. You will need to\ndepend on the [biblatex](https://docs.rs/biblatex/latest/biblatex/) crate to\nobtain its `Entry`. Therefore, you could also use your BibLaTeX content like\nthis:\n\n```rust\nuse hayagriva::Entry;\nlet converted: Entry = your_biblatex_entry.into();\n```\n\nIf you do not need BibLaTeX compatibility, you can use Hayagriva without the\ndefault features by writing this in your `Cargo.toml`:\n\n```toml\n[dependencies]\nhayagriva = { version = \"0.8\", default-features = false }\n```\n\n### Selectors\n\nHayagriva uses a custom selector language that enables you to filter\nbibliographies by type of media. For more information about selectors, refer to\nthe [selectors.md\nfile](https://github.com/typst/hayagriva/blob/main/docs/selectors.md). While you\ncan parse user-defined selectors using the function `Selector::parse`, you may\ninstead want to use the selector macro to avoid the run time cost of parsing a\nselector when working with constant selectors.\n\n```rust\nuse hayagriva::select;\nuse hayagriva::io::from_yaml_str;\n\nlet yaml = r#\"\nquantized-vortex:\n    type: Article\n    author: Gross, E. P.\n    title: Structure of a Quantized Vortex in Boson Systems\n    date: 1961-05\n    page-range: 454-477\n    doi: 10.1007/BF02731494\n    parent:\n        issue: 3\n        volume: 20\n        title: Il Nuovo Cimento\n\"#;\n\nlet entries = from_yaml_str(yaml).unwrap();\nlet journal = select!((Article[\"date\"]) \u003e (\"journal\":Periodical));\nassert!(journal.matches(entries.nth(0).unwrap()));\n```\n\nThere are two ways to check if a selector matches an entry.\nYou should use [`Selector::matches`] if you just want to know if an item\nmatches a selector and [`Selector::apply`] to continue to work with the data from\nparents of a matching entry. Keep in mind that the latter function will\nreturn `Some` even if no sub-entry was bound / if the hash map is empty.\n\n## Installation\n\nRun this in your terminal:\n\n```bash\ncargo install hayagriva --features cli\n```\n\nCargo will install the Hayagriva Command Line Interface for you. Now, you just\nneed a Hayagriva YAML literature file or a Bib(La)TeX file to get started. The\nHayagriva YAML file is intuitive to write and can represent a wealth of media\ntypes, [learn how to write one in its dedicated\ndocumentation.](https://github.com/typst/hayagriva/blob/main/docs/file-format.md)\n\nSuppose you have this file saved as `literature.yml` in your current working\ndirectory:\n\n```yaml\ndependence:\n    type: Article\n    title: The program dependence graph and its use in optimization\n    author: [\"Ferrante, Jeanne\", \"Ottenstein, Karl J.\", \"Warren, Joe D.\"]\n    date: 1987-07\n    serial-number:\n        doi: \"10.1145/24039.24041\"\n    parent:\n        type: Periodical\n        title: ACM Transactions on Programming Languages and Systems\n        volume: 9\n        issue: 3\n\nfeminism:\n    type: Article\n    title: She swoons to conquer\n    author: Ungard-Sargon, Batya\n    editor: Weintraub, Pam\n    date: 2015-09-25\n    url: https://aeon.co/essays/can-you-enjoy-romance-fiction-and-be-a-feminist\n    parent:\n        type: Blog\n        title: Aeon\n```\n\nYou can then issue the following command to get reference list entries for both\nof these articles.\n\n```bash\nhayagriva literature.yml reference\n```\n\nHayagriva defaults to the Author-Date style of the Chicago Manual of Style (17th\nedition). If you prefer to use another style, you can, for example, do the\nfollowing to use the style of the American Psychological Association instead:\n\n```bash\nhayagriva literature.yml reference --style apa\n```\n\nAvailable values for the `--style` argument can be viewed by calling\n`hayagriva help reference`.\n\nIf you now need an in-text citation to the second article in the above file, you\ncan call:\n\n```bash\nhayagriva literature.yml cite --key feminism\n```\n\nThe `--key` takes a comma-separated list of keys (or a single one). The\nsub-command will then only work on the specified keys. Just like the `reference`\nsub-command, the `cite` command also allows the `--style` argument. Its possible\nvalues can be viewed with `hayagriva help cite`. It will default to the _Author\nDate_ style.\n\nInstead of the `--key` argument, you can also use `--select` to provide a custom\n[Hayagriva selector.](https://github.com/typst/hayagriva/blob/main/docs/selectors.md)\nFor example, you could run the following to only reference entries that have a\nURL or DOI at the top level:\n\n```bash\nhayagriva literature.yml --select \"*[url] | *[doi]\" reference\n```\n\nThis expression would match both entries in our example and therefore the\ncommand would return the same result as the first reference command.\n\nHayagriva also allows you to explore which values were bound to which\nsub-entries if the selector matches. This is especially useful if you intend to\nconsume Hayagriva as a dependency in your application and need to debug an\nexpression. Consider this selector which always binds the sub-entry with the\nvolume field to `a`, regardless of if it occurred at the top level or in the\nfirst parent: `a:*[volume] | * \u003e a:[volume]`. You can then use the command below\nto show which sub-entry the selector bound as `a` for each match:\n\n```bash\nhayagriva literature.yml --select \"a:*[volume] | * \u003e a:[volume]\" --show-bound\n```\n\nThe `--show-bound` flag shows all keys matching the selector or key filter and\ndetails which sub-entries of each entry were bound by the selector. If, instead,\nyou only want to obtain a list of matching keys, use the `--keys` flag.\n\nIf you are working with BibTeX, you can use your `.bib` file with Hayagriva just\nlike you would use a `.yml` file. If you want to convert your `.bib` file to a\n`.yml` file, you can simply pass the `.bib` file to the CLI without any additional\narguments. It will then show the YAML-formatted bibliography with key and selector\nfilters applied on standard output. If you therefore want to convert your `.bib`\nfile and save the result somewhere, you can just use `\u003e`:\n\n```bash\nhayagriva literature.bib \u003e converted.yml\n```\n\n## Contributing\n\nWe are looking forward to receiving your bugs and feature requests in the Issues\ntab. We would also be very happy to accept PRs for bug fixes, minor\nrefactorings, features that were requested in the issues and greenlit by us, as\nwell as the planned features listed below:\n\n- Implementing the YAML-to-BibLaTeX conversion\n- Documentation improvements\n- CSL bugfixes\n- CSL-M Support\n\nWe wish to thank each and every prospective contributor for the effort you (plan\nto) invest in this project and for adopting it!\n\n## License\n\nHayagriva is licensed under a MIT / Apache 2.0 dual license.\n\nUsers and consumers of the library may choose which of those licenses they want\nto apply whereas contributors have to accept that their code is in compliance\nand distributed under the terms of both of these licenses.\n\nHayagriva includes CSL styles that are licensed as CC-BY-SA 3.0 Deed if the\n`archive` feature is enabled. The file `styles.cbor.rkyv` is a collection of\nthese works and falls under this license. Retrieve attribution information by\ndeserializing it using the `styles` function and reading the `StyleInfo`\nstructs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypst%2Fhayagriva","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftypst%2Fhayagriva","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypst%2Fhayagriva/lists"}