Permalink
Browse files

fix dev api documentation

  • Loading branch information...
Lucas Krause
Lucas Krause committed Feb 22, 2015
1 parent cb0fed5 commit 6822d08f14bea51776e64d5e2561f310d4dafe12
Showing with 95 additions and 87 deletions.
  1. +29 −71 doc/Dev-API:-GustavContent.md
  2. +52 −15 doc/Dev-API:-GustavDest.md
  3. +11 −1 doc/Dev-API:-GustavMatch.md
  4. +3 −0 src/futape/gustav/GustavMatch.php
@@ -1,91 +1,49 @@
##Static functions
##Instance functions
###`string prepareContent( string $content, string $path )`
###`private void initContent()`
Checks whether the source file is a [PHP source file](PHP-source-files) (i.e. its extension equals "php" case-insensitively). If it is, [it is executed](Reading-source-content) and the resulting content is used as content. Otherwise the passed, unmodified content is used instead.
Prepares and finalizes the content and initializes the object's [`$content` property](#private-string-content).
###`public mixed __call( string $function_name, array $arguments )`
A *magic* overloading function is called when an object's non-reachable function is called.
This function is used to emulate global getter functions for some of the object's properties. The following getters are available:
This is the first function called in the process of building the [source content](Source-content).
<dl>
<dt><code>$content</code></dt>
<dd>The (non-executed) source file's content.</dd>
<dt><code>getPath()</code></dt>
<dd>The path of the source file containing the content (<a href="#private-string-path"><code>$path</code> property</a>).</dd>
</dl>
If any other non-reachable function is called, a [`BadMethodCallException`](http://php.net/manual/en/class.badmethodcallexception.php) is thrown.
<dl>
<dt><code>$function_name</code></dt>
<dd>The name of the called function.</dd>
<dt><code>$path</code></dt>
<dd>The path of the source file.</dd>
<dt><code>$arguments</code></dt>
<dd>The arguments passed to the called function.</dd>
</dl>
Returns the content. Either the one that has been passed to this function or the resulting content of the executed source file.
###`string finalizeContent( string $content, array $gvblock [, bool $convert_content = true ] )`
Finalizes a source file's content.
##Instance properties
[Extends](Extending-source-content) another source file's content (if specified) and [converts](Converting-source-content) the source content.
###`private string $path`
Steps:
The path of the source file containing the content.
<pre><code>1. If <a href="Gustav-core-options#_ext"><code>_ext</code></a> is defined:
If content is empty or constists of whitespaces only (not 3.):
Use content (not converted) of extended source file instead.
2. <a href="Converting-source-content">Convert</a> content using the source file's converter(s).
3. If <a href="Gustav-core-options#_ext"><code>_ext</code></a> is defined:
If the source file's original content is not empty and doesn't consist of whitespaces only (not 1.):
If <a href="Gustav-core-options#_ext_content"><code>_ext_content</code></a> is defined:
If the final content of the extended source file isn't empty:
Concatenate final content of extended source file and the content (converted, see 2.)
of the source file separated by the value of <a href="Gustav-core-options#_ext_content"><code>_ext_content</code></a>.
Extended source file's content first, then the content the extending source file.</code></pre>
###`private string $content`
Notes on the steps:
The content.
<dl>
<dt>1. (<em><strong>transparent extension</strong></em>)</dt>
<dd>
<p>If the extended source file (<em>src2</em>) matches the conditions in 1., too, the content of the source file (<em>src3</em>) extended by <em>src2</em> is not converted, too. The same applies to a source file (<em>src4</em>) that gets extended by <em>src3</em> if <em>src3</em> matches the conditions in 1., too. And so on for <em>src5</em>, <em>src6</em> ...</p>
<p>
If <em>src2</em> would match the conditions in 3., the content of <em>src3</em> would be converted using <em>src3</em>'s converter(s) and is concatenated with the content (not converted) of <em>src2</em>. The content of <em>src2</em> in turn wouldn't be converted using the converter(s) of <em>src2</em>.<br />
The concatenated content (<em>src3</em>'s one converted, <em>src2</em>'s one not converted) would then be converted using the converter(s) of <em>src1</em>. Therefore the content of <em>src3</em> would be converted twice: first with its own converter(s) and then with the one(s) of <em>src1</em>.
</p>
</dd>
<dt>3. (<em><strong>isolated extension</strong></em>)</dt>
<dd>The content of the extended source file (<em>src2</em>) is converted using the converter(s) of <em>src2</em>. It's built completely independent of the extending source file (<em>src1</em>).</dd>
</dl>
###`private GustavBlock $block`
This is the second and last function called in the process of building the [source content](Source-content), following [`GustavContent::prepareContent()`](#string-preparecontent-string-content-string-path-).
The source file's GvBlock.
<dl>
<dt><code>$content</code></dt>
<dd>The prepared content. May very likely be a string returned by <a href="#string-preparecontent-string-content-string-path-"><code>GustavContent::prepareContent()</code></a>.</dd>
<dt><code>$gvblock</code></dt>
<dd>The source file's <a href="GvBlock">GvBlock</a>.</dd>
<dt><code>$convert_content</code></dt>
<dd>If set to <code>false</code>, the content isn't [converted](Converting-source-content) using the converter(s) of the source file. The content of an extended source file that gets concatenated with the extending source file's content will still be converted using its own converter(s).</dd>
</dl>
Returns the finalized [source content](Source-content).
###`string convContent( string $content, string $converter [, mixed &$next_converter ] )`
##Constants
Converts text using the specified converter. If the converter doesn't exist, the original text is returned.
###`string HOOKS_CLASS`
<dl>
<dt><code>$content</code></dt>
<dd>The content to convert.</dd>
<dt><code>$converter</code></dt>
<dd>The name of the converter that should be used.</dd>
<dt><code>&amp;$next_converter</code></dt>
<dd>
A variable passed to this parameter will contain the converter name returned by the used converter.<br />
For the <a href="Converting-source-content#the-plain-text-converter-txttextplain">hardcoded plain text converter</a> the value will be <code>html</code> while being <code>null</code> for the <a href="Converting-source-content#the-html-converter-htmlhtm">hardcoded HTML converter</a>. Although returning <code>html</code> or <code>null</code> has a very similar effect, <a href="User-defined-converters">user-defined converters</a> should always prefer <code>html</code> over <code>null</code>.<br />
If the converter doesn't exist, the variable will contain <code>false</code>.<br />
The converter name passed to the variable may not exist.
</dd>
</dl>
Returns the converted content.
The name, including the namespace, of `GustavContent`'s corresponding Hooks class.
View
@@ -1,22 +1,59 @@
##Static functions
##Instance functions
###`string finalizePath( string|string[] $dest_path, array $gvblock [, bool $reverse = false ] )`
###`private void initPath()`
Builds the [real destination path](Generating-destination-files#generating-the-destination-path) for a source file and initializes the object's [`$path` property](#private-string-path).
###`private void initContent()`
Builds the [final content](Generating-destination-files#generating-the-destination-content) of the destination file and initializes the object's [`$content` property](#private-string-content).
###`public mixed __call( string $function_name, array $arguments )`
A *magic* overloading function is called when an object's non-reachable function is called.
This function is used to emulate global getter functions for some of the object's properties. The following getters are available:
Finalizes a [destination path](Generating-destination-files#generating-the-destination-path) by appending `index.` followed by right file-extension if only the [destination file](Destination-files)'s dirname has been specified (i.e. the path ends with a directory separator) or just the correct file-extension if also a (extension-less) filename has been specified (and `$reverse` is set to `true`).
The *right file-extension* is `php` for PHP destination files and `html` for static ones.
<dl>
<dt><code>$dest_path</code></dt>
<dd>The unfinalzed path of the <a href="Destination-files">destination file</a>. Gets passed to <a href="Private-API%3a-GustavBase#string-path-stringstring-path_segment--stringstring-path_segment--stringstring---"><code>GustavBase::path()</code></a>.</dd>
<dt><code>getPath()</code></dt>
<dd>The path of the destination file (<a href="#private-string-path"><code>$path</code> property</a>).</dd>
<dt><code>getSrc()</code></dt>
<dd>The <a href="API#gustavsrc"><code>GustavSrc</code></a> object for the used source file (<a href="#private-gustavsrc-src"><code>$src</code> property</a>).</dd>
<dt><code>$gvblock</code></dt>
<dd>The source file's <a href="GvBlock">GvBlock</a>.</dd>
<dt><code>getContent()</code></dt>
<dd>The final content of the destination file (<a href="#private-string-content"><code>$content</code> property</a>).</dd>
</dl>
If any other non-reachable function is called, a [`BadMethodCallException`](http://php.net/manual/en/class.badmethodcallexception.php) is thrown.
<dl>
<dt><code>$function_name</code></dt>
<dd>The name of the called function.</dd>
<dt><code>$reverse</code></dt>
<dd>
By default <code>index.&lt;ext&gt;</code> is appended to the passed destination path if a trailing directory separator has been found.<br />
If this parameter is set to <code>true</code>, only <code>&lt;ext&gt;</code> is appended if <strong>no</strong> trailing directory separator is found.
</dd>
<dt><code>$arguments</code></dt>
<dd>The arguments passed to the called function.</dd>
</dl>
Returns the finalized [destination path](Generating-destination-files#generating-the-destination-path).
##Instance properties
###`private GustavSrc $src`
A [`GustavSrc`](API#gustavsrc) object representing the source of the destination file.
###`private string $path`
The path of the destination file.
###`private string $content`
The destination file's final content.
##Constants
###`string HOOKS_CLASS`
The name, including the namespace, of `GustavDest`'s corresponding Hooks class.
@@ -1,10 +1,20 @@
##Instance functions
###`private void initSearch()`
###`private void initSearch( string[][] $search )`
Initializes the array containing the search items ([`$search`](#private-string-search)).
Empty string values are filtered out.
<dl>
<dt><code>$search</code></dt>
<dd>
An associative array containing the search items.<br />
The array's items should use one of the <a href="Public-API%3a-GustavBase#constants"><code>GustavBase::KEY_*</code></a> constants as key and an array of strings containing the search items as value.
</dd>
</dl>
###`private void initRegex()`
Initializes the word-boundary ([`$reWordBoundary`](#private-string-rewordboundary)) and modifier ([`$reMod`](#private-string-remod)) used in regular expressions based on the passed flags.
@@ -260,6 +260,9 @@ public function __construct($str_path, $arr_search, $int_flags=0){
* Initializes the array containing the search items (`$search`).
* Empty items are filtered out.
*
* @param string[][] $search An associative array containing the search items.
* The array's items should use one of the `GustavBase::KEY_*` constants as key and an array of strings containing the search items as value.
*
* @return void
*/
private function initSearch($arr_search){

0 comments on commit 6822d08

Please sign in to comment.