hocon/
lib.rs

1//! # hocon
2//!
3//! Full [Lightbend HOCON specification](https://github.com/lightbend/config/blob/main/HOCON.md)-compliant
4//! parser for Rust.
5//!
6//! ## Quick Example
7//!
8//! ```rust
9//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
10//! let config = hocon::parse(r#"
11//!     server {
12//!         host = "localhost"
13//!         port = 8080
14//!     }
15//! "#)?;
16//!
17//! assert_eq!(config.get_string("server.host")?, "localhost");
18//! assert_eq!(config.get_i64("server.port")?, 8080);
19//! # Ok(())
20//! # }
21//! ```
22//!
23//! ## Parsing
24//!
25//! - [`parse`] -- parse a HOCON string into a [`Config`].
26//! - [`parse_file`] -- parse a HOCON file. Include directives are resolved
27//!   relative to the file's directory.
28//! - [`parse_with_env`] / [`parse_file_with_env`] -- parse with a custom
29//!   environment variable map instead of inheriting the process environment.
30//!
31//! ## Accessing Values
32//!
33//! [`Config`] provides typed getters that accept dot-separated paths:
34//!
35//! | Method | Return type |
36//! |--------|-------------|
37//! | [`Config::get_string`] | `Result<String, ConfigError>` |
38//! | [`Config::get_i64`] | `Result<i64, ConfigError>` |
39//! | [`Config::get_f64`] | `Result<f64, ConfigError>` |
40//! | [`Config::get_bool`] | `Result<bool, ConfigError>` |
41//! | [`Config::get_config`] | `Result<Config, ConfigError>` |
42//! | [`Config::get_list`] | `Result<Vec<HoconValue>, ConfigError>` |
43//! | [`Config::get_duration`] | `Result<Duration, ConfigError>` |
44//! | [`Config::get_bytes`] | `Result<i64, ConfigError>` |
45//!
46//! Each typed getter has an `_option` variant (e.g., [`Config::get_string_option`])
47//! that returns `Option<T>` instead.
48//!
49//! ## Duration and Byte-Size Values
50//!
51//! ```rust
52//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
53//! let config = hocon::parse(r#"
54//!     timeout = 30 seconds
55//!     max-upload = 512 MB
56//! "#)?;
57//!
58//! let timeout = config.get_duration("timeout")?;
59//! let max_upload = config.get_bytes("max-upload")?;
60//! # Ok(())
61//! # }
62//! ```
63//!
64//! Duration units: `ns`, `us`, `ms`, `s`/`seconds`, `m`/`minutes`, `h`/`hours`, `d`/`days`.
65//!
66//! Byte-size units: `B`, `KB`, `KiB`, `MB`, `MiB`, `GB`, `GiB`, `TB`, `TiB`
67//! (and their long forms like `megabytes`, `mebibytes`).
68//!
69//! ## Serde Deserialization
70//!
71//! With the `serde` feature enabled, deserialize a [`Config`] (or sub-config)
72//! into any type implementing `serde::Deserialize`:
73//!
74//! ```rust,ignore
75//! use serde::Deserialize;
76//!
77//! #[derive(Deserialize)]
78//! struct Server {
79//!     host: String,
80//!     port: u16,
81//! }
82//!
83//! let server: Server = config.get_config("server")?.deserialize()?;
84//! ```
85//!
86//! ## Include Files
87//!
88//! HOCON supports `include` directives to compose configuration from multiple files:
89//!
90//! ```hocon
91//! include "defaults.conf"
92//!
93//! server.port = 9090  # override a value from defaults
94//! ```
95//!
96//! When parsing with [`parse_file`], include paths are resolved relative to the
97//! file being parsed.
98//!
99//! ## Error Types
100//!
101//! - [`HoconError`] -- unified error returned by parse functions. Wraps:
102//!   - [`ParseError`] -- syntax errors during lexing or parsing (includes line/column).
103//!   - [`ResolveError`] -- substitution resolution failures, cycle detection.
104//!   - `std::io::Error` -- file I/O errors (top-level file read; include file errors appear as [`ResolveError`]).
105//! - [`ConfigError`] -- missing keys or type mismatches when accessing values.
106//!
107//! ## HOCON Specification
108//!
109//! For the full specification, see the
110//! [Lightbend HOCON spec](https://github.com/lightbend/config/blob/main/HOCON.md).
111
112pub mod config;
113pub mod error;
114/// Internal lexer module. Not part of the stable public API.
115///
116/// This module is `pub` to allow integration tests to access internal types.
117/// All items are subject to change without notice across minor versions.
118/// Prefer the re-exported items (`tokenize`, `Token`, etc.) over direct module access.
119#[doc(hidden)]
120pub mod lexer;
121pub(crate) mod numeric_array;
122pub mod options;
123/// Internal parser module. Not part of the stable public API.
124///
125/// This module is `pub` to allow integration tests to access internal types.
126/// All items are subject to change without notice across minor versions.
127#[doc(hidden)]
128pub mod parser;
129pub(crate) mod properties;
130/// Internal resolver module. Not part of the stable public API.
131///
132/// This module is `pub` to allow integration tests to access internal types
133/// (`build_tree`, `resolve_tree`, `merge_unresolved`, `ResObj`, etc.).
134/// All items are subject to change without notice across minor versions.
135#[doc(hidden)]
136pub mod resolver;
137pub mod value;
138mod value_factory;
139
140#[cfg(feature = "serde")]
141pub mod serde;
142
143pub use config::{Config, Period};
144pub use error::{ConfigError, HoconError, NotResolvedError, ParseError, ResolveError};
145pub use options::{ParseOptions, ResolveOptions};
146pub use value::{HoconValue, ScalarType, ScalarValue};
147pub use value_factory::empty;
148
149#[cfg(feature = "serde")]
150pub use value_factory::from_map;
151
152// Lexer surface intentionally narrow — only the items integration tests
153// and diagnostic tooling need. The full lexer module is not part of the
154// public API.
155pub use lexer::{tokenize, Segment, SubstPayload, Token, TokenKind};
156
157#[cfg(feature = "serde")]
158pub use serde::{from_value, DeserializeError};
159
160use std::collections::HashMap;
161use std::path::Path;
162
163// ── include-package feature: public Parser builder ───────────────────────────
164
165/// Builder-style parser with a per-instance package registry for
166/// `include package(...)` support (E11).
167///
168/// # Feature flag
169///
170/// This type is only available when the `include-package` Cargo feature is
171/// enabled:
172///
173/// ```toml
174/// [dependencies]
175/// hocon-parser = { version = "...", features = ["include-package"] }
176/// ```
177///
178/// # Usage
179///
180/// ```rust,ignore
181/// # #[cfg(feature = "include-package")]
182/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
183/// let config = hocon::Parser::new()
184///     .register_package("github.com/org/pkg", "reference.conf", include_str!("conf/reference.conf"))
185///     .parse_file("app.conf")?;
186/// # Ok(())
187/// # }
188/// ```
189///
190/// # Cascade convention
191///
192/// For packages that depend on other HOCON-config-providing packages, follow
193/// this convention to cascade registrations:
194///
195/// ```rust,ignore
196/// // In your package (e.g., pkg_a/src/hocon.rs):
197/// pub fn register(parser: hocon::Parser) -> hocon::Parser {
198///     let parser = parser
199///         .register_package("github.com/org/pkg_a", "reference.conf", include_str!("../conf/reference.conf"));
200///     // Cascade to dependencies:
201///     // let parser = pkg_b::hocon::register(parser);
202///     parser
203/// }
204/// ```
205///
206/// Callers:
207/// ```rust,ignore
208/// let config = pkg_a::hocon::register(hocon::Parser::new())
209///     .parse_file("app.conf")?;
210/// ```
211///
212/// # Collision policy
213///
214/// Registering two **different** content strings for the same `(identifier, file)`
215/// key **panics** — this is a programming error (setup-time invariant). Re-registering
216/// **byte-identical** content is idempotent (no panic).
217#[cfg(feature = "include-package")]
218pub struct Parser {
219    registry: HashMap<(String, String), String>,
220}
221
222#[cfg(feature = "include-package")]
223impl Default for Parser {
224    fn default() -> Self {
225        Self::new()
226    }
227}
228
229#[cfg(feature = "include-package")]
230impl Parser {
231    /// Create a new `Parser` with an empty package registry.
232    pub fn new() -> Self {
233        Parser {
234            registry: HashMap::new(),
235        }
236    }
237
238    /// Register HOCON content for an `include package("identifier", "file")`
239    /// include statement.
240    ///
241    /// # Arguments
242    ///
243    /// * `identifier` — the package identifier (e.g., `"github.com/org/pkg"`).
244    ///   Should follow Go-module-path style for cross-impl portability (E11 decision 1),
245    ///   but any non-empty string is accepted by the parser.
246    /// * `file` — the file path within the package (e.g., `"reference.conf"`).
247    ///   Must satisfy E11 decision 6 constraints.
248    /// * `content` — the HOCON source text. Typically loaded via `include_str!`.
249    ///   Empty content is valid and contributes `{}` to the merge.
250    ///
251    /// # Panics
252    ///
253    /// Panics if different content is registered for the same `(identifier, file)` pair.
254    /// Re-registering byte-identical content is idempotent (no panic).
255    ///
256    /// # Example
257    ///
258    /// ```rust,ignore
259    /// let parser = hocon::Parser::new()
260    ///     .register_package("github.com/org/pkg", "reference.conf", include_str!("conf/reference.conf"))
261    ///     .register_package("github.com/org/pkg", "overrides.conf", include_str!("conf/overrides.conf"));
262    /// ```
263    pub fn register_package(
264        mut self,
265        identifier: impl Into<String>,
266        file: impl Into<String>,
267        content: impl Into<String>,
268    ) -> Self {
269        let id = identifier.into();
270        let f = file.into();
271        let c = content.into();
272        if let Some(existing) = self.registry.get(&(id.clone(), f.clone())) {
273            if existing != &c {
274                panic!(
275                    "hocon: conflicting content registered for package ({:?}, {:?}): \
276                     different content already registered for this (identifier, file) pair",
277                    id, f
278                );
279            }
280            // byte-identical: idempotent, no-op
281        } else {
282            self.registry.insert((id, f), c);
283        }
284        self
285    }
286
287    /// Parse a HOCON string using the registered package registry.
288    pub fn parse(self, input: &str) -> Result<Config, HoconError> {
289        self.parse_with_env(input, &std::env::vars().collect())
290    }
291
292    /// Parse a HOCON file using the registered package registry.
293    pub fn parse_file(self, path: impl AsRef<Path>) -> Result<Config, HoconError> {
294        self.parse_file_with_env(path, &std::env::vars().collect())
295    }
296
297    /// Parse a HOCON string with a custom environment map and the registered registry.
298    pub fn parse_with_env(
299        self,
300        input: &str,
301        env: &HashMap<String, String>,
302    ) -> Result<Config, HoconError> {
303        self.parse_with_options(input, ParseOptions::defaults().with_env(env.clone()))
304    }
305
306    /// Parse a HOCON file with a custom environment map and the registered registry.
307    pub fn parse_file_with_env(
308        self,
309        path: impl AsRef<Path>,
310        env: &HashMap<String, String>,
311    ) -> Result<Config, HoconError> {
312        self.parse_file_with_options(path, ParseOptions::defaults().with_env(env.clone()))
313    }
314
315    /// Parse a HOCON string with explicit [`ParseOptions`] and the registered registry.
316    ///
317    /// Equivalent to the module-level [`parse_string_with_options`] but threads the
318    /// per-`Parser` package registry through phase 1, enabling
319    /// `include package("identifier", "file")` to resolve against `register_package`-supplied
320    /// content. Supports both fused (`resolve_substitutions = true`, default) and deferred
321    /// (`resolve_substitutions = false`) lifecycles. The latter returns an unresolved
322    /// `Config` whose `Config::resolve` call performs phase 2 — includes are already
323    /// inlined at phase 1 so the registry is not needed after this call returns.
324    pub fn parse_with_options(self, input: &str, opts: ParseOptions) -> Result<Config, HoconError> {
325        let tokens = lexer::tokenize(input)?;
326        // S3.1 (corrected, xx.hocon E10): an empty / whitespace-only /
327        // comment-only / BOM-only document parses to the empty object per the
328        // HOCON.md L134-136 brace-omission relaxation — no emptiness guard.
329        let ast = parser::parse_tokens(&tokens)?;
330        reject_array_root(&ast, opts.origin_description.as_deref().unwrap_or("input"))?;
331
332        let env: HashMap<String, String> = opts.env.clone().unwrap_or_else(|| {
333            if opts.resolve_substitutions {
334                std::env::vars().collect()
335            } else {
336                HashMap::new()
337            }
338        });
339
340        let internal_opts = self.into_resolve_opts(env, opts.base_dir.clone());
341
342        if opts.resolve_substitutions {
343            let value = resolver::resolve(ast, &internal_opts)?;
344            match value {
345                HoconValue::Object(fields) => {
346                    let mut cfg = Config::new(fields);
347                    cfg.parse_base_dir = opts.base_dir;
348                    cfg.origin_description = opts.origin_description;
349                    Ok(cfg)
350                }
351                _ => Err(HoconError::Parse(ParseError {
352                    message: "root must be an object".into(),
353                    line: 1,
354                    col: 1,
355                })),
356            }
357        } else {
358            let tree = resolver::build_tree(ast, &internal_opts)?;
359            Ok(Config::new_from_res_obj(
360                tree,
361                opts.base_dir,
362                opts.origin_description,
363            ))
364        }
365    }
366
367    /// Parse a HOCON file with explicit [`ParseOptions`] and the registered registry.
368    /// File's parent directory is used as base_dir (overrides `opts.base_dir`).
369    pub fn parse_file_with_options(
370        self,
371        path: impl AsRef<Path>,
372        opts: ParseOptions,
373    ) -> Result<Config, HoconError> {
374        let path = path.as_ref();
375        let content = std::fs::read_to_string(path)
376            .map_err(|e| std::io::Error::new(e.kind(), format!("{}: {}", path.display(), e)))?;
377        let base_dir = path.parent().map(|p| p.to_path_buf());
378        // Default the origin to the file path so diagnostics (e.g. the S3.5
379        // array-at-file-root error) name the file, matching Lightbend origins.
380        let origin_description = opts
381            .origin_description
382            .or_else(|| Some(path.display().to_string()));
383        let opts = ParseOptions {
384            base_dir,
385            origin_description,
386            ..opts
387        };
388        self.parse_with_options(&content, opts)
389    }
390
391    /// Convert this `Parser` into `ResolveOptions`, threading the registry in.
392    fn into_resolve_opts(
393        self,
394        env: HashMap<String, String>,
395        base_dir: Option<std::path::PathBuf>,
396    ) -> resolver::InternalResolveOptions {
397        let mut opts = resolver::InternalResolveOptions::new(env);
398        if let Some(dir) = base_dir {
399            opts = opts.with_base_dir(dir);
400        }
401        opts.package_registry = std::sync::Arc::new(self.registry);
402        opts
403    }
404}
405
406/// Parse a HOCON string into a Config.
407pub fn parse(input: &str) -> Result<Config, HoconError> {
408    parse_with_env(input, &std::env::vars().collect())
409}
410
411/// Parse a HOCON string with explicit [`ParseOptions`].
412///
413/// `opts.resolve_substitutions = true` (default): fused parse + resolve, same
414/// as [`parse`]. `opts.resolve_substitutions = false`: phase 1 only; returned
415/// `Config` may have `is_resolved() = false`. Use [`Config::resolve`] later.
416///
417/// This module-level function does **not** thread a package registry — for that,
418/// use [`Parser::parse_with_options`] (feature `include-package`).
419pub fn parse_string_with_options(input: &str, opts: ParseOptions) -> Result<Config, HoconError> {
420    let tokens = lexer::tokenize(input)?;
421    let ast = parser::parse_tokens(&tokens)?;
422    reject_array_root(&ast, opts.origin_description.as_deref().unwrap_or("input"))?;
423
424    let env: HashMap<String, String> = opts.env.clone().unwrap_or_else(|| {
425        if opts.resolve_substitutions {
426            std::env::vars().collect()
427        } else {
428            HashMap::new()
429        }
430    });
431
432    let mut internal_opts = resolver::InternalResolveOptions::new(env);
433    if let Some(ref bd) = opts.base_dir {
434        internal_opts = internal_opts.with_base_dir(bd.clone());
435    }
436
437    if opts.resolve_substitutions {
438        // Fused path: phase 1 + phase 2.
439        let value = resolver::resolve(ast, &internal_opts)?;
440        match value {
441            HoconValue::Object(fields) => {
442                let mut cfg = Config::new(fields);
443                cfg.parse_base_dir = opts.base_dir;
444                cfg.origin_description = opts.origin_description;
445                Ok(cfg)
446            }
447            _ => Err(HoconError::Parse(ParseError {
448                message: "root must be an object".into(),
449                line: 1,
450                col: 1,
451            })),
452        }
453    } else {
454        // Deferred path: phase 1 only.
455        let tree = resolver::build_tree(ast, &internal_opts)?;
456        Ok(Config::new_from_res_obj(
457            tree,
458            opts.base_dir,
459            opts.origin_description,
460        ))
461    }
462}
463
464/// Parse a HOCON file with explicit [`ParseOptions`].
465/// File's parent directory is used as base_dir (overrides opts.base_dir).
466pub fn parse_file_with_options<P: AsRef<Path>>(
467    path: P,
468    opts: ParseOptions,
469) -> Result<Config, HoconError> {
470    let path = path.as_ref();
471    let content = std::fs::read_to_string(path)
472        .map_err(|e| std::io::Error::new(e.kind(), format!("{}: {}", path.display(), e)))?;
473    let base_dir = path.parent().map(|p| p.to_path_buf());
474    // Default the origin to the file path so diagnostics (e.g. the S3.5
475    // array-at-file-root error) name the file, matching Lightbend origins.
476    let origin_description = opts
477        .origin_description
478        .or_else(|| Some(path.display().to_string()));
479    let opts = ParseOptions {
480        base_dir,
481        origin_description,
482        ..opts
483    };
484    parse_string_with_options(&content, opts)
485}
486
487/// Parse a HOCON file into a Config.
488pub fn parse_file<P: AsRef<Path>>(path: P) -> Result<Config, HoconError> {
489    parse_file_with_env(path, &std::env::vars().collect())
490}
491
492/// Parse a HOCON file with a custom environment variable map.
493pub fn parse_file_with_env<P: AsRef<Path>>(
494    path: P,
495    env: &HashMap<String, String>,
496) -> Result<Config, HoconError> {
497    let path = path.as_ref();
498    let content = std::fs::read_to_string(path)
499        .map_err(|e| std::io::Error::new(e.kind(), format!("{}: {}", path.display(), e)))?;
500    let tokens = lexer::tokenize(&content)?;
501    let ast = parser::parse_tokens(&tokens)?;
502    reject_array_root(&ast, &path.display().to_string())?;
503    let mut opts = resolver::InternalResolveOptions::new(env.clone());
504    if let Some(dir) = path.parent() {
505        opts = opts.with_base_dir(dir.to_path_buf());
506    }
507    let value = resolver::resolve(ast, &opts)?;
508    match value {
509        HoconValue::Object(fields) => Ok(Config::new(fields)),
510        _ => Err(HoconError::Parse(ParseError {
511            message: "root must be an object".into(),
512            line: 1,
513            col: 1,
514        })),
515    }
516}
517
518/// S3.5 (HOCON.md L989-991): an array-root document is valid syntax, but the
519/// object-rooted Config API rejects it at the Config boundary with a TYPE
520/// error, matching Lightbend's `Parseable.forceParsedToObject`
521/// (`ConfigException.WrongType` "has type LIST rather than object at file
522/// root"). The message carries the origin and the opening bracket's position.
523fn reject_array_root(ast: &parser::AstNode, origin: &str) -> Result<(), HoconError> {
524    if let parser::AstNode::Array { pos, .. } = ast {
525        return Err(HoconError::Config(ConfigError {
526            message: format!(
527                "{}: {}:{}: document has type array rather than object at file root (HOCON.md L989-991); the Config API requires an object at file root",
528                origin, pos.line, pos.col
529            ),
530            path: String::new(),
531        }));
532    }
533    Ok(())
534}
535
536/// Parse a HOCON string with a custom environment variable map.
537pub fn parse_with_env(input: &str, env: &HashMap<String, String>) -> Result<Config, HoconError> {
538    let tokens = lexer::tokenize(input)?;
539    let ast = parser::parse_tokens(&tokens)?;
540    reject_array_root(&ast, "input")?;
541    let opts = resolver::InternalResolveOptions::new(env.clone());
542    let value = resolver::resolve(ast, &opts)?;
543    match value {
544        HoconValue::Object(fields) => Ok(Config::new(fields)),
545        _ => Err(HoconError::Parse(ParseError {
546            message: "root must be an object".into(),
547            line: 1,
548            col: 1,
549        })),
550    }
551}
552
553/// Internal JSON renderer for use by Layer-2 fixture tests.
554///
555/// Emits compact sorted-key JSON. Not semver-stable.
556/// Callers: `tests/deferred_resolution_fixtures.rs`.
557#[doc(hidden)]
558pub fn _render_json_for_test(config: &Config) -> String {
559    use crate::value::HoconValue;
560    use std::fmt::Write;
561
562    fn render_value(val: &HoconValue, out: &mut String) {
563        match val {
564            HoconValue::Scalar(sv) => {
565                use crate::value::ScalarType;
566                match sv.value_type {
567                    ScalarType::Null => out.push_str("null"),
568                    ScalarType::Boolean => out.push_str(&sv.raw),
569                    ScalarType::Number => out.push_str(&sv.raw),
570                    ScalarType::String => {
571                        let escaped = sv
572                            .raw
573                            .replace('\\', "\\\\")
574                            .replace('"', "\\\"")
575                            .replace('\n', "\\n")
576                            .replace('\r', "\\r")
577                            .replace('\t', "\\t");
578                        let _ = write!(out, "\"{}\"", escaped);
579                    }
580                }
581            }
582            HoconValue::Object(map) => {
583                out.push('{');
584                let mut keys: Vec<&str> = map.keys().map(|s| s.as_str()).collect();
585                keys.sort_unstable();
586                for (i, k) in keys.iter().enumerate() {
587                    if i > 0 {
588                        out.push(',');
589                    }
590                    let _ = write!(out, "\"{}\":", k);
591                    render_value(map.get(*k).unwrap(), out);
592                }
593                out.push('}');
594            }
595            HoconValue::Array(arr) => {
596                out.push('[');
597                for (i, v) in arr.iter().enumerate() {
598                    if i > 0 {
599                        out.push(',');
600                    }
601                    render_value(v, out);
602                }
603                out.push(']');
604            }
605            HoconValue::Placeholder(pv) => {
606                let _ = write!(out, "\"<unresolved:{}>\"", pv.path);
607            }
608        }
609    }
610
611    let mut out = String::from("{");
612    let mut keys: Vec<&str> = config.root.keys().map(|s| s.as_str()).collect();
613    keys.sort_unstable();
614    for (i, k) in keys.iter().enumerate() {
615        if i > 0 {
616            out.push(',');
617        }
618        let _ = write!(out, "\"{}\":", k);
619        render_value(config.root.get(*k).unwrap(), &mut out);
620    }
621    out.push('}');
622    out
623}
hocon/lib.rs

hocon/
lib.rs
