hedl_cli/lib.rs
1// Dweve HEDL - Hierarchical Entity Data Language
2//
3// Copyright (c) 2025 Dweve IP B.V. and individual contributors.
4//
5// SPDX-License-Identifier: Apache-2.0
6//
7// Licensed under the Apache License, Version 2.0 (the "License");
8// you may not use this file except in compliance with the License.
9// You may obtain a copy of the License in the LICENSE file at the
10// root of this repository or at: http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18//! HEDL CLI library for command-line parsing and execution.
19//!
20//! This library provides the core functionality for the HEDL command-line interface,
21//! including all command implementations for validation, formatting, linting, and
22//! format conversion operations.
23//!
24//! # Commands
25//!
26//! The CLI provides the following commands:
27//!
28//! ## Validation & Inspection
29//!
30//! - **validate**: Validate HEDL file syntax and structure
31//! - **inspect**: Visualize HEDL internal structure with tree view
32//!
33//! ## Formatting & Canonicalization
34//!
35//! - **format**: Format HEDL files to canonical form
36//! - **lint**: Lint HEDL files for best practices and style
37//!
38//! ## Format Conversion
39//!
40//! Bidirectional conversion between HEDL and popular data formats:
41//!
42//! - **to-json/from-json**: JSON conversion (compact and pretty)
43//! - **to-yaml/from-yaml**: YAML conversion
44//! - **to-xml/from-xml**: XML conversion (compact and pretty)
45//! - **to-csv/from-csv**: CSV conversion (tabular data)
46//! - **to-parquet/from-parquet**: Apache Parquet conversion (columnar)
47//!
48//! ## Analysis & Statistics
49//!
50//! - **stats**: Compare size and token efficiency vs other formats
51//!
52//! ## Utilities
53//!
54//! - **completion**: Generate shell completion scripts (bash, zsh, fish, powershell, elvish)
55//!
56//! ## Batch Processing
57//!
58//! - **batch-validate**: Validate multiple files in parallel
59//! - **batch-format**: Format multiple files in parallel
60//! - **batch-lint**: Lint multiple files in parallel
61//!
62//! # Examples
63//!
64//! ## Validation
65//!
66//! ```no_run
67//! use hedl_cli::commands::validate;
68//!
69//! # fn main() -> Result<(), String> {
70//! // Validate a HEDL file
71//! validate("example.hedl", false)?;
72//!
73//! // Strict validation (all references must resolve)
74//! validate("example.hedl", true)?;
75//! # Ok(())
76//! # }
77//! ```
78//!
79//! ## Format Conversion
80//!
81//! ```no_run
82//! use hedl_cli::commands::{to_json, from_json};
83//!
84//! # fn main() -> Result<(), String> {
85//! // Convert HEDL to pretty JSON
86//! to_json("data.hedl", Some("output.json"), false, true)?;
87//!
88//! // Convert JSON back to HEDL
89//! from_json("data.json", Some("output.hedl"))?;
90//! # Ok(())
91//! # }
92//! ```
93//!
94//! ## Batch Processing
95//!
96//! ```no_run
97//! use hedl_cli::commands::batch_validate;
98//!
99//! # fn main() -> Result<(), String> {
100//! // Validate multiple files in parallel
101//! let files = vec!["file1.hedl".to_string(), "file2.hedl".to_string()];
102//! batch_validate(files, false, true, false)?;
103//! # Ok(())
104//! # }
105//! ```
106//!
107//! # Security
108//!
109//! The CLI includes several security features:
110//!
111//! - **File size limits**: Prevents OOM attacks (configurable via `HEDL_MAX_FILE_SIZE`)
112//! - **Input validation**: Type names and parameters are validated
113//! - **Safe conversions**: All format conversions use safe, well-tested libraries
114//!
115//! # Performance
116//!
117//! - **Parallel processing**: Batch commands automatically use parallel processing
118//! - **Optimized stats**: Format conversions run in parallel (3-5x speedup)
119//! - **Memory efficiency**: Streaming where possible, size checks before reading
120//!
121//! # Error Handling
122//!
123//! All commands return `Result<(), String>` for consistent error handling.
124//! Errors are descriptive and include context like file paths and line numbers
125//! where applicable.
126
127pub mod batch;
128pub mod cli;
129pub mod commands;
130pub mod error;