svn commit: r1737642 [2/7] - in /lucy/site/trunk/content/docs: 0.4.0/ 0.4.0/perl/ 0.4.0/perl/Lucy/ 0.4.0/perl/Lucy/Analysis/ 0.4.0/perl/Lucy/Docs/ 0.4.0/perl/Lucy/Docs/Cookbook/ 0.4.0/perl/Lucy/Docs/Tutorial/ 0.4.0/perl/Lucy/Document/ 0.4.0/perl/Lucy/H...

[nw...@apache.org]

Added: lucy/site/trunk/content/docs/perl/Clownfish.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,137 @@
+Title: Clownfish – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish - Apache Clownfish symbiotic object system</p>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<p>The Apache Clownfish &#8220;symbiotic&#8221; object system pairs with &#8220;host&#8221; programming language environments and facilitates the development of high performance language extensions.</p>
+
+<h3><a class='u'
+name="Features"
+>Features</a></h3>
+
+<ul>
+<li>Support for multiple host languages.</li>
+
+<li>Support for stand-alone C libraries and executables.</li>
+
+<li>Subclassing and method overriding from the host language.</li>
+
+<li>Support for host language idioms like named parameters or default argument values.</li>
+
+<li>Highly performant object system with lazy creation of host language objects.</li>
+
+<li>Runtime with classes for commonly used data structures like strings,
+dynamic arrays and hash tables.</li>
+
+<li>Guaranteed ABI stability when adding or reordering methods or instance variables.</li>
+
+<li>Modularity.</li>
+
+<li>Introspection.</li>
+
+<li>Documentation generator.</li>
+</ul>
+
+<h3><a class='u'
+name="Planned_features"
+>Planned features</a></h3>
+
+<ul>
+<li>Support for more host languages.</li>
+
+<li>Support for interfaces.</li>
+</ul>
+
+<h3><a class='u'
+name="Overview"
+>Overview</a></h3>
+
+<p>Clownfish consists of two parts,
+the Clownfish compiler &#8220;CFC&#8221; and the Clownfish runtime.
+CFC is a code generator that creates C header files,
+host language bindings,
+initialization code and documentation from a set of Clownfish header files.
+The generated code is compiled with other project code and linked with the Clownfish runtime.</p>
+
+<p>Clownfish header files have a <code>.cfh</code> extension and define classes used within the Clownfish object system.
+The object system is implemented in C and supports single inheritance and virtual method dispatch.
+CFC creates a C header file from each Clownfish header containing the C interface to Clownfish objects.
+Functions and methods of objects are implemented in normal C source files.
+Beyond the C level,
+CFC can generate host language bindings to make Clownfish objects accessible from other programming languages.
+The compiler also creates class documentation in various formats from comments contained in Clownfish header files and standalone Markdown files.</p>
+
+<p>The Clownfish runtime provides:</p>
+
+<ul>
+<li>The <a href="./Clownfish/Obj.html" class="podlinkpod"
+>Obj</a> class which is the root of the class hierarchy.</li>
+
+<li>Core data types like <a href="./Clownfish/String.html" class="podlinkpod"
+>strings</a>,
+<a href="./Clownfish/Vector.html" class="podlinkpod"
+>dynamic arrays</a>,
+and <a href="./Clownfish/Hash.html" class="podlinkpod"
+>hashes</a>.</li>
+
+<li>The <a href="./Clownfish/Class.html" class="podlinkpod"
+>Class</a> metaclass.</li>
+
+<li>Some helper classes.</li>
+</ul>
+
+<h3><a class='u'
+name="Host_language_support"
+>Host language support</a></h3>
+
+<p>Bindings for the following hosts are under development:</p>
+
+<ul>
+<li>C (feature-complete)</li>
+
+<li>Go (experimental)</li>
+
+<li>Perl 5 (feature-complete)</li>
+
+<li>Python 3 / CPython (nascent)</li>
+
+<li>Ruby / MRI (nascent)</li>
+</ul>
+
+<h3><a class='u'
+name="Help_wanted"
+>Help wanted</a></h3>
+
+<p>The target audience for the current release of Clownfish is developers.
+Clownfish is developed by the Apache Lucy community,
+where it is used to provide host language bindings for the Lucy search engine library; we expect that as Clownfish matures it will eventually spin off as an independent project.
+If you would like to contribute to Clownfish,
+please join the <a href="http://lucy.apache.org/mailing_lists" class="podlinkurl"
+>Lucy developers mailing list</a>.</p>
+
+<h3><a class='u'
+name="Documentation"
+>Documentation</a></h3>
+
+<ul>
+<li><a href="./Clownfish/Docs/ClassIntro.html" class="podlinkpod"
+>Working with Clownfish classes</a></li>
+
+<li><a href="./Clownfish/Docs/BuildingProjects.html" class="podlinkpod"
+>Building Clownfish projects in C environments</a></li>
+
+<li><a href="./Clownfish/Docs/WritingClasses.html" class="podlinkpod"
+>Writing Clownfish classes</a></li>
+</ul>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/Blob.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/Blob.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/Blob.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/Blob.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,78 @@
+Title: Clownfish::Blob – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::Blob - Immutable buffer holding arbitrary bytes.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>my $blob = Clownfish::Blob-&#62;new($byte_string);
+my $byte_string = $blob-&#62;to_perl;</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<h2><a class='u'
+name="CONSTRUCTORS"
+>CONSTRUCTORS</a></h2>
+
+<h3><a class='u'
+name="new"
+>new</a></h3>
+
+<pre>my $blob = Clownfish::Blob-&#62;new($byte_string);</pre>
+
+<p>Create a Blob containing the passed-in bytes.</p>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="get_size"
+>get_size</a></h3>
+
+<pre>my $int = $blob-&#62;get_size();</pre>
+
+<p>Return the number of bytes held by the Blob.</p>
+
+<h3><a class='u'
+name="compare_to"
+>compare_to</a></h3>
+
+<pre>my $int = $blob-&#62;compare_to($other);</pre>
+
+<p>Indicate whether one Blob is less than,
+equal to,
+or greater than another.
+The byte contents of the Blobs are compared lexicographically.
+Throws an exception if <code>other</code> is not a Blob.</p>
+
+<p>Returns: 0 if the Blobs are equal,
+a negative number if <code>self</code> is less than <code>other</code>,
+and a positive number if <code>self</code> is greater than <code>other</code>.</p>
+
+<h3><a class='u'
+name="clone"
+>clone</a></h3>
+
+<pre>my $result = $blob-&#62;clone();</pre>
+
+<p>Return a clone of the object.</p>
+
+<h2><a class='u'
+name="INHERITANCE"
+>INHERITANCE</a></h2>
+
+<p>Clownfish::Blob isa <a href="../Clownfish/Obj.html" class="podlinkpod"
+>Clownfish::Obj</a>.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/Boolean.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/Boolean.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/Boolean.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/Boolean.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,70 @@
+Title: Clownfish::Boolean – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::Boolean - Boolean type.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>use Clownfish::Boolean qw( $true_singleton $false_singleton );
+
+my $bool = Clownfish::Boolean-&#62;singleton($truth_value);
+my $truth_value = $bool-&#62;get_value;
+
+if ($bool-&#62;equals($true_singleton)) {
+    print &#34;true\n&#34;;
+}</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<p>There are only two singleton instances of this class: <code>$true_singleton</code> and <code>$false_singleton</code> which are exported on demand.</p>
+
+<h2><a class='u'
+name="CONSTRUCTORS"
+>CONSTRUCTORS</a></h2>
+
+<h3><a class='u'
+name="singleton"
+>singleton</a></h3>
+
+<pre>my $bool = Clownfish::Boolean-&#62;singleton($truth_value);</pre>
+
+<p>Return either <code>$true_singleton</code> or <code>$false_singleton</code> depending on the supplied value.</p>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="get_value"
+>get_value</a></h3>
+
+<pre>my $bool = $boolean-&#62;get_value();</pre>
+
+<p>Return the value of the Boolean.</p>
+
+<h3><a class='u'
+name="clone"
+>clone</a></h3>
+
+<pre>my $result = $boolean-&#62;clone();</pre>
+
+<p>Return a clone of the object.</p>
+
+<h2><a class='u'
+name="INHERITANCE"
+>INHERITANCE</a></h2>
+
+<p>Clownfish::Boolean isa <a href="../Clownfish/Obj.html" class="podlinkpod"
+>Clownfish::Obj</a>.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/ByteBuf.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/ByteBuf.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/ByteBuf.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/ByteBuf.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,132 @@
+Title: Clownfish::ByteBuf – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::ByteBuf - Growable buffer holding arbitrary bytes.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>my $buf = Clownfish::ByteBuf-&#62;new($byte_string);
+my $byte_string = $buf-&#62;to_perl;</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<h2><a class='u'
+name="CONSTRUCTORS"
+>CONSTRUCTORS</a></h2>
+
+<h3><a class='u'
+name="new"
+>new</a></h3>
+
+<pre>my $buf = Clownfish::ByteBuf-&#62;new($byte_string);</pre>
+
+<p>Create a ByteBuf containing the passed-in bytes.</p>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="set_size"
+>set_size</a></h3>
+
+<pre>$byte_buf-&#62;set_size($size);</pre>
+
+<p>Resize the ByteBuf to <code>size</code>.
+If greater than the object&#8217;s capacity,
+throws an error.</p>
+
+<h3><a class='u'
+name="get_size"
+>get_size</a></h3>
+
+<pre>my $int = $byte_buf-&#62;get_size();</pre>
+
+<p>Return the size of the ByteBuf in bytes.</p>
+
+<h3><a class='u'
+name="get_capacity"
+>get_capacity</a></h3>
+
+<pre>my $int = $byte_buf-&#62;get_capacity();</pre>
+
+<p>Return the number of bytes in the ByteBuf&#8217;s allocation.</p>
+
+<h3><a class='u'
+name="cat"
+>cat</a></h3>
+
+<pre>$byte_buf-&#62;cat($blob);</pre>
+
+<p>Concatenate the contents of <a href="../Clownfish/Blob.html" class="podlinkpod"
+>Blob</a> <code>blob</code> onto the end of the original ByteBuf.
+Allocate more memory as needed.</p>
+
+<h3><a class='u'
+name="yield_blob"
+>yield_blob</a></h3>
+
+<pre>my $blob = $byte_buf-&#62;yield_blob();</pre>
+
+<p>Return the content of the ByteBuf as <a href="../Clownfish/Blob.html" class="podlinkpod"
+>Blob</a> and clear the ByteBuf.</p>
+
+<h3><a class='u'
+name="utf8_to_string"
+>utf8_to_string</a></h3>
+
+<pre>my $string = $byte_buf-&#62;utf8_to_string();</pre>
+
+<p>Return a String which holds a copy of the UTF-8 character data in the ByteBuf after checking for validity.</p>
+
+<h3><a class='u'
+name="trusted_utf8_to_string"
+>trusted_utf8_to_string</a></h3>
+
+<pre>my $string = $byte_buf-&#62;trusted_utf8_to_string();</pre>
+
+<p>Return a String which holds a copy of the UTF-8 character data in the ByteBuf,
+skipping validity checks.</p>
+
+<h3><a class='u'
+name="compare_to"
+>compare_to</a></h3>
+
+<pre>my $int = $byte_buf-&#62;compare_to($other);</pre>
+
+<p>Indicate whether one ByteBuf is less than,
+equal to,
+or greater than another.
+The byte contents of the ByteBufs are compared lexicographically.
+Throws an exception if <code>other</code> is not a ByteBuf.</p>
+
+<p>Returns: 0 if the ByteBufs are equal,
+a negative number if <code>self</code> is less than <code>other</code>,
+and a positive number if <code>self</code> is greater than <code>other</code>.</p>
+
+<h3><a class='u'
+name="clone"
+>clone</a></h3>
+
+<pre>my $result = $byte_buf-&#62;clone();</pre>
+
+<p>Return a clone of the object.</p>
+
+<h2><a class='u'
+name="INHERITANCE"
+>INHERITANCE</a></h2>
+
+<p>Clownfish::ByteBuf isa <a href="../Clownfish/Obj.html" class="podlinkpod"
+>Clownfish::Obj</a>.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/CharBuf.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/CharBuf.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/CharBuf.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/CharBuf.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,129 @@
+Title: Clownfish::CharBuf – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::CharBuf - Growable buffer holding Unicode characters.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>my $buf = Clownfish::CharBuf-&#62;new;
+$buf-&#62;cat(&#39;abc&#39;);
+$buf-&#62;cat_char(ord(&#34;\n&#34;));
+print $buf-&#62;to_string;</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<h2><a class='u'
+name="CONSTRUCTORS"
+>CONSTRUCTORS</a></h2>
+
+<h3><a class='u'
+name="new"
+>new</a></h3>
+
+<pre>my $char_buf = Clownfish::CharBuf-&#62;new(
+    capacity =&#62; $capacity  # default: 0
+);</pre>
+
+<p>Return a new CharBuf.</p>
+
+<ul>
+<li><b>capacity</b> - Initial minimum capacity of the CharBuf,
+in bytes.</li>
+</ul>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="cat"
+>cat</a></h3>
+
+<pre>$char_buf-&#62;cat($string);</pre>
+
+<p>Concatenate the contents of <a href="../Clownfish/String.html" class="podlinkpod"
+>String</a> <code>string</code> onto the end of the caller.</p>
+
+<ul>
+<li><b>string</b> - The String to concatenate.</li>
+</ul>
+
+<h3><a class='u'
+name="cat_char"
+>cat_char</a></h3>
+
+<pre>$char_buf-&#62;cat_char($code_point);</pre>
+
+<p>Concatenate one Unicode character onto the end of the CharBuf.</p>
+
+<ul>
+<li><b>code_point</b> - The code point of the Unicode character.</li>
+</ul>
+
+<h3><a class='u'
+name="grow"
+>grow</a></h3>
+
+<pre>$char_buf-&#62;grow($capacity);</pre>
+
+<p>Assign more memory to the CharBuf,
+if it doesn&#8217;t already have enough room to hold a string of <code>size</code> bytes.
+Cannot shrink the allocation.</p>
+
+<ul>
+<li><b>capacity</b> - The new minimum capacity of the ByteBuf.</li>
+</ul>
+
+<h3><a class='u'
+name="clear"
+>clear</a></h3>
+
+<pre>$char_buf-&#62;clear();</pre>
+
+<p>Clear the CharBuf.</p>
+
+<h3><a class='u'
+name="get_size"
+>get_size</a></h3>
+
+<pre>my $int = $char_buf-&#62;get_size();</pre>
+
+<p>Return the size of the CharBuf&#8217;s content in bytes.</p>
+
+<h3><a class='u'
+name="clone"
+>clone</a></h3>
+
+<pre>my $result = $char_buf-&#62;clone();</pre>
+
+<p>Return a clone of the object.</p>
+
+<h3><a class='u'
+name="yield_string"
+>yield_string</a></h3>
+
+<pre>my $string = $char_buf-&#62;yield_string();</pre>
+
+<p>Return the content of the CharBuf as <a href="../Clownfish/String.html" class="podlinkpod"
+>String</a> and clear the CharBuf.
+This is more efficient than <a href="../Clownfish/Obj.html#to_string" class="podlinkpod"
+>to_string()</a>.</p>
+
+<h2><a class='u'
+name="INHERITANCE"
+>INHERITANCE</a></h2>
+
+<p>Clownfish::CharBuf isa <a href="../Clownfish/Obj.html" class="podlinkpod"
+>Clownfish::Obj</a>.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/Class.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/Class.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/Class.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/Class.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,105 @@
+Title: Clownfish::Class – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::Class - Class.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>my $class = Clownfish::Class-&#62;fetch_class(&#39;Foo::Bar&#39;);
+my $subclass = Clownfish::Class-&#62;singleton(&#39;Foo::Bar::Jr&#39;, $class);</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<p>Classes are first-class objects in Clownfish.
+Class objects are instances of Clownfish::Class.</p>
+
+<h2><a class='u'
+name="CONSTRUCTORS"
+>CONSTRUCTORS</a></h2>
+
+<h3><a class='u'
+name="fetch_class"
+>fetch_class</a></h3>
+
+<pre>my $class = Clownfish::Class-&#62;fetch_class($class_name);</pre>
+
+<p>Find a registered class.
+May return undef if the class is not registered.</p>
+
+<h3><a class='u'
+name="singleton"
+>singleton</a></h3>
+
+<pre>my $class = Clownfish::Class-&#62;singleton(
+    class_name =&#62; $class_name  # required
+    parent     =&#62; $parent      # required
+);</pre>
+
+<p>Return a singleton.
+If a Class can be found in the registry based on the supplied class name,
+it will be returned.
+Otherwise,
+a new Class will be created using <code>parent</code> as a base.</p>
+
+<p>If <code>parent</code> is undef,
+an attempt will be made to find it.
+If the attempt fails,
+an error will result.</p>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="make_obj"
+>make_obj</a></h3>
+
+<pre>my $obj = $class-&#62;make_obj();</pre>
+
+<p>Create an empty object of the type defined by the Class: allocate,
+assign its class and give it an initial refcount of 1.
+The caller is responsible for initialization.</p>
+
+<h3><a class='u'
+name="get_name"
+>get_name</a></h3>
+
+<pre>my $string = $class-&#62;get_name();</pre>
+
+<p>Return the name of the class.</p>
+
+<h3><a class='u'
+name="get_parent"
+>get_parent</a></h3>
+
+<pre>my $result = $class-&#62;get_parent();</pre>
+
+<p>Return the parent class,
+or undef for a root of the class hierarchy.</p>
+
+<h3><a class='u'
+name="get_obj_alloc_size"
+>get_obj_alloc_size</a></h3>
+
+<pre>my $int = $class-&#62;get_obj_alloc_size();</pre>
+
+<p>Return the number of bytes needed to hold an instance of the class.</p>
+
+<h2><a class='u'
+name="INHERITANCE"
+>INHERITANCE</a></h2>
+
+<p>Clownfish::Class isa <a href="../Clownfish/Obj.html" class="podlinkpod"
+>Clownfish::Obj</a>.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/Docs/BuildingProjects.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/Docs/BuildingProjects.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/Docs/BuildingProjects.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/Docs/BuildingProjects.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,154 @@
+Title: Clownfish::Docs::BuildingProjects – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::Docs::BuildingProjects - Building Apache Clownfish projects in C environments</p>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<p>The following steps are required to build a project that uses Apache Clownfish:</p>
+
+<ul>
+<li>Run the <code>cfc</code> command-line application (Clownfish compiler) to generate C headers,
+C source files,
+and documentation.</li>
+
+<li>Include the C headers generated by the Clownfish compiler in your own code to <a href="../../Clownfish/Docs/ClassIntro.html" class="podlinkpod"
+>work with Clownfish objects</a>.</li>
+
+<li>Compile an additional C source file generated by CFC.</li>
+
+<li>Link your object code,
+the object code from the generated file,
+and the Clownfish runtime library.</li>
+</ul>
+
+<h3><a class='u'
+name="Running_cfc"
+>Running cfc</a></h3>
+
+<pre>cfc [--source=&#60;dir&#62;] [--include=&#60;dir&#62;] [--parcel=&#60;name&#62;]
+    --dest=&#60;dir&#62;
+    [--header=&#60;file&#62;] [--footer=&#60;file&#62;]</pre>
+
+<h4><a class='u'
+name="(8211)source"
+>&#8211;source</a></h4>
+
+<p>Every <code>--source</code> argument adds a directory to the list of source directories to search for source parcels.
+For every source parcel found,
+CFC generates C headers,
+a C source file,
+and documentation.</p>
+
+<p>The source directories are scanned for Clownfish parcel definitions (<code>.cfp</code>),
+Clownfish headers (<code>.cfh</code>),
+and standalone documentation in Markdown format (<code>.md</code>).</p>
+
+<p>This option may be specified multiple times.</p>
+
+<h4><a class='u'
+name="(8211)include"
+>&#8211;include</a></h4>
+
+<p>Every <code>--include</code> argument adds a directory to the list of include directories.
+CFC generates C headers for parcels from an include directory only if they&#8217;re required by a source parcel or if they&#8217;re specified with the <code>--parcel</code> option.
+Only C headers are generated for included parcels,
+no C source code or documentation.</p>
+
+<p>The include directories are scanned for Clownfish parcel definitions (<code>.cfp</code>) and Clownfish headers (<code>.cfh</code>).</p>
+
+<p>After the directories specified on the command-line,
+the following directories are processed:</p>
+
+<ul>
+<li>Directories from the environment variable <code>CLOWNFISH_INCLUDE</code>.
+This variable contains a colon-separated list of directories.</li>
+
+<li>On UNIX-like systems <code>/usr/local/share/clownfish/include</code> and <code>/usr/share/clownfish/include</code>.</li>
+</ul>
+
+<p>This option may be specified multiple times.</p>
+
+<h4><a class='u'
+name="(8211)parcel"
+>&#8211;parcel</a></h4>
+
+<p>Adds a parcel to the list of prerequisite parcels to make sure that its C headers are generated.
+This is useful when running without the <code>--source</code> option.
+For example,
+a project that doesn&#8217;t define its own Clownfish classes can generate the C headers for the Clownfish runtime with:</p>
+
+<pre>cfc --parcel=Clownfish --dest=autogen</pre>
+
+<p>This option may be specified multiple times.</p>
+
+<h4><a class='u'
+name="(8211)dest"
+>&#8211;dest</a></h4>
+
+<p>The destination directory for generated files.
+By convention,
+the name <code>autogen</code> is used.</p>
+
+<p>CFC creates the following subdirectories in the destination directory:</p>
+
+<ul>
+<li><code>include</code> contains generated C headers.</li>
+
+<li><code>sources</code> contains generated C source files.</li>
+
+<li><code>man</code> contains generated man pages.</li>
+
+<li><code>share/doc/clownfish</code> contains generated HTML documentation.</li>
+</ul>
+
+<p>This option is required.</p>
+
+<h4><a class='u'
+name="(8211)header"
+>&#8211;header</a></h4>
+
+<p>Specifies a file whose contents are added as a comment on top of each generated file.</p>
+
+<h4><a class='u'
+name="(8211)footer"
+>&#8211;footer</a></h4>
+
+<p>Specifies a file whose contents are added as a comment on the bottom of each generated file.</p>
+
+<h3><a class='u'
+name="Including_the_generated_C_headers"
+>Including the generated C headers</a></h3>
+
+<p>The C header files generated with <code>cfc</code> can be found in <code>autogen/include</code>.
+You should add this directory to your compiler&#8217;s search path,
+for example using <code>-Iautogen/include</code> under GCC.</p>
+
+<p>One C header file is generated for every Clownfish header (.cfh) file.
+C code that makes use of a class defined in the .cfh file must include the respective C header.
+The Clownfish compiler also creates a few other internal C header files.</p>
+
+<h3><a class='u'
+name="Compiling_the_generated_source_files"
+>Compiling the generated source files</a></h3>
+
+<p><code>cfc</code> creates one source file for every parcel in <code>autogen/sources/{parcel_nick}_parcel.c</code>.
+These files must be compiled with <code>autogen/include</code> added to the header search path.</p>
+
+<h3><a class='u'
+name="Linking"
+>Linking</a></h3>
+
+<p>When linking,
+add the object files of the CFC-generated code created in the previous step.
+You must also link the shared library of the Clownfish runtime (<code>-lcfish</code> under GCC).</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/Docs/ClassIntro.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/Docs/ClassIntro.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/Docs/ClassIntro.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/Docs/ClassIntro.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,132 @@
+Title: Clownfish::Docs::ClassIntro – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::Docs::ClassIntro - Working with Apache Clownfish classes in C</p>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<h3><a class='u'
+name="Inititalizing_Clownfish_parcels"
+>Inititalizing Clownfish parcels</a></h3>
+
+<p>Every Clownfish parcel must be initialized before it is used.
+The initialization function is named <code>{parcel_nick}_bootstrap_parcel</code> and takes no arguments.</p>
+
+<p>Example:</p>
+
+<pre>cfish_bootstrap_parcel();</pre>
+
+<h3><a class='u'
+name="Including_the_generated_header_file"
+>Including the generated header file</a></h3>
+
+<p>To use Clownfish classes from C code,
+the header file generated by the Clownfish compiler must be included.
+The name of the C header is derived from the name of the Clownfish <code>.cfh</code> header.
+It can also be found in the class documentation.</p>
+
+<p>Typically,
+the &#8220;short name macro&#8221; should be defined before including a Clownfish header.
+Its name is derived from the parcel nickname and has the form <code>{PARCEL_NICK}_USE_SHORT_NAMES</code>.
+If the short name macro is in effect,
+you don&#8217;t have to worry about parcel prefixes.</p>
+
+<p>Example:</p>
+
+<pre>#define CFISH_USE_SHORT_NAMES
+
+#include &#60;Clownfish/String.h&#62;
+#include &#60;Clownfish/Vector.h&#62;</pre>
+
+<h3><a class='u'
+name="Function_and_method_prefixes"
+>Function and method prefixes</a></h3>
+
+<p>Clownfish classes can have a &#8220;nickname&#8221; &#8211; a shorter version of the class name that is used for function and method prefixes.
+The nickname can be found in the class documentation.</p>
+
+<p>For example the String class has the nickname <code>Str</code>.</p>
+
+<h3><a class='u'
+name="Creating_objects"
+>Creating objects</a></h3>
+
+<p>A Clownfish object is an opaque struct referenced by pointer.</p>
+
+<p>Most classes come with one or more constructors.
+On the C level,
+a constructor is simply an &#8220;inert&#8221; function of a class that returns a new object.
+In Clownfish parlance,
+an inert function is any function in a class that isn&#8217;t a method,
+similar to static methods in Java or static member functions in C++.</p>
+
+<p>Example:</p>
+
+<pre>// Notice the use of nickname &#34;Str&#34; in the constructor prefix.
+String *name = Str_newf(&#34;%s %s&#34;, first, last);</pre>
+
+<h3><a class='u'
+name="Calling_methods"
+>Calling methods</a></h3>
+
+<p>Calling methods is straightforward.
+The invocant is always passed as first argument.</p>
+
+<pre>// Notice the use of nickname &#34;Str&#34; in the method prefix.
+size_t len = Str_Length(name);</pre>
+
+<p>Method names always start with an uppercase letter.</p>
+
+<h3><a class='u'
+name="Memory_management"
+>Memory management</a></h3>
+
+<p>Clownfish uses reference counting to manage memory.
+Constructors,
+but also some methods,
+return an &#8220;incremented&#8221; object.
+If you&#8217;re done with an incremented object,
+you must decrease its reference count to avoid leaking memory.
+Use the <code>DECREF</code> macro to release an object:</p>
+
+<pre>DECREF(name);</pre>
+
+<p>Some other methods return non-incremented objects.
+If you want to retain a reference to such an object,
+you must increase its reference count using the <code>INCREF</code> macro to make sure it won&#8217;t be destroyed too early:</p>
+
+<pre>obj = INCREF(obj);</pre>
+
+<p>This invocation of INCREF must be matched by a DECREF when you&#8217;re done with the object.</p>
+
+<p>Some methods,
+for example in container classes,
+take &#8220;decremented&#8221; objects as arguments.
+From the caller&#8217;s perspective,
+passing a decremented argument is equivalent to passing a non-decremented argument and calling DECREF afterwards.
+Typically,
+this avoids a call to DECREF in the calling code.
+But sometimes,
+it must be compensated with an INCREF.</p>
+
+<h3><a class='u'
+name="Further_reading"
+>Further reading</a></h3>
+
+<ul>
+<li><a href="../../Clownfish/Docs/BuildingProjects.html" class="podlinkpod"
+>Building Clownfish projects in C environments</a></li>
+
+<li><a href="../../Clownfish/Docs/WritingClasses.html" class="podlinkpod"
+>Writing Clownfish classes</a></li>
+</ul>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/Docs/WritingClasses.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/Docs/WritingClasses.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/Docs/WritingClasses.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/Docs/WritingClasses.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,641 @@
+Title: Clownfish::Docs::WritingClasses – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::Docs::WritingClasses - Writing Apache Clownfish classes</p>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<h3><a class='u'
+name="Parcels"
+>Parcels</a></h3>
+
+<p>Every Clownfish class belongs to a Clownfish parcel.
+Parcels are used for namespacing and versioning.
+Information about parcels is stored in <code>.cfp</code> files which contain a JSON hash with the following keys:</p>
+
+<ul>
+<li><b>name:</b> The parcel&#8217;s name.
+It must contain only letters.</li>
+
+<li><b>nickname:</b> A short nickname.
+It must contain only letters.
+This nickname,
+followed by an underscore,
+is used to prefix generated C symbols and macros.
+Depending on the kind of symbol,
+a lowercase or uppercase prefix will be used.</li>
+
+<li><b>version:</b> A version specifier of the following form (without whitespace):
+<pre>version-specifier = &#34;v&#34; version-number
+version-number = digit+ | digit+ &#34;.&#34; version-number</pre>
+</li>
+
+<li><b>prerequisites:</b> A hash containing the prerequisite parcels.
+The hash keys are the parcel names.
+The values contain the minimum required version.</li>
+</ul>
+
+<p>An example <code>.cfp</code> file might look like:</p>
+
+<pre>{
+    &#34;name&#34;: &#34;Pathfinder&#34;,
+    &#34;nickname&#34;: &#34;Pfind&#34;,
+    &#34;version&#34;: &#34;v2.3.8&#34;,
+    &#34;prerequisites&#34;: {
+        &#34;Clownfish&#34;: &#34;v0.5.0&#34;
+    }
+}</pre>
+
+<p>A parcel specifier of the following form is used in Clownfish header files:</p>
+
+<pre>parcel-specifier = &#34;parcel&#34; parcel-name &#34;;&#34;
+parcel-name = identifier</pre>
+
+<p>For example:</p>
+
+<pre>parcel Pathfinder;</pre>
+
+<p>Every <code>.cfh</code> file starts with a parcel specifier containing the name of the parcel for all classes in the header file.</p>
+
+<h4><a class='u'
+name="Initialization"
+>Initialization</a></h4>
+
+<p>Every Clownfish parcel must be initialized before it is used.
+The initialization function is named <code>{parcel_nick}_bootstrap_parcel</code> and takes no arguments.</p>
+
+<p>Example call:</p>
+
+<pre>pfind_bootstrap_parcel();</pre>
+
+<p>The generated host language bindings call the bootstrap function automatically.
+C projects must call the function manually.</p>
+
+<h4><a class='u'
+name="Short_names"
+>Short names</a></h4>
+
+<p>If a macro with the uppercase name <code>{PARCEL_NICK}_USE_SHORT_NAMES</code> is defined before including a generated C header,
+additional macros without the parcel prefix will be defined for most symbols.</p>
+
+<p>Example:</p>
+
+<pre>#define PFIND_USE_SHORT_NAMES
+#include &#60;Pathfinder/Graph.h&#62;
+#include &#60;Pathfinder/Path.h&#62;
+
+/* Prefixes can be omitted. */
+Path *path = Graph_Find_Shortest_Path(graph);
+
+/* Without PFIND_USE_SHORT_NAMES, one would have to write: */
+pfind_Path *path = PFIND_Graph_Find_Shortest_Path(graph);</pre>
+
+<p>For object types in Clownfish header files,
+prefixes of class structs can also be omitted unless multiple parcels declare classes with the same last component of the class name.</p>
+
+<h4><a class='u'
+name="The_(8220)Clownfish(8221)_parcel"
+>The &#8220;Clownfish&#8221; parcel</a></h4>
+
+<p>The Clownfish runtime classes live in a parcel named <code>Clownfish</code> with nickname <code>Cfish</code>.
+Consequently,
+the short name macro is named <code>CFISH_USE_SHORT_NAMES</code>.</p>
+
+<h3><a class='u'
+name="Declaring_classes"
+>Declaring classes</a></h3>
+
+<p>Classes are declared in Clownfish header files using a declaration of the following form:</p>
+
+<pre>class-declaration = class-exposure-specifier?
+                    class-modifier*
+                    &#34;class&#34; class-name
+                    (&#34;nickname&#34; class-nickname)?
+                    (&#34;inherits&#34; class-name)?
+                    &#34;{&#34; class-contents &#34;}&#34;
+class-exposure-specifier = &#34;public&#34;
+class-modifier = &#34;inert&#34; | &#34;final&#34;
+class-name = identifier | identifier &#34;::&#34; class-name
+class-nickname = identifier
+class-contents = (variable-declaration | function-declaration)*</pre>
+
+<p>Class name components must start with an uppercase letter and must not contain underscores.
+The last component must contain at least one lowercase letter and must be unique for every class in a parcel.</p>
+
+<p>For every class,
+a type with the name <code>{parcel_nick}_{Class_Last_Comp}</code> is defined in the generated C header.
+This is an opaque typedef used to ensure type safety.</p>
+
+<p>For every class,
+a global variable with the uppercase name <code>{PARCEL_NICK}_{CLASS_LAST_COMP}</code> is defined.
+This variable is a pointer to a Clownfish::Class object which is initialized when bootstrapping the parcel.</p>
+
+<p>Non-inert classes inherit from Clownfish::Obj by default.</p>
+
+<p>Example of a class declaration:</p>
+
+<pre>parcel Pathfinder;
+
+public class Pathfinder::Graph::VisibilityGraph nickname VisGraph
+    extends Clownfish::Obj {
+    /* Variables and functions */
+}</pre>
+
+<p>This will generate:</p>
+
+<pre>typedef struct pfind_VisibilityGraph pfind_VisibilityGraph;
+extern cfish_Class *PFIND_VISIBILITYGRAPH;</pre>
+
+<h4><a class='u'
+name="Class_exposure"
+>Class exposure</a></h4>
+
+<p>API documentation will only be generated for classes with <code>public</code> exposure.</p>
+
+<h4><a class='u'
+name="Inert_classes"
+>Inert classes</a></h4>
+
+<p>Inert classes must contain only inert variables or inert functions,
+that is,
+neither instance variables nor methods.
+They must not inherit from another class nor be inherited from.
+They&#8217;re essentially nothing more than a namespace for functions and global variables.</p>
+
+<h4><a class='u'
+name="Final_classes"
+>Final classes</a></h4>
+
+<p>For final classes,
+every method is made final,
+regardless of the method modifier.
+Final classes must not be inherited from.</p>
+
+<h3><a class='u'
+name="Variables"
+>Variables</a></h3>
+
+<p>Variables are declared with a declaration of the following form:</p>
+
+<pre>variable-declaration = variable-modifier*
+                       type variable-name &#34;;&#34;
+variable-modifier = &#34;inert&#34;
+variable-name = identifier</pre>
+
+<h4><a class='u'
+name="Inert_variables"
+>Inert variables</a></h4>
+
+<p>Inert variables are global class variables of which only a single copy exists.
+They are declared in the generated C header with the name <code>{parcel_nick}_{Class_Nick}_{Variable_Name}</code> and must be defined in a C source file.</p>
+
+<p>Example:</p>
+
+<pre>public class Pathfinder::Path {
+    public inert int max_path_length;
+}</pre>
+
+<p>This will generate:</p>
+
+<pre>extern int pfind_Path_max_path_length;</pre>
+
+<p>The C source file defining the variable will typically use short names.
+So the definition will look like:</p>
+
+<pre>int Path_max_path_length = 5000;</pre>
+
+<h4><a class='u'
+name="Instance_variables"
+>Instance variables</a></h4>
+
+<p>Non-inert variables are instance variables and added to the class&#8217;s ivars struct.</p>
+
+<p>Example:</p>
+
+<pre>public class Pathfinder::Path {
+    int num_nodes;
+
+    public int
+    Get_Num_Nodes(Path *self);
+}</pre>
+
+<p>This will add a <code>num_nodes</code> member to the ivars struct of <code>Path</code>.</p>
+
+<h4><a class='u'
+name="The_ivars_struct"
+>The ivars struct</a></h4>
+
+<p>To access instance variables,
+the macro <code>C_{PARCEL_NICK}_{CLASS_LAST_COMP}</code> must be defined before including the generated header file.
+This will make a struct named <code>{parcel_nick}_{Class_Name}IVARS</code> with a corresponding typedef and short name available that contains all instance variables of the class and all superclasses from the same parcel.
+Instance variables defined in other parcels are not accessible.
+This is by design to guarantee ABI stability if the instance variable layout of a superclass from another parcel changes in a different version.
+If you need to access an instance variable from another parcel,
+add accessor methods.</p>
+
+<p>A pointer to the ivars struct can be obtained by calling an inline function named <code>{parcel_nick}_{Class_Name}_IVARS</code>.
+This function takes the object of the class (typically <code>self</code>) as argument.</p>
+
+<p>Example using short names:</p>
+
+<pre>#define C_PFIND_PATH
+#define PFIND_USE_SHORT_NAMES
+#include &#34;Pathfinder/Path.h&#34;
+
+int
+Path_get_num_nodes(Path *self) {
+    PathIVARS *ivars = Path_IVARS(self);
+    return ivars-&#62;num_nodes;
+}</pre>
+
+<h3><a class='u'
+name="Functions"
+>Functions</a></h3>
+
+<pre>function-declaration = function-exposure-specifier?
+                       function-modifier*
+                       return-type function-name
+                       &#34;(&#34; param-list? &#34;)&#34; &#34;;&#34;
+function-exposure-specifier = &#34;public&#34;
+function-modifier = &#34;inert&#34; | &#34;inline&#34; | &#34;abstract&#34; | &#34;final&#34;
+return-type = return-type-qualifier* type
+return-type-qualifier = &#34;incremented&#34; | &#34;nullable&#34;
+function-name = identifier
+param-list = param | param &#34;,&#34; param-list
+param = param-qualifier* type param-name (&#34;=&#34; scalar-constant)?
+param-name = identifier
+param-qualifier = &#34;decremented&#34;</pre>
+
+<h4><a class='u'
+name="Function_exposure"
+>Function exposure</a></h4>
+
+<p>API documentation will only be generated for functions with <code>public</code> exposure.</p>
+
+<h4><a class='u'
+name="Inert_functions"
+>Inert functions</a></h4>
+
+<p>Inert functions are dispatched statically.
+They are declared in the generated C header with the name <code>{parcel_nick}_{Class_Nick}_{Function_Name}</code> and must be defined in a C source file.
+They must be neither abstract nor final.</p>
+
+<p>Example:</p>
+
+<pre>public class Pathfinder::Graph::VisibilityGraph nickname VisGraph
+    extends Clownfish::Obj {
+
+    public inert incremented VisibilityGraph*
+    new(int node_capacity);
+}</pre>
+
+<p>This will generate:</p>
+
+<pre>pfind_VisibilityGraph*
+pfind_VisGraph_new(int node_capacity);</pre>
+
+<p>The C source file implementing the inert function will typically use short names.
+So the implementation will look like:</p>
+
+<pre>#define PFIND_USE_SHORT_NAMES
+#include &#34;Pathfinder/Graph/VisibilityGraph.h&#34;
+
+VisibilityGraph*
+VisGraph_new(int node_capacity) {
+    /* Implementation */
+}</pre>
+
+<h4><a class='u'
+name="Inline_functions"
+>Inline functions</a></h4>
+
+<p>Inert functions can be inline.
+They should be defined as static inline functions in a C block in the Clownfish header file.
+The macro <code>CFISH_INLINE</code> expands to the C compiler&#8217;s inline keyword and should be used for portability.</p>
+
+<h4><a class='u'
+name="Methods"
+>Methods</a></h4>
+
+<p>Non-inert functions are dynamically dispatched methods.
+Their name must start with an uppercase letter and every underscore must be followed by an uppercase letter.
+Methods must not be declared inline.</p>
+
+<p>The first parameter of a method must be a pointer to an object of the method&#8217;s class which receives the object on which the method was invoked.
+By convention,
+this parameter is named <code>self</code>.</p>
+
+<p>For every method,
+an inline wrapper for dynamic dispatch is defined in the generated C header with the name <code>{PARCEL_NICK}_{Class_Nick}_{Method_Name}</code>.
+Additionally,
+an implementing function is declared with the name <code>{PARCEL_NICK}_{Class_Nick}_{Method_Name}_IMP</code>.
+The Clownfish compiler also generates a typedef for the method&#8217;s function pointer type named <code>{PARCEL_NICK}_{Class_Nick}_{Method_Name}_t</code>.
+Wrappers and typedefs are created for all subclasses whether they override a method or not.</p>
+
+<p>Example:</p>
+
+<pre>public class Pathfinder::Graph::VisibilityGraph nickname VisGraph
+    extends Clownfish::Obj {
+
+    public void
+    Add_Node(VisibilityGraph *self, decremented Node *node);
+}</pre>
+
+<p>This will generate:</p>
+
+<pre>/* Wrapper for dynamic dispatch */
+static inline void
+PFIND_VisGraph_Add_Node(pfind_VisibilityGraph *self, pfind_Node *node) {
+    /* Inline code for wrapper */
+}
+
+/* Declaration of implementing function */
+void
+PFIND_VisGraph_Add_Node_IMP(pfind_VisibilityGraph *self,
+                            pfind_Node *node);
+
+/* Declaration of function pointer type */
+typedef void
+(*PFIND_VisGraph_Add_Node_t)(pfind_VisibilityGraph *self,
+                             pfind_Node *node);</pre>
+
+<p>The implementing function of non-abstract methods must be defined in a C source file.
+This file will typically define the short names macro.
+So the implementation will look like:</p>
+
+<pre>#define PFIND_USE_SHORT_NAMES
+#include &#34;Pathfinder/Graph/VisibilityGraph.h&#34;
+
+void
+VisGraph_Add_Node_IMP(VisibilityGraph *self, Node *node) {
+    /* Implementation */
+}</pre>
+
+<h4><a class='u'
+name="Looking_up_methods"
+>Looking up methods</a></h4>
+
+<p>Clownfish defines a macro named <code>CFISH_METHOD_PTR</code> that looks up the pointer to the implementing function of a method.
+The first parameter of the macro is a pointer to the Clownfish::Class object of the method&#8217;s class,
+the second is the unshortened name of the method wrapper.
+If short names for the Clownfish parcel are used,
+the macro is also available under the name <code>METHOD_PTR</code>.</p>
+
+<p>To lookup methods from a superclass,
+there&#8217;s a macro <code>CFISH_SUPER_METHOD_PTR</code> with the same parameters.</p>
+
+<p>Example using short names:</p>
+
+<pre>// Note that the name of the method wrapper must not be shortened.
+VisGraph_Add_Node_t add_node
+    = METHOD_PTR(VISIBILITYGRAPH, Pfind_VisGraph_Add_Node);
+
+VisGraph_Add_Node_t super_add_node
+    = SUPER_METHOD_PTR(VISIBILITYGRAPH, Pfind_VisGraph_Add_Node);</pre>
+
+<h4><a class='u'
+name="Abstract_methods"
+>Abstract methods</a></h4>
+
+<p>For abstract methods,
+the Clownfish compiler generates an implementing function which throws an error.
+They should be overridden in a subclass.</p>
+
+<h4><a class='u'
+name="Final_methods"
+>Final methods</a></h4>
+
+<p>Final methods must not be overridden.
+They must not be abstract.</p>
+
+<h4><a class='u'
+name="Nullable_return_type"
+>Nullable return type</a></h4>
+
+<p>If a function has a nullable return type,
+it must return a pointer.
+Non-nullable functions must never return the NULL pointer.</p>
+
+<h4><a class='u'
+name="Incremented_return_type"
+>Incremented return type</a></h4>
+
+<p>Incremented return types must be pointers to Clownfish objects.
+The function will either return a new object with an initial reference count of 1 or increment the reference count.
+The caller must decrement the reference count of the returned object when it&#8217;s no longer used.</p>
+
+<p>For returned objects with non-incremented return type,
+usually no additional handling of reference counts is required.
+Only if an object is returned from an accessor or a container object and the caller wants to use the object longer than the returning object retains a reference,
+it must increment the reference count itself and decrement when the object is no longer used.</p>
+
+<h4><a class='u'
+name="Decremented_parameters"
+>Decremented parameters</a></h4>
+
+<p>Decremented parameters must be pointers to Clownfish objects.
+The function will either decrement the reference count of the passed-in object or retain a reference without incrementing the reference count.
+If the caller wants to use the passed-in object afterwards,
+it usually must increment its reference count before the call and decrement it when it&#8217;s no longer used.
+If the caller does not make further use of the passed-in object,
+it must not decrement its reference count after the call.</p>
+
+<p>This is typically used in container classes like Vector:</p>
+
+<pre>String *string = String_newf(&#34;Hello&#34;);
+Vec_Push(array, (Obj*)string);
+// No need to DECREF the string.</pre>
+
+<h4><a class='u'
+name="Default_parameter_values"
+>Default parameter values</a></h4>
+
+<p>Default parameter values can be given as integer,
+float,
+or string literals.
+The values <code>true</code>,
+<code>false</code>,
+and <code>NULL</code> are also supported.
+The default values are only used by certain host language bindings.
+They&#8217;re not supported when calling a function from C.</p>
+
+<h3><a class='u'
+name="C_blocks"
+>C blocks</a></h3>
+
+<p>Clownfish headers can contain C blocks which start with a line containing the string <code>__C__</code> and end on a line containing the string <code>__END_C__</code>.
+The contents of a C block are copied verbatim to the generated C header.</p>
+
+<p>Example:</p>
+
+<pre>__C__
+
+struct pfind_AuxiliaryStruct {
+    int a;
+    int b;
+};
+
+__END_C__</pre>
+
+<h3><a class='u'
+name="Object_life_cycle"
+>Object life cycle</a></h3>
+
+<h4><a class='u'
+name="Object_creation"
+>Object creation</a></h4>
+
+<p>Objects are allocated by invoking the <code>Make_Obj</code> method on a class&#8217;s Clownfish::Class object.</p>
+
+<p>Any inert function can be used to construct objects from C.
+But to support inheritance and object creation from the host language,
+Clownfish classes need a separate function to initialize objects.
+The initializer must take a pointer to an object as first argument and return a pointer to the same object.
+If the parent class has an initializer,
+it should be called first by the subclass&#8217;s initializer.</p>
+
+<p>By convention,
+the standard constructor is named <code>new</code> and the standard initializer <code>init</code>.</p>
+
+<p>Example:</p>
+
+<pre>/* Clownfish header */
+
+class Vehicle {
+    double max_speed;
+
+    inert Vehicle*
+    init(Vehicle *self, double max_speed);
+}
+
+class Train inherits Vehicle {
+    double track_gauge;
+
+    inert incremented Train*
+    new(double max_speed, double track_gauge);
+
+    inert Train*
+    init(Train *self, double max_speed, double track_gauge);
+}
+
+/* Implementation */
+
+Train*
+Train_new(double max_speed, double track_gauge) {
+    Train *self = (Train*)Class_Make_Obj(TRAIN);
+    return Train_init(self, max_speed, track_gauge);
+}
+
+Train*
+Train_init(Train *self, double max_speed, double track_gauge) {
+    Vehicle_init((Vehicle*)self, max_speed);
+    self-&#62;track_gauge = track_gauge;
+    return self;
+}</pre>
+
+<h4><a class='u'
+name="Reference_counting"
+>Reference counting</a></h4>
+
+<p>Clownfish uses reference counting for memory management.
+Objects are created with a reference count of 1.
+There are two macros <code>CFISH_INCREF</code> and <code>CFISH_DECREF</code> to increment and decrement reference counts.
+If short names for the Clownfish parcel are enabled,
+the macros can be abbreviated to <code>INCREF</code> and <code>DECREF</code>.
+Both macros take a pointer to an object as argument.
+NULL pointers are allowed.
+<code>CFISH_INCREF</code> returns a pointer to the object.
+This value might differ from the passed-in pointer in some cases.
+So if a reference is retained,
+the pointer returned from <code>CFISH_INCREF</code> should be used.
+<code>CFISH_DECREF</code> returns the modified reference count.</p>
+
+<p>Examples:</p>
+
+<pre>self-&#62;value = INCREF(arg);
+
+DECREF(object);</pre>
+
+<h4><a class='u'
+name="Object_destruction"
+>Object destruction</a></h4>
+
+<p>If an object&#8217;s reference count reaches 0,
+its <code>Destroy</code> method is called.
+This public method takes no arguments besides <code>self</code> and has no return value.
+It should release the resources held by the object and finally call the <code>Destroy</code> method of the superclass via the <code>CFISH_SUPER_DESTROY</code> macro with short name <code>SUPER_DESTROY</code>.
+This macro takes the <code>self</code> pointer as first argument and a pointer to the object&#8217;s Clownfish::Class as second argument.
+The <code>Destroy</code> method of the Clownfish::Obj class will eventually free the object struct.</p>
+
+<p>Example:</p>
+
+<pre>/* Clownfish header */
+
+class Path {
+    Vector *nodes;
+
+    public void
+    Destroy(Path *self);
+}
+
+/* Implementation */
+
+void
+Path_Destroy_IMP(Path *self) {
+    DECREF(self-&#62;nodes);
+    SUPER_DESTROY(self, PATH);
+}</pre>
+
+<h3><a class='u'
+name="Documentation"
+>Documentation</a></h3>
+
+<p>The Clownfish compiler creates documentation in the host language&#8217;s preferred format from so-called DocuComments found in the <code>.cfh</code> files.
+DocuComments use Markdown (<a href="http://commonmark.org/" class="podlinkurl"
+>CommonMark</a> flavor) for formatting.
+DocuComments are multi-line C-style comments that start with <code>/**</code>.
+They immediately precede the documented class,
+inert function,
+or method.
+A left border consisting of whitespace and asterisks is stripped.</p>
+
+<p>The DocuComment for a class should start with a short description (everything up until the first period <code>.</code>) which may appear in the name section of a man page,
+for example.</p>
+
+<p>DocuComments for functions and methods may end with a series of <code>@param</code> and <code>@return</code> directives which document the parameters and return values.</p>
+
+<p>Example:</p>
+
+<pre>/** Class describing a train.
+ *
+ * The Train class describes a train. It extends the Vehicle class and
+ * adds some useful properties specific to trains.
+ */
+public class Train inherits Vehicle {
+    /** Create a new Train object.
+     *
+     * @param max_speed The maximum speed in km/h.
+     * @param track_gauge The track gauge in mm.
+     */
+    public inert incremented Train*
+    new(double max_speed, double track_gauge);
+
+    /** Accessor for maximum speed.
+     *
+     * @return the maximum speed in km/h.
+     */
+    public double
+    Get_Max_Speed(Train *self);
+}</pre>
+
+<p>The Clownfish compiler also looks for standalone Markdown <code>.md</code> files in the source directories which will be included in the documentation.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/Err.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/Err.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/Err.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/Err.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,73 @@
+Title: Clownfish::Err – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::Err - Exception.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>package MyErr;
+use base qw( Clownfish::Err );
+
+...
+
+package main;
+use Scalar::Util qw( blessed );
+while (1) {
+    eval {
+        do_stuff() or MyErr-&#62;throw(&#34;retry&#34;);
+    };
+    if ( blessed($@) and $@-&#62;isa(&#34;MyErr&#34;) ) {
+        warn &#34;Retrying...\n&#34;;
+    }
+    else {
+        # Re-throw.
+        die &#34;do_stuff() died: $@&#34;;
+    }
+}</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<p>Clownfish::Err is the base class for exceptions in the Clownfish object hierarchy.</p>
+
+<p>The Err module also provides access to a per-thread Err shared variable via set_error() and get_error().
+It may be used to store an Err object temporarily,
+so that calling code may choose how to handle a particular error condition.</p>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="cat_mess"
+>cat_mess</a></h3>
+
+<pre>$err-&#62;cat_mess($mess);</pre>
+
+<p>Concatenate the supplied argument onto the error message.</p>
+
+<h3><a class='u'
+name="get_mess"
+>get_mess</a></h3>
+
+<pre>my $string = $err-&#62;get_mess();</pre>
+
+<p>Return the error message.</p>
+
+<h2><a class='u'
+name="INHERITANCE"
+>INHERITANCE</a></h2>
+
+<p>Clownfish::Err isa <a href="../Clownfish/Obj.html" class="podlinkpod"
+>Clownfish::Obj</a>.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/Float.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/Float.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/Float.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/Float.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,91 @@
+Title: Clownfish::Float – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::Float - Immutable double precision floating point number.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>my $float = Clownfish::Float-&#62;new(2.5);
+my $value = $float-&#62;get_value;</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<h2><a class='u'
+name="CONSTRUCTORS"
+>CONSTRUCTORS</a></h2>
+
+<h3><a class='u'
+name="new"
+>new</a></h3>
+
+<pre>my $float = Clownfish::Float-&#62;new($value);</pre>
+
+<p>Return a new Float.</p>
+
+<ul>
+<li><b>value</b> - Initial value.</li>
+</ul>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="get_value"
+>get_value</a></h3>
+
+<pre>my $result = $float-&#62;get_value();</pre>
+
+<p>Return the value of the Float.</p>
+
+<h3><a class='u'
+name="to_i64"
+>to_i64</a></h3>
+
+<pre>my $int = $float-&#62;to_i64();</pre>
+
+<p>Convert the Float to an integer,
+truncating toward zero.
+Throw an exception if the value is out of the range of an <code>int64_t</code>.</p>
+
+<h3><a class='u'
+name="compare_to"
+>compare_to</a></h3>
+
+<pre>my $int = $float-&#62;compare_to($other);</pre>
+
+<p>Indicate whether one number is less than,
+equal to,
+or greater than another.
+Throws an exception if <code>other</code> is neither a Float nor an Integer.</p>
+
+<p>Returns: 0 if the numbers are equal,
+a negative number if <code>self</code> is less than <code>other</code>,
+and a positive number if <code>self</code> is greater than <code>other</code>.</p>
+
+<h3><a class='u'
+name="clone"
+>clone</a></h3>
+
+<pre>my $result = $float-&#62;clone();</pre>
+
+<p>Return a clone of the object.</p>
+
+<h2><a class='u'
+name="INHERITANCE"
+>INHERITANCE</a></h2>
+
+<p>Clownfish::Float isa <a href="../Clownfish/Obj.html" class="podlinkpod"
+>Clownfish::Obj</a>.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/Hash.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/Hash.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/Hash.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/Hash.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,124 @@
+Title: Clownfish::Hash – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::Hash - Hashtable.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>my $hash = Clownfish::Hash-&#62;new;
+$hash-&#62;store($key, $value);
+my $value = $hash-&#62;fetch($key);</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<p>Values are stored by reference and may be any kind of Obj.</p>
+
+<h2><a class='u'
+name="CONSTRUCTORS"
+>CONSTRUCTORS</a></h2>
+
+<h3><a class='u'
+name="new"
+>new</a></h3>
+
+<pre>my $hash = Clownfish::Hash-&#62;new(
+    capacity =&#62; $capacity  # default: 0
+);</pre>
+
+<p>Return a new Hash.</p>
+
+<ul>
+<li><b>capacity</b> - The number of elements that the hash will be asked to hold initially.</li>
+</ul>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="clear"
+>clear</a></h3>
+
+<pre>$hash-&#62;clear();</pre>
+
+<p>Empty the hash of all key-value pairs.</p>
+
+<h3><a class='u'
+name="store"
+>store</a></h3>
+
+<pre>$hash-&#62;store($key, $value);</pre>
+
+<p>Store a key-value pair.</p>
+
+<h3><a class='u'
+name="fetch"
+>fetch</a></h3>
+
+<pre>my $obj = $hash-&#62;fetch($key);</pre>
+
+<p>Fetch the value associated with <code>key</code>.</p>
+
+<p>Returns: the value,
+or undef if <code>key</code> is not present.</p>
+
+<h3><a class='u'
+name="delete"
+>delete</a></h3>
+
+<pre>my $obj = $hash-&#62;delete($key);</pre>
+
+<p>Attempt to delete a key-value pair from the hash.</p>
+
+<p>Returns: the value if <code>key</code> exists and thus deletion succeeds; otherwise undef.</p>
+
+<h3><a class='u'
+name="has_key"
+>has_key</a></h3>
+
+<pre>my $bool = $hash-&#62;has_key($key);</pre>
+
+<p>Indicate whether the supplied <code>key</code> is present.</p>
+
+<h3><a class='u'
+name="keys"
+>keys</a></h3>
+
+<pre>my $arrayref = $hash-&#62;keys();</pre>
+
+<p>Return the Hash&#8217;s keys.</p>
+
+<h3><a class='u'
+name="values"
+>values</a></h3>
+
+<pre>my $arrayref = $hash-&#62;values();</pre>
+
+<p>Return the Hash&#8217;s values.</p>
+
+<h3><a class='u'
+name="get_size"
+>get_size</a></h3>
+
+<pre>my $int = $hash-&#62;get_size();</pre>
+
+<p>Return the number of key-value pairs.</p>
+
+<h2><a class='u'
+name="INHERITANCE"
+>INHERITANCE</a></h2>
+
+<p>Clownfish::Hash isa <a href="../Clownfish/Obj.html" class="podlinkpod"
+>Clownfish::Obj</a>.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/HashIterator.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/HashIterator.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/HashIterator.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/HashIterator.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,80 @@
+Title: Clownfish::HashIterator – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::HashIterator - Hashtable Iterator.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>my $iter = Clownfish::HashIterator-&#62;new($hash);
+while ($iter-&#62;next) {
+    my $key   = $iter-&#62;get_key;
+    my $value = $iter-&#62;get_value;
+}</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<h2><a class='u'
+name="CONSTRUCTORS"
+>CONSTRUCTORS</a></h2>
+
+<h3><a class='u'
+name="new"
+>new</a></h3>
+
+<pre>my $iter = Clownfish::HashIterator-&#62;new($hash);</pre>
+
+<p>Return a HashIterator for <code>hash</code>.</p>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="next"
+>next</a></h3>
+
+<pre>my $bool = $hash_iterator-&#62;next();</pre>
+
+<p>Advance the iterator to the next key-value pair.</p>
+
+<p>Returns: true if there&#8217;s another key-value pair,
+false if the iterator is exhausted.</p>
+
+<h3><a class='u'
+name="get_key"
+>get_key</a></h3>
+
+<pre>my $string = $hash_iterator-&#62;get_key();</pre>
+
+<p>Return the key of the current key-value pair.
+It&#8217;s not allowed to call this method before <a href="#next" class="podlinkpod"
+>next()</a> was called for the first time or after the iterator was exhausted.</p>
+
+<h3><a class='u'
+name="get_value"
+>get_value</a></h3>
+
+<pre>my $obj = $hash_iterator-&#62;get_value();</pre>
+
+<p>Return the value of the current key-value pair.
+It&#8217;s not allowed to call this method before <a href="#next" class="podlinkpod"
+>next()</a> was called for the first time or after the iterator was exhausted.</p>
+
+<h2><a class='u'
+name="INHERITANCE"
+>INHERITANCE</a></h2>
+
+<p>Clownfish::HashIterator isa <a href="../Clownfish/Obj.html" class="podlinkpod"
+>Clownfish::Obj</a>.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/Integer.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/Integer.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/Integer.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/Integer.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,89 @@
+Title: Clownfish::Integer – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::Integer - Immutable 64-bit signed integer.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>my $integer = Clownfish::Integer-&#62;new(7);
+my $value = $integer-&#62;get_value;</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<h2><a class='u'
+name="CONSTRUCTORS"
+>CONSTRUCTORS</a></h2>
+
+<h3><a class='u'
+name="new"
+>new</a></h3>
+
+<pre>my $integer = Clownfish::Integer-&#62;new($value);</pre>
+
+<p>Return a new Integer.</p>
+
+<ul>
+<li><b>value</b> - Initial value.</li>
+</ul>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="get_value"
+>get_value</a></h3>
+
+<pre>my $int = $integer-&#62;get_value();</pre>
+
+<p>Return the value of the Integer.</p>
+
+<h3><a class='u'
+name="to_f64"
+>to_f64</a></h3>
+
+<pre>my $float = $integer-&#62;to_f64();</pre>
+
+<p>Convert the Integer to floating point.</p>
+
+<h3><a class='u'
+name="compare_to"
+>compare_to</a></h3>
+
+<pre>my $int = $integer-&#62;compare_to($other);</pre>
+
+<p>Indicate whether one number is less than,
+equal to,
+or greater than another.
+Throws an exception if <code>other</code> is neither an Integer nor a Float.</p>
+
+<p>Returns: 0 if the numbers are equal,
+a negative number if <code>self</code> is less than <code>other</code>,
+and a positive number if <code>self</code> is greater than <code>other</code>.</p>
+
+<h3><a class='u'
+name="clone"
+>clone</a></h3>
+
+<pre>my $result = $integer-&#62;clone();</pre>
+
+<p>Return a clone of the object.</p>
+
+<h2><a class='u'
+name="INHERITANCE"
+>INHERITANCE</a></h2>
+
+<p>Clownfish::Integer isa <a href="../Clownfish/Obj.html" class="podlinkpod"
+>Clownfish::Obj</a>.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/Obj.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/Obj.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/Obj.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/Obj.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,163 @@
+Title: Clownfish::Obj – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::Obj - Base class for all objects.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>package MyObj;
+use base qw( Clownfish::Obj );
+
+# Inside-out member var.
+my %foo;
+
+sub new {
+    my ( $class, %args ) = @_;
+    my $foo = delete $args{foo};
+    my $self = $class-&#62;SUPER::new(%args);
+    $foo{$$self} = $foo;
+    return $self;
+}
+
+sub get_foo {
+    my $self = shift;
+    return $foo{$$self};
+}
+
+sub DESTROY {
+    my $self = shift;
+    delete $foo{$$self};
+    $self-&#62;SUPER::DESTROY;
+}</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<p>Clownfish::Obj is the base class of the Clownfish object hierarchy.</p>
+
+<p>From the standpoint of a Perl programmer,
+all classes are implemented as blessed scalar references,
+with the scalar storing a pointer to a C struct.</p>
+
+<h3><a class='u'
+name="Subclassing"
+>Subclassing</a></h3>
+
+<p>The recommended way to subclass Clownfish::Obj and its descendants is to use the inside-out design pattern.
+(See <a href="../Class/InsideOut.html" class="podlinkpod"
+>Class::InsideOut</a> for an introduction to inside-out techniques.)</p>
+
+<p>Since the blessed scalar stores a C pointer value which is unique per-object,
+<code>$$self</code> can be used as an inside-out ID.</p>
+
+<pre># Accessor for &#39;foo&#39; member variable.
+sub get_foo {
+    my $self = shift;
+    return $foo{$$self};
+}</pre>
+
+<p>Caveats:</p>
+
+<ul>
+<li>Inside-out aficionados will have noted that the &#34;cached scalar id&#34; stratagem recommended above isn&#39;t compatible with ithreads.</li>
+
+<li>Overridden methods must not return undef unless the API specifies that returning undef is permissible.</li>
+</ul>
+
+<h2><a class='u'
+name="CONSTRUCTOR"
+>CONSTRUCTOR</a></h2>
+
+<h3><a class='u'
+name="new"
+>new</a></h3>
+
+<pre>my $self = $class-&#62;SUPER::new;</pre>
+
+<p>Abstract constructor -- must be invoked via a subclass.
+Attempting to instantiate objects of class &#34;Clownfish::Obj&#34; directly causes an error.</p>
+
+<p>Takes no arguments; if any are supplied,
+an error will be reported.</p>
+
+<h2><a class='u'
+name="ABSTRACT_METHODS"
+>ABSTRACT METHODS</a></h2>
+
+<h3><a class='u'
+name="clone"
+>clone</a></h3>
+
+<pre>my $result = $obj-&#62;clone();</pre>
+
+<p>Return a clone of the object.</p>
+
+<h3><a class='u'
+name="compare_to"
+>compare_to</a></h3>
+
+<pre>my $int = $obj-&#62;compare_to($other);</pre>
+
+<p>Indicate whether one object is less than,
+equal to,
+or greater than another.</p>
+
+<ul>
+<li><b>other</b> - Another Obj.</li>
+</ul>
+
+<p>Returns: 0 if the objects are equal,
+a negative number if <code>self</code> is less than <code>other</code>,
+and a positive number if <code>self</code> is greater than <code>other</code>.</p>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="to_perl"
+>to_perl</a></h3>
+
+<pre>my $native = $obj-&#62;to_perl;</pre>
+
+<p>Tries to convert the object to its native Perl representation.</p>
+
+<h3><a class='u'
+name="equals"
+>equals</a></h3>
+
+<pre>my $bool = $obj-&#62;equals($other);</pre>
+
+<p>Indicate whether two objects are the same.
+By default,
+compares the memory address.</p>
+
+<ul>
+<li><b>other</b> - Another Obj.</li>
+</ul>
+
+<h3><a class='u'
+name="DESTROY"
+>DESTROY</a></h3>
+
+<p>All Clownfish classes implement a DESTROY method; if you override it in a subclass,
+you must call <code>$self-&#62;SUPER::DESTROY</code> to avoid leaking memory.</p>
+
+<h3><a class='u'
+name="to_string"
+>to_string</a></h3>
+
+<pre>my $string = $obj-&#62;to_string();</pre>
+
+<p>Generic stringification: &#8220;ClassName@hex_mem_address&#8221;.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/String.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/String.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/String.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/String.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,251 @@
+Title: Clownfish::String – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::String - Immutable string holding Unicode characters.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>my $string = Clownfish::String-&#62;new(&#39;abc&#39;);
+print $string-&#62;to_perl, &#34;\n&#34;;</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<h2><a class='u'
+name="CONSTRUCTORS"
+>CONSTRUCTORS</a></h2>
+
+<h3><a class='u'
+name="new"
+>new</a></h3>
+
+<pre>my $string = Clownfish::String-&#62;new($perl_string);</pre>
+
+<p>Return a String containing the passed-in Perl string.</p>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="cat"
+>cat</a></h3>
+
+<pre>my $result = $string-&#62;cat($other);</pre>
+
+<p>Return the concatenation of the String and <code>other</code>.</p>
+
+<h3><a class='u'
+name="to_i64"
+>to_i64</a></h3>
+
+<pre>my $int = $string-&#62;to_i64();</pre>
+
+<p>Extract a 64-bit integer from a decimal string.
+See <a href="#basex_to_i64" class="podlinkpod"
+>basex_to_i64()</a> for details.</p>
+
+<h3><a class='u'
+name="basex_to_i64"
+>basex_to_i64</a></h3>
+
+<pre>my $int = $string-&#62;basex_to_i64($base);</pre>
+
+<p>Extract a 64-bit integer from a variable-base stringified version.
+Expects an optional minus sign followed by base-x digits,
+stopping at any non-digit character.
+Returns zero if no digits are found.
+If the value exceeds the range of an <code>int64_t</code>,
+the result is undefined.</p>
+
+<ul>
+<li><b>base</b> - A base between 2 and 36.</li>
+</ul>
+
+<h3><a class='u'
+name="to_f64"
+>to_f64</a></h3>
+
+<pre>my $float = $string-&#62;to_f64();</pre>
+
+<p>Convert a string to a floating-point number using the C library function <code>strtod</code>.</p>
+
+<h3><a class='u'
+name="starts_with"
+>starts_with</a></h3>
+
+<pre>my $bool = $string-&#62;starts_with($prefix);</pre>
+
+<p>Test whether the String starts with <code>prefix</code>.</p>
+
+<h3><a class='u'
+name="ends_with"
+>ends_with</a></h3>
+
+<pre>my $bool = $string-&#62;ends_with($suffix);</pre>
+
+<p>Test whether the String ends with <code>suffix</code>.</p>
+
+<h3><a class='u'
+name="contains"
+>contains</a></h3>
+
+<pre>my $bool = $string-&#62;contains($substring);</pre>
+
+<p>Test whether the String contains <code>substring</code>.</p>
+
+<h3><a class='u'
+name="find"
+>find</a></h3>
+
+<pre>my $string_iterator = $string-&#62;find($substring);</pre>
+
+<p>Return a <a href="../Clownfish/StringIterator.html" class="podlinkpod"
+>StringIterator</a> pointing to the first occurrence of <code>substring</code> within the String,
+or undef if the substring does not match.</p>
+
+<h3><a class='u'
+name="length"
+>length</a></h3>
+
+<pre>my $int = $string-&#62;length();</pre>
+
+<p>Return the number of Unicode code points the String contains.</p>
+
+<h3><a class='u'
+name="get_size"
+>get_size</a></h3>
+
+<pre>my $int = $string-&#62;get_size();</pre>
+
+<p>Return the number of bytes occupied by the String&#8217;s internal content.</p>
+
+<h3><a class='u'
+name="to_bytebuf"
+>to_bytebuf</a></h3>
+
+<pre>my $byte_buf = $string-&#62;to_bytebuf();</pre>
+
+<p>Return a ByteBuf which holds a copy of the String.</p>
+
+<h3><a class='u'
+name="clone"
+>clone</a></h3>
+
+<pre>my $result = $string-&#62;clone();</pre>
+
+<p>Return a clone of the object.</p>
+
+<h3><a class='u'
+name="compare_to"
+>compare_to</a></h3>
+
+<pre>my $int = $string-&#62;compare_to($other);</pre>
+
+<p>Indicate whether one String is less than,
+equal to,
+or greater than another.
+The Unicode code points of the Strings are compared lexicographically.
+Throws an exception if <code>other</code> is not a String.</p>
+
+<p>Returns: 0 if the Strings are equal,
+a negative number if <code>self</code> is less than <code>other</code>,
+and a positive number if <code>self</code> is greater than <code>other</code>.</p>
+
+<h3><a class='u'
+name="trim"
+>trim</a></h3>
+
+<pre>my $result = $string-&#62;trim();</pre>
+
+<p>Return a copy of the String with Unicode whitespace characters removed from both top and tail.
+Whitespace is any character that has the Unicode property <code>White_Space</code>.</p>
+
+<h3><a class='u'
+name="trim_top"
+>trim_top</a></h3>
+
+<pre>my $result = $string-&#62;trim_top();</pre>
+
+<p>Return a copy of the String with leading Unicode whitespace removed.
+Whitespace is any character that has the Unicode property <code>White_Space</code>.</p>
+
+<h3><a class='u'
+name="trim_tail"
+>trim_tail</a></h3>
+
+<pre>my $result = $string-&#62;trim_tail();</pre>
+
+<p>Return a copy of the String with trailing Unicode whitespace removed.
+Whitespace is any character that has the Unicode property <code>White_Space</code>.</p>
+
+<h3><a class='u'
+name="code_point_at"
+>code_point_at</a></h3>
+
+<pre>my $int = $string-&#62;code_point_at($tick);</pre>
+
+<p>Return the Unicode code point located <code>tick</code> code points in from the top.
+Return <code>CFISH_STR_OOB</code> if out of bounds.</p>
+
+<h3><a class='u'
+name="code_point_from"
+>code_point_from</a></h3>
+
+<pre>my $int = $string-&#62;code_point_from($tick);</pre>
+
+<p>Return the Unicode code point located <code>tick</code> code points counting backwards from the end.
+Return <code>CFISH_STR_OOB</code> if out of bounds.</p>
+
+<h3><a class='u'
+name="substring"
+>substring</a></h3>
+
+<pre>my $result = $string-&#62;substring(
+    offset =&#62; $offset  # required
+    length =&#62; $length  # required
+);</pre>
+
+<p>Return a new substring containing a copy of the specified range.</p>
+
+<ul>
+<li><b>offset</b> - Offset from the top,
+in code points.</li>
+
+<li><b>length</b> - The desired length of the substring,
+in code points.</li>
+</ul>
+
+<h3><a class='u'
+name="top"
+>top</a></h3>
+
+<pre>my $string_iterator = $string-&#62;top();</pre>
+
+<p>Return an iterator initialized to the start of the string.</p>
+
+<h3><a class='u'
+name="tail"
+>tail</a></h3>
+
+<pre>my $string_iterator = $string-&#62;tail();</pre>
+
+<p>Return an iterator initialized to the end of the string.</p>
+
+<h2><a class='u'
+name="INHERITANCE"
+>INHERITANCE</a></h2>
+
+<p>Clownfish::String isa <a href="../Clownfish/Obj.html" class="podlinkpod"
+>Clownfish::Obj</a>.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/StringIterator.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/StringIterator.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/StringIterator.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/StringIterator.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,171 @@
+Title: Clownfish::StringIterator – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::StringIterator - Iterate Unicode code points in a String.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>my $iter = $string-&#62;top;
+while (my $code_point = $iter-&#62;next) {
+    ...
+}</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="clone"
+>clone</a></h3>
+
+<pre>my $result = $string_iterator-&#62;clone();</pre>
+
+<p>Return a clone of the object.</p>
+
+<h3><a class='u'
+name="assign"
+>assign</a></h3>
+
+<pre>$string_iterator-&#62;assign($other);</pre>
+
+<p>Assign the source string and current position of <code>other</code> to <code>self</code>.</p>
+
+<h3><a class='u'
+name="compare_to"
+>compare_to</a></h3>
+
+<pre>my $int = $string_iterator-&#62;compare_to($other);</pre>
+
+<p>Indicate whether one StringIterator is less than,
+equal to,
+or greater than another by comparing their character positions.
+Throws an exception if <code>other</code> is not a StringIterator pointing to the same source string as <code>self</code>.</p>
+
+<p>Returns: 0 if the StringIterators are equal,
+a negative number if <code>self</code> is less than <code>other</code>,
+and a positive number if <code>self</code> is greater than <code>other</code>.</p>
+
+<h3><a class='u'
+name="has_next"
+>has_next</a></h3>
+
+<pre>my $bool = $string_iterator-&#62;has_next();</pre>
+
+<p>Return true if the iterator is not at the end of the string.</p>
+
+<h3><a class='u'
+name="has_prev"
+>has_prev</a></h3>
+
+<pre>my $bool = $string_iterator-&#62;has_prev();</pre>
+
+<p>Return true if the iterator is not at the start of the string.</p>
+
+<h3><a class='u'
+name="next"
+>next</a></h3>
+
+<pre>my $code_point = $iter-&#62;next;</pre>
+
+<p>Return the code point after the current position and advance the iterator.
+Returns undef at the end of the string.
+Returns zero but true for U+0000.</p>
+
+<h3><a class='u'
+name="prev"
+>prev</a></h3>
+
+<pre>my $code_point = $iter-&#62;prev;</pre>
+
+<p>Return the code point before the current position and go one step back.
+Returns undef at the start of the string.
+Returns zero but true for U+0000.</p>
+
+<h3><a class='u'
+name="advance"
+>advance</a></h3>
+
+<pre>my $int = $string_iterator-&#62;advance($num);</pre>
+
+<p>Skip code points.</p>
+
+<ul>
+<li><b>num</b> - The number of code points to skip.</li>
+</ul>
+
+<p>Returns: the number of code points actually skipped.
+This can be less than the requested number if the end of the string is reached.</p>
+
+<h3><a class='u'
+name="recede"
+>recede</a></h3>
+
+<pre>my $int = $string_iterator-&#62;recede($num);</pre>
+
+<p>Skip code points backward.</p>
+
+<ul>
+<li><b>num</b> - The number of code points to skip.</li>
+</ul>
+
+<p>Returns: the number of code points actually skipped.
+This can be less than the requested number if the start of the string is reached.</p>
+
+<h3><a class='u'
+name="skip_whitespace"
+>skip_whitespace</a></h3>
+
+<pre>my $int = $string_iterator-&#62;skip_whitespace();</pre>
+
+<p>Skip whitespace.
+Whitespace is any character that has the Unicode property <code>White_Space</code>.</p>
+
+<p>Returns: the number of code points skipped.</p>
+
+<h3><a class='u'
+name="skip_whitespace_back"
+>skip_whitespace_back</a></h3>
+
+<pre>my $int = $string_iterator-&#62;skip_whitespace_back();</pre>
+
+<p>Skip whitespace backward.
+Whitespace is any character that has the Unicode property <code>White_Space</code>.</p>
+
+<p>Returns: the number of code points skipped.</p>
+
+<h3><a class='u'
+name="starts_with"
+>starts_with</a></h3>
+
+<pre>my $bool = $string_iterator-&#62;starts_with($prefix);</pre>
+
+<p>Test whether the content after the iterator starts with <code>prefix</code>.</p>
+
+<h3><a class='u'
+name="ends_with"
+>ends_with</a></h3>
+
+<pre>my $bool = $string_iterator-&#62;ends_with($suffix);</pre>
+
+<p>Test whether the content before the iterator ends with <code>suffix</code>.</p>
+
+<h2><a class='u'
+name="INHERITANCE"
+>INHERITANCE</a></h2>
+
+<p>Clownfish::StringIterator isa <a href="../Clownfish/Obj.html" class="podlinkpod"
+>Clownfish::Obj</a>.</p>
+
+</div>

Added: lucy/site/trunk/content/docs/perl/Clownfish/Vector.mdtext
URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/perl/Clownfish/Vector.mdtext?rev=1737642&view=auto
==============================================================================
--- lucy/site/trunk/content/docs/perl/Clownfish/Vector.mdtext (added)
+++ lucy/site/trunk/content/docs/perl/Clownfish/Vector.mdtext Mon Apr  4 09:22:30 2016
@@ -0,0 +1,207 @@
+Title: Clownfish::Vector – Apache Clownfish Documentation
+
+<div>
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<h2><a class='u'
+name="NAME"
+>NAME</a></h2>
+
+<p>Clownfish::Vector - Variable-sized array.</p>
+
+<h2><a class='u'
+name="SYNOPSIS"
+>SYNOPSIS</a></h2>
+
+<pre>my $vector = Clownfish::Vector-&#62;new;
+$vector-&#62;store($tick, $value);
+my $value = $vector-&#62;fetch($tick);</pre>
+
+<h2><a class='u'
+name="DESCRIPTION"
+>DESCRIPTION</a></h2>
+
+<h2><a class='u'
+name="CONSTRUCTORS"
+>CONSTRUCTORS</a></h2>
+
+<h3><a class='u'
+name="new"
+>new</a></h3>
+
+<pre>my $vector = Clownfish::Vector-&#62;new(
+    capacity =&#62; $capacity  # default: 0
+);</pre>
+
+<p>Return a new Vector.</p>
+
+<ul>
+<li><b>capacity</b> - Initial number of elements that the object will be able to hold before reallocation.</li>
+</ul>
+
+<h2><a class='u'
+name="METHODS"
+>METHODS</a></h2>
+
+<h3><a class='u'
+name="push"
+>push</a></h3>
+
+<pre>$vector-&#62;push($element);
+$vector-&#62;push();  # default: undef</pre>
+
+<p>Push an item onto the end of a Vector.</p>
+
+<h3><a class='u'
+name="push_all"
+>push_all</a></h3>
+
+<pre>$vector-&#62;push_all($other);</pre>
+
+<p>Push all the elements of another Vector onto the end of this one.</p>
+
+<h3><a class='u'
+name="pop"
+>pop</a></h3>
+
+<pre>my $obj = $vector-&#62;pop();</pre>
+
+<p>Pop an item off of the end of a Vector.</p>
+
+<p>Returns: the element or undef if the Vector is empty.</p>
+
+<h3><a class='u'
+name="insert"
+>insert</a></h3>
+
+<pre>$vector-&#62;insert(
+    tick    =&#62; $tick     # required
+    element =&#62; $element  # default: undef
+);</pre>
+
+<p>Insert an element at <code>tick</code> moving the following elements.</p>
+
+<h3><a class='u'
+name="insert_all"
+>insert_all</a></h3>
+
+<pre>$vector-&#62;insert_all(
+    tick  =&#62; $tick   # required
+    other =&#62; $other  # required
+);</pre>
+
+<p>Inserts elements from <code>other</code> vector at <code>tick</code> moving the following elements.</p>
+
+<h3><a class='u'
+name="fetch"
+>fetch</a></h3>
+
+<pre>my $obj = $vector-&#62;fetch($tick);</pre>
+
+<p>Fetch the element at <code>tick</code>.</p>
+
+<p>Returns: the element or undef if <code>tick</code> is out of bounds.</p>
+
+<h3><a class='u'
+name="store"
+>store</a></h3>
+
+<pre>$vector-&#62;store($tick, $elem)</pre>
+
+<p>Store an element at index <code>tick</code>,
+possibly displacing an existing element.</p>
+
+<h3><a class='u'
+name="delete"
+>delete</a></h3>
+
+<pre>my $obj = $vector-&#62;delete($tick);</pre>
+
+<p>Replace an element in the Vector with undef and return it.</p>
+
+<p>Returns: the element stored at <code>tick</code> or undef if <code>tick</code> is out of bounds.</p>
+
+<h3><a class='u'
+name="excise"
+>excise</a></h3>
+
+<pre>$vector-&#62;excise(
+    offset =&#62; $offset  # required
+    length =&#62; $length  # required
+);</pre>
+
+<p>Remove <code>length</code> elements from the Vector,
+starting at <code>offset</code>.
+Move elements over to fill in the gap.</p>
+
+<h3><a class='u'
+name="clone"
+>clone</a></h3>
+
+<pre>my $arrayref = $vector-&#62;clone();</pre>
+
+<p>Clone the Vector but merely increment the refcounts of its elements rather than clone them.</p>
+
+<h3><a class='u'
+name="sort"
+>sort</a></h3>
+
+<pre>$vector-&#62;sort();</pre>
+
+<p>Sort the Vector.
+Sort order is guaranteed to be <i>stable</i>: the relative order of elements which compare as equal will not change.</p>
+
+<h3><a class='u'
+name="resize"
+>resize</a></h3>
+
+<pre>$vector-&#62;resize($size);</pre>
+
+<p>Set the size for the Vector.
+If the new size is larger than the current size,
+grow the object to accommodate undef elements; if smaller than the current size,
+decrement and discard truncated elements.</p>
+
+<h3><a class='u'
+name="clear"
+>clear</a></h3>
+
+<pre>$vector-&#62;clear();</pre>
+
+<p>Empty the Vector.</p>
+
+<h3><a class='u'
+name="get_size"
+>get_size</a></h3>
+
+<pre>my $int = $vector-&#62;get_size();</pre>
+
+<p>Return the size of the Vector.</p>
+
+<h3><a class='u'
+name="slice"
+>slice</a></h3>
+
+<pre>my $arrayref = $vector-&#62;slice(
+    offset =&#62; $offset  # required
+    length =&#62; $length  # required
+);</pre>
+
+<p>Return a slice of the Vector consisting of elements from a contiguous range.
+If the specified range is out of bounds,
+return a slice with fewer elements &#8211; potentially none.</p>
+
+<ul>
+<li><b>offset</b> - The index of the element to start at.</li>
+
+<li><b>length</b> - The maximum number of elements to slice.</li>
+</ul>
+
+<h2><a class='u'
+name="INHERITANCE"
+>INHERITANCE</a></h2>
+
+<p>Clownfish::Vector isa <a href="../Clownfish/Obj.html" class="podlinkpod"
+>Clownfish::Obj</a>.</p>
+
+</div>