Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_austenite/src/eval/lib/model/bibliography.rs

19.3 KiB, 45 runs

created by r1870400018:63248, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1// SPDX-License-Identifier: Apache-2.0
2// Original work copyright (c) the Typst project authors (typst-library `model/{bibliography,cite}.rs`, version 0.15.1).
3// Modified for Austenite: the elements' fields, defaults and default shows, ported to Hematite's types over `bib.rs`.
4// U5 owns this file: bibliography and the realisation of citations, over `crate::bib`.
5//
6// Sources are read when the element is constructed and kept on it (Typst keeps the parsed library the
7// same way), so a citation anywhere in the document can be formatted from the bibliography the previous
8// pass found. BibTeX and BibLaTeX sources are read, and Hayagriva YAML through `bib_hayagriva`. Two
9// styles are set, IEEE (Typst's default) and Chicago author-date; another style name is an error, since
10// no CSL processor exists yet. Only the document's first bibliography is consulted: `target` and `group`,
11// which split citations across several bibliographies, are accepted but not applied. Adjacent citations
12// are grouped by realisation (`cite-group`, which awaits its element kind), and [`show_cite_group`]
13// renders such a group.
14
15use crate::bib::{
16 Bibliography,
17 CiteForm,
18 CiteStyle,
19 Entry,
20 ListEntry,
21 RefRun,
22 RefStyle,
23};
24use crate::bib_hayagriva;
25use crate::diag::DiagnosticKind;
26use crate::eval::args::Args;
27use crate::eval::content::{
28 Content,
29 ElemKind,
30 FieldDefault,
31 FieldSpec,
32 FieldType,
33};
34use crate::eval::lib::model::common::{
35 self,
36 expect,
37 expect_cast,
38 to_content,
39 CastErr,
40 K,
41};
42use crate::eval::import;
43use crate::eval::lib::data;
44use crate::eval::lib::model::link;
45use crate::eval::lib::model::lookup;
46use crate::eval::select::Selector;
47use crate::eval::styles::{
48 StyleChain,
49 Styles,
50};
51use crate::eval::value::{
52 Label,
53 Value,
54};
55use crate::eval::Engine;
56use crate::syntax::Span;
57
58use oxedyne_fe2o3_core::prelude::*;
59
60const ANY: FieldType = FieldType::Any;
61
62static BIBLIOGRAPHY: [FieldSpec; 8] = [
63 FieldSpec::required("sources", ANY),
64 FieldSpec::named("title", ANY, FieldDefault::Auto),
65 FieldSpec::named("full", FieldType::Of(crate::eval::value::Type::Bool), FieldDefault::Bool(false)),
66 FieldSpec::named("style", ANY, FieldDefault::Str("ieee")),
67 FieldSpec::named("target", ANY, FieldDefault::Auto),
68 FieldSpec::named("group", ANY, FieldDefault::Auto),
69 FieldSpec::named("keys", ANY, FieldDefault::EmptyArray).synthesised().internal(),
70 FieldSpec::named("data", ANY, FieldDefault::EmptyArray).synthesised().internal(),
71];
72
73pub fn fields(kind: ElemKind) -> &'static [FieldSpec] {
74 match kind {
75 ElemKind::Bibliography => &BIBLIOGRAPHY,
76 ElemKind::CiteGroup => &CITE_GROUP,
77 _ => &[],
78 }
79}
80
81pub fn cast(_kind: ElemKind, name: &str, v: Value) -> Result<Value, CastErr> {
82 match name {
83 "sources" => match &v {
84 Value::Array(a) => {
85 for x in a.iter() {
86 ok!(expect(x, &[K::Path, K::Str, K::Bytes]));
87 }
88 Ok(v)
89 }
90 _ => expect_cast(v, &[K::Path, K::Str, K::Bytes, K::Array]),
91 },
92 "title" => match v {
93 Value::Auto | Value::None => Ok(v),
94 other => expect(&other, &[K::Content, K::None, K::Auto]).map(|_| to_content(other)),
95 },
96 "full" => expect(&v, &[K::Bool]).map(|_| v),
97 "style" => match &v {
98 Value::Str(s) => style_name(s).map(|_| style_value(s)),
99 other => Err(CastErr::Type(common::mismatch("string", other))),
100 },
101 "target" => expect(&v, &[K::Label, K::Func, K::Location, K::Selector, K::Auto]).map(|_| v),
102 "group" => expect_cast(v, &[K::Str, K::None, K::Auto]),
103 _ => Ok(v),
104 }
105}
106
107/// `cite-group`'s one field: the citations realisation gathered.
108pub fn cast_group(name: &str, v: Value) -> Result<Value, CastErr> {
109 match name {
110 "children" => expect(&v, &[K::Array]).map(|_| v),
111 _ => Ok(v),
112 }
113}
114
115static CITE_GROUP: [FieldSpec; 1] = [
116 FieldSpec::required("children", ANY),
117];
118
119/// Checks a style name: one Austenite sets; one of Typst's other built-in styles, refused as not yet
120/// supported; anything else unknown, as Typst says. A path to a `.csl` file is refused too.
121pub fn style_name(s: &str) -> Result<CiteStyle, CastErr> {
122 if let Some(st) = CiteStyle::by_name(s) {
123 return Ok(st);
124 }
125 if s.ends_with(".csl") || TYPST_STYLES.contains(&s) {
126 return Err(CastErr::Value(fmt!("the bibliography style `{}` is not supported yet \
127 (the styles set are ieee and chicago-author-date)", s)));
128 }
129 Err(CastErr::Value(fmt!("unknown style: {}", s)))
130}
131
132/// A style name as Typst stores it: IEEE's long name is `ieee`.
133pub fn style_value(s: &str) -> Value {
134 match CiteStyle::by_name(s) {
135 Some(CiteStyle::Ieee) => Value::str("ieee"),
136 _ => Value::str(s),
137 }
138}
139
140// Typst 0.15.1's built-in style names, for telling a style not yet set from a misspelt one.
141const TYPST_STYLES: &[&str] = &[
142 "alphanumeric", "american-anthropological-association", "american-chemical-society",
143 "american-geophysical-union", "american-institute-of-aeronautics-and-astronautics",
144 "american-institute-of-physics", "american-medical-association", "american-meteorological-society",
145 "american-physics-society", "american-physiological-society", "american-political-science-association",
146 "american-psychological-association", "apa", "american-society-for-microbiology",
147 "american-society-of-civil-engineers", "american-society-of-mechanical-engineers",
148 "american-sociological-association", "angewandte-chemie", "annual-reviews", "annual-reviews-author-date",
149 "associacao-brasileira-de-normas-tecnicas", "association-for-computing-machinery", "biomed-central",
150 "bristol-university-press", "british-medical-journal", "bmj", "chicago-notes", "chicago-fullnotes",
151 "chicago-shortened-notes", "copernicus", "cse-citation-sequence-brackets-8th-edition",
152 "council-of-science-editors", "cse-name-year", "council-of-science-editors-author-date",
153 "current-opinion", "deutsche-gesellschaft-f\u{fc}r-psychologie", "deutsche-sprache", "elsevier-harvard",
154 "elsevier-vancouver", "elsevier-with-titles", "frontiers", "future-medicine", "future-science",
155 "gb-7714-2005-numeric", "gb-7714-2015-author-date", "gb-7714-2015-note", "gb-7714-2015-numeric",
156 "gost-r-705-2008-numeric", "harvard-cite-them-right", "institute-of-physics-numeric",
157 "iso-690-author-date", "iso-690-numeric", "karger", "mary-ann-liebert-vancouver",
158 "modern-humanities-research-association-notes", "modern-humanities-research-association",
159 "modern-language-association", "mla", "modern-language-association-8", "mla-8",
160 "multidisciplinary-digital-publishing-institute", "nature", "nlm-citation-sequence", "vancouver",
161 "nlm-citation-sequence-superscript", "vancouver-superscript", "pensoft", "public-library-of-science",
162 "royal-society-of-chemistry", "sage-vancouver", "sist02", "springer-basic", "springer-basic-author-date",
163 "springer-fachzeitschriften-medizin-psychologie", "springer-humanities-author-date",
164 "springer-lecture-notes-in-computer-science", "springer-mathphys", "springer-socpsych-author-date",
165 "springer-vancouver", "taylor-and-francis-chicago-author-date",
166 "taylor-and-francis-national-library-of-medicine", "the-institution-of-engineering-and-technology",
167 "the-lancet", "thieme", "trends", "turabian-author-date", "turabian-fullnote-8",
168];
169
170/// `bibliography(sources, ..)`: the schema walk, then the sources read and their keys checked.
171pub fn construct(engine: &mut Engine, args: &mut Args) -> Outcome<Content> {
172 let span = args.span;
173 // A path resolves at the argument that wrote it, as Typst does: `bibliography.with("refs.bib")`
174 // handed to a template in another file still names the caller's file.
175 let at = args.items.iter()
176 .find(|a| a.name.is_none() || a.name.as_deref() == Some("sources"))
177 .map(|a| a.span)
178 .unwrap_or(span);
179 let mut elem = res!(super::construct_schema(engine, ElemKind::Bibliography, args));
180 let sources = match elem.field("sources") {
181 Some(Value::Array(a)) => (**a).clone(),
182 Some(v) => vec![v.clone()],
183 None => Vec::new(),
184 };
185 let mut srcs: Vec<(SourceFormat, String)> = Vec::new();
186 for s in sources {
187 let (text, format) = match s {
188 Value::Str(p) => {
189 let path = res!(import::resolve_path(engine, &p, at.file, at));
190 let bytes = res!(import::read_file(engine, &path, at));
191 let text = match String::from_utf8(bytes) {
192 Ok(t) => t,
193 Err(_) => return Err(engine.error(DiagnosticKind::Encoding, at, "file is not valid utf-8")),
194 };
195 // Typst chooses the reader by the path's extension.
196 let lower = p.to_ascii_lowercase();
197 let format = if lower.ends_with(".yml") || lower.ends_with(".yaml") {
198 SourceFormat::Yaml
199 } else if lower.ends_with(".bib") {
200 SourceFormat::Bib
201 } else {
202 return Err(engine.error(DiagnosticKind::Type, at, "unknown bibliography format (must be .yaml/.yml or .bib)"));
203 };
204 (text, format)
205 }
206 Value::Bytes(b) => match String::from_utf8((*b).clone()) {
207 Ok(t) => {
208 let format = SourceFormat::sniff(&t);
209 (t, format)
210 }
211 Err(_) => return Err(engine.error(DiagnosticKind::Encoding, at, "file is not valid utf-8")),
212 },
213 _ => continue,
214 };
215 srcs.push((format, text));
216 }
217 let mut seen: Vec<String> = Vec::new();
218 let mut dups: Vec<String> = Vec::new();
219 for (format, text) in &srcs {
220 for e in res!(read_source(engine, at, *format, text)) {
221 let k = e.key();
222 if seen.iter().any(|s| s == k) {
223 if !dups.iter().any(|d| d == k) {
224 dups.push(k.to_string());
225 }
226 } else {
227 seen.push(k.to_string());
228 }
229 }
230 }
231 if !dups.is_empty() {
232 return Err(engine.error(DiagnosticKind::Type, span, fmt!("duplicate bibliography keys: {}", dups.join(", "))));
233 }
234 let keys: Vec<Value> = seen.into_iter().map(Value::str).collect();
235 elem.set(res!(common::fid(ElemKind::Bibliography, "keys")), Value::array(keys));
236 // Each source is kept with its format, so that `works` reads it again with the same reader.
237 elem.set(res!(common::fid(ElemKind::Bibliography, "data")), Value::array(srcs.into_iter()
238 .map(|(f, t)| Value::array(vec![Value::str(f.tag()), Value::str(t)]))
239 .collect()));
240 Ok(elem)
241}
242
243#[derive(Clone, Copy, Debug, PartialEq, Eq)]
244enum SourceFormat {
245 Bib,
246 Yaml,
247}
248
249impl SourceFormat {
250 fn tag(self) -> &'static str {
251 match self {
252 Self::Bib => "bib",
253 Self::Yaml => "yaml",
254 }
255 }
256
257 fn from_tag(s: &str) -> Option<Self> {
258 match s {
259 "bib" => Some(Self::Bib),
260 "yaml" => Some(Self::Yaml),
261 _ => None,
262 }
263 }
264
265 /// Bytes carry no extension: a source with a BibTeX entry opener at the start of a line is BibTeX,
266 /// anything else Hayagriva YAML, where `@` cannot start a plain scalar.
267 fn sniff(text: &str) -> Self {
268 if text.lines().any(|l| l.trim_start().starts_with('@')) {
269 Self::Bib
270 } else {
271 Self::Yaml
272 }
273 }
274}
275
276/// One source's entries, read by its format's reader; a fault is reported at `at`.
277fn read_source(engine: &mut Engine, at: Span, format: SourceFormat, text: &str) -> Outcome<Vec<Entry>> {
278 match format {
279 SourceFormat::Bib => Ok(res!(Bibliography::parse(text)).into_entries()),
280 SourceFormat::Yaml => {
281 let doc = match data::yaml_parse(text) {
282 Ok(v) => v,
283 Err((pos, m)) => return Err(data::parse_error(engine, at, "YAML", text, pos, &m)),
284 };
285 match bib_hayagriva::entries(&doc) {
286 Ok(es) => Ok(es),
287 Err(m) => Err(engine.error(DiagnosticKind::Type, at, m)),
288 }
289 }
290 }
291}
292
293/// The sources as one library, an entry's first appearance kept.
294fn parse(engine: &mut Engine, span: Span, srcs: &[(SourceFormat, String)]) -> Outcome<Bibliography> {
295 let mut all = Vec::new();
296 for (format, text) in srcs {
297 all.extend(res!(read_source(engine, span, *format, text)));
298 }
299 Ok(Bibliography::from_entries(all))
300}
301
302/// Does this bibliography element hold `key`?
303pub fn has_key(bib: &Content, key: &Label) -> bool {
304 match bib.field("keys") {
305 Some(Value::Array(a)) => a.iter().any(|k| matches!(k, Value::Str(s) if s.as_str() == key.as_str())),
306 _ => false,
307 }
308}
309
310/// Headings in a bibliography are not numbered; the list is indented by 1em.
311pub fn show_set() -> Outcome<Styles> {
312 common::props(vec![
313 (ElemKind::Heading, "numbering", Value::None),
314 (ElemKind::Pad, "left", common::em(1.0)),
315 ])
316}
317
318/// What formatting a citation needs: the bibliography, its library, its style and the cited keys in
319/// first-citation order.
320struct Works {
321 bib: Content,
322 lib: Bibliography,
323 style: CiteStyle,
324 cited: Vec<String>,
325}
326
327fn works(engine: &mut Engine, span: Span) -> Outcome<Works> {
328 let bibs = res!(lookup::query(engine, &Selector::Elem(ElemKind::Bibliography, None), span));
329 let bib = match bibs.into_iter().next() {
330 Some(b) => b,
331 None => return Err(engine.error(DiagnosticKind::Type, span, "the document does not contain a bibliography")),
332 };
333 let srcs: Vec<(SourceFormat, String)> = match bib.field("data") {
334 Some(Value::Array(a)) => a.iter().filter_map(|v| match v {
335 Value::Array(pair) => match pair.as_slice() {
336 [Value::Str(f), Value::Str(t)] => SourceFormat::from_tag(f).map(|f| (f, t.to_string())),
337 _ => None,
338 },
339 _ => None,
340 }).collect(),
341 _ => Vec::new(),
342 };
343 let lib = res!(parse(engine, span, &srcs));
344 let style = match bib.field("style") {
345 Some(Value::Str(s)) => CiteStyle::by_name(s).unwrap_or(CiteStyle::Ieee),
346 _ => CiteStyle::Ieee,
347 };
348 let mut cited: Vec<String> = Vec::new();
349 let citing = Selector::Or(vec![Selector::Elem(ElemKind::Cite, None), Selector::Elem(ElemKind::Ref, None)]);
350 for e in res!(lookup::query(engine, &citing, span)).iter() {
351 let key = match e.kind() {
352 Some(ElemKind::Cite) => e.field("key"),
353 Some(ElemKind::Ref) => e.field("target"),
354 _ => None,
355 };
356 if let Some(Value::Label(l)) = key {
357 if lib.has(l.as_str()) && !cited.iter().any(|c| c == l.as_str()) {
358 cited.push(l.as_str().to_string());
359 }
360 }
361 }
362 Ok(Works { bib, lib, style, cited })
363}
364
365/// Runs as content: italics as `emph`, a URL or a DOI as a link.
366fn runs_to_content(runs: &[RefRun], span: Span) -> Outcome<Content> {
367 let mut seq = Vec::with_capacity(runs.len());
368 for r in runs {
369 let text = common::text(&r.text).with_span(span);
370 seq.push(match r.style {
371 RefStyle::Normal => text,
372 RefStyle::Italic => res!(common::raw_elem(ElemKind::Emph, span, vec![("body", Value::Content(text))])),
373 RefStyle::Link => res!(common::raw_elem(ElemKind::Link, span, vec![
374 ("dest", Value::str(r.text.as_str())),
375 ("body", Value::Content(text)),
376 ])),
377 RefStyle::Doi => res!(common::raw_elem(ElemKind::Link, span, vec![
378 ("dest", Value::str(fmt!("https://doi.org/{}", r.text))),
379 ("body", Value::Content(text)),
380 ])),
381 });
382 }
383 Ok(Content::sequence(seq))
384}
385
386fn citation_parts(engine: &mut Engine, elem: &Content, styles: &StyleChain, works: &Works)
387 -> Outcome<(String, Option<CiteForm>, Option<String>, CiteStyle)>
388{
389 let span = elem.span();
390 let key = match elem.field("key") {
391 Some(Value::Label(l)) => l.as_str().to_string(),
392 _ => return Err(engine.error(DiagnosticKind::Type, span, "missing argument: key")),
393 };
394 if !works.lib.has(&key) {
395 return Err(engine.error(DiagnosticKind::Type, span, fmt!("key `{}` does not exist in the bibliography", key)));
396 }
397 let form = match res!(common::get(elem, styles, "form")) {
398 Value::Str(s) => CiteForm::by_name(&s),
399 _ => None,
400 };
401 let supplement = match res!(common::get(elem, styles, "supplement")) {
402 Value::Content(c) if !c.is_empty() => Some(common::plain_text(&c)),
403 _ => None,
404 };
405 let style = match res!(common::get(elem, styles, "style")) {
406 Value::Str(s) => CiteStyle::by_name(&s).unwrap_or(works.style),
407 _ => works.style,
408 };
409 Ok((key, form, supplement, style))
410}
411
412/// A citation: its form in the bibliography's style, linked to the bibliography. A citation of form
413/// `none` shows nothing and only lists the work.
414pub fn show_cite(engine: &mut Engine, elem: &Content, styles: &StyleChain) -> Outcome<Content> {
415 let span = elem.span();
416 let works = res!(works(engine, span));
417 let (key, form, supplement, style) = res!(citation_parts(engine, elem, styles, &works));
418 let form = match form {
419 Some(f) => f,
420 None => return Ok(Content::empty()),
421 };
422 let runs = res!(works.lib.render_citation(style, &key, form, supplement.as_deref(), &works.cited));
423 let body = res!(runs_to_content(&runs, span));
424 match works.bib.location() {
425 Some(loc) => link::to_location(body, loc),
426 None => Ok(body),
427 }
428}
429
430/// Citations cited together: IEEE's `[1], [2]`, author-date's `(A 2001; B 2002)`.
431pub fn show_cite_group(engine: &mut Engine, cites: &[Content], styles: &StyleChain) -> Outcome<Content> {
432 let span = cites.first().map(|c| c.span()).unwrap_or(Span::detached());
433 let works = res!(works(engine, span));
434 let mut items: Vec<(String, Option<String>)> = Vec::new();
435 let mut style = works.style;
436 for c in cites {
437 let (key, _, supplement, s) = res!(citation_parts(engine, c, styles, &works));
438 style = s;
439 items.push((key, supplement));
440 }
441 let borrowed: Vec<(&str, Option<&str>)> = items.iter().map(|(k, s)| (k.as_str(), s.as_deref())).collect();
442 let parts = res!(works.lib.render_group(style, &borrowed, &works.cited));
443 let sep = crate::bib::group_separator(style);
444 let mut seq = Vec::new();
445 for (i, runs) in parts.iter().enumerate() {
446 if i > 0 {
447 seq.push(common::text(sep));
448 }
449 let body = res!(runs_to_content(runs, span));
450 seq.push(match works.bib.location() {
451 Some(loc) => res!(link::to_location(body, loc)),
452 None => body,
453 });
454 }
455 Ok(Content::sequence(seq))
456}
457
458const COLUMN_GUTTER: f64 = 0.65; // em, between a numbered entry's prefix and its body
459const HANGING_INDENT: f64 = 1.5; // em, of an unnumbered entry's second and later lines
460
461pub fn show(engine: &mut Engine, elem: &Content, styles: &StyleChain) -> Outcome<Option<Content>> {
462 if elem.is(ElemKind::CiteGroup) {
463 let cites: Vec<Content> = match elem.field("children") {
464 Some(Value::Array(a)) => a.iter().filter_map(|v| match v {
465 Value::Content(c) => Some(c.clone()),
466 _ => None,
467 }).collect(),
468 _ => Vec::new(),
469 };
470 return show_cite_group(engine, &cites, styles).map(Some);
471 }
472 let span = elem.span();
473 let mut seq = Vec::new();
474 let title = match res!(common::get(elem, styles, "title")) {
475 Value::Auto => Some(common::text(common::local(styles, "bibliography"))),
476 Value::None => None,
477 v => Some(common::display(v)),
478 };
479 if let Some(t) = title {
480 seq.push(res!(common::raw_elem(ElemKind::Heading, span, vec![
481 ("depth", Value::Int(1)),
482 ("body", Value::Content(common::spanned(t, span))),
483 ])));
484 }
485 let works = res!(works(engine, span));
486 let full = matches!(res!(common::get(elem, styles, "full")), Value::Bool(true));
487 let style = match res!(common::get(elem, styles, "style")) {
488 Value::Str(s) => CiteStyle::by_name(&s).unwrap_or(works.style),
489 _ => works.style,
490 };
491 let entries: Vec<ListEntry> = works.lib.render_list(style, &works.cited, full);
492 if entries.iter().any(|e| e.prefix.is_some()) {
493 let mut cells = Vec::with_capacity(entries.len() * 2);
494 for e in &entries {
495 cells.push(Value::Content(common::text(e.prefix.as_deref().unwrap_or(""))));
496 cells.push(Value::Content(res!(runs_to_content(&e.body.runs, span))));
497 }
498 let row_gutter = res!(common::style(styles, ElemKind::Par, "spacing"));
499 seq.push(res!(common::build(engine, ElemKind::Grid, span, cells, vec![
500 ("columns", Value::array(vec![Value::Auto, Value::Auto])),
501 ("column-gutter", Value::array(vec![common::em(COLUMN_GUTTER)])),
502 ("row-gutter", Value::array(vec![row_gutter])),
503 ])));
504 } else {
505 for e in &entries {
506 let body = res!(runs_to_content(&e.body.runs, span));
507 let block = if style.hangs() {
508 let pull = res!(common::h(engine, common::em(-HANGING_INDENT), false));
509 let inset = common::start_side(styles, common::em(HANGING_INDENT));
510 res!(common::block(engine, common::seq(vec![pull, body]), span, vec![("inset", inset)]))
511 } else {
512 res!(common::block(engine, body, span, Vec::new()))
513 };
514 seq.push(block);
515 }
516 }
517 Ok(Some(common::seq(seq)))
518}