diff options
| author | stevedonovan <steve.j.donovan@gmail.com> | 2010-12-20 18:52:24 +0300 |
|---|---|---|
| committer | stevedonovan <steve.j.donovan@gmail.com> | 2010-12-20 18:52:24 +0300 |
| commit | 86379a2b0889ba8dc35b6e2cbd7ef4302c86944a (patch) | |
| tree | 7a24f1e49ee76882dd8e975c5c1fd4e3aa1f66d0 /docs | |
| parent | 29b77cb8c4b472c71fec7ae90c5aad1673677755 (diff) | |
Version 0.9.0 Initial Commit:0.9.0
- lots of documentation improvements
- module() is no longer used
Diffstat (limited to 'docs')
33 files changed, 4810 insertions, 1493 deletions
diff --git a/docs/api/index.html b/docs/api/index.html index cf53687..c21ad9e 100644 --- a/docs/api/index.html +++ b/docs/api/index.html @@ -2,7 +2,9 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title> + pl.app: + Luadocs Index</title> <link rel="stylesheet" href="luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +23,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><strong>Index</strong></li> @@ -31,7 +33,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +77,10 @@ </li> <li> + <a href="modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="modules/pl.lexer.html">pl.lexer</a> </li> @@ -147,6 +153,7 @@ + <h2>Modules</h2> <table class="module_list"> <!--<tr><td colspan="2">Modules</td></tr>--> @@ -163,7 +170,7 @@ <tr> <td class="name"><a href="modules/pl.class.html">pl.class</a></td> - <td class="summary">Wrapper classes: Map and Set.</td> + <td class="summary">Provides a reuseable and convenient framework for creating classes in Lua.</td> </tr> <tr> @@ -183,12 +190,12 @@ <tr> <td class="name"><a href="modules/pl.dir.html">pl.dir</a></td> - <td class="summary">Useful functions for getting directory contents and matching them against wildcards </td> + <td class="summary">Useful functions for getting directory contents and matching them against wildcards.</td> </tr> <tr> <td class="name"><a href="modules/pl.file.html">pl.file</a></td> - <td class="summary">File Operations: copy,move,reading,writing </td> + <td class="summary">File manipulation functions: reading, writing, moving and copying.</td> </tr> <tr> @@ -202,6 +209,11 @@ </tr> <tr> + <td class="name"><a href="modules/pl.lapp.html">pl.lapp</a></td> + <td class="summary">Simple command-line parsing using human-readable specification.</td> + </tr> + + <tr> <td class="name"><a href="modules/pl.lexer.html">pl.lexer</a></td> <td class="summary">Lexical scanner for creating a sequence of tokens from text.</td> </tr> @@ -223,12 +235,12 @@ <tr> <td class="name"><a href="modules/pl.permute.html">pl.permute</a></td> - <td class="summary">Permutation operations </td> + <td class="summary">Permutation operations.</td> </tr> <tr> <td class="name"><a href="modules/pl.pretty.html">pl.pretty</a></td> - <td class="summary">Pretty-printing Lua tables </td> + <td class="summary">Pretty-printing Lua tables.</td> </tr> <tr> @@ -243,7 +255,7 @@ <tr> <td class="name"><a href="modules/pl.stringio.html">pl.stringio</a></td> - <td class="summary">reading and writing strings using Lua IO </td> + <td class="summary">reading and writing strings using Lua IO.</td> </tr> <tr> @@ -253,7 +265,7 @@ <tr> <td class="name"><a href="modules/pl.tablex.html">pl.tablex</a></td> - <td class="summary">Extended operations on Lua tables </td> + <td class="summary">Extended operations on Lua tables.</td> </tr> <tr> @@ -286,6 +298,6 @@ <p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p> </div> <!-- id="about" --> -</div> <!-- id="container" --> +</div> <!-- id="container" --> </body> </html> diff --git a/docs/api/luadoc.css b/docs/api/luadoc.css index bc0f98a..d22fb10 100644 --- a/docs/api/luadoc.css +++ b/docs/api/luadoc.css @@ -1,286 +1,287 @@ -body { - margin-left: 1em; - margin-right: 1em; - font-family: arial, helvetica, geneva, sans-serif; - background-color:#ffffff; margin:0px; +/* BEGIN RESET + +Copyright (c) 2010, Yahoo! Inc. All rights reserved. +Code licensed under the BSD License: +http://developer.yahoo.com/yui/license.html +version: 2.8.2r1 +*/ +html { + color: #000; + background: #FFF; } - -code { - font-family: "Andale Mono", monospace; +body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td { + margin: 0; + padding: 0; +} +table { + border-collapse: collapse; + border-spacing: 0; +} +fieldset,img { + border: 0; +} +address,caption,cite,code,dfn,em,strong,th,var,optgroup { + font-style: inherit; + font-weight: inherit; +} +del,ins { + text-decoration: none; +} +li { + list-style: bullet; + margin-left: 20px; +} +caption,th { + text-align: left; +} +h1,h2,h3,h4,h5,h6 { + font-size: 100%; + font-weight: bold; } +q:before,q:after { + content: ''; +} +abbr,acronym { + border: 0; + font-variant: normal; +} +sup { + vertical-align: baseline; +} +sub { + vertical-align: baseline; +} +legend { + color: #000; +} +input,button,textarea,select,optgroup,option { + font-family: inherit; + font-size: inherit; + font-style: inherit; + font-weight: inherit; +} +input,button,textarea,select {*font-size:100%; +} +/* END RESET */ -tt { - font-family: "Andale Mono", monospace; +body { + margin-left: 1em; + margin-right: 1em; + font-family: arial, helvetica, geneva, sans-serif; + background-color: #ffffff; margin: 0px; } -body, td, th { font-size: 11pt; } +code, tt { font-family: monospace; } -h1, h2, h3, h4 { margin-left: 0em; } +body, p, td, th { font-size: .95em; line-height: 1.2em;} -textarea, pre, tt { font-size:10pt; } -body, td, th { color:#000000; } -small { font-size:0.85em; } -h1 { font-size:1.5em; } -h2 { font-size:1.25em; } -h3 { font-size:1.15em; } -h4 { font-size:1.06em; } +p, ul { margin: 10px 0 0 10px;} -a:link { font-weight:bold; color: #004080; text-decoration: none; } -a:visited { font-weight:bold; color: #006699; text-decoration: none; } -a:link:hover { text-decoration:underline; } -hr { color:#cccccc } -img { border-width: 0px; } +strong { font-weight: bold;} +h1 { + font-size: 1.5em; + margin: 0 0 20px 0; +} +h2, h3, h4 { margin: 15px 0 10px 0; } +h2 { font-size: 1.25em; } +h3 { font-size: 1.15em; } +h4 { font-size: 1.06em; } + +a:link { font-weight: bold; color: #004080; text-decoration: none; } +a:visited { font-weight: bold; color: #006699; text-decoration: none; } +a:link:hover { text-decoration: underline; } + +hr { + color:#cccccc; + background: #00007f; + height: 1px; +} -h3 { padding-top: 1em; } +blockquote { margin-left: 3em; } -p { margin-left: 1em; } +ul { list-style-type: disc; } -p.name { - font-family: "Andale Mono", monospace; +p.name { + font-family: "Andale Mono", monospace; padding-top: 1em; - margin-left: 0em; } -blockquote { margin-left: 3em; } - pre.example { background-color: rgb(245, 245, 245); - border-top-width: 1px; - border-right-width: 1px; - border-bottom-width: 1px; - border-left-width: 1px; - border-top-style: solid; - border-right-style: solid; - border-bottom-style: solid; - border-left-style: solid; - border-top-color: silver; - border-right-color: silver; - border-bottom-color: silver; - border-left-color: silver; - padding: 1em; - margin-left: 1em; - margin-right: 1em; - font-family: "Andale Mono", monospace; - font-size: smaller; -} - - -hr { - margin-left: 0em; - background: #00007f; - border: 0px; - height: 1px; + border: 1px solid silver; + padding: 10px; + margin: 10px 0 10px 0; + font-family: "Andale Mono", monospace; + font-size: .85em; } -ul { list-style-type: disc; } - table.index { border: 1px #00007f; } table.index td { text-align: left; vertical-align: top; } -table.index ul { padding-top: 0em; margin-top: 0em; } - -table { - border: 1px solid black; - border-collapse: collapse; - margin-left: auto; - margin-right: auto; -} -th { - border: 1px solid black; - padding: 0.5em; -} -td { - border: 1px solid black; - padding: 0.5em; -} -div.header, div.footer { margin-left: 0em; } -#container -{ - margin-left: 1em; - margin-right: 1em; - background-color: #f0f0f0; +#container { + margin-left: 1em; + margin-right: 1em; + background-color: #f0f0f0; } -#product -{ - text-align: center; - border-bottom: 1px solid #cccccc; - background-color: #ffffff; +#product { + text-align: center; + border-bottom: 1px solid #cccccc; + background-color: #ffffff; } #product big { - font-size: 2em; -} - -#product_logo -{ -} - -#product_name -{ -} - -#product_description -{ + font-size: 2em; } -#main -{ - background-color: #f0f0f0; - border-left: 2px solid #cccccc; +#main { + background-color: #f0f0f0; + border-left: 2px solid #cccccc; } -#navigation -{ - float: left; - width: 18em; - margin: 0; - vertical-align: top; - background-color: #f0f0f0; - overflow:visible; +#navigation { + float: left; + width: 18em; + vertical-align: top; + background-color: #f0f0f0; + overflow: visible; } -#navigation h1 { - background-color:#e7e7e7; - font-size:1.1em; - color:#000000; - text-align:left; - margin:0px; - padding:0.2em; - border-top:1px solid #dddddd; - border-bottom:1px solid #dddddd; +#navigation h2 { + background-color:#e7e7e7; + font-size:1.1em; + color:#000000; + text-align: left; + padding:0.2em; + border-top:1px solid #dddddd; + border-bottom:1px solid #dddddd; } #navigation ul { - font-size:1em; - list-style-type: none; - padding: 0; - margin: 1px; + font-size:1em; + list-style-type: none; + margin: 1px 1px 10px 1px; } -#navigation li -{ - text-indent: -1em; - margin: 0em 0em 0em 0.5em; - display: block; - padding: 3px 0px 0px 12px; +#navigation li { + text-indent: -1em; + display: block; + margin: 3px 0px 0px 22px; } -#navigation li li a -{ - padding: 0px 3px 0px -1em; +#navigation li li a { + margin: 0px 3px 0px -1em; } -#content -{ - margin-left: 18em; - padding: 1em; - border-left: 2px solid #cccccc; - border-right: 2px solid #cccccc; - background-color: #ffffff; +#content { + margin-left: 18em; + padding: 1em; + border-left: 2px solid #cccccc; + border-right: 2px solid #cccccc; + background-color: #ffffff; } -#about -{ - clear: both; - margin: 0; - padding: 5px; - border-top: 2px solid #cccccc; - background-color: #ffffff; +#about { + clear: both; + padding: 5px; + border-top: 2px solid #cccccc; + background-color: #ffffff; } @media print { - body { - font: 12pt "Times New Roman", "TimeNR", Times, serif; - } - a { font-weight:bold; color: #004080; text-decoration: underline; } - - #main
{
background-color: #ffffff;
border-left: 0px;
}
- #container
{
margin-left: 2%;
margin-right: 2%;
background-color: #ffffff;
} - - #content
{
margin-left: 0px;
padding: 1em;
border-left: 0px;
border-right: 0px;
background-color: #ffffff;
} - - #navigation
{
display: none; - } - pre.example { - font-family: "Andale Mono", monospace; - font-size: 10pt; - page-break-inside: avoid; - } -} - -table.module_list td -{ - border-width: 1px; - padding: 3px; - border-style: solid; - border-color: #cccccc; + body { + font: 12pt "Times New Roman", "TimeNR", Times, serif; + } + a { font-weight: bold; color: #004080; text-decoration: underline; } + + #main { + background-color: #ffffff; + border-left: 0px; + } + + #container { + margin-left: 2%; + margin-right: 2%; + background-color: #ffffff; + } + + #content { + padding: 1em; + background-color: #ffffff; + } + + #navigation { + display: none; + } + pre.example { + font-family: "Andale Mono", monospace; + font-size: 10pt; + page-break-inside: avoid; + } +} + +table.module_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; } table.module_list td.name { background-color: #f0f0f0; } table.module_list td.summary { width: 100%; } -table.file_list -{ - border-width: 1px; - border-style: solid; - border-color: #cccccc; - border-collapse: collapse; +table.file_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; } -table.file_list td -{ - border-width: 1px; - padding: 3px; - border-style: solid; - border-color: #cccccc; +table.file_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; } + table.file_list td.name { background-color: #f0f0f0; } -table.file_list td.summary { width: 100%; } +table.file_list td.summary { width: 100%; } -table.function_list -{ - border-width: 1px; - border-style: solid; - border-color: #cccccc; - border-collapse: collapse; +table.function_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; } -table.function_list td -{ - border-width: 1px; - padding: 3px; - border-style: solid; - border-color: #cccccc; +table.function_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; } + table.function_list td.name { background-color: #f0f0f0; } -table.function_list td.summary { width: 100%; } +table.function_list td.summary { width: 100%; } -table.table_list -{ - border-width: 1px; - border-style: solid; - border-color: #cccccc; - border-collapse: collapse; +table.table_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; } -table.table_list td -{ - border-width: 1px; - padding: 3px; - border-style: solid; - border-color: #cccccc; +table.table_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; } -table.table_list td.name { background-color: #f0f0f0; } -table.table_list td.summary { width: 100%; } - -dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;} -dl.function dd {padding-bottom: 1em;} -dl.function h3 {padding: 0; margin: 0; font-size: medium;} -dl.table dt {border-top: 1px solid #ccc; padding-top: 1em;} -dl.table dd {padding-bottom: 1em;} -dl.table h3 {padding: 0; margin: 0; font-size: medium;} +table.table_list td.name { background-color: #f0f0f0; } -#TODO: make module_list, file_list, function_list, table_list inherit from a list +table.table_list td.summary { width: 100%; } +dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;} +dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;} +dl.table h3, dl.function h3 {font-size: .95em;}
\ No newline at end of file diff --git a/docs/api/modules/pl.app.html b/docs/api/modules/pl.app.html index a1b3f12..418526c 100644 --- a/docs/api/modules/pl.app.html +++ b/docs/api/modules/pl.app.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.app: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li><strong>pl.app</strong></li> @@ -73,6 +73,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,10 @@ <div id="content"> -<h1>Module <code>pl.app</code></h1> +<h1>Module "pl.app"</h1> -<p>Application support functions.</p> +<p>Application support functions. +<p>See <a href="../../index.html#app">the Guide</a></p> @@ -155,17 +160,17 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#appfile">appfile</a> (file)</td> + <td class="name" nowrap><a href="#app.appfile">app.appfile</a> (file)</td> <td class="summary">return a suitable path for files private to this application.</td> </tr> <tr> - <td class="name" nowrap><a href="#parse_args">parse_args</a> (args, flags_with_values)</td> + <td class="name" nowrap><a href="#app.parse_args">app.parse_args</a> (args, flags_with_values)</td> <td class="summary">parse command-line arguments into flags and parameters.</td> </tr> <tr> - <td class="name" nowrap><a href="#require_here">require_here</a> ()</td> + <td class="name" nowrap><a href="#app.require_here">app.require_here</a> ()</td> <td class="summary">add the current script's path to the Lua module path.</td> </tr> @@ -186,12 +191,14 @@ -<dt><a name="appfile"></a><strong>appfile</strong> (file)</dt> +<dt><a name="app.appfile"></a><strong>app.appfile</strong> (file)</dt> <dd> -return a suitable path for files private to this application. These will look like '~/.SNAME/file', with '~' as with expanduser and SNAME is the name of the script without .lua extension. +return a suitable path for files private to this application. +These will look like '~/.SNAME/file', with '~' as with expanduser and +SNAME is the name of the script without .lua extension. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -205,6 +212,8 @@ return a suitable path for files private to this application. These will look li + + <h3>Return value:</h3> a full pathname @@ -215,12 +224,16 @@ a full pathname -<dt><a name="parse_args"></a><strong>parse_args</strong> (args, flags_with_values)</dt> +<dt><a name="app.parse_args"></a><strong>app.parse_args</strong> (args, flags_with_values)</dt> <dd> -parse command-line arguments into flags and parameters. Understands GNU-style command-line flags; short (-f) and long (--flag). These may be given a value with either '=' or ':' (-k:2,--alpha=3.2,-n2); note that a number value can be given without a space. Multiple short args can be combined like so: (-abcd). +parse command-line arguments into flags and parameters. +Understands GNU-style command-line flags; short (-f) and long (--flag). +These may be given a value with either '=' or ':' (-k:2,--alpha=3.2,-n2); +note that a number value can be given without a space. +Multiple short args can be combined like so: (-abcd). -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -238,6 +251,8 @@ parse command-line arguments into flags and parameters. Understands GNU-style co + + <h3>Return values:</h3> <ol> @@ -254,9 +269,13 @@ parse command-line arguments into flags and parameters. Understands GNU-style co -<dt><a name="require_here"></a><strong>require_here</strong> ()</dt> +<dt><a name="app.require_here"></a><strong>app.require_here</strong> ()</dt> <dd> -add the current script's path to the Lua module path. Applies to both the source and the binary module paths. It makes it easy for the main file of a multi-file program to access its modules in the same directory. +add the current script's path to the Lua module path. +Applies to both the source and the binary module paths. It makes it easy for +the main file of a multi-file program to access its modules in the same directory. + + diff --git a/docs/api/modules/pl.array2d.html b/docs/api/modules/pl.array2d.html index 0972382..99e2a74 100644 --- a/docs/api/modules/pl.array2d.html +++ b/docs/api/modules/pl.array2d.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.array2d: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -73,6 +73,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,7 +147,7 @@ <div id="content"> -<h1>Module <code>pl.array2d</code></h1> +<h1>Module "pl.array2d"</h1> <p>Operations on two-dimensional arrays.</p> @@ -155,102 +159,102 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#column">column</a> (a, key)</td> + <td class="name" nowrap><a href="#array2d.column">array2d.column</a> (a, key)</td> <td class="summary">extract a column from the 2D array.</td> </tr> <tr> - <td class="name" nowrap><a href="#extract_cols">extract_cols</a> (t, cidx, a)</td> + <td class="name" nowrap><a href="#array2d.extract_cols">array2d.extract_cols</a> (t, cidx, a)</td> <td class="summary">extract the specified columns.</td> </tr> <tr> - <td class="name" nowrap><a href="#extract_rows">extract_rows</a> (t, ridx, a)</td> + <td class="name" nowrap><a href="#array2d.extract_rows">array2d.extract_rows</a> (t, ridx, a)</td> <td class="summary">extract the specified rows.</td> </tr> <tr> - <td class="name" nowrap><a href="#forall">forall</a> (t, row_op, end_row_op, i1, j1, i2, j2, a)</td> + <td class="name" nowrap><a href="#array2d.forall">array2d.forall</a> (t, row_op, end_row_op, i1, j1, i2, j2, a)</td> <td class="summary">perform an operation for all values in a 2D array.</td> </tr> <tr> - <td class="name" nowrap><a href="#iter">iter</a> (a, indices, i1, j1, i2, j2)</td> + <td class="name" nowrap><a href="#array2d.iter">array2d.iter</a> (a, indices, i1, j1, i2, j2)</td> <td class="summary">iterate over all elements in a 2D array, with optional indices.</td> </tr> <tr> - <td class="name" nowrap><a href="#map">map</a> (f, a, arg)</td> + <td class="name" nowrap><a href="#array2d.map">array2d.map</a> (f, a, arg)</td> <td class="summary">map a function over a 2D array </td> </tr> <tr> - <td class="name" nowrap><a href="#map2">map2</a> (f, ad, bd, a, b, arg)</td> + <td class="name" nowrap><a href="#array2d.map2">array2d.map2</a> (f, ad, bd, a, b, arg)</td> <td class="summary">map a function over two arrays.</td> </tr> <tr> - <td class="name" nowrap><a href="#parse_range">parse_range</a> (s)</td> + <td class="name" nowrap><a href="#array2d.parse_range">array2d.parse_range</a> (s)</td> <td class="summary">parse a spreadsheet range.</td> </tr> <tr> - <td class="name" nowrap><a href="#product">product</a> (f, t1, t2)</td> + <td class="name" nowrap><a href="#array2d.product">array2d.product</a> (f, t1, t2)</td> <td class="summary">cartesian product of two 1d arrays.</td> </tr> <tr> - <td class="name" nowrap><a href="#range">range</a> (t, rstr)</td> - <td class="summary">get a slice of a 2D array using spreadsheet range notation (see <a href="#parse_range">parse_range</a>).</td> + <td class="name" nowrap><a href="#array2d.range">array2d.range</a> (t, rstr)</td> + <td class="summary">get a slice of a 2D array using spreadsheet range notation (see <a href="#array2d.parse_range">parse_range</a>).</td> </tr> <tr> - <td class="name" nowrap><a href="#reduce2">reduce2</a> (opc, opr, a)</td> + <td class="name" nowrap><a href="#array2d.reduce2">array2d.reduce2</a> (opc, opr, a)</td> <td class="summary">reduce a 2D array into a scalar, using two operations.</td> </tr> <tr> - <td class="name" nowrap><a href="#reduce_cols">reduce_cols</a> (f, a)</td> + <td class="name" nowrap><a href="#array2d.reduce_cols">array2d.reduce_cols</a> (f, a)</td> <td class="summary">reduce the columns using a function.</td> </tr> <tr> - <td class="name" nowrap><a href="#reduce_rows">reduce_rows</a> (f, a)</td> + <td class="name" nowrap><a href="#array2d.reduce_rows">array2d.reduce_rows</a> (f, a)</td> <td class="summary">reduce the rows using a function.</td> </tr> <tr> - <td class="name" nowrap><a href="#remove_col">remove_col</a> (t, j)</td> + <td class="name" nowrap><a href="#array2d.remove_col">array2d.remove_col</a> (t, j)</td> <td class="summary">remove a column from an array.</td> </tr> <tr> - <td class="name" nowrap><a href="#remove_row">remove_row</a> (t, i)</td> + <td class="name" nowrap><a href="#array2d.remove_row">array2d.remove_row</a> (t, i)</td> <td class="summary">remove a row from an array.</td> </tr> <tr> - <td class="name" nowrap><a href="#set">set</a> (t, value, i1, j1, i2, j2)</td> + <td class="name" nowrap><a href="#array2d.set">array2d.set</a> (t, value, i1, j1, i2, j2)</td> <td class="summary">set a specified range of an array to a value.</td> </tr> <tr> - <td class="name" nowrap><a href="#slice">slice</a> (t, i1, j1, i2, j2)</td> + <td class="name" nowrap><a href="#array2d.slice">array2d.slice</a> (t, i1, j1, i2, j2)</td> <td class="summary">get a slice of a 2D array.</td> </tr> <tr> - <td class="name" nowrap><a href="#swap_cols">swap_cols</a> (t, j1, j2, i1, i2)</td> + <td class="name" nowrap><a href="#array2d.swap_cols">array2d.swap_cols</a> (t, j1, j2, i1, i2)</td> <td class="summary">swap two columns of an array.</td> </tr> <tr> - <td class="name" nowrap><a href="#swap_rows">swap_rows</a> (t, i1, i2)</td> + <td class="name" nowrap><a href="#array2d.swap_rows">array2d.swap_rows</a> (t, i1, i2)</td> <td class="summary">swap two rows of an array.</td> </tr> <tr> - <td class="name" nowrap><a href="#write">write</a> (t, f, fmt, i1, j1, i2, j2)</td> + <td class="name" nowrap><a href="#array2d.write">array2d.write</a> (t, f, fmt, i1, j1, i2, j2)</td> <td class="summary">write a 2D array to a file.</td> </tr> @@ -271,12 +275,12 @@ -<dt><a name="column"></a><strong>column</strong> (a, key)</dt> +<dt><a name="array2d.column"></a><strong>array2d.column</strong> (a, key)</dt> <dd> extract a column from the 2D array. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -294,6 +298,8 @@ extract a column from the 2D array. + + <h3>Return value:</h3> 1d array @@ -304,12 +310,12 @@ extract a column from the 2D array. -<dt><a name="extract_cols"></a><strong>extract_cols</strong> (t, cidx, a)</dt> +<dt><a name="array2d.extract_cols"></a><strong>array2d.extract_cols</strong> (t, cidx, a)</dt> <dd> extract the specified columns. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -333,17 +339,19 @@ extract the specified columns. + + </dd> -<dt><a name="extract_rows"></a><strong>extract_rows</strong> (t, ridx, a)</dt> +<dt><a name="array2d.extract_rows"></a><strong>array2d.extract_rows</strong> (t, ridx, a)</dt> <dd> extract the specified rows. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -367,17 +375,19 @@ extract the specified rows. + + </dd> -<dt><a name="forall"></a><strong>forall</strong> (t, row_op, end_row_op, i1, j1, i2, j2, a)</dt> +<dt><a name="array2d.forall"></a><strong>array2d.forall</strong> (t, row_op, end_row_op, i1, j1, i2, j2, a)</dt> <dd> perform an operation for all values in a 2D array. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -421,17 +431,19 @@ perform an operation for all values in a 2D array. + + </dd> -<dt><a name="iter"></a><strong>iter</strong> (a, indices, i1, j1, i2, j2)</dt> +<dt><a name="array2d.iter"></a><strong>array2d.iter</strong> (a, indices, i1, j1, i2, j2)</dt> <dd> iterate over all elements in a 2D array, with optional indices. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -465,6 +477,8 @@ iterate over all elements in a 2D array, with optional indices. + + <h3>Return value:</h3> either value or i,j,value depending on indices @@ -475,12 +489,12 @@ either value or i,j,value depending on indices -<dt><a name="map"></a><strong>map</strong> (f, a, arg)</dt> +<dt><a name="array2d.map"></a><strong>array2d.map</strong> (f, a, arg)</dt> <dd> map a function over a 2D array -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -502,6 +516,8 @@ map a function over a 2D array + + <h3>Return value:</h3> 2d array @@ -512,12 +528,13 @@ map a function over a 2D array -<dt><a name="map2"></a><strong>map2</strong> (f, ad, bd, a, b, arg)</dt> +<dt><a name="array2d.map2"></a><strong>array2d.map2</strong> (f, ad, bd, a, b, arg)</dt> <dd> -map a function over two arrays. They can be both or either 2D arrays +map a function over two arrays. +They can be both or either 2D arrays -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -551,6 +568,8 @@ map a function over two arrays. They can be both or either 2D arrays + + <h3>Return value:</h3> 2D array, unless both arrays are 1D @@ -561,12 +580,14 @@ map a function over two arrays. They can be both or either 2D arrays -<dt><a name="parse_range"></a><strong>parse_range</strong> (s)</dt> +<dt><a name="array2d.parse_range"></a><strong>array2d.parse_range</strong> (s)</dt> <dd> -parse a spreadsheet range. The range can be specified either as 'A1:B2' or 'R1C1:R2C2'; a special case is a single element (e.g 'A1' or 'R1C1') +parse a spreadsheet range. +The range can be specified either as 'A1:B2' or 'R1C1:R2C2'; +a special case is a single element (e.g 'A1' or 'R1C1') -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -580,6 +601,8 @@ parse a spreadsheet range. The range can be specified either as 'A1:B2' or 'R1C1 + + <h3>Return values:</h3> <ol> @@ -600,12 +623,12 @@ parse a spreadsheet range. The range can be specified either as 'A1:B2' or 'R1C1 -<dt><a name="product"></a><strong>product</strong> (f, t1, t2)</dt> +<dt><a name="array2d.product"></a><strong>array2d.product</strong> (f, t1, t2)</dt> <dd> cartesian product of two 1d arrays. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -627,6 +650,8 @@ cartesian product of two 1d arrays. + + <h3>Return value:</h3> 2d table @@ -637,12 +662,12 @@ cartesian product of two 1d arrays. -<dt><a name="range"></a><strong>range</strong> (t, rstr)</dt> +<dt><a name="array2d.range"></a><strong>array2d.range</strong> (t, rstr)</dt> <dd> -get a slice of a 2D array using spreadsheet range notation (see <a href="#parse_range">parse_range</a>). +get a slice of a 2D array using spreadsheet range notation (see <a href="#array2d.parse_range">parse_range</a>). -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -660,6 +685,8 @@ get a slice of a 2D array using spreadsheet range notation (see <a href="#parse_ + + <h3>Return value:</h3> a slice @@ -668,12 +695,12 @@ a slice <h3>See also:</h3> <ul> - <li><a href="../modules/pl.array2d.html#parse_range"> - parse_range + <li><a href=""> + array2d.parse_range </a> - <li><a href="../modules/pl.array2d.html#slice"> - slice + <li><a href=""> + array2d.slice </a> </ul> @@ -683,12 +710,12 @@ a slice -<dt><a name="reduce2"></a><strong>reduce2</strong> (opc, opr, a)</dt> +<dt><a name="array2d.reduce2"></a><strong>array2d.reduce2</strong> (opc, opr, a)</dt> <dd> reduce a 2D array into a scalar, using two operations. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -712,17 +739,19 @@ reduce a 2D array into a scalar, using two operations. + + </dd> -<dt><a name="reduce_cols"></a><strong>reduce_cols</strong> (f, a)</dt> +<dt><a name="array2d.reduce_cols"></a><strong>array2d.reduce_cols</strong> (f, a)</dt> <dd> reduce the columns using a function. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -740,6 +769,8 @@ reduce the columns using a function. + + <h3>Return value:</h3> 1d array @@ -748,7 +779,7 @@ reduce the columns using a function. <h3>See also:</h3> <ul> - <li><a href="../modules/pl.tablex.html#reduce"> + <li><a href=""> pl.tablex.reduce </a> @@ -759,12 +790,12 @@ reduce the columns using a function. -<dt><a name="reduce_rows"></a><strong>reduce_rows</strong> (f, a)</dt> +<dt><a name="array2d.reduce_rows"></a><strong>array2d.reduce_rows</strong> (f, a)</dt> <dd> reduce the rows using a function. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -782,6 +813,8 @@ reduce the rows using a function. + + <h3>Return value:</h3> 1d array @@ -790,7 +823,7 @@ reduce the rows using a function. <h3>See also:</h3> <ul> - <li><a href="../modules/pl.tablex.html#reduce"> + <li><a href=""> pl.tablex.reduce </a> @@ -801,12 +834,12 @@ reduce the rows using a function. -<dt><a name="remove_col"></a><strong>remove_col</strong> (t, j)</dt> +<dt><a name="array2d.remove_col"></a><strong>array2d.remove_col</strong> (t, j)</dt> <dd> remove a column from an array. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -826,17 +859,19 @@ remove a column from an array. + + </dd> -<dt><a name="remove_row"></a><strong>remove_row</strong> (t, i)</dt> +<dt><a name="array2d.remove_row"></a><strong>array2d.remove_row</strong> (t, i)</dt> <dd> remove a row from an array. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -856,17 +891,19 @@ remove a row from an array. + + </dd> -<dt><a name="set"></a><strong>set</strong> (t, value, i1, j1, i2, j2)</dt> +<dt><a name="array2d.set"></a><strong>array2d.set</strong> (t, value, i1, j1, i2, j2)</dt> <dd> set a specified range of an array to a value. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -902,17 +939,20 @@ set a specified range of an array to a value. + + </dd> -<dt><a name="slice"></a><strong>slice</strong> (t, i1, j1, i2, j2)</dt> +<dt><a name="array2d.slice"></a><strong>array2d.slice</strong> (t, i1, j1, i2, j2)</dt> <dd> -get a slice of a 2D array. Note that if the specified range has a 1D result, the rank of the result will be 1. +get a slice of a 2D array. Note that if the specified range has +a 1D result, the rank of the result will be 1. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -942,6 +982,8 @@ get a slice of a 2D array. Note that if the specified range has a 1D result, the + + <h3>Return value:</h3> an array, 2D in general but 1D in special cases. @@ -952,12 +994,12 @@ an array, 2D in general but 1D in special cases. -<dt><a name="swap_cols"></a><strong>swap_cols</strong> (t, j1, j2, i1, i2)</dt> +<dt><a name="array2d.swap_cols"></a><strong>array2d.swap_cols</strong> (t, j1, j2, i1, i2)</dt> <dd> swap two columns of an array. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -989,17 +1031,19 @@ swap two columns of an array. + + </dd> -<dt><a name="swap_rows"></a><strong>swap_rows</strong> (t, i1, i2)</dt> +<dt><a name="array2d.swap_rows"></a><strong>array2d.swap_rows</strong> (t, i1, i2)</dt> <dd> swap two rows of an array. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1023,17 +1067,19 @@ swap two rows of an array. + + </dd> -<dt><a name="write"></a><strong>write</strong> (t, f, fmt, i1, j1, i2, j2)</dt> +<dt><a name="array2d.write"></a><strong>array2d.write</strong> (t, f, fmt, i1, j1, i2, j2)</dt> <dd> write a 2D array to a file. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1073,6 +1119,8 @@ write a 2D array to a file. + + </dd> diff --git a/docs/api/modules/pl.class.html b/docs/api/modules/pl.class.html index e897907..a059263 100644 --- a/docs/api/modules/pl.class.html +++ b/docs/api/modules/pl.class.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.class: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -73,6 +73,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,13 @@ <div id="content"> -<h1>Module <code>pl.class</code></h1> +<h1>Module "pl.class"</h1> -<p>Wrapper classes: Map and Set. Provides a reuseable and convenient framework for creating classes in Lua. See the Guide for further <a href="../../index.html#class">discussion</a></p> +<p>Provides a reuseable and convenient framework for creating classes in Lua. +Two possible notations: <code> B = class(A) </code> or <code> class.B(A) </code>. +The latter form creates a named class. +This module also provides Map and Set classes. +See the Guide for further <a href="../../index.html#class">discussion</a></p> @@ -170,11 +178,6 @@ </tr> <tr> - <td class="name" nowrap><a href="#Map:keys">Map:keys</a> ()</td> - <td class="summary">list of keys.</td> - </tr> - - <tr> <td class="name" nowrap><a href="#Map:len">Map:len</a> ()</td> <td class="summary">size of map.</td> </tr> @@ -185,11 +188,6 @@ </tr> <tr> - <td class="name" nowrap><a href="#Map:values">Map:values</a> ()</td> - <td class="summary">list of values.</td> - </tr> - - <tr> <td class="name" nowrap><a href="#Set:difference">Set:difference</a> (set)</td> <td class="summary">new set with elements in the set that are not in the other (also -).</td> </tr> @@ -266,7 +264,7 @@ get a value from the map. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -280,6 +278,8 @@ get a value from the map. + + <h3>Return value:</h3> the value, or nil if not found. @@ -302,6 +302,8 @@ return a List of all key-value pairs, sorted by the keys. + + </dd> @@ -319,21 +321,6 @@ return an iterator over all key-value pairs. -</dd> - - - - -<dt><a name="Map:keys"></a><strong>Map:keys</strong> ()</dt> -<dd> -list of keys. - - - - - - - </dd> @@ -343,7 +330,10 @@ list of keys. <dt><a name="Map:len"></a><strong>Map:len</strong> ()</dt> <dd> -size of map. note: this is a relatively expensive operation! +size of map. +note: this is a relatively expensive operation! + + @@ -363,7 +353,7 @@ size of map. note: this is a relatively expensive operation! put a value into the map. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -383,21 +373,6 @@ put a value into the map. -</dd> - - - - -<dt><a name="Map:values"></a><strong>Map:values</strong> ()</dt> -<dd> -list of values. - - - - - - - </dd> @@ -410,7 +385,7 @@ list of values. new set with elements in the set that are not in the other (also -). -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -424,6 +399,8 @@ new set with elements in the set that are not in the other (also -). + + <h3>Return value:</h3> a new set @@ -439,7 +416,7 @@ a new set intersection of two sets (also *). -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -453,6 +430,8 @@ intersection of two sets (also *). + + <h3>Return value:</h3> a new set @@ -465,10 +444,11 @@ a new set <dt><a name="Set:isdisjoint"></a><strong>Set:isdisjoint</strong> (set)</dt> <dd> -are the sets disjoint? (no elements in common). Uses naive definition, i.e. that intersection is empty +are the sets disjoint? (no elements in common). +Uses naive definition, i.e. that intersection is empty -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -482,6 +462,8 @@ are the sets disjoint? (no elements in common). Uses naive definition, i.e. that + + <h3>Return value:</h3> true or false @@ -502,6 +484,8 @@ is the set empty?. + + <h3>Return value:</h3> true or false @@ -517,7 +501,7 @@ true or false is the first set a subset of the second?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -531,6 +515,8 @@ is the first set a subset of the second?. + + <h3>Return value:</h3> true or false @@ -546,7 +532,7 @@ true or false map a function over the values of a set. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -564,6 +550,8 @@ map a function over the values of a set. + + <h3>Return value:</h3> a new set @@ -579,7 +567,7 @@ a new set add a value to a set. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -595,6 +583,8 @@ add a value to a set. + + </dd> @@ -605,7 +595,7 @@ add a value to a set. union of two sets (also +). -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -619,6 +609,8 @@ union of two sets (also +). + + <h3>Return value:</h3> a new set @@ -634,7 +626,7 @@ a new set remove a value from a set. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -650,6 +642,8 @@ remove a value from a set. + + </dd> @@ -667,6 +661,8 @@ get a list of the values in a set. + + </dd> @@ -674,10 +670,12 @@ get a list of the values in a set. <dt><a name="class"></a><strong>class</strong> (base, c_arg, c)</dt> <dd> -create a new class, derived from a given base class. supporting two class creation syntaxes: either 'Name = class()' or'class.Name()' +create a new class, derived from a given base class. +supporting two class creation syntaxes: +either 'Name = class()' or'class.Name()' -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -701,6 +699,8 @@ create a new class, derived from a given base class. supporting two class creati + + </dd> diff --git a/docs/api/modules/pl.classx.html b/docs/api/modules/pl.classx.html index 07cbd4f..fdd2d2d 100644 --- a/docs/api/modules/pl.classx.html +++ b/docs/api/modules/pl.classx.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.classx: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -73,6 +73,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,7 +147,7 @@ <div id="content"> -<h1>Module <code>pl.classx</code></h1> +<h1>Module "pl.classx"</h1> <p>extra classes: MultiMap, OrderedMap and Typed List.</p> @@ -238,10 +242,10 @@ <dt><a name="MultiMap:set"></a><strong>MultiMap:set</strong> (key, val)</dt> <dd> -add a new value to a key. +add a new value to a key. Setting a nil value removes the key. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -261,6 +265,8 @@ add a new value to a key. + + </dd> @@ -271,7 +277,7 @@ add a new value to a key. update a MultiMap using a table. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -287,6 +293,8 @@ update a MultiMap using a table. + + </dd> @@ -304,6 +312,8 @@ iterate over key-value pairs in order. + + </dd> @@ -311,7 +321,10 @@ iterate over key-value pairs in order. <dt><a name="OrderedMap:keys"></a><strong>OrderedMap:keys</strong> ()</dt> <dd> -return the keys in order. (Not a copy!) +return the keys in order. +(Not a copy!) + + @@ -328,10 +341,11 @@ return the keys in order. (Not a copy!) <dt><a name="OrderedMap:set"></a><strong>OrderedMap:set</strong> (key, val)</dt> <dd> -set the key's value. +set the key's value. This key will be appended at the end of the map. <br> +If the value is nil, then the key is removed. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -351,6 +365,8 @@ set the key's value. + + </dd> @@ -361,7 +377,7 @@ set the key's value. sort the keys. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -377,6 +393,8 @@ sort the keys. + + </dd> @@ -385,13 +403,16 @@ sort the keys. <dt><a name="OrderedMap:update"></a><strong>OrderedMap:update</strong> (t)</dt> <dd> update an OrderedMap using a table. +If the table is itself an OrderedMap, then its entries will be appended. <br> +if it s a table of the form {{key1=val1},{key2=val2},...} these will be appended. <br> +Otherwise, it is assumed to be a map-like table, and order of extra entries is arbitrary. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - t: map-like table. + t: a table. </li> </ul> @@ -403,6 +424,8 @@ update an OrderedMap using a table. + + </dd> @@ -410,7 +433,10 @@ update an OrderedMap using a table. <dt><a name="OrderedMap:values"></a><strong>OrderedMap:values</strong> ()</dt> <dd> -return the values in order. this is relatively expensive. +return the values in order. +this is relatively expensive. + + @@ -427,10 +453,11 @@ return the values in order. this is relatively expensive. <dt><a name="TypedList:append"></a><strong>TypedList:append</strong> (val)</dt> <dd> -append a value to the list. Will throw an error if the value is not of the correct type. +append a value to the list. +Will throw an error if the value is not of the correct type. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -444,6 +471,8 @@ append a value to the list. Will throw an error if the value is not of the corre + + <h3>Return value:</h3> the list @@ -459,7 +488,7 @@ the list extend the list using another list. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -473,6 +502,8 @@ extend the list using another list. + + <h3>Return value:</h3> the list @@ -488,7 +519,7 @@ the list return a slice of the list -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -506,6 +537,8 @@ return a slice of the list + + <h3>Return value:</h3> a new typed list @@ -532,7 +565,8 @@ a new typed list <dl class="table"> <dt><a name="TypedList"></a><strong>TypedList</strong></dt> -<dd>construct a specific TypedList. For example, class.StringList(TypedList,'string') +<dd>construct a specific TypedList. +For example, class.StringList(TypedList,'string') diff --git a/docs/api/modules/pl.config.html b/docs/api/modules/pl.config.html index 2244f5a..12ee5e5 100644 --- a/docs/api/modules/pl.config.html +++ b/docs/api/modules/pl.config.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.config: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -73,6 +73,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,37 @@ <div id="content"> -<h1>Module <code>pl.config</code></h1> +<h1>Module "pl.config"</h1> + +<p>reads configuration files into a Lua table. <p> + Understands INI files, classic Unix config files, and simple +delimited columns of values. <p> +<pre class=example> + # test.config + # Read timeout in seconds + read.timeout=10 + # Write timeout in seconds + write.timeout=5 + #acceptable ports + ports = 1002,1003,1004 + + -- readconfig.lua + require 'pl' + local t = config.read 'test.config' + print(pretty.write(t)) -<p>reads configuration files into a Lua table. <br> Understands INI files, classic Unix config files, and simple delimited columns of values. <br> See the Guide for further <a href="../../index.html#config">discussion</a></p> + ### output ##### + { + ports = { + 1002, + 1003, + 1004 + }, + write_timeout = 5, + read_timeout = 10 + } +</pre> +See the Guide for further <a href="../../index.html#config">discussion</a></p> @@ -155,12 +187,12 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#lines">lines</a> (file)</td> + <td class="name" nowrap><a href="#config.lines">config.lines</a> (file)</td> <td class="summary">like io.lines(), but allows for lines to be continued with '\'.</td> </tr> <tr> - <td class="name" nowrap><a href="#read">read</a> (file, cnfg)</td> + <td class="name" nowrap><a href="#config.read">config.read</a> (file, cnfg)</td> <td class="summary">read a configuration file into a table </td> </tr> @@ -181,16 +213,17 @@ -<dt><a name="lines"></a><strong>lines</strong> (file)</dt> +<dt><a name="config.lines"></a><strong>config.lines</strong> (file)</dt> <dd> like io.lines(), but allows for lines to be continued with '\'. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - file: a file-like object (anything where read() returns the next line) or a filename. Defaults to stardard input. + file: a file-like object (anything where read() returns the next line) or a filename. +Defaults to stardard input. </li> </ul> @@ -200,6 +233,8 @@ like io.lines(), but allows for lines to be continued with '\'. + + <h3>Return value:</h3> an iterator over the lines @@ -210,12 +245,12 @@ an iterator over the lines -<dt><a name="read"></a><strong>read</strong> (file, cnfg)</dt> +<dt><a name="config.read"></a><strong>config.read</strong> (file, cnfg)</dt> <dd> read a configuration file into a table -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -233,6 +268,8 @@ read a configuration file into a table + + <h3>Return value:</h3> nil,error_msg in case of an error, otherwise a table containing items diff --git a/docs/api/modules/pl.data.html b/docs/api/modules/pl.data.html index bff11b4..9cd12a0 100644 --- a/docs/api/modules/pl.data.html +++ b/docs/api/modules/pl.data.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.data: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -73,6 +73,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,23 @@ <div id="content"> -<h1>Module <code>pl.data</code></h1> +<h1>Module "pl.data"</h1> -<p>Reading and querying simple tabular data. <br> This provides a way of creating basic SQL-like queries. <br> See <a href="../../index.html#data">the Guide</a></p> +<p>Reading and querying simple tabular data. +<pre class=example> +data.read 'test.txt' +==> {{10,20},{2,5},{40,50},fieldnames={'x','y'},delim=','} +</pre> +Provides a way of creating basic SQL-like queries. +<pre class=example> + require 'pl' + local d = data.read('xyz.txt') + local q = d:select('x,y,z where x > 3 and z < 2 sort by y') + for x,y,z in q do + print(x,y,z) + end +</pre> +<p>See <a href="../../index.html#data">the Guide</a></p> @@ -155,22 +173,22 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#filter">filter</a> (Q, file, dont_fail)</td> + <td class="name" nowrap><a href="#data.filter">data.filter</a> (Q, file, dont_fail)</td> <td class="summary">Filter input using a query.</td> </tr> <tr> - <td class="name" nowrap><a href="#new">new</a> (data, fieldnames)</td> + <td class="name" nowrap><a href="#data.new">data.new</a> (d, fieldnames)</td> <td class="summary">create a new dataset from a table of rows.</td> </tr> <tr> - <td class="name" nowrap><a href="#query">query</a> (data, condn, context, return_row)</td> + <td class="name" nowrap><a href="#data.query">data.query</a> (data, condn, context, return_row)</td> <td class="summary">create a query iterator from a select string.</td> </tr> <tr> - <td class="name" nowrap><a href="#read">read</a> (file, cnfg)</td> + <td class="name" nowrap><a href="#data.read">data.read</a> (file, cnfg)</td> <td class="summary">read a delimited file in a Lua table.</td> </tr> @@ -191,12 +209,12 @@ -<dt><a name="filter"></a><strong>filter</strong> (Q, file, dont_fail)</dt> +<dt><a name="data.filter"></a><strong>data.filter</strong> (Q, file, dont_fail)</dt> <dd> Filter input using a query. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -220,21 +238,26 @@ Filter input using a query. + + </dd> -<dt><a name="new"></a><strong>new</strong> (data, fieldnames)</dt> +<dt><a name="data.new"></a><strong>data.new</strong> (d, fieldnames)</dt> <dd> -create a new dataset from a table of rows. <br> Can specify the fieldnames, else the table must have a field called 'fieldnames', which is either a string of comma-separated names, or a table of names. +create a new dataset from a table of rows. <br> +Can specify the fieldnames, else the table must have a field called +'fieldnames', which is either a string of comma-separated names, +or a table of names. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - data: the table. + d: the table. </li> <li> @@ -248,6 +271,8 @@ create a new dataset from a table of rows. <br> Can specify the fieldnames, else + + <h3>Return value:</h3> the table. @@ -258,12 +283,17 @@ the table. -<dt><a name="query"></a><strong>query</strong> (data, condn, context, return_row)</dt> +<dt><a name="data.query"></a><strong>data.query</strong> (data, condn, context, return_row)</dt> <dd> -create a query iterator from a select string. Select string has this format: <br> FIELDLIST [ where LUA-CONDN [ sort by FIELD] ]<br> FIELDLISt is a comma-separated list of valid fields, or '*'. <br> <br> The condition can also be a table, with fields 'fields' (comma-sep string or table), 'sort_by' (string) and 'where' (Lua expression string or function) +create a query iterator from a select string. +Select string has this format: <br> +FIELDLIST [ where LUA-CONDN [ sort by FIELD] ]<br> +FIELDLISt is a comma-separated list of valid fields, or '*'. <br> <br> +The condition can also be a table, with fields 'fields' (comma-sep string or +table), 'sort_by' (string) and 'where' (Lua expression string or function) -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -289,6 +319,8 @@ create a query iterator from a select string. Select string has this format: <br + + <h3>Return value:</h3> an iterator over the specified fields @@ -299,12 +331,13 @@ an iterator over the specified fields -<dt><a name="read"></a><strong>read</strong> (file, cnfg)</dt> +<dt><a name="data.read"></a><strong>data.read</strong> (file, cnfg)</dt> <dd> -read a delimited file in a Lua table. By default, attempts to treat first line as separated list of fieldnames. +read a delimited file in a Lua table. +By default, attempts to treat first line as separated list of fieldnames. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -312,7 +345,9 @@ read a delimited file in a Lua table. By default, attempts to treat first line a </li> <li> - cnfg: options table: can override delim (a string pattern), fieldnames (a list), specify no_convert (default is to convert), numfields (indices of columns known to be numbers) and thousands_dot (thousands separator in Excel CSV is '.') + cnfg: options table: can override delim (a string pattern), fieldnames (a list), +specify no_convert (default is to convert), numfields (indices of columns known +to be numbers) and thousands_dot (thousands separator in Excel CSV is '.') </li> </ul> @@ -324,6 +359,8 @@ read a delimited file in a Lua table. By default, attempts to treat first line a + + </dd> diff --git a/docs/api/modules/pl.dir.html b/docs/api/modules/pl.dir.html index 5d02651..a0dc5ff 100644 --- a/docs/api/modules/pl.dir.html +++ b/docs/api/modules/pl.dir.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.dir: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -73,6 +73,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,9 @@ <div id="content"> -<h1>Module <code>pl.dir</code></h1> +<h1>Module "pl.dir"</h1> -<p>Useful functions for getting directory contents and matching them against wildcards</p> +<p>Useful functions for getting directory contents and matching them against wildcards.</p> @@ -155,57 +159,57 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#clonetree">clonetree</a> (path1, path2, file_fun, verbose)</td> + <td class="name" nowrap><a href="#dir.clonetree">dir.clonetree</a> (path1, path2, file_fun, verbose)</td> <td class="summary">clone a directory tree.</td> </tr> <tr> - <td class="name" nowrap><a href="#copyfile">copyfile</a> (src, dest, flag)</td> + <td class="name" nowrap><a href="#dir.copyfile">dir.copyfile</a> (src, dest, flag)</td> <td class="summary">copy a file.</td> </tr> <tr> - <td class="name" nowrap><a href="#filter">filter</a> (files, pattern)</td> + <td class="name" nowrap><a href="#dir.filter">dir.filter</a> (files, pattern)</td> <td class="summary">return a list of all files in a list of files which match the pattern.</td> </tr> <tr> - <td class="name" nowrap><a href="#fnmatch">fnmatch</a> (file, pattern)</td> + <td class="name" nowrap><a href="#dir.fnmatch">dir.fnmatch</a> (file, pattern)</td> <td class="summary">does the filename match the shell pattern?.</td> </tr> <tr> - <td class="name" nowrap><a href="#getallfiles">getallfiles</a> (start_path, pattern)</td> - <td class="summary">Recursively returns all the file starting at <i>path</i>.</td> + <td class="name" nowrap><a href="#dir.getallfiles">dir.getallfiles</a> (start_path, pattern)</td> + <td class="summary"> Recursively returns all the file starting at <i>path</i>.</td> </tr> <tr> - <td class="name" nowrap><a href="#getdirectories">getdirectories</a> (dir)</td> + <td class="name" nowrap><a href="#dir.getdirectories">dir.getdirectories</a> (dir)</td> <td class="summary">return a list of all subdirectories of the directory.</td> </tr> <tr> - <td class="name" nowrap><a href="#getfiles">getfiles</a> (dir, mask)</td> + <td class="name" nowrap><a href="#dir.getfiles">dir.getfiles</a> (dir, mask)</td> <td class="summary">return a list of all files in a directory which match the a shell pattern.</td> </tr> <tr> - <td class="name" nowrap><a href="#makepath">makepath</a> (p)</td> + <td class="name" nowrap><a href="#dir.makepath">dir.makepath</a> (p)</td> <td class="summary">create a directory path.</td> </tr> <tr> - <td class="name" nowrap><a href="#movefile">movefile</a> (src, dest)</td> + <td class="name" nowrap><a href="#dir.movefile">dir.movefile</a> (src, dest)</td> <td class="summary">move a file.</td> </tr> <tr> - <td class="name" nowrap><a href="#rmtree">rmtree</a> (fullpath)</td> + <td class="name" nowrap><a href="#dir.rmtree">dir.rmtree</a> (fullpath)</td> <td class="summary">remove a whole directory tree.</td> </tr> <tr> - <td class="name" nowrap><a href="#walk">walk</a> (root, bottom_up)</td> + <td class="name" nowrap><a href="#dir.walk">dir.walk</a> (root, bottom_up)</td> <td class="summary">return an iterator which walks through a directory tree starting at root.</td> </tr> @@ -226,12 +230,13 @@ -<dt><a name="clonetree"></a><strong>clonetree</strong> (path1, path2, file_fun, verbose)</dt> +<dt><a name="dir.clonetree"></a><strong>dir.clonetree</strong> (path1, path2, file_fun, verbose)</dt> <dd> -clone a directory tree. Will always try to create a new directory structure if necessary. +clone a directory tree. Will always try to create a new directory structure +if necessary. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -260,8 +265,11 @@ clonetree('.','../backup',copyfile) + + <h3>Return value:</h3> -if failed, false plus an error message. If completed the traverse, true, a list of failed directory creations and a list of failed file operations. +if failed, false plus an error message. If completed the traverse, + true, a list of failed directory creations and a list of failed file operations. @@ -270,12 +278,12 @@ if failed, false plus an error message. If completed the traverse, true, a list -<dt><a name="copyfile"></a><strong>copyfile</strong> (src, dest, flag)</dt> +<dt><a name="dir.copyfile"></a><strong>dir.copyfile</strong> (src, dest, flag)</dt> <dd> copy a file. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -297,6 +305,8 @@ copy a file. + + <h3>Return value:</h3> true if operation succeeded @@ -307,12 +317,13 @@ true if operation succeeded -<dt><a name="filter"></a><strong>filter</strong> (files, pattern)</dt> +<dt><a name="dir.filter"></a><strong>dir.filter</strong> (files, pattern)</dt> <dd> -return a list of all files in a list of files which match the pattern. (cf. fnmatch.filter in Python, 11.8) +return a list of all files in a list of files which match the pattern. +(cf. fnmatch.filter in Python, 11.8) -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -332,17 +343,20 @@ return a list of all files in a list of files which match the pattern. (cf. fnma + + </dd> -<dt><a name="fnmatch"></a><strong>fnmatch</strong> (file, pattern)</dt> +<dt><a name="dir.fnmatch"></a><strong>dir.fnmatch</strong> (file, pattern)</dt> <dd> -does the filename match the shell pattern?. (cf. fnmatch.fnmatch in Python, 11.8) +does the filename match the shell pattern?. +(cf. fnmatch.fnmatch in Python, 11.8) -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -362,17 +376,20 @@ does the filename match the shell pattern?. (cf. fnmatch.fnmatch in Python, 11.8 + + </dd> -<dt><a name="getallfiles"></a><strong>getallfiles</strong> (start_path, pattern)</dt> +<dt><a name="dir.getallfiles"></a><strong>dir.getallfiles</strong> (start_path, pattern)</dt> <dd> -Recursively returns all the file starting at <i>path</i>. It can optionally take a shell pattern and only returns files that match <i>pattern</i>. If a pattern is given it will do a case insensitive search. + Recursively returns all the file starting at <i>path</i>. It can optionally take a shell pattern and + only returns files that match <i>pattern</i>. If a pattern is given it will do a case insensitive search. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -390,6 +407,8 @@ Recursively returns all the file starting at <i>path</i>. It can optionally take + + <h3>Return value:</h3> Table containing all the files found recursively starting at <i>path</i> and filtered by <i>pattern</i>. @@ -400,12 +419,12 @@ Table containing all the files found recursively starting at <i>path</i> and fil -<dt><a name="getdirectories"></a><strong>getdirectories</strong> (dir)</dt> +<dt><a name="dir.getdirectories"></a><strong>dir.getdirectories</strong> (dir)</dt> <dd> return a list of all subdirectories of the directory. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -421,17 +440,19 @@ return a list of all subdirectories of the directory. + + </dd> -<dt><a name="getfiles"></a><strong>getfiles</strong> (dir, mask)</dt> +<dt><a name="dir.getfiles"></a><strong>dir.getfiles</strong> (dir, mask)</dt> <dd> return a list of all files in a directory which match the a shell pattern. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -451,17 +472,20 @@ return a list of all files in a directory which match the a shell pattern. + + </dd> -<dt><a name="makepath"></a><strong>makepath</strong> (p)</dt> +<dt><a name="dir.makepath"></a><strong>dir.makepath</strong> (p)</dt> <dd> -create a directory path. This will create subdirectories as necessary! +create a directory path. +This will create subdirectories as necessary! -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -477,17 +501,19 @@ create a directory path. This will create subdirectories as necessary! + + </dd> -<dt><a name="movefile"></a><strong>movefile</strong> (src, dest)</dt> +<dt><a name="dir.movefile"></a><strong>dir.movefile</strong> (src, dest)</dt> <dd> move a file. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -505,6 +531,8 @@ move a file. + + <h3>Return value:</h3> true if operation succeeded @@ -515,12 +543,12 @@ true if operation succeeded -<dt><a name="rmtree"></a><strong>rmtree</strong> (fullpath)</dt> +<dt><a name="dir.rmtree"></a><strong>dir.rmtree</strong> (fullpath)</dt> <dd> remove a whole directory tree. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -536,17 +564,26 @@ remove a whole directory tree. + + </dd> -<dt><a name="walk"></a><strong>walk</strong> (root, bottom_up)</dt> +<dt><a name="dir.walk"></a><strong>dir.walk</strong> (root, bottom_up)</dt> <dd> -return an iterator which walks through a directory tree starting at root. The iterator returns (root,dirs,files) Note that dirs and files are lists of names (i.e. you must say _path.join(root,d)_ to get the actual full path) If bottom_up is false (or not present), then the entries at the current level are returned before we go deeper. This means that you can modify the returned list of directories before continuing. This is a clone of os.walk from the Python libraries. +return an iterator which walks through a directory tree starting at root. +The iterator returns (root,dirs,files) +Note that dirs and files are lists of names (i.e. you must say _path.join(root,d)_ +to get the actual full path) +If bottom_up is false (or not present), then the entries at the current level are returned +before we go deeper. This means that you can modify the returned list of directories before +continuing. +This is a clone of os.walk from the Python libraries. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -566,6 +603,8 @@ return an iterator which walks through a directory tree starting at root. The it + + </dd> diff --git a/docs/api/modules/pl.file.html b/docs/api/modules/pl.file.html index 9930e0f..79bb134 100644 --- a/docs/api/modules/pl.file.html +++ b/docs/api/modules/pl.file.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.file: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -73,6 +73,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,9 @@ <div id="content"> -<h1>Module <code>pl.file</code></h1> +<h1>Module "pl.file"</h1> -<p>File Operations: copy,move,reading,writing</p> +<p>File manipulation functions: reading, writing, moving and copying.</p> @@ -155,42 +159,42 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#access_time">access_time</a> (path)</td> + <td class="name" nowrap><a href="#file.access_time">file.access_time</a> (path)</td> <td class="summary">Return the time of last access as the number of seconds since the epoch.</td> </tr> <tr> - <td class="name" nowrap><a href="#copy">copy</a> (src, dest, flag)</td> + <td class="name" nowrap><a href="#file.copy">file.copy</a> (src, dest, flag)</td> <td class="summary">copy a file.</td> </tr> <tr> - <td class="name" nowrap><a href="#creation_time">creation_time</a> (path)</td> + <td class="name" nowrap><a href="#file.creation_time">file.creation_time</a> (path)</td> <td class="summary">Return when the file was created.</td> </tr> <tr> - <td class="name" nowrap><a href="#delete">delete</a> (path)</td> + <td class="name" nowrap><a href="#file.delete">file.delete</a> (path)</td> <td class="summary">Delete a file </td> </tr> <tr> - <td class="name" nowrap><a href="#modified_time">modified_time</a> (path)</td> + <td class="name" nowrap><a href="#file.modified_time">file.modified_time</a> (path)</td> <td class="summary">Return the time of last modification </td> </tr> <tr> - <td class="name" nowrap><a href="#move">move</a> (src, dest)</td> + <td class="name" nowrap><a href="#file.move">file.move</a> (src, dest)</td> <td class="summary">move a file.</td> </tr> <tr> - <td class="name" nowrap><a href="#read">read</a> (filename)</td> + <td class="name" nowrap><a href="#file.read">file.read</a> (filename)</td> <td class="summary">return the contents of a file as a string </td> </tr> <tr> - <td class="name" nowrap><a href="#write">write</a> (filename, str)</td> + <td class="name" nowrap><a href="#file.write">file.write</a> (filename, str)</td> <td class="summary">write a string to a file </td> </tr> @@ -211,12 +215,12 @@ -<dt><a name="access_time"></a><strong>access_time</strong> (path)</dt> +<dt><a name="file.access_time"></a><strong>file.access_time</strong> (path)</dt> <dd> Return the time of last access as the number of seconds since the epoch. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -232,17 +236,19 @@ Return the time of last access as the number of seconds since the epoch. + + </dd> -<dt><a name="copy"></a><strong>copy</strong> (src, dest, flag)</dt> +<dt><a name="file.copy"></a><strong>file.copy</strong> (src, dest, flag)</dt> <dd> copy a file. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -264,6 +270,8 @@ copy a file. + + <h3>Return value:</h3> true if operation succeeded @@ -274,12 +282,12 @@ true if operation succeeded -<dt><a name="creation_time"></a><strong>creation_time</strong> (path)</dt> +<dt><a name="file.creation_time"></a><strong>file.creation_time</strong> (path)</dt> <dd> Return when the file was created. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -295,17 +303,19 @@ Return when the file was created. + + </dd> -<dt><a name="delete"></a><strong>delete</strong> (path)</dt> +<dt><a name="file.delete"></a><strong>file.delete</strong> (path)</dt> <dd> Delete a file -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -321,17 +331,19 @@ Delete a file + + </dd> -<dt><a name="modified_time"></a><strong>modified_time</strong> (path)</dt> +<dt><a name="file.modified_time"></a><strong>file.modified_time</strong> (path)</dt> <dd> Return the time of last modification -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -347,17 +359,19 @@ Return the time of last modification + + </dd> -<dt><a name="move"></a><strong>move</strong> (src, dest)</dt> +<dt><a name="file.move"></a><strong>file.move</strong> (src, dest)</dt> <dd> move a file. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -375,6 +389,8 @@ move a file. + + <h3>Return value:</h3> true if operation succeeded, else false and the reason for the error. @@ -385,12 +401,12 @@ true if operation succeeded, else false and the reason for the error. -<dt><a name="read"></a><strong>read</strong> (filename)</dt> +<dt><a name="file.read"></a><strong>file.read</strong> (filename)</dt> <dd> return the contents of a file as a string -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -404,6 +420,8 @@ return the contents of a file as a string + + <h3>Return value:</h3> file contents @@ -414,12 +432,12 @@ file contents -<dt><a name="write"></a><strong>write</strong> (filename, str)</dt> +<dt><a name="file.write"></a><strong>file.write</strong> (filename, str)</dt> <dd> write a string to a file -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -439,6 +457,8 @@ write a string to a file + + </dd> diff --git a/docs/api/modules/pl.func.html b/docs/api/modules/pl.func.html index 65791c7..376f6dc 100644 --- a/docs/api/modules/pl.func.html +++ b/docs/api/modules/pl.func.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.func: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -73,6 +73,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,10 @@ <div id="content"> -<h1>Module <code>pl.func</code></h1> +<h1>Module "pl.func"</h1> -<p>Functional helpers like composition,binding and placeholder expressions. <br> See <a href="../../index.html#func">the Guide</a></p> +<p>Functional helpers like composition,binding and placeholder expressions. <br> +See <a href="../../index.html#func">the Guide</a></p> @@ -155,47 +160,47 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#I">I</a> (e)</td> + <td class="name" nowrap><a href="#func.I">func.I</a> (e)</td> <td class="summary">instantiate a PE unless it has already been done.</td> </tr> <tr> - <td class="name" nowrap><a href="#bind">bind</a> (fn, ...)</td> + <td class="name" nowrap><a href="#func.bind">func.bind</a> (fn, ...)</td> <td class="summary">bind the arguments of a function to given values.</td> </tr> <tr> - <td class="name" nowrap><a href="#compose">compose</a> (f, g)</td> + <td class="name" nowrap><a href="#func.compose">func.compose</a> (f, g)</td> <td class="summary">create a function which chains two functions.</td> </tr> <tr> - <td class="name" nowrap><a href="#curry">curry</a> (fn, p)</td> + <td class="name" nowrap><a href="#func.curry">func.curry</a> (fn, p)</td> <td class="summary">bind the first parameter of the function to a value.</td> </tr> <tr> - <td class="name" nowrap><a href="#import">import</a> (tname, context)</td> + <td class="name" nowrap><a href="#func.import">func.import</a> (tname, context)</td> <td class="summary">wrap a table of functions.</td> </tr> <tr> - <td class="name" nowrap><a href="#instantiate">instantiate</a> (e)</td> + <td class="name" nowrap><a href="#func.instantiate">func.instantiate</a> (e)</td> <td class="summary">instantiate a PE into an actual function.</td> </tr> <tr> - <td class="name" nowrap><a href="#register">register</a> (fun, name, an)</td> + <td class="name" nowrap><a href="#func.register">func.register</a> (fun, name, an)</td> <td class="summary">register a function for use in placeholder expressions.</td> </tr> <tr> - <td class="name" nowrap><a href="#repr">repr</a> (e, lastpred)</td> + <td class="name" nowrap><a href="#func.repr">func.repr</a> (e, lastpred)</td> <td class="summary">create a string representation of a placeholder expression.</td> </tr> <tr> - <td class="name" nowrap><a href="#tail">tail</a> (ls)</td> + <td class="name" nowrap><a href="#func.tail">func.tail</a> (ls)</td> <td class="summary">all elements of a table except the first.</td> </tr> @@ -216,12 +221,12 @@ -<dt><a name="I"></a><strong>I</strong> (e)</dt> +<dt><a name="func.I"></a><strong>func.I</strong> (e)</dt> <dd> instantiate a PE unless it has already been done. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -235,6 +240,8 @@ instantiate a PE unless it has already been done. + + <h3>Return value:</h3> the function @@ -245,12 +252,13 @@ the function -<dt><a name="bind"></a><strong>bind</strong> (fn, ...)</dt> +<dt><a name="func.bind"></a><strong>func.bind</strong> (fn, ...)</dt> <dd> -bind the arguments of a function to given values. bind(fn,v,_2) is equivalent to curry(fn,v). +bind the arguments of a function to given values. +bind(fn,v,_2) is equivalent to curry(fn,v). -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -266,7 +274,7 @@ bind the arguments of a function to given values. bind(fn,v,_2) is equivalent to -<h3>Usage</h3> +<h3>Usage:</h3> <ul> <li>(bind(f,_1,a))(b) == f(a,b) @@ -277,6 +285,8 @@ bind the arguments of a function to given values. bind(fn,v,_2) is equivalent to + + <h3>Return value:</h3> a function @@ -287,12 +297,12 @@ a function -<dt><a name="compose"></a><strong>compose</strong> (f, g)</dt> +<dt><a name="func.compose"></a><strong>func.compose</strong> (f, g)</dt> <dd> create a function which chains two functions. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -313,6 +323,8 @@ printf = compose(io.write,string.format) + + <h3>Return value:</h3> a function @@ -323,12 +335,12 @@ a function -<dt><a name="curry"></a><strong>curry</strong> (fn, p)</dt> +<dt><a name="func.curry"></a><strong>func.curry</strong> (fn, p)</dt> <dd> bind the first parameter of the function to a value. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -349,6 +361,8 @@ bind the first parameter of the function to a value. + + <h3>Return value:</h3> a function of one less argument @@ -359,12 +373,13 @@ a function of one less argument -<dt><a name="import"></a><strong>import</strong> (tname, context)</dt> +<dt><a name="func.import"></a><strong>func.import</strong> (tname, context)</dt> <dd> -wrap a table of functions. This makes them available for use in placeholder expressions. +wrap a table of functions. This makes them available for use in +placeholder expressions. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -384,17 +399,22 @@ wrap a table of functions. This makes them available for use in placeholder expr + + </dd> -<dt><a name="instantiate"></a><strong>instantiate</strong> (e)</dt> +<dt><a name="func.instantiate"></a><strong>func.instantiate</strong> (e)</dt> <dd> -instantiate a PE into an actual function. First we find the largest placeholder used, e.g. _2; from this a list of the formal parameters can be build. Then we collect and replace any non-PE values from the PE, and build up a constant binding list. Finally, the expression can be compiled, and e.__PE_function is set. +instantiate a PE into an actual function. First we find the largest placeholder used, +e.g. _2; from this a list of the formal parameters can be build. Then we collect and replace +any non-PE values from the PE, and build up a constant binding list. +Finally, the expression can be compiled, and e.__PE_function is set. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -408,6 +428,8 @@ instantiate a PE into an actual function. First we find the largest placeholder + + <h3>Return value:</h3> a function @@ -418,12 +440,12 @@ a function -<dt><a name="register"></a><strong>register</strong> (fun, name, an)</dt> +<dt><a name="func.register"></a><strong>func.register</strong> (fun, name, an)</dt> <dd> register a function for use in placeholder expressions. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -445,6 +467,8 @@ register a function for use in placeholder expressions. + + <h3>Return value:</h3> a placeholder functiond @@ -455,12 +479,12 @@ a placeholder functiond -<dt><a name="repr"></a><strong>repr</strong> (e, lastpred)</dt> +<dt><a name="func.repr"></a><strong>func.repr</strong> (e, lastpred)</dt> <dd> create a string representation of a placeholder expression. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -480,17 +504,19 @@ create a string representation of a placeholder expression. + + </dd> -<dt><a name="tail"></a><strong>tail</strong> (ls)</dt> +<dt><a name="func.tail"></a><strong>func.tail</strong> (ls)</dt> <dd> all elements of a table except the first. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -506,6 +532,8 @@ all elements of a table except the first. + + </dd> diff --git a/docs/api/modules/pl.input.html b/docs/api/modules/pl.input.html index 6c9a89e..4671ffb 100644 --- a/docs/api/modules/pl.input.html +++ b/docs/api/modules/pl.input.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.input: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -73,6 +73,10 @@ <li><strong>pl.input</strong></li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,15 @@ <div id="content"> -<h1>Module <code>pl.input</code></h1> +<h1>Module "pl.input"</h1> -<p>Iterators for extracting words or numbers from an input source.</p> +<p>Iterators for extracting words or numbers from an input source. +<pre class=example> + require 'pl' + local total,n = <a href="pl.seq.html#seq.sum">seq.sum</a>(input.numbers()) + print('average',total/n) +</pre> +<p> See <a href="../../index.html#lexer">here</a></p> @@ -155,27 +165,27 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#alltokens">alltokens</a> (getter, pattern, fn)</td> + <td class="name" nowrap><a href="#input.alltokens">input.alltokens</a> (getter, pattern, fn)</td> <td class="summary">create an iterator over all tokens.</td> </tr> <tr> - <td class="name" nowrap><a href="#create_getter">create_getter</a> (f)</td> + <td class="name" nowrap><a href="#input.create_getter">input.create_getter</a> (f)</td> <td class="summary">create a function which grabs the next value from a source.</td> </tr> <tr> - <td class="name" nowrap><a href="#fields">fields</a> (ids, delim, f, opts)</td> + <td class="name" nowrap><a href="#input.fields">input.fields</a> (ids, delim, f, opts)</td> <td class="summary">parse an input source into fields.</td> </tr> <tr> - <td class="name" nowrap><a href="#numbers">numbers</a> (f)</td> + <td class="name" nowrap><a href="#input.numbers">input.numbers</a> (f)</td> <td class="summary">generate a sequence of numbers from a source.</td> </tr> <tr> - <td class="name" nowrap><a href="#words">words</a> (f)</td> + <td class="name" nowrap><a href="#input.words">input.words</a> (f)</td> <td class="summary">generate a sequence of words from a source.</td> </tr> @@ -196,12 +206,13 @@ -<dt><a name="alltokens"></a><strong>alltokens</strong> (getter, pattern, fn)</dt> +<dt><a name="input.alltokens"></a><strong>input.alltokens</strong> (getter, pattern, fn)</dt> <dd> -create an iterator over all tokens. based on allwords from PiL, 7.1 +create an iterator over all tokens. +based on allwords from PiL, 7.1 -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -223,6 +234,8 @@ create an iterator over all tokens. based on allwords from PiL, 7.1 + + <h3>Return value:</h3> an iterator @@ -233,12 +246,13 @@ an iterator -<dt><a name="create_getter"></a><strong>create_getter</strong> (f)</dt> +<dt><a name="input.create_getter"></a><strong>input.create_getter</strong> (f)</dt> <dd> -create a function which grabs the next value from a source. If the source is a string, then the getter will return the string and thereafter return nil. If not specified then the source is assumed to be stdin. +create a function which grabs the next value from a source. If the source is a string, then the getter +will return the string and thereafter return nil. If not specified then the source is assumed to be stdin. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -252,6 +266,8 @@ create a function which grabs the next value from a source. If the source is a s + + <h3>Return value:</h3> a getter function @@ -262,12 +278,13 @@ a getter function -<dt><a name="fields"></a><strong>fields</strong> (ids, delim, f, opts)</dt> +<dt><a name="input.fields"></a><strong>input.fields</strong> (ids, delim, f, opts)</dt> <dd> -parse an input source into fields. By default, will fail if it cannot convert a field to a number. +parse an input source into fields. +By default, will fail if it cannot convert a field to a number. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -296,6 +313,8 @@ for x,y in fields {2,3} do print(x,y) end -- 2nd and 3rd fields from stdin + + <h3>Return value:</h3> an iterator with the field values @@ -306,12 +325,12 @@ an iterator with the field values -<dt><a name="numbers"></a><strong>numbers</strong> (f)</dt> +<dt><a name="input.numbers"></a><strong>input.numbers</strong> (f)</dt> <dd> generate a sequence of numbers from a source. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -325,6 +344,8 @@ generate a sequence of numbers from a source. + + <h3>Return value:</h3> An iterator @@ -335,12 +356,12 @@ An iterator -<dt><a name="words"></a><strong>words</strong> (f)</dt> +<dt><a name="input.words"></a><strong>input.words</strong> (f)</dt> <dd> generate a sequence of words from a source. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -354,6 +375,8 @@ generate a sequence of words from a source. + + <h3>Return value:</h3> An iterator diff --git a/docs/api/modules/pl.lapp.html b/docs/api/modules/pl.lapp.html new file mode 100644 index 0000000..8492987 --- /dev/null +++ b/docs/api/modules/pl.lapp.html @@ -0,0 +1,438 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html> +<head> + <title>pl.lapp: Module Index</title> + <link rel="stylesheet" href="../luadoc.css" type="text/css" /> + <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> +</head> + +<body> +<div id="container"> + +<div id="product"> + <div id="product_logo"></div> + <div id="product_name"><big><b></b></big></div> + <div id="product_description"></div> +</div> <!-- id="product" --> + +<div id="main"> + +<div id="navigation"> + + +<h2>LuaDoc</h2> +<ul> + + <li><a href="../index.html">Index</a></li> + +</ul> + + +<!-- Module list --> + +<h2>Modules</h2> +<ul> + + <li> + <a href="../modules/pl.app.html">pl.app</a> + </li> + + <li> + <a href="../modules/pl.array2d.html">pl.array2d</a> + </li> + + <li> + <a href="../modules/pl.class.html">pl.class</a> + </li> + + <li> + <a href="../modules/pl.classx.html">pl.classx</a> + </li> + + <li> + <a href="../modules/pl.config.html">pl.config</a> + </li> + + <li> + <a href="../modules/pl.data.html">pl.data</a> + </li> + + <li> + <a href="../modules/pl.dir.html">pl.dir</a> + </li> + + <li> + <a href="../modules/pl.file.html">pl.file</a> + </li> + + <li> + <a href="../modules/pl.func.html">pl.func</a> + </li> + + <li> + <a href="../modules/pl.input.html">pl.input</a> + </li> + + <li><strong>pl.lapp</strong></li> + + <li> + <a href="../modules/pl.lexer.html">pl.lexer</a> + </li> + + <li> + <a href="../modules/pl.list.html">pl.list</a> + </li> + + <li> + <a href="../modules/pl.operator.html">pl.operator</a> + </li> + + <li> + <a href="../modules/pl.path.html">pl.path</a> + </li> + + <li> + <a href="../modules/pl.permute.html">pl.permute</a> + </li> + + <li> + <a href="../modules/pl.pretty.html">pl.pretty</a> + </li> + + <li> + <a href="../modules/pl.seq.html">pl.seq</a> + </li> + + <li> + <a href="../modules/pl.sip.html">pl.sip</a> + </li> + + <li> + <a href="../modules/pl.stringio.html">pl.stringio</a> + </li> + + <li> + <a href="../modules/pl.stringx.html">pl.stringx</a> + </li> + + <li> + <a href="../modules/pl.tablex.html">pl.tablex</a> + </li> + + <li> + <a href="../modules/pl.test.html">pl.test</a> + </li> + + <li> + <a href="../modules/pl.text.html">pl.text</a> + </li> + + <li> + <a href="../modules/pl.utils.html">pl.utils</a> + </li> + +</ul> + + + +<!-- File list --> + + + + + + +</div><!-- id="navigation" --> + +<div id="content"> + +<h1>Module "pl.lapp"</h1> + +<p>Simple command-line parsing using human-readable specification. +Supports GNU-style parameters. +<pre class=example> + lapp = require 'pl.lapp' + local args = lapp [[ + Does some calculations + -o,--offset (default 0.0) Offset to add to scaled number + -s,--scale (number) Scaling factor + <number> (number ) Number to be scaled + ]] + + print(args.offset + args.scale * args.number) +</pre> +Lines begining with '-' are flags; there may be a short and a long name; +lines begining wih '<var>' are arguments. Anything in parens after +the flag/argument is either a default, a type name or a range constraint. +<p>See <a href="../../index.html#lapp">the Guide</a></p> + + + + + +<h2>Functions</h2> +<table class="function_list"> + + <tr> + <td class="name" nowrap><a href="#lapp.add_type">lapp.add_type</a> (name, converter, constraint)</td> + <td class="summary">add a new type to Lapp.</td> + </tr> + + <tr> + <td class="name" nowrap><a href="#lapp.assert">lapp.assert</a> (condn, msg)</td> + <td class="summary">quit if the condition is false.</td> + </tr> + + <tr> + <td class="name" nowrap><a href="#lapp.error">lapp.error</a> (msg, no_usage)</td> + <td class="summary">print an error to stderr and quit.</td> + </tr> + + <tr> + <td class="name" nowrap><a href="#lapp.open">lapp.open</a> (file, opt)</td> + <td class="summary">open a file.</td> + </tr> + + <tr> + <td class="name" nowrap><a href="#lapp.process_options_string">lapp.process_options_string</a> (str)</td> + <td class="summary">process a Lapp options string.</td> + </tr> + + <tr> + <td class="name" nowrap><a href="#lapp.quit">lapp.quit</a> (msg, no_usage)</td> + <td class="summary">quit this script immediately.</td> + </tr> + +</table> + + + + + + +<br/> +<br/> + + + +<h2><a name="functions"></a>Functions</h2> +<dl class="function"> + + + +<dt><a name="lapp.add_type"></a><strong>lapp.add_type</strong> (name, converter, constraint)</dt> +<dd> +add a new type to Lapp. These appear in parens after the value like +a range constraint, e.g. '<ival> (integer) Process PID' + + +<h3>Parameters:</h3> +<ul> + + <li> + name: name of type + </li> + + <li> + converter: either a function to convert values, or a Lua type name. + </li> + + <li> + constraint: optional function to verify values, should use lapp.error +if failed. + </li> + +</ul> + + + + + + + + + + +</dd> + + + + +<dt><a name="lapp.assert"></a><strong>lapp.assert</strong> (condn, msg)</dt> +<dd> +quit if the condition is false. + + +<h3>Parameters:</h3> +<ul> + + <li> + condn: a condition + </li> + + <li> + msg: an optional message + </li> + +</ul> + + + + + + + + + + +</dd> + + + + +<dt><a name="lapp.error"></a><strong>lapp.error</strong> (msg, no_usage)</dt> +<dd> +print an error to stderr and quit. + + +<h3>Parameters:</h3> +<ul> + + <li> + msg: a message + </li> + + <li> + no_usage: suppress 'usage' display + </li> + +</ul> + + + + + + + + + + +</dd> + + + + +<dt><a name="lapp.open"></a><strong>lapp.open</strong> (file, opt)</dt> +<dd> +open a file. +This will quit on error, and keep a list of file objects for later cleanup. + + +<h3>Parameters:</h3> +<ul> + + <li> + file: filename + </li> + + <li> + opt: same as second parameter of <code>io.open</code> + </li> + +</ul> + + + + + + + + + + +</dd> + + + + +<dt><a name="lapp.process_options_string"></a><strong>lapp.process_options_string</strong> (str)</dt> +<dd> +process a Lapp options string. +Usually called as lapp(). + + +<h3>Parameters:</h3> +<ul> + + <li> + str: the options text + </li> + +</ul> + + + + + + + + +<h3>Return value:</h3> +a table with parameter-value pairs + + + +</dd> + + + + +<dt><a name="lapp.quit"></a><strong>lapp.quit</strong> (msg, no_usage)</dt> +<dd> +quit this script immediately. + + +<h3>Parameters:</h3> +<ul> + + <li> + msg: optional message + </li> + + <li> + no_usage: suppress 'usage' display + </li> + +</ul> + + + + + + + + + + +</dd> + + +</dl> + + + + + + +</div> <!-- id="content" --> + +</div> <!-- id="main" --> + +<div id="about"> + <p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p> +</div> <!-- id="about" --> + +</div> <!-- id="container" --> +</body> +</html> diff --git a/docs/api/modules/pl.lexer.html b/docs/api/modules/pl.lexer.html index 4bd3245..5c9123e 100644 --- a/docs/api/modules/pl.lexer.html +++ b/docs/api/modules/pl.lexer.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.lexer: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -74,6 +74,10 @@ <a href="../modules/pl.input.html">pl.input</a> </li> + <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + <li><strong>pl.lexer</strong></li> <li> @@ -143,9 +147,28 @@ <div id="content"> -<h1>Module <code>pl.lexer</code></h1> +<h1>Module "pl.lexer"</h1> -<p>Lexical scanner for creating a sequence of tokens from text. <br> See the Guide for further <a href="../../index.html#lexer">discussion</a></p> +<p>Lexical scanner for creating a sequence of tokens from text. <br> +<p><code>lexer.scan(s)</code> returns an iterator over all tokens found in the +string <code>s</code>. This iterator returns two values, a token type string +(such as 'string' for quoted string, 'iden' for identifier) and the value of the +token. +<p> +Versions specialized for Lua and C are available; these also handle block comments +and classify keywords as 'keyword' tokens. For example: +<pre class=example> +> s = 'for i=1,n do' +> for t,v in lexer.lua(s) do print(t,v) end +keyword for +iden i += = +number 1 +, , +iden n +keyword do +</pre> +See the Guide for further <a href="../../index.html#lexer">discussion</a> <br></p> @@ -155,52 +178,52 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#cpp">cpp</a> (s, filter, options)</td> + <td class="name" nowrap><a href="#lexer.cpp">lexer.cpp</a> (s, filter, options)</td> <td class="summary">create a C/C++ token iterator from a string.</td> </tr> <tr> - <td class="name" nowrap><a href="#expecting">expecting</a> (tok, expected_type, no_skip_ws)</td> + <td class="name" nowrap><a href="#lexer.expecting">lexer.expecting</a> (tok, expected_type, no_skip_ws)</td> <td class="summary">get the next token, which must be of the expected type.</td> </tr> <tr> - <td class="name" nowrap><a href="#get_keywords">get_keywords</a> ()</td> + <td class="name" nowrap><a href="#lexer.get_keywords">lexer.get_keywords</a> ()</td> <td class="summary">get the Lua keywords as a set-like table.</td> </tr> <tr> - <td class="name" nowrap><a href="#get_separated_list">get_separated_list</a> (tok, endtoken, delim)</td> + <td class="name" nowrap><a href="#lexer.get_separated_list">lexer.get_separated_list</a> (tok, endtoken, delim)</td> <td class="summary">get a list of parameters separated by a delimiter from a stream.</td> </tr> <tr> - <td class="name" nowrap><a href="#getline">getline</a> (tok)</td> + <td class="name" nowrap><a href="#lexer.getline">lexer.getline</a> (tok)</td> <td class="summary">get everything in a stream upto a newline.</td> </tr> <tr> - <td class="name" nowrap><a href="#getrest">getrest</a> (tok)</td> + <td class="name" nowrap><a href="#lexer.getrest">lexer.getrest</a> (tok)</td> <td class="summary">get the rest of the stream.</td> </tr> <tr> - <td class="name" nowrap><a href="#insert">insert</a> (tok, a1, a2)</td> + <td class="name" nowrap><a href="#lexer.insert">lexer.insert</a> (tok, a1, a2)</td> <td class="summary">insert tokens into a stream.</td> </tr> <tr> - <td class="name" nowrap><a href="#lua">lua</a> (s, filter, options)</td> + <td class="name" nowrap><a href="#lexer.lua">lexer.lua</a> (s, filter, options)</td> <td class="summary">create a Lua token iterator from a string.</td> </tr> <tr> - <td class="name" nowrap><a href="#scan">scan</a> (s, matches, filter, options)</td> + <td class="name" nowrap><a href="#lexer.scan">lexer.scan</a> (s, matches, filter, options)</td> <td class="summary">create a plain token iterator from a string.</td> </tr> <tr> - <td class="name" nowrap><a href="#skipws">skipws</a> (tok)</td> + <td class="name" nowrap><a href="#lexer.skipws">lexer.skipws</a> (tok)</td> <td class="summary">get the next non-space token from the stream.</td> </tr> @@ -221,12 +244,12 @@ -<dt><a name="cpp"></a><strong>cpp</strong> (s, filter, options)</dt> +<dt><a name="lexer.cpp"></a><strong>lexer.cpp</strong> (s, filter, options)</dt> <dd> create a C/C++ token iterator from a string. Will return the token type type and value. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -238,7 +261,8 @@ create a C/C++ token iterator from a string. Will return the token type type and </li> <li> - options: a table of options; by default, {number=true,string=true}, which means convert numbers and strip string quotes. + options: a table of options; by default, {number=true,string=true}, +which means convert numbers and strip string quotes. </li> </ul> @@ -250,17 +274,20 @@ create a C/C++ token iterator from a string. Will return the token type type and + + </dd> -<dt><a name="expecting"></a><strong>expecting</strong> (tok, expected_type, no_skip_ws)</dt> +<dt><a name="lexer.expecting"></a><strong>lexer.expecting</strong> (tok, expected_type, no_skip_ws)</dt> <dd> -get the next token, which must be of the expected type. Throws an error if this type does not match! +get the next token, which must be of the expected type. +Throws an error if this type does not match! -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -284,14 +311,19 @@ get the next token, which must be of the expected type. Throws an error if this + + </dd> -<dt><a name="get_keywords"></a><strong>get_keywords</strong> ()</dt> +<dt><a name="lexer.get_keywords"></a><strong>lexer.get_keywords</strong> ()</dt> <dd> -get the Lua keywords as a set-like table. So <code>res["and"]</code> etc would be <code>true</code>. +get the Lua keywords as a set-like table. +So <code>res["and"]</code> etc would be <code>true</code>. + + @@ -309,12 +341,12 @@ a table -<dt><a name="get_separated_list"></a><strong>get_separated_list</strong> (tok, endtoken, delim)</dt> +<dt><a name="lexer.get_separated_list"></a><strong>lexer.get_separated_list</strong> (tok, endtoken, delim)</dt> <dd> get a list of parameters separated by a delimiter from a stream. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -336,6 +368,8 @@ get a list of parameters separated by a delimiter from a stream. + + <h3>Return value:</h3> a list of token lists. @@ -346,12 +380,12 @@ a list of token lists. -<dt><a name="getline"></a><strong>getline</strong> (tok)</dt> +<dt><a name="lexer.getline"></a><strong>lexer.getline</strong> (tok)</dt> <dd> get everything in a stream upto a newline. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -365,6 +399,8 @@ get everything in a stream upto a newline. + + <h3>Return value:</h3> a string @@ -375,12 +411,12 @@ a string -<dt><a name="getrest"></a><strong>getrest</strong> (tok)</dt> +<dt><a name="lexer.getrest"></a><strong>lexer.getrest</strong> (tok)</dt> <dd> get the rest of the stream. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -394,6 +430,8 @@ get the rest of the stream. + + <h3>Return value:</h3> a string @@ -404,12 +442,12 @@ a string -<dt><a name="insert"></a><strong>insert</strong> (tok, a1, a2)</dt> +<dt><a name="lexer.insert"></a><strong>lexer.insert</strong> (tok, a1, a2)</dt> <dd> insert tokens into a stream. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -417,7 +455,8 @@ insert tokens into a stream. </li> <li> - a1: a string is the type, a table is a token list and a function is assumed to be a token-like iterator (returns type & value) + a1: a string is the type, a table is a token list and +a function is assumed to be a token-like iterator (returns type & value) </li> <li> @@ -433,17 +472,19 @@ insert tokens into a stream. + + </dd> -<dt><a name="lua"></a><strong>lua</strong> (s, filter, options)</dt> +<dt><a name="lexer.lua"></a><strong>lexer.lua</strong> (s, filter, options)</dt> <dd> create a Lua token iterator from a string. Will return the token type and value. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -455,7 +496,8 @@ create a Lua token iterator from a string. Will return the token type and value. </li> <li> - options: a table of options; by default, {number=true,string=true}, which means convert numbers and strip string quotes. + options: a table of options; by default, {number=true,string=true}, +which means convert numbers and strip string quotes. </li> </ul> @@ -467,17 +509,19 @@ create a Lua token iterator from a string. Will return the token type and value. + + </dd> -<dt><a name="scan"></a><strong>scan</strong> (s, matches, filter, options)</dt> +<dt><a name="lexer.scan"></a><strong>lexer.scan</strong> (s, matches, filter, options)</dt> <dd> create a plain token iterator from a string. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -493,7 +537,8 @@ create a plain token iterator from a string. </li> <li> - options: a table of options; by default, {number=true,string=true}, which means convert numbers and strip string quotes. + options: a table of options; by default, {number=true,string=true}, +which means convert numbers and strip string quotes. </li> </ul> @@ -505,17 +550,19 @@ create a plain token iterator from a string. + + </dd> -<dt><a name="skipws"></a><strong>skipws</strong> (tok)</dt> +<dt><a name="lexer.skipws"></a><strong>lexer.skipws</strong> (tok)</dt> <dd> get the next non-space token from the stream. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -531,6 +578,8 @@ get the next non-space token from the stream. + + </dd> diff --git a/docs/api/modules/pl.list.html b/docs/api/modules/pl.list.html index 70c2e0e..d3419d2 100644 --- a/docs/api/modules/pl.list.html +++ b/docs/api/modules/pl.list.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.list: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +75,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,25 @@ <div id="content"> -<h1>Module <code>pl.list</code></h1> +<h1>Module "pl.list"</h1> -<p>Python-style list class. Based on original code by Nick Trout. <br /><br /> <b>Please Note</b>: methods that change the list will return the list. This is to allow for method chaining, but please note that <tt>ls = ls:sort()</tt> does not mean that a new copy of the list is made. In-place (mutable) methods are marked as returning 'the list' in this documentation. <br /><br /> See the Guide for further <a href="../../index.html#list">discussion</a> <br /><br /> See <a href="http://www.python.org/doc/current/tut/tut.html">http://www.python.org/doc/current/tut/tut.html</a>, section 5.1 <br /><br /> <b>Note</b>: The comments before some of the functions are from the Python docs and contain Python code. <br /><br /> Written for Lua version 4.0 <br /> Redone for Lua 5.1, Steve Donovan.</p> +<p>Python-style list class. <p> +Based on original code by Nick Trout. +<p> +<b>Please Note</b>: methods that change the list will return the list. +This is to allow for method chaining, but please note that <tt>ls = ls:sort()</tt> +does not mean that a new copy of the list is made. In-place (mutable) methods +are marked as returning 'the list' in this documentation. +<p> +See the Guide for further <a href="../../index.html#list">discussion</a> +<p> +See <a href="http://www.python.org/doc/current/tut/tut.html">http://www.python.org/doc/current/tut/tut.html</a>, section 5.1 +<p> +<b>Note</b>: The comments before some of the functions are from the Python docs +and contain Python code. +<p> +Written for Lua version 4.0 <br /> +Redone for Lua 5.1, Steve Donovan.</p> @@ -245,8 +265,9 @@ </tr> <tr> - <td class="name" nowrap><a href="#List:join">List:join</a> (delim)</td> - <td class="summary">join the elements of a list using a delimiter.<br> This method uses tostring on all elements.</td> + <td class="name" nowrap><a href="#List:join">List:join</a> (delim, v2s)</td> + <td class="summary">join the elements of a list using a delimiter.<br> +This method uses tostring on all elements.</td> </tr> <tr> @@ -326,7 +347,8 @@ <tr> <td class="name" nowrap><a href="#List:splice">List:splice</a> (idx, list)</td> - <td class="summary">Insert a sublist into a list equivalent to 's[idx:idx] = list' in Python </td> + <td class="summary">Insert a sublist into a list +equivalent to 's[idx:idx] = list' in Python </td> </tr> <tr> @@ -358,10 +380,11 @@ <dt><a name="List.range"></a><strong>List.range</strong> (start, finish)</dt> <dd> -Emulate Python's range(x) function. Include it in List table for tidiness +Emulate Python's range(x) function. +Include it in List table for tidiness -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -384,6 +407,8 @@ List.range(0,3) == List {0,1,2,3} + + </dd> @@ -394,7 +419,7 @@ List.range(0,3) == List {0,1,2,3} split a string using a delimiter. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -412,6 +437,8 @@ split a string using a delimiter. + + <h3>Return value:</h3> a List of strings @@ -420,7 +447,7 @@ a List of strings <h3>See also:</h3> <ul> - <li><a href="../modules/pl.utils.html#split"> + <li><a href=""> pl.utils.split </a> @@ -446,6 +473,8 @@ for v in ls do print(v) end + + </dd> @@ -456,7 +485,7 @@ for v in ls do print(v) end concatenation operator .. . -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -470,6 +499,8 @@ concatenation operator .. . + + <h3>Return value:</h3> a new list consisting of the list with the elements of the new list appended @@ -485,7 +516,7 @@ a new list consisting of the list with the elements of the new list appended equality operator ==. True iff all elements of two lists are equal. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -499,6 +530,8 @@ equality operator ==. True iff all elements of two lists are equal. + + <h3>Return value:</h3> true or false @@ -521,6 +554,8 @@ how our list should be rendered as a string. Uses join(). + + <h3>See also:</h3> <ul> @@ -540,7 +575,7 @@ how our list should be rendered as a string. Uses join(). Add an item to the end of the list. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -554,6 +589,8 @@ Add an item to the end of the list. + + <h3>Return value:</h3> the list @@ -566,10 +603,11 @@ the list <dt><a name="List:chop"></a><strong>List:chop</strong> (i1, i2)</dt> <dd> -Remove a subrange of elements. equivalent to 'del s[i1:i2]' in Python. +Remove a subrange of elements. +equivalent to 'del s[i1:i2]' in Python. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -587,6 +625,8 @@ Remove a subrange of elements. equivalent to 'del s[i1:i2]' in Python. + + <h3>Return value:</h3> the list @@ -607,6 +647,8 @@ empty the list. + + <h3>Return value:</h3> the list @@ -619,10 +661,11 @@ the list <dt><a name="List:concat"></a><strong>List:concat</strong> (delim)</dt> <dd> -join a list of strings. <br> Uses table.concat directly. +join a list of strings. <br> +Uses table.concat directly. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -636,6 +679,8 @@ join a list of strings. <br> Uses table.concat directly. + + <h3>Return value:</h3> a string @@ -651,7 +696,7 @@ a string does this list contain the value?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -665,6 +710,8 @@ does this list contain the value?. + + <h3>Return value:</h3> true or false @@ -680,7 +727,7 @@ true or false Return the number of times value appears in the list. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -694,6 +741,8 @@ Return the number of times value appears in the list. + + <h3>Return value:</h3> number of times x appears @@ -706,10 +755,11 @@ number of times x appears <dt><a name="List:extend"></a><strong>List:extend</strong> (L)</dt> <dd> -Extend the list by appending all the items in the given list. equivalent to 'a[len(a):] = L'. +Extend the list by appending all the items in the given list. +equivalent to 'a[len(a):] = L'. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -723,6 +773,8 @@ Extend the list by appending all the items in the given list. equivalent to 'a[l + + <h3>Return value:</h3> the list @@ -738,7 +790,7 @@ the list create a list of all elements which match a function. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -760,6 +812,8 @@ create a list of all elements which match a function. + + <h3>Return value:</h3> a new filtered list. @@ -775,7 +829,7 @@ a new filtered list. call the function for each element of the list. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -795,6 +849,8 @@ call the function for each element of the list. + + </dd> @@ -802,10 +858,11 @@ call the function for each element of the list. <dt><a name="List:index"></a><strong>List:index</strong> (x, idx)</dt> <dd> -Return the index in the list of the first item whose value is given. Return nil if there is no such item. +Return the index in the list of the first item whose value is given. +Return nil if there is no such item. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -823,6 +880,8 @@ Return the index in the list of the first item whose value is given. Return nil + + <h3>Return value:</h3> the index, or nil if not found. @@ -835,10 +894,11 @@ the index, or nil if not found. <dt><a name="List:insert"></a><strong>List:insert</strong> (i, x)</dt> <dd> -Insert an item at a given position. i is the index of the element before which to insert. +Insert an item at a given position. i is the index of the +element before which to insert. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -856,6 +916,8 @@ Insert an item at a given position. i is the index of the element before which t + + <h3>Return value:</h3> the list @@ -878,23 +940,30 @@ return an iterator over all values. + + </dd> -<dt><a name="List:join"></a><strong>List:join</strong> (delim)</dt> +<dt><a name="List:join"></a><strong>List:join</strong> (delim, v2s)</dt> <dd> -join the elements of a list using a delimiter.<br> This method uses tostring on all elements. +join the elements of a list using a delimiter.<br> +This method uses tostring on all elements. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> delim: a delimiter string, can be empty. </li> + <li> + v2s: + </li> + </ul> @@ -902,6 +971,8 @@ join the elements of a list using a delimiter.<br> This method uses tostring on + + <h3>Return value:</h3> a string @@ -924,6 +995,8 @@ list:len() is the same as #list. + + </dd> @@ -931,10 +1004,11 @@ list:len() is the same as #list. <dt><a name="List:map"></a><strong>List:map</strong> (fun, ..., arg1)</dt> <dd> -apply a function to all elements. Any extra arguments will be passed to the function +apply a function to all elements. +Any extra arguments will be passed to the function -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -956,6 +1030,8 @@ apply a function to all elements. Any extra arguments will be passed to the func + + <h3>Return value:</h3> a new list: {f(x) for x in self} @@ -964,7 +1040,7 @@ a new list: {f(x) for x in self} <h3>See also:</h3> <ul> - <li><a href="../modules/pl.tablex.html#imap"> + <li><a href=""> pl.tablex.imap </a> @@ -977,10 +1053,11 @@ a new list: {f(x) for x in self} <dt><a name="List:map2"></a><strong>List:map2</strong> (fun, ls, ...)</dt> <dd> -apply a function to elements of two lists. Any extra arguments will be passed to the function +apply a function to elements of two lists. +Any extra arguments will be passed to the function -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1002,6 +1079,8 @@ apply a function to elements of two lists. Any extra arguments will be passed to + + <h3>Return value:</h3> a new list: {f(x,y) for x in self, for x in arg1} @@ -1010,7 +1089,7 @@ a new list: {f(x,y) for x in self, for x in arg1} <h3>See also:</h3> <ul> - <li><a href="../modules/pl.tablex.html#imap2"> + <li><a href=""> pl.tablex.imap2 </a> @@ -1023,10 +1102,11 @@ a new list: {f(x,y) for x in self, for x in arg1} <dt><a name="List:mapm"></a><strong>List:mapm</strong> (name, ...)</dt> <dd> -apply a named meethod to all elements. Any extra arguments will be passed to the method. +apply a named meethod to all elements. +Any extra arguments will be passed to the method. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1044,6 +1124,8 @@ apply a named meethod to all elements. Any extra arguments will be passed to the + + <h3>Return value:</h3> a new list of the results @@ -1052,7 +1134,7 @@ a new list of the results <h3>See also:</h3> <ul> - <li><a href="../modules/pl.seq.html#mapmethod"> + <li><a href=""> pl.seq.mapmethod </a> @@ -1065,10 +1147,12 @@ a new list of the results <dt><a name="List:new"></a><strong>List:new</strong> (t)</dt> <dd> -Create a new list. Can optionally pass a table; passing another instance of List will cause a copy to be created we pass anything which isn't a simple table to iter() to work out +Create a new list. Can optionally pass a table; +passing another instance of List will cause a copy to be created +we pass anything which isn't a simple table to iter() to work out -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1085,6 +1169,8 @@ ls = List(); ls = List {1,2,3,4} + + <h3>Return value:</h3> a new List @@ -1106,10 +1192,11 @@ a new List <dt><a name="List:partition"></a><strong>List:partition</strong> (fun, ...)</dt> <dd> -partition a list using a classifier function. The function may return nil, but this will be converted to the string key '<nil>'. +partition a list using a classifier function. +The function may return nil, but this will be converted to the string key '<nil>'. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1127,8 +1214,11 @@ partition a list using a classifier function. The function may return nil, but t + + <h3>Return value:</h3> -a table where the keys are the returned values, and the values are Lists of values where the function returned that key. It is given the type of Multimap. +a table where the keys are the returned values, and the values are Lists +of values where the function returned that key. It is given the type of Multimap. @@ -1148,10 +1238,12 @@ a table where the keys are the returned values, and the values are Lists of valu <dt><a name="List:pop"></a><strong>List:pop</strong> (i)</dt> <dd> -Remove the item at the given position in the list, and return it. If no index is specified, a:pop() returns the last item in the list. The item is also removed from the list. +Remove the item at the given position in the list, and return it. +If no index is specified, a:pop() returns the last item in the list. +The item is also removed from the list. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1165,6 +1257,8 @@ Remove the item at the given position in the list, and return it. If no index is + + <h3>Return value:</h3> the item @@ -1180,7 +1274,7 @@ the item Insert an item at the begining of the list. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1194,6 +1288,8 @@ Insert an item at the begining of the list. + + <h3>Return value:</h3> the list @@ -1209,7 +1305,7 @@ the list 'reduce' a list using a binary function. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1223,6 +1319,8 @@ the list + + <h3>Return value:</h3> result of the function @@ -1231,7 +1329,7 @@ result of the function <h3>See also:</h3> <ul> - <li><a href="../modules/pl.tablex.html#reduce"> + <li><a href=""> pl.tablex.reduce </a> @@ -1244,10 +1342,11 @@ result of the function <dt><a name="List:remove"></a><strong>List:remove</strong> (i)</dt> <dd> -Remove an element given its index. (equivalent of Python's del s[i]) +Remove an element given its index. +(equivalent of Python's del s[i]) -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1261,6 +1360,8 @@ Remove an element given its index. (equivalent of Python's del s[i]) + + <h3>Return value:</h3> the list @@ -1273,10 +1374,13 @@ the list <dt><a name="List:remove_value"></a><strong>List:remove_value</strong> (x)</dt> <dd> -Remove the first item from the list whose value is given. (This is called 'remove' in Python; renamed to avoid confusion with table.remove) Return nil if there is no such item. +Remove the first item from the list whose value is given. +(This is called 'remove' in Python; renamed to avoid confusion +with table.remove) +Return nil if there is no such item. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1290,6 +1394,8 @@ Remove the first item from the list whose value is given. (This is called 'remov + + <h3>Return value:</h3> the list @@ -1310,6 +1416,8 @@ Reverse the elements of the list, in place. + + <h3>Return value:</h3> the list @@ -1322,10 +1430,13 @@ the list <dt><a name="List:slice"></a><strong>List:slice</strong> (first, last)</dt> <dd> -Emulate list slicing. like 'list[first:last]' in Python. If first or last are negative then they are relative to the end of the list eg. slice(-2) gives last 2 entries in a list, and slice(-4,-2) gives from -4th to -2nd +Emulate list slicing. like 'list[first:last]' in Python. +If first or last are negative then they are relative to the end of the list +eg. slice(-2) gives last 2 entries in a list, and +slice(-4,-2) gives from -4th to -2nd -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1343,6 +1454,8 @@ Emulate list slicing. like 'list[first:last]' in Python. If first or last are + + <h3>Return value:</h3> a new List @@ -1358,7 +1471,7 @@ a new List general slice assignment s[i1:i2] = seq. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1380,6 +1493,8 @@ general slice assignment s[i1:i2] = seq. + + <h3>Return value:</h3> the list @@ -1395,7 +1510,7 @@ the list Sort the items of the list, in place. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1409,6 +1524,8 @@ Sort the items of the list, in place. + + <h3>Return value:</h3> the list @@ -1421,10 +1538,11 @@ the list <dt><a name="List:splice"></a><strong>List:splice</strong> (idx, list)</dt> <dd> -Insert a sublist into a list equivalent to 's[idx:idx] = list' in Python +Insert a sublist into a list +equivalent to 's[idx:idx] = list' in Python -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1441,7 +1559,9 @@ Insert a sublist into a list equivalent to 's[idx:idx] = list' in Python <h3>Usage:</h3> -l = List{10,20}; l:splice(2,{21,22}); assert(l == List{10,21,22,20}) + l = List{10,20}; l:splice(2,{21,22}); assert(l == List{10,21,22,20}) + + @@ -1457,10 +1577,11 @@ the list <dt><a name="List:transform"></a><strong>List:transform</strong> (fun, t, ...)</dt> <dd> -apply a function to all elements, in-place. Any extra arguments are passed to the function. +apply a function to all elements, in-place. +Any extra arguments are passed to the function. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1484,6 +1605,8 @@ apply a function to all elements, in-place. Any extra arguments are passed to th + + </dd> @@ -1491,10 +1614,12 @@ apply a function to all elements, in-place. Any extra arguments are passed to th <dt><a name="iter"></a><strong>iter</strong> (seq)</dt> <dd> -Create an iterator over a seqence. This captures the Python concept of 'sequence'. For tables, iterates over all values with integer indices. +Create an iterator over a seqence. +This captures the Python concept of 'sequence'. +For tables, iterates over all values with integer indices. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1506,7 +1631,7 @@ Create an iterator over a seqence. This captures the Python concept of 'sequence -<h3>Usage</h3> +<h3>Usage:</h3> <ul> <li>for x in iter {1,10,22,55} do io.write(x,',') end ==> 1,10,22,55 @@ -1519,6 +1644,8 @@ Create an iterator over a seqence. This captures the Python concept of 'sequence + + </dd> diff --git a/docs/api/modules/pl.operator.html b/docs/api/modules/pl.operator.html index d07b2a5..e31ef0a 100644 --- a/docs/api/modules/pl.operator.html +++ b/docs/api/modules/pl.operator.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.operator: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +75,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,12 @@ <div id="content"> -<h1>Module <code>pl.operator</code></h1> +<h1>Module "pl.operator"</h1> -<p>Lua operators available as functions. (similar to the Python module of the same name)<br> There is a module field <code>optable</code> which maps the operator strings onto these functions, e.g. <pre class=example>operator.optable['()']==operator.call</pre></p> +<p>Lua operators available as functions. +(similar to the Python module of the same name)<br> +There is a module field <code>optable</code> which maps the operator strings +onto these functions, e.g. <pre class=example>operator.optable['()']==operator.call</pre></p> @@ -155,112 +162,112 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#add">add</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.add">operator.add</a> (a, b)</td> <td class="summary">add two values + </td> </tr> <tr> - <td class="name" nowrap><a href="#call">call</a> (fn, ...)</td> + <td class="name" nowrap><a href="#operator.call">operator.call</a> (fn, ...)</td> <td class="summary">apply function to some arguments () </td> </tr> <tr> - <td class="name" nowrap><a href="#concat">concat</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.concat">operator.concat</a> (a, b)</td> <td class="summary">concatenate two values (either strings or __concat defined) ..</td> </tr> <tr> - <td class="name" nowrap><a href="#div">div</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.div">operator.div</a> (a, b)</td> <td class="summary">divide first value by second / </td> </tr> <tr> - <td class="name" nowrap><a href="#eq">eq</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.eq">operator.eq</a> (a, b)</td> <td class="summary">returns true if arguments are equal == </td> </tr> <tr> - <td class="name" nowrap><a href="#ge">ge</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.ge">operator.ge</a> (a, b)</td> <td class="summary">returns true if a is greater or equal to b >= </td> </tr> <tr> - <td class="name" nowrap><a href="#gt">gt</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.gt">operator.gt</a> (a, b)</td> <td class="summary">returns true if a is greater than b > </td> </tr> <tr> - <td class="name" nowrap><a href="#index">index</a> (t, k)</td> + <td class="name" nowrap><a href="#operator.index">operator.index</a> (t, k)</td> <td class="summary">get the indexed value from a table [] </td> </tr> <tr> - <td class="name" nowrap><a href="#land">land</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.land">operator.land</a> (a, b)</td> <td class="summary">true if both values evaluate as true (i.e.</td> </tr> <tr> - <td class="name" nowrap><a href="#le">le</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.le">operator.le</a> (a, b)</td> <td class="summary">returns true if a is less or equal to b <= </td> </tr> <tr> - <td class="name" nowrap><a href="#len">len</a> (a)</td> + <td class="name" nowrap><a href="#operator.len">operator.len</a> (a)</td> <td class="summary">returns length of string or table # </td> </tr> <tr> - <td class="name" nowrap><a href="#lnot">lnot</a> (a)</td> + <td class="name" nowrap><a href="#operator.lnot">operator.lnot</a> (a)</td> <td class="summary">false if value evaluates as true (i.e.</td> </tr> <tr> - <td class="name" nowrap><a href="#lor">lor</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.lor">operator.lor</a> (a, b)</td> <td class="summary">true if either value evaluate as true (i.e.</td> </tr> <tr> - <td class="name" nowrap><a href="#lt">lt</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.lt">operator.lt</a> (a, b)</td> <td class="summary">returns true if a is less than b < </td> </tr> <tr> - <td class="name" nowrap><a href="#mod">mod</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.mod">operator.mod</a> (a, b)</td> <td class="summary">modulo; remainder of a divided by b % </td> </tr> <tr> - <td class="name" nowrap><a href="#mul">mul</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.mul">operator.mul</a> (a, b)</td> <td class="summary">multiply two values * </td> </tr> <tr> - <td class="name" nowrap><a href="#neq">neq</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.neq">operator.neq</a> (a, b)</td> <td class="summary">returns true if arguments are not equal ~= </td> </tr> <tr> - <td class="name" nowrap><a href="#nop">nop</a> (...)</td> + <td class="name" nowrap><a href="#operator.nop">operator.nop</a> (...)</td> <td class="summary">the null operation.</td> </tr> <tr> - <td class="name" nowrap><a href="#pow">pow</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.pow">operator.pow</a> (a, b)</td> <td class="summary">raise first to the power of second ^ </td> </tr> <tr> - <td class="name" nowrap><a href="#sub">sub</a> (a, b)</td> + <td class="name" nowrap><a href="#operator.sub">operator.sub</a> (a, b)</td> <td class="summary">subtract b from a - </td> </tr> <tr> - <td class="name" nowrap><a href="#table">table</a> (...)</td> + <td class="name" nowrap><a href="#operator.table">operator.table</a> (...)</td> <td class="summary">make a table from the arguments.</td> </tr> <tr> - <td class="name" nowrap><a href="#unm">unm</a> (a)</td> + <td class="name" nowrap><a href="#operator.unm">operator.unm</a> (a)</td> <td class="summary">return the negative of a value - </td> </tr> @@ -281,12 +288,12 @@ -<dt><a name="add"></a><strong>add</strong> (a, b)</dt> +<dt><a name="operator.add"></a><strong>operator.add</strong> (a, b)</dt> <dd> add two values + -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -306,17 +313,19 @@ add two values + + + </dd> -<dt><a name="call"></a><strong>call</strong> (fn, ...)</dt> +<dt><a name="operator.call"></a><strong>operator.call</strong> (fn, ...)</dt> <dd> apply function to some arguments () -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -336,17 +345,19 @@ apply function to some arguments () + + </dd> -<dt><a name="concat"></a><strong>concat</strong> (a, b)</dt> +<dt><a name="operator.concat"></a><strong>operator.concat</strong> (a, b)</dt> <dd> concatenate two values (either strings or __concat defined) .. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -366,17 +377,19 @@ concatenate two values (either strings or __concat defined) .. + + </dd> -<dt><a name="div"></a><strong>div</strong> (a, b)</dt> +<dt><a name="operator.div"></a><strong>operator.div</strong> (a, b)</dt> <dd> divide first value by second / -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -396,17 +409,19 @@ divide first value by second / + + </dd> -<dt><a name="eq"></a><strong>eq</strong> (a, b)</dt> +<dt><a name="operator.eq"></a><strong>operator.eq</strong> (a, b)</dt> <dd> returns true if arguments are equal == -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -426,17 +441,19 @@ returns true if arguments are equal == + + </dd> -<dt><a name="ge"></a><strong>ge</strong> (a, b)</dt> +<dt><a name="operator.ge"></a><strong>operator.ge</strong> (a, b)</dt> <dd> returns true if a is greater or equal to b >= -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -456,17 +473,19 @@ returns true if a is greater or equal to b >= + + </dd> -<dt><a name="gt"></a><strong>gt</strong> (a, b)</dt> +<dt><a name="operator.gt"></a><strong>operator.gt</strong> (a, b)</dt> <dd> returns true if a is greater than b > -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -486,17 +505,19 @@ returns true if a is greater than b > + + </dd> -<dt><a name="index"></a><strong>index</strong> (t, k)</dt> +<dt><a name="operator.index"></a><strong>operator.index</strong> (t, k)</dt> <dd> get the indexed value from a table [] -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -516,17 +537,19 @@ get the indexed value from a table [] + + </dd> -<dt><a name="land"></a><strong>land</strong> (a, b)</dt> +<dt><a name="operator.land"></a><strong>operator.land</strong> (a, b)</dt> <dd> true if both values evaluate as true (i.e. not nil or false) and -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -546,17 +569,19 @@ true if both values evaluate as true (i.e. not nil or false) and + + </dd> -<dt><a name="le"></a><strong>le</strong> (a, b)</dt> +<dt><a name="operator.le"></a><strong>operator.le</strong> (a, b)</dt> <dd> returns true if a is less or equal to b <= -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -576,17 +601,19 @@ returns true if a is less or equal to b <= + + </dd> -<dt><a name="len"></a><strong>len</strong> (a)</dt> +<dt><a name="operator.len"></a><strong>operator.len</strong> (a)</dt> <dd> returns length of string or table # -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -602,17 +629,19 @@ returns length of string or table # + + </dd> -<dt><a name="lnot"></a><strong>lnot</strong> (a)</dt> +<dt><a name="operator.lnot"></a><strong>operator.lnot</strong> (a)</dt> <dd> false if value evaluates as true (i.e. not nil or false) not -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -628,17 +657,19 @@ false if value evaluates as true (i.e. not nil or false) not + + </dd> -<dt><a name="lor"></a><strong>lor</strong> (a, b)</dt> +<dt><a name="operator.lor"></a><strong>operator.lor</strong> (a, b)</dt> <dd> true if either value evaluate as true (i.e. not nil or false) or -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -658,17 +689,19 @@ true if either value evaluate as true (i.e. not nil or false) or + + </dd> -<dt><a name="lt"></a><strong>lt</strong> (a, b)</dt> +<dt><a name="operator.lt"></a><strong>operator.lt</strong> (a, b)</dt> <dd> returns true if a is less than b < -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -688,17 +721,19 @@ returns true if a is less than b < + + </dd> -<dt><a name="mod"></a><strong>mod</strong> (a, b)</dt> +<dt><a name="operator.mod"></a><strong>operator.mod</strong> (a, b)</dt> <dd> modulo; remainder of a divided by b % -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -718,17 +753,19 @@ modulo; remainder of a divided by b % + + </dd> -<dt><a name="mul"></a><strong>mul</strong> (a, b)</dt> +<dt><a name="operator.mul"></a><strong>operator.mul</strong> (a, b)</dt> <dd> multiply two values * -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -748,17 +785,19 @@ multiply two values * + + </dd> -<dt><a name="neq"></a><strong>neq</strong> (a, b)</dt> +<dt><a name="operator.neq"></a><strong>operator.neq</strong> (a, b)</dt> <dd> returns true if arguments are not equal ~= -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -778,17 +817,19 @@ returns true if arguments are not equal ~= + + </dd> -<dt><a name="nop"></a><strong>nop</strong> (...)</dt> +<dt><a name="operator.nop"></a><strong>operator.nop</strong> (...)</dt> <dd> the null operation. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -802,6 +843,8 @@ the null operation. + + <h3>Return value:</h3> the arguments @@ -812,12 +855,12 @@ the arguments -<dt><a name="pow"></a><strong>pow</strong> (a, b)</dt> +<dt><a name="operator.pow"></a><strong>operator.pow</strong> (a, b)</dt> <dd> raise first to the power of second ^ -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -837,17 +880,19 @@ raise first to the power of second ^ + + </dd> -<dt><a name="sub"></a><strong>sub</strong> (a, b)</dt> +<dt><a name="operator.sub"></a><strong>operator.sub</strong> (a, b)</dt> <dd> subtract b from a - -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -867,17 +912,19 @@ subtract b from a - + + </dd> -<dt><a name="table"></a><strong>table</strong> (...)</dt> +<dt><a name="operator.table"></a><strong>operator.table</strong> (...)</dt> <dd> make a table from the arguments. {} -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -891,6 +938,8 @@ make a table from the arguments. {} + + <h3>Return value:</h3> a table @@ -901,12 +950,12 @@ a table -<dt><a name="unm"></a><strong>unm</strong> (a)</dt> +<dt><a name="operator.unm"></a><strong>operator.unm</strong> (a)</dt> <dd> return the negative of a value - -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -922,6 +971,8 @@ return the negative of a value - + + </dd> diff --git a/docs/api/modules/pl.path.html b/docs/api/modules/pl.path.html index 4b33cd9..59ca212 100644 --- a/docs/api/modules/pl.path.html +++ b/docs/api/modules/pl.path.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.path: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +75,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,10 @@ <div id="content"> -<h1>Module <code>pl.path</code></h1> +<h1>Module "pl.path"</h1> -<p>path manipulation and file queries. <br> This is modelled after Python's os.path library (11.1)</p> +<p>path manipulation and file queries. <br> +This is modelled after Python's os.path library (11.1)</p> @@ -155,102 +160,102 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#abspath">abspath</a> (path)</td> + <td class="name" nowrap><a href="#path.abspath">path.abspath</a> (P, PP)</td> <td class="summary">return an absolute path.</td> </tr> <tr> - <td class="name" nowrap><a href="#basename">basename</a> (path)</td> + <td class="name" nowrap><a href="#path.basename">path.basename</a> (P)</td> <td class="summary">return the file part of a path </td> </tr> <tr> - <td class="name" nowrap><a href="#common_prefix">common_prefix</a> (path1, path2)</td> + <td class="name" nowrap><a href="#path.common_prefix">path.common_prefix</a> (path1, path2)</td> <td class="summary">return the largest common prefix path of two paths.</td> </tr> <tr> - <td class="name" nowrap><a href="#dirname">dirname</a> (path)</td> + <td class="name" nowrap><a href="#path.dirname">path.dirname</a> (P)</td> <td class="summary">return the directory part of a path </td> </tr> <tr> - <td class="name" nowrap><a href="#exists">exists</a> (path)</td> + <td class="name" nowrap><a href="#path.exists">path.exists</a> (P)</td> <td class="summary">does a path exist?.</td> </tr> <tr> - <td class="name" nowrap><a href="#expanduser">expanduser</a> (path)</td> + <td class="name" nowrap><a href="#path.expanduser">path.expanduser</a> (P)</td> <td class="summary">Replace a starting '~' with the user's home directory.</td> </tr> <tr> - <td class="name" nowrap><a href="#extension">extension</a> (path)</td> + <td class="name" nowrap><a href="#path.extension">path.extension</a> (P)</td> <td class="summary">get the extension part of a path.</td> </tr> <tr> - <td class="name" nowrap><a href="#getatime">getatime</a> (path)</td> + <td class="name" nowrap><a href="#path.getatime">path.getatime</a> (P)</td> <td class="summary">Return the time of last access as the number of seconds since the epoch.</td> </tr> <tr> - <td class="name" nowrap><a href="#getctime">getctime</a> (path)</td> + <td class="name" nowrap><a href="#path.getctime">path.getctime</a> (P)</td> <td class="summary">Return the system's ctime.</td> </tr> <tr> - <td class="name" nowrap><a href="#getmtime">getmtime</a> (path)</td> + <td class="name" nowrap><a href="#path.getmtime">path.getmtime</a> (P)</td> <td class="summary">Return the time of last modification </td> </tr> <tr> - <td class="name" nowrap><a href="#getsize">getsize</a> (path)</td> + <td class="name" nowrap><a href="#path.getsize">path.getsize</a> (P)</td> <td class="summary">return size of a file.</td> </tr> <tr> - <td class="name" nowrap><a href="#isabs">isabs</a> (path)</td> + <td class="name" nowrap><a href="#path.isabs">path.isabs</a> (P)</td> <td class="summary">is this an absolute path?.</td> </tr> <tr> - <td class="name" nowrap><a href="#isdir">isdir</a> (path)</td> + <td class="name" nowrap><a href="#path.isdir">path.isdir</a> (P)</td> <td class="summary">is this a directory? </td> </tr> <tr> - <td class="name" nowrap><a href="#isfile">isfile</a> (path)</td> + <td class="name" nowrap><a href="#path.isfile">path.isfile</a> (P)</td> <td class="summary">is this a file?.</td> </tr> <tr> - <td class="name" nowrap><a href="#join">join</a> (p1, p2)</td> - <td class="summary">return the path resulting from combining the two paths.</td> + <td class="name" nowrap><a href="#path.join">path.join</a> (p1, p2)</td> + <td class="summary">return the P resulting from combining the two paths.</td> </tr> <tr> - <td class="name" nowrap><a href="#normcase">normcase</a> (path)</td> + <td class="name" nowrap><a href="#path.normcase">path.normcase</a> (P)</td> <td class="summary">Normalize the case of a pathname.</td> </tr> <tr> - <td class="name" nowrap><a href="#package_path">package_path</a> (mod)</td> + <td class="name" nowrap><a href="#path.package_path">path.package_path</a> (mod)</td> <td class="summary">return the full path where a particular Lua module would be found.</td> </tr> <tr> - <td class="name" nowrap><a href="#splitext">splitext</a> (path)</td> + <td class="name" nowrap><a href="#path.splitext">path.splitext</a> (P)</td> <td class="summary">given a path, return the root part and the extension part.</td> </tr> <tr> - <td class="name" nowrap><a href="#splitpath">splitpath</a> (path)</td> + <td class="name" nowrap><a href="#path.splitpath">path.splitpath</a> (P)</td> <td class="summary">given a path, return the directory part and a file part.</td> </tr> <tr> - <td class="name" nowrap><a href="#tmpname">tmpname</a> ()</td> + <td class="name" nowrap><a href="#path.tmpname">path.tmpname</a> ()</td> <td class="summary">Return a suitable full path to a new temporary file name.</td> </tr> @@ -271,16 +276,20 @@ -<dt><a name="abspath"></a><strong>abspath</strong> (path)</dt> +<dt><a name="path.abspath"></a><strong>path.abspath</strong> (P, PP)</dt> <dd> return an absolute path. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: + </li> + + <li> + PP: A A file path </li> </ul> @@ -292,21 +301,23 @@ return an absolute path. + + </dd> -<dt><a name="basename"></a><strong>basename</strong> (path)</dt> +<dt><a name="path.basename"></a><strong>path.basename</strong> (P)</dt> <dd> return the file part of a path -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -318,17 +329,19 @@ return the file part of a path + + </dd> -<dt><a name="common_prefix"></a><strong>common_prefix</strong> (path1, path2)</dt> +<dt><a name="path.common_prefix"></a><strong>path.common_prefix</strong> (path1, path2)</dt> <dd> return the largest common prefix path of two paths. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -348,21 +361,23 @@ return the largest common prefix path of two paths. + + </dd> -<dt><a name="dirname"></a><strong>dirname</strong> (path)</dt> +<dt><a name="path.dirname"></a><strong>path.dirname</strong> (P)</dt> <dd> return the directory part of a path -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -374,21 +389,23 @@ return the directory part of a path + + </dd> -<dt><a name="exists"></a><strong>exists</strong> (path)</dt> +<dt><a name="path.exists"></a><strong>path.exists</strong> (P)</dt> <dd> does a path exist?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -400,21 +417,28 @@ does a path exist?. +<h3>Return value:</h3> +the file path if it exists, nil otherwise + + + </dd> -<dt><a name="expanduser"></a><strong>expanduser</strong> (path)</dt> +<dt><a name="path.expanduser"></a><strong>path.expanduser</strong> (P)</dt> <dd> -Replace a starting '~' with the user's home directory. In windows, if HOME isn't set, then USERPROFILE is used in preference to HOMEDRIVE HOMEPATH. This is guaranteed to be writeable on all versions of Windows. +Replace a starting '~' with the user's home directory. +In windows, if HOME isn't set, then USERPROFILE is used in preference to +HOMEDRIVE HOMEPATH. This is guaranteed to be writeable on all versions of Windows. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -426,21 +450,23 @@ Replace a starting '~' with the user's home directory. In windows, if HOME isn't + + </dd> -<dt><a name="extension"></a><strong>extension</strong> (path)</dt> +<dt><a name="path.extension"></a><strong>path.extension</strong> (P)</dt> <dd> get the extension part of a path. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -452,21 +478,23 @@ get the extension part of a path. + + </dd> -<dt><a name="getatime"></a><strong>getatime</strong> (path)</dt> +<dt><a name="path.getatime"></a><strong>path.getatime</strong> (P)</dt> <dd> Return the time of last access as the number of seconds since the epoch. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -478,21 +506,23 @@ Return the time of last access as the number of seconds since the epoch. + + </dd> -<dt><a name="getctime"></a><strong>getctime</strong> (path)</dt> +<dt><a name="path.getctime"></a><strong>path.getctime</strong> (P)</dt> <dd> Return the system's ctime. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -504,21 +534,23 @@ Return the system's ctime. + + </dd> -<dt><a name="getmtime"></a><strong>getmtime</strong> (path)</dt> +<dt><a name="path.getmtime"></a><strong>path.getmtime</strong> (P)</dt> <dd> Return the time of last modification -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -530,21 +562,23 @@ Return the time of last modification + + </dd> -<dt><a name="getsize"></a><strong>getsize</strong> (path)</dt> +<dt><a name="path.getsize"></a><strong>path.getsize</strong> (P)</dt> <dd> return size of a file. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -556,21 +590,23 @@ return size of a file. + + </dd> -<dt><a name="isabs"></a><strong>isabs</strong> (path)</dt> +<dt><a name="path.isabs"></a><strong>path.isabs</strong> (P)</dt> <dd> is this an absolute path?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -582,21 +618,23 @@ is this an absolute path?. + + </dd> -<dt><a name="isdir"></a><strong>isdir</strong> (path)</dt> +<dt><a name="path.isdir"></a><strong>path.isdir</strong> (P)</dt> <dd> is this a directory? -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -608,21 +646,23 @@ is this a directory? + + </dd> -<dt><a name="isfile"></a><strong>isfile</strong> (path)</dt> +<dt><a name="path.isfile"></a><strong>path.isfile</strong> (P)</dt> <dd> is this a file?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -634,17 +674,20 @@ is this a file?. + + </dd> -<dt><a name="join"></a><strong>join</strong> (p1, p2)</dt> +<dt><a name="path.join"></a><strong>path.join</strong> (p1, p2)</dt> <dd> -return the path resulting from combining the two paths. if the second is already an absolute path, then it returns it. +return the P resulting from combining the two paths. +if the second is already an absolute path, then it returns it. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -664,21 +707,25 @@ return the path resulting from combining the two paths. if the second is already + + </dd> -<dt><a name="normcase"></a><strong>normcase</strong> (path)</dt> +<dt><a name="path.normcase"></a><strong>path.normcase</strong> (P)</dt> <dd> -Normalize the case of a pathname. On Unix, this returns the path unchanged; for Windows, it converts the path to lowercase, and it also converts forward slashes to backward slashes. Will also replace '\dir\..\' by '\' (PL extension!) +Normalize the case of a pathname. On Unix, this returns the path unchanged; + for Windows, it converts the path to lowercase, and it also converts forward slashes +to backward slashes. Will also replace '\dir\..\' by '\' (PL extension!) -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -690,17 +737,21 @@ Normalize the case of a pathname. On Unix, this returns the path unchanged; for + + </dd> -<dt><a name="package_path"></a><strong>package_path</strong> (mod)</dt> +<dt><a name="path.package_path"></a><strong>path.package_path</strong> (mod)</dt> <dd> -return the full path where a particular Lua module would be found. Both package.path and package.cpath is searched, so the result may either be a Lua file or a shared libarary. +return the full path where a particular Lua module would be found. +Both package.path and package.cpath is searched, so the result may +either be a Lua file or a shared libarary. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -714,6 +765,8 @@ return the full path where a particular Lua module would be found. Both package. + + <h3>Return values:</h3> <ol> @@ -730,16 +783,17 @@ return the full path where a particular Lua module would be found. Both package. -<dt><a name="splitext"></a><strong>splitext</strong> (path)</dt> +<dt><a name="path.splitext"></a><strong>path.splitext</strong> (P)</dt> <dd> -given a path, return the root part and the extension part. if there's no extension part, the second value will be empty +given a path, return the root part and the extension part. +if there's no extension part, the second value will be empty -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -751,21 +805,24 @@ given a path, return the root part and the extension part. if there's no extensi + + </dd> -<dt><a name="splitpath"></a><strong>splitpath</strong> (path)</dt> +<dt><a name="path.splitpath"></a><strong>path.splitpath</strong> (P)</dt> <dd> -given a path, return the directory part and a file part. if there's no directory part, the first value will be empty +given a path, return the directory part and a file part. +if there's no directory part, the first value will be empty -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - path: A file path + P: A file path </li> </ul> @@ -777,14 +834,19 @@ given a path, return the directory part and a file part. if there's no directory + + </dd> -<dt><a name="tmpname"></a><strong>tmpname</strong> ()</dt> +<dt><a name="path.tmpname"></a><strong>path.tmpname</strong> ()</dt> <dd> -Return a suitable full path to a new temporary file name. unlike os.tmpnam(), it always gives you a writeable path (uses %TMP% on Windows) +Return a suitable full path to a new temporary file name. +unlike os.tmpnam(), it always gives you a writeable path (uses %TMP% on Windows) + + diff --git a/docs/api/modules/pl.permute.html b/docs/api/modules/pl.permute.html index 640b495..50639a7 100644 --- a/docs/api/modules/pl.permute.html +++ b/docs/api/modules/pl.permute.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.permute: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +75,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,9 @@ <div id="content"> -<h1>Module <code>pl.permute</code></h1> +<h1>Module "pl.permute"</h1> -<p>Permutation operations</p> +<p>Permutation operations.</p> @@ -155,12 +159,12 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#iter">iter</a> (a)</td> + <td class="name" nowrap><a href="#permute.iter">permute.iter</a> (a)</td> <td class="summary">an iterator over all permutations of the elements of a list.</td> </tr> <tr> - <td class="name" nowrap><a href="#table">table</a> (a)</td> + <td class="name" nowrap><a href="#permute.table">permute.table</a> (a)</td> <td class="summary">construct a table containing all the permutations of a list.</td> </tr> @@ -181,12 +185,13 @@ -<dt><a name="iter"></a><strong>iter</strong> (a)</dt> +<dt><a name="permute.iter"></a><strong>permute.iter</strong> (a)</dt> <dd> -an iterator over all permutations of the elements of a list. Please note that the same list is returned each time, so do not keep references! +an iterator over all permutations of the elements of a list. +Please note that the same list is returned each time, so do not keep references! -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -200,6 +205,8 @@ an iterator over all permutations of the elements of a list. Please note that th + + <h3>Return value:</h3> an iterator which provides the next permutation as a list @@ -210,12 +217,12 @@ an iterator which provides the next permutation as a list -<dt><a name="table"></a><strong>table</strong> (a)</dt> +<dt><a name="permute.table"></a><strong>permute.table</strong> (a)</dt> <dd> construct a table containing all the permutations of a list. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -232,6 +239,8 @@ permute.table {1,2,3} --> {{2,3,1},{3,2,1},{3,1,2},{1,3,2},{2,1,3},{1,2,3}} + + <h3>Return value:</h3> a table of tables diff --git a/docs/api/modules/pl.pretty.html b/docs/api/modules/pl.pretty.html index 74ff5c2..906fb70 100644 --- a/docs/api/modules/pl.pretty.html +++ b/docs/api/modules/pl.pretty.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.pretty: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +75,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,9 @@ <div id="content"> -<h1>Module <code>pl.pretty</code></h1> +<h1>Module "pl.pretty"</h1> -<p>Pretty-printing Lua tables</p> +<p>Pretty-printing Lua tables.</p> @@ -155,18 +159,18 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#dump">dump</a> (t, ...)</td> - <td class="summary">Dump a Lua table out to a file or stdout.</td> + <td class="name" nowrap><a href="#pretty.dump">pretty.dump</a> (t, ...)</td> + <td class="summary"> Dump a Lua table out to a file or stdout.</td> </tr> <tr> - <td class="name" nowrap><a href="#read">read</a> (s)</td> + <td class="name" nowrap><a href="#pretty.read">pretty.read</a> (s)</td> <td class="summary">read a string representation of a Lua table.</td> </tr> <tr> - <td class="name" nowrap><a href="#write">write</a> (tbl, space, not_clever)</td> - <td class="summary">Create a string representation of a Lua table.</td> + <td class="name" nowrap><a href="#pretty.write">pretty.write</a> (tbl, space, not_clever)</td> + <td class="summary"> Create a string representation of a Lua table.</td> </tr> </table> @@ -186,12 +190,12 @@ -<dt><a name="dump"></a><strong>dump</strong> (t, ...)</dt> +<dt><a name="pretty.dump"></a><strong>pretty.dump</strong> (t, ...)</dt> <dd> -Dump a Lua table out to a file or stdout. + Dump a Lua table out to a file or stdout. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -199,7 +203,8 @@ Dump a Lua table out to a file or stdout. </li> <li> - ...: {string} (optional) File name to write too. Defaults to writing to stdout. + ...: {string} (optional) File name to write too. Defaults to writing + to stdout. </li> </ul> @@ -211,21 +216,28 @@ Dump a Lua table out to a file or stdout. + + </dd> -<dt><a name="read"></a><strong>read</strong> (s)</dt> +<dt><a name="pretty.read"></a><strong>pretty.read</strong> (s)</dt> <dd> -read a string representation of a Lua table. Uses loadstring, but tries to be cautious about loading arbitrary code! It is expecting a string of the form '{...}', with perhaps some whitespace before or after the curly braces. An empty environment is used, and any occurance of the keyword 'function' will be considered a problem. +read a string representation of a Lua table. +Uses loadstring, but tries to be cautious about loading arbitrary code! +It is expecting a string of the form '{...}', with perhaps some whitespace +before or after the curly braces. An empty environment is used, and +any occurance of the keyword 'function' will be considered a problem. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - s: {string} string of the form '{...}', with perhaps some whitespace before or after the curly braces. + s: {string} string of the form '{...}', with perhaps some whitespace + before or after the curly braces. </li> </ul> @@ -237,17 +249,19 @@ read a string representation of a Lua table. Uses loadstring, but tries to be ca + + </dd> -<dt><a name="write"></a><strong>write</strong> (tbl, space, not_clever)</dt> +<dt><a name="pretty.write"></a><strong>pretty.write</strong> (tbl, space, not_clever)</dt> <dd> -Create a string representation of a Lua table. + Create a string representation of a Lua table. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -255,11 +269,13 @@ Create a string representation of a Lua table. </li> <li> - space: {string} (optional) The indent to use. Defaults to two spaces. + space: {string} (optional) The indent to use. + Defaults to two spaces. </li> <li> - not_clever: {bool} (optional) Use for plain output, e.g {['key']=1}. Defaults to false. + not_clever: {bool} (optional) Use for plain output, e.g {['key']=1}. + Defaults to false. </li> </ul> @@ -271,6 +287,8 @@ Create a string representation of a Lua table. + + </dd> diff --git a/docs/api/modules/pl.seq.html b/docs/api/modules/pl.seq.html index c7959e2..fde1518 100644 --- a/docs/api/modules/pl.seq.html +++ b/docs/api/modules/pl.seq.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.seq: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +75,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,7 +147,7 @@ <div id="content"> -<h1>Module <code>pl.seq</code></h1> +<h1>Module "pl.seq"</h1> <p>Manipulating sequences as iterators.</p> @@ -155,117 +159,118 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#copy">copy</a> (iter)</td> + <td class="name" nowrap><a href="#seq.copy">seq.copy</a> (iter)</td> <td class="summary">create a table from the sequence.</td> </tr> <tr> - <td class="name" nowrap><a href="#copy2">copy2</a> (iter, i1, i2)</td> + <td class="name" nowrap><a href="#seq.copy2">seq.copy2</a> (iter, i1, i2)</td> <td class="summary">create a table of pairs from the double-valued sequence.</td> </tr> <tr> - <td class="name" nowrap><a href="#copy_tuples">copy_tuples</a> (iter)</td> + <td class="name" nowrap><a href="#seq.copy_tuples">seq.copy_tuples</a> (iter)</td> <td class="summary">create a table of 'tuples' from a multi-valued sequence.</td> </tr> <tr> - <td class="name" nowrap><a href="#count_map">count_map</a> (iter)</td> + <td class="name" nowrap><a href="#seq.count_map">seq.count_map</a> (iter)</td> <td class="summary">A table where the key/values are the values and value counts of the sequence.</td> </tr> <tr> - <td class="name" nowrap><a href="#enum">enum</a> (iter)</td> + <td class="name" nowrap><a href="#seq.enum">seq.enum</a> (iter)</td> <td class="summary">a sequence with a sequence count and the original value.</td> </tr> <tr> - <td class="name" nowrap><a href="#filter">filter</a> (iter, pred, arg)</td> + <td class="name" nowrap><a href="#seq.filter">seq.filter</a> (iter, pred, arg)</td> <td class="summary">filter a sequence using a predicate function </td> </tr> <tr> - <td class="name" nowrap><a href="#foreach">foreach</a> (iter, fn)</td> + <td class="name" nowrap><a href="#seq.foreach">seq.foreach</a> (iter, fn)</td> <td class="summary">call the function on each element of the sequence.</td> </tr> <tr> - <td class="name" nowrap><a href="#keys">keys</a> (t)</td> + <td class="name" nowrap><a href="#seq.keys">seq.keys</a> (t)</td> <td class="summary">return the keys of the table.</td> </tr> <tr> - <td class="name" nowrap><a href="#last">last</a> (iter)</td> + <td class="name" nowrap><a href="#seq.last">seq.last</a> (iter)</td> <td class="summary">a sequence of (last,current) values from another sequence.</td> </tr> <tr> - <td class="name" nowrap><a href="#lines">lines</a> (f)</td> + <td class="name" nowrap><a href="#seq.lines">seq.lines</a> (f)</td> <td class="summary">create a wrapped iterator over all lines in the file.</td> </tr> <tr> - <td class="name" nowrap><a href="#list">list</a> (t)</td> + <td class="name" nowrap><a href="#seq.list">seq.list</a> (t)</td> <td class="summary">sequence adaptor for a table.</td> </tr> <tr> - <td class="name" nowrap><a href="#map">map</a> (fn, iter, arg)</td> - <td class="summary">return a sequence where every element of a sequence has been transformed by a function.</td> + <td class="name" nowrap><a href="#seq.map">seq.map</a> (fn, iter, arg)</td> + <td class="summary">return a sequence where every element of a sequence has been transformed +by a function.</td> </tr> <tr> - <td class="name" nowrap><a href="#mapmethod">mapmethod</a> (iter, name, arg1, arg2)</td> + <td class="name" nowrap><a href="#seq.mapmethod">seq.mapmethod</a> (iter, name, arg1, arg2)</td> <td class="summary">map using a named method over a sequence.</td> </tr> <tr> - <td class="name" nowrap><a href="#matching">matching</a> (s, a)</td> + <td class="name" nowrap><a href="#seq.matching">seq.matching</a> (s, a)</td> <td class="summary">given a string, return a function(y) which matches y against the string.</td> </tr> <tr> - <td class="name" nowrap><a href="#minmax">minmax</a> (iter)</td> + <td class="name" nowrap><a href="#seq.minmax">seq.minmax</a> (iter)</td> <td class="summary">return the minimum and the maximum value of the sequence.</td> </tr> <tr> - <td class="name" nowrap><a href="#random">random</a> (n, l, u)</td> + <td class="name" nowrap><a href="#seq.random">seq.random</a> (n, l, u)</td> <td class="summary">return an iterator of random numbers.</td> </tr> <tr> - <td class="name" nowrap><a href="#range">range</a> (start, finish)</td> + <td class="name" nowrap><a href="#seq.range">seq.range</a> (start, finish)</td> <td class="summary">create an iterator over a numerical range.</td> </tr> <tr> - <td class="name" nowrap><a href="#reduce">reduce</a> (fun, seq, oldval)</td> + <td class="name" nowrap><a href="#seq.reduce">seq.reduce</a> (fun, seq, oldval)</td> <td class="summary">'reduce' a sequence using a binary function.</td> </tr> <tr> - <td class="name" nowrap><a href="#skip">skip</a> (iter, n)</td> + <td class="name" nowrap><a href="#seq.skip">seq.skip</a> (iter, n)</td> <td class="summary">skip the first n values of a sequence </td> </tr> <tr> - <td class="name" nowrap><a href="#sort">sort</a> (iter, comp)</td> + <td class="name" nowrap><a href="#seq.sort">seq.sort</a> (iter, comp)</td> <td class="summary">return an iterator to the sorted elements of a sequence.</td> </tr> <tr> - <td class="name" nowrap><a href="#sum">sum</a> (iter, fn)</td> + <td class="name" nowrap><a href="#seq.sum">seq.sum</a> (iter, fn)</td> <td class="summary">return the sum and element count of the sequence.</td> </tr> <tr> - <td class="name" nowrap><a href="#take">take</a> (iter, n)</td> + <td class="name" nowrap><a href="#seq.take">seq.take</a> (iter, n)</td> <td class="summary">take the first n values from the sequence.</td> </tr> <tr> - <td class="name" nowrap><a href="#zip">zip</a> (iter1, iter2)</td> + <td class="name" nowrap><a href="#seq.zip">seq.zip</a> (iter1, iter2)</td> <td class="summary">return an iterator which returns elements of two sequences.</td> </tr> @@ -286,12 +291,12 @@ -<dt><a name="copy"></a><strong>copy</strong> (iter)</dt> +<dt><a name="seq.copy"></a><strong>seq.copy</strong> (iter)</dt> <dd> create a table from the sequence. (This will make the result a List.) -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -303,7 +308,7 @@ create a table from the sequence. (This will make the result a List.) -<h3>Usage</h3> +<h3>Usage:</h3> <ul> <li>copy(list(ls)) is equal to ls @@ -314,6 +319,8 @@ create a table from the sequence. (This will make the result a List.) + + <h3>Return value:</h3> a List @@ -324,12 +331,12 @@ a List -<dt><a name="copy2"></a><strong>copy2</strong> (iter, i1, i2)</dt> +<dt><a name="seq.copy2"></a><strong>seq.copy2</strong> (iter, i1, i2)</dt> <dd> create a table of pairs from the double-valued sequence. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -351,6 +358,8 @@ create a table of pairs from the double-valued sequence. + + <h3>Return value:</h3> a list-like table @@ -361,12 +370,13 @@ a list-like table -<dt><a name="copy_tuples"></a><strong>copy_tuples</strong> (iter)</dt> +<dt><a name="seq.copy_tuples"></a><strong>seq.copy_tuples</strong> (iter)</dt> <dd> -create a table of 'tuples' from a multi-valued sequence. A generalization of copy2 above +create a table of 'tuples' from a multi-valued sequence. +A generalization of copy2 above -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -380,6 +390,8 @@ create a table of 'tuples' from a multi-valued sequence. A generalization of cop + + <h3>Return value:</h3> a list-like table @@ -390,12 +402,14 @@ a list-like table -<dt><a name="count_map"></a><strong>count_map</strong> (iter)</dt> +<dt><a name="seq.count_map"></a><strong>seq.count_map</strong> (iter)</dt> <dd> -A table where the key/values are the values and value counts of the sequence. This version works with 'hashable' values like strings and numbers. <br> pl.tablex.count_map is more general. +A table where the key/values are the values and value counts of the sequence. +This version works with 'hashable' values like strings and numbers. <br> +pl.tablex.count_map is more general. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -409,6 +423,8 @@ A table where the key/values are the values and value counts of the sequence. Th + + <h3>Return values:</h3> <ol> @@ -423,7 +439,7 @@ A table where the key/values are the values and value counts of the sequence. Th <h3>See also:</h3> <ul> - <li><a href="../modules/pl.tablex.html#count_map"> + <li><a href=""> pl.tablex.count_map </a> @@ -434,12 +450,13 @@ A table where the key/values are the values and value counts of the sequence. Th -<dt><a name="enum"></a><strong>enum</strong> (iter)</dt> +<dt><a name="seq.enum"></a><strong>seq.enum</strong> (iter)</dt> <dd> -a sequence with a sequence count and the original value. <br> enum(copy(ls)) is a roundabout way of saying ipairs(ls). +a sequence with a sequence count and the original value. <br> +enum(copy(ls)) is a roundabout way of saying ipairs(ls). -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -453,6 +470,8 @@ a sequence with a sequence count and the original value. <br> enum(copy(ls)) is + + <h3>Return value:</h3> sequence of (i,v), i = 1..n and v is from iter. @@ -463,12 +482,12 @@ sequence of (i,v), i = 1..n and v is from iter. -<dt><a name="filter"></a><strong>filter</strong> (iter, pred, arg)</dt> +<dt><a name="seq.filter"></a><strong>seq.filter</strong> (iter, pred, arg)</dt> <dd> filter a sequence using a predicate function -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -492,17 +511,19 @@ filter a sequence using a predicate function + + </dd> -<dt><a name="foreach"></a><strong>foreach</strong> (iter, fn)</dt> +<dt><a name="seq.foreach"></a><strong>seq.foreach</strong> (iter, fn)</dt> <dd> call the function on each element of the sequence. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -522,17 +543,19 @@ call the function on each element of the sequence. + + </dd> -<dt><a name="keys"></a><strong>keys</strong> (t)</dt> +<dt><a name="seq.keys"></a><strong>seq.keys</strong> (t)</dt> <dd> return the keys of the table. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -546,6 +569,8 @@ return the keys of the table. + + <h3>Return value:</h3> iterator over keys @@ -556,12 +581,13 @@ iterator over keys -<dt><a name="last"></a><strong>last</strong> (iter)</dt> +<dt><a name="seq.last"></a><strong>seq.last</strong> (iter)</dt> <dd> -a sequence of (last,current) values from another sequence. This will return S(i-1),S(i) if given S(i) +a sequence of (last,current) values from another sequence. + This will return S(i-1),S(i) if given S(i) -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -577,17 +603,19 @@ a sequence of (last,current) values from another sequence. This will return S(i- + + </dd> -<dt><a name="lines"></a><strong>lines</strong> (f)</dt> +<dt><a name="seq.lines"></a><strong>seq.lines</strong> (f)</dt> <dd> create a wrapped iterator over all lines in the file. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -601,6 +629,8 @@ create a wrapped iterator over all lines in the file. + + <h3>Return value:</h3> a sequence wrapper @@ -611,12 +641,13 @@ a sequence wrapper -<dt><a name="list"></a><strong>list</strong> (t)</dt> +<dt><a name="seq.list"></a><strong>seq.list</strong> (t)</dt> <dd> -sequence adaptor for a table. Note that if any generic function is passed a table, it will automatically use seq.list() +sequence adaptor for a table. Note that if any generic function is +passed a table, it will automatically use seq.list() -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -628,7 +659,7 @@ sequence adaptor for a table. Note that if any generic function is passed a ta -<h3>Usage</h3> +<h3>Usage:</h3> <ul> <li>sum(list(t)) is the sum of all elements of t @@ -641,17 +672,22 @@ sequence adaptor for a table. Note that if any generic function is passed a ta + + </dd> -<dt><a name="map"></a><strong>map</strong> (fn, iter, arg)</dt> +<dt><a name="seq.map"></a><strong>seq.map</strong> (fn, iter, arg)</dt> <dd> -return a sequence where every element of a sequence has been transformed by a function. If you don't supply an argument, then the function will receive both values of a double-valued sequence, otherwise behaves rather like tablex.map. +return a sequence where every element of a sequence has been transformed +by a function. If you don't supply an argument, then the function will +receive both values of a double-valued sequence, otherwise behaves rather like +tablex.map. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -675,17 +711,19 @@ return a sequence where every element of a sequence has been transformed by a fu + + </dd> -<dt><a name="mapmethod"></a><strong>mapmethod</strong> (iter, name, arg1, arg2)</dt> +<dt><a name="seq.mapmethod"></a><strong>seq.mapmethod</strong> (iter, name, arg1, arg2)</dt> <dd> map using a named method over a sequence. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -713,17 +751,19 @@ map using a named method over a sequence. + + </dd> -<dt><a name="matching"></a><strong>matching</strong> (s, a)</dt> +<dt><a name="seq.matching"></a><strong>seq.matching</strong> (s, a)</dt> <dd> given a string, return a function(y) which matches y against the string. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -743,17 +783,19 @@ given a string, return a function(y) which matches y against the string. + + </dd> -<dt><a name="minmax"></a><strong>minmax</strong> (iter)</dt> +<dt><a name="seq.minmax"></a><strong>seq.minmax</strong> (iter)</dt> <dd> return the minimum and the maximum value of the sequence. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -769,17 +811,19 @@ return the minimum and the maximum value of the sequence. + + </dd> -<dt><a name="random"></a><strong>random</strong> (n, l, u)</dt> +<dt><a name="seq.random"></a><strong>seq.random</strong> (n, l, u)</dt> <dd> return an iterator of random numbers. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -801,6 +845,8 @@ return an iterator of random numbers. + + <h3>Return value:</h3> a sequnce @@ -811,12 +857,12 @@ a sequnce -<dt><a name="range"></a><strong>range</strong> (start, finish)</dt> +<dt><a name="seq.range"></a><strong>seq.range</strong> (start, finish)</dt> <dd> create an iterator over a numerical range. Like the standard Python function xrange. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -836,17 +882,19 @@ create an iterator over a numerical range. Like the standard Python function xra + + </dd> -<dt><a name="reduce"></a><strong>reduce</strong> (fun, seq, oldval)</dt> +<dt><a name="seq.reduce"></a><strong>seq.reduce</strong> (fun, seq, oldval)</dt> <dd> 'reduce' a sequence using a binary function. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -873,17 +921,19 @@ seq.reduce(operator.add,seq.list{1,2,3,4}) == 10 + + </dd> -<dt><a name="skip"></a><strong>skip</strong> (iter, n)</dt> +<dt><a name="seq.skip"></a><strong>seq.skip</strong> (iter, n)</dt> <dd> skip the first n values of a sequence -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -903,17 +953,19 @@ skip the first n values of a sequence + + </dd> -<dt><a name="sort"></a><strong>sort</strong> (iter, comp)</dt> +<dt><a name="seq.sort"></a><strong>seq.sort</strong> (iter, comp)</dt> <dd> return an iterator to the sorted elements of a sequence. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -933,17 +985,19 @@ return an iterator to the sorted elements of a sequence. + + </dd> -<dt><a name="sum"></a><strong>sum</strong> (iter, fn)</dt> +<dt><a name="seq.sum"></a><strong>seq.sum</strong> (iter, fn)</dt> <dd> return the sum and element count of the sequence. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -963,17 +1017,19 @@ return the sum and element count of the sequence. + + </dd> -<dt><a name="take"></a><strong>take</strong> (iter, n)</dt> +<dt><a name="seq.take"></a><strong>seq.take</strong> (iter, n)</dt> <dd> take the first n values from the sequence. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -991,6 +1047,8 @@ take the first n values from the sequence. + + <h3>Return value:</h3> a sequence of at most n items @@ -1001,12 +1059,12 @@ a sequence of at most n items -<dt><a name="zip"></a><strong>zip</strong> (iter1, iter2)</dt> +<dt><a name="seq.zip"></a><strong>seq.zip</strong> (iter1, iter2)</dt> <dd> return an iterator which returns elements of two sequences. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1029,6 +1087,8 @@ for x,y in seq.zip(ls1,ls2) do....end + + </dd> diff --git a/docs/api/modules/pl.sip.html b/docs/api/modules/pl.sip.html index 0132247..0d23e11 100644 --- a/docs/api/modules/pl.sip.html +++ b/docs/api/modules/pl.sip.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.sip: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +75,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,28 @@ <div id="content"> -<h1>Module <code>pl.sip</code></h1> +<h1>Module "pl.sip"</h1> -<p>Simple Input Patterns (SIP). SIP patterns start with '$', then a one-letter type, and then an optional variable in curly braces. <br> Example: <pre class=example>sip.match('($q{first},$q{second})','("john","smith")',res)</pre> <pre class=example>result is true and 'res' is: {second='smith',first='john'} </pre> See <a href="../../index.html#sip">the Guide</a></p> +<p>Simple Input Patterns (SIP). <p> +SIP patterns start with '$', then a +one-letter type, and then an optional variable in curly braces. <p> +Example: +<pre class=example> + sip.match('$v=$q','name="dolly"',res) + ==> res=={'name','dolly'} + sip.match('($q{first},$q{second})','("john","smith")',res) + ==> res=={second='smith',first='john'} +</pre> +<pre> +<b>Type names</b> +v identifier +i integer +f floating-point +q quoted string +([{< match up to closing bracket +</pre> +<p> +See <a href="../../index.html#sip">the Guide</a></p> @@ -155,37 +178,37 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#compile">compile</a> (spec, options)</td> + <td class="name" nowrap><a href="#sip.compile">sip.compile</a> (spec, options)</td> <td class="summary">convert a SIP pattern into a matching function.</td> </tr> <tr> - <td class="name" nowrap><a href="#create_pattern">create_pattern</a> (spec, options, fieldnames, fieldtypes)</td> + <td class="name" nowrap><a href="#sip.create_pattern">sip.create_pattern</a> (spec, options, fieldnames, fieldtypes)</td> <td class="summary">convert a SIP pattern into the equivalent Lua regular expression.</td> </tr> <tr> - <td class="name" nowrap><a href="#fields">fields</a> (spec, f)</td> + <td class="name" nowrap><a href="#sip.fields">sip.fields</a> (spec, f)</td> <td class="summary">given a pattern and a file object, return an iterator over the results </td> </tr> <tr> - <td class="name" nowrap><a href="#match">match</a> (spec, line, res, options)</td> + <td class="name" nowrap><a href="#sip.match">sip.match</a> (spec, line, res, options)</td> <td class="summary">match a SIP pattern against a string.</td> </tr> <tr> - <td class="name" nowrap><a href="#match_at_start">match_at_start</a> (spec, line, res)</td> + <td class="name" nowrap><a href="#sip.match_at_start">sip.match_at_start</a> (spec, line, res)</td> <td class="summary">match a SIP pattern against the start of a string.</td> </tr> <tr> - <td class="name" nowrap><a href="#pattern">pattern</a> (spec, fun)</td> + <td class="name" nowrap><a href="#sip.pattern">sip.pattern</a> (spec, fun)</td> <td class="summary">register a match which will be used in the read function.</td> </tr> <tr> - <td class="name" nowrap><a href="#read">read</a> (f)</td> + <td class="name" nowrap><a href="#sip.read">sip.read</a> (f)</td> <td class="summary">enter a loop which applies all registered matches to the input file.</td> </tr> @@ -206,12 +229,15 @@ -<dt><a name="compile"></a><strong>compile</strong> (spec, options)</dt> +<dt><a name="sip.compile"></a><strong>sip.compile</strong> (spec, options)</dt> <dd> -convert a SIP pattern into a matching function. The returned function takes two arguments, the line and an empty table. If the line matched the pattern, then this function return true and the table is filled with field-value pairs. +convert a SIP pattern into a matching function. +The returned function takes two arguments, the line and an empty table. +If the line matched the pattern, then this function return true +and the table is filled with field-value pairs. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -229,6 +255,8 @@ convert a SIP pattern into a matching function. The returned function takes two + + <h3>Return value:</h3> a function if successful, or nil,<error> @@ -239,12 +267,12 @@ a function if successful, or nil,<error> -<dt><a name="create_pattern"></a><strong>create_pattern</strong> (spec, options, fieldnames, fieldtypes)</dt> +<dt><a name="sip.create_pattern"></a><strong>sip.create_pattern</strong> (spec, options, fieldnames, fieldtypes)</dt> <dd> convert a SIP pattern into the equivalent Lua regular expression. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -272,17 +300,19 @@ convert a SIP pattern into the equivalent Lua regular expression. + + </dd> -<dt><a name="fields"></a><strong>fields</strong> (spec, f)</dt> +<dt><a name="sip.fields"></a><strong>sip.fields</strong> (spec, f)</dt> <dd> given a pattern and a file object, return an iterator over the results -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -302,17 +332,19 @@ given a pattern and a file object, return an iterator over the results + + </dd> -<dt><a name="match"></a><strong>match</strong> (spec, line, res, options)</dt> +<dt><a name="sip.match"></a><strong>sip.match</strong> (spec, line, res, options)</dt> <dd> match a SIP pattern against a string. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -338,6 +370,8 @@ match a SIP pattern against a string. + + <h3>Return value:</h3> true or false @@ -348,12 +382,12 @@ true or false -<dt><a name="match_at_start"></a><strong>match_at_start</strong> (spec, line, res)</dt> +<dt><a name="sip.match_at_start"></a><strong>sip.match_at_start</strong> (spec, line, res)</dt> <dd> match a SIP pattern against the start of a string. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -375,6 +409,8 @@ match a SIP pattern against the start of a string. + + <h3>Return value:</h3> true or false @@ -385,12 +421,12 @@ true or false -<dt><a name="pattern"></a><strong>pattern</strong> (spec, fun)</dt> +<dt><a name="sip.pattern"></a><strong>sip.pattern</strong> (spec, fun)</dt> <dd> register a match which will be used in the read function. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -410,10 +446,12 @@ register a match which will be used in the read function. + + <h3>See also:</h3> <ul> - <li><a href="../modules/pl.sip.html#read"> + <li><a href=""> read </a> @@ -424,12 +462,12 @@ register a match which will be used in the read function. -<dt><a name="read"></a><strong>read</strong> (f)</dt> +<dt><a name="sip.read"></a><strong>sip.read</strong> (f)</dt> <dd> enter a loop which applies all registered matches to the input file. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -445,6 +483,8 @@ enter a loop which applies all registered matches to the input file. + + </dd> diff --git a/docs/api/modules/pl.stringio.html b/docs/api/modules/pl.stringio.html index 65fad22..beeecc4 100644 --- a/docs/api/modules/pl.stringio.html +++ b/docs/api/modules/pl.stringio.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.stringio: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +75,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,9 @@ <div id="content"> -<h1>Module <code>pl.stringio</code></h1> +<h1>Module "pl.stringio"</h1> -<p>reading and writing strings using Lua IO</p> +<p>reading and writing strings using Lua IO.</p> @@ -155,12 +159,12 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#create">create</a> ()</td> + <td class="name" nowrap><a href="#stringio.create">stringio.create</a> ()</td> <td class="summary">create a file object which can be used to construct a string.</td> </tr> <tr> - <td class="name" nowrap><a href="#open">open</a> (s)</td> + <td class="name" nowrap><a href="#stringio.open">stringio.open</a> (s)</td> <td class="summary">create a file object for reading from a given string.</td> </tr> @@ -181,9 +185,11 @@ -<dt><a name="create"></a><strong>create</strong> ()</dt> +<dt><a name="stringio.create"></a><strong>stringio.create</strong> ()</dt> <dd> -create a file object which can be used to construct a string. The resulting file object will have an extra value() method for retrieving the string value. +create a file object which can be used to construct a string. +The resulting file object will have an extra value() method for +retrieving the string value. @@ -196,17 +202,19 @@ f = create(); f:write('hello, dolly\n'); print(f:value()) + + </dd> -<dt><a name="open"></a><strong>open</strong> (s)</dt> +<dt><a name="stringio.open"></a><strong>stringio.open</strong> (s)</dt> <dd> create a file object for reading from a given string. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -222,6 +230,8 @@ create a file object for reading from a given string. + + </dd> diff --git a/docs/api/modules/pl.stringx.html b/docs/api/modules/pl.stringx.html index 82c4bca..b52dcf7 100644 --- a/docs/api/modules/pl.stringx.html +++ b/docs/api/modules/pl.stringx.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.stringx: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +75,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,13 @@ <div id="content"> -<h1>Module <code>pl.stringx</code></h1> +<h1>Module "pl.stringx"</h1> -<p>Python-style string library. see 3.6.1 of the Python reference. <br> <br> If you want to make these available as string methods, then say <code>stringx.import()</code> to bring them into the standard <code>string</code> table.</p> +<p>Python-style string library. <p> +see 3.6.1 of the Python reference. <p> +If you want to make these available as string methods, then say +<code>stringx.import()</code> to bring them into the standard <code>string</code> +table.</p> @@ -155,132 +163,137 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#at">at</a> (self, idx)</td> + <td class="name" nowrap><a href="#split">split</a> (self, re)</td> + <td class="summary">split a string into a list of strings using a pattern.</td> + </tr> + + <tr> + <td class="name" nowrap><a href="#stringx.at">stringx.at</a> (self, idx)</td> <td class="summary">return the 'character' at the index.</td> </tr> <tr> - <td class="name" nowrap><a href="#center">center</a> (s, w, ch)</td> + <td class="name" nowrap><a href="#stringx.center">stringx.center</a> (s, w, ch)</td> <td class="summary">center-justify s with width w.</td> </tr> <tr> - <td class="name" nowrap><a href="#count">count</a> (self, sub)</td> + <td class="name" nowrap><a href="#stringx.count">stringx.count</a> (self, sub)</td> <td class="summary">count all instances of substring in string.</td> </tr> <tr> - <td class="name" nowrap><a href="#endswith">endswith</a> (self, s, first, last)</td> + <td class="name" nowrap><a href="#stringx.endswith">stringx.endswith</a> (self, s, first, last)</td> <td class="summary">does string end with the given substring?.</td> </tr> <tr> - <td class="name" nowrap><a href="#expandtabs">expandtabs</a> (self, n)</td> + <td class="name" nowrap><a href="#stringx.expandtabs">stringx.expandtabs</a> (self, n)</td> <td class="summary">replace all tabs in s with n spaces.</td> </tr> <tr> - <td class="name" nowrap><a href="#isalnum">isalnum</a> (s)</td> + <td class="name" nowrap><a href="#stringx.isalnum">stringx.isalnum</a> (s)</td> <td class="summary">does s only contain alphanumeric characters?.</td> </tr> <tr> - <td class="name" nowrap><a href="#isalpha">isalpha</a> (s)</td> + <td class="name" nowrap><a href="#stringx.isalpha">stringx.isalpha</a> (s)</td> <td class="summary">does s only contain alphabetic characters?.</td> </tr> <tr> - <td class="name" nowrap><a href="#isdigit">isdigit</a> (s)</td> + <td class="name" nowrap><a href="#stringx.isdigit">stringx.isdigit</a> (s)</td> <td class="summary">does s only contain digits?.</td> </tr> <tr> - <td class="name" nowrap><a href="#islower">islower</a> (s)</td> + <td class="name" nowrap><a href="#stringx.islower">stringx.islower</a> (s)</td> <td class="summary">does s only contain lower case characters?.</td> </tr> <tr> - <td class="name" nowrap><a href="#isspace">isspace</a> (s)</td> + <td class="name" nowrap><a href="#stringx.isspace">stringx.isspace</a> (s)</td> <td class="summary">does s only contain spaces?.</td> </tr> <tr> - <td class="name" nowrap><a href="#isupper">isupper</a> (s)</td> + <td class="name" nowrap><a href="#stringx.isupper">stringx.isupper</a> (s)</td> <td class="summary">does s only contain upper case characters?.</td> </tr> <tr> - <td class="name" nowrap><a href="#join">join</a> (self, seq)</td> + <td class="name" nowrap><a href="#stringx.join">stringx.join</a> (self, seq)</td> <td class="summary">concatenate the strings using this string as a delimiter.</td> </tr> <tr> - <td class="name" nowrap><a href="#lfind">lfind</a> (self, sub, i1)</td> + <td class="name" nowrap><a href="#stringx.lfind">stringx.lfind</a> (self, sub, i1)</td> <td class="summary">find index of first instance of sub in s from the left.</td> </tr> <tr> - <td class="name" nowrap><a href="#lines">lines</a> (self)</td> + <td class="name" nowrap><a href="#stringx.lines">stringx.lines</a> (self)</td> <td class="summary">return an interator over all lines in a string </td> </tr> <tr> - <td class="name" nowrap><a href="#ljust">ljust</a> (self, w, ch)</td> + <td class="name" nowrap><a href="#stringx.ljust">stringx.ljust</a> (self, w, ch)</td> <td class="summary">left-justify s with width w.</td> </tr> <tr> - <td class="name" nowrap><a href="#lstrip">lstrip</a> (self, chrs)</td> + <td class="name" nowrap><a href="#stringx.lstrip">stringx.lstrip</a> (self, chrs)</td> <td class="summary">trim any whitespace on the left of s.</td> </tr> <tr> - <td class="name" nowrap><a href="#partition">partition</a> (self, ch)</td> + <td class="name" nowrap><a href="#stringx.partition">stringx.partition</a> (self, ch)</td> <td class="summary">partition the string using first occurance of a delimiter </td> </tr> <tr> - <td class="name" nowrap><a href="#replace">replace</a> (s, old, new, n)</td> + <td class="name" nowrap><a href="#stringx.replace">stringx.replace</a> (s, old, new, n)</td> <td class="summary">replace up to n instances of old by new in the string s.</td> </tr> <tr> - <td class="name" nowrap><a href="#rfind">rfind</a> (self, sub, first, last)</td> + <td class="name" nowrap><a href="#stringx.rfind">stringx.rfind</a> (self, sub, first, last)</td> <td class="summary">find index of first instance of sub in s from the right.</td> </tr> <tr> - <td class="name" nowrap><a href="#rjust">rjust</a> (s, w, ch)</td> + <td class="name" nowrap><a href="#stringx.rjust">stringx.rjust</a> (s, w, ch)</td> <td class="summary">right-justify s with width w.</td> </tr> <tr> - <td class="name" nowrap><a href="#rpartition">rpartition</a> (self, ch)</td> + <td class="name" nowrap><a href="#stringx.rpartition">stringx.rpartition</a> (self, ch)</td> <td class="summary">partition the string p using last occurance of a delimiter </td> </tr> <tr> - <td class="name" nowrap><a href="#rstrip">rstrip</a> (s, chrs)</td> + <td class="name" nowrap><a href="#stringx.rstrip">stringx.rstrip</a> (s, chrs)</td> <td class="summary">trim any whitespace on the right of s.</td> </tr> <tr> - <td class="name" nowrap><a href="#split">split</a> (self, re)</td> - <td class="summary">split a string into a list of strings using a pattern.</td> + <td class="name" nowrap><a href="#stringx.shorten">stringx.shorten</a> (self, sz, tail)</td> + <td class="summary">return a shorted version of a string.</td> </tr> <tr> - <td class="name" nowrap><a href="#splitv">splitv</a> (self, re)</td> + <td class="name" nowrap><a href="#stringx.splitv">stringx.splitv</a> (self, re)</td> <td class="summary">split a string using a pattern.</td> </tr> <tr> - <td class="name" nowrap><a href="#startswith">startswith</a> (self, s2)</td> + <td class="name" nowrap><a href="#stringx.startswith">stringx.startswith</a> (self, s2)</td> <td class="summary">does string start with the substring?.</td> </tr> <tr> - <td class="name" nowrap><a href="#strip">strip</a> (self, chrs)</td> + <td class="name" nowrap><a href="#stringx.strip">stringx.strip</a> (self, chrs)</td> <td class="summary">trim any whitespace on both left and right of s.</td> </tr> @@ -301,12 +314,47 @@ -<dt><a name="at"></a><strong>at</strong> (self, idx)</dt> +<dt><a name="split"></a><strong>split</strong> (self, re)</dt> +<dd> +split a string into a list of strings using a pattern. + + +<h3>Parameters:</h3> +<ul> + + <li> + self: the string + </li> + + <li> + re: a Lua string pattern (defaults to whitespace) + </li> + +</ul> + + + + +<h3>Usage:</h3> +#(('one two'):split()) == 2 + + + + + + + +</dd> + + + + +<dt><a name="stringx.at"></a><strong>stringx.at</strong> (self, idx)</dt> <dd> return the 'character' at the index. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -324,6 +372,8 @@ return the 'character' at the index. + + <h3>Return value:</h3> a substring of length 1 if successful, empty string otherwise. @@ -334,12 +384,12 @@ a substring of length 1 if successful, empty string otherwise. -<dt><a name="center"></a><strong>center</strong> (s, w, ch)</dt> +<dt><a name="stringx.center"></a><strong>stringx.center</strong> (s, w, ch)</dt> <dd> center-justify s with width w. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -363,17 +413,19 @@ center-justify s with width w. + + </dd> -<dt><a name="count"></a><strong>count</strong> (self, sub)</dt> +<dt><a name="stringx.count"></a><strong>stringx.count</strong> (self, sub)</dt> <dd> count all instances of substring in string. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -393,17 +445,19 @@ count all instances of substring in string. + + </dd> -<dt><a name="endswith"></a><strong>endswith</strong> (self, s, first, last)</dt> +<dt><a name="stringx.endswith"></a><strong>stringx.endswith</strong> (self, s, first, last)</dt> <dd> does string end with the given substring?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -431,17 +485,19 @@ does string end with the given substring?. + + </dd> -<dt><a name="expandtabs"></a><strong>expandtabs</strong> (self, n)</dt> +<dt><a name="stringx.expandtabs"></a><strong>stringx.expandtabs</strong> (self, n)</dt> <dd> replace all tabs in s with n spaces. If not specified, n defaults to 8. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -461,17 +517,19 @@ replace all tabs in s with n spaces. If not specified, n defaults to 8. + + </dd> -<dt><a name="isalnum"></a><strong>isalnum</strong> (s)</dt> +<dt><a name="stringx.isalnum"></a><strong>stringx.isalnum</strong> (s)</dt> <dd> does s only contain alphanumeric characters?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -487,17 +545,19 @@ does s only contain alphanumeric characters?. + + </dd> -<dt><a name="isalpha"></a><strong>isalpha</strong> (s)</dt> +<dt><a name="stringx.isalpha"></a><strong>stringx.isalpha</strong> (s)</dt> <dd> does s only contain alphabetic characters?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -513,17 +573,19 @@ does s only contain alphabetic characters?. + + </dd> -<dt><a name="isdigit"></a><strong>isdigit</strong> (s)</dt> +<dt><a name="stringx.isdigit"></a><strong>stringx.isdigit</strong> (s)</dt> <dd> does s only contain digits?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -539,17 +601,19 @@ does s only contain digits?. + + </dd> -<dt><a name="islower"></a><strong>islower</strong> (s)</dt> +<dt><a name="stringx.islower"></a><strong>stringx.islower</strong> (s)</dt> <dd> does s only contain lower case characters?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -565,17 +629,19 @@ does s only contain lower case characters?. + + </dd> -<dt><a name="isspace"></a><strong>isspace</strong> (s)</dt> +<dt><a name="stringx.isspace"></a><strong>stringx.isspace</strong> (s)</dt> <dd> does s only contain spaces?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -591,17 +657,19 @@ does s only contain spaces?. + + </dd> -<dt><a name="isupper"></a><strong>isupper</strong> (s)</dt> +<dt><a name="stringx.isupper"></a><strong>stringx.isupper</strong> (s)</dt> <dd> does s only contain upper case characters?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -617,17 +685,19 @@ does s only contain upper case characters?. + + </dd> -<dt><a name="join"></a><strong>join</strong> (self, seq)</dt> +<dt><a name="stringx.join"></a><strong>stringx.join</strong> (self, seq)</dt> <dd> concatenate the strings using this string as a delimiter. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -650,17 +720,19 @@ concatenate the strings using this string as a delimiter. + + </dd> -<dt><a name="lfind"></a><strong>lfind</strong> (self, sub, i1)</dt> +<dt><a name="stringx.lfind"></a><strong>stringx.lfind</strong> (self, sub, i1)</dt> <dd> find index of first instance of sub in s from the left. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -672,7 +744,7 @@ find index of first instance of sub in s from the left. </li> <li> - i1: start index + i1: </li> </ul> @@ -684,17 +756,19 @@ find index of first instance of sub in s from the left. + + </dd> -<dt><a name="lines"></a><strong>lines</strong> (self)</dt> +<dt><a name="stringx.lines"></a><strong>stringx.lines</strong> (self)</dt> <dd> return an interator over all lines in a string -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -708,6 +782,8 @@ return an interator over all lines in a string + + <h3>Return value:</h3> an iterator @@ -718,12 +794,12 @@ an iterator -<dt><a name="ljust"></a><strong>ljust</strong> (self, w, ch)</dt> +<dt><a name="stringx.ljust"></a><strong>stringx.ljust</strong> (self, w, ch)</dt> <dd> left-justify s with width w. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -747,17 +823,19 @@ left-justify s with width w. + + </dd> -<dt><a name="lstrip"></a><strong>lstrip</strong> (self, chrs)</dt> +<dt><a name="stringx.lstrip"></a><strong>stringx.lstrip</strong> (self, chrs)</dt> <dd> trim any whitespace on the left of s. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -777,17 +855,19 @@ trim any whitespace on the left of s. + + </dd> -<dt><a name="partition"></a><strong>partition</strong> (self, ch)</dt> +<dt><a name="stringx.partition"></a><strong>stringx.partition</strong> (self, ch)</dt> <dd> partition the string using first occurance of a delimiter -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -805,6 +885,8 @@ partition the string using first occurance of a delimiter + + <h3>Return value:</h3> part before ch, ch, part after ch @@ -815,12 +897,13 @@ part before ch, ch, part after ch -<dt><a name="replace"></a><strong>replace</strong> (s, old, new, n)</dt> +<dt><a name="stringx.replace"></a><strong>stringx.replace</strong> (s, old, new, n)</dt> <dd> -replace up to n instances of old by new in the string s. if n is not present, replace all instances. +replace up to n instances of old by new in the string s. +if n is not present, replace all instances. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -846,6 +929,8 @@ replace up to n instances of old by new in the string s. if n is not present, re + + <h3>Return values:</h3> <ol> @@ -862,12 +947,12 @@ replace up to n instances of old by new in the string s. if n is not present, re -<dt><a name="rfind"></a><strong>rfind</strong> (self, sub, first, last)</dt> +<dt><a name="stringx.rfind"></a><strong>stringx.rfind</strong> (self, sub, first, last)</dt> <dd> find index of first instance of sub in s from the right. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -895,17 +980,19 @@ find index of first instance of sub in s from the right. + + </dd> -<dt><a name="rjust"></a><strong>rjust</strong> (s, w, ch)</dt> +<dt><a name="stringx.rjust"></a><strong>stringx.rjust</strong> (s, w, ch)</dt> <dd> right-justify s with width w. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -929,17 +1016,19 @@ right-justify s with width w. + + </dd> -<dt><a name="rpartition"></a><strong>rpartition</strong> (self, ch)</dt> +<dt><a name="stringx.rpartition"></a><strong>stringx.rpartition</strong> (self, ch)</dt> <dd> partition the string p using last occurance of a delimiter -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -957,6 +1046,8 @@ partition the string p using last occurance of a delimiter + + <h3>Return value:</h3> part before ch, ch, part after ch @@ -967,12 +1058,12 @@ part before ch, ch, part after ch -<dt><a name="rstrip"></a><strong>rstrip</strong> (s, chrs)</dt> +<dt><a name="stringx.rstrip"></a><strong>stringx.rstrip</strong> (s, chrs)</dt> <dd> trim any whitespace on the right of s. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -992,17 +1083,19 @@ trim any whitespace on the right of s. + + </dd> -<dt><a name="split"></a><strong>split</strong> (self, re)</dt> +<dt><a name="stringx.shorten"></a><strong>stringx.shorten</strong> (self, sz, tail)</dt> <dd> -split a string into a list of strings using a pattern. +return a shorted version of a string. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1010,7 +1103,11 @@ split a string into a list of strings using a pattern. </li> <li> - re: a Lua string pattern (defaults to whitespace) + sz: the maxinum size allowed + </li> + + <li> + tail: true if we want to show the end of the string (head otherwise) </li> </ul> @@ -1018,8 +1115,7 @@ split a string into a list of strings using a pattern. -<h3>Usage:</h3> -#(('one two'):split()) == 2 + @@ -1030,12 +1126,12 @@ split a string into a list of strings using a pattern. -<dt><a name="splitv"></a><strong>splitv</strong> (self, re)</dt> +<dt><a name="stringx.splitv"></a><strong>stringx.splitv</strong> (self, re)</dt> <dd> split a string using a pattern. Note that at least one value will be returned! -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1052,7 +1148,9 @@ split a string using a pattern. Note that at least one value will be returned! <h3>Usage:</h3> -a,b = line:splitv('=') + a,b = line:splitv('=') + + @@ -1066,12 +1164,12 @@ the parts of the string -<dt><a name="startswith"></a><strong>startswith</strong> (self, s2)</dt> +<dt><a name="stringx.startswith"></a><strong>stringx.startswith</strong> (self, s2)</dt> <dd> does string start with the substring?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1091,17 +1189,19 @@ does string start with the substring?. + + </dd> -<dt><a name="strip"></a><strong>strip</strong> (self, chrs)</dt> +<dt><a name="stringx.strip"></a><strong>stringx.strip</strong> (self, chrs)</dt> <dd> trim any whitespace on both left and right of s. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1121,6 +1221,8 @@ trim any whitespace on both left and right of s. + + </dd> diff --git a/docs/api/modules/pl.tablex.html b/docs/api/modules/pl.tablex.html index f533931..ae97285 100644 --- a/docs/api/modules/pl.tablex.html +++ b/docs/api/modules/pl.tablex.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.tablex: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +75,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,9 @@ <div id="content"> -<h1>Module <code>pl.tablex</code></h1> +<h1>Module "pl.tablex"</h1> -<p>Extended operations on Lua tables</p> +<p>Extended operations on Lua tables.</p> @@ -155,208 +159,209 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#clear">clear</a> (t, istart)</td> + <td class="name" nowrap><a href="#tablex.clear">tablex.clear</a> (t, istart)</td> <td class="summary">clear out the contents of a table.</td> </tr> <tr> - <td class="name" nowrap><a href="#compare">compare</a> (t1, t2, cmp)</td> + <td class="name" nowrap><a href="#tablex.compare">tablex.compare</a> (t1, t2, cmp)</td> <td class="summary">compare two list-like tables using a predicate.</td> </tr> <tr> - <td class="name" nowrap><a href="#compare_no_order">compare_no_order</a> (t1, t2, cmp)</td> + <td class="name" nowrap><a href="#tablex.compare_no_order">tablex.compare_no_order</a> (t1, t2, cmp)</td> <td class="summary">compare two list-like tables using an optional predicate, without regard for element order.</td> </tr> <tr> - <td class="name" nowrap><a href="#copy">copy</a> (t)</td> + <td class="name" nowrap><a href="#tablex.copy">tablex.copy</a> (t)</td> <td class="summary">make a shallow copy of a table </td> </tr> <tr> - <td class="name" nowrap><a href="#count_map">count_map</a> (t, cmp)</td> + <td class="name" nowrap><a href="#tablex.count_map">tablex.count_map</a> (t, cmp)</td> <td class="summary">A table where the key/values are the values and value counts of the table.</td> </tr> <tr> - <td class="name" nowrap><a href="#deepcompare">deepcompare</a> (t1, t2, ignore_mt)</td> + <td class="name" nowrap><a href="#tablex.deepcompare">tablex.deepcompare</a> (t1, t2, ignore_mt)</td> <td class="summary">compare two values.</td> </tr> <tr> - <td class="name" nowrap><a href="#deepcopy">deepcopy</a> (t)</td> + <td class="name" nowrap><a href="#tablex.deepcopy">tablex.deepcopy</a> (t)</td> <td class="summary">make a deep copy of a table, recursively copying all the keys and fields.</td> </tr> <tr> - <td class="name" nowrap><a href="#difference">difference</a> (s1, s2, symm)</td> + <td class="name" nowrap><a href="#tablex.difference">tablex.difference</a> (s1, s2, symm)</td> <td class="summary">a new table which is the difference of two tables.</td> </tr> <tr> - <td class="name" nowrap><a href="#filter">filter</a> (t, pred, arg, optional)</td> + <td class="name" nowrap><a href="#tablex.filter">tablex.filter</a> (t, pred, arg, optional)</td> <td class="summary">filter a table's values using a predicate function </td> </tr> <tr> - <td class="name" nowrap><a href="#find">find</a> (t, val, idx)</td> + <td class="name" nowrap><a href="#tablex.find">tablex.find</a> (t, val, idx)</td> <td class="summary">return the index of a value in a list.</td> </tr> <tr> - <td class="name" nowrap><a href="#find_if">find_if</a> (t, cmp, arg)</td> + <td class="name" nowrap><a href="#tablex.find_if">tablex.find_if</a> (t, cmp, arg)</td> <td class="summary">return the index (or key) of a value in a table using a comparison function.</td> </tr> <tr> - <td class="name" nowrap><a href="#foreach">foreach</a> (t, fun, ...)</td> + <td class="name" nowrap><a href="#tablex.foreach">tablex.foreach</a> (t, fun, ...)</td> <td class="summary">apply a function to all elements of a table.</td> </tr> <tr> - <td class="name" nowrap><a href="#foreachi">foreachi</a> (t, fun, ...)</td> + <td class="name" nowrap><a href="#tablex.foreachi">tablex.foreachi</a> (t, fun, ...)</td> <td class="summary">apply a function to all elements of a list-like table in order.</td> </tr> <tr> - <td class="name" nowrap><a href="#icopy">icopy</a> (dest, src, idest, isrc, nsrc, n)</td> + <td class="name" nowrap><a href="#tablex.icopy">tablex.icopy</a> (dest, src, idest, isrc, nsrc, n)</td> <td class="summary">copy an array into another one, resizing the destination if necessary.</td> </tr> <tr> - <td class="name" nowrap><a href="#imap">imap</a> (fun, t, ...)</td> + <td class="name" nowrap><a href="#tablex.imap">tablex.imap</a> (fun, t, ...)</td> <td class="summary">apply a function to all values of a list.</td> </tr> <tr> - <td class="name" nowrap><a href="#imap2">imap2</a> (fun, t1, t2, ...)</td> + <td class="name" nowrap><a href="#tablex.imap2">tablex.imap2</a> (fun, t1, t2, ...)</td> <td class="summary">apply a function to values from two arrays.</td> </tr> <tr> - <td class="name" nowrap><a href="#index_by">index_by</a> (tbl, idx)</td> + <td class="name" nowrap><a href="#tablex.index_by">tablex.index_by</a> (tbl, idx)</td> <td class="summary">return a list of all values in a table indexed by another list.</td> </tr> <tr> - <td class="name" nowrap><a href="#index_map">index_map</a> (t)</td> + <td class="name" nowrap><a href="#tablex.index_map">tablex.index_map</a> (t)</td> <td class="summary">create an index map from a list-like table.</td> </tr> <tr> - <td class="name" nowrap><a href="#insertvalues">insertvalues</a> (t, ...)</td> + <td class="name" nowrap><a href="#tablex.insertvalues">tablex.insertvalues</a> (t, ...)</td> <td class="summary">insert values into a table.</td> </tr> <tr> - <td class="name" nowrap><a href="#keys">keys</a> (t)</td> + <td class="name" nowrap><a href="#tablex.keys">tablex.keys</a> (t)</td> <td class="summary">return all the keys of a table in arbitrary order.</td> </tr> <tr> - <td class="name" nowrap><a href="#makeset">makeset</a> (t)</td> + <td class="name" nowrap><a href="#tablex.makeset">tablex.makeset</a> (t)</td> <td class="summary">create a set from a list-like table.</td> </tr> <tr> - <td class="name" nowrap><a href="#map">map</a> (fun, t, ...)</td> + <td class="name" nowrap><a href="#tablex.map">tablex.map</a> (fun, t, ...)</td> <td class="summary">apply a function to all values of a table.</td> </tr> <tr> - <td class="name" nowrap><a href="#map2">map2</a> (fun, t1, t2, ...)</td> + <td class="name" nowrap><a href="#tablex.map2">tablex.map2</a> (fun, t1, t2, ...)</td> <td class="summary">apply a function to values from two tables.</td> </tr> <tr> - <td class="name" nowrap><a href="#map_named_method">map_named_method</a> (name, t, ...)</td> + <td class="name" nowrap><a href="#tablex.map_named_method">tablex.map_named_method</a> (name, t, ...)</td> <td class="summary">apply a named method to values from a table.</td> </tr> <tr> - <td class="name" nowrap><a href="#mapn">mapn</a> (fun, ...)</td> + <td class="name" nowrap><a href="#tablex.mapn">tablex.mapn</a> (fun, ...)</td> <td class="summary">Apply a function to a number of tables.</td> </tr> <tr> - <td class="name" nowrap><a href="#merge">merge</a> (t1, t2, dup)</td> + <td class="name" nowrap><a href="#tablex.merge">tablex.merge</a> (t1, t2, dup)</td> <td class="summary">combine two tables, either as union or intersection.</td> </tr> <tr> - <td class="name" nowrap><a href="#move">move</a> (dest, src, idest, isrc, nsrc, n)</td> + <td class="name" nowrap><a href="#tablex.move">tablex.move</a> (dest, src, idest, isrc, nsrc, n)</td> <td class="summary">copy an array into another one.</td> </tr> <tr> - <td class="name" nowrap><a href="#new">new</a> (n, val)</td> + <td class="name" nowrap><a href="#tablex.new">tablex.new</a> (n, val)</td> <td class="summary">create a new array of specified size with initial value.</td> </tr> <tr> - <td class="name" nowrap><a href="#pairmap">pairmap</a> (fun, t, ...)</td> + <td class="name" nowrap><a href="#tablex.pairmap">tablex.pairmap</a> (fun, t, ...)</td> <td class="summary">call the function with the key and value pairs from a table.</td> </tr> <tr> - <td class="name" nowrap><a href="#range">range</a> (start, finish, step)</td> + <td class="name" nowrap><a href="#tablex.range">tablex.range</a> (start, finish, step)</td> <td class="summary">generate a table of all numbers in a range </td> </tr> <tr> - <td class="name" nowrap><a href="#reduce">reduce</a> (fun, t)</td> + <td class="name" nowrap><a href="#tablex.reduce">tablex.reduce</a> (fun, t)</td> <td class="summary">'reduce' a list using a binary function.</td> </tr> <tr> - <td class="name" nowrap><a href="#removevalues">removevalues</a> (t, i1, i2)</td> + <td class="name" nowrap><a href="#tablex.removevalues">tablex.removevalues</a> (t, i1, i2)</td> <td class="summary">remove a range of values from a table.</td> </tr> <tr> - <td class="name" nowrap><a href="#rfind">rfind</a> (t, val, idx)</td> + <td class="name" nowrap><a href="#tablex.rfind">tablex.rfind</a> (t, val, idx)</td> <td class="summary">return the index of a value in a list, searching from the end.</td> </tr> <tr> - <td class="name" nowrap><a href="#search">search</a> (t, value, exclude)</td> + <td class="name" nowrap><a href="#tablex.search">tablex.search</a> (t, value, exclude)</td> <td class="summary">find a value in a table by recursive search.</td> </tr> <tr> - <td class="name" nowrap><a href="#set">set</a> (t, val, i1, i2)</td> + <td class="name" nowrap><a href="#tablex.set">tablex.set</a> (t, val, i1, i2)</td> <td class="summary">set an array range to a value.</td> </tr> <tr> - <td class="name" nowrap><a href="#size">size</a> (t)</td> + <td class="name" nowrap><a href="#tablex.size">tablex.size</a> (t)</td> <td class="summary">total number of elements in this table.</td> </tr> <tr> - <td class="name" nowrap><a href="#sub">sub</a> (t, first, last)</td> + <td class="name" nowrap><a href="#tablex.sub">tablex.sub</a> (t, first, last)</td> <td class="summary">Extract a range from a table, like 'string.sub'.</td> </tr> <tr> - <td class="name" nowrap><a href="#transform">transform</a> (fun, t, ...)</td> + <td class="name" nowrap><a href="#tablex.transform">tablex.transform</a> (fun, t, ...)</td> <td class="summary">apply a function to all values of a table, in-place.</td> </tr> <tr> - <td class="name" nowrap><a href="#update">update</a> (t1, t2)</td> + <td class="name" nowrap><a href="#tablex.update">tablex.update</a> (t1, t2)</td> <td class="summary">copy a table into another, in-place.</td> </tr> <tr> - <td class="name" nowrap><a href="#values">values</a> (t)</td> + <td class="name" nowrap><a href="#tablex.values">tablex.values</a> (t)</td> <td class="summary">return all the values of the table in arbitrary order </td> </tr> <tr> - <td class="name" nowrap><a href="#zip">zip</a> (...)</td> - <td class="summary">return a table where each element is a table of the ith values of an arbitrary number of tables.</td> + <td class="name" nowrap><a href="#tablex.zip">tablex.zip</a> (...)</td> + <td class="summary">return a table where each element is a table of the ith values of an arbitrary +number of tables.</td> </tr> </table> @@ -376,12 +381,12 @@ -<dt><a name="clear"></a><strong>clear</strong> (t, istart)</dt> +<dt><a name="tablex.clear"></a><strong>tablex.clear</strong> (t, istart)</dt> <dd> clear out the contents of a table. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -401,17 +406,19 @@ clear out the contents of a table. + + </dd> -<dt><a name="compare"></a><strong>compare</strong> (t1, t2, cmp)</dt> +<dt><a name="tablex.compare"></a><strong>tablex.compare</strong> (t1, t2, cmp)</dt> <dd> compare two list-like tables using a predicate. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -435,17 +442,19 @@ compare two list-like tables using a predicate. + + </dd> -<dt><a name="compare_no_order"></a><strong>compare_no_order</strong> (t1, t2, cmp)</dt> +<dt><a name="tablex.compare_no_order"></a><strong>tablex.compare_no_order</strong> (t1, t2, cmp)</dt> <dd> compare two list-like tables using an optional predicate, without regard for element order. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -469,17 +478,19 @@ compare two list-like tables using an optional predicate, without regard for ele + + </dd> -<dt><a name="copy"></a><strong>copy</strong> (t)</dt> +<dt><a name="tablex.copy"></a><strong>tablex.copy</strong> (t)</dt> <dd> make a shallow copy of a table -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -493,6 +504,8 @@ make a shallow copy of a table + + <h3>Return value:</h3> new table @@ -503,12 +516,12 @@ new table -<dt><a name="count_map"></a><strong>count_map</strong> (t, cmp)</dt> +<dt><a name="tablex.count_map"></a><strong>tablex.count_map</strong> (t, cmp)</dt> <dd> A table where the key/values are the values and value counts of the table. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -526,6 +539,8 @@ A table where the key/values are the values and value counts of the table. + + <h3>Return value:</h3> a map-like table @@ -534,8 +549,8 @@ a map-like table <h3>See also:</h3> <ul> - <li><a href="../modules/pl.seq.html#count_map"> - pl.seq.count_map + <li><a href=""> + seq.count_map </a> </ul> @@ -545,12 +560,13 @@ a map-like table -<dt><a name="deepcompare"></a><strong>deepcompare</strong> (t1, t2, ignore_mt)</dt> +<dt><a name="tablex.deepcompare"></a><strong>tablex.deepcompare</strong> (t1, t2, ignore_mt)</dt> <dd> -compare two values. if they are tables, then compare their keys and fields recursively. +compare two values. +if they are tables, then compare their keys and fields recursively. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -572,6 +588,8 @@ compare two values. if they are tables, then compare their keys and fields recur + + <h3>Return value:</h3> true or false @@ -582,12 +600,13 @@ true or false -<dt><a name="deepcopy"></a><strong>deepcopy</strong> (t)</dt> +<dt><a name="tablex.deepcopy"></a><strong>tablex.deepcopy</strong> (t)</dt> <dd> -make a deep copy of a table, recursively copying all the keys and fields. This will also set the copied table's metatable to that of the original. +make a deep copy of a table, recursively copying all the keys and fields. +This will also set the copied table's metatable to that of the original. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -601,6 +620,8 @@ make a deep copy of a table, recursively copying all the keys and fields. This w + + <h3>Return value:</h3> new table @@ -611,12 +632,14 @@ new table -<dt><a name="difference"></a><strong>difference</strong> (s1, s2, symm)</dt> +<dt><a name="tablex.difference"></a><strong>tablex.difference</strong> (s1, s2, symm)</dt> <dd> -a new table which is the difference of two tables. With sets (where the values are all true) this is set difference and symmetric difference depending on the third parameter. +a new table which is the difference of two tables. +With sets (where the values are all true) this is set difference and +symmetric difference depending on the third parameter. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -638,6 +661,8 @@ a new table which is the difference of two tables. With sets (where the values a + + <h3>Return value:</h3> a map-like table or set @@ -648,12 +673,12 @@ a map-like table or set -<dt><a name="filter"></a><strong>filter</strong> (t, pred, arg, optional)</dt> +<dt><a name="tablex.filter"></a><strong>tablex.filter</strong> (t, pred, arg, optional)</dt> <dd> filter a table's values using a predicate function -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -681,17 +706,21 @@ filter a table's values using a predicate function + + </dd> -<dt><a name="find"></a><strong>find</strong> (t, val, idx)</dt> +<dt><a name="tablex.find"></a><strong>tablex.find</strong> (t, val, idx)</dt> <dd> -return the index of a value in a list. Like string.find, there is an optional index to start searching, which can be negative. +return the index of a value in a list. +Like string.find, there is an optional index to start searching, +which can be negative. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -711,7 +740,7 @@ return the index of a value in a list. Like string.find, there is an optional in -<h3>Usage</h3> +<h3>Usage:</h3> <ul> <li>find({10,20,30},20) == 2 @@ -722,6 +751,8 @@ return the index of a value in a list. Like string.find, there is an optional in + + <h3>Return value:</h3> index of value or nil if not found @@ -732,12 +763,12 @@ index of value or nil if not found -<dt><a name="find_if"></a><strong>find_if</strong> (t, cmp, arg)</dt> +<dt><a name="tablex.find_if"></a><strong>tablex.find_if</strong> (t, cmp, arg)</dt> <dd> return the index (or key) of a value in a table using a comparison function. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -759,6 +790,8 @@ return the index (or key) of a value in a table using a comparison function. + + <h3>Return values:</h3> <ol> @@ -775,12 +808,15 @@ return the index (or key) of a value in a table using a comparison function. -<dt><a name="foreach"></a><strong>foreach</strong> (t, fun, ...)</dt> +<dt><a name="tablex.foreach"></a><strong>tablex.foreach</strong> (t, fun, ...)</dt> <dd> -apply a function to all elements of a table. The arguments to the function will be the value, the key and <i>finally</i> any extra arguments passed to this function. Note that the Lua 5.0 function table.foreach passed the <i>key</i> first. +apply a function to all elements of a table. +The arguments to the function will be the value, +the key and <i>finally</i> any extra arguments passed to this function. +Note that the Lua 5.0 function table.foreach passed the <i>key</i> first. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -804,17 +840,21 @@ apply a function to all elements of a table. The arguments to the function will + + </dd> -<dt><a name="foreachi"></a><strong>foreachi</strong> (t, fun, ...)</dt> +<dt><a name="tablex.foreachi"></a><strong>tablex.foreachi</strong> (t, fun, ...)</dt> <dd> -apply a function to all elements of a list-like table in order. The arguments to the function will be the value, the index and <i>finally</i> any extra arguments passed to this function +apply a function to all elements of a list-like table in order. +The arguments to the function will be the value, +the index and <i>finally</i> any extra arguments passed to this function -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -838,17 +878,19 @@ apply a function to all elements of a list-like table in order. The arguments to + + </dd> -<dt><a name="icopy"></a><strong>icopy</strong> (dest, src, idest, isrc, nsrc, n)</dt> +<dt><a name="tablex.icopy"></a><strong>tablex.icopy</strong> (dest, src, idest, isrc, nsrc, n)</dt> <dd> copy an array into another one, resizing the destination if necessary. <br> -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -884,17 +926,21 @@ copy an array into another one, resizing the destination if necessary. <br> + + </dd> -<dt><a name="imap"></a><strong>imap</strong> (fun, t, ...)</dt> +<dt><a name="tablex.imap"></a><strong>tablex.imap</strong> (fun, t, ...)</dt> <dd> -apply a function to all values of a list. This returns a table of the results. Any extra arguments are passed to the function. +apply a function to all values of a list. +This returns a table of the results. +Any extra arguments are passed to the function. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -919,6 +965,8 @@ imap(function(v) return v*v end, {10,20,30,fred=2}) is {100,400,900} + + <h3>Return value:</h3> a list-like table @@ -929,12 +977,12 @@ a list-like table -<dt><a name="imap2"></a><strong>imap2</strong> (fun, t1, t2, ...)</dt> +<dt><a name="tablex.imap2"></a><strong>tablex.imap2</strong> (fun, t1, t2, ...)</dt> <dd> apply a function to values from two arrays. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -965,17 +1013,19 @@ imap2('+',{1,2,3,m=4},{10,20,30,m=40}) is {11,22,23} + + </dd> -<dt><a name="index_by"></a><strong>index_by</strong> (tbl, idx)</dt> +<dt><a name="tablex.index_by"></a><strong>tablex.index_by</strong> (tbl, idx)</dt> <dd> return a list of all values in a table indexed by another list. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -991,7 +1041,7 @@ return a list of all values in a table indexed by another list. -<h3>Usage</h3> +<h3>Usage:</h3> <ul> <li>index_by({10,20,30,40},{2,4}) == {20,40} @@ -1002,6 +1052,8 @@ return a list of all values in a table indexed by another list. + + <h3>Return value:</h3> a list-like table @@ -1012,12 +1064,13 @@ a list-like table -<dt><a name="index_map"></a><strong>index_map</strong> (t)</dt> +<dt><a name="tablex.index_map"></a><strong>tablex.index_map</strong> (t)</dt> <dd> -create an index map from a list-like table. The original values become keys, and the associated values are the indices into the original list. +create an index map from a list-like table. The original values become keys, +and the associated values are the indices into the original list. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1031,6 +1084,8 @@ create an index map from a list-like table. The original values become keys, and + + <h3>Return value:</h3> a map-like table @@ -1041,12 +1096,15 @@ a map-like table -<dt><a name="insertvalues"></a><strong>insertvalues</strong> (t, ...)</dt> +<dt><a name="tablex.insertvalues"></a><strong>tablex.insertvalues</strong> (t, ...)</dt> <dd> -insert values into a table. <br> insertvalues(t, [pos,] values) <br> similar to table.insert but inserts values from given table "values", not the object itself, into table "t" at position "pos". +insert values into a table. <br> +insertvalues(t, [pos,] values) <br> +similar to table.insert but inserts values from given table "values", +not the object itself, into table "t" at position "pos". -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1066,17 +1124,19 @@ insert values into a table. <br> insertvalues(t, [pos,] values) <br> similar to + + </dd> -<dt><a name="keys"></a><strong>keys</strong> (t)</dt> +<dt><a name="tablex.keys"></a><strong>tablex.keys</strong> (t)</dt> <dd> return all the keys of a table in arbitrary order. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1092,17 +1152,20 @@ return all the keys of a table in arbitrary order. + + </dd> -<dt><a name="makeset"></a><strong>makeset</strong> (t)</dt> +<dt><a name="tablex.makeset"></a><strong>tablex.makeset</strong> (t)</dt> <dd> -create a set from a list-like table. A set is a table where the original values become keys, and the associated values are all true. +create a set from a list-like table. A set is a table where the original values +become keys, and the associated values are all true. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1116,6 +1179,8 @@ create a set from a list-like table. A set is a table where the original values + + <h3>Return value:</h3> a set (a map-like table) @@ -1126,12 +1191,14 @@ a set (a map-like table) -<dt><a name="map"></a><strong>map</strong> (fun, t, ...)</dt> +<dt><a name="tablex.map"></a><strong>tablex.map</strong> (fun, t, ...)</dt> <dd> -apply a function to all values of a table. This returns a table of the results. Any extra arguments are passed to the function. +apply a function to all values of a table. +This returns a table of the results. +Any extra arguments are passed to the function. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1158,17 +1225,19 @@ map(function(v) return v*v end, {10,20,30,fred=2}) is {100,400,900,fred=4} + + </dd> -<dt><a name="map2"></a><strong>map2</strong> (fun, t1, t2, ...)</dt> +<dt><a name="tablex.map2"></a><strong>tablex.map2</strong> (fun, t1, t2, ...)</dt> <dd> apply a function to values from two tables. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1197,6 +1266,8 @@ map2('+',{1,2,3,m=4},{10,20,30,m=40}) is {11,22,23,m=44} + + <h3>Return value:</h3> a table @@ -1207,12 +1278,12 @@ a table -<dt><a name="map_named_method"></a><strong>map_named_method</strong> (name, t, ...)</dt> +<dt><a name="tablex.map_named_method"></a><strong>tablex.map_named_method</strong> (name, t, ...)</dt> <dd> apply a named method to values from a table. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1236,17 +1307,22 @@ apply a named method to values from a table. + + </dd> -<dt><a name="mapn"></a><strong>mapn</strong> (fun, ...)</dt> +<dt><a name="tablex.mapn"></a><strong>tablex.mapn</strong> (fun, ...)</dt> <dd> -Apply a function to a number of tables. A more general version of map The result is a table containing the result of applying that function to the ith value of each table. Length of output list is the minimum length of all the lists +Apply a function to a number of tables. +A more general version of map +The result is a table containing the result of applying that function to the +ith value of each table. Length of output list is the minimum length of all the lists -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1262,7 +1338,7 @@ Apply a function to a number of tables. A more general version of map The result -<h3>Usage</h3> +<h3>Usage:</h3> <ul> <li>mapn(function(x,y,z) return x+y+z end, {1,2,3},{10,20,30},{100,200,300}) is {111,222,333} @@ -1275,17 +1351,21 @@ Apply a function to a number of tables. A more general version of map The result + + </dd> -<dt><a name="merge"></a><strong>merge</strong> (t1, t2, dup)</dt> +<dt><a name="tablex.merge"></a><strong>tablex.merge</strong> (t1, t2, dup)</dt> <dd> -combine two tables, either as union or intersection. Corresponds to set operations for sets () but more general. Not particularly useful for list-like tables. +combine two tables, either as union or intersection. Corresponds to +set operations for sets () but more general. Not particularly +useful for list-like tables. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1305,7 +1385,7 @@ combine two tables, either as union or intersection. Corresponds to set operatio -<h3>Usage</h3> +<h3>Usage:</h3> <ul> <li>merge({alice=23,fred=34},{bob=25,fred=34}) is {fred=34} @@ -1318,11 +1398,13 @@ combine two tables, either as union or intersection. Corresponds to set operatio + + <h3>See also:</h3> <ul> - <li><a href="../modules/pl.tablex.html#index_map"> - index_map + <li><a href=""> + tablex.index_map </a> </ul> @@ -1332,12 +1414,12 @@ combine two tables, either as union or intersection. Corresponds to set operatio -<dt><a name="move"></a><strong>move</strong> (dest, src, idest, isrc, nsrc, n)</dt> +<dt><a name="tablex.move"></a><strong>tablex.move</strong> (dest, src, idest, isrc, nsrc, n)</dt> <dd> copy an array into another one. <br> -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1373,17 +1455,19 @@ copy an array into another one. <br> + + </dd> -<dt><a name="new"></a><strong>new</strong> (n, val)</dt> +<dt><a name="tablex.new"></a><strong>tablex.new</strong> (n, val)</dt> <dd> create a new array of specified size with initial value. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1401,6 +1485,8 @@ create a new array of specified size with initial value. + + <h3>Return value:</h3> the table @@ -1411,12 +1497,15 @@ the table -<dt><a name="pairmap"></a><strong>pairmap</strong> (fun, t, ...)</dt> +<dt><a name="tablex.pairmap"></a><strong>tablex.pairmap</strong> (fun, t, ...)</dt> <dd> -call the function with the key and value pairs from a table. The function can return a value and a key (note the order!). If both are not nil, then this pair is inserted into the result. If only value is not nil, then it is appended to the result. +call the function with the key and value pairs from a table. +The function can return a value and a key (note the order!). If both +are not nil, then this pair is inserted into the result. If only value is not nil, then +it is appended to the result. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1436,7 +1525,7 @@ call the function with the key and value pairs from a table. The function can re -<h3>Usage</h3> +<h3>Usage:</h3> <ul> <li>pairmap({fred=10,bonzo=20},function(k,v) return v end) is {10,20} @@ -1449,17 +1538,19 @@ call the function with the key and value pairs from a table. The function can re + + </dd> -<dt><a name="range"></a><strong>range</strong> (start, finish, step)</dt> +<dt><a name="tablex.range"></a><strong>tablex.range</strong> (start, finish, step)</dt> <dd> generate a table of all numbers in a range -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1483,17 +1574,19 @@ generate a table of all numbers in a range + + </dd> -<dt><a name="reduce"></a><strong>reduce</strong> (fun, t)</dt> +<dt><a name="tablex.reduce"></a><strong>tablex.reduce</strong> (fun, t)</dt> <dd> 'reduce' a list using a binary function. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1514,6 +1607,8 @@ reduce('+',{1,2,3,4}) == 10 + + <h3>Return value:</h3> the result of the function @@ -1524,12 +1619,12 @@ the result of the function -<dt><a name="removevalues"></a><strong>removevalues</strong> (t, i1, i2)</dt> +<dt><a name="tablex.removevalues"></a><strong>tablex.removevalues</strong> (t, i1, i2)</dt> <dd> remove a range of values from a table. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1551,6 +1646,8 @@ remove a range of values from a table. + + <h3>Return value:</h3> the table @@ -1561,12 +1658,14 @@ the table -<dt><a name="rfind"></a><strong>rfind</strong> (t, val, idx)</dt> +<dt><a name="tablex.rfind"></a><strong>tablex.rfind</strong> (t, val, idx)</dt> <dd> -return the index of a value in a list, searching from the end. Like string.find, there is an optional index to start searching, which can be negative. +return the index of a value in a list, searching from the end. +Like string.find, there is an optional index to start searching, +which can be negative. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1591,6 +1690,8 @@ rfind({10,10,10},10) == 3 + + <h3>Return value:</h3> index of value or nil if not found @@ -1601,12 +1702,12 @@ index of value or nil if not found -<dt><a name="search"></a><strong>search</strong> (t, value, exclude)</dt> +<dt><a name="tablex.search"></a><strong>tablex.search</strong> (t, value, exclude)</dt> <dd> find a value in a table by recursive search. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1631,6 +1732,8 @@ search(_G,math.sin,{package.path}) == 'math.sin' + + <h3>Return value:</h3> a fieldspec, e.g. 'a.b' or 'math.sin' @@ -1641,12 +1744,13 @@ a fieldspec, e.g. 'a.b' or 'math.sin' -<dt><a name="set"></a><strong>set</strong> (t, val, i1, i2)</dt> +<dt><a name="tablex.set"></a><strong>tablex.set</strong> (t, val, i1, i2)</dt> <dd> -set an array range to a value. If it's a function we use the result of applying it to the indices. +set an array range to a value. If it's a function we use the result +of applying it to the indices. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1674,17 +1778,23 @@ set an array range to a value. If it's a function we use the result of applying + + </dd> -<dt><a name="size"></a><strong>size</strong> (t)</dt> +<dt><a name="tablex.size"></a><strong>tablex.size</strong> (t)</dt> <dd> -total number of elements in this table. <br> Note that this is distinct from #t, which is the number of values in the array part; this value will always be greater or equal. The difference gives the size of the hash part, for practical purposes. +total number of elements in this table. <br> +Note that this is distinct from #t, which is the number +of values in the array part; this value will always +be greater or equal. The difference gives the size of +the hash part, for practical purposes. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1698,6 +1808,8 @@ total number of elements in this table. <br> Note that this is distinct from #t, + + <h3>Return value:</h3> the size @@ -1708,12 +1820,15 @@ the size -<dt><a name="sub"></a><strong>sub</strong> (t, first, last)</dt> +<dt><a name="tablex.sub"></a><strong>tablex.sub</strong> (t, first, last)</dt> <dd> -Extract a range from a table, like 'string.sub'. If first or last are negative then they are relative to the end of the list eg. sub(t,-2) gives last 2 entries in a list, and sub(t,-4,-2) gives from -4th to -2nd +Extract a range from a table, like 'string.sub'. +If first or last are negative then they are relative to the end of the list +eg. sub(t,-2) gives last 2 entries in a list, and +sub(t,-4,-2) gives from -4th to -2nd -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1735,6 +1850,8 @@ Extract a range from a table, like 'string.sub'. If first or last are negative + + <h3>Return value:</h3> a new List @@ -1745,12 +1862,13 @@ a new List -<dt><a name="transform"></a><strong>transform</strong> (fun, t, ...)</dt> +<dt><a name="tablex.transform"></a><strong>tablex.transform</strong> (fun, t, ...)</dt> <dd> -apply a function to all values of a table, in-place. Any extra arguments are passed to the function. +apply a function to all values of a table, in-place. +Any extra arguments are passed to the function. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1774,17 +1892,19 @@ apply a function to all values of a table, in-place. Any extra arguments are pas + + </dd> -<dt><a name="update"></a><strong>update</strong> (t1, t2)</dt> +<dt><a name="tablex.update"></a><strong>tablex.update</strong> (t1, t2)</dt> <dd> copy a table into another, in-place. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1802,6 +1922,8 @@ copy a table into another, in-place. + + <h3>Return value:</h3> first table @@ -1812,12 +1934,12 @@ first table -<dt><a name="values"></a><strong>values</strong> (t)</dt> +<dt><a name="tablex.values"></a><strong>tablex.values</strong> (t)</dt> <dd> return all the values of the table in arbitrary order -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1833,17 +1955,20 @@ return all the values of the table in arbitrary order + + </dd> -<dt><a name="zip"></a><strong>zip</strong> (...)</dt> +<dt><a name="tablex.zip"></a><strong>tablex.zip</strong> (...)</dt> <dd> -return a table where each element is a table of the ith values of an arbitrary number of tables. It is equivalent to a matrix transpose. +return a table where each element is a table of the ith values of an arbitrary +number of tables. It is equivalent to a matrix transpose. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -1862,6 +1987,8 @@ zip({10,20,30},{100,200,300}) is {{10,100},{20,200},{30,300}} + + </dd> diff --git a/docs/api/modules/pl.test.html b/docs/api/modules/pl.test.html index a57be5a..2c5bffc 100644 --- a/docs/api/modules/pl.test.html +++ b/docs/api/modules/pl.test.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.test: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +75,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,7 +147,7 @@ <div id="content"> -<h1>Module <code>pl.test</code></h1> +<h1>Module "pl.test"</h1> <p>Useful test utilities.</p> @@ -155,17 +159,17 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#asserteq">asserteq</a> (x, y)</td> + <td class="name" nowrap><a href="#test.asserteq">test.asserteq</a> (x, y)</td> <td class="summary">like assert, except takes two arguments that must be equal and can be tables.</td> </tr> <tr> - <td class="name" nowrap><a href="#asserteq2">asserteq2</a> (x1, x2, y1, y2)</td> + <td class="name" nowrap><a href="#test.asserteq2">test.asserteq2</a> (x1, x2, y1, y2)</td> <td class="summary">a version of asserteq that takes two pairs of values.</td> </tr> <tr> - <td class="name" nowrap><a href="#timer">timer</a> (msg, n, fun, ...)</td> + <td class="name" nowrap><a href="#test.timer">test.timer</a> (msg, n, fun, ...)</td> <td class="summary">Time a function.</td> </tr> @@ -186,12 +190,13 @@ -<dt><a name="asserteq"></a><strong>asserteq</strong> (x, y)</dt> +<dt><a name="test.asserteq"></a><strong>test.asserteq</strong> (x, y)</dt> <dd> -like assert, except takes two arguments that must be equal and can be tables. If they are plain tables, it will use tablex.deepcompare. +like assert, except takes two arguments that must be equal and can be tables. +If they are plain tables, it will use tablex.deepcompare. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -211,17 +216,21 @@ like assert, except takes two arguments that must be equal and can be tables. If + + </dd> -<dt><a name="asserteq2"></a><strong>asserteq2</strong> (x1, x2, y1, y2)</dt> +<dt><a name="test.asserteq2"></a><strong>test.asserteq2</strong> (x1, x2, y1, y2)</dt> <dd> -a version of asserteq that takes two pairs of values. <code>x1==y1 and x2==y2</code> must be true. Useful for functions that naturally return two values. +a version of asserteq that takes two pairs of values. +<code>x1==y1 and x2==y2</code> must be true. Useful for functions that naturally +return two values. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -249,17 +258,20 @@ a version of asserteq that takes two pairs of values. <code>x1==y1 and x2==y2</c + + </dd> -<dt><a name="timer"></a><strong>timer</strong> (msg, n, fun, ...)</dt> +<dt><a name="test.timer"></a><strong>test.timer</strong> (msg, n, fun, ...)</dt> <dd> -Time a function. Call the function a given number of times, and report the number of seconds taken, together with a message. Any extra arguments will be passed to the function. +Time a function. Call the function a given number of times, and report the number of seconds taken, +together with a message. Any extra arguments will be passed to the function. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -287,6 +299,8 @@ Time a function. Call the function a given number of times, and report the numbe + + </dd> diff --git a/docs/api/modules/pl.text.html b/docs/api/modules/pl.text.html index 31007d4..fc667eb 100644 --- a/docs/api/modules/pl.text.html +++ b/docs/api/modules/pl.text.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.text: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +75,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,9 +147,22 @@ <div id="content"> -<h1>Module <code>pl.text</code></h1> +<h1>Module "pl.text"</h1> -<p>Text processing utilities. <br> This provides a Template class (modeled after the same from the Python <br> libraries, see string.Template). It also provides dedent, wrap and fill as found in the textwrap module, as well as indent.</p> +<p>Text processing utilities. <p> +This provides a Template class (modeled after the same from the Python +libraries, see string.Template). It also provides similar functions to those +found in the textwrap module. +<p> +Calling <code>text.format_operator()</code> overloads the % operator for strings to give Python/Ruby style formated output. +This is extended to also do template-like substitution for map-like data. +<pre class=example> +> require 'pl.text'.format_operator() +> = '%s = %5.3f' % {'PI',math.pi} +PI = 3.142 +> = '$name = $value' % {name='dog',value='Pluto'} +dog = Pluto +</pre></p> @@ -170,22 +187,28 @@ </tr> <tr> - <td class="name" nowrap><a href="#dedent">dedent</a> (s)</td> + <td class="name" nowrap><a href="#text.dedent">text.dedent</a> (s)</td> <td class="summary">dedent a multiline string by removing any initial indent.</td> </tr> <tr> - <td class="name" nowrap><a href="#fill">fill</a> (s, width)</td> + <td class="name" nowrap><a href="#text.fill">text.fill</a> (s, width)</td> <td class="summary">format a paragraph so that it fits into a line width.</td> </tr> <tr> - <td class="name" nowrap><a href="#indent">indent</a> (s, n, ch)</td> + <td class="name" nowrap><a href="#text.format_operator">text.format_operator</a> ()</td> + <td class="summary">Python-style formatting operator ------ +(see http://lua-users.org/wiki/StringInterpolation) -- </td> + </tr> + + <tr> + <td class="name" nowrap><a href="#text.indent">text.indent</a> (s, n, ch)</td> <td class="summary">indent a multiline string.</td> </tr> <tr> - <td class="name" nowrap><a href="#wrap">wrap</a> (s, width)</td> + <td class="name" nowrap><a href="#text.wrap">text.wrap</a> (s, width)</td> <td class="summary">format a paragraph into lines so that they fit into a line width.</td> </tr> @@ -208,10 +231,14 @@ <dt><a name="Template:indent_substitute"></a><strong>Template:indent_substitute</strong> (tbl)</dt> <dd> -substitute values into a template, preserving indentation. <br> If the value is a multiline string _or_ a template, it will insert the lines at the correct indentation. <br> Furthermore, if a template, then that template will be subsituted using the same table. +substitute values into a template, preserving indentation. <br> +If the value is a multiline string _or_ a template, it will insert +the lines at the correct indentation. <br> +Furthermore, if a template, then that template will be subsituted +using the same table. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -227,6 +254,8 @@ substitute values into a template, preserving indentation. <br> If the value is + + </dd> @@ -234,10 +263,11 @@ substitute values into a template, preserving indentation. <br> If the value is <dt><a name="Template:safe_substitute"></a><strong>Template:safe_substitute</strong> (tbl)</dt> <dd> -substitute values into a template. This version just passes unknown names through. +substitute values into a template. +This version just passes unknown names through. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -253,6 +283,8 @@ substitute values into a template. This version just passes unknown names throug + + </dd> @@ -260,10 +292,11 @@ substitute values into a template. This version just passes unknown names throug <dt><a name="Template:substitute"></a><strong>Template:substitute</strong> (tbl)</dt> <dd> -substitute values into a template, throwing an error. This will throw an error if no name is found. +substitute values into a template, throwing an error. +This will throw an error if no name is found. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -279,17 +312,20 @@ substitute values into a template, throwing an error. This will throw an error i + + </dd> -<dt><a name="dedent"></a><strong>dedent</strong> (s)</dt> +<dt><a name="text.dedent"></a><strong>text.dedent</strong> (s)</dt> <dd> -dedent a multiline string by removing any initial indent. useful when working with [[..]] strings. +dedent a multiline string by removing any initial indent. +useful when working with [[..]] strings. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -303,6 +339,8 @@ dedent a multiline string by removing any initial indent. useful when working wi + + <h3>Return value:</h3> a string with initial indent zero. @@ -313,12 +351,12 @@ a string with initial indent zero. -<dt><a name="fill"></a><strong>fill</strong> (s, width)</dt> +<dt><a name="text.fill"></a><strong>text.fill</strong> (s, width)</dt> <dd> format a paragraph so that it fits into a line width. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -336,6 +374,8 @@ format a paragraph so that it fits into a line width. + + <h3>Return value:</h3> a string @@ -344,7 +384,7 @@ a string <h3>See also:</h3> <ul> - <li><a href="../modules/pl.text.html#wrap"> + <li><a href=""> wrap </a> @@ -355,12 +395,32 @@ a string -<dt><a name="indent"></a><strong>indent</strong> (s, n, ch)</dt> +<dt><a name="text.format_operator"></a><strong>text.format_operator</strong> ()</dt> +<dd> +Python-style formatting operator ------ +(see http://lua-users.org/wiki/StringInterpolation) -- + + + + + + + + + + + +</dd> + + + + +<dt><a name="text.indent"></a><strong>text.indent</strong> (s, n, ch)</dt> <dd> indent a multiline string. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -382,6 +442,8 @@ indent a multiline string. + + <h3>Return value:</h3> indented string @@ -392,12 +454,14 @@ indented string -<dt><a name="wrap"></a><strong>wrap</strong> (s, width)</dt> +<dt><a name="text.wrap"></a><strong>text.wrap</strong> (s, width)</dt> <dd> -format a paragraph into lines so that they fit into a line width. It will not break long words, so lines can be over the length to that extent. +format a paragraph into lines so that they fit into a line width. +It will not break long words, so lines can be over the length +to that extent. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -415,6 +479,8 @@ format a paragraph into lines so that they fit into a line width. It will not br + + <h3>Return value:</h3> a list of lines diff --git a/docs/api/modules/pl.utils.html b/docs/api/modules/pl.utils.html index 7a2a89e..b614a03 100644 --- a/docs/api/modules/pl.utils.html +++ b/docs/api/modules/pl.utils.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> - <title>Reference</title> + <title>pl.utils: Module Index</title> <link rel="stylesheet" href="../luadoc.css" type="text/css" /> <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/--> </head> @@ -21,7 +21,7 @@ <div id="navigation"> -<h1>LuaDoc</h1> +<h2>LuaDoc</h2> <ul> <li><a href="../index.html">Index</a></li> @@ -31,7 +31,7 @@ <!-- Module list --> -<h1>Modules</h1> +<h2>Modules</h2> <ul> <li> @@ -75,6 +75,10 @@ </li> <li> + <a href="../modules/pl.lapp.html">pl.lapp</a> + </li> + + <li> <a href="../modules/pl.lexer.html">pl.lexer</a> </li> @@ -143,7 +147,7 @@ <div id="content"> -<h1>Module <code>pl.utils</code></h1> +<h1>Module "pl.utils"</h1> <p>Generally useful routines.</p> @@ -155,92 +159,102 @@ <table class="function_list"> <tr> - <td class="name" nowrap><a href="#args">args</a> (...)</td> - <td class="summary">take an arbitrary set of arguments and make into a table.</td> + <td class="name" nowrap><a href="#utils.assert_arg">utils.assert_arg</a> (n, val, tp, verify, msg, lev)</td> + <td class="summary">assert that the given argument is in fact of the correct type.</td> + </tr> + + <tr> + <td class="name" nowrap><a href="#utils.assert_string">utils.assert_string</a> (n, val)</td> + <td class="summary">assert the common case that the argument is a string.</td> </tr> <tr> - <td class="name" nowrap><a href="#bind1">bind1</a> (fn, p)</td> + <td class="name" nowrap><a href="#utils.bind1">utils.bind1</a> (fn, p)</td> <td class="summary">bind the first argument of the function to a value.</td> </tr> <tr> - <td class="name" nowrap><a href="#choose">choose</a> (cond, value1, value2)</td> + <td class="name" nowrap><a href="#utils.choose">utils.choose</a> (cond, value1, value2)</td> <td class="summary">return either of two values, depending on a condition.</td> </tr> <tr> - <td class="name" nowrap><a href="#escape">escape</a> (s)</td> + <td class="name" nowrap><a href="#utils.escape">utils.escape</a> (s)</td> <td class="summary">escape any 'magic' characters in a string </td> </tr> <tr> - <td class="name" nowrap><a href="#fprintf">fprintf</a> (f, fmt, ...)</td> + <td class="name" nowrap><a href="#utils.fprintf">utils.fprintf</a> (f, fmt, ...)</td> <td class="summary">write an arbitrary number of arguments to a file using a format.</td> </tr> <tr> - <td class="name" nowrap><a href="#function_arg">function_arg</a> (f)</td> + <td class="name" nowrap><a href="#utils.function_arg">utils.function_arg</a> (idx, f, msg)</td> <td class="summary">process a function argument.</td> </tr> <tr> - <td class="name" nowrap><a href="#import">import</a> (t, T)</td> + <td class="name" nowrap><a href="#utils.import">utils.import</a> (t, T)</td> <td class="summary">take a table and 'inject' it into the local namespace.</td> </tr> <tr> - <td class="name" nowrap><a href="#is_callable">is_callable</a> (obj)</td> + <td class="name" nowrap><a href="#utils.is_callable">utils.is_callable</a> (obj)</td> <td class="summary">is the object either a function or a callable object?.</td> </tr> <tr> - <td class="name" nowrap><a href="#is_type">is_type</a> (obj, tp)</td> + <td class="name" nowrap><a href="#utils.is_type">utils.is_type</a> (obj, tp)</td> <td class="summary">is the object of the specified type?.</td> </tr> <tr> - <td class="name" nowrap><a href="#memoize">memoize</a> (func)</td> + <td class="name" nowrap><a href="#utils.memoize">utils.memoize</a> (func)</td> <td class="summary">'memoize' a function (cache returned value for next call).</td> </tr> <tr> - <td class="name" nowrap><a href="#printf">printf</a> (fmt, ...)</td> + <td class="name" nowrap><a href="#utils.on_error">utils.on_error</a> (mode)</td> + <td class="summary">control the error strategy used by Penlight.</td> + </tr> + + <tr> + <td class="name" nowrap><a href="#utils.printf">utils.printf</a> (fmt, ...)</td> <td class="summary">print an arbitrary number of arguments using a format.</td> </tr> <tr> - <td class="name" nowrap><a href="#quit">quit</a> (code, msg, ...)</td> + <td class="name" nowrap><a href="#utils.quit">utils.quit</a> (code, msg, ...)</td> <td class="summary">end this program gracefully.</td> </tr> <tr> - <td class="name" nowrap><a href="#readfile">readfile</a> (filename, is_bin)</td> - <td class="summary">return the contents of a file as a string </td> + <td class="name" nowrap><a href="#utils.raise">utils.raise</a> (err)</td> + <td class="summary">used by Penlight functions to return errors.</td> </tr> <tr> - <td class="name" nowrap><a href="#readlines">readlines</a> (filename)</td> - <td class="summary">return the contents of a file as a list of lines </td> + <td class="name" nowrap><a href="#utils.readfile">utils.readfile</a> (filename, is_bin)</td> + <td class="summary">return the contents of a file as a string </td> </tr> <tr> - <td class="name" nowrap><a href="#split">split</a> (s, re)</td> - <td class="summary">split a string into a list of strings separated by a delimiter.</td> + <td class="name" nowrap><a href="#utils.readlines">utils.readlines</a> (filename)</td> + <td class="summary">return the contents of a file as a list of lines </td> </tr> <tr> - <td class="name" nowrap><a href="#splitl">splitl</a> (s)</td> - <td class="summary">split a string into a list of strings separated by either spaces or commas.</td> + <td class="name" nowrap><a href="#utils.split">utils.split</a> (s, re)</td> + <td class="summary">split a string into a list of strings separated by a delimiter.</td> </tr> <tr> - <td class="name" nowrap><a href="#splitv">splitv</a> (s, re)</td> + <td class="name" nowrap><a href="#utils.splitv">utils.splitv</a> (s, re)</td> <td class="summary">split a string into a number of values.</td> </tr> <tr> - <td class="name" nowrap><a href="#writefile">writefile</a> (filename, str)</td> + <td class="name" nowrap><a href="#utils.writefile">utils.writefile</a> (filename, str)</td> <td class="summary">write a string to a file </td> </tr> @@ -261,16 +275,36 @@ -<dt><a name="args"></a><strong>args</strong> (...)</dt> +<dt><a name="utils.assert_arg"></a><strong>utils.assert_arg</strong> (n, val, tp, verify, msg, lev)</dt> <dd> -take an arbitrary set of arguments and make into a table. This returns the table and the size; works fine for nil arguments +assert that the given argument is in fact of the correct type. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - ...: arguments + n: argument index + </li> + + <li> + val: the value + </li> + + <li> + tp: the type + </li> + + <li> + verify: an optional verfication function + </li> + + <li> + msg: an optional custom message + </li> + + <li> + lev: optional stack position for trace, default 2 </li> </ul> @@ -279,18 +313,49 @@ take an arbitrary set of arguments and make into a table. This returns the table <h3>Usage:</h3> -local t,n = utils.args(...) +<ul> + + <li>assert_arg(1,t,'table') + + <li>assert_arg(n,val,'string',path.isdir,'not a directory') + +</ul> + + + + + + + +</dd> + -<h3>Return values:</h3> -<ol> +<dt><a name="utils.assert_string"></a><strong>utils.assert_string</strong> (n, val)</dt> +<dd> +assert the common case that the argument is a string. + + +<h3>Parameters:</h3> +<ul> - <li>table + <li> + n: argument index + </li> - <li>table size + <li> + val: a value that must be a string + </li> -</ol> +</ul> + + + + + + + @@ -299,12 +364,12 @@ local t,n = utils.args(...) -<dt><a name="bind1"></a><strong>bind1</strong> (fn, p)</dt> +<dt><a name="utils.bind1"></a><strong>utils.bind1</strong> (fn, p)</dt> <dd> bind the first argument of the function to a value. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -322,6 +387,8 @@ bind the first argument of the function to a value. + + <h3>Return value:</h3> a function such that f(x) is fn(p,x) @@ -330,7 +397,7 @@ a function such that f(x) is fn(p,x) <h3>See also:</h3> <ul> - <li><a href="../modules/pl.func.html#curry"> + <li><a href=""> pl.func.curry </a> @@ -341,12 +408,12 @@ a function such that f(x) is fn(p,x) -<dt><a name="choose"></a><strong>choose</strong> (cond, value1, value2)</dt> +<dt><a name="utils.choose"></a><strong>utils.choose</strong> (cond, value1, value2)</dt> <dd> return either of two values, depending on a condition. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -370,17 +437,19 @@ return either of two values, depending on a condition. + + </dd> -<dt><a name="escape"></a><strong>escape</strong> (s)</dt> +<dt><a name="utils.escape"></a><strong>utils.escape</strong> (s)</dt> <dd> escape any 'magic' characters in a string -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -396,17 +465,19 @@ escape any 'magic' characters in a string + + </dd> -<dt><a name="fprintf"></a><strong>fprintf</strong> (f, fmt, ...)</dt> +<dt><a name="utils.fprintf"></a><strong>utils.fprintf</strong> (f, fmt, ...)</dt> <dd> write an arbitrary number of arguments to a file using a format. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -430,23 +501,36 @@ write an arbitrary number of arguments to a file using a format. + + </dd> -<dt><a name="function_arg"></a><strong>function_arg</strong> (f)</dt> +<dt><a name="utils.function_arg"></a><strong>utils.function_arg</strong> (idx, f, msg)</dt> <dd> -process a function argument. <br> This is used throughout Penlight and defines what is meant by a function: <br> Something that is_callable, or an operator string as defined by pl.operator, <br> such as '>' or '#'. +process a function argument. +This is used throughout Penlight and defines what is meant by a function: +Something that is callable, or an operator string as defined by <code>pl.operator</code>, +such as '>' or '#'. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> + idx: argument index + </li> + + <li> f: a function, operator string, or callable object </li> + <li> + msg: optional error message + </li> + </ul> @@ -454,22 +538,33 @@ process a function argument. <br> This is used throughout Penlight and defines w + + <h3>Return value:</h3> a callable +<h3>See also:</h3> +<ul> + + <li><a href=""> + utils.is_callable + </a> + +</ul> + </dd> -<dt><a name="import"></a><strong>import</strong> (t, T)</dt> +<dt><a name="utils.import"></a><strong>utils.import</strong> (t, T)</dt> <dd> take a table and 'inject' it into the local namespace. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -489,17 +584,19 @@ take a table and 'inject' it into the local namespace. + + </dd> -<dt><a name="is_callable"></a><strong>is_callable</strong> (obj)</dt> +<dt><a name="utils.is_callable"></a><strong>utils.is_callable</strong> (obj)</dt> <dd> is the object either a function or a callable object?. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -515,17 +612,20 @@ is the object either a function or a callable object?. + + </dd> -<dt><a name="is_type"></a><strong>is_type</strong> (obj, tp)</dt> +<dt><a name="utils.is_type"></a><strong>utils.is_type</strong> (obj, tp)</dt> <dd> -is the object of the specified type?. If the type is a string, then use type, otherwise compare with metatable +is the object of the specified type?. +If the type is a string, then use type, otherwise compare with metatable -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -545,17 +645,22 @@ is the object of the specified type?. If the type is a string, then use type, ot + + </dd> -<dt><a name="memoize"></a><strong>memoize</strong> (func)</dt> +<dt><a name="utils.memoize"></a><strong>utils.memoize</strong> (func)</dt> <dd> -'memoize' a function (cache returned value for next call). This is useful if you have a function which is relatively expensive, but you don't know in advance what values will be required, so building a table upfront is wasteful/impossible. +'memoize' a function (cache returned value for next call). +This is useful if you have a function which is relatively expensive, +but you don't know in advance what values will be required, so +building a table upfront is wasteful/impossible. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -569,6 +674,8 @@ is the object of the specified type?. If the type is a string, then use type, ot + + <h3>Return value:</h3> a function with at least one argument, which is used as the key. @@ -579,12 +686,53 @@ a function with at least one argument, which is used as the key. -<dt><a name="printf"></a><strong>printf</strong> (fmt, ...)</dt> +<dt><a name="utils.on_error"></a><strong>utils.on_error</strong> (mode)</dt> +<dd> +control the error strategy used by Penlight. +Controls how <code>utils.raise</code> works; the default is for it +to return nil and the error string, but if the mode is 'error' then +it will throw an error. If mode is 'quit' it will immediately terminate +the program. + + +<h3>Parameters:</h3> +<ul> + + <li> + mode: - either 'default', 'quit' or 'error' + </li> + +</ul> + + + + + + + + + + +<h3>See also:</h3> +<ul> + + <li><a href=""> + utils.raise + </a> + +</ul> + +</dd> + + + + +<dt><a name="utils.printf"></a><strong>utils.printf</strong> (fmt, ...)</dt> <dd> print an arbitrary number of arguments using a format. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -604,17 +752,19 @@ print an arbitrary number of arguments using a format. + + </dd> -<dt><a name="quit"></a><strong>quit</strong> (code, msg, ...)</dt> +<dt><a name="utils.quit"></a><strong>utils.quit</strong> (code, msg, ...)</dt> <dd> end this program gracefully. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -638,11 +788,13 @@ end this program gracefully. + + <h3>See also:</h3> <ul> - <li><a href="../modules/pl.utils.html#fprintf"> - pl.utils.fprintf + <li><a href=""> + utils.fprintf </a> </ul> @@ -652,20 +804,17 @@ end this program gracefully. -<dt><a name="readfile"></a><strong>readfile</strong> (filename, is_bin)</dt> +<dt><a name="utils.raise"></a><strong>utils.raise</strong> (err)</dt> <dd> -return the contents of a file as a string +used by Penlight functions to return errors. Its global behaviour is controlled +by <code>utils.on_error</code> -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - filename: The file path - </li> - - <li> - is_bin: + err: the error string. </li> </ul> @@ -675,28 +824,40 @@ return the contents of a file as a string -<h3>Return value:</h3> -file contents + +<h3>See also:</h3> +<ul> + + <li><a href=""> + utils.on_error + </a> + +</ul> + </dd> -<dt><a name="readlines"></a><strong>readlines</strong> (filename)</dt> +<dt><a name="utils.readfile"></a><strong>utils.readfile</strong> (filename, is_bin)</dt> <dd> -return the contents of a file as a list of lines +return the contents of a file as a string -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> filename: The file path </li> + <li> + is_bin: + </li> + </ul> @@ -704,8 +865,10 @@ return the contents of a file as a list of lines + + <h3>Return value:</h3> -file contents as a table +file contents @@ -714,20 +877,16 @@ file contents as a table -<dt><a name="split"></a><strong>split</strong> (s, re)</dt> +<dt><a name="utils.readlines"></a><strong>utils.readlines</strong> (filename)</dt> <dd> -split a string into a list of strings separated by a delimiter. +return the contents of a file as a list of lines -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> - s: The input string - </li> - - <li> - re: A regular expression; defaults to spaces + filename: The file path </li> </ul> @@ -737,8 +896,10 @@ split a string into a list of strings separated by a delimiter. + + <h3>Return value:</h3> -a list-like table +file contents as a table @@ -747,18 +908,22 @@ a list-like table -<dt><a name="splitl"></a><strong>splitl</strong> (s)</dt> +<dt><a name="utils.split"></a><strong>utils.split</strong> (s, re)</dt> <dd> -split a string into a list of strings separated by either spaces or commas. +split a string into a list of strings separated by a delimiter. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> s: The input string </li> + <li> + re: A regular expression; defaults to spaces + </li> + </ul> @@ -766,6 +931,8 @@ split a string into a list of strings separated by either spaces or commas. + + <h3>Return value:</h3> a list-like table @@ -776,12 +943,12 @@ a list-like table -<dt><a name="splitv"></a><strong>splitv</strong> (s, re)</dt> +<dt><a name="utils.splitv"></a><strong>utils.splitv</strong> (s, re)</dt> <dd> split a string into a number of values. -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -802,6 +969,8 @@ first,next = splitv('jane:doe',':') + + <h3>Return value:</h3> n values @@ -810,7 +979,7 @@ n values <h3>See also:</h3> <ul> - <li><a href="../modules/pl.utils.html#split"> + <li><a href=""> split </a> @@ -821,12 +990,12 @@ n values -<dt><a name="writefile"></a><strong>writefile</strong> (filename, str)</dt> +<dt><a name="utils.writefile"></a><strong>utils.writefile</strong> (filename, str)</dt> <dd> write a string to a file -<h3>Parameters</h3> +<h3>Parameters:</h3> <ul> <li> @@ -846,6 +1015,8 @@ write a string to a file + + </dd> diff --git a/docs/docgen.lua b/docs/docgen.lua index eda282f..012ddba 100644 --- a/docs/docgen.lua +++ b/docs/docgen.lua @@ -1,44 +1,44 @@ --- massaging @see references in the markdown source.
--- (for a more elegant way of doing this, see seesubst.lua in the examples
--- directory.)
-local lua = arg[-1]
-local markdown_dir = arg[1]
-if lua:find ' ' then lua = '"'..lua..'"' end
-
-function markdown (file,tmp)
- local tmp_created
- if tmp then
- local f = io.open (tmp,'w')
- for line in io.lines (file) do
- line = line:gsub('@see [%a%.]+',function(s)
- s = s:gsub('@see ','')
- local mod,fun = s:match('(.-%..-)%.(.+)')
- if not mod then mod = s end
- local res = '[see '..s..'](modules/'..mod..'.html'
- if fun then return res..'#'..fun..')'
- else return res..')'
- end
- end)
- f:write(line,'\n')
- end
- f:close()
- tmp_created = true
- else
- tmp = file
- end
- local cmd = lua..' '..markdown_dir..'/markdown.lua -s doc.css -l '..tmp
- print(cmd)
- os.execute (cmd)
- if tmp_created then os.remove (tmp) end
-end
-
-markdown ('penlight.md','index.txt')
-markdown ('function_index.txt')
-
-
-
-
-
-
-
-
+-- massaging @see references in the markdown source. +-- (for a more elegant way of doing this, see seesubst.lua in the examples +-- directory.) +local lua = arg[-1] +local markdown_dir = arg[1] +if lua:find ' ' then lua = '"'..lua..'"' end + +function markdown (file,tmp) + local tmp_created + if tmp then + local f = io.open (tmp,'w') + for line in io.lines (file) do + line = line:gsub('@see [%a%.]+',function(s) + s = s:gsub('@see ','') + local m,fun = s:match('(.-)%.(.+)') + if not m then m = s end + local res = '[see '..s..'](modules/pl.'..m..'.html' + if fun then return res..'#'..s..')' + else return res..')' + end + end) + f:write(line,'\n') + end + f:close() + tmp_created = true + else + tmp = file + end + local cmd = lua..' '..markdown_dir..'/markdown.lua -s doc.css -l '..tmp + print(cmd) + os.execute (cmd) + if tmp_created then os.remove (tmp) end +end + +markdown ('penlight.md','index.txt') +markdown ('function_index.txt') + + + + + + + + diff --git a/docs/index.html b/docs/index.html index 6bbf6e6..f3fe084 100644 --- a/docs/index.html +++ b/docs/index.html @@ -26,18 +26,18 @@ a:link:hover { text-decoration:underline; } <li><a href="#T4">To Inject or not to Inject?</a></li> <li><a href="#T5">What are function arguments in Penlight?</a></li> <li><a href="#T6">Pros and Cons of Loopless Programming</a></li> - <li><a href="#T.">Utilities. Generally useful functions.</a></li> + <li><a href="#T7">Utilities. Generally useful functions.</a></li> <li><a href="#T8">Application Support</a></li> - <li><a href="#T.">Classes. Simplifying Object-Oriented Programming in Lua</a></li> + <li><a href="#T9">Classes. Simplifying Object-Oriented Programming in Lua</a></li> </ul></li> <li><a href="#T10">Tables and Arrays</a> <ul> <li><a href="#T11">Python-style Lists</a></li> <li><a href="#T12">Map and Set classes</a></li> - <li><a href="#T.">Tablex. Useful Operations on Tables</a></li> + <li><a href="#T13">Tablex. Useful Operations on Tables</a></li> <li><a href="#T14">Operations on two-dimensional tables</a></li> </ul></li> - <li><a href="#T.">Strings. Higher-level operations on strings.</a> + <li><a href="#T15">Strings. Higher-level operations on strings.</a> <ul> <li><a href="#T16">Extra String Methods</a></li> <li><a href="#T17">String Templates</a></li> @@ -73,11 +73,11 @@ a:link:hover { text-decoration:underline; } <li><a href="#T38">'varargs' Parameter Arrays</a></li> <li><a href="#T39">Defining a Parameter Callback</a></li> </ul></li> - </ul></li> - <li><a href="#T40">Technical Choices</a> - <ul> - <li><a href="#T41">Modularity and Granularity</a></li> - <li><a href="#T42">Defining what is Callable</a></li> + <li><a href="#T40">Technical Choices</a> + <ul> + <li><a href="#T41">Modularity and Granularity</a></li> + <li><a href="#T42">Defining what is Callable</a></li> + </ul></li> </ul></li> </ul> @@ -86,7 +86,7 @@ a:link:hover { text-decoration:underline; } <p>The module documentation is available <a href="api/index.html">here</a>; and there is an alphabetical <a href="function_index.html">function index</a>.</p> -<p>The latest vesion is available at <a href="http://github.com/stevedonovan/Penlight/downloads">GitHub</a>.</p> +<p>The latest vesion is available at <a href="http://github.com/stevedonovan/Penlight">Github</a>.</p> <h2 id="T2">Introduction</h2> @@ -175,12 +175,10 @@ nil <h3 id="T5">What are function arguments in Penlight?</h3> -<p>Many functions in Penlight themselves take function arguments, like <code>map</code> which applies a function to a list, element by element. You can use existing functions, like <code>math.max</code>, anonymous functions (like <code>function(x,y) return x > y end</code>), operations by name (e.g '*' or '..') or <em>string lambdas</em> like '|x,y| x > y'. The module <code>pl.operator</code> exports all the standard Lua operations, like the Python module of the same name. Penlight allows these to be refered to by name, so <code>operator.gt</code> can be more concisely expressed as '>'.</p> +<p>Many functions in Penlight themselves take function arguments, like <code>map</code> which applies a function to a list, element by element. You can use existing functions, like <code>math.max</code>, anonymous functions (like <code>function(x,y) return x > y end</code>), or operations by name (e.g '*' or '..'). The module <code>pl.operator</code> exports all the standard Lua operations, like the Python module of the same name. Penlight allows these to be refered to by name, so <code>operator.gt</code> can be more concisely expressed as '>'.</p> <p>Note that the <code>map</code> functions pass any extra arguments to the function, so we can have <code>ls:filter('>',0)</code>, which is effectively <code>ls:filter(function(x) return x > 0 end)</code>.</p> -<p>String lambdas provide a convenient way to express simple anonymous functions, without the 'keyword noise' of the usual syntax. This is not to everyone's taste, which is why it is not part of the language itself, but these forms can make code that is both more compact and readable.</p> - <p>Finally, <code>pl.func</code> supports <em>placeholder expressions</em> in the Boost style, so that an anonymous function to multiply the two arguments can be expressed as <code>_1*_2</code>.</p> <p>To use them directly, note that <em>all</em> function arguments in Penlight go through <code>utils.function_arg</code>:</p> @@ -212,7 +210,7 @@ end <p>Writing loops is 'error-prone and tedious', as Stroustrup says. But any half-decent editor can be taught to do much of that typing for you. The question should actually be: is it tedious to <em>read</em> loops? As with natural language, programmers tend to read chunks at a time. A for-loop causes no suprise, and probably little brain activity. One argument for loopless programming is the loops that you <em>do</em> write stand out more, and signal 'something different happening here'. It should not be an all-or-nothing thing, since most programs require a mixture of idioms that suit the problem. Some languages (like APL) do nearly everything with map and reduce operations on arrays, and so solutions can sometimes seem forced. Wisdom is knowing when a particular idiom makes a particular problem easy to <em>solve</em> and the solution easy to <em>explain</em> afterwards.</p> -<h3 id="T.">Utilities. Generally useful functions.</h3> +<h3 id="T7">Utilities. Generally useful functions.</h3> <p>The function <code>printf</code> discussed earlier is included in <code>pl.utils</code> because it makes properly formatted output easier. (There is an equivalent <code>fprintf</code> which also takes a file object parameter, just like the C function.)</p> @@ -226,10 +224,10 @@ end end </code></pre> -<p>But this will bite you someday when <code>nil</code> is one of the arguments, since this will put a 'hole' in your table. In particular, <code>#ls</code> will only give you the size upto the <code>nil</code> value. Hence the need for <code>utils.args</code>:</p> +<p>But this will bite you someday when <code>nil</code> is one of the arguments, since this will put a 'hole' in your table. In particular, <code>#ls</code> will only give you the size upto the <code>nil</code> value. Hence the need for <code>table.pack</code> - this is a new Lua 5.2 function which Penlight defines also for Lua 5.1.</p> <pre><code>function t(...) - local args,n = utils.args(...) + local args,n = table.pack(...) for i = 1,n do ... end @@ -249,6 +247,7 @@ s = sum(1e8) --takes time! s = sum(1e8) --returned saved value! </code></pre> +<p><a id="app"/></p> <h3 id="T8">Application Support</h3> <p><code>app.parse_args</code> is a simple command-line argument parser. If called without any arguments, it tries to use the global <code>arg</code> array. It returns the <em>flags</em> (options begining with '-') as a table of name/value pairs, and the <em>arguments</em> as an array. It knows about long GNU-style flag names, e.g. <code>--value</code>, and groups of short flags are understood, so that <code>-ab</code> is short for <code>-a -b</code>. The flags result would then look like <code>{value=true,a=true,b=true}</code>.</p> @@ -277,12 +276,12 @@ s = sum(1e8) --returned saved value! <p>Penlight makes it convenient to save application data in Lua format. You can use <code>pretty.dump(t,file)</code> to write a Lua table in a human-readable form to a file, and <code>pretty.read(file.read(file))</code> to generate the table again.</p> -<p>(<a href="modules/pl.app.html">see pl.app</a>, <a href="modules/pl.pretty.html">see pl.pretty</a>)</p> +<p>(<a href="modules/pl.app.html">see app</a>, <a href="modules/pl.pretty.html">see pretty</a>)</p> <p><a id="class"/></p> -<h3 id="T.">Classes. Simplifying Object-Oriented Programming in Lua</h3> +<h3 id="T9">Classes. Simplifying Object-Oriented Programming in Lua</h3> <p>Lua is similar to JavaScript in that the concept of class is not directly supported by the language. In fact, Lua has a very general mechanism for extending the behaviour of tables which makes it straightforward to implement classes. A table's behaviour is controlled by its metatable. If that metatable has a <code>__index</code> function or table, this will handle looking up anything which is not found in the original table. A class is just a table with an <code>__index</code> key pointing to itself. Creating an object involves making a table and setting its metatable to the class; then when handling <code>obj.fun</code>, Lua first looks up <code>fun</code> in the table <code>obj</code>, and if not found it looks it up in the class. <code>obj:fun(a)</code> is just short for <code>obj.fun(obj,a)</code>. So with the metatable mechanism and this bit of syntactic sugar, it is straightforward to implement classic object orientation.</p> @@ -368,7 +367,7 @@ Alice: 00459AE8 <h3 id="T11">Python-style Lists</h3> -<p>One of the elegant things about Lua is that tables do the job of both lists and dicts (as called in Python) or vectors and maps, (as called in C++), and they do it efficiently. However, if we are dealing with 'tables with numerical indices' we may as well call them lists and look for operations which particularly make sense for lists. The Penlight <code>List</code> class was originally written by Nick Trout for Lua 5.0, and translated to 5.1 and extended by myself. It seemed that borrowing from Python was a good idea, and this eventually grew into Penlight. (<a href="modules/pl.list.html">see pl.list</a>)</p> +<p>One of the elegant things about Lua is that tables do the job of both lists and dicts (as called in Python) or vectors and maps, (as called in C++), and they do it efficiently. However, if we are dealing with 'tables with numerical indices' we may as well call them lists and look for operations which particularly make sense for lists. The Penlight <code>List</code> class was originally written by Nick Trout for Lua 5.0, and translated to 5.1 and extended by myself. It seemed that borrowing from Python was a good idea, and this eventually grew into Penlight. (<a href="modules/pl.list.html">see list</a>)</p> <p>Here is an example showing <code>List</code> in action; it redefines <code>__tostring</code>, so that it can print itself out more sensibly:</p> @@ -541,9 +540,9 @@ end </code></pre> -<p>(<a href="modules/pl.class.html">see pl.class</a>, <a href="modules/pl.classx.html">see pl.classx</a>)</p> +<p>(<a href="modules/pl.class.html">see class</a>, <a href="modules/pl.classx.html">see classx</a>)</p> -<h3 id="T.">Tablex. Useful Operations on Tables</h3> +<h3 id="T13">Tablex. Useful Operations on Tables</h3> <p>Some notes on terminology: Lua tables are usually <em>list-like</em> (like an array) or <em>map-like</em> (like an associative array or dict); they can of course have a list-like and a map-like part. Some of the table operations only make sense for list-like tables, and some only for map-like tables. (The usual Lua terminology is the array part and the hash part of the table, which reflects the actual implementation used.)</p> @@ -556,7 +555,7 @@ end return res </code></pre> -<p>The <code>tablex</code> module (<a href="modules/pl.tablex.html">see pl.tablex</a>) provides this as <code>copy</code>, which does a <em>shallow</em> copy of a table. There is also <code>deepcopy</code> which goes further than a simple loop in two ways; first, it also gives the copy the same metatable as the original (so it can copy objects like <code>List</code> above) and any nested tables will also be copied, to arbitrary depth. There is also <code>icopy</code> which operates on list-like tables, where you can set optionally set the start index of the source and destination as well. It ensures that any left-over elements will be deleted:</p> +<p>The <code>tablex</code> module (<a href="modules/pl.tablex.html">see tablex</a>) provides this as <code>copy</code>, which does a <em>shallow</em> copy of a table. There is also <code>deepcopy</code> which goes further than a simple loop in two ways; first, it also gives the copy the same metatable as the original (so it can copy objects like <code>List</code> above) and any nested tables will also be copied, to arbitrary depth. There is also <code>icopy</code> which operates on list-like tables, where you can set optionally set the start index of the source and destination as well. It ensures that any left-over elements will be deleted:</p> <pre><code>asserteq(icopy({1,2,3,4,5,6},{20,30}),{20,30}) -- start at 1 asserteq(icopy({1,2,3,4,5,6},{20,30},2),{1,20,30}) -- start at 2 @@ -850,9 +849,9 @@ lines = map2(string.rjust,2,1,lines,maxlens) 3 3 9 </code></pre> -<p>(<a href="modules/pl.array.html">see pl.array</a>2d)</p> +<p>(<a href="modules/pl.array.html">see array</a>2d)</p> -<h2 id="T.">Strings. Higher-level operations on strings.</h2> +<h2 id="T15">Strings. Higher-level operations on strings.</h2> <h3 id="T16">Extra String Methods</h3> @@ -881,7 +880,7 @@ three <p>Most of these can be fairly easily implemented using the Lua string library, which is more general and powerful. But they are convenient operations to have easily at hand. Note that can be injected into the <code>string</code> table if you use <code>require 'pl'</code> and then <code>stringx.import()</code>, or explicitly call <code>pl.stringx.import()</code>, but a simple alias like 'stringx = require 'pl.string'` can be used. This is the recommended practice when writing modules for consumption by other people, since it is bad manners to change the global state of the rest of the system.</p> -<p>(<a href="modules/pl.stringx.html">see pl.stringx</a>)</p> +<p>(<a href="modules/pl.stringx.html">see stringx</a>)</p> <h3 id="T17">String Templates</h3> @@ -932,7 +931,7 @@ print(t:indent_substitute {body=body,t='tbl'}) <p><code>pl.text</code> also has a number of useful functions like <code>dedent</code>, which strips all the initial indentation from a multiline string. As in Python, this is useful for preprocessing multiline strings if you like indenting them with your code. The function <code>wrap</code> is passed a long string (a <em>paragraph</em>) and returns a list of lines that fit into a desired line width. As an extension, there is also <code>indent</code> for indenting multiline strings.</p> -<p>(<a href="modules/pl.text.html">see pl.text</a>)</p> +<p>(<a href="modules/pl.text.html">see text</a>)</p> <h2 id="T18">Paths and Directories</h2> @@ -1115,7 +1114,9 @@ end <h3 id="T24">Reading Unstructured Text Data</h3> -<p>Text data is sometimes unstructured, for example a file containing words. The 'pl.input` module has a number of functions which makes processing such files easier. For example, a script to count the number of words in standard input (<a href="modules/pl.input.html#words">see pl.input.words</a>):</p> +<p><a id="input"/></p> + +<p>Text data is sometimes unstructured, for example a file containing words. The 'pl.input` module has a number of functions which makes processing such files easier. For example, a script to count the number of words in standard input (<a href="modules/pl.input.html#input.words">see input.words</a>):</p> <pre><code>-- countwords.lua require 'pl' @@ -1126,7 +1127,7 @@ end print('count',k) </code></pre> -<p>Or this script to calculate the average of a set of numbers (<a href="modules/pl.input.html#numbers">see pl.input.numbers</a>):</p> +<p>Or this script to calculate the average of a set of numbers (<a href="modules/pl.input.html#input.numbers">see input.numbers</a>):</p> <pre><code>-- average.lua require 'pl' @@ -1162,8 +1163,6 @@ for line in io.lines() do end </code></pre> -<p><a id="data"/></p> - <h3 id="T25">Reading Columnar Data</h3> <p>It is very common to find data in columnar form, either space or comma-separated, perhaps with an initial set of column headers. Here is a typical example:</p> @@ -1195,7 +1194,7 @@ end <p>The second parameter is a delimiter, by default spaces. ' ' is understood to mean 'any number of spaces', i.e. '%s+'. Any Lua string pattern can be used.</p> -<p>The third parameter is a <em>data source</em>, by default standard input (<a href="modules/pl.input.html#create">see pl.input.create</a>_getter) It assumes that the data source has a <code>read</code> method which brings in the next line, i.e. it is a 'file-like' object. As a special case, a string will be split into its lines:</p> +<p>The third parameter is a <em>data source</em>, by default standard input (<a href="modules/pl.input.html#input.create">see input.create</a>_getter) It assumes that the data source has a <code>read</code> method which brings in the next line, i.e. it is a 'file-like' object. As a special case, a string will be split into its lines:</p> <pre><code>> for x,y in input.fields(2,' ','10 20\n30 40\n') do print(x,y) end 10 20 @@ -1211,7 +1210,9 @@ line 2: cannot convert '40x' to number <p>This behaviour of <code>input.fields</code> is appropriate for a script which you want to fail immediately with an appropriate <em>user</em> error message if conversion fails. The fourth optional parameter is an options table: <code>{no_fail=true}</code> means that conversion is attempted but if it fails it just returns the string, rather as AWK would operate. You are then responsible for checking the type of the returned field. <code>{no_convert=true}</code> switches off conversion altogether and all fields are returned as strings.</p> -<p>Sometimes it is useful to bring a whole dataset into memory, for operations such as extracting columns. Penlight provides a flexible reader specifically for reading this kind of data (<a href="modules/pl.data.html#read">see pl.data.read</a>). Given a file looking like this:</p> +<p><a id="data"/></p> + +<p>Sometimes it is useful to bring a whole dataset into memory, for operations such as extracting columns. Penlight provides a flexible reader specifically for reading this kind of data (<a href="modules/pl.data.html#data.read">see data.read</a>). Given a file looking like this:</p> <pre><code>x,y 10,20 @@ -1305,7 +1306,7 @@ end </code></pre> -<p>I've always been an admirer of the AWK programming language; with <code>filter</code> (<a href="modules/pl.data.html#filter">see pl.data.filter</a>) you can get Lua programs which are just as compact:</p> +<p>I've always been an admirer of the AWK programming language; with <code>filter</code> (<a href="modules/pl.data.html#data.filter">see data.filter</a>) you can get Lua programs which are just as compact:</p> <pre><code>-- printxy.lua require 'pl' @@ -1359,7 +1360,7 @@ write.timeout=5 ports = 1002,1003,1004 </code></pre> -<p>This can be easily brought in using <code>config.read</code> and the result shown using <code>pl.pretty.write</code> (<a href="modules/pl.pretty.html#write">see pl.pretty.write</a>)</p> +<p>This can be easily brought in using <code>config.read</code> and the result shown using <code>pl.pretty.write</code> (<a href="modules/pl.pretty.html#pretty.write">see pretty.write</a>)</p> <pre><code>-- readconfig.lua local config = require 'pl.config' @@ -1684,7 +1685,7 @@ print(pretty.write(seq.count_map(globals))) 3 </code></pre> -<p><code>seq.printall</code> is useful for printing out single-valued sequences, and provides some finer control over formating, such as a delimiter, the number of fields per line, and a format string to use (<a href="modules/string.format.html">see string.format</a>)</p> +<p><code>seq.printall</code> is useful for printing out single-valued sequences, and provides some finer control over formating, such as a delimiter, the number of fields per line, and a format string to use (<a href="modules/pl.string.html#string.format">see string.format</a>)</p> <pre><code>> seq.printall(seq.random(10)) 0.0012512588885159 0.56358531449324 0.19330423902097 .... @@ -1799,7 +1800,7 @@ ONE TWO <pre><code>seq.lines():take(10):upper():enum():map('..'):printall '\n' </code></pre> -<p>Note the method <code>upper</code>, which is not a <code>seq</code> function. if an unknown method is called, sequence wrappers apply that method to all the values in the sequence (this is implicit use of <code>mapmethod</code> - <a href="modules/pl.seq.html#mapmethod.">see pl.seq.mapmethod.</a>)</p> +<p>Note the method <code>upper</code>, which is not a <code>seq</code> function. if an unknown method is called, sequence wrappers apply that method to all the values in the sequence (this is implicit use of <code>mapmethod</code> - <a href="modules/pl.seq.html#seq.mapmethod">see seq.mapmethod</a>)</p> <p>It is straightforward to create custom sequences that can be used in this way. On Unix, <code>/dev/random</code> gives you an <em>endless</em> sequence of random bytes, so we use <code>take</code> to limit the sequence, and then <code>map</code> to scale the result into the desired range. The key step is to use <code>seq</code> to wrap the iterator function:</p> @@ -1821,11 +1822,6 @@ dev_random():take(10):map('%',100):map('/',100):printall ',' </code></pre> -<p>You may prefer this form, which uses the new 'string lambda' notation:</p> - -<pre><code>dev_random():take(10):map '|n| (n % 100)/100':printall ',' -</code></pre> - <p>Another Linux one-liner depends on the <code>/proc</code> filesystem and makes a list of all the currently running processes:</p> <pre><code>pids = seq(lfs.dir '/proc'):filter(stringx.isdigit):map(tonumber):copy() @@ -2102,7 +2098,6 @@ for i = 1,n do end </code></pre> -<p>Another option now supported by Penlight is the use of <em>string lambdas</em>. These use the 'short-form' for anonymous functions. So any Penlight function can accept strings like '|x,y| x+y', which is equivalent to <code>function(x,y) return x+y end</code>. Please note that these functions are effectively compiled in the global context and they cannot have references to locals. They do not suffer from the quoting problem, so that we can say '|f| f:read()', and they can be efficiently memoized.</p> <h2 id="T34">Additional Libraries</h2> @@ -2246,7 +2241,7 @@ true {first='jan',rest='and a string',last='smit'} </code></pre> -<p>(<a href="modules/pl.sip.html">see pl.sip</a>)</p> +<p>(<a href="modules/pl.sip.html">see sip</a>)</p> <p><a id="lapp"/></p> @@ -2537,4 +2532,4 @@ List._class = List -</body></html> +</body></html>
\ No newline at end of file diff --git a/docs/luadoc.css b/docs/luadoc.css new file mode 100644 index 0000000..d22fb10 --- /dev/null +++ b/docs/luadoc.css @@ -0,0 +1,287 @@ +/* BEGIN RESET + +Copyright (c) 2010, Yahoo! Inc. All rights reserved. +Code licensed under the BSD License: +http://developer.yahoo.com/yui/license.html +version: 2.8.2r1 +*/ +html { + color: #000; + background: #FFF; +} +body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td { + margin: 0; + padding: 0; +} +table { + border-collapse: collapse; + border-spacing: 0; +} +fieldset,img { + border: 0; +} +address,caption,cite,code,dfn,em,strong,th,var,optgroup { + font-style: inherit; + font-weight: inherit; +} +del,ins { + text-decoration: none; +} +li { + list-style: bullet; + margin-left: 20px; +} +caption,th { + text-align: left; +} +h1,h2,h3,h4,h5,h6 { + font-size: 100%; + font-weight: bold; +} +q:before,q:after { + content: ''; +} +abbr,acronym { + border: 0; + font-variant: normal; +} +sup { + vertical-align: baseline; +} +sub { + vertical-align: baseline; +} +legend { + color: #000; +} +input,button,textarea,select,optgroup,option { + font-family: inherit; + font-size: inherit; + font-style: inherit; + font-weight: inherit; +} +input,button,textarea,select {*font-size:100%; +} +/* END RESET */ + +body { + margin-left: 1em; + margin-right: 1em; + font-family: arial, helvetica, geneva, sans-serif; + background-color: #ffffff; margin: 0px; +} + +code, tt { font-family: monospace; } + +body, p, td, th { font-size: .95em; line-height: 1.2em;} + +p, ul { margin: 10px 0 0 10px;} + +strong { font-weight: bold;} + +h1 { + font-size: 1.5em; + margin: 0 0 20px 0; +} +h2, h3, h4 { margin: 15px 0 10px 0; } +h2 { font-size: 1.25em; } +h3 { font-size: 1.15em; } +h4 { font-size: 1.06em; } + +a:link { font-weight: bold; color: #004080; text-decoration: none; } +a:visited { font-weight: bold; color: #006699; text-decoration: none; } +a:link:hover { text-decoration: underline; } + +hr { + color:#cccccc; + background: #00007f; + height: 1px; +} + +blockquote { margin-left: 3em; } + +ul { list-style-type: disc; } + +p.name { + font-family: "Andale Mono", monospace; + padding-top: 1em; +} + +pre.example { + background-color: rgb(245, 245, 245); + border: 1px solid silver; + padding: 10px; + margin: 10px 0 10px 0; + font-family: "Andale Mono", monospace; + font-size: .85em; +} + +table.index { border: 1px #00007f; } +table.index td { text-align: left; vertical-align: top; } + +#container { + margin-left: 1em; + margin-right: 1em; + background-color: #f0f0f0; +} + +#product { + text-align: center; + border-bottom: 1px solid #cccccc; + background-color: #ffffff; +} + +#product big { + font-size: 2em; +} + +#main { + background-color: #f0f0f0; + border-left: 2px solid #cccccc; +} + +#navigation { + float: left; + width: 18em; + vertical-align: top; + background-color: #f0f0f0; + overflow: visible; +} + +#navigation h2 { + background-color:#e7e7e7; + font-size:1.1em; + color:#000000; + text-align: left; + padding:0.2em; + border-top:1px solid #dddddd; + border-bottom:1px solid #dddddd; +} + +#navigation ul +{ + font-size:1em; + list-style-type: none; + margin: 1px 1px 10px 1px; +} + +#navigation li { + text-indent: -1em; + display: block; + margin: 3px 0px 0px 22px; +} + +#navigation li li a { + margin: 0px 3px 0px -1em; +} + +#content { + margin-left: 18em; + padding: 1em; + border-left: 2px solid #cccccc; + border-right: 2px solid #cccccc; + background-color: #ffffff; +} + +#about { + clear: both; + padding: 5px; + border-top: 2px solid #cccccc; + background-color: #ffffff; +} + +@media print { + body { + font: 12pt "Times New Roman", "TimeNR", Times, serif; + } + a { font-weight: bold; color: #004080; text-decoration: underline; } + + #main { + background-color: #ffffff; + border-left: 0px; + } + + #container { + margin-left: 2%; + margin-right: 2%; + background-color: #ffffff; + } + + #content { + padding: 1em; + background-color: #ffffff; + } + + #navigation { + display: none; + } + pre.example { + font-family: "Andale Mono", monospace; + font-size: 10pt; + page-break-inside: avoid; + } +} + +table.module_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} +table.module_list td.name { background-color: #f0f0f0; } +table.module_list td.summary { width: 100%; } + +table.file_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.file_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} + +table.file_list td.name { background-color: #f0f0f0; } + +table.file_list td.summary { width: 100%; } + +table.function_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.function_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} + +table.function_list td.name { background-color: #f0f0f0; } + +table.function_list td.summary { width: 100%; } + +table.table_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.table_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} + +table.table_list td.name { background-color: #f0f0f0; } + +table.table_list td.summary { width: 100%; } + +dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;} +dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;} +dl.table h3, dl.function h3 {font-size: .95em;}
\ No newline at end of file diff --git a/docs/markdown.lua b/docs/markdown.lua new file mode 100644 index 0000000..f23954f --- /dev/null +++ b/docs/markdown.lua @@ -0,0 +1,1388 @@ +#!/usr/bin/env lua
+
+--[[
+# markdown.lua -- version 0.32
+
+<http://www.frykholm.se/files/markdown.lua>
+
+**Author:** Niklas Frykholm, <niklas@frykholm.se>
+**Date:** 31 May 2008
+
+This is an implementation of the popular text markup language Markdown in pure Lua.
+Markdown can convert documents written in a simple and easy to read text format
+to well-formatted HTML. For a more thourough description of Markdown and the Markdown
+syntax, see <http://daringfireball.net/projects/markdown>.
+
+The original Markdown source is written in Perl and makes heavy use of advanced
+regular expression techniques (such as negative look-ahead, etc) which are not available
+in Lua's simple regex engine. Therefore this Lua port has been rewritten from the ground
+up. It is probably not completely bug free. If you notice any bugs, please report them to
+me. A unit test that exposes the error is helpful.
+
+## Usage
+
+ require "markdown"
+ markdown(source)
+
+``markdown.lua`` exposes a single global function named ``markdown(s)`` which applies the
+Markdown transformation to the specified string.
+
+``markdown.lua`` can also be used directly from the command line:
+
+ lua markdown.lua test.md
+
+Creates a file ``test.html`` with the converted content of ``test.md``. Run:
+
+ lua markdown.lua -h
+
+For a description of the command-line options.
+
+``markdown.lua`` uses the same license as Lua, the MIT license.
+
+## License
+
+Copyright © 2008 Niklas Frykholm.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
+to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies
+or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+## Version history
+
+- **0.32** -- 31 May 2008
+ - Fix for links containing brackets
+- **0.31** -- 1 Mar 2008
+ - Fix for link definitions followed by spaces
+- **0.30** -- 25 Feb 2008
+ - Consistent behavior with Markdown when the same link reference is reused
+- **0.29** -- 24 Feb 2008
+ - Fix for <pre> blocks with spaces in them
+- **0.28** -- 18 Feb 2008
+ - Fix for link encoding
+- **0.27** -- 14 Feb 2008
+ - Fix for link database links with ()
+- **0.26** -- 06 Feb 2008
+ - Fix for nested italic and bold markers
+- **0.25** -- 24 Jan 2008
+ - Fix for encoding of naked <
+- **0.24** -- 21 Jan 2008
+ - Fix for link behavior.
+- **0.23** -- 10 Jan 2008
+ - Fix for a regression bug in longer expressions in italic or bold.
+- **0.22** -- 27 Dec 2007
+ - Fix for crash when processing blocks with a percent sign in them.
+- **0.21** -- 27 Dec 2007
+ - Fix for combined strong and emphasis tags
+- **0.20** -- 13 Oct 2007
+ - Fix for < as well in image titles, now matches Dingus behavior
+- **0.19** -- 28 Sep 2007
+ - Fix for quotation marks " and ampersands & in link and image titles.
+- **0.18** -- 28 Jul 2007
+ - Does not crash on unmatched tags (behaves like standard markdown)
+- **0.17** -- 12 Apr 2007
+ - Fix for links with %20 in them.
+- **0.16** -- 12 Apr 2007
+ - Do not require arg global to exist.
+- **0.15** -- 28 Aug 2006
+ - Better handling of links with underscores in them.
+- **0.14** -- 22 Aug 2006
+ - Bug for *`foo()`*
+- **0.13** -- 12 Aug 2006
+ - Added -l option for including stylesheet inline in document.
+ - Fixed bug in -s flag.
+ - Fixed emphasis bug.
+- **0.12** -- 15 May 2006
+ - Fixed several bugs to comply with MarkdownTest 1.0 <http://six.pairlist.net/pipermail/markdown-discuss/2004-December/000909.html>
+- **0.11** -- 12 May 2006
+ - Fixed bug for escaping `*` and `_` inside code spans.
+ - Added license terms.
+ - Changed join() to table.concat().
+- **0.10** -- 3 May 2006
+ - Initial public release.
+
+// Niklas
+]]
+
+
+-- Set up a table for holding local functions to avoid polluting the global namespace
+local M = {}
+local MT = {__index = _G}
+setmetatable(M, MT)
+setfenv(1, M)
+
+----------------------------------------------------------------------
+-- Utility functions
+----------------------------------------------------------------------
+
+-- Locks table t from changes, writes an error if someone attempts to change the table.
+-- This is useful for detecting variables that have "accidently" been made global. Something
+-- I tend to do all too much.
+function lock(t)
+ function lock_new_index(t, k, v)
+ error("module has been locked -- " .. k .. " must be declared local", 2)
+ end
+
+ local mt = {__newindex = lock_new_index}
+ if getmetatable(t) then mt.__index = getmetatable(t).__index end
+ setmetatable(t, mt)
+end
+
+-- Returns the result of mapping the values in table t through the function f
+function map(t, f)
+ local out = {}
+ for k,v in pairs(t) do out[k] = f(v,k) end
+ return out
+end
+
+-- The identity function, useful as a placeholder.
+function identity(text) return text end
+
+-- Functional style if statement. (NOTE: no short circuit evaluation)
+function iff(t, a, b) if t then return a else return b end end
+
+-- Splits the text into an array of separate lines.
+function split(text, sep)
+ sep = sep or "\n"
+ local lines = {}
+ local pos = 1
+ while true do
+ local b,e = text:find(sep, pos)
+ if not b then table.insert(lines, text:sub(pos)) break end
+ table.insert(lines, text:sub(pos, b-1))
+ pos = e + 1
+ end
+ return lines
+end
+
+-- Converts tabs to spaces
+function detab(text)
+ local tab_width = 4
+ local function rep(match)
+ local spaces = -match:len()
+ while spaces<1 do spaces = spaces + tab_width end
+ return match .. string.rep(" ", spaces)
+ end
+ text = text:gsub("([^\n]-)\t", rep)
+ return text
+end
+
+-- Applies string.find for every pattern in the list and returns the first match
+function find_first(s, patterns, index)
+ local res = {}
+ for _,p in ipairs(patterns) do
+ local match = {s:find(p, index)}
+ if #match>0 and (#res==0 or match[1] < res[1]) then res = match end
+ end
+ return unpack(res)
+end
+
+-- If a replacement array is specified, the range [start, stop] in the array is replaced
+-- with the replacement array and the resulting array is returned. Without a replacement
+-- array the section of the array between start and stop is returned.
+function splice(array, start, stop, replacement)
+ if replacement then
+ local n = stop - start + 1
+ while n > 0 do
+ table.remove(array, start)
+ n = n - 1
+ end
+ for i,v in ipairs(replacement) do
+ table.insert(array, start, v)
+ end
+ return array
+ else
+ local res = {}
+ for i = start,stop do
+ table.insert(res, array[i])
+ end
+ return res
+ end
+end
+
+-- Outdents the text one step.
+function outdent(text)
+ text = "\n" .. text
+ text = text:gsub("\n ? ? ?", "\n")
+ text = text:sub(2)
+ return text
+end
+
+-- Indents the text one step.
+function indent(text)
+ text = text:gsub("\n", "\n ")
+ return text
+end
+
+-- Does a simple tokenization of html data. Returns the data as a list of tokens.
+-- Each token is a table with a type field (which is either "tag" or "text") and
+-- a text field (which contains the original token data).
+function tokenize_html(html)
+ local tokens = {}
+ local pos = 1
+ while true do
+ local start = find_first(html, {"<!%-%-", "<[a-z/!$]", "<%?"}, pos)
+ if not start then
+ table.insert(tokens, {type="text", text=html:sub(pos)})
+ break
+ end
+ if start ~= pos then table.insert(tokens, {type="text", text = html:sub(pos, start-1)}) end
+
+ local _, stop
+ if html:match("^<!%-%-", start) then
+ _,stop = html:find("%-%->", start)
+ elseif html:match("^<%?", start) then
+ _,stop = html:find("?>", start)
+ else
+ _,stop = html:find("%b<>", start)
+ end
+ if not stop then
+ -- error("Could not match html tag " .. html:sub(start,start+30))
+ table.insert(tokens, {type="text", text=html:sub(start, start)})
+ pos = start + 1
+ else
+ table.insert(tokens, {type="tag", text=html:sub(start, stop)})
+ pos = stop + 1
+ end
+ end
+ return tokens
+end
+
+----------------------------------------------------------------------
+-- Hash
+----------------------------------------------------------------------
+
+-- This is used to "hash" data into alphanumeric strings that are unique
+-- in the document. (Note that this is not cryptographic hash, the hash
+-- function is not one-way.) The hash procedure is used to protect parts
+-- of the document from further processing.
+
+local HASH = {
+ -- Has the hash been inited.
+ inited = false,
+
+ -- The unique string prepended to all hash values. This is to ensure
+ -- that hash values do not accidently coincide with an actual existing
+ -- string in the document.
+ identifier = "",
+
+ -- Counter that counts up for each new hash instance.
+ counter = 0,
+
+ -- Hash table.
+ table = {}
+}
+
+-- Inits hashing. Creates a hash_identifier that doesn't occur anywhere
+-- in the text.
+function init_hash(text)
+ HASH.inited = true
+ HASH.identifier = ""
+ HASH.counter = 0
+ HASH.table = {}
+
+ local s = "HASH"
+ local counter = 0
+ local id
+ while true do
+ id = s .. counter
+ if not text:find(id, 1, true) then break end
+ counter = counter + 1
+ end
+ HASH.identifier = id
+end
+
+-- Returns the hashed value for s.
+function hash(s)
+ assert(HASH.inited)
+ if not HASH.table[s] then
+ HASH.counter = HASH.counter + 1
+ local id = HASH.identifier .. HASH.counter .. "X"
+ HASH.table[s] = id
+ end
+ return HASH.table[s]
+end
+
+----------------------------------------------------------------------
+-- Protection
+----------------------------------------------------------------------
+
+-- The protection module is used to "protect" parts of a document
+-- so that they are not modified by subsequent processing steps.
+-- Protected parts are saved in a table for later unprotection
+
+-- Protection data
+local PD = {
+ -- Saved blocks that have been converted
+ blocks = {},
+
+ -- Block level tags that will be protected
+ tags = {"p", "div", "h1", "h2", "h3", "h4", "h5", "h6", "blockquote",
+ "pre", "table", "dl", "ol", "ul", "script", "noscript", "form", "fieldset",
+ "iframe", "math", "ins", "del"}
+}
+
+-- Pattern for matching a block tag that begins and ends in the leftmost
+-- column and may contain indented subtags, i.e.
+-- <div>
+-- A nested block.
+-- <div>
+-- Nested data.
+-- </div>
+-- </div>
+function block_pattern(tag)
+ return "\n<" .. tag .. ".-\n</" .. tag .. ">[ \t]*\n"
+end
+
+-- Pattern for matching a block tag that begins and ends with a newline
+function line_pattern(tag)
+ return "\n<" .. tag .. ".-</" .. tag .. ">[ \t]*\n"
+end
+
+-- Protects the range of characters from start to stop in the text and
+-- returns the protected string.
+function protect_range(text, start, stop)
+ local s = text:sub(start, stop)
+ local h = hash(s)
+ PD.blocks[h] = s
+ text = text:sub(1,start) .. h .. text:sub(stop)
+ return text
+end
+
+-- Protect every part of the text that matches any of the patterns. The first
+-- matching pattern is protected first, etc.
+function protect_matches(text, patterns)
+ while true do
+ local start, stop = find_first(text, patterns)
+ if not start then break end
+ text = protect_range(text, start, stop)
+ end
+ return text
+end
+
+-- Protects blocklevel tags in the specified text
+function protect(text)
+ -- First protect potentially nested block tags
+ text = protect_matches(text, map(PD.tags, block_pattern))
+ -- Then protect block tags at the line level.
+ text = protect_matches(text, map(PD.tags, line_pattern))
+ -- Protect <hr> and comment tags
+ text = protect_matches(text, {"\n<hr[^>]->[ \t]*\n"})
+ text = protect_matches(text, {"\n<!%-%-.-%-%->[ \t]*\n"})
+ return text
+end
+
+-- Returns true if the string s is a hash resulting from protection
+function is_protected(s)
+ return PD.blocks[s]
+end
+
+-- Unprotects the specified text by expanding all the nonces
+function unprotect(text)
+ for k,v in pairs(PD.blocks) do
+ v = v:gsub("%%", "%%%%")
+ text = text:gsub(k, v)
+ end
+ return text
+end
+
+
+----------------------------------------------------------------------
+-- Block transform
+----------------------------------------------------------------------
+
+-- The block transform functions transform the text on the block level.
+-- They work with the text as an array of lines rather than as individual
+-- characters.
+
+-- Returns true if the line is a ruler of (char) characters.
+-- The line must contain at least three char characters and contain only spaces and
+-- char characters.
+function is_ruler_of(line, char)
+ if not line:match("^[ %" .. char .. "]*$") then return false end
+ if not line:match("%" .. char .. ".*%" .. char .. ".*%" .. char) then return false end
+ return true
+end
+
+-- Identifies the block level formatting present in the line
+function classify(line)
+ local info = {line = line, text = line}
+
+ if line:match("^ ") then
+ info.type = "indented"
+ info.outdented = line:sub(5)
+ return info
+ end
+
+ for _,c in ipairs({'*', '-', '_', '='}) do
+ if is_ruler_of(line, c) then
+ info.type = "ruler"
+ info.ruler_char = c
+ return info
+ end
+ end
+
+ if line == "" then
+ info.type = "blank"
+ return info
+ end
+
+ if line:match("^(#+)[ \t]*(.-)[ \t]*#*[ \t]*$") then
+ local m1, m2 = line:match("^(#+)[ \t]*(.-)[ \t]*#*[ \t]*$")
+ info.type = "header"
+ info.level = m1:len()
+ info.text = m2
+ return info
+ end
+
+ if line:match("^ ? ? ?(%d+)%.[ \t]+(.+)") then
+ local number, text = line:match("^ ? ? ?(%d+)%.[ \t]+(.+)")
+ info.type = "list_item"
+ info.list_type = "numeric"
+ info.number = 0 + number
+ info.text = text
+ return info
+ end
+
+ if line:match("^ ? ? ?([%*%+%-])[ \t]+(.+)") then
+ local bullet, text = line:match("^ ? ? ?([%*%+%-])[ \t]+(.+)")
+ info.type = "list_item"
+ info.list_type = "bullet"
+ info.bullet = bullet
+ info.text= text
+ return info
+ end
+
+ if line:match("^>[ \t]?(.*)") then
+ info.type = "blockquote"
+ info.text = line:match("^>[ \t]?(.*)")
+ return info
+ end
+
+ if is_protected(line) then
+ info.type = "raw"
+ info.html = unprotect(line)
+ return info
+ end
+
+ info.type = "normal"
+ return info
+end
+
+-- Find headers constisting of a normal line followed by a ruler and converts them to
+-- header entries.
+function headers(array)
+ local i = 1
+ while i <= #array - 1 do
+ if array[i].type == "normal" and array[i+1].type == "ruler" and
+ (array[i+1].ruler_char == "-" or array[i+1].ruler_char == "=") then
+ local info = {line = array[i].line}
+ info.text = info.line
+ info.type = "header"
+ info.level = iff(array[i+1].ruler_char == "=", 1, 2)
+ table.remove(array, i+1)
+ array[i] = info
+ end
+ i = i + 1
+ end
+ return array
+end
+
+-- Find list blocks and convert them to protected data blocks
+function lists(array, sublist)
+ local function process_list(arr)
+ local function any_blanks(arr)
+ for i = 1, #arr do
+ if arr[i].type == "blank" then return true end
+ end
+ return false
+ end
+
+ local function split_list_items(arr)
+ local acc = {arr[1]}
+ local res = {}
+ for i=2,#arr do
+ if arr[i].type == "list_item" then
+ table.insert(res, acc)
+ acc = {arr[i]}
+ else
+ table.insert(acc, arr[i])
+ end
+ end
+ table.insert(res, acc)
+ return res
+ end
+
+ local function process_list_item(lines, block)
+ while lines[#lines].type == "blank" do
+ table.remove(lines)
+ end
+
+ local itemtext = lines[1].text
+ for i=2,#lines do
+ itemtext = itemtext .. "\n" .. outdent(lines[i].line)
+ end
+ if block then
+ itemtext = block_transform(itemtext, true)
+ if not itemtext:find("<pre>") then itemtext = indent(itemtext) end
+ return " <li>" .. itemtext .. "</li>"
+ else
+ local lines = split(itemtext)
+ lines = map(lines, classify)
+ lines = lists(lines, true)
+ lines = blocks_to_html(lines, true)
+ itemtext = table.concat(lines, "\n")
+ if not itemtext:find("<pre>") then itemtext = indent(itemtext) end
+ return " <li>" .. itemtext .. "</li>"
+ end
+ end
+
+ local block_list = any_blanks(arr)
+ local items = split_list_items(arr)
+ local out = ""
+ for _, item in ipairs(items) do
+ out = out .. process_list_item(item, block_list) .. "\n"
+ end
+ if arr[1].list_type == "numeric" then
+ return "<ol>\n" .. out .. "</ol>"
+ else
+ return "<ul>\n" .. out .. "</ul>"
+ end
+ end
+
+ -- Finds the range of lines composing the first list in the array. A list
+ -- starts with (^ list_item) or (blank list_item) and ends with
+ -- (blank* $) or (blank normal).
+ --
+ -- A sublist can start with just (list_item) does not need a blank...
+ local function find_list(array, sublist)
+ local function find_list_start(array, sublist)
+ if array[1].type == "list_item" then return 1 end
+ if sublist then
+ for i = 1,#array do
+ if array[i].type == "list_item" then return i end
+ end
+ else
+ for i = 1, #array-1 do
+ if array[i].type == "blank" and array[i+1].type == "list_item" then
+ return i+1
+ end
+ end
+ end
+ return nil
+ end
+ local function find_list_end(array, start)
+ local pos = #array
+ for i = start, #array-1 do
+ if array[i].type == "blank" and array[i+1].type ~= "list_item"
+ and array[i+1].type ~= "indented" and array[i+1].type ~= "blank" then
+ pos = i-1
+ break
+ end
+ end
+ while pos > start and array[pos].type == "blank" do
+ pos = pos - 1
+ end
+ return pos
+ end
+
+ local start = find_list_start(array, sublist)
+ if not start then return nil end
+ return start, find_list_end(array, start)
+ end
+
+ while true do
+ local start, stop = find_list(array, sublist)
+ if not start then break end
+ local text = process_list(splice(array, start, stop))
+ local info = {
+ line = text,
+ type = "raw",
+ html = text
+ }
+ array = splice(array, start, stop, {info})
+ end
+
+ -- Convert any remaining list items to normal
+ for _,line in ipairs(array) do
+ if line.type == "list_item" then line.type = "normal" end
+ end
+
+ return array
+end
+
+-- Find and convert blockquote markers.
+function blockquotes(lines)
+ local function find_blockquote(lines)
+ local start
+ for i,line in ipairs(lines) do
+ if line.type == "blockquote" then
+ start = i
+ break
+ end
+ end
+ if not start then return nil end
+
+ local stop = #lines
+ for i = start+1, #lines do
+ if lines[i].type == "blank" or lines[i].type == "blockquote" then
+ elseif lines[i].type == "normal" then
+ if lines[i-1].type == "blank" then stop = i-1 break end
+ else
+ stop = i-1 break
+ end
+ end
+ while lines[stop].type == "blank" do stop = stop - 1 end
+ return start, stop
+ end
+
+ local function process_blockquote(lines)
+ local raw = lines[1].text
+ for i = 2,#lines do
+ raw = raw .. "\n" .. lines[i].text
+ end
+ local bt = block_transform(raw)
+ if not bt:find("<pre>") then bt = indent(bt) end
+ return "<blockquote>\n " .. bt ..
+ "\n</blockquote>"
+ end
+
+ while true do
+ local start, stop = find_blockquote(lines)
+ if not start then break end
+ local text = process_blockquote(splice(lines, start, stop))
+ local info = {
+ line = text,
+ type = "raw",
+ html = text
+ }
+ lines = splice(lines, start, stop, {info})
+ end
+ return lines
+end
+
+-- Find and convert codeblocks.
+function codeblocks(lines)
+ local function find_codeblock(lines)
+ local start
+ for i,line in ipairs(lines) do
+ if line.type == "indented" then start = i break end
+ end
+ if not start then return nil end
+
+ local stop = #lines
+ for i = start+1, #lines do
+ if lines[i].type ~= "indented" and lines[i].type ~= "blank" then
+ stop = i-1
+ break
+ end
+ end
+ while lines[stop].type == "blank" do stop = stop - 1 end
+ return start, stop
+ end
+
+ local function process_codeblock(lines)
+ local raw = detab(encode_code(outdent(lines[1].line)))
+ for i = 2,#lines do
+ raw = raw .. "\n" .. detab(encode_code(outdent(lines[i].line)))
+ end
+ return "<pre><code>" .. raw .. "\n</code></pre>"
+ end
+
+ while true do
+ local start, stop = find_codeblock(lines)
+ if not start then break end
+ local text = process_codeblock(splice(lines, start, stop))
+ local info = {
+ line = text,
+ type = "raw",
+ html = text
+ }
+ lines = splice(lines, start, stop, {info})
+ end
+ return lines
+end
+
+local idcount = 1
+local list_of_headers = {}
+local first_header
+
+-- Convert lines to html code
+function blocks_to_html(lines, no_paragraphs)
+ local out = {}
+ local i = 1
+ while i <= #lines do
+ local line = lines[i]
+ if line.type == "ruler" then
+ table.insert(out, "<hr/>")
+ elseif line.type == "raw" then
+ table.insert(out, line.html)
+ elseif line.type == "normal" then
+ local s = line.line
+
+ while i+1 <= #lines and lines[i+1].type == "normal" do
+ i = i + 1
+ s = s .. "\n" .. lines[i].line
+ end
+
+ if no_paragraphs then
+ table.insert(out, span_transform(s))
+ else
+ table.insert(out, "<p>" .. span_transform(s) .. "</p>")
+ end
+ elseif line.type == "header" then
+ local txt = span_transform(line.text)
+ local id = "T" .. idcount
+ local s = "<h" .. line.level .. ' id="'.. id .. '">' .. txt .. "</h" .. line.level .. ">"
+ if not first_header then
+ first_header = {line=s,text=txt}
+ else
+ table.insert(out, s)
+ table.insert(list_of_headers, {level=line.level,text=txt,id=id})
+ end
+ idcount = idcount + 1
+ else
+ table.insert(out, line.line)
+ end
+ i = i + 1
+ end
+ return out
+end
+
+-- Perform all the block level transforms
+function block_transform(text, sublist)
+ local lines = split(text)
+ lines = map(lines, classify)
+ lines = headers(lines)
+ lines = lists(lines, sublist)
+ lines = codeblocks(lines)
+ lines = blockquotes(lines)
+ lines = blocks_to_html(lines)
+ local text = table.concat(lines, "\n")
+ return text
+end
+
+-- Debug function for printing a line array to see the result
+-- of partial transforms.
+function print_lines(lines)
+ for i, line in ipairs(lines) do
+ print(i, line.type, line.text or line.line)
+ end
+end
+
+----------------------------------------------------------------------
+-- Span transform
+----------------------------------------------------------------------
+
+-- Functions for transforming the text at the span level.
+
+-- These characters may need to be escaped because they have a special
+-- meaning in markdown.
+escape_chars = "'\\`*_{}[]()>#+-.!'"
+escape_table = {}
+
+function init_escape_table()
+ escape_table = {}
+ for i = 1,#escape_chars do
+ local c = escape_chars:sub(i,i)
+ escape_table[c] = hash(c)
+ end
+end
+
+-- Adds a new escape to the escape table.
+function add_escape(text)
+ if not escape_table[text] then
+ escape_table[text] = hash(text)
+ end
+ return escape_table[text]
+end
+
+-- Escape characters that should not be disturbed by markdown.
+function escape_special_chars(text)
+ local tokens = tokenize_html(text)
+
+ local out = ""
+ for _, token in ipairs(tokens) do
+ local t = token.text
+ if token.type == "tag" then
+ -- In tags, encode * and _ so they don't conflict with their use in markdown.
+ t = t:gsub("%*", escape_table["*"])
+ t = t:gsub("%_", escape_table["_"])
+ else
+ t = encode_backslash_escapes(t)
+ end
+ out = out .. t
+ end
+ return out
+end
+
+-- Encode backspace-escaped characters in the markdown source.
+function encode_backslash_escapes(t)
+ for i=1,escape_chars:len() do
+ local c = escape_chars:sub(i,i)
+ t = t:gsub("\\%" .. c, escape_table[c])
+ end
+ return t
+end
+
+-- Unescape characters that have been encoded.
+function unescape_special_chars(t)
+ local tin = t
+ for k,v in pairs(escape_table) do
+ k = k:gsub("%%", "%%%%")
+ t = t:gsub(v,k)
+ end
+ if t ~= tin then t = unescape_special_chars(t) end
+ return t
+end
+
+-- Encode/escape certain characters inside Markdown code runs.
+-- The point is that in code, these characters are literals,
+-- and lose their special Markdown meanings.
+function encode_code(s)
+ s = s:gsub("%&", "&")
+ s = s:gsub("<", "<")
+ s = s:gsub(">", ">")
+ for k,v in pairs(escape_table) do
+ s = s:gsub("%"..k, v)
+ end
+ return s
+end
+
+-- Handle backtick blocks.
+function code_spans(s)
+ s = s:gsub("\\\\", escape_table["\\"])
+ s = s:gsub("\\`", escape_table["`"])
+
+ local pos = 1
+ while true do
+ local start, stop = s:find("`+", pos)
+ if not start then return s end
+ local count = stop - start + 1
+ -- Find a matching numbert of backticks
+ local estart, estop = s:find(string.rep("`", count), stop+1)
+ local brstart = s:find("\n", stop+1)
+ if estart and (not brstart or estart < brstart) then
+ local code = s:sub(stop+1, estart-1)
+ code = code:gsub("^[ \t]+", "")
+ code = code:gsub("[ \t]+$", "")
+ code = code:gsub(escape_table["\\"], escape_table["\\"] .. escape_table["\\"])
+ code = code:gsub(escape_table["`"], escape_table["\\"] .. escape_table["`"])
+ code = "<code>" .. encode_code(code) .. "</code>"
+ code = add_escape(code)
+ s = s:sub(1, start-1) .. code .. s:sub(estop+1)
+ pos = start + code:len()
+ else
+ pos = stop + 1
+ end
+ end
+ return s
+end
+
+-- Encode alt text... enodes &, and ".
+function encode_alt(s)
+ if not s then return s end
+ s = s:gsub('&', '&')
+ s = s:gsub('"', '"')
+ s = s:gsub('<', '<')
+ return s
+end
+
+-- Handle image references
+function images(text)
+ local function reference_link(alt, id)
+ alt = encode_alt(alt:match("%b[]"):sub(2,-2))
+ id = id:match("%[(.*)%]"):lower()
+ if id == "" then id = text:lower() end
+ link_database[id] = link_database[id] or {}
+ if not link_database[id].url then return nil end
+ local url = link_database[id].url or id
+ url = encode_alt(url)
+ local title = encode_alt(link_database[id].title)
+ if title then title = " title=\"" .. title .. "\"" else title = "" end
+ return add_escape ('<img src="' .. url .. '" alt="' .. alt .. '"' .. title .. "/>")
+ end
+
+ local function inline_link(alt, link)
+ alt = encode_alt(alt:match("%b[]"):sub(2,-2))
+ local url, title = link:match("%(<?(.-)>?[ \t]*['\"](.+)['\"]")
+ url = url or link:match("%(<?(.-)>?%)")
+ url = encode_alt(url)
+ title = encode_alt(title)
+ if title then
+ return add_escape('<img src="' .. url .. '" alt="' .. alt .. '" title="' .. title .. '"/>')
+ else
+ return add_escape('<img src="' .. url .. '" alt="' .. alt .. '"/>')
+ end
+ end
+
+ text = text:gsub("!(%b[])[ \t]*\n?[ \t]*(%b[])", reference_link)
+ text = text:gsub("!(%b[])(%b())", inline_link)
+ return text
+end
+
+-- Handle anchor references
+function anchors(text)
+ local function reference_link(text, id)
+ text = text:match("%b[]"):sub(2,-2)
+ id = id:match("%b[]"):sub(2,-2):lower()
+ if id == "" then id = text:lower() end
+ link_database[id] = link_database[id] or {}
+ if not link_database[id].url then return nil end
+ local url = link_database[id].url or id
+ url = encode_alt(url)
+ local title = encode_alt(link_database[id].title)
+ if title then title = " title=\"" .. title .. "\"" else title = "" end
+ return add_escape("<a href=\"" .. url .. "\"" .. title .. ">") .. text .. add_escape("</a>")
+ end
+
+ local function inline_link(text, link)
+ text = text:match("%b[]"):sub(2,-2)
+ local url, title = link:match("%(<?(.-)>?[ \t]*['\"](.+)['\"]")
+ title = encode_alt(title)
+ url = url or link:match("%(<?(.-)>?%)") or ""
+ url = encode_alt(url)
+ if title then
+ return add_escape("<a href=\"" .. url .. "\" title=\"" .. title .. "\">") .. text .. "</a>"
+ else
+ return add_escape("<a href=\"" .. url .. "\">") .. text .. add_escape("</a>")
+ end
+ end
+
+ text = text:gsub("(%b[])[ \t]*\n?[ \t]*(%b[])", reference_link)
+ text = text:gsub("(%b[])(%b())", inline_link)
+ return text
+end
+
+-- Handle auto links, i.e. <http://www.google.com/>.
+function auto_links(text)
+ local function link(s)
+ return add_escape("<a href=\"" .. s .. "\">") .. s .. "</a>"
+ end
+ -- Encode chars as a mix of dec and hex entitites to (perhaps) fool
+ -- spambots.
+ local function encode_email_address(s)
+ -- Use a deterministic encoding to make unit testing possible.
+ -- Code 45% hex, 45% dec, 10% plain.
+ local hex = {code = function(c) return "&#x" .. string.format("%x", c:byte()) .. ";" end, count = 1, rate = 0.45}
+ local dec = {code = function(c) return "&#" .. c:byte() .. ";" end, count = 0, rate = 0.45}
+ local plain = {code = function(c) return c end, count = 0, rate = 0.1}
+ local codes = {hex, dec, plain}
+ local function swap(t,k1,k2) local temp = t[k2] t[k2] = t[k1] t[k1] = temp end
+
+ local out = ""
+ for i = 1,s:len() do
+ for _,code in ipairs(codes) do code.count = code.count + code.rate end
+ if codes[1].count < codes[2].count then swap(codes,1,2) end
+ if codes[2].count < codes[3].count then swap(codes,2,3) end
+ if codes[1].count < codes[2].count then swap(codes,1,2) end
+
+ local code = codes[1]
+ local c = s:sub(i,i)
+ -- Force encoding of "@" to make email address more invisible.
+ if c == "@" and code == plain then code = codes[2] end
+ out = out .. code.code(c)
+ code.count = code.count - 1
+ end
+ return out
+ end
+ local function mail(s)
+ s = unescape_special_chars(s)
+ local address = encode_email_address("mailto:" .. s)
+ local text = encode_email_address(s)
+ return add_escape("<a href=\"" .. address .. "\">") .. text .. "</a>"
+ end
+ -- links
+ text = text:gsub("<(https?:[^'\">%s]+)>", link)
+ text = text:gsub("<(ftp:[^'\">%s]+)>", link)
+
+ -- mail
+ text = text:gsub("<mailto:([^'\">%s]+)>", mail)
+ text = text:gsub("<([-.%w]+%@[-.%w]+)>", mail)
+ return text
+end
+
+-- Encode free standing amps (&) and angles (<)... note that this does not
+-- encode free >.
+function amps_and_angles(s)
+ -- encode amps not part of &..; expression
+ local pos = 1
+ while true do
+ local amp = s:find("&", pos)
+ if not amp then break end
+ local semi = s:find(";", amp+1)
+ local stop = s:find("[ \t\n&]", amp+1)
+ if not semi or (stop and stop < semi) or (semi - amp) > 15 then
+ s = s:sub(1,amp-1) .. "&" .. s:sub(amp+1)
+ pos = amp+1
+ else
+ pos = amp+1
+ end
+ end
+
+ -- encode naked <'s
+ s = s:gsub("<([^a-zA-Z/?$!])", "<%1")
+ s = s:gsub("<$", "<")
+
+ -- what about >, nothing done in the original markdown source to handle them
+ return s
+end
+
+-- Handles emphasis markers (* and _) in the text.
+function emphasis(text)
+ for _, s in ipairs {"%*%*", "%_%_"} do
+ text = text:gsub(s .. "([^%s][%*%_]?)" .. s, "<strong>%1</strong>")
+ text = text:gsub(s .. "([^%s][^<>]-[^%s][%*%_]?)" .. s, "<strong>%1</strong>")
+ end
+ for _, s in ipairs {"%*", "%_"} do
+ text = text:gsub(s .. "([^%s_])" .. s, "<em>%1</em>")
+ text = text:gsub(s .. "(<strong>[^%s_]</strong>)" .. s, "<em>%1</em>")
+ text = text:gsub(s .. "([^%s_][^<>_]-[^%s_])" .. s, "<em>%1</em>")
+ text = text:gsub(s .. "([^<>_]-<strong>[^<>_]-</strong>[^<>_]-)" .. s, "<em>%1</em>")
+ end
+ return text
+end
+
+-- Handles line break markers in the text.
+function line_breaks(text)
+ return text:gsub(" +\n", " <br/>\n")
+end
+
+-- Perform all span level transforms.
+function span_transform(text)
+ text = code_spans(text)
+ text = escape_special_chars(text)
+ text = images(text)
+ text = anchors(text)
+ text = auto_links(text)
+ text = amps_and_angles(text)
+ text = emphasis(text)
+ text = line_breaks(text)
+ return text
+end
+
+----------------------------------------------------------------------
+-- Markdown
+----------------------------------------------------------------------
+
+-- Cleanup the text by normalizing some possible variations to make further
+-- processing easier.
+function cleanup(text)
+ -- Standardize line endings
+ text = text:gsub("\r\n", "\n") -- DOS to UNIX
+ text = text:gsub("\r", "\n") -- Mac to UNIX
+
+ -- Convert all tabs to spaces
+ text = detab(text)
+
+ -- Strip lines with only spaces and tabs
+ while true do
+ local subs
+ text, subs = text:gsub("\n[ \t]+\n", "\n\n")
+ if subs == 0 then break end
+ end
+
+ return "\n" .. text .. "\n"
+end
+
+-- Strips link definitions from the text and stores the data in a lookup table.
+function strip_link_definitions(text)
+ local linkdb = {}
+
+ local function link_def(id, url, title)
+ id = id:match("%[(.+)%]"):lower()
+ linkdb[id] = linkdb[id] or {}
+ linkdb[id].url = url or linkdb[id].url
+ linkdb[id].title = title or linkdb[id].title
+ return ""
+ end
+
+ local def_no_title = "\n ? ? ?(%b[]):[ \t]*\n?[ \t]*<?([^%s>]+)>?[ \t]*"
+ local def_title1 = def_no_title .. "[ \t]+\n?[ \t]*[\"'(]([^\n]+)[\"')][ \t]*"
+ local def_title2 = def_no_title .. "[ \t]*\n[ \t]*[\"'(]([^\n]+)[\"')][ \t]*"
+ local def_title3 = def_no_title .. "[ \t]*\n?[ \t]+[\"'(]([^\n]+)[\"')][ \t]*"
+
+ text = text:gsub(def_title1, link_def)
+ text = text:gsub(def_title2, link_def)
+ text = text:gsub(def_title3, link_def)
+ text = text:gsub(def_no_title, link_def)
+ return text, linkdb
+end
+
+link_database = {}
+
+-- Main markdown processing function
+function markdown(text)
+ init_hash(text)
+ init_escape_table()
+
+ text = cleanup(text)
+ text = protect(text)
+ text, link_database = strip_link_definitions(text)
+ text = block_transform(text)
+ text = unescape_special_chars(text)
+ return text
+end
+
+----------------------------------------------------------------------
+-- End of module
+----------------------------------------------------------------------
+
+setfenv(1, _G)
+M.lock(M)
+
+-- Expose markdown function to the world
+markdown = M.markdown
+
+-- Class for parsing command-line options
+local OptionParser = {}
+OptionParser.__index = OptionParser
+
+-- Creates a new option parser
+function OptionParser:new()
+ local o = {short = {}, long = {}}
+ setmetatable(o, self)
+ return o
+end
+
+-- Calls f() whenever a flag with specified short and long name is encountered
+function OptionParser:flag(short, long, f)
+ local info = {type = "flag", f = f}
+ if short then self.short[short] = info end
+ if long then self.long[long] = info end
+end
+
+-- Calls f(param) whenever a parameter flag with specified short and long name is encountered
+function OptionParser:param(short, long, f)
+ local info = {type = "param", f = f}
+ if short then self.short[short] = info end
+ if long then self.long[long] = info end
+end
+
+-- Calls f(v) for each non-flag argument
+function OptionParser:arg(f)
+ self.arg = f
+end
+
+-- Runs the option parser for the specified set of arguments. Returns true if all arguments
+-- where successfully parsed and false otherwise.
+function OptionParser:run(args)
+ local pos = 1
+ while pos <= #args do
+ local arg = args[pos]
+ if arg == "--" then
+ for i=pos+1,#args do
+ if self.arg then self.arg(args[i]) end
+ return true
+ end
+ end
+ if arg:match("^%-%-") then
+ local info = self.long[arg:sub(3)]
+ if not info then print("Unknown flag: " .. arg) return false end
+ if info.type == "flag" then
+ info.f()
+ pos = pos + 1
+ else
+ param = args[pos+1]
+ if not param then print("No parameter for flag: " .. arg) return false end
+ info.f(param)
+ pos = pos+2
+ end
+ elseif arg:match("^%-") then
+ for i=2,arg:len() do
+ local c = arg:sub(i,i)
+ local info = self.short[c]
+ if not info then print("Unknown flag: -" .. c) return false end
+ if info.type == "flag" then
+ info.f()
+ else
+ if i == arg:len() then
+ param = args[pos+1]
+ if not param then print("No parameter for flag: -" .. c) return false end
+ info.f(param)
+ pos = pos + 1
+ else
+ param = arg:sub(i+1)
+ info.f(param)
+ end
+ break
+ end
+ end
+ pos = pos + 1
+ else
+ if self.arg then self.arg(arg) end
+ pos = pos + 1
+ end
+ end
+ return true
+end
+
+-- Handles the case when markdown is run from the command line
+local function run_command_line(arg)
+ -- Generate output for input s given options
+ local function run(s, options)
+ s = markdown(s)
+ if not options.wrap_header then return s end
+ local header = ""
+ if options.header then
+ local f = io.open(options.header) or error("Could not open file: " .. options.header)
+ header = f:read("*a")
+ f:close()
+ else
+ header = [[
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html>
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=CHARSET" />
+ <title>TITLE</title>
+ <link rel="stylesheet" type="text/css" href="STYLESHEET" />
+</head>
+<body>
+]]
+ local title = options.title or (first_header and first_header.text) or "Untitled"
+ header = header:gsub("TITLE", title)
+ if options.inline_style then
+ local style = ""
+ local f = io.open(options.stylesheet)
+ if f then
+ style = f:read("*a") f:close()
+ else
+ error("Could not include style sheet " .. options.stylesheet .. ": File not found")
+ end
+ header = header:gsub('<link rel="stylesheet" type="text/css" href="STYLESHEET" />',
+ "<style type=\"text/css\"><!--\n" .. style .. "\n--></style>")
+ else
+ header = header:gsub("STYLESHEET", options.stylesheet)
+ end
+ header = header:gsub("CHARSET", options.charset)
+ end
+ local footer = "</body></html>"
+ if options.footer then
+ local f = io.open(options.footer) or error("Could not open file: " .. options.footer)
+ footer = f:read("*a")
+ f:close()
+ end
+ if first_header then
+ header = header .. first_header.line ..'\n'
+ -- Build TOC if required!
+ local txt = ''
+ local indent = 0
+ local last_level
+ for i,h in ipairs(list_of_headers) do
+ if i > 1 then
+ local diff = h.level - last_level
+ if diff > 0 then indent = indent + 1
+ elseif diff < 0 then indent = indent - 1
+ end
+ end
+ txt = txt..string.rep('\t',indent)..'* ['..h.text..'](#'..h.id..')\n'
+ last_level = h.level
+ end
+ header = header .. markdown(txt)
+ end
+ return header .. s .. footer
+ end
+
+ -- Generate output path name from input path name given options.
+ local function outpath(path, options)
+ if options.append then return path .. ".html" end
+ local m = path:match("^(.+%.html)[^/\\]+$") if m then return m end
+ m = path:match("^(.+%.)[^/\\]*$") if m and path ~= m .. "html" then return m .. "html" end
+ return path .. ".html"
+ end
+
+ -- Default commandline options
+ local options = {
+ wrap_header = true,
+ header = nil,
+ footer = nil,
+ charset = "utf-8",
+ title = nil,
+ stylesheet = "default.css",
+ inline_style = false
+ }
+ local help = [[
+Usage: markdown.lua [OPTION] [FILE]
+Runs the markdown text markup to HTML converter on each file specified on the
+command line. If no files are specified, runs on standard input.
+
+No header:
+ -n, --no-wrap Don't wrap the output in <html>... tags.
+Custom header:
+ -e, --header FILE Use content of FILE for header.
+ -f, --footer FILE Use content of FILE for footer.
+Generated header:
+ -c, --charset SET Specifies charset (default utf-8).
+ -i, --title TITLE Specifies title (default from first <h1> tag).
+ -s, --style STYLE Specifies style sheet file (default default.css).
+ -l, --inline-style Include the style sheet file inline in the header.
+Generated files:
+ -a, --append Append .html extension (instead of replacing).
+Other options:
+ -h, --help Print this help text.
+ -t, --test Run the unit tests.
+]]
+
+ local run_stdin = true
+ local op = OptionParser:new()
+ op:flag("n", "no-wrap", function () options.wrap_header = false end)
+ op:param("e", "header", function (x) options.header = x end)
+ op:param("f", "footer", function (x) options.footer = x end)
+ op:param("c", "charset", function (x) options.charset = x end)
+ op:param("i", "title", function(x) options.title = x end)
+ op:param("s", "style", function(x) options.stylesheet = x end)
+ op:flag("l", "inline-style", function(x) options.inline_style = true end)
+ op:flag("a", "append", function() options.append = true end)
+ op:flag("t", "test", function()
+ local n = arg[0]:gsub("markdown.lua", "markdown-tests.lua")
+ local f = io.open(n)
+ if f then
+ f:close() dofile(n)
+ else
+ error("Cannot find markdown-tests.lua")
+ end
+ run_stdin = false
+ end)
+ op:flag("h", "help", function() print(help) run_stdin = false end)
+ op:arg(function(path)
+ local file = io.open(path) or error("Could not open file: " .. path)
+ local s = file:read("*a")
+ file:close()
+ s = run(s, options)
+ file = io.open(outpath(path, options), "w") or error("Could not open output file: " .. outpath(path, options))
+ file:write(s)
+ file:close()
+ run_stdin = false
+ end
+ )
+
+ if not op:run(arg) then
+ print(help)
+ run_stdin = false
+ end
+
+ if run_stdin then
+ local s = io.read("*a")
+ s = run(s, options)
+ io.write(s)
+ end
+end
+
+-- If we are being run from the command-line, act accordingly
+if arg and arg[0]:find("markdown%.lua$") then
+ run_command_line(arg)
+else
+ return markdown
+end
diff --git a/docs/penlight.md b/docs/penlight.md index 6d22c1d..2d3ba7a 100644 --- a/docs/penlight.md +++ b/docs/penlight.md @@ -3,7 +3,7 @@ The module documentation is available [here](api/index.html); and there is an alphabetical [function index](function_index.html).
-The latest vesion is available at [LuaForge](http://luaforge.net/frs/?group_id=450).
+The latest vesion is available at [Github](http://github.com/stevedonovan/Penlight).
## Introduction
@@ -85,12 +85,10 @@ If you wish to enforce strictness globally, then just add `require 'pl.strict'` ### What are function arguments in Penlight?
-Many functions in Penlight themselves take function arguments, like `map` which applies a function to a list, element by element. You can use existing functions, like `math.max`, anonymous functions (like `function(x,y) return x > y end`), operations by name (e.g '*' or '..') or _string lambdas_ like '|x,y| x > y'. The module `pl.operator` exports all the standard Lua operations, like the Python module of the same name. Penlight allows these to be refered to by name, so `operator.gt` can be more concisely expressed as '>'.
+Many functions in Penlight themselves take function arguments, like `map` which applies a function to a list, element by element. You can use existing functions, like `math.max`, anonymous functions (like `function(x,y) return x > y end`), or operations by name (e.g '*' or '..'). The module `pl.operator` exports all the standard Lua operations, like the Python module of the same name. Penlight allows these to be refered to by name, so `operator.gt` can be more concisely expressed as '>'.
Note that the `map` functions pass any extra arguments to the function, so we can have `ls:filter('>',0)`, which is effectively `ls:filter(function(x) return x > 0 end)`.
-String lambdas provide a convenient way to express simple anonymous functions, without the 'keyword noise' of the usual syntax. This is not to everyone's taste, which is why it is not part of the language itself, but these forms can make code that is both more compact and readable.
-
Finally, `pl.func` supports _placeholder expressions_ in the Boost style, so that an anonymous function to multiply the two arguments can be expressed as `_1*_2`.
To use them directly, note that _all_ function arguments in Penlight go through `utils.function_arg`:
@@ -133,10 +131,10 @@ A common pattern when working with Lua varargs is capturing all the arguments in ...
end
-But this will bite you someday when `nil` is one of the arguments, since this will put a 'hole' in your table. In particular, `#ls` will only give you the size upto the `nil` value. Hence the need for `utils.args`:
+But this will bite you someday when `nil` is one of the arguments, since this will put a 'hole' in your table. In particular, `#ls` will only give you the size upto the `nil` value. Hence the need for `table.pack` - this is a new Lua 5.2 function which Penlight defines also for Lua 5.1.
function t(...)
- local args,n = utils.args(...)
+ local args,n = table.pack(...)
for i = 1,n do
...
end
@@ -154,6 +152,7 @@ The 'memoize' pattern occurs when you have a function which is expensive to call ...
s = sum(1e8) --returned saved value!
+<a id="app"/>
### Application Support
`app.parse_args` is a simple command-line argument parser. If called without any arguments, it tries to use the global `arg` array. It returns the _flags_ (options begining with '-') as a table of name/value pairs, and the _arguments_ as an array. It knows about long GNU-style flag names, e.g. `--value`, and groups of short flags are understood, so that `-ab` is short for `-a -b`. The flags result would then look like `{value=true,a=true,b=true}`.
@@ -179,7 +178,7 @@ and the equivalent on my Linux machine: Penlight makes it convenient to save application data in Lua format. You can use `pretty.dump(t,file)` to write a Lua table in a human-readable form to a file, and `pretty.read(file.read(file))` to generate the table again.
-(@see pl.app, @see pl.pretty)
+(@see app, @see pretty)
<a id="class"/>
@@ -268,7 +267,7 @@ This useful notation is borrowed from Hugo Etchegoyen's [classlib](http://lua-us ### Python-style Lists
-One of the elegant things about Lua is that tables do the job of both lists and dicts (as called in Python) or vectors and maps, (as called in C++), and they do it efficiently. However, if we are dealing with 'tables with numerical indices' we may as well call them lists and look for operations which particularly make sense for lists. The Penlight `List` class was originally written by Nick Trout for Lua 5.0, and translated to 5.1 and extended by myself. It seemed that borrowing from Python was a good idea, and this eventually grew into Penlight. (@see pl.list)
+One of the elegant things about Lua is that tables do the job of both lists and dicts (as called in Python) or vectors and maps, (as called in C++), and they do it efficiently. However, if we are dealing with 'tables with numerical indices' we may as well call them lists and look for operations which particularly make sense for lists. The Penlight `List` class was originally written by Nick Trout for Lua 5.0, and translated to 5.1 and extended by myself. It seemed that borrowing from Python was a good idea, and this eventually grew into Penlight. (@see list)
Here is an example showing `List` in action; it redefines `__tostring`, so that it can print itself out more sensibly:
@@ -428,7 +427,7 @@ In general, this parameter is meant to be passed to the _class constructor_. In end
-(@see pl.class, @see pl.classx)
+(@see class, @see classx)
### Tablex. Useful Operations on Tables
@@ -442,7 +441,7 @@ The functions provided in `table` provide all the basic manipulations on Lua tab end
return res
-The `tablex` module (@see pl.tablex) provides this as `copy`, which does a _shallow_ copy of a table. There is also `deepcopy` which goes further than a simple loop in two ways; first, it also gives the copy the same metatable as the original (so it can copy objects like `List` above) and any nested tables will also be copied, to arbitrary depth. There is also `icopy` which operates on list-like tables, where you can set optionally set the start index of the source and destination as well. It ensures that any left-over elements will be deleted:
+The `tablex` module (@see tablex) provides this as `copy`, which does a _shallow_ copy of a table. There is also `deepcopy` which goes further than a simple loop in two ways; first, it also gives the copy the same metatable as the original (so it can copy objects like `List` above) and any nested tables will also be copied, to arbitrary depth. There is also `icopy` which operates on list-like tables, where you can set optionally set the start index of the source and destination as well. It ensures that any left-over elements will be deleted:
asserteq(icopy({1,2,3,4,5,6},{20,30}),{20,30}) -- start at 1
asserteq(icopy({1,2,3,4,5,6},{20,30},2),{1,20,30}) -- start at 2
@@ -707,7 +706,7 @@ This applies to `iter` as well, which can also optionally be given a range: 3 2 8
3 3 9
-(@see pl.array2d)
+(@see array2d)
## Strings. Higher-level operations on strings.
@@ -737,7 +736,7 @@ These are convenient borrowings from Python, as described in 3.6.1 of the Python Most of these can be fairly easily implemented using the Lua string library, which is more general and powerful. But they are convenient operations to have easily at hand. Note that can be injected into the `string` table if you use `require 'pl'` and then `stringx.import()`, or explicitly call `pl.stringx.import()`, but a simple alias like 'stringx = require 'pl.string'` can be used. This is the recommended practice when writing modules for consumption by other people, since it is bad manners to change the global state of the rest of the system.
-(@see pl.stringx)
+(@see stringx)
### String Templates
@@ -785,7 +784,7 @@ And the output is: `pl.text` also has a number of useful functions like `dedent`, which strips all the initial indentation from a multiline string. As in Python, this is useful for preprocessing multiline strings if you like indenting them with your code. The function `wrap` is passed a long string (a _paragraph_) and returns a list of lines that fit into a desired line width. As an extension, there is also `indent` for indenting multiline strings.
-(@see pl.text)
+(@see text)
## Paths and Directories
@@ -956,7 +955,9 @@ This is more self-documenting; it is generally better to make the code express t ### Reading Unstructured Text Data
-Text data is sometimes unstructured, for example a file containing words. The 'pl.input` module has a number of functions which makes processing such files easier. For example, a script to count the number of words in standard input (@see pl.input.words):
+<a id="input"/>
+
+Text data is sometimes unstructured, for example a file containing words. The 'pl.input` module has a number of functions which makes processing such files easier. For example, a script to count the number of words in standard input (@see input.words):
-- countwords.lua
require 'pl'
@@ -966,7 +967,7 @@ Text data is sometimes unstructured, for example a file containing words. The 'p end
print('count',k)
-Or this script to calculate the average of a set of numbers (@see pl.input.numbers):
+Or this script to calculate the average of a set of numbers (@see input.numbers):
-- average.lua
require 'pl'
@@ -998,8 +999,6 @@ A useful feature of a sequence generator like `numbers` is that it can read from print(seq.sum(input.numbers(line))
end
-<a id="data"/>
-
### Reading Columnar Data
It is very common to find data in columnar form, either space or comma-separated, perhaps with an initial set of column headers. Here is a typical example:
@@ -1028,7 +1027,7 @@ It is very common to find data in columnar form, either space or comma-separated The second parameter is a delimiter, by default spaces. ' ' is understood to mean 'any number of spaces', i.e. '%s+'. Any Lua string pattern can be used.
-The third parameter is a _data source_, by default standard input (@see pl.input.create_getter) It assumes that the data source has a `read` method which brings in the next line, i.e. it is a 'file-like' object. As a special case, a string will be split into its lines:
+The third parameter is a _data source_, by default standard input (@see input.create_getter) It assumes that the data source has a `read` method which brings in the next line, i.e. it is a 'file-like' object. As a special case, a string will be split into its lines:
> for x,y in input.fields(2,' ','10 20\n30 40\n') do print(x,y) end
10 20
@@ -1042,7 +1041,9 @@ Note the default behaviour for bad fields, which is to show the offending line n This behaviour of `input.fields` is appropriate for a script which you want to fail immediately with an appropriate _user_ error message if conversion fails. The fourth optional parameter is an options table: `{no_fail=true}` means that conversion is attempted but if it fails it just returns the string, rather as AWK would operate. You are then responsible for checking the type of the returned field. `{no_convert=true}` switches off conversion altogether and all fields are returned as strings.
-Sometimes it is useful to bring a whole dataset into memory, for operations such as extracting columns. Penlight provides a flexible reader specifically for reading this kind of data (@see pl.data.read). Given a file looking like this:
+<a id="data"/>
+
+Sometimes it is useful to bring a whole dataset into memory, for operations such as extracting columns. Penlight provides a flexible reader specifically for reading this kind of data (@see data.read). Given a file looking like this:
x,y
10,20
@@ -1128,7 +1129,7 @@ Data does not have to come from files, nor does it necessarily come from the lab end
-I've always been an admirer of the AWK programming language; with `filter` (@see pl.data.filter) you can get Lua programs which are just as compact:
+I've always been an admirer of the AWK programming language; with `filter` (@see data.filter) you can get Lua programs which are just as compact:
-- printxy.lua
require 'pl'
@@ -1179,7 +1180,7 @@ The `config` module provides a simple way to convert several kinds of configurat #acceptable ports
ports = 1002,1003,1004
-This can be easily brought in using `config.read` and the result shown using `pl.pretty.write` (@see pl.pretty.write)
+This can be easily brought in using `config.read` and the result shown using `pl.pretty.write` (@see pretty.write)
-- readconfig.lua
local config = require 'pl.config'
@@ -1581,7 +1582,7 @@ As a convenience, there is a function `seq.lines` which behaves just like `io.li seq.lines():take(10):upper():enum():map('..'):printall '\n'
-Note the method `upper`, which is not a `seq` function. if an unknown method is called, sequence wrappers apply that method to all the values in the sequence (this is implicit use of `mapmethod` - @see pl.seq.mapmethod.)
+Note the method `upper`, which is not a `seq` function. if an unknown method is called, sequence wrappers apply that method to all the values in the sequence (this is implicit use of `mapmethod` - @see seq.mapmethod)
It is straightforward to create custom sequences that can be used in this way. On Unix, `/dev/random` gives you an _endless_ sequence of random bytes, so we use `take` to limit the sequence, and then `map` to scale the result into the desired range. The key step is to use `seq` to wrap the iterator function:
@@ -1602,10 +1603,6 @@ It is straightforward to create custom sequences that can be used in this way. O dev_random():take(10):map('%',100):map('/',100):printall ','
-You may prefer this form, which uses the new 'string lambda' notation:
-
- dev_random():take(10):map '|n| (n % 100)/100':printall ','
-
Another Linux one-liner depends on the `/proc` filesystem and makes a list of all the currently running processes:
pids = seq(lfs.dir '/proc'):filter(stringx.isdigit):map(tonumber):copy()
@@ -1851,7 +1848,6 @@ There are some performance considerations to using placeholder expressions. Inst res[i] = tablex.map2(fn,first[i],second[i])
end
-Another option now supported by Penlight is the use of _string lambdas_. These use the 'short-form' for anonymous functions. So any Penlight function can accept strings like '|x,y| x+y', which is equivalent to `function(x,y) return x+y end`. Please note that these functions are effectively compiled in the global context and they cannot have references to locals. They do not suffer from the quoting problem, so that we can say '|f| f:read()', and they can be efficiently memoized.
## Additional Libraries
@@ -1989,7 +1985,7 @@ Finally, putting a ' $' at the end of a pattern means 'capture the rest of the l > res
{first='jan',rest='and a string',last='smit'}
-(@see pl.sip)
+(@see sip)
<a id="lapp"/>
diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 0000000..ddfb6ae --- /dev/null +++ b/docs/readme.md @@ -0,0 +1,9 @@ +The docgen.lua script generates the HTML documentation from penlight.md, +using a custom version of markdown.lua which does ToC generation. + +This script also finds @see references and resolves them. + +The API documentation requires LuaDoc - run from api folder. + + + |