.. default-domain:: chpl

.. module:: URL
   :synopsis: Download data from a URL or upload data to a URL.

URL
===
**Usage**

.. code-block:: chapel

   use URL;


or

.. code-block:: chapel

   import URL;



Download data from a URL or upload data to a URL.

For example, the following program downloads a web-page from http://example.com and outputs each line to stdout:

.. code-block:: chapel

  use URL;
  var urlreader = openUrlReader("http://example.com");
  var str:bytes;
  // Output each line read from the URL to stdout
  while(urlreader.readLine(str)) {
    write(str);
  }

.. note::

  This module is currently implemented using :mod:`Curl`. As such, please see
  the :mod:`Curl` documentation to see which protocols are available.

 

.. function:: proc openUrlReader(url: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), style: iostyle): fileReader(kind, locking) throws

   .. warning::

      openUrlReader with a style and/or kind argument is deprecated

.. function:: proc openUrlReader(url: string, param locking = true, start: int(64) = 0, end: int(64) = max(int(64))): fileReader(locking) throws

   .. warning::

      openUrlReader with a start and/or end argument is deprecated. Please use the new region argument instead.

.. function:: proc openUrlReader(url: string, param locking = true, region: range(?) = 0..): fileReader(locking) throws

   
   
   Open a fileReader from a particular URL.
   
   :arg url: which url to open (for example, "http://example.com").
   :arg locking: compile-time argument to determine whether or not the
                 channel should use locking; sets the
                 corresponding parameter of the :record:`~IO.fileReader` type.
                 Defaults to true, but when safe, setting it to false
                 can improve performance.
   :arg region: zero-based byte offset indicating where in the file the
                fileReader should read. Defaults to ``0..`` - meaning from the
                start of the file to no end point.
   :returns: an open fileReader to the requested resource.
   
   :throws SystemError: Thrown if a fileReader could not be returned.
    

.. function:: proc openUrlWriter(url: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), style: iostyle): fileWriter(kind, locking) throws

   .. warning::

      openUrlWriter with a style and/or kind argument is deprecated

.. function:: proc openUrlWriter(url: string, param locking = true, start: int(64) = 0, end: int(64) = max(int(64))): fileWriter(locking) throws

   .. warning::

      openUrlWriter with a start and/or end argument is deprecated. Please use the new region argument instead.

.. function:: proc openUrlWriter(url: string, param locking = true, region: range(?) = 0..): fileWriter(locking) throws

   
   
   Open a fileWriter to a particular URL.
   
   :arg path: which file to open (for example, "ftp://127.0.0.1/upload/test.txt")
   :arg locking: compile-time argument to determine whether or not the
                 fileWriter should use locking; sets the
                 corresponding parameter of the :record:`~IO.fileWriter` type.
                 Defaults to true, but when safe, setting it to false
                 can improve performance.
   :arg region: zero-based byte offset indicating where in the file the
                fileWriter should write. Defaults to ``0..`` - meaning from the
                start of the file to no end point.
   :returns: an open fileWriter to the requested resource.
   
   :throws SystemError: Thrown if a fileWriter could not be returned.