Expand description
surge-profile — a lossless parser and serializer for the
Surge proxy profile (configuration) format.
The Surge profile format has no formal specification: it is INI-like, but
every section has its own per-line grammar, and third-party configurations
in the wild are wildly varied. This crate therefore follows
Postel’s law — be
liberal in what you accept — and is built around two layers:
-
A faithful document model (
Profile) produced directly byProfile::parse. It preserves section/line ordering, blank lines, comments and the original text, so that an unmodified document round-trips byte-for-byte:use surge_profile::Profile; let src = "[General]\ndns-server = 223.5.5.5 # ali\n\n[Rule]\nFINAL, DIRECT\n"; let profile = Profile::parse(src).unwrap(); assert_eq!(profile.to_string(), src); -
Typed views built on demand from the document layer (
Rule,ProxyDecl,ProxyGroup,GeneralView). Every enum that may grow as Surge evolves is#[non_exhaustive]and carries anOtherfallback, so unknown rule/proxy/section kinds are preserved rather than dropped — and adding support for them later is never a breaking change.use surge_profile::{Profile, RuleKind}; let profile = Profile::parse("[Rule]\nDOMAIN-SUFFIX, google.com, PROXY, no-resolve\n").unwrap(); let rules = profile.rules(); assert_eq!(rules[0].kind, RuleKind::DomainSuffix); assert_eq!(rules[0].value.as_deref(), Some("google.com")); assert_eq!(rules[0].policy, "PROXY"); assert!(rules[0].options.iter().any(|o| o == "no-resolve"));
The library never performs I/O: #!include and #!MANAGED-CONFIG directives
are parsed into Directive nodes and recorded, but fetching/merging them is
left to the caller.
See the module-level docs of requirement for the #!REQUIREMENT
expression language (parsing + evaluation).
Re-exports§
pub use requirement::CompareOp;pub use requirement::Env;pub use requirement::Expr;pub use requirement::Operand;pub use requirement::Requirement;pub use requirement::RequirementError;pub use requirement::StringOp;pub use typed::FromEntryError;pub use typed::GeneralView;pub use typed::GroupKind;pub use typed::ProxyDecl;pub use typed::ProxyGroup;pub use typed::ProxyKind;pub use typed::Rule;pub use typed::RuleKind;
Modules§
- requirement
- The
#!REQUIREMENTexpression language: parsing and evaluation. - typed
- Typed views (layer 2), built on demand from the document model.
Structs§
- Entry
- A configuration line whose comment has been split off but whose original text can be reproduced.
- Profile
- A parsed Surge profile, preserving section and line ordering.
- Section
- One
[Section]and the lines belonging to it. - Span
- A location in the source text.
- Warning
- A non-fatal problem encountered during lenient parsing or typed-view construction.
Enums§
- Directive
- A
#!directive. Looks like a comment, but carries semantics. - Eol
- Line terminator recorded for each physical line, so that the exact bytes (LF vs CRLF, and the presence/absence of a trailing newline) can be reproduced.
- Item
- A single line within a section (or in the preamble).
- Parse
Error - A hard parse error.
- Platform
- A platform referenced by a
#!{IOS,MACOS,TVOS}-ONLYshorthand. - Section
Name - The name of a section, with an
Otherfallback for names this version does not model. Section names are matched case-sensitively, as Surge treats them.