<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/net-gopher.xml, last change in rev  -->
<refentry id="function.gopher-parsedir">
 <refnamediv>
  <refname>gopher_parsedir</refname>
  <refpurpose>Translate a gopher formatted directory entry into an associative array.</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>gopher_parsedir</methodname>
   <methodparam><type>string</type><parameter>dirent</parameter></methodparam>
  </methodsynopsis>
  <simpara>
   While gopher returns <literal>text/plain</literal> documents for
   actual document requests. A request to a directory (such as /) will
   return specially encoded series of lines with each line being one
   directory entry or information line.
  </simpara>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example> 
    <title>Hypothetical output from <literal>gopher://gopher.example.com/</literal></title>
    <screen>
<![CDATA[
0All about my gopher site.	/allabout.txt	gopher.example.com	70
9A picture of my cat.	/pics/cat.png	gopher.example.com	70
1A collection of my writings.	/stories	gopher.example.com	70
hThe HTTP version of this site.	URL:http://www.example.com	gopher.example.com	70
1Mirror of this site in Spain.	/	gopher.ejemplo.co.es	70
iWelcome to my gopher site.		error.host	1
iPlease select one of the options above		error.host	1
iSend complaints to /dev/null		error.host	1
iLong live gopher!		error.host	1
]]>
    </screen>
   </example>
  </para>
  <simpara>
   In the example above, the root directory at gopher.example.com knows about
   one <literal>DOCUMENT</literal> identified by <literal>0</literal> located at
   <literal>gopher://gopher.example.com:70/allabout.txt</literal>.  It also knows
   about two other directory (which have their own listing files) at
   <literal>gopher://gopher.exmaple.com:70/stories</literal> and at
   <literal>gopher://gopher.ejemplo.co.es:70/</literal>.
   In addition there is a binary file, a link to an HTTP url, and several
   informative lines.
  </simpara>
  <simpara>
   By passing each line of the directory listing into 
   <function>gopher_parsedir</function>, an associative array is formed containing
   a parsed out version of the data.
  </simpara>
  <para>
   <example>
    <title>Using <function>gopher_parsedir</function></title>
    <programlisting role="php">
<![CDATA[
<?php
dl("gopher.so");

$directory = file("gopher://gopher.example.com");

foreach($directory as $dirent) {
    print_r(gopher_parsedir($dirent));
}

/* Expected Output
   ---------------

Array (
  [type] => 0
  [title] => All about my gopher site.
  [path] => /allabout.txt
  [host] => gopher.example.com
  [port] => 70
)
Array (
  [type] => 9
  [title] => A picture of my cat.
  [path] => /pics/cat.png
  [host] => gopher.example.com
  [port] => 70
)
Array (
  [type] => 1
  [title] => A collection of my writings.
  [path] => /stories
  [host] => gopher.example.com
  [port] => 70
)
Array (
  [type] => 254
  [title] => The HTTP version of this site.
  [path] => URL:http://www.example.com
  [host] => gopher.example.com
  [port] => 70
)
Array (
  [type] => 1
  [title] => Mirror of this site in Spain.
  [path] => /
  [host] => gopher.ejemplo.co.es
  [port] => 70
)
Array (
  [type] => 255
  [title] => Welcome to my gopher site.
  [path] =>
  [host] => error.host
  [port] => 1
)
Array (
  [type] => 255
  [title] => Please select one of the options above.
  [path] =>
  [host] => error.host
  [port] => 1
)
Array (
  [type] => 255
  [title] => Send complaints to /dev/null
  [path] =>
  [host] => error.host
  [port] => 1
)
Array (
  [type] => 255
  [title] => Long live gopher!
  [path] =>
  [host] => error.host
  [port] => 1
)
*/
?>
]]>
    </programlisting>
   </example>
  </para>
  <simpara>
   The values given by <parameter>type</parameter> are associated with
   the following constants.
  </simpara>
   <table>
    <title>Gopher Constants</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Constant</entry>
       <entry>Definition</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><constant>GOPHER_DOCUMENT</constant></entry>
       <entry>Standard <literal>text/plain</literal> document.</entry>
      </row>
      <row>
       <entry><constant>GOPHER_DIRECTORY</constant></entry>
       <entry>A resource containing a gopher formatted directory listing.</entry>
      </row>
      <row>
       <entry><constant>GOPHER_BINHEX</constant></entry>
       <entry>A BinHex encoded binary file.</entry>
      </row>
      <row>
       <entry><constant>GOPHER_DOSBINARY</constant></entry>
       <entry>A DOS formatted binary archive.</entry>
      </row>
      <row>
       <entry><constant>GOPHER_UUENCODED</constant></entry>
       <entry>A UUEncoded file.</entry>
      </row>
      <row>
       <entry><constant>GOPHER_BINARY</constant></entry>
       <entry>A generic binary file.</entry>
      </row>
      <row>
       <entry><constant>GOPHER_INFO</constant></entry>
       <entry>An Informational entry</entry>
      </row>
      <row>
       <entry><constant>GOPHER_HTTP</constant></entry>
       <entry>A reference to an HTTP resource.</entry>
      </row>
      <row>
       <entry><constant>GOPHER_UNKNOWN</constant></entry>
       <entry>
        An unrecognized entry, the line will be returned 
        in <parameter>data</parameter>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->