Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Docs

  • Loading branch information...
commit e8d0495eaae98b14cb08467ee25266a3e6833c76 1 parent 4cbd3d4
@runarorama authored
View
30 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.
View
17 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
View
6 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
View
23 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] =
Please sign in to comment.
Something went wrong with that request. Please try again.