Struct CapabilityPath

Source

pub struct CapabilityPath { /* private fields */ }

Expand description

A validated capability path from an agent URI.

The capability path describes what an agent does, organized as a hierarchical path of segments separated by forward slashes.

§Constraints

At least one segment required
Maximum 32 segments
Maximum 256 total characters
Each segment: 1-64 chars, lowercase alphanumeric + hyphens

§Examples

use agent_uri::CapabilityPath;

let path = CapabilityPath::parse("assistant/chat").unwrap();
assert_eq!(path.segments().len(), 2);
assert_eq!(path.segments()[0].as_str(), "assistant");
assert_eq!(path.segments()[1].as_str(), "chat");

// Deep hierarchies
let path = CapabilityPath::parse("workflow/approval/invoice").unwrap();
assert_eq!(path.segments().len(), 3);

Implementations§

Source §

impl CapabilityPath

Source

pub fn from_segments( segments: Vec<PathSegment>, ) -> Result<Self, CapabilityPathError>

Builds a CapabilityPath from pre-validated PathSegment vectors.

This method allows constructing a CapabilityPath from segments that have already been validated individually, while still validating that the resulting path meets the overall path constraints.

§Arguments

segments - A vector of pre-validated PathSegment instances

§Returns

A validated CapabilityPath on success.

§Errors

Returns CapabilityPathError if:

The segments vector is empty
The path exceeds 256 total characters
The path has more than 32 segments

§Examples

use agent_uri::{CapabilityPath, PathSegment};

let segments = vec![
    PathSegment::parse("assistant").unwrap(),
    PathSegment::parse("chat").unwrap(),
];
let path = CapabilityPath::from_segments(segments).unwrap();
assert_eq!(path.as_str(), "assistant/chat");

Source

pub fn try_from_strs(segments: &[&str]) -> Result<Self, CapabilityPathError>

Builds a CapabilityPath by parsing each segment string individually.

This is a convenience method for constructing paths from string slices without first parsing them into PathSegment instances.

§Arguments

segments - A slice of string slices, each representing a path segment

§Returns

A validated CapabilityPath on success.

§Errors

Returns CapabilityPathError if:

The segments slice is empty
Any segment string is invalid
The path exceeds 256 total characters
The path has more than 32 segments

§Examples

use agent_uri::CapabilityPath;

let path = CapabilityPath::try_from_strs(&["assistant", "chat"]).unwrap();
assert_eq!(path.as_str(), "assistant/chat");

// Invalid segment fails
let result = CapabilityPath::try_from_strs(&["valid", "INVALID"]);
assert!(result.is_err());

Source

pub fn parse(input: &str) -> Result<Self, CapabilityPathError>

Parses a capability path from a string.

§Errors

Returns CapabilityPathError if:

The path is empty
The path exceeds 256 characters
The path has more than 32 segments
Any segment is invalid

Source

pub fn segments(&self) -> &[PathSegment]

Returns the path segments.

Source

pub fn depth(&self) -> usize

Returns the number of segments.

Source

pub fn starts_with(&self, prefix: &CapabilityPath) -> bool

Returns true if this path starts with the given prefix path.

Source

pub fn as_str(&self) -> &str

Returns the normalized string representation.

Source

pub fn parent(&self) -> Option<Self>

Returns the parent path, or None if this is a single-segment path.

§Examples

use agent_uri::CapabilityPath;

let path = CapabilityPath::parse("assistant/chat/streaming").unwrap();
let parent = path.parent().unwrap();
assert_eq!(parent.as_str(), "assistant/chat");

let root = CapabilityPath::parse("chat").unwrap();
assert!(root.parent().is_none());

Source

pub fn join(&self, segment: &PathSegment) -> Result<Self, CapabilityPathError>

Returns a new path with the given segment appended.

§Errors

Returns CapabilityPathError if the resulting path would be invalid.

§Examples

use agent_uri::{CapabilityPath, PathSegment};

let path = CapabilityPath::parse("assistant").unwrap();
let segment = PathSegment::parse("chat").unwrap();
let joined = path.join(&segment).unwrap();
assert_eq!(joined.as_str(), "assistant/chat");

Source

pub fn try_join(&self, s: &str) -> Result<Self, CapabilityPathError>

Returns a new path with a segment parsed from a string appended.

§Errors

Returns CapabilityPathError if the segment or resulting path would be invalid.

§Examples

use agent_uri::CapabilityPath;

let path = CapabilityPath::parse("assistant").unwrap();
let joined = path.try_join("chat").unwrap();
assert_eq!(joined.as_str(), "assistant/chat");

Source

pub fn last(&self) -> &PathSegment

Returns the last segment of the path.

§Examples

use agent_uri::CapabilityPath;

let path = CapabilityPath::parse("assistant/chat").unwrap();
assert_eq!(path.last().as_str(), "chat");

§Panics

This method will not panic because a CapabilityPath always has at least one segment (empty paths cannot be created).

Source

pub fn iter(&self) -> Iter<'_, PathSegment>

Returns an iterator over the path segments.

§Examples

use agent_uri::CapabilityPath;

let path = CapabilityPath::parse("assistant/chat/streaming").unwrap();
let names: Vec<&str> = path.iter().map(|s| s.as_str()).collect();
assert_eq!(names, vec!["assistant", "chat", "streaming"]);