Skip to content

Commit

Permalink
References Microsite Page.
Browse files Browse the repository at this point in the history 
Adds an overview paragraph at the top of the Rreadme.
Adds to the microsite a section for talks, blog posts, related
libraries and othere reference material on FS2.
  • Loading branch information
@diesalbla
diesalbla committed Dec 27, 2018
1 parent 3a27282 commit e04ac49
Show file tree
Hide file tree
Showing 3 changed files with 133 additions and 62 deletions.
118 changes: 57 additions & 61 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,24 @@
FS2: Functional Streams for Scala (previously 'Scalaz-Stream')
FS2: Functional Streams for Scala
=============

[![Build Status](https://travis-ci.org/functional-streams-for-scala/fs2.svg?branch=series/1.0)](http://travis-ci.org/functional-streams-for-scala/fs2)
[![Gitter Chat](https://badges.gitter.im/functional-streams-for-scala/fs2.svg)](https://gitter.im/functional-streams-for-scala/fs2)
[![Latest version](https://img.shields.io/maven-central/v/co.fs2/fs2-core_2.12.svg)](https://index.scala-lang.org/functional-streams-for-scala/fs2/fs2-core)

### Overview

FS2 is a library for purely functional, effectful, and polymorphic stream processing library in the [Scala programming language]((https://scala-lang.org). Its design goals are compositionality, expressiveness, resource safety, and speed. The name is a modified acronym for **F**unctional **S**treams for **Scala** (FSS, or FS2).

FS2 is available for Scala 2.11, Scala 2.12, and [Scala.js](http://www.scala-js.org/). FS2 is built upon two major functional libraries for Scala:
- [Cats](https://typelevel.org/cats/), which defines such type classes as _Functor_, _Monad_, or _MonadError_, and their implementation for usual data types in Scala.
- [Cats-Effect](https://typelevel.org/cats-effect/), which defines more specific type-classes for concurrency, asynchronicity, input-output, timing, resource baracketing, and interruption. Cats-Effect also provides several data-types for communication and coordination among concurrent processes, such as semaphores, deferred values, or atomic references. Some of these types were first developed in FS2.

Regardless of those dependencies, FS2 core types (streams and pulls) are polymorphic in the effect type (as long as it is compatible with `cats-effect` typeclasses), and thus FS2 can be used with other IO libraries, such as [Monix](https://monix.io/), or [ZIO](https://scalaz.github.io/scalaz-zio/).

Prior to 2016, FS2 was known as `scalaz-stream`, which was based on the [`scalaz`](https://github.com/scalaz/scalaz) library.

### Getting Started

Quick links:

* [Microsite][microsite]
Expand All @@ -19,7 +33,46 @@ Quick links:
[rx-api]: https://oss.sonatype.org/service/local/repositories/releases/archive/co/fs2/fs2-reactive-streams_2.12/1.0.1/fs2-reactive-streams_2.12-1.0.1-javadoc.jar/!/fs2/interop/reactivestreams/index.html
[experimental-api]: https://oss.sonatype.org/service/local/repositories/releases/archive/co/fs2/fs2-experimental_2.12/1.0.1/fs2-experimental_2.12-1.0.1-javadoc.jar/!/fs2/experimental/index.html

### <a id="about"></a>About the library ###
### <a id="getit"></a> Where to get the latest version ###

The latest version is 1.0.x. See the badge at the top of the README for the exact version number.

The [1.0 migration guide](https://github.com/functional-streams-for-scala/fs2/blob/series/1.0/docs/migration-guide-1.0.md)
summarizes the differences between 1.0 and 0.10. To get 1.0.x, add the following to your SBT build:

```
// available for Scala 2.11, 2.12
libraryDependencies += "co.fs2" %% "fs2-core" % "1.0.1" // For cats 1.5.0 and cats-effect 1.1.0
// optional I/O library
libraryDependencies += "co.fs2" %% "fs2-io" % "1.1.0"
// optional reactive streams interop
libraryDependencies += "co.fs2" %% "fs2-reactive-streams" % "1.1.0"
// optional experimental library
libraryDependencies += "co.fs2" %% "fs2-experimental" % "1.1.0"
```

The previous stable release is 0.10.6. You may want to first
[read the 0.10 migration guide](https://github.com/functional-streams-for-scala/fs2/blob/series/0.10/docs/migration-guide-0.10.md)
if you are upgrading from 0.9 or earlier. To get 0.10, add the following to your SBT build:

```
// available for Scala 2.11, 2.12
libraryDependencies += "co.fs2" %% "fs2-core" % "0.10.6"
// optional I/O library
libraryDependencies += "co.fs2" %% "fs2-io" % "0.10.6"
```

The fs2-core library is also supported on Scala.js:

```
libraryDependencies += "co.fs2" %%% "fs2-core" % "0.10.6"
```

### <a id="about"></a>Example ###

FS2 is a streaming I/O library. The design goals are compositionality, expressiveness, resource safety, and speed. Here's a simple example of its use:

Expand Down Expand Up @@ -68,56 +121,12 @@ These features mean that FS2 goes beyond streaming I/O to offer a very general a

### <a id="docs"></a>Documentation and getting help ###

* Here are the API ScalaDocs for [The core library][core-api], which defines and implements the core types for streams and pulls, as well as the type aliases for pipes and sinks. [The `io` library][io-api], FS2 bindings for NIO-based file I/O and TCP/UDP networking
* [The official guide](https://functional-streams-for-scala.github.io/fs2/guide.html) is a good starting point for learning more about the library.
* The [documentation page](https://functional-streams-for-scala.github.io/fs2/faq.html) is intended to serve as a list of all references, including conference presentation recordings, academic papers, and blog posts, on the use and implementation of `fs2`.
* [The FAQ](https://functional-streams-for-scala.github.io/fs2/faq.html) has frequently asked questions. Feel free to open issues or PRs with additions to the FAQ!
* Also feel free to come discuss and ask/answer questions in [the gitter channel](https://gitter.im/functional-streams-for-scala/fs2) and/or on StackOverflow using [the tag FS2](http://stackoverflow.com/tags/fs2). Gitter will generally get you a quicker answer.

Blog posts, talks, and other external resources are listed on the [Additional Resources](https://github.com/functional-streams-for-scala/fs2/wiki/Additional-Resources) page.

### <a id="getit"></a> Where to get the latest version ###

The latest version is 1.0.x. See the badge at the top of the README for the exact version number.

The [1.0 migration guide](https://github.com/functional-streams-for-scala/fs2/blob/series/1.0/docs/migration-guide-1.0.md)
summarizes the differences between 1.0 and 0.10. To get 1.0.x, add the following to your SBT build:

```
// available for Scala 2.11, 2.12
libraryDependencies += "co.fs2" %% "fs2-core" % "1.0.1" // For cats 1.5.0 and cats-effect 1.1.0
// optional I/O library
libraryDependencies += "co.fs2" %% "fs2-io" % "1.1.0"
// optional reactive streams interop
libraryDependencies += "co.fs2" %% "fs2-reactive-streams" % "1.1.0"
// optional experimental library
libraryDependencies += "co.fs2" %% "fs2-experimental" % "1.1.0"
```

The previous stable release is 0.10.6. You may want to first
[read the 0.10 migration guide](https://github.com/functional-streams-for-scala/fs2/blob/series/0.10/docs/migration-guide-0.10.md)
if you are upgrading from 0.9 or earlier. To get 0.10, add the following to your SBT build:

```
// available for Scala 2.11, 2.12
libraryDependencies += "co.fs2" %% "fs2-core" % "0.10.6"
// optional I/O library
libraryDependencies += "co.fs2" %% "fs2-io" % "0.10.6"
```

The fs2-core library is also supported on Scala.js:

```
libraryDependencies += "co.fs2" %%% "fs2-core" % "0.10.6"
```

API docs:

* [The core library][core-api]
* [The `io` library][io-api], FS2 bindings for NIO-based file I/O and TCP/UDP networking

### Projects using FS2 ###

If you have a project you'd like to include in this list, either open a PR or let us know in [the gitter channel](https://gitter.im/functional-streams-for-scala/fs2) and we'll add a link to it here.
Expand Down Expand Up @@ -148,19 +157,6 @@ If you have a project you'd like to include in this list, either open a PR or le
* [streamz](https://github.com/krasserm/streamz): A library that supports the conversion of [Akka Stream](http://doc.akka.io/docs/akka/2.4/scala/stream/index.html) `Source`s, `Flow`s and `Sink`s to and from FS2 `Stream`s, `Pipe`s and `Sink`s, respectively. It also supports the usage of [Apache Camel](http://camel.apache.org/) endpoints in FS2 `Stream`s and Akka Stream `Source`s, `Flow`s and `SubFlow`s.
* [upperbound](https://github.com/SystemFw/upperbound): A purely functional, interval-based rate limiter with support for backpressure.

### Related projects ###

FS2 has evolved from earlier work on streaming APIs in Scala and Haskell. Some influences:

* [Machines](https://github.com/ekmett/machines/), a Haskell library by Ed Kmett, which spawned [`scala-machines`](https://github.com/runarorama/scala-machines)
* [The FP in Scala stream processing library](https://github.com/fpinscala/fpinscala/blob/master/answers/src/main/scala/fpinscala/streamingio/StreamingIO.scala) developed for the book [FP in Scala](https://www.manning.com/books/functional-programming-in-scala)
* [Reflex](https://hackage.haskell.org/package/reflex), an FRP library in Haskell, by Ryan Trinkle
* There are various other iteratee-style libraries for doing compositional, streaming I/O in Scala, notably the [`scalaz/iteratee`](https://github.com/scalaz/scalaz/tree/scalaz-seven/iteratee) package and [iteratees in Play](https://www.playframework.com/documentation/2.0/Iteratees).

### Presentations, Blogs, etc. ###

See [Additional resources](https://github.com/functional-streams-for-scala/fs2/wiki/Additional-Resources).

### Acknowledgments ###

[![YourKit](https://www.yourkit.com/images/yklogo.png)](https://www.yourkit.com/)
Expand Down
2 changes: 1 addition & 1 deletion build.sbt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -344,7 +344,7 @@ lazy val microsite = project
.settings(commonSettings)
.settings(
micrositeName := "fs2",
micrositeDescription := "fs2 - Functional Streams for Scala",
micrositeDescription := "Purely functional, effectful, resourceful, concurrent streams for Scala",
micrositeGithubOwner := "functional-streams-for-scala",
micrositeGithubRepo := "fs2",
micrositeBaseUrl := "",
Expand Down
75 changes: 75 additions & 0 deletions site/src/main/tut/documentation.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
layout: page
title: "Documentation and References"
section: "documentation"
position: 4
---

#### API ScalaDocs

* [The core library][core-api], which defines the basic types for streams and pulls.
* [The `io` library][io-api], FS2 bindings for NIO-based file I/O and TCP/UDP networking.


#### Talks and Presentations

* [Declarative Control Flow with fs2 Stream](https://www.youtube.com/watch?v=YSN__0VEsaw), a talk by [Fabio Labella][1] at the [Typelevel Summit](https://typelevel.org/event/2018-03-summit-boston/), celebrated in Boston in March 2018. Slides available at the author's [Github](https://github.com/SystemFw/TL-Summit-Boston-2018).
* [Compose your program flow with Stream](https://www.youtube.com/watch?v=x3GLwl1FxcA), a talk by [Fabio Labella][1] at a Klarna tech talk, sometime before March 2018.
* 2018-03-20: [Compose your program flow with Stream](https://www.youtube.com/watch?v=x3GLwl1FxcA) by [Fabio Labella][1]
* [FS2 Internals: Performance](https://www.youtube.com/watch?v=TXxzMF14pxU), a talk by [Michael Pilquist][2] at [Scale by the Bay](http://2017.scale.bythebay.io/), in November 2017. [Slides](https://speakerdeck.com/mpilquist/fs2-internals).
* [Compositional Streaming with FS2](https://www.youtube.com/watch?v=oFk8-a1FSP0), a talk by [Michael Pilquist][2] at [Scale by the Bay](http://scala.bythebay.io/), November 2016. [Slides](https://speakerdeck.com/mpilquist/compositional-streaming-with-fs2).


#### Tutorials

* [An introduction to FS2 Streams](https://www.youtube.com/watch?v=B1wb4fIdtn4&t=3094s), a REPL-demo tutorial given by [Michael Pilquist][2] for the [Scala Toronto](https://www.meetup.com/scalator/events/254059603/) Meetup group, on September 2018.
* Introduction to Functional Streams for Scala (FS2), a REPL-demo tutorial on FS2 (version 0.9), given by [Michael Pilquist][2] in May of 2016. The tutorial is split in three parts:
* [Part 1](https://www.youtube.com/watch?v=cahvyadYfX8).
* [Part 2: Chunks & Pipes](https://www.youtube.com/watch?v=HM0mOu5o2uA).
* [Part 3: Concurrency](https://www.youtube.com/watch?v=8YxcB6PIUDg).


#### Blog Posts and Short Articles

* [Inference Driven Design](https://mpilquist.github.io/blog/2018/07/04/fs2/), by [Muchael Pilquist][2], describes some of the tradeoffs in designing the API and the code of FS2, used to work around some of the problems in the Scala compiler.
* [Tips for working with FS2](https://underscore.io/blog/posts/2018/03/20/fs2.html), by [Pere Villega](https://github.com/pvillega),
* [A streaming library with a superpower: FS2 and functional programming](https://medium.freecodecamp.org/a-streaming-library-with-a-superpower-fs2-and-functional-programming-6f602079f70a).


#### Related Academic Research

* [Stream Fusion, to Completeness](https://arxiv.org/abs/1612.06668), by Oleg Kyseliov et al. In _Principles of Programming Languages (POPL)_, January 2017. [DBLP](https://dblp.uni-trier.de/rec/bibtex/conf/popl/KiselyovBPS17).

* [Iteratees](okmij.org/ftp/Haskell/Iteratee/describe.pdf), by Oleg Kyseliov, in _International Symposium of Functional and Logic Programming (FLOPS)_. [DBLP](https://dblp.uni-trier.de/rec/bibtex/conf/flops/Kiselyov12). [Author's webpage](http://okmij.org/ftp/Haskell/Iteratee/index.html).


#### Related Scala Libraries

* FS2 was originally called [Scalaz-Stream](https://github.com/scalaz/scalaz-stream).
* [Monix](https://monix.io/) defines a special type for lazy, pull-based streaming, called `monix.tail.Iterant`.
* [ZIO](https://scalaz.github.io/) provides a stream type ([source code](https://github.com/scalaz/scalaz-zio/blob/master/core/shared/src/main/scala/scalaz/zio/stream/Stream.scala).
* [The FP in Scala stream processing library](https://github.com/fpinscala/fpinscala/blob/master/answers/src/main/scala/fpinscala/streamingio/StreamingIO.scala) developed for the book [FP in Scala](https://www.manning.com/books/functional-programming-in-scala)
* There are various other iteratee-style libraries for doing compositional, streaming I/O in Scala, notably the [`scalaz/iteratee`](https://github.com/scalaz/scalaz/tree/scalaz-seven/iteratee) package and [iteratees in Play](https://www.playframework.com/documentation/2.0/Iteratees).
* [Akka-Streams](https://doc.akka.io/docs/akka/2.5/stream/index.html)


#### Related Haskell Libraries

Since Haskell is the purely functional lazily-evaluated programming language _par excellance_, it is no wonder that many of the ideas in FS2 were first tried and developed in there.

* [Machines](https://github.com/ekmett/machines/), a Haskell library by Ed Kmett, which spawned [`scala-machines`](https://github.com/runarorama/scala-machines)
* [Conduit](http://hackage.haskell.org/package/conduit)
* [Pipes](http://hackage.haskell.org/package/pipes)
* [Reflex](https://hackage.haskell.org/package/reflex), an FRP library in Haskell, by Ryan Trinkle
* [Streaming](http://hackage.haskell.org/package/streaming) is a recent addition to Haskell streaming libraries. It represents a Stream using a `FreeT` monad transformer.


[1]: https://github.com/SystemFw
[2]: https://github.com/mpilquist


### Older References ###

The Github page for [Additional resources](https://github.com/functional-streams-for-scala/fs2/wiki/Additional-Resources) lists some of the references above and several older ones, mostly from the `scalaz-stream` days.


0 comments on commit e04ac49

Please sign in to comment.