use std::fmt;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum SegmentKind {
Root,
Static(String),
Dynamic(String),
CatchAll(String),
OptionalCatchAll(String),
Group(String),
Slot(String),
Intercept { level: InterceptLevel, inner: Box<SegmentKind> },
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum InterceptLevel {
Same,
Up(usize),
Root,
}
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(tag = "type", content = "value", rename_all = "snake_case")]
pub enum PatternSegment {
Static(String),
Dynamic(String),
CatchAll(String),
OptionalCatchAll(String),
}
impl PatternSegment {
pub fn param_name(&self) -> Option<&str> {
match self {
PatternSegment::Static(_) => None,
PatternSegment::Dynamic(n) | PatternSegment::CatchAll(n) | PatternSegment::OptionalCatchAll(n) => Some(n),
}
}
pub fn is_catch_all(&self) -> bool {
matches!(self, PatternSegment::CatchAll(_) | PatternSegment::OptionalCatchAll(_))
}
pub fn shape(&self) -> String {
match self {
PatternSegment::Static(s) => s.clone(),
PatternSegment::Dynamic(_) => "[]".into(),
PatternSegment::CatchAll(_) => "[...]".into(),
PatternSegment::OptionalCatchAll(_) => "[[...]]".into(),
}
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(transparent)]
pub struct RoutePattern(pub Vec<PatternSegment>);
impl RoutePattern {
pub fn segments(&self) -> &[PatternSegment] {
&self.0
}
pub fn to_fs_string(&self) -> String {
if self.0.is_empty() {
return "/".into();
}
let mut s = String::new();
for seg in &self.0 {
s.push('/');
match seg {
PatternSegment::Static(v) => s.push_str(v),
PatternSegment::Dynamic(n) => s.push_str(&format!("[{n}]")),
PatternSegment::CatchAll(n) => s.push_str(&format!("[...{n}]")),
PatternSegment::OptionalCatchAll(n) => s.push_str(&format!("[[...{n}]]")),
}
}
s
}
pub fn to_display_string(&self) -> String {
if self.0.is_empty() {
return "/".into();
}
let mut s = String::new();
for seg in &self.0 {
s.push('/');
match seg {
PatternSegment::Static(v) => s.push_str(v),
PatternSegment::Dynamic(n) => s.push_str(&format!(":{n}")),
PatternSegment::CatchAll(n) => s.push_str(&format!("*{n}")),
PatternSegment::OptionalCatchAll(n) => s.push_str(&format!("*{n}?")),
}
}
s
}
pub fn shape(&self) -> String {
let parts: Vec<String> = self.0.iter().map(PatternSegment::shape).collect();
format!("/{}", parts.join("/"))
}
pub fn is_dynamic(&self) -> bool {
self.0.iter().any(|s| !matches!(s, PatternSegment::Static(_)))
}
pub fn param_names(&self) -> impl Iterator<Item = &str> {
self.0.iter().filter_map(PatternSegment::param_name)
}
pub fn to_path(&self, params: &crate::Params) -> Option<String> {
let mut out = String::new();
for seg in &self.0 {
match seg {
PatternSegment::Static(v) => {
out.push('/');
out.push_str(&crate::encode_segment(v));
}
PatternSegment::Dynamic(n) => {
out.push('/');
out.push_str(&crate::encode_segment(params.get(n)?));
}
PatternSegment::CatchAll(n) => {
let all = params.get_all(n)?;
if all.is_empty() {
return None;
}
for v in all {
out.push('/');
out.push_str(&crate::encode_segment(v));
}
}
PatternSegment::OptionalCatchAll(n) => {
for v in params.get_all(n).unwrap_or(&[]) {
out.push('/');
out.push_str(&crate::encode_segment(v));
}
}
}
}
Some(if out.is_empty() { "/".into() } else { out })
}
}
impl fmt::Display for RoutePattern {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.to_fs_string())
}
}
fn is_ident(s: &str) -> bool {
let mut chars = s.chars();
matches!(chars.next(), Some(c) if c.is_ascii_alphabetic() || c == '_')
&& chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
}
pub fn parse_segment(name: &str) -> Result<Option<SegmentKind>, String> {
if name.is_empty() {
return Err("empty directory name".into());
}
if name.starts_with('_') || name.starts_with('.') {
return Ok(None);
}
if name.starts_with("(.)") || name.starts_with("(..)") || name.starts_with("(...)") {
let (level, rest) = if let Some(rest) = name.strip_prefix("(...)") {
(InterceptLevel::Root, rest)
} else if let Some(rest) = name.strip_prefix("(.)") {
(InterceptLevel::Same, rest)
} else {
let mut rest = name;
let mut n = 0;
while let Some(r) = rest.strip_prefix("(..)") {
rest = r;
n += 1;
}
(InterceptLevel::Up(n), rest)
};
if rest.is_empty() {
return Err(format!("intercepting route `{name}` needs a segment after the marker, e.g. `(.)photo`"));
}
let inner = match parse_segment(rest)? {
Some(
k @ (SegmentKind::Static(_)
| SegmentKind::Dynamic(_)
| SegmentKind::CatchAll(_)
| SegmentKind::OptionalCatchAll(_)),
) => k,
_ => return Err(format!("intercepting route `{name}` must intercept a static or dynamic segment")),
};
return Ok(Some(SegmentKind::Intercept { level, inner: Box::new(inner) }));
}
if let Some(inner) = name.strip_prefix('(').and_then(|n| n.strip_suffix(')')) {
if inner.is_empty() || inner.contains(['(', ')']) {
return Err(format!("invalid route group name `{name}`; use `(name)`"));
}
return Ok(Some(SegmentKind::Group(inner.to_owned())));
}
if let Some(inner) = name.strip_prefix('@') {
if !is_ident(inner) {
return Err(format!("invalid slot name `{name}`; slot names must be identifiers like `@analytics`"));
}
return Ok(Some(SegmentKind::Slot(inner.to_owned())));
}
if let Some(inner) = name.strip_prefix("[[").and_then(|n| n.strip_suffix("]]")) {
let Some(param) = inner.strip_prefix("...") else {
return Err(format!(
"`{name}`: double brackets are only valid for optional catch-all segments like `[[...slug]]`"
));
};
check_param(name, param)?;
return Ok(Some(SegmentKind::OptionalCatchAll(param.to_owned())));
}
if let Some(inner) = name.strip_prefix('[').and_then(|n| n.strip_suffix(']')) {
if let Some(param) = inner.strip_prefix("...") {
check_param(name, param)?;
return Ok(Some(SegmentKind::CatchAll(param.to_owned())));
}
check_param(name, inner)?;
return Ok(Some(SegmentKind::Dynamic(inner.to_owned())));
}
if name.contains(['[', ']']) {
return Err(format!(
"`{name}` mixes static text with brackets; a dynamic segment must be the whole directory name, e.g. `[id]`"
));
}
if name.starts_with('(') && name.ends_with(')') {
return Err(format!("invalid route group name `{name}`"));
}
if name.contains('/') || name.contains('\\') {
return Err(format!("`{name}` contains a path separator"));
}
Ok(Some(SegmentKind::Static(name.to_owned())))
}
fn check_param(name: &str, param: &str) -> Result<(), String> {
if param.is_empty() {
return Err(format!("`{name}` has an empty parameter name"));
}
if !is_ident(param) {
return Err(format!(
"`{name}`: parameter `{param}` must be a valid identifier (letters, digits and `_`, not starting with a digit)"
));
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_all_kinds() {
assert_eq!(parse_segment("about").unwrap(), Some(SegmentKind::Static("about".into())));
assert_eq!(parse_segment("hello world").unwrap(), Some(SegmentKind::Static("hello world".into())));
assert_eq!(parse_segment("héllo-日本").unwrap(), Some(SegmentKind::Static("héllo-日本".into())));
assert_eq!(parse_segment("[id]").unwrap(), Some(SegmentKind::Dynamic("id".into())));
assert_eq!(parse_segment("[...slug]").unwrap(), Some(SegmentKind::CatchAll("slug".into())));
assert_eq!(parse_segment("[[...slug]]").unwrap(), Some(SegmentKind::OptionalCatchAll("slug".into())));
assert_eq!(parse_segment("(marketing)").unwrap(), Some(SegmentKind::Group("marketing".into())));
assert_eq!(parse_segment("@team").unwrap(), Some(SegmentKind::Slot("team".into())));
assert_eq!(parse_segment("_components").unwrap(), None);
assert_eq!(parse_segment(".git").unwrap(), None);
assert_eq!(
parse_segment("(..)(..)photo").unwrap(),
Some(SegmentKind::Intercept {
level: InterceptLevel::Up(2),
inner: Box::new(SegmentKind::Static("photo".into()))
})
);
assert_eq!(
parse_segment("(.)[id]").unwrap(),
Some(SegmentKind::Intercept {
level: InterceptLevel::Same,
inner: Box::new(SegmentKind::Dynamic("id".into()))
})
);
assert!(matches!(
parse_segment("(...)x").unwrap(),
Some(SegmentKind::Intercept { level: InterceptLevel::Root, .. })
));
}
#[test]
fn rejects_invalid() {
for bad in
["[]", "[...]", "[[slug]]", "[a-b]", "[1a]", "user[id]", "()", "@", "@a-b", "(.)", "(.)(group)", "[[...a]"]
{
assert!(parse_segment(bad).is_err(), "{bad} should be rejected");
}
}
#[test]
fn pattern_strings() {
let p = RoutePattern(vec![
PatternSegment::Static("docs".into()),
PatternSegment::Dynamic("v".into()),
PatternSegment::OptionalCatchAll("rest".into()),
]);
assert_eq!(p.to_fs_string(), "/docs/[v]/[[...rest]]");
assert_eq!(p.to_display_string(), "/docs/:v/*rest?");
assert_eq!(p.shape(), "/docs/[]/[[...]]");
let params = crate::Params::new().with("v", "1 2").with("rest", ["a", "b"]);
assert_eq!(p.to_path(¶ms).unwrap(), "/docs/1%202/a/b");
assert_eq!(RoutePattern::default().to_fs_string(), "/");
}
}