Skip to main content

badness_parser/semantic/
completion.rs

1//! Static word lists and metadata used only by completion and hover.
2
3use std::collections::HashMap;
4use std::sync::LazyLock;
5
6use serde::Deserialize;
7
8include!(concat!(env!("OUT_DIR"), "/expl3_names.rs"));
9
10/// Public expl3 names from the pinned CWL catalog, without argument signatures.
11pub fn expl3_names() -> &'static [&'static str] {
12    EXPL3_NAMES
13}
14
15// The baked `.sty`/`.cls` name lists are generated from TeX Live's tlpdb. File
16// order is completion rank; comments and the primary/secondary separator are not
17// candidates.
18const PACKAGE_NAMES_TXT: &str = include_str!("../../data/package_names.txt");
19const CLASS_NAMES_TXT: &str = include_str!("../../data/class_names.txt");
20
21static PACKAGE_NAMES: LazyLock<Vec<&'static str>> =
22    LazyLock::new(|| parse_name_list(PACKAGE_NAMES_TXT));
23static CLASS_NAMES: LazyLock<Vec<&'static str>> =
24    LazyLock::new(|| parse_name_list(CLASS_NAMES_TXT));
25
26fn parse_name_list(text: &'static str) -> Vec<&'static str> {
27    text.lines()
28        .filter(|line| !line.is_empty() && !line.starts_with('#') && *line != "---")
29        .collect()
30}
31
32/// All known `.sty` package name stems, in completion-rank order.
33pub fn package_names() -> &'static [&'static str] {
34    &PACKAGE_NAMES
35}
36
37/// All known `.cls` class name stems, in completion-rank order.
38pub fn class_names() -> &'static [&'static str] {
39    &CLASS_NAMES
40}
41
42const COLORS_JSON: &str = include_str!("../../data/colors.json");
43const TIKZ_LIBRARIES_JSON: &str = include_str!("../../data/tikz_libraries.json");
44const ARG_ENUMS_JSON: &str = include_str!("../../data/arg_enums.json");
45
46#[derive(Deserialize)]
47struct ColorsData {
48    names: Vec<String>,
49    models: Vec<String>,
50}
51
52#[derive(Deserialize)]
53struct TikzLibrariesData {
54    tikz: Vec<String>,
55    pgf: Vec<String>,
56}
57
58static COLORS: LazyLock<ColorsData> = LazyLock::new(|| {
59    serde_json::from_str(COLORS_JSON).expect("bundled data/colors.json must be valid")
60});
61static TIKZ_LIBRARIES: LazyLock<TikzLibrariesData> = LazyLock::new(|| {
62    serde_json::from_str(TIKZ_LIBRARIES_JSON)
63        .expect("bundled data/tikz_libraries.json must be valid")
64});
65static ARG_ENUMS: LazyLock<HashMap<String, HashMap<usize, Vec<String>>>> = LazyLock::new(|| {
66    serde_json::from_str(ARG_ENUMS_JSON).expect("bundled data/arg_enums.json must be valid")
67});
68
69fn as_static_slice(names: &'static [String]) -> Vec<&'static str> {
70    names.iter().map(String::as_str).collect()
71}
72
73/// Built-in color names for color-argument completion.
74pub fn color_names() -> &'static [&'static str] {
75    static NAMES: LazyLock<Vec<&'static str>> = LazyLock::new(|| as_static_slice(&COLORS.names));
76    &NAMES
77}
78
79/// Built-in color models for `\definecolor` model completion.
80pub fn color_models() -> &'static [&'static str] {
81    static MODELS: LazyLock<Vec<&'static str>> = LazyLock::new(|| as_static_slice(&COLORS.models));
82    &MODELS
83}
84
85/// Built-in TikZ library names.
86pub fn tikz_libraries() -> &'static [&'static str] {
87    static LIBS: LazyLock<Vec<&'static str>> =
88        LazyLock::new(|| as_static_slice(&TIKZ_LIBRARIES.tikz));
89    &LIBS
90}
91
92/// Built-in PGF library names.
93pub fn pgf_libraries() -> &'static [&'static str] {
94    static LIBS: LazyLock<Vec<&'static str>> =
95        LazyLock::new(|| as_static_slice(&TIKZ_LIBRARIES.pgf));
96    &LIBS
97}
98
99/// Suggested values for a command's brace-group argument.
100pub fn arg_enum_values(name: &str, index: usize) -> Option<&'static [String]> {
101    ARG_ENUMS.get(name)?.get(&index).map(Vec::as_slice)
102}
103
104type PackageMetaMap = phf::Map<&'static str, PackageMeta>;
105
106/// Shipped CTAN metadata for one package or class stem.
107#[derive(Debug, Clone, Copy)]
108pub struct PackageMeta {
109    pub desc: Option<&'static str>,
110    pub ctan: Option<&'static str>,
111}
112
113impl PackageMeta {
114    /// The canonical CTAN package page, when a catalogue id is known.
115    pub fn ctan_url(&self) -> Option<String> {
116        self.ctan.map(|id| format!("https://ctan.org/pkg/{id}"))
117    }
118}
119
120const fn meta(desc: Option<&'static str>, ctan: Option<&'static str>) -> PackageMeta {
121    PackageMeta { desc, ctan }
122}
123
124include!(concat!(env!("OUT_DIR"), "/package_metadata.rs"));
125
126/// The shipped CTAN metadata for a package or class stem.
127pub fn package_metadata(name: &str) -> Option<&'static PackageMeta> {
128    PACKAGE_METADATA.get(name)
129}
130
131#[cfg(test)]
132mod tests {
133    use super::*;
134
135    #[test]
136    fn expl3_catalog_is_sorted_and_separate_from_signatures() {
137        let names = expl3_names();
138        assert_eq!(names.len(), 4708);
139        assert!(names.windows(2).all(|pair| pair[0] < pair[1]));
140        for name in ["tl_set:Nn", "seq_map_inline:Nn", "cs_new:Npn", "l_tmpa_tl"] {
141            assert!(names.binary_search(&name).is_ok());
142            assert!(crate::semantic::signature::cwl().command(name).is_none());
143            assert!(
144                crate::semantic::signature::builtin()
145                    .command(name)
146                    .is_none()
147            );
148        }
149        assert!(names.iter().all(|name| !name.contains("__")));
150    }
151
152    #[test]
153    fn arg_enums_load_and_resolve() {
154        assert_eq!(
155            arg_enum_values("pagenumbering", 0),
156            Some(
157                ["arabic", "roman", "Roman", "alph", "Alph"]
158                    .map(String::from)
159                    .as_slice()
160            )
161        );
162        assert!(arg_enum_values("pagestyle", 0).is_some());
163        assert!(arg_enum_values("pagestyle", 1).is_none());
164        assert!(arg_enum_values("definitelynotacommand", 0).is_none());
165    }
166
167    #[test]
168    fn package_metadata_resolves_stem_to_ctan_facts() {
169        let meta = package_metadata("amsmath").expect("amsmath in metadata DB");
170        assert_eq!(meta.desc, Some("AMS mathematical facilities for LaTeX"));
171        assert_eq!(
172            meta.ctan_url().as_deref(),
173            Some("https://ctan.org/pkg/latex-amsmath")
174        );
175        assert!(package_metadata("definitely-not-a-real-package").is_none());
176    }
177}