#MoonBit URI Library

#Overview

#Features

• Complete RFC 3986 Implementation: Full compliance with URI specification
• Parsing and Validation: Parse URI strings with comprehensive error reporting
• Builder Pattern: Fluent API for constructing URIs programmatically
• Authority Handling: Support for userinfo, hosts (IPv4, IPv6, domain names), and ports
• Path Management: Support for all path types (absolute, relative, empty, etc.)
• Query Parameter Support: Build and parse query strings with proper encoding
• Relative Reference Resolution: Resolve relative URIs against base URIs
• Percent Encoding: Proper encoding/decoding for URI components
• Type Safety: Strong typing with comprehensive error reporting

#Installation

moon add username/uri

{
  "import": ["username/uri"]
}

#Quick Start

#Basic URI Parsing

// Parse a complete URI
let uri_string = "https://example.com:8080/path?query=value#fragment"
match parse_uri(uri_string) {
  Ok(uri) => {
    println("Scheme: \{uri.scheme}")
    println("Host: \{uri.authority}")
    println("Path: \{uri.path}")
  }
  Err(error) => println("Parse error: \{error}")
}

#Creating URIs with Builder

// Build an HTTP URI fluently
let uri = new_builder()
  .scheme("https")
  .host("api.example.com")
  .port(443)
  .path("/v1/users")
  .add_query_param("limit", "10")
  .add_query_param("offset", "20")
  .fragment("results")
  .build()

match uri {
  Ok(u) => println("Built URI: \{uri_to_string(u)}")
  Err(e) => println("Build error: \{e}")
}

#API Reference

#Core Types

#URI Structure

pub struct URI {
  scheme : String        // Required scheme (http, https, ftp, etc.)
  authority : Authority? // Optional authority component
  path : String          // Path component
  path_type : PathType   // Classification of path type
  query : String?        // Optional query string
  fragment : String?     // Optional fragment identifier
}

#Authority Component

pub struct Authority {
  userinfo : String?  // Optional user information
  host : HostType     // Host (required in authority)
  port : Int?         // Optional port number
}

pub enum HostType {
  IPv4(String)      // IPv4 address (e.g., "192.168.1.1")
  IPv6(String)      // IPv6 address (e.g., "::1")
  IPvFuture(String) // Future IP version
  RegName(String)   // Regular domain name (e.g., "example.com")
}

#Parsing Functions

#parse_uri(uri_string : String) -> URIResult[URI]

let result = parse_uri("https://user@example.com:8080/path?q=val#frag")

#parse_uri_reference(uri_ref_string : String) -> URIResult[URI]

// Absolute URI
let abs_uri = parse_uri_reference("https://example.com/path")

// Relative reference
let rel_ref = parse_uri_reference("/path?query=value")

#Creation Functions

#create_uri() - Full URI Creation

pub fn create_uri(
  scheme : String,
  authority : Authority?,
  path : String,
  query : String?,
  fragment : String?
) -> URIResult[URI]

#Convenience Creators

// Simple URI with scheme and path
create_simple_uri("file", "/path/to/file.txt")

// HTTP URI
create_http_uri("example.com", Some(8080), "/api", Some("v=1"), None)

// HTTPS URI
create_https_uri("secure.example.com", None, "/", None, Some("top"))

// File URI
create_file_uri("/home/user/document.pdf")

#URI Builder

new_builder()
  .scheme("https")               // Set scheme
  .host("api.example.com")       // Set host (creates authority)
  .port(443)                     // Set port
  .userinfo("user:pass")         // Set userinfo
  .path("/v1/endpoint")          // Set path
  .add_path_segment("users")     // Add path segment
  .query("format=json")          // Set query string
  .add_query_param("page", "1")  // Add single parameter
  .fragment("section1")          // Set fragment
  .build()                       // Build final URI

#Utility Functions

#uri_to_string(uri : URI) -> String

let uri_string = uri_to_string(parsed_uri)

#resolve_reference(base : URI, reference : URI) -> URIResult[URI]

let base = parse_uri("https://example.com/base/path")
let reference = parse_uri_reference("../other/file")
let resolved = resolve_reference(base, reference)

#Error Handling

pub enum URIError {
  InvalidScheme(String)
  InvalidAuthority(String)
  InvalidHost(String)
  InvalidPort(String)
  InvalidPath(String)
  InvalidQuery(String)
  InvalidFragment(String)
  InvalidPercentEncoding(String)
  MalformedURI(String)
}

#Examples

#Simple Web URL

fn example_web_url() {
  let url = new_builder()
    .scheme("https")
    .host("www.example.com")
    .add_path_segment("products")
    .add_path_segment("123")
    .add_query_param("color", "blue")
    .add_query_param("size", "large")
    .build()

  match url {
    Ok(uri) => {
      // Output: https://www.example.com/products/123?color=blue&size=large
      println(uri_to_string(uri))
    }
    Err(e) => println("Error: \{e}")
  }
}

#File URI

fn example_file_uri() {
  let file_uri = create_file_uri("/home/user/documents/report.pdf")
  match file_uri {
    Ok(uri) => {
      // Output: file:///home/user/documents/report.pdf
      println(uri_to_string(uri))
    }
    Err(e) => println("Error: \{e}")
  }
}

#Complex URI with IPv6 Host

fn example_ipv6_uri() {
  let host_type = HostType::IPv6("2001:db8::1")
  let authority = { userinfo: None, host: host_type, port: Some(8080) }

  let uri = create_uri(
    "http",
    Some(authority),
    "/api/v1/data",
    Some("format=json"),
    Some("results")
  )

  match uri {
    Ok(u) => {
      // Output: http://[2001:db8::1]:8080/api/v1/data?format=json#results
      println(uri_to_string(u))
    }
    Err(e) => println("Error: \{e}")
  }
}

#Parsing and Validating User Input

fn validate_user_uri(input : String) -> Bool {
  match parse_uri_reference(input) {
    Ok(uri) => {
      // Additional validation can be performed here
      true
    }
    Err(_) => false
  }
}

fn example_validation() {
  let test_urls = [
    "https://example.com",
    "ftp://files.example.com/path",
    "/relative/path",
    "invalid::uri",
  ]

  for url in test_urls {
    if validate_user_uri(url) {
      println("\{url} is valid")
    } else {
      println("\{url} is invalid")
    }
  }
}

#Working with Query Parameters

fn example_query_handling() {
  let params = [
    ("search", "moon programming"),
    ("page", "1"),
    ("sort", "date"),
    ("order", "desc")
  ]

  let uri = new_builder()
    .scheme("https")
    .host("search.example.com")
    .path("/results")
    .query_params(params)
    .build()

  match uri {
    Ok(u) => {
      // Properly encoded query string
      println(uri_to_string(u))
    }
    Err(e) => println("Error: \{e}")
  }
}

#Testing

moon test

#Compliance

• URI syntax and components
• Percent-encoding mechanisms
• Reserved and unreserved characters
• Authority component parsing (userinfo, host, port)
• Path normalization and classification
• Query and fragment handling
• Relative reference resolution

#License

#Contributing