Ported half of the documentation

This commit is contained in:
Matthias Richter 2010-08-12 17:43:47 +02:00
parent 65cc5763af
commit f42198ce27

View File

@ -4,9 +4,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>vrld/hump @ GitHub</title>
<title>hump - L&Ouml;VE Helper Utilities for More Productivity</title>
<style type="text/css">
body {
margin-top: 1.0em;
@ -16,56 +14,401 @@
}
#container {
margin: 0 auto;
width: 700px;
width: 800px;
}
h1 { font-size: 3.8em; color: #080303; margin-bottom: 3px; }
h1 { font-size: 3.8em; color: #080303; margin-bottom: 10px; border-bottom: 2px solid #080303; }
h1 .small { font-size: 0.4em; }
h1 a { text-decoration: none }
h2 { font-size: 1.5em; color: #080303; }
h3 { text-align: center; color: #080303; }
h2 { font-size: 1.5em; color: #080303; border-top: 1px solid #a0a0a0; }
h3 { color: #080303; margin-bottom: 1em; background: #eee; margin-top: 3em; }
h4 { color: #080303; margin-top: 2em; }
a { color: #080303; }
.description { font-size: 1.2em; margin-bottom: 30px; margin-top: 30px; font-style: italic;}
.download { float: right; }
pre { background: #000; color: #fff; padding: 15px;}
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.footer { text-align:center; padding-top:30px; font-style: italic; }
</style>
ul.nav { display:inline; margin-left: 0; padding-left: 0; }
ul.nav li { display:inline; margin-right: 1em; }
a.top { font-size: .2em; margin-left: 1em; float: right; }
.doc { padding-left: 1em; margin-bottom: 1em; border-left: 1px dotted #aaa; }
.function { display:block; font-weight:bold; font-family: fixed; background: #f9f9f9; border:1px solid #ddd; margin-left: -1em; }
.functionlist { border-left: 1px dotted #aaa; margin: -.6em 0 0 2em; }
.functionlist a { text-decoration: none; font-weight:bold; color: #506060; }
.functionlist a:hover { color: black; }
.doc table { margin-top: 5px; }
th { text-align: left; font-weight: normal; font-style: italic; text-decoration: underline; }
td { padding-left: 1em; }
.doc td em { font-size: .8em; font-weight:bold; font-style:normal; padding-right: .6em;}
.doc pre, code { color: black; padding: 0; font-family: fixed; border: 1px solid #ddd; background: #e7ecec; }
</style>
</head>
<body>
<a href="http://github.com/vrld/hump"><img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
<a name="top"></a>
<div id="container">
<div class="download">
<a href="http://github.com/vrld/hump/zipball/master">
<img border="0" width="90" src="http://github.com/images/modules/download/zip.png"></a>
<a href="http://github.com/vrld/hump/tarball/master">
<img border="0" width="90" src="http://github.com/images/modules/download/tar.png"></a>
</div>
<h1><a href="http://github.com/vrld/hump">hump</a>
<span class="small">by <a href="http://github.com/vrld">vrld</a></span></h1>
<span class="small"> Helper Utilities for More Productivity</span></h1>
<div class="description">
LÖVE Helper Utilities for Massive Progression
<ul class="nav">
<li><a href="#intro">Introduction</a></li>
<li><a href="#doc">Documenation</a></li>
<li><a href="#license">License</a></li>
<li><a href="#download">Download</a></li>
</ul>
<a name="intro"></a>
<h2>Introduction<a class="top" href="#top">^ top</a></h2>
<p><em>Helper Utilities for a Multitude of Problems</em> is a set of lightweight helpers
for the excellent <a href="http://love2d.org/">L&Ouml;VE</a> Engine.</p>
<p>It currently features
<ul>
<li><em>vector.lua</em>: a mature vector type,</li>
<li><em>class.lua</em>: a simple and easy class system with function inheritance,</li>
<li><em>camera.lua</em>: a translate-, zoom- and rotatable camera and</li>
<li><em>gamestate.lua</em>: a gamestate system.</li>
</ul></p>
<p><em>hump</em> differs from other libraries in that every component is independent of the
remaining ones (apart from camera.lua, which depends on the vector type).
<em>hump</em>'s footprint is very small and thus should fit nicely into your projects.</p>
<a name="doc"></a>
<h2>Documentation<a class="top" href="#top">^ top</a></h2>
Below is the documentation of the various modules. You can directly jump to a
module by clicking these:
<ul>
<li><a href="#vector.lua">vector.lua</a></li>
<li><a href="#class.lua">class.lua</a></li>
<li><a href="#camera.lua">camera.lua</a></li>
<li><a href="#gamestate.lua">gamestate.lua</a></li>
</ul>
<div class="module">
<a name="vector.lua"></a>
<h3>vector.lua<a class="top" href="#doc">^ top</a></h3>
<p>A vector class implementing everything you want to do with vectors, and some more.</p>
<p>Overview (click item for more details):
<table class="functionlist">
<tr><td><a href="#vector.lua-vector">vector(x,y)</a></td><td>constructor</td></tr>
<tr><td><a href="#vector.lua-isvector">isvector(v)</a></td><td>type check</td></tr>
<tr><td><a href="#vector.lua-clone">Vector:clone()</a></td><td>deep copy</td></tr>
<tr><td><a href="#vector.lua-unpack">Vector:unpack()</a></td><td>element unfolding</td></tr>
<tr><td><a href="#vector.lua-operators">Operators</a></td><td>Arithmetics and ordering</td></tr>
<tr><td><a href="#vector.lua-permul">vector:permul(other)</a></td><td>per-element multiplication</td></tr>
<tr><td><a href="#vector.lua-len">vector:len()</a></td><td>vector length</td></tr>
<tr><td><a href="#vector.lua-len2">vector:len2()</a></td><td>squared vector length</td></tr>
<tr><td><a href="#vector.lua-dist">vector:dist(other)</a></td><td>distance to vector</td></tr>
<tr><td><a href="#vector.lua-normalized">vector:normalized()</a></td><td>normalize vector</td></tr>
<tr><td><a href="#vector.lua-normalize_inplace">vector:normalize_inplace()</a></td><td>normalize vector in-place</td></tr>
<tr><td><a href="#vector.lua-rotated">Vector:rotated(phi)</a></td><td>rotate vector</td></tr>
<tr><td><a href="#vector.lua-rotate_inplace">Vector:rotate_inplace(phi)</a></td><td>rotate vector in-place</td></tr>
</table></p>
<a name="vector.lua-vector"></a>
<div class="doc"><span class="function">function vector(x,y)<a class="top" href="#vector.lua">^ top</a></span>
Creates a new vector. Element access with <code>v.x</code> and <code>v.y</code>.
<table>
<tr><th>Parameters:</th><td><em>[number]</em><code>x</code>:</td><td>x coordinate</td></tr>
<tr><td> </td><td><em>[number]</em><code>y</code>:</td><td>y coordinate</td></tr>
<tr><th>Returns:</th><td colspan="2">the vector</td></tr>
</table>
</div>
<h2>Authors</h2>
<p>vrld</p>
<a name="vector.lua-isvector"></a>
<div class="doc"><span class="function">function isvector(v)<a class="top" href="#vector.lua">^ top</a></span>
Tests for vector type.
<table>
<tr><th>Parameters:</th><td><code>v</code></td><td>variable to test</td></tr>
<tr><th>Returns:</th><td colspan="2"><code>true</code> if <code>v</code> is a vector</td></tr>
</table>
</div>
<a name="vector.lua-clone"></a>
<div class="doc"><span class="function">function vector:clone()<a class="top" href="#vector.lua">^ top</a></span>
Clones a vector. Use when you do not want to create references.
<table>
<tr><th>Returns:</th><td colspan="2">New vector with the same coordinates.</td></tr>
</table>
</div>
<a name="vector.lua-unpack"></a>
<div class="doc"><span class="function">function vector:unpack()<a class="top" href="#vector.lua">^ top</a></span>
Unpacks the vector.
<table>
<tr><th>Returns:</th><td colspan="2">the coordinate tuple <code>x, y</code></td></tr>
<tr><th colspan="3">Example:</th></tr>
<tr><td colspan="3"><pre>v = vector(1,2)
print(v:unpack()) -- prints "1 2"</pre></td></tr>
</table>
</div>
<a name="vector.lua-operators"></a>
<div class="doc"><span class="function">Operators<a class="top" href="#vector.lua">^ top</a></span>
<p>Arithmetic (<code>+</code>, <code>-</code>, <code>*</code>, <code>/</code>) and
comparative operators (<code>==</code>, <code>&lt;=</code>, <code>&lt;</code>) are defined:</p>
<ul>
<li><code>+</code> and <code>-</code> <em>only</em> work on vectors. <code>-</code> is also
the unary minus (e.g. <code>print(-vector(1,2)) -- prints (-1,-2)</code>)</li>
<li><code>a * b</code> works on vectors and numbers:<ul>
<li>If <code>a</code> is a number and <code>b</code> is a vector (or vice versa),
the result the scalar multiplication.</li>
<li>If <code>a</code> and <code>b</code> both are vectors, then the result is the
<em>dot product</em>.</li></ul></li>
<li><code>a / b</code> is only defined for <code>a</code> being a vector and <code>b</code>
being a number. Same as <code>a * 1/b</code>.</li>
</ul>
<p><code>&lt;=</code> and <code>&lt;</code> sort lexically, i.e. <code>a &lt; b</code>
is true if it holds: <code>a.x &lt; b.x</code> or <code>a.y &lt; b.y</code> if
<code>a.x == b.x</code></p>
</div>
<a name="vector.lua-permul"></a>
<div class="doc"><span class="function">function vector:permul(other)<a class="top" href="#vector.lua">^ top</a></span>
Perform element-wise multiplication.
</div>
<a name="vector.lua-len"></a>
<div class="doc"><span class="function">function vector:len()<a class="top" href="#vector.lua">^ top</a></span>
Get length of vector.
</div>
<a name="vector.lua-len2"></a>
<div class="doc"><span class="function">function vector:len2()<a class="top" href="#vector.lua">^ top</a></span>
Get squared length.
</div>
<a name="vector.lua-dist"></a>
<div class="doc"><span class="function">function vector:dist(other)<a class="top" href="#vector.lua">^ top</a></span>
Get distance to other vector.
<table><tr><th>Example:</th></tr>
<tr><td><pre>a,b = vector(0,1), vector(1,0)
print(a:dist(b)) -- prints 1.4142135623731</pre></td></tr>
</table>
</div>
<a name="vector.lua-normalized"></a>
<div class="doc"><span class="function">function vector:normalized()<a class="top" href="#vector.lua">^ top</a></span>
Get normalized vector. The original vector remains unchanged.
</div>
<a name="vector.lua-normalize_inplace"></a>
<div class="doc"><span class="function">function vector:normalize_inplace()<a class="top" href="#vector.lua">^ top</a></span>
Normalize vector and return it.
<p><strong>Warning:</strong> This will change the state of all references to this vector.</p>
</div>
<a name="vector.lua-rotated"></a>
<div class="doc"><span class="function">function vector:rotated(phi)<a class="top" href="#vector.lua">^ top</a></span>
Get rotated vector. The original vector remains unchanged.
<table>
<tr><th>Parameters:</th><td><em>[number]</em><code>phi</code>:</td><td>Rotation angle in radians.</td></tr>
</table>
</div>
<a name="vector.lua-rotate_inplace"></a>
<div class="doc"><span class="function">function vector:rotate_inplace(phi)<a class="top" href="#vector.lua">^ top</a></span>
Rotate the vector and return it.
<p><strong>Warning:</strong> This will change the state of all references to this vector.</p>
</div>
</div>
<h2>Download</h2>
<p>
You can download this project in either
<div class="module">
<a name="class.lua"></a>
<h3>class.lua<a class="top" href="#doc">^ top</a></h3>
<p>class.lua provides a simple and easy to use class system. Albeit it's
limitations, class.lua offers multiple inheritance and minimal
reflection capabilities. Note that only methods will be inherited
and runtime changes of a superclass won't affect subclasses.</p>
<p>The module only consists of three functions:
<table class="functionlist">
<tr><td><a href="#class.lua-Class">Class(constructor)</a></td><td>define class</td></tr>
<tr><td><a href="#class.lua-Class2">Class{name = name, constructor}</a></td><td>define named class</td></tr>
<tr><td><a href="#class.lua-Interface">Interface(name)</a></td><td>define interface</td></tr>
<tr><td><a href="#class.lua-Inherit">Inherit(class, super, ...)</a></td><td>subclassing</td></tr>
</table></p>
<p>For an example, <a href="#class.lua-Example">see below</a>. Also be sure to read the
<a href="#class.lua-Warning">warning</a> regarding metamethods.</p>
<a name="class.lua-Class"></a>
<div class="doc"><span class="function">function Class(constructor)<a class="top" href="#class.lua">^ top</a></span>
Creates a new unnamed class.
<table>
<tr><th>Parameters:</th><td><em>[optional function]</em><code>constructor</code></td>
<td>A function used to construct the class. The first parameter of this function
is the object, the others are parameters given upon construction.</td></tr>
<tr><th>Returns:</th><td colspan="2">the new class</td></tr>
<tr><th colspan="3">Example</th></tr>
<tr><td colspan="3"><pre>Feline = Class(function(self, size, weight)
self.size = size self.weight = weight
end)
function Feline:stats()
return string.format("size: %.02f, weight %.02f", self.size, self.weight)
end
garfield = Feline(.7, 45)
felix = Feline(.8, 12)
print("Garfield: " .. garfield:stats(), "Felix: " .. felix:stats())</pre></td></tr>
</table>
</div>
<a name="class.lua-Class2"></a>
<div class="doc"><span class="function">function Class{name = name, constructor}<a class="top" href="#class.lua">^ top</a></span>
Create a named class, i.e. define a <code>__tostring</code> metamethod. Parameters are the same as above.
Great for debugging. Both <code>name</code> and <code>constructor</code> can be omitted (but why would you want to?)
<table><tr><th>Example:</th></tr>
<tr><td><pre>Feline = Class{name = "Feline", function(self, size, weight)
self.size = size self.weight = weight
end}
print(Feline) -- prints 'Feline'</pre></td></tr>
</table>
</div>
<a name="class.lua-Interface"></a>
<div class="doc"><span class="function">function Interface(name)<a class="top" href="#class.lua">^ top</a></span>
Shortcut to <code>Class{name = name}</code>, i.e. a possibly named class without constructor.
</div>
<a name="class.lua-Interface"></a>
<div class="doc"><span class="function">function Inherit(class, super, ...)<a class="top" href="#class.lua">^ top</a></span>
Add functions of <code>super</code> to <code>class</code>. Multiple interfaces can be defined.
<p><code>super</code>'s constructor can be accessed via super.construct(self). See example below.</p>
</div>
<a name="class.lua-Example"></a>
<h4>Example usage</h4>
<div class="doc"><span class="function">Everybody loves cats!<a class="top" href="#class.lua">^ top</a></span>
<pre>Feline = Class{name = "Feline", function(self, size, weight)
self.size = size self.weight = weight
end}
function Feline:stats()
return string.format("size: %.02f, weight %.02f", self.size, self.weight)
end
function Feline:speak() print("meow") end
Cat = Class{name = "Cat", function(self, name, size, weight)
Feline.construct(self, size, weight)
self.name = name
end}
Inherit(Cat, Feline)
function Cat:stats()
return string.format("name: %s, %s", self.name, Feline.stats(self))
end
Tiger = Class{name = "tiger", function(self, size, weight)
Feline.construct(self, size, weight)
end}
Inherit(Tiger, Feline)
function Tiger:speak() print("ROAR!") end
felix = Cat("Felix", .8, 12)
hobbes = Tiger(2.2, 68)
print(felix:stats(), hobbes:stats())
felix:speak()
hobbes:speak()</pre>
</div>
<a name="class.lua-Warning"></a>
<h4>Warning</h4>
<div class="doc"><span class="function">Nothing is perfect<a class="top" href="#class.lua">^ top</a></span>
<p>Be careful when using metamethods like <code>__add</code> or <code>__mul</code>:
When subclass inherits those methods from a superclass, but does not overwrite
them, the result of the operation may be of the type superclass. Consider the following:</p>
<pre>A = Class(function(self, x) self.x = x end)
function A:__add(other) return A(self.x + other.x) end
function A:print() print("A:", self.x) end
B = Class(function(self, x, y) A.construct(self, x) self.y = y end)
Inherit(B, A)
function B:print() print("B:", self.x, self.y) end
function B:foo() print("foo") end
one, two = B(1,2), B(3,4)
result = one + two
result:print() -- prints "A: 4"
result:foo() -- error: method does not exist</pre>
</div>
</div>
<div class="module">
<a name="camera.lua"></a>
<h3>camera.lua<a class="top" href="#doc">^ top</a></h3>
<em>Depends on <a href="#vector.lua">vector.lua</a></em>
<p>Camera object to display only a partial region of the game world. The region
can be zoomed and rotated. You can transform camera coordinates to world coordinated
(e.g. get the location of the mouse in the game world). It is possible to have
more than one camera per game.</p>
</div>
<div class="module">
<a name="gamestate.lua"></a>
<h3>gamestate.lua<a class="top" href="#doc">^ top</a></h3>
</div>
<a name="license"></a>
<h2>License<a class="top" href="#top">^ top</a></h2>
<p>Yay, <em>free software</em>:</p>
<blockquote><p>Copyright (c) 2010 Matthias Richter</p>
<p>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:</p>
<p>The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.</p>
<p>Except as contained in this notice, the name(s) of the above copyright holders
shall not be used in advertising or otherwise to promote the sale, use or
other dealings in this Software without prior written authorization.</p>
<p>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.</p></blockquote>
<a name="download"></a>
<h2>Download<a class="top" href="#top">^ top</a></h2>
<p>You can download this project in either
<a href="http://github.com/vrld/hump/zipball/master">zip</a> or
<a href="http://github.com/vrld/hump/tarball/master">tar</a> formats.
</p>
<p>You can also clone the project with <a href="http://git-scm.com">Git</a>
by running:
<pre>$ git clone git://github.com/vrld/hump</pre>
</p>
<a href="http://github.com/vrld/hump/tarball/master">tar</a> formats.</p>
<p>You can also clone the project with <a href="http://git-scm.com">Git</a> by running:
<pre>$ git clone git://github.com/vrld/hump</pre></p>
<div class="footer">
get the source code on GitHub : <a href="http://github.com/vrld/hump">vrld/hump</a>