nybl-lang 0.4.2

A small, embeddable, dynamically-typed programming language with zero dependencies
Documentation
//! Identifier classification: the shared rules every engine and the
//! parser consult to sort a name into naming buckets.
//!
//! # Rules
//!
//! Strip any leading underscores to get the "core":
//!
//! | core                                              | kind           |
//! |---------------------------------------------------|----------------|
//! | empty                                             | `Wildcard`     |
//! | starts uppercase, **all** uppercase/digit/`_`     | `Constant`     |
//! | starts uppercase, has any lowercase               | `Type`         |
//! | starts lowercase or digit                         | `Value`        |
//!
//! So `FOO` and `HTTP2` classify as `Constant`, `Foo` and `HttpClient`
//! classify as `Type`, and `foo` / `_bar` / `_1` classify as `Value`.
//!
//! **Two important rules at declaration sites:**
//!
//! - `struct` / `enum` / enum variant accept **either** `Type` or
//!   `Constant` — the bare "starts with a capital letter" rule.
//!   Single-letter variants like `enum Dir { N, E, S, W }` are fine.
//! - `const` accepts **only** `Constant` — the name must be all
//!   uppercase. `const Pi = 3.14` is rejected.
//!
//! Leading underscores mark "private by convention" — they don't
//! change the classification. `_foo` is a `Value`, `_Foo` is a
//! `Type`, `_FOO` is a `Constant`. Glob imports skip names that
//! start with an underscore; explicit selective or aliased imports
//! still expose them.

#[cfg(all(feature = "no_std", not(feature = "std")))]
use alloc::{format, string::String};

/// The shape bucket an identifier string belongs to.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum IdentKind {
    /// Binding name: `let` / `fn` / param / field / method / alias
    /// / module path segment / `for-in` var / pattern binding.
    Value,
    /// Type name that *isn't* pure-uppercase — `Foo`, `Http`,
    /// `HttpClient`, `MyStruct`, `_Internal`. Accepted at
    /// struct/enum/variant sites.
    Type,
    /// Pure-uppercase name — either a `const` declaration or a
    /// valid type name that happens to be all caps (`FOO`, `X`,
    /// `HTTP`, `Dir::N`). Accepted at struct/enum/variant sites
    /// *and* at `const` sites. Assigned-to in a source expression
    /// means "reassigning a constant" and is refused at parse
    /// time.
    Constant,
    /// Pure-underscore identifier (`_`, `__`) — match wildcard
    /// and "explicitly discard" let (`let _ = foo()`).
    Wildcard,
}

/// Classify `name` into its shape bucket. See the module docs.
pub fn classify(name: &str) -> IdentKind {
    let core = name.trim_start_matches('_');
    if core.is_empty() {
        return IdentKind::Wildcard;
    }
    let first = core.as_bytes()[0];
    if first.is_ascii_uppercase() {
        if core.bytes().any(|b| b.is_ascii_lowercase()) {
            IdentKind::Type
        } else {
            IdentKind::Constant
        }
    } else {
        // Lowercase letter or digit.
        IdentKind::Value
    }
}

/// `true` if the identifier has a leading underscore and isn't a
/// pure-underscore wildcard — the "private by convention" marker.
/// Glob imports skip these so a module's internals stay private
/// unless the caller asks explicitly.
pub fn is_private(name: &str) -> bool {
    name.starts_with('_') && !name.trim_start_matches('_').is_empty()
}

/// Does this name's shape suit a binding site (`let`, `fn`,
/// param, field, alias, `for-in`, match binding)? Wildcards
/// count — `let _ = foo()` is legal.
pub fn is_value_name(name: &str) -> bool {
    matches!(classify(name), IdentKind::Value | IdentKind::Wildcard)
}

/// Does this name's shape suit a type site (`struct`, `enum`,
/// enum variant)? Both `Type` and `Constant` shapes pass — the
/// rule is "starts with an uppercase letter."
pub fn is_type_name(name: &str) -> bool {
    matches!(classify(name), IdentKind::Type | IdentKind::Constant)
}

/// Does this name's shape suit a `const` site? Only pure-
/// uppercase names pass — `const Foo = 1` is rejected.
pub fn is_constant_name(name: &str) -> bool {
    matches!(classify(name), IdentKind::Constant)
}

/// Human-readable label for error messages.
pub fn kind_label(kind: IdentKind) -> &'static str {
    match kind {
        IdentKind::Value => "value",
        IdentKind::Type => "type",
        IdentKind::Constant => "constant",
        IdentKind::Wildcard => "wildcard",
    }
}

/// Build a "did you mean?" hint for a mis-shaped identifier at a
/// specific kind of site. The suggestion is best-effort — users
/// can always pick a different name — but most of the time the
/// obvious case transform produces something usable.
pub fn hint_for(expected_kind: &str, actual: &str) -> String {
    match expected_kind {
        "value" => {
            let is_all_upper = actual.chars().all(|c| !c.is_ascii_lowercase());
            if is_all_upper && actual.chars().any(|c| c.is_ascii_alphabetic()) {
                return format!(
                    "names bound by `let` / `fn` / params start with a lowercase letter. \
                     Did you mean to declare a constant? (`const {actual} = ...`)"
                );
            }
            format!(
                "names bound by `let` / `fn` / params start with a lowercase letter. \
                 Try `{}`?",
                lowercase_first(actual)
            )
        }
        "type" => {
            format!(
                "type names start with an uppercase letter. Try `{}`?",
                capitalize_first(actual)
            )
        }
        "constant" => {
            format!(
                "`const` names are SCREAMING_SNAKE_CASE (all uppercase). Try `{}`?",
                all_caps(actual)
            )
        }
        _ => String::new(),
    }
}

/// Hint for a mis-shaped identifier in a `match` pattern binding
/// position. Unlike `let` / `fn` / param sites, an all-uppercase
/// name here usually means the user wanted to match *against* an
/// existing constant's value — not to declare one — so suggest
/// the guard form that expresses that, instead of `hint_for`'s
/// "declare a constant" wording (the parser can't know whether
/// the constant already exists).
pub fn pattern_binding_hint(actual: &str) -> String {
    let is_all_upper = actual.chars().all(|c| !c.is_ascii_lowercase());
    if is_all_upper && actual.chars().any(|c| c.is_ascii_alphabetic()) {
        return format!(
            "uppercase names can't be pattern bindings. To match against the value of \
             `{actual}`, bind a lowercase name and compare it in a guard: \
             `n if n == {actual} => ...`"
        );
    }
    hint_for("value", actual)
}

fn capitalize_first(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    let mut first = true;
    for c in s.chars() {
        if first {
            out.extend(c.to_uppercase());
            first = false;
        } else {
            out.push(c);
        }
    }
    out
}

fn lowercase_first(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    let mut first = true;
    for c in s.chars() {
        if first {
            out.extend(c.to_lowercase());
            first = false;
        } else {
            out.push(c);
        }
    }
    out
}

fn all_caps(s: &str) -> String {
    s.chars().flat_map(|c| c.to_uppercase()).collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn value_shapes() {
        for name in [
            "foo",
            "my_var",
            "camelCase",
            "doTheThing",
            "_foo",
            "_bar",
            "__baz",
            "x1",
            "_1",
        ] {
            assert_eq!(classify(name), IdentKind::Value, "{name} should be Value");
        }
    }

    #[test]
    fn type_shapes_are_pascal_case() {
        for name in [
            "Entity",
            "Result",
            "Ok",
            "Err",
            "HttpClient",
            "_Internal",
            "Foo",
            "BarBaz",
        ] {
            assert_eq!(classify(name), IdentKind::Type, "{name} should be Type");
        }
    }

    #[test]
    fn constant_shapes_are_all_caps() {
        for name in [
            "PI",
            "MAX_SIZE",
            "HTTP_PORT",
            "HTTP",
            "_DEBUG",
            "__RESERVED",
            "X",
            "X2",
            "X_Y",
            "N",
        ] {
            assert_eq!(
                classify(name),
                IdentKind::Constant,
                "{name} should be Constant"
            );
        }
    }

    #[test]
    fn wildcards() {
        assert_eq!(classify("_"), IdentKind::Wildcard);
        assert_eq!(classify("__"), IdentKind::Wildcard);
    }

    #[test]
    fn type_sites_accept_both_type_and_constant_shapes() {
        // The parser's `is_type_name` accepts both so `enum Dir { N, E, S, W }`
        // and short-acronym types like `HTTP` are legal even though
        // classify() separates them.
        assert!(is_type_name("Foo"));
        assert!(is_type_name("FOO"));
        assert!(is_type_name("N"));
        assert!(!is_type_name("foo"));
        assert!(!is_type_name("_"));
    }

    #[test]
    fn constant_sites_require_all_caps() {
        assert!(is_constant_name("PI"));
        assert!(is_constant_name("MAX"));
        assert!(!is_constant_name("Pi"));
        assert!(!is_constant_name("pi"));
    }

    #[test]
    fn privacy_marker() {
        assert!(is_private("_foo"));
        assert!(is_private("_Foo"));
        assert!(is_private("_FOO"));
        assert!(!is_private("foo"));
        assert!(!is_private("Foo"));
        assert!(!is_private("FOO"));
        assert!(!is_private("_")); // wildcard, not private
    }
}