Docs

LICENSE

@@ -0,0 +1,30 @@
+Copyright 2012 Rúnar Bjarnason, Paul Chiusano, Dan Doel, Edward Kmett
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. 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.
+
+3. Neither the name of the author nor the names of his contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``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 AUTHORS 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.

README.md

@@ -1,4 +1,15 @@
-scala-transducers
-=================
+Machines
+========
+
+Machines are demand-driven input sources like pipes, conduits, or iteratees, but can support inputs of arbitrary complexity.
+
+You design a `Machine` by writing a `Plan`. You then `compile` the machine if it is to run once to completion, or designate it to run `repeatedly`.
+
+Simple machines that take one input are called a `Process` and processes form a `Category`. More generally you can attach a `Process` to the output of any type of `Machine`, yielding a new `Machine`.
+
+More complicated machines provide other ways of connecting to them.
+
+Typically the use of machines proceeds by using simple plans into machine `Tee`s and `Wye`s, `cap`ping many of the inputs to those with possibly monadic sources, feeding the input (possibly repeatedly).
+
+Machines are entirely pure. They embed no monadic effects. An effectful `Driver` can be used to drive a machine. Such a driver can have effects when requesting the input and emitting the output.
 
-A stream processing library for Scala

src/main/scala/com/clarifi/machines/Plan.scala

@@ -7,8 +7,9 @@ import scalaz._
 
 /**
  * You can construct a `Plan` and then `compile` it to a `Machine`.
- * A `Plan[K, O, A]` is a specification for a pure `Machine` that reads inputs selected by `K`,
- * writes values of type `O`, and has intermediate results of type `A`.
+ * A `Plan[K, O, A]` is a specification for a pure `Machine` that reads
+ * inputs selected by `K` and writes values of type `O`. The `Plan` has
+ * intermediate results of type `A` which are placeholders for further plans.
  */
 sealed trait Plan[+K, +O, +A] {
   def flatMap[L >: K, P >: O, B](f: A => Plan[L, P, B]): Plan[L, P, B]
@@ -111,6 +112,7 @@ case object Stop extends Plan[Nothing, Nothing, Nothing] {
 }
 
 object Plan {
+  /** `Plan` is a ringad. */
   implicit def planInstance[K, O]: MonadPlus[({type λ[α] = Plan[K, O, α]})#λ] =
     new MonadPlus[({type λ[+α] = Plan[K, O, α]})#λ] {
       def bind[A, B](m: Plan[K, O, A])(f: A => Plan[K, O, B]) = m flatMap f

src/main/scala/com/clarifi/machines/package.scala

@@ -12,16 +12,22 @@ package object machines {
    * Many combinators are parameterized on the choice of `Handle`.
    * This acts like an input stream selector.
    *
-   * For example:
+   * For example, to select one of two streams, on the `left` or `right`:
    * {{{
-   * L : Handle[Merge, (A, B), A]
-   * R : Handle[Merge, (A, B), B]
+   * left  : Handle[T[A, Any], A]
+   * right : Handle[T[Any, A], B]
    * }}}
    */
   type Handle[+K, +O] = (O => Any) => K
 
+  /**
+   * A machine that requests inputs described by `K` and emits values of type `O`.
+   */
   type Machine[+K, +O] = Plan[K, O, Nothing]
 
+  /**
+   * A machine that requests values of type `I` and emits values of type `O`.
+   */
   type Process[-I, +O] = Machine[I => Any, O]
 
   sealed class ProcessW[-I, +O](p: Process[I, O]) {
@@ -36,8 +42,15 @@ package object machines {
   }
   implicit def processw[I, O](p: Process[I, O]): ProcessW[I, O] = new ProcessW(p)
 
+  /**
+   * A machine that emits values of type `O` without taking any input.
+   */
   type Source[+O] = Machine[Nothing, O]
 
+  /**
+   * A machine that can request values of type `A` on the left,
+   * request values of type `B` on the right, and emit values of type `C`.
+   */
   type Tee[-A, -B, +C] = Machine[T[A, B], C]
   sealed class TeeW[-I, -J, +O](t: Tee[I, J, O]) {
     import Tee._
@@ -57,6 +70,10 @@ package object machines {
   }
   implicit def teew[I, J, O](tee: Tee[I, J, O]): TeeW[I, J, O] = new TeeW(tee)
 
+  /**
+   * Same as a `Tee` except it can indicate that it has no preference whether it
+   * receives an `I` on the left or a `J` on the right.
+   */
   type Wye[-I, -J, +O] = Machine[These[I => Any, J => Any], O]
 
   def traversePlan_[F[_], K, O, A](as: F[A])(f: A => Plan[K, O, Unit])(implicit F: Foldable[F]): Plan[K, O, Unit] =