= URI =

{{{#!rst
Purpose:
  Utility methods which convert to and from file paths and create absolute or relative URIs.

Namespace:
  urn:WebWorks-XSLT-Extension-URI

Prefix:
  wwuri

Methods:
  IsFile(string  uriAsString):
    Determine if the supplied URI refers to the file system.

    Returns:
      Boolean.

    Example:
      Determine if ``\\network\filesystem\file`` and ``file:///network/filesystem/file`` are file URIs.

      ::

        <xsl:if test="wwuri:IsFile('\\\\network\\filesystem\\file')">
         <xsl:variable name="VarLog" select="wwlog:Message('File!')" />
        </xsl:if>

        <xsl:if test="wwuri:IsFile('file:///network/filesystem/file')">
         <xsl:variable name="VarLog" select="wwlog:Message('File!')" />
        </xsl:if>

  AsFilePath(string  uriAsString):
    Convert a file URI into a system file path.

    Returns:
      File path as string.

    Example:
      Convert URIs ``\\network\filesystem\file`` and ``file:///network/filesystem/file`` to file paths.

      ::

        <xsl:variable name="VarFilePath1" select="wwuri:AsFilePath('\\\\network\\filesystem\\file')">

        <xsl:variable name="VarFilePath2" select="wwuri:AsFilePath('file:///network/filesystem/file')">


  AsURI(string  uriAsString):
    Convert file paths to URIs.

    Returns:
      URI as string.

    Example:
      Convert ``C:\file`` to a URI.

      ::

        <xsl:variable name="VarURI" select="wwuri:AsURI('C:\\file')" />


  PossibleResolvedUris(string  uriAsString):
    Convert file paths to URIs.

    Returns:
      Node set of possible resolved URIs for the given virtual URI.

      ::

        <wwuri:Uris>
         <wwuri:Uri value="file:///C:/Users/user/Projects/Targets/Reverb/Transforms/pages.xsl" />
         <wwuri:Uri value="file:///C:/Users/user/Projects/Formats/WebWorks Reverb/Transforms/pages.xsl" />
         <wwuri:Uri value="file:///C:/Program Files (x86)/WebWorks/ePublisher/2012.4/Formats/WebWorks Reverb/Transforms/pages.xsl" />
        </wwuri:Uris>


    Example:
      Resolve virtual URI ``wwformat:Transforms/pages.xsl``.

      ::

        <xsl:variable name="VarPossibleURIs" select="wwuri:PossibleResolvedUris('wwformat:Transforms/pages.xsl')" />
        <xsl:for-each select="$VarPossibleURIs/wwuri:Uris/wwuri:Uri">
         <xsl:variable name="VarPossibleURI" select="." />

         <xsl:if test="wwuri:IsFile($VarPossibleURI)">
          <xsl:variable name="VarPossibleFilePath" select="wwuri:AsFilePath($VarPossibleURI)" />
          <xsl:if test="wwfilesystem:FileExists($VarPossibleFilePath)">
           ...
          </xsl:if>
         </xsl:if>
        </xsl:for-each>


  GetRelativeTo(string  uriAsString, string  anchorUriAsString):
    Convert an absolute URI into a relative URI.

    Returns:
      URI as string.

    Example:
      Determine the relative path to ``http://www.webworks.com/css/webworks.css`` from ``http://www.webworks.com/information/index.html``.

      ::
      
        <xsl:variable name="VarRelativeURI" select="wwuri:GetRelativeTo('http://www.webworks.com/css/webworks.css', 'http://www.webworks.com/information/index.html')" />


  MakeAbsolute(string  absoluteUriAsString, string  uriAsString):
    Convert a relative URI into an absolute URI.  If the second parameter is already an absolute URI, it will be returned unchanged.

    Returns:
      URI as string.

    Example:
      Fully qualify the relative URI ``../css/webworks.css`` against the absolute URI ``http://www.webworks.com/information/index.html``.

      ::
      
        <xsl:variable name="VarCSSURI" select="wwuri:MakeAbsolute('http://www.webworks.com/information/index.html', '../css/webworks.css')" />


  EscapeUri(string  unescapedUri):
    Convert unescaped URI into an escaped URI path.

    Returns:
      Escaped URI as a string.

    Example:
      Convert ``http://www.webworks.com/name with spaces.html`` to ``http://www.webworks.com/name%20with%20spaces.html``.

      ::
      
        <xsl:variable name="VarEscapedURI" select="wwuri:EscapeUri('http://www.webworks.com/name with spaces.html')" />


  EscapeData(string  unescapedString):
    Convert unescaped string into an escaped URI data.

    Returns:
      Escaped string.

    Example:
      Convert ``http://www.webworks.com/name with spaces.html`` to ``http%3a%2f%2fwww.webworks.com%2fname%20with%20spaces.html``.

      ::
      
        <xsl:variable name="VarEscapedData" select="wwuri:EscapeData('http://www.webworks.com/name with spaces.html')" />


  Unescape(string  escapedString):
    Convert URI escaped string into unescaped string (%20 to space, etc.).

    Returns:
      Unescaped string.

    Example:
      Convert ``name%20with%20spaces.html`` to ``name with spaces.html``.

      ::
      
        <xsl:variable name="VarUnescape" select="wwuri:Unescape('name%20with%20spaces.html')" />
}}}