cvs: peardoc /en/pyrus/extending packagefile.xml

cellog		Thu Jul  9 17:46:05 2009 UTC

  Modified files:              
    /peardoc/en/pyrus/extending	packagefile.xml 
  Log:
  new docs on usesrole, usestask and compatible tag access
  
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/extending/packagefile.xml?r1=1.5&r2=1.6&diff_format=u
Index: peardoc/en/pyrus/extending/packagefile.xml
diff -u peardoc/en/pyrus/extending/packagefile.xml:1.5 peardoc/en/pyrus/extending/packagefile.xml:1.6
--- peardoc/en/pyrus/extending/packagefile.xml:1.5	Thu Jul  9 17:34:52 2009
+++ peardoc/en/pyrus/extending/packagefile.xml	Thu Jul  9 17:46:05 2009
@@ -41,6 +41,12 @@
     </listitem>
     <listitem>
      <para>
+      To learn about managing custom tasks, roles, and compatible packages, read the section on
+      <link linkend="pyrus.extending.packagefile.custom">usesrole, usestask and compatible</link>.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
       To learn about accessing PECL-specific properties such as configureoption,
       srcpackage, srcuri and providesextension, read the section on
       <link linkend="pyrus.extending.packagefile.pecl">Accessing PECL properties</link>
@@ -602,4 +608,69 @@
    </programlisting>
   </para>
  </section>
+ <section xml:id="pyrus.extending.packagefile.custom">
+  <info><title>Accessing usesrole, usestask and compatible tags</title></info>
+  <para>
+   When declaring that a package.xml uses a custom role or task, this code should
+   be used:
+  </para>
+  <para>
+   <programlisting role="php">
+    <![CDATA[
+<?php
+$package->files['example/file.php'] = array(
+    'role' => 'myrole',
+    'tasks:mytask' => '',
+);
+
+$package->usesrole['myrole']->package('MyRole')->channel('mypear.example.com');
+$package->usestask['mytask']->package('MyTask')->channel('mypear.example.com');
+
+// for uri-based packages:
+$package->usesrole['myrole']->uri('http://my.example.com/MyRole-1.2.3');
+?>
+    ]]>
+   </programlisting>
+  </para>
+  <para>
+   If you are unfamiliar with the <literal>&lt;compatible&gt;</literal> tag,
+   you should first read the documentation on its use
+   <link linkend="guide.developers.package2.compatible">here</link>.  Creating
+   and accessing compatible tags in Pyrus is as easy as:
+  </para>
+  <para>
+   <programlisting role="php">
+    <![CDATA[
+<?php
+$package->compatible['pear.php.net/Archive_Tar']
+        ->min('1.2')
+        ->max('1.3.0')
+        ->exclude('1.2.1', '1.2.2');
+
+// remove a compatibility declaration
+unset($package->compatible['pear.php.net/Archive_Tar']);
+
+// test for existence of compatible declaration
+isset($package->compatible['pear.php.net/Archive_Tar']);
+
+// display info:
+echo $package->compatible['pear.php.net/Archive_Tar']->min;
+
+// iterating over compatible packages
+foreach ($package->compatible as $package => $info) {
+    echo "Package :", $package, "\n";
+    echo "min: ", $info->min, "\n";
+    echo "max: ", $info->max, "\n";
+    if (isset($info->exclude)) {
+        echo "Excludes versions ",
+        foreach ($info->exclude as $version) {
+            echo ' ', $version, "\n";
+        }
+    }
+}
+?>
+    ]]>
+   </programlisting>
+  </para>
+ </section>
 </section>