Skip to main content

Crate surge_profile

Crate surge_profile 

Source
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:

  1. A faithful document model (Profile) produced directly by Profile::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);
  2. 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 an Other fallback, 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 #!REQUIREMENT expression 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).
ParseError
A hard parse error.
Platform
A platform referenced by a #!{IOS,MACOS,TVOS}-ONLY shorthand.
SectionName
The name of a section, with an Other fallback for names this version does not model. Section names are matched case-sensitively, as Surge treats them.