<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-matevfs-uri">
  <refnamediv>
    <refname>matevfs.URI</refname>
    <refpurpose>Object encapsulating a URI</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>
    <classsynopsis language="python">
      <ooclass><classname>matevfs.URI</classname></ooclass>
      <constructorsynopsis language="python">
        <methodname><link linkend="constructor-matevfs-uri">matevfs.URI</link></methodname>
	<methodparam><parameter role="keyword">text_uri</parameter></methodparam>
      </constructorsynopsis>
      <methodsynopsis>
        <methodname><link linkend="method-matevfs-uri--append_file_name">append_file_name</link></methodname>
	<methodparam><parameter role="keyword">file_name</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis>
        <methodname><link linkend="method-matevfs-uri--append_path">append_path</link></methodname>
	<methodparam><parameter role="keyword">path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis>
        <methodname><link linkend="method-matevfs-uri--append_string">append_string</link></methodname>
	<methodparam><parameter role="keyword">path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis>
        <methodname><link linkend="method-matevfs-uri--copy">copy</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis>
        <methodname><link linkend="method-matevfs-uri--is_parent">is_parent</link></methodname>
	<methodparam><parameter role="keyword">item</parameter></methodparam>
	<methodparam><parameter role="keyword">recursive</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis>
        <methodname><link linkend="method-matevfs-uri--resolve_relative">resolve_relative</link></methodname>
	<methodparam><parameter role="keyword">relative_reference</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>
  </refsect1>

  <refsect1>
    <title>Description</title>
    <para></para>
  </refsect1>

  <refsect1>
    <title>Attributes</title>
    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
        <tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="3" colwidth="3.5in"/>

	  <tbody>
	    <row valign="top">
	      <entry>dirname</entry>
	      <entry>Read/Write</entry>
	      <entry>The name of the directory in which the file pointed to by this URI is located.</entry>
	    </row>

	    <row valign="top">
	      <entry>fragment_identifier</entry>
	      <entry>Read/Write</entry>
	      <entry></entry>
	    </row>

	    <row valign="top">
	      <entry>host_name</entry>
	      <entry>Read</entry>
	      <entry>Server hostname (for remote schemes).</entry>
	    </row>

	    <row valign="top">
	      <entry>host_port</entry>
	      <entry>Read</entry>
	      <entry>Server port (for remote schemes).</entry>
	    </row>

	    <row valign="top">
	      <entry>is_local</entry>
	      <entry>Read/Write</entry>
	      <entry>Whether the URI is a local filesystem.</entry>
	    </row>

	    <row valign="top">
	      <entry>parent</entry>
	      <entry>Read/Write</entry>
	      <entry>The parent URI.</entry>
	    </row>

	    <row valign="top">
	      <entry>password</entry>
	      <entry>Read</entry>
	      <entry>Password (for schemes which require authorization).</entry>
	    </row>

	    <row valign="top">
	      <entry>path</entry>
	      <entry>Read/Write</entry>
	      <entry>The full path name.</entry>
	    </row>

	    <row valign="top">
	      <entry>scheme</entry>
	      <entry>Read/Write</entry>
	      <entry>The URI scheme (`gzip', `tar', `http', etc).</entry>
	    </row>

	    <row valign="top">
	      <entry>short_name</entry>
	      <entry>Read/Write</entry>
	      <entry>The base name for the file referred to by this URI.  This matches the XPG definition of a basename.  This is useful when you want the name of the URI target, but don't care whether the URI points to a file or directory.  If the URI points to the root of a domain, this is the host name.</entry>
	    </row>

	    <row valign="top">
	      <entry>short_path_name</entry>
	      <entry>Read/Write</entry>
	      <entry>Same as short_name, but if the URI points to the root of a domain, this is equal to /</entry>
	    </row>

	    <row valign="top">
	      <entry>toplevel</entry>
	      <entry>Read/Write</entry>
	      <entry>The toplevel URI</entry>
	    </row>

	    <row valign="top">
	      <entry>user_name</entry>
	      <entry>Read</entry>
	      <entry>User name (for schemes which require authorization).</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>
  </refsect1>

  <refsect1>
    <title>Constructor</title>

    <refsect2 id="constructor-matevfs-uri">
      <programlisting>
        <constructorsynopsis language="python">
          <methodname>matevfs.URI</methodname>
	  <methodparam><parameter role="keyword">text_uri</parameter></methodparam>
        </constructorsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><parameter role="keyword">text_uri</parameter>:</term>
	  <listitem><simpara>A string representing the URI.</simpara></listitem>
	</varlistentry>
        <varlistentry>
	  <term><emphasis>Returns</emphasis>:</term>
	  <listitem><simpara>the new <link linkend="class-matevfs-uri">matevfs.URI</link></simpara></listitem>
	</varlistentry>
      </variablelist>
      <para></para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-matevfs-uri--append_file_name">
      <title>matevfs.URI.append_file_name</title>
      <programlisting>
        <methodsynopsis language="python">
          <methodname>append_file_name</methodname>
	  <methodparam><parameter role="keyword">file_name</parameter></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><parameter role="keyword">file_name</parameter>:</term>
	  <listitem><simpara>The file name to append.</simpara></listitem>
	</varlistentry>
        <varlistentry>
	  <term><emphasis>Returns</emphasis>:</term>
	  <listitem><simpara>The new URI.</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>Create a new URI by appending <parameter role="keyword">file_name</parameter>.  This will add the appropriate directory separator if necessary.</para>
    </refsect2>

    <refsect2 id="method-matevfs-uri--append_path">
      <title>matevfs.URI.append_path</title>
      <programlisting>
        <methodsynopsis language="python">
          <methodname>append_path</methodname>
	  <methodparam><parameter role="keyword">path</parameter></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><parameter role="keyword">path</parameter>:</term>
	  <listitem><simpara>The path to append (unescaped)</simpara></listitem>
	</varlistentry>
        <varlistentry>
	  <term><emphasis>Returns</emphasis>:</term>
	  <listitem><simpara>The new URI.</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>Create a new URI by appending <parameter role="keyword">path</parameter>.  This will add the appropriate directory separator if necessary.</para>
    </refsect2>

    <refsect2 id="method-matevfs-uri--append_string">
      <title>matevfs.URI.append_string</title>
      <programlisting>
        <methodsynopsis language="python">
          <methodname>append_string</methodname>
	  <methodparam><parameter role="keyword">path</parameter></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><parameter role="keyword">path</parameter>:</term>
	  <listitem><simpara>The path to append (fully escaped)</simpara></listitem>
	</varlistentry>
        <varlistentry>
	  <term><emphasis>Returns</emphasis>:</term>
	  <listitem><simpara>The new URI.</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>Create a new URI by appending <parameter role="keyword">path</parameter>.  This will add the appropriate directory separator if necessary.</para>
    </refsect2>

    <refsect2 id="method-matevfs-uri--copy">
      <title>matevfs.URI.copy</title>
      <programlisting>
        <methodsynopsis language="python">
          <methodname>copy</methodname>
	  <methodparam></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><emphasis>Returns</emphasis>:</term>
	  <listitem><simpara>A copy of this URI.</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>Create a copy of this URI.</para>
    </refsect2>

    <refsect2 id="method-matevfs-uri--is_parent">
      <title>matevfs.URI.is_parent</title>
      <programlisting>
        <methodsynopsis language="python">
          <methodname>is_parent</methodname>
	  <methodparam><parameter role="keyword">item</parameter></methodparam>
	  <methodparam><parameter role="keyword">recursive</parameter></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><parameter role="keyword">item</parameter>:</term>
	  <listitem><simpara>The item to search for.</simpara></listitem>
	</varlistentry>
        <varlistentry>
	  <term><parameter role="keyword">recursive</parameter>:</term>
	  <listitem><simpara>Whether to check the entire hierarchy.</simpara></listitem>
	</varlistentry>
        <varlistentry>
	  <term><emphasis>Returns</emphasis>:</term>
	  <listitem><simpara>True if <parameter role="keyword">item</parameter> is a child of self.</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>Check if this URI is a parent of <parameter role="keyword">item</parameter>.  If <parameter role="keyword">recursive</parameter> is True, check the entire hierarchy.</para>
    </refsect2>

    <refsect2 id="method-matevfs-uri--resolve_relative">
      <title>matevfs.URI.resolve_relative</title>
      <programlisting>
        <methodsynopsis language="python">
          <methodname>resolve_relative</methodname>
	  <methodparam><parameter role="keyword">relative_reference</parameter></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
	  <term><parameter role="keyword">relative_reference</parameter>:</term>
	  <listitem><simpara>A string representing the (possibly) relative URI.</simpara></listitem>
	</varlistentry>
        <varlistentry>
	  <term><emphasis>Returns</emphasis>:</term>
	  <listitem><simpara>The new URI.</simpara></listitem>
	</varlistentry>
      </variablelist>
      <para>Create a new URI from <parameter role="keyword">relative_reference</parameter> relative to self.  The resolution algorithm follows RFC 2396. For details, see section 5.2 of http://www.ietf.org/rfc/rfc2396.txt .</para>
      <para>In short, if the base uri ends in '/', relative_reference is appended to base, otherwise it replaces the part of base after the last '/'.</para>
    </refsect2>
  </refsect1>
</refentry>
