atom

Module uri

Source
Expand description

§Atom URI Format

This module provides comprehensive parsing and handling of Atom URIs, which are used to reference atoms from various sources including Git repositories, local paths, and external URLs.

§URI Format

Atom URIs follow this general format:

[scheme://][alias:][url-fragment::]atom-id[@version]

§Components

  • scheme - Optional protocol (e.g., https://, ssh://, file://)
  • alias - Optional user-configurable URL shortener (e.g., gh for GitHub)
  • url-fragment - Optional path within the repository
  • atom-id - Required atom identifier (Unicode string)
  • version - Optional version requirement (e.g., @1.0.0, @^1.0)

§Key Types

  • Uri - The main parsed URI structure
  • AliasedUrl - URL with optional alias resolution
  • UriError - Errors that can occur during URI parsing

§Alias System

Aliases provide a convenient way to shorten common URLs. They are configured in the Eka configuration file and can reference full URLs or other aliases.

§Alias Examples

  • gh:owner/repo::my-atom → https://github.com/owner/repo::my-atom
  • work:repo::my-atom → https://github.com/my-work-org/repo::my-atom
  • local::my-atom → file:///path/to/repo::my-atom

§URI Examples

use atom::uri::Uri;

// Simple atom reference
let uri: Uri = "my-atom".parse().unwrap();
assert_eq!(uri.tag().to_string(), "my-atom");

// Atom with version
let uri: Uri = "my-atom@^1.0.0".parse().unwrap();
assert_eq!(uri.tag().to_string(), "my-atom");

// GitHub reference with alias
let uri: Uri = "gh:user/repo::my-atom".parse().unwrap();
assert_eq!(uri.url().unwrap().host().unwrap(), "github.com");

// Direct URL reference
let uri: Uri = "https://github.com/user/repo::my-atom".parse().unwrap();
assert_eq!(uri.url().unwrap().host().unwrap(), "github.com");

// Local file reference
let uri: Uri = "file:///path/to/repo::my-atom".parse().unwrap();
assert_eq!(uri.url().unwrap().scheme, "file".into());

§Error Handling

The URI parser provides detailed error messages for common issues:

  • Invalid atom IDs (wrong characters, too long, etc.)
  • Unknown aliases
  • Malformed URLs
  • Invalid version specifications
  • Missing required components

Structs§

AliasedUrl
a url potentially containing an alias
Uri
Represents the parsed components of an Atom URI.

Enums§

UriError
A error encountered when constructing the concrete types from an Atom URI
UriOrUrl
Represents either an atom URI or an aliased URL component