Skip to content
Browse files

overview and top-level module doc

  • Loading branch information...
1 parent cfb791d commit 3bcf166d208e2caab1fec24ab2323c80487844eb Bryan Fink committed Apr 28, 2011
Showing with 59 additions and 0 deletions.
  1. +2 −0 .gitignore
  2. +10 −0 doc/overview.edoc
  3. +27 −0 src/gin.erl
  4. +20 −0 src/mayo.erl
View
2 .gitignore
@@ -1,4 +1,6 @@
*~
ebin/
.eunit/
+doc/*
+!doc/overview.edoc
View
10 doc/overview.edoc
@@ -0,0 +1,10 @@
+@doc Mixers is a collection of useful utilities for functional
+programming.
+
+The {@link gin} module implements function-based "generators" to
+facitate iteration without, for example, first having to build a list
+for use with lists:fold, :map, etc.
+
+The {@link mayo} module implements "do", "while", and "loop" functions
+to make it easier to analyze structures recursively using anonymous
+functions (as is often the case in the Erlang console).
View
27 src/gin.erl
@@ -1,3 +1,30 @@
+%% @doc Function-based generators.
+%%
+%% Sometimes building a list simply to have something to iterate
+%% along is annoying, wasteful, or impossible. For those
+%% situations, consider `gin'.
+%%
+%% A gin is a function of zero arity. When evaluated, it
+%% produces the "next" item, and a new gin (as a 2-tuple `{Item,
+%% Gin}'). When the gin has nothing more to produce, the result
+%% of its evaluation should be the atom `stop'.
+%%
+%% The {@link seq/2} function provides a nice example. Calling
+%% it with the arguments 1 and 3 produces a gin that will
+%% evaluate to 1, 2, and 3, before stopping:
+%% ```
+%% First = gin:seq(1, 3). % create a new gin
+%% {1, Second} = gin:next(First). % get the first value
+%% {2, Third} = gin:next(Second). % get the second value
+%% {3, Fourth} = gin:next(Third). % get the third value
+%% stop = gin:next(Fourth).
+%% '''
+%%
+%% Remember that gins are functions, so they can do anything:
+%% compute pure values, receive messages, print output, receive
+%% input, etc. The functions in this module have no side effects
+%% themselves, so it's up to the caller to determine whether they
+%% stay that way.
-module(gin).
-export([
View
20 src/mayo.erl
@@ -1,3 +1,23 @@
+%% @doc Recursion help for anonymous functions and alternate control.
+%%
+%% When you're stuck at the Erlang console, wishing you could
+%% write a recursive anonymous function to debug some data
+%% structure, or you need a different kind of control than
+%% {@link lists} offers, load `mayo'.
+%%
+%% For instance, you may want to sum mailbox messages until some
+%% signal:
+%% ```
+%% sum_until(Marker) ->
+%% mayo:loop(
+%% fun(Sum) ->
+%% receive
+%% Marker -> {stop, Sum};
+%% Number -> {continue, Number+Sum}
+%% end
+%% end,
+%% 0).
+%% '''
-module(mayo).
-export([

0 comments on commit 3bcf166

Please sign in to comment.
Something went wrong with that request. Please try again.