<commit_before><?xml version="1.0" encoding="iso-8859-1"?>
<document title="XP::Tasks::Overview">
  <main>
    <references>
      <ref link="about">An introduction</ref>
      <ref link="examples">Examples</ref>
      <ref type="ext" link="http://php3.de/manual/en/features.commandline.php">Using PHP from the command line</ref>
      <ref type="ext" link="http://www.gnome.org/seegnome.html">See GTK/Gnome in action</ref>
      <ref type="ext" link="http://www.gimp.org/the_gimp_screenshots.html">GIMP screenshots</ref>
      <ref type="ext" link="http://gtk.php.net/resources.php">PHP-GTK: Resources</ref>
      <ref type="ext" link="http://www.eit.uni-kl.de/litz/lehre/seminar/seminar_ss_01/Meisner/sld012.htm">What is SOAP? (Slides)</ref>
      <ref type="ext" link="http://www.fh-wedel.de/~si/seminare/ws00/Ausarbeitung/6.soap/soap01.htm">SOAP introduction</ref>
      <ref type="ext" link="http://de3.php.net/manual/en/history.php">History of PHP and related projects</ref>
    </references>
    <content>
      <title>Common Tasks</title>
      <editor>$Id$</editor>
      
      <para>
        <caption>How to complete common tasks with XP</caption>
        <text>
          This section will give an introduction to the basics of common tasks
          and how to accomplish them using the XP framework.
        </text>
      </para>
      
      <!-- cmd -->
      <para>
        <caption>Command-line tools</caption>
        <text>
          This is probably the most simple of all tasks, though not common to a large
          number of PHP users: PHP runs very well and stable as a command line tool,
          such as Perl, given even more power in the Release of PHP 4.3.0, where the
          CLI SAPI was introduced (see <ref type="ext" link="http://php3.de/manual/en/features.commandline.php">
          Using PHP from the command line</ref> for more information).
          <br/>
          As the XP framework's exception classes have no formatted error messages at all,
          you won't find yourself lost in tons of useless HTML pooring down your shell window if
          you print out stack traces (<ref type="api:class" link="lang.Exception#printStackTrace"/>) 
          or an object's string representation (<ref type="api:class" link="lang.Object#toString"/>).
          <br/>
          Command line tools differ from websites in various ways:
          <ul>
            <li>
              Usually, no HTML is printed. Text is formatted with linefeeds, tabs or spaces, 
              special characters or combination of such to draw lines, arrows or underline
              stuff.
            </li>
            <li>
              Input is read from STDIN, printed to STDOUT or STDERR.
            </li>
            <li>
              Variables (arguments) are passed via command line parameters, such as 
              <tt>-l</tt>, <tt>--debug</tt> or <tt>--prefix=/usr/local/</tt>.
            </li>
          </ul>
          This sounds like hacking in the first place, but actually, it's more like a religion. 
          Anyway, that's another story not to be told here, so let's have a start.
          <br/>
          <br/>
          Take, for example, this sample command line application:
          <code><![CDATA[  require('lang.base.php');
  xp::sapi('cli');

  $p= &new ParamString();
  if (2 != $p->count) {   // Always #options +1: values include script's name (#0)
    Console::writeLinef('Usage: %s <name>', $p->value(0));
    exit();
  }
  Console::writeLinef('Hello %s, how are you?', $p->value(1)); ]]></code>
          Calling this application from the command line as <tt>php -q hello.php</tt> 
          (assuming this script is called hello.php),
          it will simply print out <tt>Usage: hello.php &lt;name&gt;</tt> and exit. If a name
          is specified, e.g. <tt>php -q hello.php Timm</tt>, you will se <tt>Hello Timm, how
          are you?</tt> appear on your shell window. Simple enough?
          <br/>
          <br/>
          Now, we'll include support for a help option as seen in most tools (that is, supply
          a <tt>-?</tt> or <tt>--help</tt> in the parameter list of a command line tool and it
          will say how you're supposed to use it). Again, this is simple - modify line no. five
          of the above example to read:
          <code><![CDATA[  if (2 != $p->count || $p->exists('help', '?')) { ]]></code>
          As soon as a user calls <tt>php -q hello.php -?</tt> or <tt>php -q hello.php --help</tt>,
          the tool will now also print out the usage information. Have a look at the 
          <ref type="api:class" link="util.cmd.ParamString"/> class for more information.
          <br/>
          <br/>
          There is actually not much more to know about the basics of command line scripts
          in relation to the XP framework. There are however, some advanced topics
          on more complex tasks and how they're wrapped into classes and objects.
        </text>
        <!-- TBD
        <advanced>
          <ref link="tasks.cmd.stdio">Using the standard I/O streams</ref>
          <ref link="tasks.cmd.cron">Cronjobs</ref>
          <ref link="tasks.cmd.interactive">Interactive tools</ref>
        </advanced>
        -->
      </para>
      
      <!-- web -->
      <para>
        <caption>Web sites</caption>
        <text>
          <!-- <ref type="api:class" link="org.apache.HttpScriptlet"/> -->
          Web sites is what PHP was made for. In his 
          <ref type="ext" link="http://groups.google.com/groups?selm=3r7pgp%24aa1%40ionews.io.org">announce mail</ref>
          in June of 1995, Rasmus Lerdorf marketed PHP (then called "Personal Home Page Tools"
          as the ideal tool to develop guest books and handle form requests.
          <br/>
          PHP (now called "PHP Hypertext Preprocessor") has since then become much more than
          a "set of cgi scripts". Of course, it is still formidable at handling HTTP request, be
          it as an Apache module or as a CGI. Recently, Yahoo! - being one of the world's busiest
          sites - <ref type="ext" link="http://news.com.com/2100-1023-963937.html?tag=lh">has decided 
          to migrate its scripts to PHP</ref>.
          <br/>
          <br/>
          The XP framework introduces an API called "scriptlets". Scriptlets are the counterpart to 
          Java's Servlets - as one might have guessed from their name. Scriptlets are not a 1:1 
          implementation of Servlets though one might find a lot of similarities!
          <br/>
          Let's have a look at a simple scriptlet:
          <code><![CDATA[  uses('org.apache.HttpScriplet');

  class HelloScriptlet extends HttpScriplet {

    function doGet(&$request, &$response) {
      // [... Sample abridged for brevity ...]
      if (empty($request->getParam('name'))) {
        $response->write('
          <form action="'.basename($request->getEnvValue('SCRIPT_URI')).'">
            Enter your name here: <input type="text" name="name"/>
            <input type="submit"/>
          </form>
        ');
        return;
      }
      $response->write('Hello '.$request->getParam('name'));
    }
  } ]]></code>
          Of course, this seems, not much more elaborate than embedding PHP
          into HTML. Plus, it's probably more complicated to use all the object-oriented
          "bloat" at first.
          <br/>
          <br/>
          Of course, writing out HTML (with maybe some variable here or there) is easy,
          but you will find that after a while of doing so, it turns out this tactic
          is rather counter-productive. Imagine you want to completely redesign your website:
          Changing the navigation from a frameset to tables, put some links at top, make
          each page contain a link to produce a printer-friendly version of itself.
          <br/>
          You will inadvertedly find yourself going through tons of sourcecode "knowing"
          to much about but effectively producing the same HTML over and over and will<commit_msg>- Change org.apache.HttpScriplet to scriptlet.HttpScriplet # The scriptlet API in org.apache is dead<commit_after><?xml version="1.0" encoding="iso-8859-1"?>
<document title="XP::Tasks::Overview">
  <main>
    <references>
      <ref link="about">An introduction</ref>
      <ref link="examples">Examples</ref>
      <ref type="ext" link="http://php3.de/manual/en/features.commandline.php">Using PHP from the command line</ref>
      <ref type="ext" link="http://www.gnome.org/seegnome.html">See GTK/Gnome in action</ref>
      <ref type="ext" link="http://www.gimp.org/the_gimp_screenshots.html">GIMP screenshots</ref>
      <ref type="ext" link="http://gtk.php.net/resources.php">PHP-GTK: Resources</ref>
      <ref type="ext" link="http://www.eit.uni-kl.de/litz/lehre/seminar/seminar_ss_01/Meisner/sld012.htm">What is SOAP? (Slides)</ref>
      <ref type="ext" link="http://www.fh-wedel.de/~si/seminare/ws00/Ausarbeitung/6.soap/soap01.htm">SOAP introduction</ref>
      <ref type="ext" link="http://de3.php.net/manual/en/history.php">History of PHP and related projects</ref>
    </references>
    <content>
      <title>Common Tasks</title>
      <editor>$Id$</editor>
      
      <para>
        <caption>How to complete common tasks with XP</caption>
        <text>
          This section will give an introduction to the basics of common tasks
          and how to accomplish them using the XP framework.
        </text>
      </para>
      
      <!-- cmd -->
      <para>
        <caption>Command-line tools</caption>
        <text>
          This is probably the most simple of all tasks, though not common to a large
          number of PHP users: PHP runs very well and stable as a command line tool,
          such as Perl, given even more power in the Release of PHP 4.3.0, where the
          CLI SAPI was introduced (see <ref type="ext" link="http://php3.de/manual/en/features.commandline.php">
          Using PHP from the command line</ref> for more information).
          <br/>
          As the XP framework's exception classes have no formatted error messages at all,
          you won't find yourself lost in tons of useless HTML pooring down your shell window if
          you print out stack traces (<ref type="api:class" link="lang.Exception#printStackTrace"/>) 
          or an object's string representation (<ref type="api:class" link="lang.Object#toString"/>).
          <br/>
          Command line tools differ from websites in various ways:
          <ul>
            <li>
              Usually, no HTML is printed. Text is formatted with linefeeds, tabs or spaces, 
              special characters or combination of such to draw lines, arrows or underline
              stuff.
            </li>
            <li>
              Input is read from STDIN, printed to STDOUT or STDERR.
            </li>
            <li>
              Variables (arguments) are passed via command line parameters, such as 
              <tt>-l</tt>, <tt>--debug</tt> or <tt>--prefix=/usr/local/</tt>.
            </li>
          </ul>
          This sounds like hacking in the first place, but actually, it's more like a religion. 
          Anyway, that's another story not to be told here, so let's have a start.
          <br/>
          <br/>
          Take, for example, this sample command line application:
          <code><![CDATA[  require('lang.base.php');
  xp::sapi('cli');

  $p= &new ParamString();
  if (2 != $p->count) {   // Always #options +1: values include script's name (#0)
    Console::writeLinef('Usage: %s <name>', $p->value(0));
    exit();
  }
  Console::writeLinef('Hello %s, how are you?', $p->value(1)); ]]></code>
          Calling this application from the command line as <tt>php -q hello.php</tt> 
          (assuming this script is called hello.php),
          it will simply print out <tt>Usage: hello.php &lt;name&gt;</tt> and exit. If a name
          is specified, e.g. <tt>php -q hello.php Timm</tt>, you will se <tt>Hello Timm, how
          are you?</tt> appear on your shell window. Simple enough?
          <br/>
          <br/>
          Now, we'll include support for a help option as seen in most tools (that is, supply
          a <tt>-?</tt> or <tt>--help</tt> in the parameter list of a command line tool and it
          will say how you're supposed to use it). Again, this is simple - modify line no. five
          of the above example to read:
          <code><![CDATA[  if (2 != $p->count || $p->exists('help', '?')) { ]]></code>
          As soon as a user calls <tt>php -q hello.php -?</tt> or <tt>php -q hello.php --help</tt>,
          the tool will now also print out the usage information. Have a look at the 
          <ref type="api:class" link="util.cmd.ParamString"/> class for more information.
          <br/>
          <br/>
          There is actually not much more to know about the basics of command line scripts
          in relation to the XP framework. There are however, some advanced topics
          on more complex tasks and how they're wrapped into classes and objects.
        </text>
        <!-- TBD
        <advanced>
          <ref link="tasks.cmd.stdio">Using the standard I/O streams</ref>
          <ref link="tasks.cmd.cron">Cronjobs</ref>
          <ref link="tasks.cmd.interactive">Interactive tools</ref>
        </advanced>
        -->
      </para>
      
      <!-- web -->
      <para>
        <caption>Web sites</caption>
        <text>
          Web sites is what PHP was made for. In his 
          <ref type="ext" link="http://groups.google.com/groups?selm=3r7pgp%24aa1%40ionews.io.org">announce mail</ref>
          in June of 1995, <NAME> marketed PHP (then called "Personal Home Page Tools"
          as the ideal tool to develop guest books and handle form requests.
          <br/>
          PHP (now called "PHP Hypertext Preprocessor") has since then become much more than
          a "set of cgi scripts". Of course, it is still formidable at handling HTTP request, be
          it as an Apache module or as a CGI. Recently, Yahoo! - being one of the world's busiest
          sites - <ref type="ext" link="http://news.com.com/2100-1023-963937.html?tag=lh">has decided 
          to migrate its scripts to PHP</ref>.
          <br/>
          <br/>
          The XP framework introduces an API called "scriptlets". Scriptlets are the counterpart to 
          Java's Servlets - as one might have guessed from their name. Scriptlets are not a 1:1 
          implementation of Servlets though one might find a lot of similarities!
          <br/>
          Let's have a look at a simple scriptlet:
          <code><![CDATA[  uses('scriptlet.HttpScriplet');

  class HelloScriptlet extends HttpScriplet {

    function doGet(&$request, &$response) {
      // [... Sample abridged for brevity ...]
      if (empty($request->getParam('name'))) {
        $response->write('
          <form action="'.basename($request->getEnvValue('SCRIPT_URI')).'">
            Enter your name here: <input type="text" name="name"/>
            <input type="submit"/>
          </form>
        ');
        return;
      }
      $response->write('Hello '.$request->getParam('name'));
    }
  } ]]></code>
          Of course, this seems, not much more elaborate than embedding PHP
          into HTML. Plus, it's probably more complicated to use all the object-oriented
          "bloat" at first.
          <br/>
          <br/>
          Of course, writing out HTML (with maybe some variable here or there) is easy,
          but you will find that after a while of doing so, it turns out this tactic
          is rather counter-productive. Imagine you want to completely redesign your website:
          Changing the navigation from a frameset to tables, put some links at top, make
          each page contain a link to produce a printer-friendly version of itself.
          <br/>
          You will inadvertedly find yourself going through tons of sourcecode "knowing"
          to much about but effectively producing the same HTML over and over and will
{'fraction_non_alphanumeric': 0.1168145987213705, 'fraction_numerical': 0.006951772081186767, 'mean_word_length': 2.2761285075233837, 'pattern_counts': {'":': 0, '<': 252, '<?xml version=': 2, '>': 272, 'https://': 0, 'lorem ipsum': 0, 'www.': 8, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '801857', 'n_tokens_mistral': 4691, 'n_tokens_neox': 4451, 'n_words': 1714}