URI Utilities Library 1.0.3

Delphi 4 to 2009 and Kylix 3 Implementation

by Dieter Köhler


LICENSE

The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at "http://www.mozilla.org/MPL/"

Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.

The Original Code is "UriUtils.pas".

The Initial Developer of the Original Code is Dieter Köhler (Heidelberg, Germany, "http://www.philo.de/"). Portions created by the Initial Developer are Copyright (C) 2003-2008 Dieter Köhler. All Rights Reserved.

Alternatively, the contents of this file may be used under the terms of the GNU General Public License Version 2 or later (the "GPL"), in which case the provisions of the GPL are applicable instead of those above. If you wish to allow use of your version of this file only under the terms of the GPL, and not to allow others to use your version of this file under the terms of the MPL, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the GPL. If you do not delete the provisions above, a recipient may use your version of this file under the terms of any one of the MPL or the GPL.


Introduction

The URI Utilities Library contains helper functions for Universal Resource Identifier (URI) processing. For more information about URIs see the relevant specifications:

The latest version of this software is available at <http://www.philo.de/xml/>.


Using the unit

The URI Utilities Library does not contain any components to be registered. So using it from inside your own projects is very simple: Add "UriUtils" to the uses clause of your unit and make sure that the path to the location of the UriUtils.pas file is included in Delphi's list of library paths. To include it go to the Library section of Delphi's Environment Options dialog (see the menu item: "Tools/Environment Options ...").


Routines for Testing URI Rules

String and Character Test Functions

The following functions serve to test whether a string S or character C conforms to the respective Universal Resource Identifier (URI) rule (see [RFC 2396], App. A). All functions return 'true' if S or C conforms to the rule, otherwise 'false' is returned.

function IsUriURI_referenceStr(S: string): Boolean;
function IsUriAbsoluteURIStr(S: string): Boolean;
function IsUriRelativeURIStr(S: string): Boolean;
function IsUriHier_partStr(S: string): Boolean;
function IsUriOpaque_partStr(S: string): Boolean;
function IsUriNet_pathStr(S: string): Boolean;
function IsUriAbs_pathStr(S: string): Boolean;
function IsUriRel_pathStr(S: string): Boolean;
function IsUriRel_segmentStr(S: string): Boolean;
function IsUriSchemeStr(S: string): Boolean;
function IsUriAuthorityStr(S: string): Boolean;
function IsUriReg_nameStr(S: string): Boolean;
function IsUriServerStr(S: string): Boolean;
function IsUriUserinfoStr(S: string): Boolean;
function IsUriHostPortStr(S: string): Boolean;
function IsUriHostStr(S: string): Boolean;
function IsUriHostnameStr(S: string): Boolean;
function IsUriDomainlabelStr(S: string): Boolean;
function IsUriToplabelStr(S: string): Boolean;
function IsUriIPv4addressStr(S: string): Boolean;
function IsUriPortStr(S: string): Boolean;
function IsUriPathStr(S: string): Boolean;
function IsUriPath_segmentsStr(S: string): Boolean;
function IsUriSegmentStr(S: string): Boolean;
function IsUriParamStr(S: string): Boolean;
function IsUriQueryStr(S: string): Boolean;
function IsUriFragmentStr(S: string): Boolean;
function IsUriUricStr(S: string): Boolean;
function IsUriReservedChar(C: Char): Boolean;
function IsUriUnreservedChar(C: Char): Boolean;
function IsUriMarkChar(C: Char): Boolean;
function IsUriHexChar(C: Char): Boolean;
function IsUriAlphanumChar(C: Char): Boolean;
function IsUriAlphaChar(C: Char): Boolean;
function IsUriDigitChar(C: Char): Boolean;

Wide String and Wide Character Test Functions

The following functions serve to test whether a WideString S or WideChar C conforms to the respective Universal Resource Identifier (URI) rule (see [RFC 2396], App. A). All functions return 'True' if S or C conforms to the rule, otherwise 'False' is returned.

function IsUriURI_referenceWideStr(S: WideString): Boolean;
function IsUriAbsoluteURIWideStr(S: WideString): Boolean;
function IsUriRelativeURIWideStr(S: WideString): Boolean;
function IsUriHier_partWideStr(S: WideString): Boolean;
function IsUriOpaque_partWideStr(S: WideString): Boolean;
function IsUriNet_pathWideStr(S: WideString): Boolean;
function IsUriAbs_pathWideStr(S: WideString): Boolean;
function IsUriRel_pathWideStr(S: WideString): Boolean;
function IsUriRel_segmentWideStr(S: WideString): Boolean;
function IsUriSchemeWideStr(S: WideString): Boolean;
function IsUriAuthorityWideStr(S: WideString): Boolean;
function IsUriReg_nameWideStr(S: WideString): Boolean;
function IsUriServerWideStr(S: WideString): Boolean;
function IsUriUserinfoWideStr(S: WideString): Boolean;
function IsUriHostPortWideStr(S: WideString): Boolean;
function IsUriHostWideStr(S: WideString): Boolean;
function IsUriHostnameWideStr(S: WideString): Boolean;
function IsUriDomainlabelWideStr(S: WideString): Boolean;
function IsUriToplabelWideStr(S: WideString): Boolean;
function IsUriIPv4addressWideStr(S: WideString): Boolean;
function IsUriPortWideStr(S: WideString): Boolean;
function IsUriPathWideStr(S: WideString): Boolean;
function IsUriPath_segmentsWideStr(S: WideString): Boolean;
function IsUriSegmentWideStr(S: WideString): Boolean;
function IsUriParamWideStr(S: WideString): Boolean;
function IsUriQueryWideStr(S: WideString): Boolean;
function IsUriFragmentWideStr(S: WideString): Boolean;
function IsUriUricWideStr(S: WideString): Boolean;
function IsUriReservedWideChar(C: WideChar): Boolean;
function IsUriUnreservedWideChar(C: WideChar): Boolean;
function IsUriMarkWideChar(C: WideChar): Boolean;
function IsUriHexWideChar(C: WideChar): Boolean;
function IsUriAlphanumWideChar(C: WideChar): Boolean;
function IsUriAlphaWideChar(C: WideChar): Boolean;
function IsUriDigitWideChar(C: WideChar): Boolean;

URI Processing

The following functions and classes provide means for some general operations on Universal Resource Identifiers.

TdomFilenameToUriOptions = set of (fuSetLocalhost, fuPlainColon);

TdomFilenameToUriOptions defines a set of constants which determine filename to URI transformations.


function FilenameToUriStr(const Path: TFilename; const Opt: TUtilsFilenameToUriOptions): string;

Generates a "file" scheme URI reference from a string that represents a file name, and returns it as a string. Unreserved characters are escaped according to [RFC 2396], § 2.4.

Parameters:

Return Value:


function FilenameToUriWideStr(const Path: TFilename; const Opt: TUtilsFilenameToUriOptions): WideString;

Generates a "file" scheme URI reference from a string that represents a file name, and returns it as a WideString. Unreserved characters are escaped according to [RFC 2396], § 2.4.

Parameters:

Return Value:


function ResolveRelativeUriStr(const BaseUri, RelUri: string; var ResultUri: string): Boolean;

Resolves an URI reference relative to a given base URI. For details on URI resolvement see [RFC 2396], § 5.2 and App. C.

Parameters:

Return Parameter:

Return Value:


function ResolveRelativeUriWideStr(const BaseUri, RelUri: WideString; var ResultUri: WideString): Boolean;

Resolves an URI reference relative to a given base URI. For details on URI resolvement see [RFC 2396], § 5.2 and App. C.

Parameters:

Return Parameter:

Return Value:


function UriStrToFilename(const Uri: string; var Path: TFilename; var Authority, Query, Fragment: string): Boolean;

Extracts the relevant information from a "file" scheme URI reference.

Parameters:

Return Parameter:

Return Value:


function UriWideStrToFilename(const Uri: WideString; var Path: TFilename; var Authority, Query, Fragment: string): Boolean;

Extracts the relevant information from a "file" scheme URI reference.

Parameters:

Return Parameter:

Return Value:


TUriStrAnalyzer = class

This class can be used to analyze an URI reference or to construct an URI reference from its parts by using strings (see TUriWideStrAnalyzer for an equivalent class designed for WideStrings). The relevant parts are the URI reference's scheme (omitting the final ':'), authority (omitting the leading '//'), path (including the leading '/' if any), query (omitting the leading '?'), and fragment identifier (omitting the leading '#'). The following properties can be used to extract the URI information as a string:

Since an URI's authority, fragment, query or scheme part can be undefined as well as be empty, it is not sufficient to check only the string information, which also returns an empty string if the respective part is undefined. The following properties can be used to check whether a specific part was defined or not:

To specify the value of an URI reference or of one of its parts the following functions can be used. The 'Value' parameter contains the value to be set and the 'IsDefined' parameter when required must be set to 'True' to define the respective URI part and set to 'False' to undefine it (in this case the 'Value' parameter is not evaluated and the respective string information property will return an empty string). Setting the value of one of the URI parts will also effect the value of the 'UriReference' property as well as setting the value of the 'UriReference' property will effect the URI parts. If a set operation was successful the function returns 'True'; otherwise -- i.e. if 'IsDefined' when required was set to 'True' and the provided 'Value' was malformed -- 'False' is returned and the result of the function is the same as if it was called with the property 'Value' containing an empty string and 'IsDefined' when required set to 'False'.


TUriWideStrAnalyzer = class

This class can be used to analyze an URI reference or to construct an URI reference from its parts by using WideStrings (see TUriStrAnalyzer for an equivalent class designed for dtrings). The relevant parts are the URI reference's scheme (omitting the final ':'), authority (omitting the leading '//'), path (including the leading '/' if any), query (omitting the leading '?'), and fragment identifier (omitting the leading '#'). The following properties can be used to extract the URI information as a WideString:

Since an URI's authority, fragment, query or scheme part can be undefined as well as be empty, it is not sufficient to check only the string information, which also returns an empty WideString if the respective part is undefined. The following properties can be used to check whether a specific part was defined or not:

To specify the value of an URI reference or of one of its parts the following functions can be used. The 'Value' parameter contains the value to be set and the 'IsDefined' parameter when required must be set to 'True' to define the respective URI part and set to 'False' to undefine it (in this case the 'Value' parameter is not evaluated and the respective string information property will return an empty WideString). Setting the value of one of the URI parts will also effect the value of the 'UriReference' property as well as setting the value of the 'UriReference' property will effect the URI parts. If a set operation was successful the function returns 'True'; otherwise -- i.e. if 'IsDefined' when required was set to 'True' and the provided 'Value' was malformed -- 'False' is returned and the result of the function is the same as if it was called with the property 'Value' containing an empty string and 'IsDefined' when required set to 'False'.