big-code-analysis-ast 2.4.0

Parse and classification layer behind big-code-analysis (internal, version-locked)
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
111
112
113
114
115
116
117

//! Error type returned from the library's top-level entry points.
//!
//! `big_code_analysis::FromPathError`, the richer error of the
//! file-backed `Ast::from_path`, lives in the root crate's
//! `from_path_error` module; this one is the parse-layer error every
//! dispatch entry point returns.
//!
//! Prior to this module, every entry point returned `Option<…>` and
//! collapsed parse failure, empty input, and disabled-language builds
//! into a single `None`. [`MetricsError`] distinguishes those cases so
//! library consumers can react appropriately (e.g. report a disabled
//! language distinctly from an empty parse).
//!
//! New variants may be added in future minor versions, so consumers
//! must include a `_` arm when matching exhaustively — this is enforced
//! by the [`#[non_exhaustive]`][non_exhaustive] attribute on the enum.
//!
//! [non_exhaustive]: https://doc.rust-lang.org/reference/attributes/type_system.html#the-non_exhaustive-attribute

use crate::LANG;

/// Error returned by the library's metric-computation entry points.
///
/// # Stability
///
/// The variant set is additive: new variants may be introduced in
/// minor versions, so the enum is marked `#[non_exhaustive]`. Existing
/// variants will not be removed without a major version bump. The
/// [`std::error::Error`] and [`std::fmt::Display`] impls are part of
/// the stable surface; the exact wording of the `Display` output is
/// not.
///
/// # Examples
///
/// The [`MetricsError::EmptyRoot`] variant is reserved for a future
/// walker change (see its documentation). The
/// [`MetricsError::LanguageDisabled`] variant is the one actually
/// produced today: every dispatch entry point emits it when the
/// caller selects a
/// [`LANG`] whose per-language Cargo feature is not enabled in the
/// current build (see #252). The example demonstrates the
/// exhaustive-with-`_` match shape that callers should adopt to stay
/// forward-compatible with future variants.
///
/// [`AnyParser::parse`](crate::langs::AnyParser::parse) stands in for
/// `big_code_analysis::analyze` here — it is the same dispatch, one
/// layer down, and it is reachable from this crate alone. The match
/// arms are the ones an `analyze` caller writes.
///
/// ```
/// use big_code_analysis_ast::{AnyParser, MetricsError, LANG};
///
/// let result = AnyParser::parse(LANG::Cpp, b"int a = 42;".to_vec(), None, None);
///
/// match result {
///     Ok(_parser) => {
///         // The `cpp` feature is enabled in this build.
///     }
///     Err(MetricsError::EmptyRoot) => {
///         // Reserved: walker produced no top-level FuncSpace.
///     }
///     Err(MetricsError::LanguageDisabled(_lang)) => {
///         // The `LANG` variant the caller asked for has no grammar
///         // crate compiled in for this build (per-language feature
///         // disabled — see the `[features]` table in Cargo.toml).
///     }
///     // `MetricsError` is `#[non_exhaustive]`; new variants may be added.
///     Err(_) => {}
/// }
/// ```
#[non_exhaustive]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum MetricsError {
    /// The walker produced no top-level `big_code_analysis::FuncSpace`.
    ///
    /// Reserved — not produced today. `metrics_with_options` always
    /// pushes a synthetic top-level [`SpaceKind::Unit`][crate::SpaceKind]
    /// `FuncSpace` onto its state stack before walking the AST, so
    /// every parse — including empty input, whitespace-only input,
    /// and comment-only input — currently returns
    /// `Ok(FuncSpace { kind: Unit, .. })`. The variant is kept for a
    /// future walker change that lets the state stack legitimately
    /// drain to empty (e.g. an option that suppresses the synthetic
    /// root for sources with no parseable structure).
    ///
    EmptyRoot,
    /// The requested [`LANG`] is not enabled in this build.
    ///
    /// Produced by every dispatch entry point
    /// (`big_code_analysis::analyze`, `big_code_analysis::Ast::parse`,
    /// `big_code_analysis::Ast::from_tree_sitter`, and
    /// [`crate::LANG::tree_sitter_language`])
    /// when the caller selects a [`LANG`] variant whose per-language
    /// Cargo feature is not enabled in the current build — see the
    /// `[features]` table in the root `Cargo.toml` for the list.
    /// The default feature set (`default = ["all-languages"]`) keeps
    /// every grammar compiled in, matching the library's historical
    /// behaviour; callers that opt into a narrower set with
    /// `--no-default-features --features rust,…` are the only ones
    /// that observe this variant.
    LanguageDisabled(LANG),
}

impl std::fmt::Display for MetricsError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::EmptyRoot => {
                f.write_str("no top-level FuncSpace could be produced from the source AST")
            }
            Self::LanguageDisabled(lang) => {
                write!(f, "language {} is not enabled in this build", lang.name())
            }
        }
    }
}

impl std::error::Error for MetricsError {}