Author: nwellnhof Date: Mon Apr 4 12:55:10 2016 New Revision: 1737682 URL: http://svn.apache.org/viewvc?rev=1737682&view=rev Log: Add C API documentation for 0.5.0 release
Added: lucy/site/trunk/content/docs/c/ lucy/site/trunk/content/docs/c/Clownfish/ lucy/site/trunk/content/docs/c/Clownfish.mdtext lucy/site/trunk/content/docs/c/Clownfish/Blob.mdtext lucy/site/trunk/content/docs/c/Clownfish/Boolean.mdtext lucy/site/trunk/content/docs/c/Clownfish/ByteBuf.mdtext lucy/site/trunk/content/docs/c/Clownfish/CharBuf.mdtext lucy/site/trunk/content/docs/c/Clownfish/Class.mdtext lucy/site/trunk/content/docs/c/Clownfish/Docs/ lucy/site/trunk/content/docs/c/Clownfish/Docs/BuildingProjects.mdtext lucy/site/trunk/content/docs/c/Clownfish/Docs/ClassIntro.mdtext lucy/site/trunk/content/docs/c/Clownfish/Docs/WritingClasses.mdtext lucy/site/trunk/content/docs/c/Clownfish/Err.mdtext lucy/site/trunk/content/docs/c/Clownfish/Float.mdtext lucy/site/trunk/content/docs/c/Clownfish/Hash.mdtext lucy/site/trunk/content/docs/c/Clownfish/HashIterator.mdtext lucy/site/trunk/content/docs/c/Clownfish/Integer.mdtext lucy/site/trunk/content/docs/c/Clownfish/Obj.mdtext lucy/site/trunk/content/docs/c/Clownfish/String.mdtext lucy/site/trunk/content/docs/c/Clownfish/StringIterator.mdtext lucy/site/trunk/content/docs/c/Clownfish/Vector.mdtext lucy/site/trunk/content/docs/c/Lucy/ lucy/site/trunk/content/docs/c/Lucy/Analysis/ lucy/site/trunk/content/docs/c/Lucy/Analysis/Analyzer.mdtext lucy/site/trunk/content/docs/c/Lucy/Analysis/CaseFolder.mdtext lucy/site/trunk/content/docs/c/Lucy/Analysis/EasyAnalyzer.mdtext lucy/site/trunk/content/docs/c/Lucy/Analysis/Inversion.mdtext lucy/site/trunk/content/docs/c/Lucy/Analysis/Normalizer.mdtext lucy/site/trunk/content/docs/c/Lucy/Analysis/PolyAnalyzer.mdtext lucy/site/trunk/content/docs/c/Lucy/Analysis/RegexTokenizer.mdtext lucy/site/trunk/content/docs/c/Lucy/Analysis/SnowballStemmer.mdtext lucy/site/trunk/content/docs/c/Lucy/Analysis/SnowballStopFilter.mdtext lucy/site/trunk/content/docs/c/Lucy/Analysis/StandardTokenizer.mdtext lucy/site/trunk/content/docs/c/Lucy/Analysis/Token.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/ lucy/site/trunk/content/docs/c/Lucy/Docs/Cookbook/ lucy/site/trunk/content/docs/c/Lucy/Docs/Cookbook.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/Cookbook/CustomQuery.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/Cookbook/CustomQueryParser.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/Cookbook/FastUpdates.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/DevGuide.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/DocIDs.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/FileFormat.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/FileLocking.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/IRTheory.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/Tutorial/ lucy/site/trunk/content/docs/c/Lucy/Docs/Tutorial.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/Tutorial/AnalysisTutorial.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/Tutorial/BeyondSimpleTutorial.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/Tutorial/FieldTypeTutorial.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/Tutorial/HighlighterTutorial.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/Tutorial/QueryObjectsTutorial.mdtext lucy/site/trunk/content/docs/c/Lucy/Docs/Tutorial/SimpleTutorial.mdtext lucy/site/trunk/content/docs/c/Lucy/Document/ lucy/site/trunk/content/docs/c/Lucy/Document/Doc.mdtext lucy/site/trunk/content/docs/c/Lucy/Document/HitDoc.mdtext lucy/site/trunk/content/docs/c/Lucy/Highlight/ lucy/site/trunk/content/docs/c/Lucy/Highlight/Highlighter.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/ lucy/site/trunk/content/docs/c/Lucy/Index/BackgroundMerger.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/DataReader.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/DataWriter.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/DeletionsWriter.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/DocReader.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/IndexManager.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/IndexReader.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/Indexer.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/Lexicon.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/LexiconReader.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/PolyReader.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/PostingList.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/PostingListReader.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/SegReader.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/SegWriter.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/Segment.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/Similarity.mdtext lucy/site/trunk/content/docs/c/Lucy/Index/Snapshot.mdtext lucy/site/trunk/content/docs/c/Lucy/Object/ lucy/site/trunk/content/docs/c/Lucy/Object/BitVector.mdtext lucy/site/trunk/content/docs/c/Lucy/Object/I32Array.mdtext lucy/site/trunk/content/docs/c/Lucy/Plan/ lucy/site/trunk/content/docs/c/Lucy/Plan/Architecture.mdtext lucy/site/trunk/content/docs/c/Lucy/Plan/BlobType.mdtext lucy/site/trunk/content/docs/c/Lucy/Plan/FieldType.mdtext lucy/site/trunk/content/docs/c/Lucy/Plan/FullTextType.mdtext lucy/site/trunk/content/docs/c/Lucy/Plan/Schema.mdtext lucy/site/trunk/content/docs/c/Lucy/Plan/StringType.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/ lucy/site/trunk/content/docs/c/Lucy/Search/ANDQuery.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/Collector/ lucy/site/trunk/content/docs/c/Lucy/Search/Collector.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/Collector/BitCollector.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/Compiler.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/Hits.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/IndexSearcher.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/LeafQuery.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/MatchAllQuery.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/Matcher.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/NOTQuery.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/NoMatchQuery.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/ORQuery.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/PhraseQuery.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/PolyQuery.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/PolySearcher.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/Query.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/QueryParser.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/RangeQuery.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/RequiredOptionalQuery.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/Searcher.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/SortRule.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/SortSpec.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/Span.mdtext lucy/site/trunk/content/docs/c/Lucy/Search/TermQuery.mdtext lucy/site/trunk/content/docs/c/Lucy/Simple.mdtext lucy/site/trunk/content/docs/c/Lucy/Store/ lucy/site/trunk/content/docs/c/Lucy/Store/FSFolder.mdtext lucy/site/trunk/content/docs/c/Lucy/Store/Folder.mdtext lucy/site/trunk/content/docs/c/Lucy/Store/Lock.mdtext lucy/site/trunk/content/docs/c/Lucy/Store/LockErr.mdtext lucy/site/trunk/content/docs/c/Lucy/Store/LockFactory.mdtext lucy/site/trunk/content/docs/c/Lucy/Store/RAMFolder.mdtext lucy/site/trunk/content/docs/c/LucyX/ lucy/site/trunk/content/docs/c/LucyX/Search/ lucy/site/trunk/content/docs/c/LucyX/Search/ProximityQuery.mdtext lucy/site/trunk/content/docs/c/cfish.mdtext lucy/site/trunk/content/docs/c/lucy.mdtext Modified: lucy/site/trunk/content/css/lucy.css lucy/site/trunk/content/docs/index.mdtext Modified: lucy/site/trunk/content/css/lucy.css URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/css/lucy.css?rev=1737682&r1=1737681&r2=1737682&view=diff ============================================================================== --- lucy/site/trunk/content/css/lucy.css (original) +++ lucy/site/trunk/content/css/lucy.css Mon Apr 4 12:55:10 2016 @@ -128,3 +128,20 @@ pre, code { font-family: "Consolas", "Menlo", monospace; } +.c-api table { + border-collapse: collapse; +} +.c-api td { + padding: 0; +} +.c-api td.label { + padding-right: 2em; + font-weight: bold; +} +.c-api dt { + font-weight: bold; +} +.c-api span.prefix, .c-api span.comment { + color: #888; +} + Added: lucy/site/trunk/content/docs/c/Clownfish.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/c/Clownfish.mdtext?rev=1737682&view=auto ============================================================================== --- lucy/site/trunk/content/docs/c/Clownfish.mdtext (added) +++ lucy/site/trunk/content/docs/c/Clownfish.mdtext Mon Apr 4 12:55:10 2016 @@ -0,0 +1,74 @@ +Title: Clownfish + +<div class="c-api"> +<h2>Apache Clownfish symbiotic object system</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>Features</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>Planned features</h3> +<ul> +<li>Support for more host languages.</li> +<li>Support for interfaces.</li> +</ul> +<h3>Overview</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">Obj</a> class which is the root of the class hierarchy.</li> +<li>Core data types like <a href="Clownfish/String.html">strings</a>, +<a href="Clownfish/Vector.html">dynamic arrays</a>, and <a href="Clownfish/Hash.html">hashes</a>.</li> +<li>The <a href="Clownfish/Class.html">Class</a> metaclass.</li> +<li>Some helper classes.</li> +</ul> +<h3>Host language support</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>Help wanted</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">Lucy +developers mailing list</a>.</p> +<h3>Documentation</h3> +<ul> +<li><a href="Clownfish/Docs/ClassIntro.html">Working with Clownfish classes</a></li> +<li><a href="Clownfish/Docs/BuildingProjects.html">Building Clownfish projects in C environments</a></li> +<li><a href="Clownfish/Docs/WritingClasses.html">Writing Clownfish classes</a></li> +</ul> +</div> Added: lucy/site/trunk/content/docs/c/Clownfish/Blob.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/c/Clownfish/Blob.mdtext?rev=1737682&view=auto ============================================================================== --- lucy/site/trunk/content/docs/c/Clownfish/Blob.mdtext (added) +++ lucy/site/trunk/content/docs/c/Clownfish/Blob.mdtext Mon Apr 4 12:55:10 2016 @@ -0,0 +1,231 @@ +Title: Clownfish::Blob â C API Documentation + +<div class="c-api"> +<h2>Clownfish::Blob</h2> +<table> +<tr> +<td class="label">parcel</td> +<td><a href="../cfish.html">Clownfish</a></td> +</tr> +<tr> +<td class="label">class variable</td> +<td><code><span class="prefix">CFISH_</span>BLOB</code></td> +</tr> +<tr> +<td class="label">struct symbol</td> +<td><code><span class="prefix">cfish_</span>Blob</code></td> +</tr> +<tr> +<td class="label">class nickname</td> +<td><code><span class="prefix">cfish_</span>Blob</code></td> +</tr> +<tr> +<td class="label">header file</td> +<td><code>Clownfish/Blob.h</code></td> +</tr> +</table> +<h3>Name</h3> +<p>Clownfish::Blob â Immutable buffer holding arbitrary bytes.</p> +<h3>Functions</h3> +<dl> +<dt id="func_new">new</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Blob* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>Blob_new</strong>( + void *<strong>bytes</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Return a new Blob which holds a copy of the passed-in bytes.</p> +<dl> +<dt>bytes</dt> +<dd><p>Pointer to an array of bytes.</p> +</dd> +<dt>size</dt> +<dd><p>Size of the array in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_init">init</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Blob* +<span class="prefix">cfish_</span><strong>Blob_init</strong>( + <span class="prefix">cfish_</span>Blob *<strong>self</strong>, + void *<strong>bytes</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Initialize a Blob which holds a copy of the passed-in bytes.</p> +<dl> +<dt>bytes</dt> +<dd><p>Pointer to an array of bytes.</p> +</dd> +<dt>size</dt> +<dd><p>Size of the array in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_new_steal">new_steal</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Blob* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>Blob_new_steal</strong>( + void *<strong>bytes</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Return a new Blob which assumes ownership of the passed-in bytes.</p> +<dl> +<dt>bytes</dt> +<dd><p>Pointer to an array of bytes.</p> +</dd> +<dt>size</dt> +<dd><p>Size of the array in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_init_steal">init_steal</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Blob* +<span class="prefix">cfish_</span><strong>Blob_init_steal</strong>( + <span class="prefix">cfish_</span>Blob *<strong>self</strong>, + void *<strong>bytes</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Initialize a Blob which assumes ownership of the passed-in bytes.</p> +<dl> +<dt>bytes</dt> +<dd><p>Pointer to an array of bytes.</p> +</dd> +<dt>size</dt> +<dd><p>Size of the array in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_new_wrap">new_wrap</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Blob* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>Blob_new_wrap</strong>( + void *<strong>bytes</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Return a new Blob which wraps an external buffer. The buffer must +stay unchanged for the lifetime of the Blob.</p> +<dl> +<dt>bytes</dt> +<dd><p>Pointer to an array of bytes.</p> +</dd> +<dt>size</dt> +<dd><p>Size of the array in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_init_wrap">init_wrap</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Blob* +<span class="prefix">cfish_</span><strong>Blob_init_wrap</strong>( + <span class="prefix">cfish_</span>Blob *<strong>self</strong>, + void *<strong>bytes</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Initialize a Blob which wraps an external buffer. The buffer must +stay unchanged for the lifetime of the Blob.</p> +<dl> +<dt>bytes</dt> +<dd><p>Pointer to an array of bytes.</p> +</dd> +<dt>size</dt> +<dd><p>Size of the array in bytes.</p> +</dd> +</dl> +</dd> +</dl> +<h3>Methods</h3> +<dl> +<dt id="func_Get_Size">Get_Size</dt> +<dd> +<pre><code>size_t +<span class="prefix">cfish_</span><strong>Blob_Get_Size</strong>( + <span class="prefix">cfish_</span>Blob *<strong>self</strong> +); +</code></pre> +<p>Return the number of bytes held by the Blob.</p> +</dd> +<dt id="func_Get_Buf">Get_Buf</dt> +<dd> +<pre><code>char* +<span class="prefix">cfish_</span><strong>Blob_Get_Buf</strong>( + <span class="prefix">cfish_</span>Blob *<strong>self</strong> +); +</code></pre> +<p>Accessor for raw internal buffer.</p> +</dd> +<dt id="func_Equals">Equals</dt> +<dd> +<pre><code>bool +<span class="prefix">cfish_</span><strong>Blob_Equals</strong>( + <span class="prefix">cfish_</span>Blob *<strong>self</strong>, + <span class="prefix">cfish_</span><a href="../Clownfish/Obj.html">Obj</a> *<strong>other</strong> +); +</code></pre> +<p>Equality test.</p> +<p><strong>Returns:</strong> true if <code>other</code> is a Blob and has the same content as <code>self</code>.</p> +</dd> +<dt id="func_Equals_Bytes">Equals_Bytes</dt> +<dd> +<pre><code>bool +<span class="prefix">cfish_</span><strong>Blob_Equals_Bytes</strong>( + <span class="prefix">cfish_</span>Blob *<strong>self</strong>, + void *<strong>bytes</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Test whether the Blob matches the passed-in bytes.</p> +<dl> +<dt>bytes</dt> +<dd><p>Pointer to an array of bytes.</p> +</dd> +<dt>size</dt> +<dd><p>Size of the array in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_Compare_To">Compare_To</dt> +<dd> +<pre><code>int32_t +<span class="prefix">cfish_</span><strong>Blob_Compare_To</strong>( + <span class="prefix">cfish_</span>Blob *<strong>self</strong>, + <span class="prefix">cfish_</span><a href="../Clownfish/Obj.html">Obj</a> *<strong>other</strong> +); +</code></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><strong>Returns:</strong> 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> +</dd> +<dt id="func_Clone">Clone</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Blob* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>Blob_Clone</strong>( + <span class="prefix">cfish_</span>Blob *<strong>self</strong> +); +</code></pre> +<p>Return a clone of the object.</p> +</dd> +<dt id="func_Destroy">Destroy</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>Blob_Destroy</strong>( + <span class="prefix">cfish_</span>Blob *<strong>self</strong> +); +</code></pre> +<p>Generic destructor. Frees the struct itself but not any complex +member elements.</p> +</dd> +</dl> +<h3>Inheritance</h3> +<p>Clownfish::Blob is a <a href="../Clownfish/Obj.html">Clownfish::Obj</a>.</p> +</div> Added: lucy/site/trunk/content/docs/c/Clownfish/Boolean.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/c/Clownfish/Boolean.mdtext?rev=1737682&view=auto ============================================================================== --- lucy/site/trunk/content/docs/c/Clownfish/Boolean.mdtext (added) +++ lucy/site/trunk/content/docs/c/Clownfish/Boolean.mdtext Mon Apr 4 12:55:10 2016 @@ -0,0 +1,98 @@ +Title: Clownfish::Boolean â C API Documentation + +<div class="c-api"> +<h2>Clownfish::Boolean</h2> +<table> +<tr> +<td class="label">parcel</td> +<td><a href="../cfish.html">Clownfish</a></td> +</tr> +<tr> +<td class="label">class variable</td> +<td><code><span class="prefix">CFISH_</span>BOOLEAN</code></td> +</tr> +<tr> +<td class="label">struct symbol</td> +<td><code><span class="prefix">cfish_</span>Boolean</code></td> +</tr> +<tr> +<td class="label">class nickname</td> +<td><code><span class="prefix">cfish_</span>Bool</code></td> +</tr> +<tr> +<td class="label">header file</td> +<td><code>Clownfish/Boolean.h</code></td> +</tr> +</table> +<h3>Name</h3> +<p>Clownfish::Boolean â Boolean type.</p> +<h3>Description</h3> +<p>There are only two singleton instances of this class: CFISH_TRUE and +CFISH_FALSE.</p> +<h3>Functions</h3> +<dl> +<dt id="func_singleton">singleton</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Boolean* +<span class="prefix">cfish_</span><strong>Bool_singleton</strong>( + bool <strong>value</strong> +); +</code></pre> +<p>Return either CFISH_TRUE or CFISH_FALSE depending on the supplied +value.</p> +</dd> +</dl> +<h3>Methods</h3> +<dl> +<dt id="func_Get_Value">Get_Value</dt> +<dd> +<pre><code>bool +<span class="prefix">cfish_</span><strong>Bool_Get_Value</strong>( + <span class="prefix">cfish_</span>Boolean *<strong>self</strong> +); +</code></pre> +<p>Return the value of the Boolean.</p> +</dd> +<dt id="func_Clone">Clone</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Boolean* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>Bool_Clone</strong>( + <span class="prefix">cfish_</span>Boolean *<strong>self</strong> +); +</code></pre> +<p>Return a clone of the object.</p> +</dd> +<dt id="func_Equals">Equals</dt> +<dd> +<pre><code>bool +<span class="prefix">cfish_</span><strong>Bool_Equals</strong>( + <span class="prefix">cfish_</span>Boolean *<strong>self</strong>, + <span class="prefix">cfish_</span><a href="../Clownfish/Obj.html">Obj</a> *<strong>other</strong> +); +</code></pre> +<p>Equality test.</p> +<p><strong>Returns:</strong> true if <code>other</code> is a Boolean with the same value as <code>self</code>.</p> +</dd> +<dt id="func_To_String">To_String</dt> +<dd> +<pre><code><span class="prefix">cfish_</span><a href="../Clownfish/String.html">String</a>* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>Bool_To_String</strong>( + <span class="prefix">cfish_</span>Boolean *<strong>self</strong> +); +</code></pre> +<p>Return âtrueâ for true values and âfalseâ for false values.</p> +</dd> +<dt id="func_Destroy">Destroy</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>Bool_Destroy</strong>( + <span class="prefix">cfish_</span>Boolean *<strong>self</strong> +); +</code></pre> +<p>Generic destructor. Frees the struct itself but not any complex +member elements.</p> +</dd> +</dl> +<h3>Inheritance</h3> +<p>Clownfish::Boolean is a <a href="../Clownfish/Obj.html">Clownfish::Obj</a>.</p> +</div> Added: lucy/site/trunk/content/docs/c/Clownfish/ByteBuf.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/c/Clownfish/ByteBuf.mdtext?rev=1737682&view=auto ============================================================================== --- lucy/site/trunk/content/docs/c/Clownfish/ByteBuf.mdtext (added) +++ lucy/site/trunk/content/docs/c/Clownfish/ByteBuf.mdtext Mon Apr 4 12:55:10 2016 @@ -0,0 +1,327 @@ +Title: Clownfish::ByteBuf â C API Documentation + +<div class="c-api"> +<h2>Clownfish::ByteBuf</h2> +<table> +<tr> +<td class="label">parcel</td> +<td><a href="../cfish.html">Clownfish</a></td> +</tr> +<tr> +<td class="label">class variable</td> +<td><code><span class="prefix">CFISH_</span>BYTEBUF</code></td> +</tr> +<tr> +<td class="label">struct symbol</td> +<td><code><span class="prefix">cfish_</span>ByteBuf</code></td> +</tr> +<tr> +<td class="label">class nickname</td> +<td><code><span class="prefix">cfish_</span>BB</code></td> +</tr> +<tr> +<td class="label">header file</td> +<td><code>Clownfish/ByteBuf.h</code></td> +</tr> +</table> +<h3>Name</h3> +<p>Clownfish::ByteBuf â Growable buffer holding arbitrary bytes.</p> +<h3>Functions</h3> +<dl> +<dt id="func_new">new</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>ByteBuf* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>BB_new</strong>( + size_t <strong>capacity</strong> +); +</code></pre> +<p>Return a new zero-sized ByteBuf.</p> +<dl> +<dt>capacity</dt> +<dd><p>Initial minimum capacity of the ByteBuf, in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_init">init</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>ByteBuf* +<span class="prefix">cfish_</span><strong>BB_init</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong>, + size_t <strong>capacity</strong> +); +</code></pre> +<p>Initialize a ByteBuf.</p> +<dl> +<dt>capacity</dt> +<dd><p>Initial minimum capacity of the ByteBuf, in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_new_bytes">new_bytes</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>ByteBuf* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>BB_new_bytes</strong>( + void *<strong>bytes</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Return a new ByteBuf which holds a copy of the passed-in bytes.</p> +<dl> +<dt>bytes</dt> +<dd><p>Pointer to an array of bytes.</p> +</dd> +<dt>size</dt> +<dd><p>Size of the array in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_init_bytes">init_bytes</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>ByteBuf* +<span class="prefix">cfish_</span><strong>BB_init_bytes</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong>, + void *<strong>bytes</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Initialize a ByteBuf which holds a copy of the passed-in bytes.</p> +<dl> +<dt>bytes</dt> +<dd><p>Pointer to an array of bytes.</p> +</dd> +<dt>size</dt> +<dd><p>Size of the array in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_new_steal_bytes">new_steal_bytes</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>ByteBuf* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>BB_new_steal_bytes</strong>( + void *<strong>bytes</strong>, + size_t <strong>size</strong>, + size_t <strong>capacity</strong> +); +</code></pre> +<p>Return a new ByteBuf which assumes ownership of the passed-in string.</p> +<dl> +<dt>bytes</dt> +<dd><p>Pointer to an array of bytes.</p> +</dd> +<dt>size</dt> +<dd><p>Initial size of the ByteBuf in bytes.</p> +</dd> +<dt>capacity</dt> +<dd><p>Total allocated bytes in the array.</p> +</dd> +</dl> +</dd> +<dt id="func_init_steal_bytes">init_steal_bytes</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>ByteBuf* +<span class="prefix">cfish_</span><strong>BB_init_steal_bytes</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong>, + void *<strong>bytes</strong>, + size_t <strong>size</strong>, + size_t <strong>capacity</strong> +); +</code></pre> +<p>Initialize a ByteBuf and assume ownership of the passed-in string.</p> +<dl> +<dt>bytes</dt> +<dd><p>Pointer to an array of bytes.</p> +</dd> +<dt>size</dt> +<dd><p>Initial size of the ByteBuf in bytes.</p> +</dd> +<dt>capacity</dt> +<dd><p>Total allocated bytes in the array.</p> +</dd> +</dl> +</dd> +</dl> +<h3>Methods</h3> +<dl> +<dt id="func_Set_Size">Set_Size</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>BB_Set_Size</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Resize the ByteBuf to <code>size</code>. If greater than the objectâs capacity, +throws an error.</p> +</dd> +<dt id="func_Get_Size">Get_Size</dt> +<dd> +<pre><code>size_t +<span class="prefix">cfish_</span><strong>BB_Get_Size</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong> +); +</code></pre> +<p>Return the size of the ByteBuf in bytes.</p> +</dd> +<dt id="func_Get_Buf">Get_Buf</dt> +<dd> +<pre><code>char* +<span class="prefix">cfish_</span><strong>BB_Get_Buf</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong> +); +</code></pre> +<p>Accessor for raw internal buffer.</p> +</dd> +<dt id="func_Get_Capacity">Get_Capacity</dt> +<dd> +<pre><code>size_t +<span class="prefix">cfish_</span><strong>BB_Get_Capacity</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong> +); +</code></pre> +<p>Return the number of bytes in the ByteBufâs allocation.</p> +</dd> +<dt id="func_Cat_Bytes">Cat_Bytes</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>BB_Cat_Bytes</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong>, + void *<strong>bytes</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Concatenate the passed-in bytes onto the end of the ByteBuf. Allocate +more memory as needed.</p> +<dl> +<dt>bytes</dt> +<dd><p>Pointer to an array of bytes.</p> +</dd> +<dt>size</dt> +<dd><p>Size of the array in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_Cat">Cat</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>BB_Cat</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong>, + <span class="prefix">cfish_</span><a href="../Clownfish/Blob.html">Blob</a> *<strong>blob</strong> +); +</code></pre> +<p>Concatenate the contents of <a href="../Clownfish/Blob.html">Blob</a> <code>blob</code> onto the end of the +original ByteBuf. Allocate more memory as needed.</p> +</dd> +<dt id="func_Grow">Grow</dt> +<dd> +<pre><code>char* +<span class="prefix">cfish_</span><strong>BB_Grow</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong>, + size_t <strong>capacity</strong> +); +</code></pre> +<p>Assign more memory to the ByteBuf, if it doesnât already have enough +room to hold <code>capacity</code> bytes. Cannot shrink the allocation.</p> +<dl> +<dt>capacity</dt> +<dd><p>The new minimum capacity of the ByteBuf.</p> +</dd> +</dl> +<p><strong>Returns:</strong> a pointer to the raw buffer.</p> +</dd> +<dt id="func_Yield_Blob">Yield_Blob</dt> +<dd> +<pre><code><span class="prefix">cfish_</span><a href="../Clownfish/Blob.html">Blob</a>* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>BB_Yield_Blob</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong> +); +</code></pre> +<p>Return the content of the ByteBuf as <a href="../Clownfish/Blob.html">Blob</a> and clear the ByteBuf.</p> +</dd> +<dt id="func_Utf8_To_String">Utf8_To_String</dt> +<dd> +<pre><code><span class="prefix">cfish_</span><a href="../Clownfish/String.html">String</a>* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>BB_Utf8_To_String</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong> +); +</code></pre> +<p>Return a String which holds a copy of the UTF-8 character data in +the ByteBuf after checking for validity.</p> +</dd> +<dt id="func_Trusted_Utf8_To_String">Trusted_Utf8_To_String</dt> +<dd> +<pre><code><span class="prefix">cfish_</span><a href="../Clownfish/String.html">String</a>* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>BB_Trusted_Utf8_To_String</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong> +); +</code></pre> +<p>Return a String which holds a copy of the UTF-8 character data in +the ByteBuf, skipping validity checks.</p> +</dd> +<dt id="func_Equals">Equals</dt> +<dd> +<pre><code>bool +<span class="prefix">cfish_</span><strong>BB_Equals</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong>, + <span class="prefix">cfish_</span><a href="../Clownfish/Obj.html">Obj</a> *<strong>other</strong> +); +</code></pre> +<p>Equality test.</p> +<p><strong>Returns:</strong> true if <code>other</code> is a ByteBuf with the same content as <code>self</code>.</p> +</dd> +<dt id="func_Equals_Bytes">Equals_Bytes</dt> +<dd> +<pre><code>bool +<span class="prefix">cfish_</span><strong>BB_Equals_Bytes</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong>, + void *<strong>bytes</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Test whether the ByteBuf matches the passed-in bytes.</p> +<dl> +<dt>bytes</dt> +<dd><p>Pointer to an array of bytes.</p> +</dd> +<dt>size</dt> +<dd><p>Size of the array in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_Compare_To">Compare_To</dt> +<dd> +<pre><code>int32_t +<span class="prefix">cfish_</span><strong>BB_Compare_To</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong>, + <span class="prefix">cfish_</span><a href="../Clownfish/Obj.html">Obj</a> *<strong>other</strong> +); +</code></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><strong>Returns:</strong> 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> +</dd> +<dt id="func_Clone">Clone</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>ByteBuf* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>BB_Clone</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong> +); +</code></pre> +<p>Return a clone of the object.</p> +</dd> +<dt id="func_Destroy">Destroy</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>BB_Destroy</strong>( + <span class="prefix">cfish_</span>ByteBuf *<strong>self</strong> +); +</code></pre> +<p>Generic destructor. Frees the struct itself but not any complex +member elements.</p> +</dd> +</dl> +<h3>Inheritance</h3> +<p>Clownfish::ByteBuf is a <a href="../Clownfish/Obj.html">Clownfish::Obj</a>.</p> +</div> Added: lucy/site/trunk/content/docs/c/Clownfish/CharBuf.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/c/Clownfish/CharBuf.mdtext?rev=1737682&view=auto ============================================================================== --- lucy/site/trunk/content/docs/c/Clownfish/CharBuf.mdtext (added) +++ lucy/site/trunk/content/docs/c/Clownfish/CharBuf.mdtext Mon Apr 4 12:55:10 2016 @@ -0,0 +1,253 @@ +Title: Clownfish::CharBuf â C API Documentation + +<div class="c-api"> +<h2>Clownfish::CharBuf</h2> +<table> +<tr> +<td class="label">parcel</td> +<td><a href="../cfish.html">Clownfish</a></td> +</tr> +<tr> +<td class="label">class variable</td> +<td><code><span class="prefix">CFISH_</span>CHARBUF</code></td> +</tr> +<tr> +<td class="label">struct symbol</td> +<td><code><span class="prefix">cfish_</span>CharBuf</code></td> +</tr> +<tr> +<td class="label">class nickname</td> +<td><code><span class="prefix">cfish_</span>CB</code></td> +</tr> +<tr> +<td class="label">header file</td> +<td><code>Clownfish/CharBuf.h</code></td> +</tr> +</table> +<h3>Name</h3> +<p>Clownfish::CharBuf â Growable buffer holding Unicode characters.</p> +<h3>Functions</h3> +<dl> +<dt id="func_new">new</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>CharBuf* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>CB_new</strong>( + size_t <strong>capacity</strong> +); +</code></pre> +<p>Return a new CharBuf.</p> +<dl> +<dt>capacity</dt> +<dd><p>Initial minimum capacity of the CharBuf, in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_init">init</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>CharBuf* +<span class="prefix">cfish_</span><strong>CB_init</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong>, + size_t <strong>capacity</strong> +); +</code></pre> +<p>Initialize a CharBuf.</p> +<dl> +<dt>capacity</dt> +<dd><p>Initial minimum capacity of the CharBuf, in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_catf">catf</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>CB_catf</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong>, + char *<strong>pattern</strong> +); +</code></pre> +<p>Invokes <a href="../Clownfish/CharBuf.html#func_VCatF">VCatF()</a> to concatenate formatted arguments. Note that this +is only a function and not a method.</p> +<dl> +<dt>pattern</dt> +<dd><p>The format string.</p> +</dd> +</dl> +</dd> +</dl> +<h3>Methods</h3> +<dl> +<dt id="func_Cat_Utf8">Cat_Utf8</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>CB_Cat_Utf8</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong>, + char *<strong>utf8</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Concatenate the passed-in string onto the end of the CharBuf.</p> +<dl> +<dt>utf8</dt> +<dd><p>Pointer to UTF-8 character data.</p> +</dd> +<dt>size</dt> +<dd><p>Size of UTF-8 character data in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_Cat_Trusted_Utf8">Cat_Trusted_Utf8</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>CB_Cat_Trusted_Utf8</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong>, + char *<strong>utf8</strong>, + size_t <strong>size</strong> +); +</code></pre> +<p>Concatenate the supplied text onto the end of the CharBuf. Donât +check for UTF-8 validity.</p> +<dl> +<dt>utf8</dt> +<dd><p>Pointer to UTF-8 character data.</p> +</dd> +<dt>size</dt> +<dd><p>Size of UTF-8 character data in bytes.</p> +</dd> +</dl> +</dd> +<dt id="func_Cat">Cat</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>CB_Cat</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong>, + <span class="prefix">cfish_</span><a href="../Clownfish/String.html">String</a> *<strong>string</strong> +); +</code></pre> +<p>Concatenate the contents of <a href="../Clownfish/String.html">String</a> <code>string</code> onto the end of the +caller.</p> +<dl> +<dt>string</dt> +<dd><p>The String to concatenate.</p> +</dd> +</dl> +</dd> +<dt id="func_VCatF">VCatF</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>CB_VCatF</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong>, + char *<strong>pattern</strong>, + va_list <strong>args</strong> +); +</code></pre> +<p>Concatenate formatted arguments. Similar to the printf family, but +only accepts minimal options (just enough for decent error messages).</p> +<pre><code>Objects: %o +char*: %s +integers: %i8 %i32 %i64 %u8 %u32 %u64 +floats: %f64 +hex: %x32 +</code></pre> +<p>Note that all Clownfish Objects, including Strings, are printed via +<code>%o</code> (which invokes <a href="../Clownfish/Obj.html#func_To_String">To_String()</a>).</p> +<dl> +<dt>pattern</dt> +<dd><p>The format string.</p> +</dd> +<dt>args</dt> +<dd><p>A <code>va_list</code> containing the arguments.</p> +</dd> +</dl> +</dd> +<dt id="func_Cat_Char">Cat_Char</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>CB_Cat_Char</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong>, + int32_t <strong>code_point</strong> +); +</code></pre> +<p>Concatenate one Unicode character onto the end of the CharBuf.</p> +<dl> +<dt>code_point</dt> +<dd><p>The code point of the Unicode character.</p> +</dd> +</dl> +</dd> +<dt id="func_Grow">Grow</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>CB_Grow</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong>, + size_t <strong>capacity</strong> +); +</code></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> +<dl> +<dt>capacity</dt> +<dd><p>The new minimum capacity of the ByteBuf.</p> +</dd> +</dl> +</dd> +<dt id="func_Clear">Clear</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>CB_Clear</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong> +); +</code></pre> +<p>Clear the CharBuf.</p> +</dd> +<dt id="func_Get_Size">Get_Size</dt> +<dd> +<pre><code>size_t +<span class="prefix">cfish_</span><strong>CB_Get_Size</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong> +); +</code></pre> +<p>Return the size of the CharBufâs content in bytes.</p> +</dd> +<dt id="func_Clone">Clone</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>CharBuf* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>CB_Clone</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong> +); +</code></pre> +<p>Return a clone of the object.</p> +</dd> +<dt id="func_To_String">To_String</dt> +<dd> +<pre><code><span class="prefix">cfish_</span><a href="../Clownfish/String.html">String</a>* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>CB_To_String</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong> +); +</code></pre> +<p>Return the content of the CharBuf as String.</p> +</dd> +<dt id="func_Yield_String">Yield_String</dt> +<dd> +<pre><code><span class="prefix">cfish_</span><a href="../Clownfish/String.html">String</a>* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>CB_Yield_String</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong> +); +</code></pre> +<p>Return the content of the CharBuf as <a href="../Clownfish/String.html">String</a> and clear the CharBuf. +This is more efficient than <a href="../Clownfish/CharBuf.html#func_To_String">To_String()</a>.</p> +</dd> +<dt id="func_Destroy">Destroy</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>CB_Destroy</strong>( + <span class="prefix">cfish_</span>CharBuf *<strong>self</strong> +); +</code></pre> +<p>Generic destructor. Frees the struct itself but not any complex +member elements.</p> +</dd> +</dl> +<h3>Inheritance</h3> +<p>Clownfish::CharBuf is a <a href="../Clownfish/Obj.html">Clownfish::Obj</a>.</p> +</div> Added: lucy/site/trunk/content/docs/c/Clownfish/Class.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/c/Clownfish/Class.mdtext?rev=1737682&view=auto ============================================================================== --- lucy/site/trunk/content/docs/c/Clownfish/Class.mdtext (added) +++ lucy/site/trunk/content/docs/c/Clownfish/Class.mdtext Mon Apr 4 12:55:10 2016 @@ -0,0 +1,135 @@ +Title: Clownfish::Class â C API Documentation + +<div class="c-api"> +<h2>Clownfish::Class</h2> +<table> +<tr> +<td class="label">parcel</td> +<td><a href="../cfish.html">Clownfish</a></td> +</tr> +<tr> +<td class="label">class variable</td> +<td><code><span class="prefix">CFISH_</span>CLASS</code></td> +</tr> +<tr> +<td class="label">struct symbol</td> +<td><code><span class="prefix">cfish_</span>Class</code></td> +</tr> +<tr> +<td class="label">class nickname</td> +<td><code><span class="prefix">cfish_</span>Class</code></td> +</tr> +<tr> +<td class="label">header file</td> +<td><code>Clownfish/Class.h</code></td> +</tr> +</table> +<h3>Name</h3> +<p>Clownfish::Class â Class.</p> +<h3>Description</h3> +<p>Classes are first-class objects in Clownfish. Class objects are instances +of Clownfish::Class.</p> +<h3>Functions</h3> +<dl> +<dt id="func_singleton">singleton</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Class* +<span class="prefix">cfish_</span><strong>Class_singleton</strong>( + <span class="prefix">cfish_</span><a href="../Clownfish/String.html">String</a> *<strong>class_name</strong>, + <span class="prefix">cfish_</span>Class *<strong>parent</strong> +); +</code></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 NULL, an attempt will be made to find it. If the +attempt fails, an error will result.</p> +</dd> +<dt id="func_fetch_class">fetch_class</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Class* +<span class="prefix">cfish_</span><strong>Class_fetch_class</strong>( + <span class="prefix">cfish_</span><a href="../Clownfish/String.html">String</a> *<strong>class_name</strong> +); +</code></pre> +<p>Find a registered class. May return NULL if the class is not +registered.</p> +</dd> +</dl> +<h3>Methods</h3> +<dl> +<dt id="func_Override">Override</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>Class_Override</strong>( + <span class="prefix">cfish_</span>Class *<strong>self</strong>, + cfish_method_t <strong>method_ptr</strong>, + uint32_t <strong>offset</strong> +); +</code></pre> +<p>Replace a function pointer in the Classâs vtable.</p> +</dd> +<dt id="func_Make_Obj">Make_Obj</dt> +<dd> +<pre><code><span class="prefix">cfish_</span><a href="../Clownfish/Obj.html">Obj</a>* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>Class_Make_Obj</strong>( + <span class="prefix">cfish_</span>Class *<strong>self</strong> +); +</code></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> +</dd> +<dt id="func_Init_Obj">Init_Obj</dt> +<dd> +<pre><code><span class="prefix">cfish_</span><a href="../Clownfish/Obj.html">Obj</a>* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>Class_Init_Obj</strong>( + <span class="prefix">cfish_</span>Class *<strong>self</strong>, + void *<strong>allocation</strong> +); +</code></pre> +<p>Take a raw memory allocation which is presumed to be of adequate size, +assign its class and give it an initial refcount of 1.</p> +</dd> +<dt id="func_Get_Name">Get_Name</dt> +<dd> +<pre><code><span class="prefix">cfish_</span><a href="../Clownfish/String.html">String</a>* +<span class="prefix">cfish_</span><strong>Class_Get_Name</strong>( + <span class="prefix">cfish_</span>Class *<strong>self</strong> +); +</code></pre> +<p>Return the name of the class.</p> +</dd> +<dt id="func_Get_Parent">Get_Parent</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Class* +<span class="prefix">cfish_</span><strong>Class_Get_Parent</strong>( + <span class="prefix">cfish_</span>Class *<strong>self</strong> +); +</code></pre> +<p>Return the parent class, or NULL for a root of the class +hierarchy.</p> +</dd> +<dt id="func_Get_Obj_Alloc_Size">Get_Obj_Alloc_Size</dt> +<dd> +<pre><code>uint32_t +<span class="prefix">cfish_</span><strong>Class_Get_Obj_Alloc_Size</strong>( + <span class="prefix">cfish_</span>Class *<strong>self</strong> +); +</code></pre> +<p>Return the number of bytes needed to hold an instance of the class.</p> +</dd> +<dt id="func_Destroy">Destroy</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>Class_Destroy</strong>( + <span class="prefix">cfish_</span>Class *<strong>self</strong> +); +</code></pre> +<p>Generic destructor. Frees the struct itself but not any complex +member elements.</p> +</dd> +</dl> +<h3>Inheritance</h3> +<p>Clownfish::Class is a <a href="../Clownfish/Obj.html">Clownfish::Obj</a>.</p> +</div> Added: lucy/site/trunk/content/docs/c/Clownfish/Docs/BuildingProjects.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/c/Clownfish/Docs/BuildingProjects.mdtext?rev=1737682&view=auto ============================================================================== --- lucy/site/trunk/content/docs/c/Clownfish/Docs/BuildingProjects.mdtext (added) +++ lucy/site/trunk/content/docs/c/Clownfish/Docs/BuildingProjects.mdtext Mon Apr 4 12:55:10 2016 @@ -0,0 +1,89 @@ +Title: Clownfish::Docs::BuildingProjects + +<div class="c-api"> +<h2>Building Apache Clownfish projects in C environments</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">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>Running cfc</h3> +<pre><code>cfc [--source=<dir>] [--include=<dir>] [--parcel=<name>] + --dest=<dir> + [--header=<file>] [--footer=<file>] +</code></pre> +<h4>âsource</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>âinclude</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>âparcel</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><code>cfc --parcel=Clownfish --dest=autogen +</code></pre> +<p>This option may be specified multiple times.</p> +<h4>âdest</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>âheader</h4> +<p>Specifies a file whose contents are added as a comment on top of +each generated file.</p> +<h4>âfooter</h4> +<p>Specifies a file whose contents are added as a comment on the +bottom of each generated file.</p> +<h3>Including the generated C headers</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>Compiling the generated source files</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>Linking</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/c/Clownfish/Docs/ClassIntro.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/c/Clownfish/Docs/ClassIntro.mdtext?rev=1737682&view=auto ============================================================================== --- lucy/site/trunk/content/docs/c/Clownfish/Docs/ClassIntro.mdtext (added) +++ lucy/site/trunk/content/docs/c/Clownfish/Docs/ClassIntro.mdtext Mon Apr 4 12:55:10 2016 @@ -0,0 +1,75 @@ +Title: Clownfish::Docs::ClassIntro + +<div class="c-api"> +<h2>Working with Apache Clownfish classes in C</h2> +<h3>Inititalizing Clownfish parcels</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><code>cfish_bootstrap_parcel(); +</code></pre> +<h3>Including the generated header file</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><code>#define CFISH_USE_SHORT_NAMES + +#include <Clownfish/String.h> +#include <Clownfish/Vector.h> +</code></pre> +<h3>Function and method prefixes</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>Creating objects</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><code>// Notice the use of nickname "Str" in the constructor prefix. +String *name = Str_newf("%s %s", first, last); +</code></pre> +<h3>Calling methods</h3> +<p>Calling methods is straightforward. The invocant is always passed as +first argument.</p> +<pre><code>// Notice the use of nickname "Str" in the method prefix. +size_t len = Str_Length(name); +</code></pre> +<p>Method names always start with an uppercase letter.</p> +<h3>Memory management</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><code>DECREF(name); +</code></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><code>obj = INCREF(obj); +</code></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>Further reading</h3> +<ul> +<li><a href="../../Clownfish/Docs/BuildingProjects.html">Building Clownfish projects in C environments</a></li> +<li><a href="../../Clownfish/Docs/WritingClasses.html">Writing Clownfish classes</a></li> +</ul> +</div> Added: lucy/site/trunk/content/docs/c/Clownfish/Docs/WritingClasses.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/c/Clownfish/Docs/WritingClasses.mdtext?rev=1737682&view=auto ============================================================================== --- lucy/site/trunk/content/docs/c/Clownfish/Docs/WritingClasses.mdtext (added) +++ lucy/site/trunk/content/docs/c/Clownfish/Docs/WritingClasses.mdtext Mon Apr 4 12:55:10 2016 @@ -0,0 +1,479 @@ +Title: Clownfish::Docs::WritingClasses + +<div class="c-api"> +<h2>Writing Apache Clownfish classes</h2> +<h3>Parcels</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> +<p><strong>name:</strong> The parcelâs name. It must contain only letters.</p> +</li> +<li> +<p><strong>nickname:</strong> 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.</p> +</li> +<li> +<p><strong>version:</strong> A version specifier of the following form (without whitespace):</p> +<pre><code>version-specifier = "v" version-number +version-number = digit+ | digit+ "." version-number +</code></pre> +</li> +<li> +<p><strong>prerequisites:</strong> A hash containing the prerequisite parcels. The hash keys +are the parcel names. The values contain the minimum required version.</p> +</li> +</ul> +<p>An example <code>.cfp</code> file might look like:</p> +<pre><code>{ + "name": "Pathfinder", + "nickname": "Pfind", + "version": "v2.3.8", + "prerequisites": { + "Clownfish": "v0.5.0" + } +} +</code></pre> +<p>A parcel specifier of the following form is used in Clownfish header files:</p> +<pre><code>parcel-specifier = "parcel" parcel-name ";" +parcel-name = identifier +</code></pre> +<p>For example:</p> +<pre><code>parcel Pathfinder; +</code></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>Initialization</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><code>pfind_bootstrap_parcel(); +</code></pre> +<p>The generated host language bindings call the bootstrap function +automatically. C projects must call the function manually.</p> +<h4>Short names</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><code>#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); +</code></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>The âClownfishâ parcel</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>Declaring classes</h3> +<p>Classes are declared in Clownfish header files using a declaration of the +following form:</p> +<pre><code>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)* +</code></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><code>parcel Pathfinder; + +public class Pathfinder::Graph::VisibilityGraph nickname VisGraph + extends Clownfish::Obj { + /* Variables and functions */ +} +</code></pre> +<p>This will generate:</p> +<pre><code>typedef struct pfind_VisibilityGraph pfind_VisibilityGraph; +extern cfish_Class *PFIND_VISIBILITYGRAPH; +</code></pre> +<h4>Class exposure</h4> +<p>API documentation will only be generated for classes with <code>public</code> exposure.</p> +<h4>Inert classes</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>Final classes</h4> +<p>For final classes, every method is made final, regardless of the method +modifier. Final classes must not be inherited from.</p> +<h3>Variables</h3> +<p>Variables are declared with a declaration of the following form:</p> +<pre><code>variable-declaration = variable-modifier* + type variable-name ";" +variable-modifier = "inert" +variable-name = identifier +</code></pre> +<h4>Inert variables</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><code>public class Pathfinder::Path { + public inert int max_path_length; +} +</code></pre> +<p>This will generate:</p> +<pre><code>extern int pfind_Path_max_path_length; +</code></pre> +<p>The C source file defining the variable will typically use short names. So the +definition will look like:</p> +<pre><code>int Path_max_path_length = 5000; +</code></pre> +<h4>Instance variables</h4> +<p>Non-inert variables are instance variables and added to the classâs ivars +struct.</p> +<p>Example:</p> +<pre><code>public class Pathfinder::Path { + int num_nodes; + + public int + Get_Num_Nodes(Path *self); +} +</code></pre> +<p>This will add a <code>num_nodes</code> member to the ivars struct of <code>Path</code>.</p> +<h4>The ivars struct</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><code>#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; +} +</code></pre> +<h3>Functions</h3> +<pre><code>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" +</code></pre> +<h4>Function exposure</h4> +<p>API documentation will only be generated for functions with <code>public</code> exposure.</p> +<h4>Inert functions</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><code>public class Pathfinder::Graph::VisibilityGraph nickname VisGraph + extends Clownfish::Obj { + + public inert incremented VisibilityGraph* + new(int node_capacity); +} +</code></pre> +<p>This will generate:</p> +<pre><code>pfind_VisibilityGraph* +pfind_VisGraph_new(int node_capacity); +</code></pre> +<p>The C source file implementing the inert function will typically use short +names. So the implementation will look like:</p> +<pre><code>#define PFIND_USE_SHORT_NAMES +#include "Pathfinder/Graph/VisibilityGraph.h" + +VisibilityGraph* +VisGraph_new(int node_capacity) { + /* Implementation */ +} +</code></pre> +<h4>Inline functions</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>Methods</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><code>public class Pathfinder::Graph::VisibilityGraph nickname VisGraph + extends Clownfish::Obj { + + public void + Add_Node(VisibilityGraph *self, decremented Node *node); +} +</code></pre> +<p>This will generate:</p> +<pre><code>/* 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); +</code></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><code>#define PFIND_USE_SHORT_NAMES +#include "Pathfinder/Graph/VisibilityGraph.h" + +void +VisGraph_Add_Node_IMP(VisibilityGraph *self, Node *node) { + /* Implementation */ +} +</code></pre> +<h4>Looking up methods</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><code>// 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); +</code></pre> +<h4>Abstract methods</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>Final methods</h4> +<p>Final methods must not be overridden. They must not be abstract.</p> +<h4>Nullable return type</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>Incremented return type</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>Decremented parameters</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><code>String *string = String_newf("Hello"); +Vec_Push(array, (Obj*)string); +// No need to DECREF the string. +</code></pre> +<h4>Default parameter values</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>C blocks</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><code>__C__ + +struct pfind_AuxiliaryStruct { + int a; + int b; +}; + +__END_C__ +</code></pre> +<h3>Object life cycle</h3> +<h4>Object creation</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><code>/* 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; +} +</code></pre> +<h4>Reference counting</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><code>self->value = INCREF(arg); + +DECREF(object); +</code></pre> +<h4>Object destruction</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><code>/* 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); +} +</code></pre> +<h3>Documentation</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/">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><code>/** 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); +} +</code></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/c/Clownfish/Err.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/c/Clownfish/Err.mdtext?rev=1737682&view=auto ============================================================================== --- lucy/site/trunk/content/docs/c/Clownfish/Err.mdtext (added) +++ lucy/site/trunk/content/docs/c/Clownfish/Err.mdtext Mon Apr 4 12:55:10 2016 @@ -0,0 +1,112 @@ +Title: Clownfish::Err â C API Documentation + +<div class="c-api"> +<h2>Clownfish::Err</h2> +<table> +<tr> +<td class="label">parcel</td> +<td><a href="../cfish.html">Clownfish</a></td> +</tr> +<tr> +<td class="label">class variable</td> +<td><code><span class="prefix">CFISH_</span>ERR</code></td> +</tr> +<tr> +<td class="label">struct symbol</td> +<td><code><span class="prefix">cfish_</span>Err</code></td> +</tr> +<tr> +<td class="label">class nickname</td> +<td><code><span class="prefix">cfish_</span>Err</code></td> +</tr> +<tr> +<td class="label">header file</td> +<td><code>Clownfish/Err.h</code></td> +</tr> +</table> +<h3>Name</h3> +<p>Clownfish::Err â Exception.</p> +<h3>Description</h3> +<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> +<h3>Functions</h3> +<dl> +<dt id="func_set_error">set_error</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>Err_set_error</strong>( + <span class="prefix">cfish_</span>Err *<strong>error</strong> <span class="comment">// decremented</span> +); +</code></pre> +<p>Set the global error object, a per-thread Err shared variable.</p> +</dd> +<dt id="func_get_error">get_error</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Err* +<span class="prefix">cfish_</span><strong>Err_get_error</strong>(void); +</code></pre> +<p>Retrieve the global error object, a per-thread Err shared variable.</p> +</dd> +<dt id="func_trap">trap</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Err* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>Err_trap</strong>( + CFISH_Err_Attempt_t <strong>routine</strong>, + void *<strong>context</strong> +); +</code></pre> +<p>Run <code>routine</code> within the hostâs exception handling +environment, catching and returning any errors that occur.</p> +<p>If an unrecognized host exception is trapped, it will be wrapped in an +Err so that it can be handled by Clownfish code.</p> +<p><strong>Returns:</strong> an Err, or NULL if no exception occurs.</p> +</dd> +</dl> +<h3>Methods</h3> +<dl> +<dt id="func_To_String">To_String</dt> +<dd> +<pre><code><span class="prefix">cfish_</span><a href="../Clownfish/String.html">String</a>* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>Err_To_String</strong>( + <span class="prefix">cfish_</span>Err *<strong>self</strong> +); +</code></pre> +<p>Return a copy of the error message.</p> +</dd> +<dt id="func_Cat_Mess">Cat_Mess</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>Err_Cat_Mess</strong>( + <span class="prefix">cfish_</span>Err *<strong>self</strong>, + <span class="prefix">cfish_</span><a href="../Clownfish/String.html">String</a> *<strong>mess</strong> +); +</code></pre> +<p>Concatenate the supplied argument onto the error message.</p> +</dd> +<dt id="func_Get_Mess">Get_Mess</dt> +<dd> +<pre><code><span class="prefix">cfish_</span><a href="../Clownfish/String.html">String</a>* +<span class="prefix">cfish_</span><strong>Err_Get_Mess</strong>( + <span class="prefix">cfish_</span>Err *<strong>self</strong> +); +</code></pre> +<p>Return the error message.</p> +</dd> +<dt id="func_Destroy">Destroy</dt> +<dd> +<pre><code>void +<span class="prefix">cfish_</span><strong>Err_Destroy</strong>( + <span class="prefix">cfish_</span>Err *<strong>self</strong> +); +</code></pre> +<p>Generic destructor. Frees the struct itself but not any complex +member elements.</p> +</dd> +</dl> +<h3>Inheritance</h3> +<p>Clownfish::Err is a <a href="../Clownfish/Obj.html">Clownfish::Obj</a>.</p> +</div> Added: lucy/site/trunk/content/docs/c/Clownfish/Float.mdtext URL: http://svn.apache.org/viewvc/lucy/site/trunk/content/docs/c/Clownfish/Float.mdtext?rev=1737682&view=auto ============================================================================== --- lucy/site/trunk/content/docs/c/Clownfish/Float.mdtext (added) +++ lucy/site/trunk/content/docs/c/Clownfish/Float.mdtext Mon Apr 4 12:55:10 2016 @@ -0,0 +1,131 @@ +Title: Clownfish::Float â C API Documentation + +<div class="c-api"> +<h2>Clownfish::Float</h2> +<table> +<tr> +<td class="label">parcel</td> +<td><a href="../cfish.html">Clownfish</a></td> +</tr> +<tr> +<td class="label">class variable</td> +<td><code><span class="prefix">CFISH_</span>FLOAT</code></td> +</tr> +<tr> +<td class="label">struct symbol</td> +<td><code><span class="prefix">cfish_</span>Float</code></td> +</tr> +<tr> +<td class="label">class nickname</td> +<td><code><span class="prefix">cfish_</span>Float</code></td> +</tr> +<tr> +<td class="label">header file</td> +<td><code>Clownfish/Num.h</code></td> +</tr> +</table> +<h3>Name</h3> +<p>Clownfish::Float â Immutable double precision floating point number.</p> +<h3>Functions</h3> +<dl> +<dt id="func_new">new</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Float* +<span class="prefix">cfish_</span><strong>Float_new</strong>( + double <strong>value</strong> +); +</code></pre> +<p>Return a new Float.</p> +<dl> +<dt>value</dt> +<dd><p>Initial value.</p> +</dd> +</dl> +</dd> +<dt id="func_init">init</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Float* +<span class="prefix">cfish_</span><strong>Float_init</strong>( + <span class="prefix">cfish_</span>Float *<strong>self</strong>, + double <strong>value</strong> +); +</code></pre> +<p>Initialize a Float.</p> +<dl> +<dt>value</dt> +<dd><p>Initial value.</p> +</dd> +</dl> +</dd> +</dl> +<h3>Methods</h3> +<dl> +<dt id="func_Get_Value">Get_Value</dt> +<dd> +<pre><code>double +<span class="prefix">cfish_</span><strong>Float_Get_Value</strong>( + <span class="prefix">cfish_</span>Float *<strong>self</strong> +); +</code></pre> +<p>Return the value of the Float.</p> +</dd> +<dt id="func_To_I64">To_I64</dt> +<dd> +<pre><code>int64_t +<span class="prefix">cfish_</span><strong>Float_To_I64</strong>( + <span class="prefix">cfish_</span>Float *<strong>self</strong> +); +</code></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> +</dd> +<dt id="func_To_String">To_String</dt> +<dd> +<pre><code><span class="prefix">cfish_</span><a href="../Clownfish/String.html">String</a>* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>Float_To_String</strong>( + <span class="prefix">cfish_</span>Float *<strong>self</strong> +); +</code></pre> +<p>Return the Float formatted as String using <code>sprintf</code> with conversion +specifier <code>%g</code>.</p> +</dd> +<dt id="func_Equals">Equals</dt> +<dd> +<pre><code>bool +<span class="prefix">cfish_</span><strong>Float_Equals</strong>( + <span class="prefix">cfish_</span>Float *<strong>self</strong>, + <span class="prefix">cfish_</span><a href="../Clownfish/Obj.html">Obj</a> *<strong>other</strong> +); +</code></pre> +<p>Indicate whether two numbers are the same.</p> +<p><strong>Returns:</strong> true if <code>other</code> is a Float or Integer with the same value as +<code>self</code>.</p> +</dd> +<dt id="func_Compare_To">Compare_To</dt> +<dd> +<pre><code>int32_t +<span class="prefix">cfish_</span><strong>Float_Compare_To</strong>( + <span class="prefix">cfish_</span>Float *<strong>self</strong>, + <span class="prefix">cfish_</span><a href="../Clownfish/Obj.html">Obj</a> *<strong>other</strong> +); +</code></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><strong>Returns:</strong> 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> +</dd> +<dt id="func_Clone">Clone</dt> +<dd> +<pre><code><span class="prefix">cfish_</span>Float* <span class="comment">// incremented</span> +<span class="prefix">cfish_</span><strong>Float_Clone</strong>( + <span class="prefix">cfish_</span>Float *<strong>self</strong> +); +</code></pre> +<p>Return a clone of the object.</p> +</dd> +</dl> +<h3>Inheritance</h3> +<p>Clownfish::Float is a <a href="../Clownfish/Obj.html">Clownfish::Obj</a>.</p> +</div>