svn: pear/peardoc/trunk/en/pyrus/

Added: pear/peardoc/trunk/en/pyrus/extending/configuration.xml
===================================================================
--- pear/peardoc/trunk/en/pyrus/extending/configuration.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/pyrus/extending/configuration.xml	2009-07-14 03:02:46 UTC (rev 284048)
@@ -0,0 +1,152 @@
+<?xml version="1.0" encoding="utf-8"?>
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="lillet"
+         xml:id="pyrus.extending.configuration">
+ <info><title>Pyrus's configuration API</title></info>
+
+ <section xml:id="pyrus.extending.configuration.intro">
+  <info><title>Introduction</title></info>
+  <para>
+   This documentation describes how to use Pyrus's public class API to access
+   configuration values.  Before reading further, you should be familiar
+   with the documentation on Pyrus's <link linkend="pyrus.configuration">configuration</link>.
+  </para>
+  <para>
+   Pyrus's configuration is controlled by the <literal>pear2\Pyrus\Config</literal>
+   class, which is implemented as a multiton mapping Pyrus installation location
+   to a configuration object.  In addition, the current configuration (most
+   recently instantiated) is also accessible to create configuration-agnostic
+   functionality.
+  </para>
+  <para>
+   Configuration variables are accessed by referring to them as class
+   properties.  Here is an example requesting the <literal>doc_dir</literal>
+   configuration variable, and setting the <literal>test_dir</literal>
+   configuration variable:
+  </para>
+  <para>
+   <programlisting role="php">
+    <![CDATA[
+<?php
+$docdir = pear2\Pyrus\Config::current()->doc_dir;
+pear2\Pyrus\Config::current()->test_dir = '/path/to/tests';
+?>
+    ]]>
+   </programlisting>
+  </para>
+  <para>
+   The user configuration in use is also accessible from each configuration
+   in the same manner as the installation-specific configuration.  Here is
+   an example requesting <literal>preferred_state</literal> and setting
+   <literal>verbose</literal>:
+  </para>
+  <para>
+   <programlisting role="php">
+    <![CDATA[
+<?php
+$pref = pear2\Pyrus\Config::current()->preferred_state;
+pear2\Pyrus\Config::current()->verbose = 3;
+?>
+    ]]>
+   </programlisting>
+  </para>
+ </section>
+ <section xml:id="pyrus.extending.configuration.special">
+  <title>Special variables available</title>
+  <para>
+   In addition to the configuration variables, Pyrus also defines a few
+   other values that are available, and cannot be used as the names
+   of custom configuration variables:
+   <itemizedlist>
+    <listitem>
+     <para>
+      <literal>path</literal> - the complete <constant>PATH_SEPARATOR</constant>
+      separated list of cascading directories this configuration represents.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>location</literal> - the writable pyrus installation this configuration
+      represents
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>registry</literal> - the registry corresponding to the configuration
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>pluginregistry</literal> - the registry corresponding to the
+      location that <link linkend="pyrus.plugins">plugins</link> are installed
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>channelregistry</literal> - the channel registry corresponding to
+      the configuration
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>systemvars</literal> - an array of names of system configuration
+      variables, built-in and custom
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>uservars</literal> - an array of names of user configuration
+      variables, built-in and custom
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>channelvars</literal> - an array of channel-specific configuration
+      variables, built-in and custom
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>mainsystemvars</literal> - an array of names of built-in
+      system variables
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>mainuservars</literal> - an array of names of built-in user
+      variables
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>mainchannelvars</literal> - an array of names of built-in
+      channel-specific variables
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>userfile</literal> - path to the user configuration file in use
+      by this configuration.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>customsystemvars</literal> - an array of names of custom
+      system variables
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>customuservars</literal> - an array of names of custom user
+      variables
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <literal>customchannelvars</literal> - an array of names of custom
+      channel-specific variables
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+ </section>
+</section>


Property changes on: pear/peardoc/trunk/en/pyrus/extending/configuration.xml
___________________________________________________________________
Added: svn:keywords
   + Id Revision

Added: pear/peardoc/trunk/en/pyrus/extending/installation.xml
===================================================================
--- pear/peardoc/trunk/en/pyrus/extending/installation.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/pyrus/extending/installation.xml	2009-07-14 03:02:46 UTC (rev 284048)
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="utf-8"?>
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="lillet"
+         xml:id="pyrus.extending.installation">
+ <info><title>Leveraging Pyrus's installation API</title></info>
+
+ <section xml:id="pyrus.extending.installation.intro">
+  <info><title>Introduction</title></info>
+  <para>
+   Pyrus provides a very simple API for performing installation tasks.  This
+   API begins with the ability to pass any packagename that can be
+   specified on the command-line to a <literal>pear2\Pyrus\Package</literal>
+   object:
+  </para>
+  <para>
+   <programlisting role="php">
+    <![CDATA[
+<?php
+// examples of the range of valid package names
+$package = new \pear2\Pyrus\Package('package.xml');
+$package = new \pear2\Pyrus\Package('/full/path/to/package.xml');
+$package = new \pear2\Pyrus\Package('Package-1.2.3.tgz');
+$package = new \pear2\Pyrus\Package('/full/path/to/Package-1.2.3.zip');
+$package = new \pear2\Pyrus\Package('RemotePackage');
+$package = new \pear2\Pyrus\Package('RemotePackage-alpha');
+$package = new \pear2\Pyrus\Package('RemotePackage-1.2.3');
+$package = new \pear2\Pyrus\Package('channelname/RemotePackage');
+$package = new \pear2\Pyrus\Package('http://example.com/RemotePackage-1.2.3.phar');
+?>
+    ]]>
+   </programlisting>
+  </para>
+  <para>
+   If there is a problem with the package name as passed to the constructor,
+   an exception is thrown.  This can be any of a wide variety of exceptions
+   ranging from a <literal>pear2\Pyrus\PackageFile\Exception</literal> for
+   invalid package.xml, a <literal>pear2\Pyrus\Package\Exception</literal> for
+   higher-level errors (file does not exist, invalid abstract package name),
+   a <literal>pear2\Pyrus\Package\InstalledException</literal> if an abstract
+   remote package was requested and a newer version is installed, and
+   a <literal>pear2\Pyrus\Channel\Exception</literal> if any problems with
+   retrieving remote REST information occur.  Also possible are
+   <literal>pear2\Pyrus\Package\Phar\Exception</literal> for errors relating
+   to local <literal>tar</literal>, <literal>tgz</literal>, <literal>zip</literal>
+   or <literal>phar</literal> archives.
+  </para>
+ </section>
+ <section xml:id="pyrus.extending.installation.install">
+  <info><title>Installing and Uninstalling packages</title></info>
+  <para>
+   Once you have a valid package object, installation is very simple.  Pyrus
+   conducts all installation activities within a transaction, meaning that all
+   changes are applied nearly simultaneously, and any failure mid-transaction
+   does not leave an invalid installation lying around.
+  </para>
+  <para>
+   <programlisting role="php">
+    <![CDATA[
+<?php
+// import the class names into the current scope
+// this step is optional, you can also use the full class names
+// like pear2\Pyrus\Installer::begin()
+use pear2\Pyrus\Installer as Installer,
+    pear2\Pyrus\Package as Package;
+
+try {
+    $p1 = new Package('package.xml');
+    $p2 = new Package('Package.tgz');
+    $p3 = new Package('pear2/RemotePackage');
+
+    // here is the meat of the installation transaction
+    Installer::begin();
+
+    Installer::prepare($p1);
+    Installer::prepare($p2);
+    Installer::prepare($p3);
+
+    Installer::commit();
+} catch (\Exception $e) {
+    echo "Install failed\n";
+}
+?>
+    ]]>
+   </programlisting>
+  </para>
+  <para>
+   Uninstalling a package is even simpler:
+  </para>
+  <para>
+   <programlisting role="php">
+    <![CDATA[
+<?php
+// import the class names into the current scope
+// this step is optional, you can also use the full class names
+// like pear2\Pyrus\Uninstaller::begin()
+use pear2\Pyrus\Uninstaller as Uninstaller;
+
+try {
+    $p1 = new Package('package.xml');
+    $p2 = new Package('Package.tgz');
+    $p3 = new Package('pear2/RemotePackage');
+
+    // here is the meat of the installation transaction
+    Uninstaller::begin();
+
+    Uninstaller::prepare('pear2.php.net/Package1');
+    Uninstaller::prepare('pear.php.net/Package');
+    Uninstaller::prepare('__uri/Package');
+
+    Uninstaller::commit();
+} catch (\Exception $e) {
+    echo "Uninstall failed\n";
+}
+?>
+    ]]>
+   </programlisting>
+  </para>
+ </section>
+</section>


Property changes on: pear/peardoc/trunk/en/pyrus/extending/installation.xml
___________________________________________________________________
Added: svn:keywords
   + Id Revision

Modified: pear/peardoc/trunk/en/pyrus/extending.xml
===================================================================
--- pear/peardoc/trunk/en/pyrus/extending.xml	2009-07-14 02:40:32 UTC (rev 284047)
+++ pear/peardoc/trunk/en/pyrus/extending.xml	2009-07-14 03:02:46 UTC (rev 284048)
@@ -20,4 +20,6 @@
   </para>

   &pyrus.extending.packagefile;
+  &pyrus.extending.configuration;
+  &pyrus.extending.installation;
  </chapter>