diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2d8d6ad..7957940 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -42,6 +42,9 @@ jobs: - name: Test run: cargo nextest run --workspace --lib --all-targets --all-features + - name: Test Docstrings + run: cargo test --doc --workspace --all-features + format: name: Code Format runs-on: ubuntu-latest diff --git a/src/curie.rs b/src/curie.rs index 85f3df8..7589157 100644 --- a/src/curie.rs +++ b/src/curie.rs @@ -1,5 +1,25 @@ use std::fmt::{Display, Formatter}; +/// A parsed CURIE (Compact URI) representation. +/// +/// A CURIE consists of a prefix and a reference separated by a colon (`:`), +/// providing a compact way to represent URIs. For example, `HP:0000054` where +/// `HP` is the prefix and `0000054` is the reference. +/// +/// This struct stores the CURIE as a single string internally for efficiency, +/// tracking the prefix length to enable zero-copy access to both components. +/// +/// # Examples +/// +/// ``` +/// # use securiety::{Curie, CurieParser, CurieParsing}; +/// let parser = CurieParser::general(); +/// let curie = parser.parse("prefix:reference").unwrap(); +/// +/// assert_eq!(curie.prefix(), "prefix"); +/// assert_eq!(curie.reference(), "reference"); +/// assert_eq!(curie.to_string(), "prefix:reference"); +/// ``` #[derive(Debug, Clone, PartialEq, Hash, Eq, PartialOrd, Ord)] pub struct Curie { inner: String, @@ -7,6 +27,10 @@ pub struct Curie { } impl Curie { + /// Creates a new `Curie` from a prefix and reference. + /// + /// This is an internal constructor used by the parser. Users should typically + /// obtain `Curie` instances through a [`CurieParser`]. pub(crate) fn new(prefix: &str, reference: &str) -> Curie { let inner = format!("{prefix}:{reference}"); let prefix_len = prefix.len(); diff --git a/src/curie_parser.rs b/src/curie_parser.rs index cef9837..512e874 100644 --- a/src/curie_parser.rs +++ b/src/curie_parser.rs @@ -2,12 +2,64 @@ use crate::curie::Curie; use crate::error::CurieParsingError; use crate::traits::{CurieParsing, CurieValidation}; +/// A parser for CURIE (Compact URI) strings that validates input using a configurable validator. +/// +/// CURIEs are compact representations of URIs in the form `prefix:reference`, commonly used +/// in semantic web applications and knowledge graphs. +/// +/// # Type Parameters +/// +/// * `Validator` - A type implementing [`CurieValidation`] used to validate CURIE strings +/// before parsing. +/// +/// # Examples +/// +/// ``` +/// use securiety::{CurieParser, CurieParsing}; +/// +/// let parser = CurieParser::general(); +/// let curie = parser.parse("prefix:reference").unwrap(); +/// assert_eq!(curie.prefix(), "prefix"); +/// assert_eq!(curie.reference(), "reference"); +/// ``` #[derive(Debug, Clone)] pub struct CurieParser { pub(crate) validator: Validator, } impl CurieParsing for CurieParser { + /// Parses a CURIE string into a [`Curie`] instance. + /// + /// The parsing process: + /// 1. Validates the input string using the configured validator + /// 2. Splits the string on the colon (`:`) separator + /// 3. Returns a [`Curie`] with the prefix and reference components + /// + /// # Arguments + /// + /// * `curie` - A string slice containing the CURIE to parse (e.g., "prefix:reference") + /// + /// # Returns + /// + /// * `Ok(Curie)` - Successfully parsed CURIE + /// * `Err(CurieParsingError::InvalidCurie)` - The input failed validation + /// * `Err(CurieParsingError::UnparsableCurie)` - The input passed validation but + /// couldn't be split into prefix and reference (no colon found) + /// + /// # Examples + /// + /// ``` + /// use securiety::{CurieParser, CurieParsing}; + /// let parser = CurieParser::hp(); + /// + /// // Valid CURIE + /// let result = parser.parse("HP:0000054"); + /// assert!(result.is_ok()); + /// + /// // Invalid CURIE (no colon) + /// let result = parser.parse("invalid"); + /// assert!(result.is_err()); + /// ``` fn parse(&self, curie: &str) -> Result { match self.validator.validate(curie) { true => { diff --git a/src/validators/regex_validator.rs b/src/validators/regex_validator.rs index 7ae799b..72a73e1 100644 --- a/src/validators/regex_validator.rs +++ b/src/validators/regex_validator.rs @@ -1,6 +1,29 @@ use crate::error::InvalidRegexError; use crate::traits::CurieValidation; use regex::Regex; + +/// A CURIE validator that uses regular expressions to validate CURIE strings. +/// +/// This validator allows flexible validation rules by accepting any regular expression +/// pattern. It's useful when you need custom validation logic beyond simple format checks. +/// +/// # Examples +/// +/// ``` +/// use securiety::{CurieRegexValidator, CurieValidation}; +/// use regex::Regex; +/// // Create a validator that requires lowercase prefixes +/// let validator = CurieRegexValidator::general(); +/// +/// assert!(validator.validate("rdf:type")); +/// ``` +/// +/// ``` +/// use securiety::{CurieRegexValidator, CurieValidation}; +/// // Create validator for specific resource +/// let validator = CurieRegexValidator::hp(); +/// assert!(validator.validate("HP:0000054")); +/// ``` #[derive(Debug, Clone)] pub struct CurieRegexValidator { regex: Regex,