Description
Parses RFC 3986 URI references, RFC 3987 IRI references, and the common WHATWG web URLs. Parse stores one compact serialized reference plus component offsets. Common absolute HTTP(S) validation avoids allocation; normalization and IDNA handling may allocate.
Authority
function Authority (Value : Reference) return String
Return the complete authority without //, or an empty string.
Parameters
- Value
Parsed reference
Return value
Authority component
Can_Parse
function Can_Parse
(Input : String;
Syntax : Syntax_Kind := IRI_Syntax;
Max_Length : Positive := Default_Max_Length) return Boolean
Validate without constructing a Reference. URI and IRI validation and the common absolute HTTP(S) fast path do not allocate; other web inputs may allocate while applying WHATWG normalization and IDNA processing.
Parameters
- Input
URI, IRI, or URL bytes
- Syntax
Grammar and policy to apply
- Max_Length
Maximum accepted input and serialized byte length
Return value
True exactly when Diagnose reports No_Error
Default_Max_Length
Default_Max_Length : constant Positive := 8 * 1_024;
Default defensive input bound used by parsing operations.
Diagnose
function Diagnose
(Input : String;
Syntax : Syntax_Kind := IRI_Syntax;
Max_Length : Positive := Default_Max_Length) return Parse_Error
Validate and report the first stable error category and byte offset.
Parameters
- Input
URI, IRI, or URL bytes
- Syntax
Grammar and policy to apply
- Max_Length
Maximum accepted input and serialized byte length
Return value
No_Error on success, otherwise the first detected failure
Error_Kind
type Error_Kind is
(No_Error,
Too_Long,
Invalid_Character,
Invalid_Percent_Encoding,
Invalid_Scheme,
Invalid_Authority,
Invalid_Path,
Relative_URL,
Unsupported_URL);
Stable parse failure categories.
Enumeration literals
- No_Error
Parsing succeeded
- Too_Long
Input exceeds the caller's maximum length
- Invalid_Character
Input contains a forbidden character or UTF-8
- Invalid_Percent_Encoding
A percent sign lacks two hexadecimal digits
- Invalid_Scheme
A scheme candidate violates the scheme grammar
- Invalid_Authority
Authority, host, IP literal, or port is malformed
- Invalid_Path
Path violates the selected reference grammar
- Relative_URL
Web URL mode requires an absolute URL
- Unsupported_URL
Web URL mode does not implement this URL form
Fragment
function Fragment (Value : Reference) return String
Return the fragment without #, or an empty string.
Parameters
- Value
Parsed reference
Return value
Fragment component
Has_Authority
function Has_Authority (Value : Reference) return Boolean
Report whether //authority is present, including an empty authority.
Parameters
- Value
Parsed reference
Return value
True when the reference has an authority delimiter
Has_Fragment
function Has_Fragment (Value : Reference) return Boolean
Report whether a fragment delimiter is present, including an empty one.
Parameters
- Value
Parsed reference
Return value
True when
#is present
Has_Query
function Has_Query (Value : Reference) return Boolean
Report whether a query delimiter is present, including an empty query.
Parameters
- Value
Parsed reference
Return value
True when
?is present
Has_Scheme
function Has_Scheme (Value : Reference) return Boolean
Report whether the reference has a scheme.
Parameters
- Value
Parsed reference
Return value
True when Scheme is nonempty
Host
function Host (Value : Reference) return String
Return the host without IPv6 brackets, or an empty string.
Parameters
- Value
Parsed reference
Return value
Host component
Image
function Image (Value : Reference) return String
Return the serialized reference.
Parameters
- Value
Parsed reference
Return value
Stored, possibly normalized serialization
Image_Length
function Image_Length (Value : Reference) return Natural
Return serialized byte length without constructing a String copy.
Parameters
- Value
Parsed reference
Return value
Number of bytes in Image
Is_Valid
function Is_Valid (Value : Reference) return Boolean
Report whether the reference came from a successful parse. A default reference and the value Try_Parse returns on failure are both invalid, which distinguishes a rejected input from a parsed empty reference without inspecting the reported error.
Parameters
- Value
Reference to examine
Return value
True when Parse, Try_Parse or Resolve produced this value
Kind
function Kind (Value : Reference) return Reference_Kind
Return the structural reference classification.
Parameters
- Value
Parsed reference
Return value
Absolute, network-path, absolute-path, relative-path, or empty
Malformed_Reference
Malformed_Reference : exception;
Raised by Parse and Resolve when their input is malformed.
Origin
function Origin (Value : Reference) return String
Return the normalized network origin for an HTTP or WebSocket URL. Credentials, path, query, and fragment are omitted. This adapter is intended for APIs such as Flyology.HTTP.Parse_Origin and Flyology.HTTP.WebSocket_Client.Parse_Origin.
Parameters
- Value
Parsed absolute HTTP(S) or WS(S) web URL
Return value
Scheme, host, and optional nondefault port
Raised exceptions
- Malformed_Reference
Value is not an HTTP or WebSocket URL
Parse
function Parse
(Input : String;
Base : Reference;
Max_Length : Positive := Default_Max_Length) return Reference
Parse a web URL using an already parsed absolute web base URL.
Parameters
- Input
Absolute or relative URL input
- Base
Absolute web URL used for relative resolution
- Max_Length
Maximum accepted input and serialized byte length
Return value
Parsed absolute web URL
Raised exceptions
- Malformed_Reference
Base or input is not a valid web URL
Parse
function Parse
(Input : String;
Syntax : Syntax_Kind := IRI_Syntax;
Max_Length : Positive := Default_Max_Length) return Reference
Parse into a compact owned representation. Web URL mode lowercases the scheme and ASCII host and inserts / for an empty HTTP-style path.
Parameters
- Input
URI, IRI, or URL bytes
- Syntax
Grammar and policy to apply
- Max_Length
Maximum accepted input and serialized byte length
Return value
Parsed reference
Raised exceptions
- Malformed_Reference
Input is invalid
Parse_Error
type Parse_Error is record
Kind : Error_Kind := No_Error;
Offset : Natural := 0;
end record;
Byte offset and failure category returned by Diagnose. Offset is one based relative to the input, or zero when no single byte is responsible.
Record fields
- Kind
Failure category
- Offset
One-based byte offset, or zero
Path
function Path (Value : Reference) return String
Return the path, which may be empty.
Parameters
- Value
Parsed reference
Return value
Path component
Port
function Port (Value : Reference) return String
Return the decimal port without its colon, or an empty string.
Parameters
- Value
Parsed reference
Return value
Port component
Query
function Query (Value : Reference) return String
Return the query without ?, or an empty string.
Parameters
- Value
Parsed reference
Return value
Query component
Reference
type Reference is private;
Compact owned parsed reference. Copies are independent; component getters return fresh String values.
Reference_Kind
type Reference_Kind is
(Absolute_Reference,
Network_Path_Reference,
Absolute_Path_Reference,
Relative_Path_Reference,
Empty_Reference);
Classification of a parsed reference.
Enumeration literals
- Absolute_Reference
A reference containing a scheme
- Network_Path_Reference
A scheme-relative
//authorityreference- Absolute_Path_Reference
A reference whose path starts with
/- Relative_Path_Reference
A nonempty relative-path reference
- Empty_Reference
An empty reference, possibly with query or fragment
Resolve
function Resolve
(Base : Reference;
Relative : String;
Max_Length : Positive := Default_Max_Length) return Reference
Resolve a URI or IRI reference against an absolute base using RFC 3986 section 5.2 merging and dot-segment removal.
Parameters
- Base
Absolute base reference
- Relative
Reference to resolve
- Max_Length
Maximum accepted input and serialized byte length
Return value
Resolved absolute reference
Raised exceptions
- Malformed_Reference
Base is not absolute or result is invalid
Scheme
function Scheme (Value : Reference) return String
Return the scheme without its colon, or an empty string.
Parameters
- Value
Parsed reference
Return value
Scheme component
Syntax
function Syntax (Value : Reference) return Syntax_Kind
Return the selected parsing policy. On failure Try_Parse reports the syntax it was asked for.
Parameters
- Value
Parsed reference
Return value
Syntax used by Parse
Syntax_Kind
type Syntax_Kind is (URI_Syntax, IRI_Syntax, Web_URL_Syntax);
Grammar and normalization policy used by the parser.
Enumeration literals
- URI_Syntax
RFC 3986 ASCII URI-reference grammar
- IRI_Syntax
RFC 3987 UTF-8 IRI-reference grammar
- Web_URL_Syntax
Absolute URL policy for common web schemes
Target
function Target (Value : Reference) return String
Return an HTTP origin-form request target from a parsed HTTP or WebSocket URL. The result contains the path and optional query while deliberately omitting the fragment.
Parameters
- Value
Parsed absolute HTTP(S) or WS(S) web URL
Return value
Origin-form path and optional query
Raised exceptions
- Malformed_Reference
Value is not an HTTP or WebSocket URL
Try_Parse
procedure Try_Parse
(Input : String;
Value : out Reference;
Error : out Parse_Error;
Syntax : Syntax_Kind := IRI_Syntax;
Max_Length : Positive := Default_Max_Length)
Parse without exceptions, returning a default reference on failure.
Parameters
- Input
URI, IRI, or URL bytes
- Value
Parsed reference on success, otherwise a default value
- Error
No_Error on success, otherwise the parse failure
- Syntax
Grammar and policy to apply
- Max_Length
Maximum accepted input and serialized byte length
Try_Parse
procedure Try_Parse
(Input : String;
Base : Reference;
Value : out Reference;
Error : out Parse_Error;
Max_Length : Positive := Default_Max_Length)
Parse a web URL against a base without raising an exception.
Parameters
- Input
Absolute or relative URL input
- Base
Absolute web URL used for relative resolution
- Value
Parsed absolute URL on success
- Error
No_Error on success, otherwise the parse failure
- Max_Length
Maximum accepted input and serialized byte length
Userinfo
function Userinfo (Value : Reference) return String
Return user information without @, or an empty string.
Parameters
- Value
Parsed reference
Return value
User-information component