Permalink
Browse files

Documentation site.

  • Loading branch information...
1 parent a43a089 commit 2563edeee2f4a11e3d19e0c2d08c70fabea35c97 @beastaugh committed Jan 4, 2011
Showing with 526 additions and 3 deletions.
  1. +5 −0 .gitignore
  2. +5 −3 README.md
  3. +262 −0 site/index.md
  4. +33 −0 site/license.md
  5. +42 −0 site/templates/default.html
  6. +166 −0 site/udon.css
  7. +13 −0 site/udon.hs
View
5 .gitignore
@@ -1 +1,6 @@
pkg
+site/_site
+site/_cache
+site/udon
+site/*.hi
+site/*.o
View
8 README.md
@@ -7,9 +7,11 @@ which provide access to these fundamentals in a more-or-less functional style.
[Ojay][ojay]'s core extensions, Oliver Steele's [Functional][functionaljs] and
Jeremy Ashkenas' [Underscore][underscore] are all good examples.
-Udon is cast in a similar mould to the above. It aims to provide basic support
-for functional programming in JavaScript, initially by porting some elements of
-Haskell's `Data.List` library.
+[Udon][udon] is cast in a similar mould to the above. It aims to provide basic
+support for functional programming in JavaScript, initially by porting some
+elements of Haskell's `Data.List` library.
+
+[udon]: http://extralogical.net/projects/udon/
Function operations
View
262 site/index.md
@@ -0,0 +1,262 @@
+---
+title: Udon | Practical functional programming in JavaScript
+---
+
+[Udon][udon] is a library to provide basic support for functional programming
+idioms in JavaScript.
+
+
+Downloads
+---------
+
+Current version: **1.0.0**.
+
+* [Development version](./downloads/udon-1.0.0.js)
+* [Production version](./downloads/udon-1.0.0-min.js) 8.4kb packed, 2.4kb
+ gzipped
+
+
+Programming with Udon
+---------------------
+
+All the functions in this library are namespaced by the `Udon` object, so a
+reference in the documentation to e.g. `map` should be read as `Udon.map`. This
+means it should play nicely with other JavaScript libraries.
+
+
+API summary
+-----------
+
+* [Function operations](#api-function-operations)
+ - [`curry`](#api-curry)
+ - [`ncurry`](#api-ncurry)
+ - [`compose`](#api-compose)
+* [List operations](#api-list-operations)
+ - [`foldl`](#api-foldl)
+ - [`foldr`](#api-foldr)
+ - [`map`](#api-map)
+ - [`filter`](#api-filter)
+ - [`any`](#api-any)
+ - [`all`](#api-all)
+ - [`none`](#api-none)
+ - [`partition`](#api-partition)
+ - [`unfoldr`](#api-unfoldr)
+ - [`zip`](#api-zip)
+ - [`zipWith`](#api-zipwith)
+
+
+<h2 id="api-function-operations">Function operations</h2>
+
+Passing functions around as first-class objects is one of the cornerstones of
+functional programming. Udon provides several handy mechanisms for enabling
+function composition and reuse.
+
+<h3 id="api-curry"><code>curry</code></h3>
+
+Currying is the process of converting a function of arity _n_ into a nested set
+of functions with arity _1_, i.e. making it partially applicable. The `curry`
+function relies on the length property of the function to generate partially
+applicable functions, for example converting a function which accepts two
+arguments to a function which accepts one argument and returns a new function
+which also accepts one argument.
+
+~~~{.JavaScript}
+var add = function(a, b) {
+ return a + b;
+};
+
+var plus10 = Udon.curry(add)(10);
+~~~
+
+<h3 id="api-ncurry"><code>ncurry</code></h3>
+
+The basic `curry` function will be fine for many circumstances, but sometimes
+(for example when dealing with variadic functions or functions with optional
+arguments) one needs to be explicit about the number of arguments a curried
+function can accept. The `ncurry` function is a generator for currying
+functions: it accepts a number and returns a curry function that transforms
+functions of that arity to, effectively, a nest of partially applicable
+functions, each of which has arity 1.
+
+~~~{.JavaScript}
+var add3 = function(a, b, c) {
+ return a + b + c;
+};
+
+var curry3 = Udon.ncurry(3),
+ add3c = curry3(add3);
+
+add3c(1)(2)(3); // -> 6
+~~~
+
+<h3 id="api-compose"><code>compose</code></h3>
+
+The `compose` function allows one to easily generate 'pipelines' of functions
+through which a value is passed. Note that the last function in the pipeline
+will be the first to be applied; this mirrors both the way the code would be
+written without `compose`, as a nest of function calls.
+
+~~~{.JavaScript}
+var tcs = Udon.compose([Math.sin, Math.cos, Math.tan]);
+
+tcs(0.7); // -> 0.6176546934901699
+~~~
+
+It accepts an optional arity argument; if this is greater than 1 then the
+function pipeline will be made partially applicable.
+
+~~~{.JavaScript}
+var ceilMax = Udon.compose([Math.ceil, Math.max], 2);
+
+roundMax(0.7)(1.1); // -> 2
+~~~
+
+
+<h2 id="api-list-operations">List operations</h2>
+
+Technically, these aren't really list operations, because the underlying data
+structures are JavaScript arrays, not singly-linked lists (as in Lisps, ML,
+Haskell etc.). They are, however, close enough for most practical purposes.
+
+<h3 id="api-foldl"><code>foldl</code></h3>
+
+Both fold functions accept a function and use it to reduce a list to another
+value. For example, you could use it to implement a `sum` function which adds
+all the elements of a list together:
+
+~~~{.JavaScript}
+var sum = function(ns) {
+ return Udon.foldl(function(a, b) {
+ return a + b;
+ }, 0, ns);
+};
+~~~
+
+<h3 id="api-foldr"><code>foldr</code></h3>
+
+As the name implies, `foldl` is a left-associative function, which `foldr` is
+right-associative. So, for example, you could use `foldr` to convert an array
+into a singly-linked list.
+
+~~~{.JavaScript}
+var array2list = function(arr) {
+ return Udon.foldr(function(head, tail) {
+ return {
+ car: head,
+ cdr: tail
+ };
+ }, {car: null, cdr: null}, arr);
+};
+~~~
+
+You can read more about folds [on Wikipedia][fold].
+
+<h3 id="api-map"><code>map</code></h3>
+
+Returns the result of applying a given function to each element of a list.
+
+~~~{.JavaScript}
+Udon.map(function(n) {
+ return n * n;
+}, [1,2,3]);
+// -> [1,4,9]
+~~~
+
+<h3 id="api-filter"><code>filter</code></h3>
+
+Returns the elements of a list which satisfy some predicate.
+
+~~~{.JavaScript}
+Udon.filter(function(n) {
+ return n < 5;
+}, [4,7,3,9,21,2]);
+// -> [4,3,2]
+~~~
+
+<h3 id="api-any"><code>any</code></h3>
+
+Check whether any element of a list satisfies some predicate.
+
+~~~{.JavaScript}
+Udon.any(function(regex) {
+ return regex.exec("http://");
+}, [/[a-z]+:\/\//, /^ftp:/]);
+// -> true
+~~~
+
+<h3 id="api-all"><code>all</code></h3>
+
+Determine whether all the elements of a list satisfy some predicate.
+
+~~~{.JavaScript}
+Udon.all(function(str) {
+ return str.match(/^[A-Z][a-z]+$/);
+}, ["One", "Two", "three"]);
+// -> false
+~~~
+
+<h3 id="api-none"><code>none</code></h3>
+
+Check that no element of a list satisfies a predicate.
+
+~~~{.JavaScript}
+Udon.none(function(c) {
+ return c === Math.PI;
+}, [1, 0, -1, Math.LN2, Math.E]);
+// -> true
+~~~
+
+<h3 id="api-partition"><code>partition</code></h3>
+
+Separates a list into lists of those elements which do and do not satisfy some
+predicate.
+
+~~~{.JavaScript}
+Udon.partition(function(n) {
+ return n < 5;
+}, [4,7,3,9,21,2]);
+// -> [[4,3,2], [7,9,21]]
+~~~
+
+<h3 id="api-unfoldr"><code>unfoldr</code></h3>
+
+Builds a list by repeatedly applying a function to a seed value. The function
+should return a pair of values: the first is an element to append to the list
+under construction, while the second is the seed value to pass to the next
+function call. The function must return `null` when it's done, at which point
+`unfoldr` will return the constructed list.
+
+~~~{.JavaScript}
+var randomInts = function(ceil, n) {
+ return Udon.unfoldr(function(i) {
+ return i < 1 ? null : [Math.floor(Math.random() * ceil), i - 1];
+ }, n);
+};
+
+randomInts(5, 4); // -> [5,1,4,5] e.g.
+~~~
+
+<h3 id="api-zip"><code>zip</code></h3>
+
+Transforms a pair of lists into a list of pairs. If the lists are of differing
+lengths, any elements left over after each element in the shorter list has been
+paired up with one from the longer list will be discarded.
+
+~~~{.JavaScript}
+zip([1,2,3], ["a", "b", "c"]); // -> [[1, "a"], [2, "b"], [3, "c"]]
+~~~
+
+<h3 id="api-zipwith"><code>zipWith</code></h3>
+
+The `zipWith` function is a generalisation of `zip`: it returns the result of
+applying a function to each pair of elements from two lists.
+
+~~~{.JavaScript}
+zipWith(function(a, b) {
+ return a * b;
+}, [1,2,3], [4,5,6]);
+// -> [4,10,18]
+~~~
+
+[udon]: https://github.com/beastaugh/udon
+[fold]: http://en.wikipedia.org/wiki/Fold_(higher-order_function)
View
33 site/license.md
@@ -0,0 +1,33 @@
+---
+title: Udon is released under the BSD license
+---
+
+License
+=======
+
+Copyright (c) 2010, Benedict Eastaugh. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above
+ copyright notice, this list of conditions and the following
+ disclaimer in the documentation and/or other materials provided
+ with the distribution.
+ * Neither the name of Benedict Eastaugh nor the names of other
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
View
42 site/templates/default.html
@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html><head>
+ <meta charset="utf-8">
+ <title>$title</title>
+
+ <link rel="stylesheet" href="$root/udon.css">
+
+ <script type="text/javascript">
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-16781818-1']);
+ _gaq.push(['_setDomainName', 'none']);
+ _gaq.push(['_setAllowLinker', true]);
+ _gaq.push(['_trackPageview']);
+ (function() {
+ var ga = document.createElement('script');
+ ga.type = 'text/javascript';
+ ga.async = true;
+ ga.src = ('https:' == document.location.protocol ?
+ 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0];
+ s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+</head><body><div id="wrapper">
+
+ <div id="header" class="clear">
+ <h1 id="title"><a href="$root">Udon</a></h1>
+
+ <p id="tagline">Practical functional programming in JavaScript</p>
+ </div>
+
+ <div id="main">
+ $body
+ </div>
+
+ <div id="footer">
+ Udon is developed by <a href="http://extralogical.net/">Benedict
+ Eastaugh</a> and released under the <a href="$root/license.html">BSD
+ license</a>.
+ </div>
+
+</div></body></html>
View
166 site/udon.css
@@ -0,0 +1,166 @@
+html, body {
+ margin: 0;
+ border: none;
+ padding: 0;
+ font-family: Helvetica, Arial, sans-serif;
+ font-size: 14px;
+ line-height: 1.5;
+ color: #404040;
+ background: #fff;
+}
+
+.clear:after {
+ content: ".";
+ display: block;
+ height: 0;
+ clear: both;
+ visibility: hidden;
+}
+
+h1, h2, h3, h4 {
+ margin: 0 0 15px 0;
+ font-family: Georgia, serif;
+ font-weight: normal;
+}
+
+h1, h2 {
+ border-bottom: 1px solid #e5e5e5;
+ padding: 0 0 5px 0;
+}
+
+h1 {
+ font-size: 20px;
+}
+
+h2 {
+ font-size: 18px;
+}
+
+h3 {
+ font-size: 16px;
+}
+
+h4 {
+ font-size: 14px;
+}
+
+p {
+ margin: 0 0 15px 0;
+}
+
+a {
+ text-decoration: underline;
+}
+
+a:link, a:visited, a:active {
+ color:#1D57BC;
+}
+
+a:hover {
+ color:#DE1F00;
+}
+
+ul, ol {
+ margin: 0 0 15px 30px;
+ padding: 0;
+}
+
+ul {
+ list-style: disc;
+}
+
+ul ul {
+ margin-top: 4px;
+ list-style: circle;
+}
+
+li {
+ margin: 0 0 2px 0;
+ padding: 0;
+}
+
+pre, code {
+ font-family: Courier, monospace;
+ font-size: 14px;
+}
+
+code {
+ background: #f0f0f0;
+}
+
+pre {
+ border: 1px solid #e5e5e5;
+ padding: 9px;
+ background: #fafafa;
+}
+
+pre code {
+ background: none;
+}
+
+h3 code {
+ font-size: 16px;
+}
+
+#wrapper {
+ width: 600px;
+ margin: 0 auto;
+ padding: 0 30px;
+}
+
+#header {
+ border-bottom: 1px solid #ccc;
+ padding: 5px 0;
+}
+
+#title {
+ margin: 25px 0 5px;
+ border: none;
+ padding: 0;
+ line-height: 1;
+ font-family: Georgia, serif;
+ font-weight: bold;
+ font-size: 24px;
+}
+
+#title a {
+ text-decoration: none;
+ color: #444;
+}
+
+#tagline {
+ margin: 0 0 5px 0;
+ font-family: Georgia, serif;
+ font-size: 16px;
+}
+
+#main {
+ padding: 20px 0;
+}
+
+#footer {
+ border-top: 1px solid #ccc;
+ margin: 0 0 100px 0;
+ padding: 10px 0;
+ font-size: 12px;
+ color: #666;
+}
+
+/* Generated by pandoc. */
+table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode, table.sourceCode pre
+ { margin: 0; padding: 0; border: 0; vertical-align: baseline; border: none; }
+td.lineNumbers { border-right: 1px solid #AAAAAA; text-align: right; color: #AAAAAA; padding-right: 5px; padding-left: 5px; }
+td.sourceCode { padding-left: 5px; }
+pre.sourceCode span.kw { color: #AE4A54; }
+pre.sourceCode span.dt { color: #902000; }
+pre.sourceCode span.dv { color: #40a070; }
+pre.sourceCode span.bn { color: #40a070; }
+pre.sourceCode span.fl { color: #40a070; }
+pre.sourceCode span.ch { color: #4070a0; }
+pre.sourceCode span.st { color: #4070a0; }
+pre.sourceCode span.co { color: #60a0b0; font-style: italic; }
+pre.sourceCode span.ot { color: #007020; }
+pre.sourceCode span.al { color: red; font-weight: bold; }
+pre.sourceCode span.fu { color: #06287e; }
+pre.sourceCode span.re { }
+pre.sourceCode span.er { color: red; font-weight: bold; }
View
13 site/udon.hs
@@ -0,0 +1,13 @@
+module Main (main) where
+
+import Text.Hakyll (hakyll)
+import Text.Hakyll.Render (renderChain, static)
+import Text.Hakyll.CreateContext (createPage)
+
+main = hakyll "http://extralogical.net/projects/udon" $ do
+ static "udon.css"
+
+ mapM_ (renderChain [ "templates/default.html" ] . createPage)
+ [ "index.md"
+ , "license.md"
+ ]

0 comments on commit 2563ede

Please sign in to comment.