mon_core/
lib.rs

1#![doc = include_str!("../README.md")]
2
3//! # Crate Overview
4//!
5//! `mon-core` is the foundational engine for the Mycel Object Notation (MON) language. It provides a complete pipeline
6//! for parsing, analyzing, and serializing MON data, designed to be fast, robust, and developer-friendly. This crate
7//! is the backbone of the Mycel ecosystem, powering tools like linters, language servers, and formatters.
8//!
9//! ## Architectural Overview
10//!
11//! The library follows a standard compiler-front-end architecture, processing MON source code in several distinct stages:
12//!
13//! 1.  **Lexical Analysis (`lexer`):** The source text is first fed into the [`lexer`], which scans the text and
14//!     converts it into a stream of tokens (e.g., identifiers, keywords, symbols). This is the most basic
15//!     level of tokenization.
16//!
17//! 2.  **Parsing (`parser`):** The stream of tokens is then passed to the [`parser`], which enforces the MON
18//!     language's grammar rules. It constructs an Abstract Syntax Tree (AST), a hierarchical representation
19//!     of the code's structure, defined in the [`ast`] module.
20//!
21//! 3.  **Semantic Analysis (`resolver`):** The raw AST is processed by the [`resolver`]. This is a crucial step
22//!     where the meaning of the code is analyzed. The resolver handles imports, resolves aliases and spreads,
23//!     and validates data against type definitions (`#struct` and `#enum`).
24//!
25//! 4.  **Public API (`api`):** The [`api`] module provides the primary, high-level interface for the library.
26//!     The [`analyze`] function wraps the entire Lexer -> Parser -> Resolver pipeline into a single, easy-to-use
27//!     function, returning a fully resolved and validated result.
28//!
29//! ## Use Cases
30//!
31//! - **Configuration Loading:** Parse and validate `.mon` configuration files for an application.
32//! - **Language Tooling:** Build linters, formatters, or a Language Server Protocol (LSP) implementation for MON.
33//! - **Data Serialization:** Use the library to convert MON data into other formats like JSON or YAML.
34//!
35//! ## Example: A Complete Analysis
36//!
37//! This example shows how to use the high-level [`analyze`] function to process a MON string from start to finish.
38//!
39//! ```rust
40//! use mon_core::api::analyze;
41//!
42//! # fn main() -> Result<(), mon_core::error::MonError> {
43//! let source = r#"
44//! {
45//!     Config: #struct { port(Number) },
46//!     my_config :: Config = { port: 8080 }
47//! }
48//! "#;
49//!
50//! // The `analyze` function handles lexing, parsing, and resolving.
51//! let result = analyze(source, "config.mon")?;
52//!
53//! // You can serialize the validated data to JSON.
54//! let json_output = result.to_json().unwrap();
55//! println!("{}", json_output);
56//!
57//! // The output will be a well-formatted JSON string.
58//! assert!(json_output.contains("\"port\": 8080.0"));
59//! # Ok(())
60//! # }
61//! ```
62//!
63//! For more granular control over each stage of the process, you can use the components from the [`lexer`], [`parser`],
64//! and [`resolver`] modules directly.
65
66/// Provides the public API for interacting with the MON core library,
67/// including parsing, analysis, and serialization functions.
68pub mod api;
69pub mod ast;
70pub mod error;
71
72pub mod lexer;
73#[cfg(feature = "lsp")]
74pub mod lsp;
75#[cfg(feature = "lsp")]
76pub mod utils;
77
78pub mod parser;
79pub mod resolver;
80pub mod serialization;
81
82pub use api::{analyze, AnalysisResult};
mon_core/lib.rs

mon_core/
lib.rs
