php-doc-en/reference/net_gopher/functions/gopher-parsedir.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- splitted from ./en/functions/net-gopher.xml, last change in rev  -->
<refentry xml:id="function.gopher-parsedir" xmlns="http://docbook.org/ns/docbook">
 <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>
  <para>
   <function>gopher_parsedir</function> parses a gopher formatted directory
   entry into an associative array.
  </para>
  <para>
   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.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>dirent</parameter></term>
     <listitem>
      <para>
       The directory entry.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an associative array whose components are: 
   <itemizedlist>
    <listitem>
     <simpara>
      <literal>type</literal> - One of the 
      <literal>GOPHER_XXX</literal> constants.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>title</literal> - The name of the resource.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>path</literal> - The path of the resource.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>host</literal> - The domain name of the host that has
      this document (or directory).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>port</literal> - The port at which to connect on
      <literal>host</literal>.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   Upon failure, the additional <literal>data</literal> entry of the
   returned array will hold the parsed line.
  </para>
 </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>
  <para>
   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.
  </para>
  <para>
   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.
  </para>
  <para>
   <example>
    <title>Using <function>gopher_parsedir</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$directory = file("gopher://gopher.example.com");

foreach($directory as $dirent) {
    print_r(gopher_parsedir($dirent));
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
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
)
]]>
    </screen>
   </example>
  </para>
 </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:"~/.phpdoc/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
-->