.. Mars Documentation
   Copyright (C) 2008 Matt Giuca
   3/9/2008

.. This program is free software: you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

.. This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

.. You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.

:mod:`urllib` --- Construction and processing of URLs
=====================================================

.. sectionauthor:: Matt Giuca <matt.giuca@gmail.com>
.. moduleauthor::  Matt Giuca <matt.giuca@gmail.com>

.. module:: urllib
   :synopsis: Functions for construction and processing of URLs.

This module enables construction and processing of URLs and URIs.

.. note::

   This module performs processing of Uniform Resource Identifiers as
   described in `RFC 3986 - URI Generic Syntax
   <http://tools.ietf.org/html/rfc3986>`_.

.. type:: URI

   ::

    URI(scheme :: Array(Num), hier :: Array(Num), query :: Array(Num), fragment :: Array(Num))

   Stores all components as percent-encoded strings.

.. function:: uriString(uri :: URI) :: Array(Num)

   Returns the string representation of *uri*.

.. function:: parseURI(uri :: Array(Num)) :: URI

   Given *uri*, a full URI string, returns a :type:`URI` object.
   It is an error if *uri* is not a valid URI.

.. function:: encodeURIComponent(string :: Array(Num)) :: Array(Num)

   Takes an arbitrary *string* and encodes all necessary bytes so it may
   be used as a URI component. Returns the resulting string.
   Encodes all characters except ASCII-alphanumeric, '-', '.', '_' and '~'.
   It is an error if any element of *string* is outside the range [0, 255].

.. function:: encodeURIComponentPlus(string :: Array(Num)) :: Array(Num)

   Takes an arbitrary *string* and encodes all necessary bytes so it may
   be used as a URI component. Spaces are encoded as a '+' rather than "%20",
   as per HTML forms. Otherwise, same as :func:`encodeURIComponent`.
   It is an error if any element of *string* is outside the range [0, 255].

.. function:: decodeURIComponent(uristring :: Array(Num)) :: Array(Num)

   Takes a URI-encoded string, *uristring*, and decodes all percent-encoded
   sequences into their source bytes.
   The resulting string may contain non-ASCII bytes, with an unspecified
   encoding (dependent on the encoding used in the percent-encoded
   characters). It is usually safe to assume UTF-8 encoding.

.. function:: decodeURIComponentPlus(uristring :: Array(Num)) :: Array(Num)

   Takes a URI-encoded string, *uristring*, and decodes all percent-encoded
   sequences into their source bytes. Also decodes '+' into spaces.
   The resulting string may contain non-ASCII bytes, with an unspecified
   encoding (dependent on the encoding used in the percent-encoded
   characters). It is usually safe to assume UTF-8 encoding.