Skip to main content

surge_profile/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(missing_docs)]
3#![cfg_attr(docsrs, feature(doc_cfg))]
4
5//! `surge-profile` — a lossless parser and serializer for the
6//! [Surge](https://manual.nssurge.com/) proxy **profile** (configuration) format.
7//!
8//! The Surge profile format has no formal specification: it is `INI`-like, but
9//! every section has its own per-line grammar, and third-party configurations
10//! in the wild are wildly varied. This crate therefore follows
11//! [Postel's law](https://en.wikipedia.org/wiki/Robustness_principle) — *be
12//! liberal in what you accept* — and is built around **two layers**:
13//!
14//! 1. **A faithful document model** ([`Profile`]) produced directly by
15//!    [`Profile::parse`]. It preserves section/line ordering, blank lines,
16//!    comments and the original text, so that an unmodified document round-trips
17//!    byte-for-byte:
18//!
19//!    ```
20//!    use surge_profile::Profile;
21//!    let src = "[General]\ndns-server = 223.5.5.5 # ali\n\n[Rule]\nFINAL, DIRECT\n";
22//!    let profile = Profile::parse(src).unwrap();
23//!    assert_eq!(profile.to_string(), src);
24//!    ```
25//!
26//! 2. **Typed views** built on demand from the document layer
27//!    ([`Rule`], [`ProxyDecl`], [`ProxyGroup`], [`GeneralView`]). Every enum that
28//!    may grow as Surge evolves is `#[non_exhaustive]` and carries an `Other`
29//!    fallback, so unknown rule/proxy/section kinds are preserved rather than
30//!    dropped — and adding support for them later is never a breaking change.
31//!
32//!    ```
33//!    use surge_profile::{Profile, RuleKind};
34//!    let profile = Profile::parse("[Rule]\nDOMAIN-SUFFIX, google.com, PROXY, no-resolve\n").unwrap();
35//!    let rules = profile.rules();
36//!    assert_eq!(rules[0].kind, RuleKind::DomainSuffix);
37//!    assert_eq!(rules[0].value.as_deref(), Some("google.com"));
38//!    assert_eq!(rules[0].policy, "PROXY");
39//!    assert!(rules[0].options.iter().any(|o| o == "no-resolve"));
40//!    ```
41//!
42//! The library never performs I/O: `#!include` and `#!MANAGED-CONFIG` directives
43//! are parsed into [`Directive`] nodes and recorded, but fetching/merging them is
44//! left to the caller.
45//!
46//! See the module-level docs of [`requirement`] for the `#!REQUIREMENT`
47//! expression language (parsing + evaluation).
48
49#[macro_use]
50mod macros;
51
52mod document;
53mod error;
54mod lexer;
55mod parse;
56mod render;
57
58pub mod requirement;
59pub mod typed;
60
61pub use document::{Directive, Entry, Eol, Item, Platform, Profile, Section, SectionName};
62pub use error::{ParseError, Span, Warning};
63pub use requirement::{CompareOp, Env, Expr, Operand, Requirement, RequirementError, StringOp};
64pub use typed::{
65    FromEntryError, GeneralView, GroupKind, ProxyDecl, ProxyGroup, ProxyKind, Rule, RuleKind,
66};