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 “symbiotic” object system pairs with “host” 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 “CFC” 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->new($byte_string); +my $byte_string = $blob->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->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->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->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->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->singleton($truth_value); +my $truth_value = $bool->get_value; + +if ($bool->equals($true_singleton)) { + print "true\n"; +}</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->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->get_value();</pre> + +<p>Return the value of the Boolean.</p> + +<h3><a class='u' +name="clone" +>clone</a></h3> + +<pre>my $result = $boolean->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->new($byte_string); +my $byte_string = $buf->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->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->set_size($size);</pre> + +<p>Resize the ByteBuf to <code>size</code>. +If greater than the object’s capacity, +throws an error.</p> + +<h3><a class='u' +name="get_size" +>get_size</a></h3> + +<pre>my $int = $byte_buf->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->get_capacity();</pre> + +<p>Return the number of bytes in the ByteBuf’s allocation.</p> + +<h3><a class='u' +name="cat" +>cat</a></h3> + +<pre>$byte_buf->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->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->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->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->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->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->new; +$buf->cat('abc'); +$buf->cat_char(ord("\n")); +print $buf->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->new( + capacity => $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->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->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->grow($capacity);</pre> + +<p>Assign more memory to the CharBuf, +if it doesn’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->clear();</pre> + +<p>Clear the CharBuf.</p> + +<h3><a class='u' +name="get_size" +>get_size</a></h3> + +<pre>my $int = $char_buf->get_size();</pre> + +<p>Return the size of the CharBuf’s content in bytes.</p> + +<h3><a class='u' +name="clone" +>clone</a></h3> + +<pre>my $result = $char_buf->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->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->fetch_class('Foo::Bar'); +my $subclass = Clownfish::Class->singleton('Foo::Bar::Jr', $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->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->singleton( + class_name => $class_name # required + parent => $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->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->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->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->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=<dir>] [--include=<dir>] [--parcel=<name>] + --dest=<dir> + [--header=<file>] [--footer=<file>]</pre> + +<h4><a class='u' +name="(8211)source" +>–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" +>–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’re required by a source parcel or if they’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" +>–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’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" +>–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" +>–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" +>–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’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 “short name macro” 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’t have to worry about parcel prefixes.</p> + +<p>Example:</p> + +<pre>#define CFISH_USE_SHORT_NAMES + +#include <Clownfish/String.h> +#include <Clownfish/Vector.h></pre> + +<h3><a class='u' +name="Function_and_method_prefixes" +>Function and method prefixes</a></h3> + +<p>Clownfish classes can have a “nickname” – 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 “inert” function of a class that returns a new object. +In Clownfish parlance, +an inert function is any function in a class that isn’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 "Str" in the constructor prefix. +String *name = Str_newf("%s %s", 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 "Str" 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 “incremented” object. +If you’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’t be destroyed too early:</p> + +<pre>obj = INCREF(obj);</pre> + +<p>This invocation of INCREF must be matched by a DECREF when you’re done with the object.</p> + +<p>Some methods, +for example in container classes, +take “decremented” objects as arguments. +From the caller’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’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 = "v" version-number +version-number = digit+ | digit+ "." 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>{ + "name": "Pathfinder", + "nickname": "Pfind", + "version": "v2.3.8", + "prerequisites": { + "Clownfish": "v0.5.0" + } +}</pre> + +<p>A parcel specifier of the following form is used in Clownfish header files:</p> + +<pre>parcel-specifier = "parcel" parcel-name ";" +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 <Pathfinder/Graph.h> +#include <Pathfinder/Path.h> + +/* 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 “Clownfish” 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* + "class" class-name + ("nickname" class-nickname)? + ("inherits" class-name)? + "{" class-contents "}" +class-exposure-specifier = "public" +class-modifier = "inert" | "final" +class-name = identifier | identifier "::" 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’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 ";" +variable-modifier = "inert" +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’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 "Pathfinder/Path.h" + +int +Path_get_num_nodes(Path *self) { + PathIVARS *ivars = Path_IVARS(self); + return ivars->num_nodes; +}</pre> + +<h3><a class='u' +name="Functions" +>Functions</a></h3> + +<pre>function-declaration = function-exposure-specifier? + function-modifier* + return-type function-name + "(" param-list? ")" ";" +function-exposure-specifier = "public" +function-modifier = "inert" | "inline" | "abstract" | "final" +return-type = return-type-qualifier* type +return-type-qualifier = "incremented" | "nullable" +function-name = identifier +param-list = param | param "," param-list +param = param-qualifier* type param-name ("=" scalar-constant)? +param-name = identifier +param-qualifier = "decremented"</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 "Pathfinder/Graph/VisibilityGraph.h" + +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’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’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’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 "Pathfinder/Graph/VisibilityGraph.h" + +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’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’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’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’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("Hello"); +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’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’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’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->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->value = INCREF(arg); + +DECREF(object);</pre> + +<h4><a class='u' +name="Object_destruction" +>Object destruction</a></h4> + +<p>If an object’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’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->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’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->throw("retry"); + }; + if ( blessed($@) and $@->isa("MyErr") ) { + warn "Retrying...\n"; + } + else { + # Re-throw. + die "do_stuff() died: $@"; + } +}</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->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->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->new(2.5); +my $value = $float->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->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->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->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->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->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->new; +$hash->store($key, $value); +my $value = $hash->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->new( + capacity => $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->clear();</pre> + +<p>Empty the hash of all key-value pairs.</p> + +<h3><a class='u' +name="store" +>store</a></h3> + +<pre>$hash->store($key, $value);</pre> + +<p>Store a key-value pair.</p> + +<h3><a class='u' +name="fetch" +>fetch</a></h3> + +<pre>my $obj = $hash->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->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->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->keys();</pre> + +<p>Return the Hash’s keys.</p> + +<h3><a class='u' +name="values" +>values</a></h3> + +<pre>my $arrayref = $hash->values();</pre> + +<p>Return the Hash’s values.</p> + +<h3><a class='u' +name="get_size" +>get_size</a></h3> + +<pre>my $int = $hash->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->new($hash); +while ($iter->next) { + my $key = $iter->get_key; + my $value = $iter->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->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->next();</pre> + +<p>Advance the iterator to the next key-value pair.</p> + +<p>Returns: true if there’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->get_key();</pre> + +<p>Return the key of the current key-value pair. +It’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->get_value();</pre> + +<p>Return the value of the current key-value pair. +It’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->new(7); +my $value = $integer->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->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->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->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->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->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->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->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 'foo' 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 "cached scalar id" stratagem recommended above isn'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->SUPER::new;</pre> + +<p>Abstract constructor -- must be invoked via a subclass. +Attempting to instantiate objects of class "Clownfish::Obj" 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->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->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->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->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->SUPER::DESTROY</code> to avoid leaking memory.</p> + +<h3><a class='u' +name="to_string" +>to_string</a></h3> + +<pre>my $string = $obj->to_string();</pre> + +<p>Generic stringification: “ClassName@hex_mem_address”.</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->new('abc'); +print $string->to_perl, "\n";</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->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->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->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->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->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->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->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->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->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->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->get_size();</pre> + +<p>Return the number of bytes occupied by the String’s internal content.</p> + +<h3><a class='u' +name="to_bytebuf" +>to_bytebuf</a></h3> + +<pre>my $byte_buf = $string->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->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->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->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->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->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->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->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->substring( + offset => $offset # required + length => $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->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->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->top; +while (my $code_point = $iter->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->clone();</pre> + +<p>Return a clone of the object.</p> + +<h3><a class='u' +name="assign" +>assign</a></h3> + +<pre>$string_iterator->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->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->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->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->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->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->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->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->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->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->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->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->new; +$vector->store($tick, $value); +my $value = $vector->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->new( + capacity => $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->push($element); +$vector->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->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->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->insert( + tick => $tick # required + element => $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->insert_all( + tick => $tick # required + other => $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->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->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->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->excise( + offset => $offset # required + length => $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->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->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->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->clear();</pre> + +<p>Empty the Vector.</p> + +<h3><a class='u' +name="get_size" +>get_size</a></h3> + +<pre>my $int = $vector->get_size();</pre> + +<p>Return the size of the Vector.</p> + +<h3><a class='u' +name="slice" +>slice</a></h3> + +<pre>my $arrayref = $vector->slice( + offset => $offset # required + length => $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 – 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>
