library-mirrors/moonscript
1
0
Fork 0
mirror of https://github.com/leafo/moonscript.git synced 2024-10-05 05:34:19 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
063b50a38f
moonscript/docs/standard_lib.html

477 lines
18 KiB
HTML
Raw Normal View History

updated doc html
2011-12-12 08:49:06 +00:00
<!DOCTYPE HTML>
<html lang="en">
<head>
<!-- Autogenerated from on Mon Dec 12 00:44:42 2011 -->
<meta charset="UTF-8">
<title>MoonScript v0.2.0 - Standard Library</title>
<style type="text/css">body {
background: #F2F6FA;
font-family: sans-serif;
margin: 0px;
}
.header h1 {
background: #404142;
margin: 0px;
color: #F2F6FA;
padding-left: 10px;
text-shadow: -1px -1px 0px #2D2D2E;
}
a:link, a:visited {
color: #007BFF;
}
a:hover {
color: #409CFF;
}
a.current {
color: black;
font-weight: bold;
text-decoration: none;
}
p {
line-height: 140%;
font-size: 16px;
}
.main {
width: 960px;
padding-left: 1em;
}
h1, h2, h3 {
color: #4B4B4B;
text-shadow: 1px 1px 0px white;
padding-bottom: 2px;
margin: 0px;
margin-top: 1.5em;
}
.main h2 {
border-bottom: 1px solid #7E7979;
}
h1 {
margin: 0px;
margin-top: 1em;
padding: 10px 20px;
font-size: 40px;
background: #E1E4E8;
}
table, .bare-code, div > pre {
background: white;
border: 1px solid #999;
margin: 10px 0px;
-webkit-box-shadow: 2px 2px 8px rgba(0, 0, 0, 0.22);
-moz-box-shadow: 2px 2px 8px rgba(0, 0, 0, 0.22);
box-shadow: 2px 2px 8px rgba(0, 0, 0, 0.22);
}
div > pre {
padding: 8px;
}
.bare-code {
padding: 8px;
}
td > pre {
padding: 0px 8px;
line-height: 18px;
}
.code-border {
border-right: 1px dashed #ddd;
}
td {
vertical-align: top;
}
.code-header {
background: #ABA9AB;
background-image: -webkit-gradient(
linear,
left bottom,
left top,
color-stop(0, rgb(148,146,148)),
color-stop(1, rgb(214,214,214))
);
background-image: -moz-linear-gradient(
center bottom,
rgb(148,146,148) 0%,
rgb(214,214,214) 100%
);
}
.code-header td {
color: white;
text-shadow: 0px -1px 0px #555;
font-size: 12px;
font-weight: bold;
padding: 2px 6px;
border-top: 1px solid #eee;
border-bottom: 1px solid #666;
}
p > code , li > code {
background: #E1E4E8;
border-radius: 4px;
padding: 0px 4px;
}
.l_string {
color: #A16D43;
/*
background: #F9D7BB;
background: #FFE9D6;
*/
}
.l_symbol, .l_bold_symbol {
color: #B50C0C;
}
.l_bold_symbol {
/* font-weight: bold; */
}
.l_keyword {
color: #0CB56C;
}
.l_comment {
color: #D74DBF;
}
.l_fn_symbol {
color: #8E4681;
}
.l_proper, .l_self_var, .l_special {
color: #30A0BD;
}
.l_proper {
font-weight: bold;
}
.l_builtins, .nv {
color: #707A34;
}
.l_number {
color: #4958C3;
}
.footer {
color: #747678;
font-size: 80%;
padding: 8px;
}
.clearfix:after {
content: ".";
display: block;
clear: both;
visibility: hidden;
line-height: 0;
height: 0;
}
.column {
float: left;
}
.index {
margin-left: 20px;
}
h3 > code {
display: block;
background: #C3DFFA;
padding: 1em;
color: #0075ea;
text-shadow: 1px 1px 0px #e8f1fa;
border-bottom: 1px solid #b1cae3;
}
</style>
</head><body>
<div class="header">
<h1>MoonScript v0.2.0 - Standard Library</h1>
</div>
<div class="clearfix index">
<div class="column">
<h3>On This Page</h3>
<ul>
<li><a href="#moonscript_standard_library">MoonScript Standard Library</a></li>
<ul>
<li><a href="#printing_functions">Printing Functions</a></li>
<ul>
<li><a href="#parg"><code>p(arg)</code></a></li>
</ul>
<li><a href="#table_functions">Table Functions</a></li>
<ul>
<li><a href="#run_with_scopefn_scope_args"><code>run_with_scope(fn, scope, [args...])</code></a></li>
<li><a href="#defaultbltbl_fn"><code>defaultbl([tbl,] fn)</code></a></li>
<li><a href="#extendarg1_arg2_rest"><code>extend(arg1, arg2, [rest...])</code></a></li>
<li><a href="#copytbl"><code>copy(tbl)</code></a></li>
</ul>
<li><a href="#classobject_functions">Class/Object Functions</a></li>
<ul>
<li><a href="#is_objectvalue"><code>is_object(value)</code></a></li>
<li><a href="#typevalue"><code>type(value)</code></a></li>
<li><a href="#bind_methodsobj"><code>bind_methods(obj)</code></a></li>
<li><a href="#mixinobj_class_args"><code>mixin(obj, class, [args...])</code></a></li>
<li><a href="#mixin_objectobj_other_obj_method_names"><code>mixin_object(obj, other_obj, method_names)</code></a></li>
<li><a href="#mixin_tablea_b_names"><code>mixin_table(a, b, [names])</code></a></li>
</ul>
<li><a href="#misc_functions">Misc Functions</a></li>
<ul>
<li><a href="#folditems_fn"><code>fold(items, fn)</code></a></li>
</ul>
<li><a href="#debug_functions">Debug Functions</a></li>
<ul>
<li><a href="#debugupvaluefn_key_value"><code>debug.upvalue(fn, key[, value])</code></a></li>
</ul> </ul>
</ul>
</div>
<div class="column">
<h3>All Pages</h3>
<ul>
<li><a href="./reference_manual.html">Language Guide</a></li>
<li><a href="./standard_lib.html" class="current">Standard Library</a></li>
</ul>
</div>
</div>
<div class="main">
<p>The MoonScript installation comes with a small kernel of functions that can be
used to perform various common things.</p>
<p>The entire library is currently contained in a single object. We can bring this
<code>moon</code> object into scope by requiring <code>"moon"</code>.</p>
<pre><code id="moon-1" class="moon-code"><span class="l_builtins">require</span> <span class="l_string">"moon"</span>
<span class="l_comment">-- `moon.p` is the debug printer
</span><span class="l_atom">moon</span><span class="l_bold_symbol">.</span><span class="l_atom">p</span> <span class="l_fn_symbol">{</span> <span class="l_table_key">hello</span><span class="l_bold_symbol">:</span> <span class="l_string">"world"</span> <span class="l_fn_symbol">}</span></code>
</pre>
<p>If you prefer to just inject all of the functions into the current scope, you
can require <code>"moon.all"</code> instead. The following has the same effect as above:</p>
<pre><code id="moon-2" class="moon-code"><span class="l_builtins">require</span> <span class="l_string">"moon.all"</span>
<span class="l_atom">p</span> <span class="l_fn_symbol">{</span> <span class="l_table_key">hello</span><span class="l_bold_symbol">:</span> <span class="l_string">"world"</span> <span class="l_fn_symbol">}</span></code>
</pre>
<p>All of the functions are compatible with Lua in addition to MoonScript, but
some of them only make sense in the context of MoonScript.</p>
</div><h1><a name="moonscript_standard_library"></a>MoonScript Standard Library</h1><div class="main">
<p>This is an overview of all the included functions.
All of the examples assume that the standard library has been included with
<code>require "moon.all"</code>.</p>
<h2><a name="printing_functions"></a>Printing Functions</h2>
<h3><a name="parg"></a><code>p(arg)</code></h3>
<p>Prints a formatted version of an object. Excellent for inspecting the contents
of a table.</p>
<h2><a name="table_functions"></a>Table Functions</h2>
<h3><a name="run_with_scopefn_scope_args"></a><code>run_with_scope(fn, scope, [args...])</code></h3>
<p>Mutates the environment of function <code>fn</code> and runs the function with any extra
arguments in <code>args...</code>. Returns the result of the function.</p>
<p>The environment of the function is set to a new table whose metatable will use
<code>scope</code> to look up values. <code>scope</code> must be a table. If <code>scope</code> does not have an
entry for a value, it will fall back on the original environment.</p>
<pre><code id="moon-3" class="moon-code"><span class="l_atom">my_env</span> <span class="l_symbol">=</span> <span class="l_fn_symbol">{</span>
<span class="l_table_key">secret_function</span><span class="l_bold_symbol">:</span> <span class="l_fn_symbol">-&gt;</span> <span class="l_builtins">print</span> <span class="l_string">"shhh this is secret"</span>
<span class="l_table_key">say_hi</span><span class="l_bold_symbol">:</span> <span class="l_fn_symbol">-&gt;</span> <span class="l_builtins">print</span> <span class="l_string">"hi there!"</span>
<span class="l_fn_symbol">}</span>
<span class="l_atom">say_hi</span> <span class="l_symbol">=</span> <span class="l_fn_symbol">-&gt;</span> <span class="l_builtins">print</span> <span class="l_string">"I am a closure"</span>
<span class="l_atom">fn</span> <span class="l_symbol">=</span> <span class="l_fn_symbol">-&gt;</span>
<span class="l_atom">secret_function</span><span class="l_symbol">!</span>
<span class="l_atom">say_hi</span><span class="l_symbol">!</span>
<span class="l_atom">run_with_scope</span> <span class="l_atom">fn</span>, <span class="l_atom">my_env</span></code>
</pre>
<p>Note that any closure values will always take precedence against global name
lookups in the environment. In the example above, the <code>say_hi</code> in the
environment has been shadowed by the local variable <code>say_hi</code>.</p>
<h3><a name="defaultbltbl_fn"></a><code>defaultbl([tbl,] fn)</code></h3>
<p>Sets the <code>__index</code> of table <code>tbl</code> to use the function <code>fn</code> to generate table
values when a missing key is looked up.</p>
<h3><a name="extendarg1_arg2_rest"></a><code>extend(arg1, arg2, [rest...])</code></h3>
<p>Chains together a series of tables by their metatable’s <code>__index</code> property.
Overwrites the metatable of all objects exept for the last with a new table
whose <code>__index</code> is set to the next table.</p>
<p>Returns the first argument.</p>
<pre><code id="moon-4" class="moon-code"><span class="l_atom">a</span> <span class="l_symbol">=</span> <span class="l_fn_symbol">{</span> <span class="l_table_key">hello</span><span class="l_bold_symbol">:</span> <span class="l_string">"world"</span> <span class="l_fn_symbol">}</span>
<span class="l_atom">b</span> <span class="l_symbol">=</span> <span class="l_fn_symbol">{</span> <span class="l_table_key">okay</span><span class="l_bold_symbol">:</span> <span class="l_string">"sure"</span> <span class="l_fn_symbol">}</span>
<span class="l_atom">extend</span> <span class="l_atom">a</span>, <span class="l_atom">b</span>
<span class="l_builtins">print</span> <span class="l_atom">a</span><span class="l_bold_symbol">.</span><span class="l_atom">okay</span></code>
</pre>
<h3><a name="copytbl"></a><code>copy(tbl)</code></h3>
<p>Creates a shallow copy of a table, equivalent to:</p>
<pre><code id="moon-5" class="moon-code"><span class="l_atom">copy</span> <span class="l_symbol">=</span> (<span class="l_atom">arg</span>) <span class="l_fn_symbol">-&gt;</span> <span class="l_fn_symbol">{</span><span class="l_atom">k</span>,<span class="l_atom">v</span> <span class="l_keyword">for</span> <span class="l_atom">k</span>,<span class="l_atom">v</span> <span class="l_keyword">in</span> <span class="l_builtins">pairs</span> <span class="l_self">self</span><span class="l_fn_symbol">}</span></code>
</pre>
<h2><a name="classobject_functions"></a>Class/Object Functions</h2>
<h3><a name="is_objectvalue"></a><code>is_object(value)</code></h3>
<p>Returns true if <code>value</code> is an instance of a MoonScript class, false otherwise.</p>
<h3><a name="typevalue"></a><code>type(value)</code></h3>
<p>If <code>value</code> is an instance of a MoonScript class, then return it’s class object.
Otherwise, return the result of calling Lua’s type method.</p>
<pre><code id="moon-6" class="moon-code"><span class="l_keyword">class</span> <span class="l_proper">MyClass</span>
<span class="l_special">nil</span>
<span class="l_atom">x</span> <span class="l_symbol">=</span> <span class="l_proper">MyClass</span><span class="l_symbol">!</span>
<span class="l_builtins">assert</span> <span class="l_atom">type</span>(<span class="l_atom">x</span>) <span class="l_symbol">=</span><span class="l_symbol">=</span> <span class="l_proper">MyClass</span></code>
</pre>
<h3><a name="bind_methodsobj"></a><code>bind_methods(obj)</code></h3>
<p>Takes an instance of an object, returns a proxy to the object whose methods can
be called without providing self as the first argument.</p>
<pre><code id="moon-7" class="moon-code"><span class="l_atom">obj</span> <span class="l_symbol">=</span> <span class="l_proper">SomeClass</span><span class="l_symbol">!</span>
<span class="l_atom">bound_obj</span> <span class="l_symbol">=</span> <span class="l_atom">bind_methods</span> <span class="l_atom">obj</span>
<span class="l_comment">-- following have the same effect
</span><span class="l_atom">obj</span><span class="l_symbol">\</span><span class="l_atom">hello</span><span class="l_symbol">!</span>
<span class="l_atom">bound_obj</span><span class="l_bold_symbol">.</span><span class="l_atom">hello</span><span class="l_symbol">!</span></code>
</pre>
<p>It lazily creates and stores in the proxy table the bound methods when they
are first called.</p>
<h3><a name="mixinobj_class_args"></a><code>mixin(obj, class, [args...])</code></h3>
<p>Copies the methods of a class <code>cls</code> into the table <code>obj</code>, then calls the
constructor of the class with the <code>obj</code> as the receiver.</p>
<p>In this example we add the functionality of <code>First</code> to an instance of <code>Second</code>
without ever instancing <code>First</code>.</p>
<pre><code id="moon-8" class="moon-code"><span class="l_keyword">class</span> <span class="l_proper">First</span>
<span class="l_table_key">new</span><span class="l_bold_symbol">:</span> (<span class="l_self_var">@var</span>) <span class="l_fn_symbol">=&gt;</span>
<span class="l_table_key">show_var</span><span class="l_bold_symbol">:</span> <span class="l_fn_symbol">=&gt;</span> <span class="l_builtins">print</span> <span class="l_string">"var is:"</span>, <span class="l_self_var">@var</span>
<span class="l_keyword">class</span> <span class="l_proper">Second</span>
<span class="l_table_key">new</span><span class="l_bold_symbol">:</span> <span class="l_fn_symbol">=&gt;</span>
<span class="l_atom">mixin</span> <span class="l_self">self</span>, <span class="l_proper">First</span>, <span class="l_string">"hi"</span>
<span class="l_atom">a</span> <span class="l_symbol">=</span> <span class="l_proper">Second</span><span class="l_symbol">!</span>
<span class="l_atom">a</span><span class="l_symbol">\</span><span class="l_atom">show_var</span><span class="l_symbol">!</span></code>
</pre>
<p>Be weary of name collisions when mixing in other classes, names will be
overwritten.</p>
<h3><a name="mixin_objectobj_other_obj_method_names"></a><code>mixin_object(obj, other_obj, method_names)</code></h3>
<p>Inserts into <code>obj</code> methods from <code>other_obj</code> whose names are listen in
<code>method_names</code>. The inserted methods are bound methods that will run with
<code>other_obj</code> as the receiver.</p>
<pre><code id="moon-9" class="moon-code"><span class="l_keyword">class</span> <span class="l_proper">List</span>
<span class="l_table_key">add</span><span class="l_bold_symbol">:</span> (<span class="l_atom">item</span>) <span class="l_fn_symbol">=&gt;</span> <span class="l_builtins">print</span> <span class="l_string">"adding to"</span>, <span class="l_self">self</span>
<span class="l_table_key">remove</span><span class="l_bold_symbol">:</span> (<span class="l_atom">item</span>) <span class="l_fn_symbol">=&gt;</span> <span class="l_builtins">print</span> <span class="l_string">"removing from"</span>, <span class="l_self">self</span>
<span class="l_keyword">class</span> <span class="l_proper">Encapsulation</span>
<span class="l_table_key">new</span><span class="l_bold_symbol">:</span> <span class="l_fn_symbol">=&gt;</span>
<span class="l_self_var">@list</span> <span class="l_symbol">=</span> <span class="l_proper">List</span><span class="l_symbol">!</span>
<span class="l_atom">mixin_object</span> <span class="l_self">self</span>, <span class="l_self_var">@list</span>, <span class="l_fn_symbol">{</span><span class="l_string">"add"</span>, <span class="l_string">"remove"</span><span class="l_fn_symbol">}</span>
<span class="l_atom">e</span> <span class="l_symbol">=</span> <span class="l_proper">Encapsulation</span><span class="l_symbol">!</span>
<span class="l_atom">e</span><span class="l_bold_symbol">.</span><span class="l_atom">add</span> <span class="l_string">"something"</span></code>
</pre>
<h3><a name="mixin_tablea_b_names"></a><code>mixin_table(a, b, [names])</code></h3>
<p>Copies the elements of table <code>b</code> into table <code>a</code>. If names is provided, then
only those names are copied.</p>
<h2><a name="misc_functions"></a>Misc Functions</h2>
<h3><a name="folditems_fn"></a><code>fold(items, fn)</code></h3>
<p>Calls function <code>fn</code> repeatedly with the accumulated value and the current value
by iterating over <code>items</code>. The accumulated value is the result of the last call
to <code>fn</code>, or, in the base case, the first value. The current value is the value
being iterated over starting with the second item.</p>
<p><code>items</code> is a normal array table.</p>
<p>For example, to sum all numbers in a list:</p>
<pre><code id="moon-10" class="moon-code"><span class="l_atom">numbers</span> <span class="l_symbol">=</span> <span class="l_fn_symbol">{</span><span class="l_number">4</span>,<span class="l_number">3</span>,<span class="l_number">5</span>,<span class="l_number">6</span>,<span class="l_number">7</span>,<span class="l_number">2</span>,<span class="l_number">3</span><span class="l_fn_symbol">}</span>
<span class="l_atom">sum</span> <span class="l_symbol">=</span> <span class="l_atom">fold</span> <span class="l_atom">numbers</span>, (<span class="l_atom">a</span>,<span class="l_atom">b</span>) <span class="l_fn_symbol">-&gt;</span> <span class="l_atom">a</span> + <span class="l_atom">b</span></code>
</pre>
<h2><a name="debug_functions"></a>Debug Functions</h2>
<h3><a name="debugupvaluefn_key_value"></a><code>debug.upvalue(fn, key[, value])</code></h3>
<p>Gets or sets the value of an upvalue for a function by name.</p>
</div>
<div class="footer">Generated on Mon Dec 12 00:44:42 2011; MoonScript v0.2.0</div>
</body>
</html>
Reference in New Issue Copy Permalink