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};