Merge pull request #9 from moatom/master

Add formatter & Update README.md

.scalafmt.conf

@@ -0,0 +1,11 @@
+version = 3.7.1
+
+runner.dialect = scala3
+maxColumn = 120
+align.preset = "most"
+docstrings {
+  style = asterisk
+  wrap = false
+}
+
+rewrite.rules = [RedundantParens, SortImports]

README.md

@@ -1,15 +1,63 @@
-**strymonas** is a library providing fast-streams for Scala 3/dotty through multi-stage programming and partial evaluation.
+**strymonas** is a library providing fast-streams for Scala 3 through multi-stage programming and partial evaluation.
 
 ![ci](https://github.com/strymonas/strymonas/actions/workflows/ci.yml/badge.svg)
 [![Join the chat at https://gitter.im/strymonas/strymonas](https://badges.gitter.im/strymonas/strymonas.svg)](https://gitter.im/strymonas/strymonas?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-## Building strymonas
+## How to Use
 
-strymonas is built with SBT 1.3.8 or later and uses the [sbt-dotty](https://github.com/lampepfl/dotty/tree/master/sbt-dotty) plugin for Scala 3.
+```scala
+import scala.quoted.staging._
+import strymonas._
+import strymonas.Code.given
 
-* Use `sbt test` to run the tests.
+given Code.Compiler = Compiler.make(getClass.getClassLoader)
+given raw: Raw = Raw(Code)
+
+val t = run {
+  // Write a streaming operation here
+  Cooked.of_int_array(Array(1,2,3,4,5,6,7,8,9,10)).fold(0, (_+_))
+}
+
+println(t)
+```
+
+Construct a streaming pipeline using the Cooked Object (defined in [Stream.scala](src/main/scala/strymonas/Stream.scala)).[^1] Then, invoke the pipeline with `scala.quoted.staging.run`.
+
+
+Refer to the [examples directory](examples) for more details.
+
+[^1]: If you are familiar with machine learning frameworks, you can think of this as an analogy to a Static Computational Graph.
+
+## How to Build
+
+strymonas is built with SBT 1.7.1 or later.
+
+* Use `sbt compile` to build the project from the source
+* Use `sbt test` to run the tests
 * Use `sbt bench/jmh:run` to run the benchmarks
 
+### Prepare Environment
+```bash
+# 1. Install SBT: https://docs.scala-lang.org/getting-started/index.html, https://get-coursier.io/docs/cli-overview
+## macOS Case:
+brew install coursier && coursier setup # Maybe `source ~/.profile` or `reboot` is required
+
+## Linux Case:
+curl -fL https://github.com/coursier/coursier/releases/latest/download/cs-x86_64-pc-linux.gz | gzip -d > cs && chmod +x cs && ./cs setup
+source ~/.profile # or reboot
+
+# 2. Clone this repo
+git clone [email protected]:strymonas/strymonas-scala.git
+cd strymonas-scala
+
+# 3. Compile via SBT
+sbt compile
+
+# 4. Clean compilation artifacts as needed
+sbt clean
+rm -rf target/ project/target/ project/project/
+```
+
 ## Contributors
 
 * Oleg Kiselyov ([okmij.org](http://okmij.org/ftp/))
@@ -21,4 +69,6 @@ strymonas is built with SBT 1.3.8 or later and uses the [sbt-dotty](https://gith
 
 ## Credits
 
-Strymonas has its origins in a [paper](https://dl.acm.org/doi/10.1145/3093333.3009880) published by Oleg Kiselyov ([okmij.org](http://okmij.org/ftp/)), Aggelos Biboudis ([@biboudis](https://github.com/biboudis)), Nick Palladinos ([@palladin](https://github.com/palladin)) and Yannis Smaragdakis [site](https://yanniss.github.io/) and this repo has its aim into making this library available for Scala 3. The initial prototypes (that correspond directly to the paper, were developed for [Scala/LMS](https://github.com/strymonas/staged-streams.scala) and [OCaml/BER MetaOCaml](https://github.com/strymonas/staged-streams.ocaml)) and the initial commit for the Scala 3 port is based on the case study presented for the [paper](https://biboudis.github.io/papers/pcp-gpce18.pdf) published by Nicolas Stucki [@nicolasstucki](https://github.com/nicolasstucki).
+strymonas has its origins in a [paper](https://dl.acm.org/doi/10.1145/3093333.3009880) published by Oleg Kiselyov ([okmij.org](http://okmij.org/ftp/)), Aggelos Biboudis ([@biboudis](https://github.com/biboudis)), Nick Palladinos ([@palladin](https://github.com/palladin)) and Yannis Smaragdakis ([site](https://yanniss.github.io/)) and this repo has its aim into making this library available for Scala 3.
+
+The initial prototypes (that correspond directly to the paper, were developed for [Scala/LMS](https://github.com/strymonas/staged-streams.scala) and [OCaml/BER MetaOCaml](https://github.com/strymonas/staged-streams.ocaml)) and the initial commit for the Scala 3 port is based on the case study presented for the [paper](https://biboudis.github.io/papers/pcp-gpce18.pdf) published by Nicolas Stucki [@nicolasstucki](https://github.com/nicolasstucki).

build.sbt

@@ -2,6 +2,7 @@ import xerial.sbt.Sonatype._
 
 val scala3Version = "3.3.4"
 
+ThisBuild / scalafmtOnCompile := true // not recommended, but just for convenience
 
 lazy val root = project
   .in(file("."))

examples/hello-world-template/build.sbt

@@ -0,0 +1,80 @@
+
+// The simplest possible sbt build file is just one line:
+
+scalaVersion := "3.3.4"
+// That is, to create a valid sbt build, all you've got to do is define the
+// version of Scala you'd like your project to use.
+
+// ============================================================================
+
+// Lines like the above defining `scalaVersion` are called "settings". Settings
+// are key/value pairs. In the case of `scalaVersion`, the key is "scalaVersion"
+// and the value is "2.13.12"
+
+// It's possible to define many kinds of settings, such as:
+
+name := "hello-world"
+organization := "ch.epfl.scala"
+version := "1.0"
+
+// Note, it's not required for you to define these three settings. These are
+// mostly only necessary if you intend to publish your library's binaries on a
+// place like Sonatype.
+
+
+// Want to use a published library in your project?
+// You can define other libraries as dependencies in your build like this:
+
+libraryDependencies ++= Seq(
+  "org.scala-lang.modules" %% "scala-parser-combinators" % "2.3.0",
+  "io.github.strymonas" %% "strymonas" % "0.1.0",
+)
+
+// Here, `libraryDependencies` is a set of dependencies, and by using `+=`,
+// we're adding the scala-parser-combinators dependency to the set of dependencies
+// that sbt will go and fetch when it starts up.
+// Now, in any Scala file, you can import classes, objects, etc., from
+// scala-parser-combinators with a regular import.
+
+// TIP: To find the "dependency" that you need to add to the
+// `libraryDependencies` set, which in the above example looks like this:
+
+// "org.scala-lang.modules" %% "scala-parser-combinators" % "2.3.0"
+
+// You can use Scaladex, an index of all known published Scala libraries. There,
+// after you find the library you want, you can just copy/paste the dependency
+// information that you need into your build file. For example, on the
+// scala/scala-parser-combinators Scaladex page,
+// https://index.scala-lang.org/scala/scala-parser-combinators, you can copy/paste
+// the sbt dependency from the sbt box on the right-hand side of the screen.
+
+// IMPORTANT NOTE: while build files look _kind of_ like regular Scala, it's
+// important to note that syntax in *.sbt files doesn't always behave like
+// regular Scala. For example, notice in this build file that it's not required
+// to put our settings into an enclosing object or class. Always remember that
+// sbt is a bit different, semantically, than vanilla Scala.
+
+// ============================================================================
+
+// Most moderately interesting Scala projects don't make use of the very simple
+// build file style (called "bare style") used in this build.sbt file. Most
+// intermediate Scala projects make use of so-called "multi-project" builds. A
+// multi-project build makes it possible to have different folders which sbt can
+// be configured differently for. That is, you may wish to have different
+// dependencies or different testing frameworks defined for different parts of
+// your codebase. Multi-project builds make this possible.
+
+// Here's a quick glimpse of what a multi-project build looks like for this
+// build, with only one "subproject" defined, called `root`:
+
+// lazy val root = (project in file(".")).
+//   settings(
+//     inThisBuild(List(
+//       organization := "ch.epfl.scala",
+//       scalaVersion := "2.13.12"
+//     )),
+//     name := "hello-world"
+//   )
+
+// To learn more about multi-project builds, head over to the official sbt
+// documentation at http://www.scala-sbt.org/documentation.html

examples/hello-world-template/project/build.properties

@@ -0,0 +1 @@
+sbt.version=1.10.7

examples/hello-world-template/src/main/scala/Main.scala

@@ -0,0 +1,12 @@
+import scala.quoted.staging._
+import strymonas._
+import strymonas.Code.given
+
+object Main extends App {
+  given Code.Compiler = Compiler.make(getClass.getClassLoader)
+  given raw: Raw = Raw(Code)
+
+  val t = run { Cooked.of_int_array(Array(1,2,3,4,5,6,7,8,9,10)).fold(0, (_+_)) }
+
+  println(t)
+}

project/plugins.sbt

@@ -1,4 +1,5 @@
 addSbtPlugin("pl.project13.scala" % "sbt-jmh" % "0.4.3")
+addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.5.0")
 addSbtPlugin("org.xerial.sbt" % "sbt-sonatype" % "3.12.2")
 addSbtPlugin("com.github.sbt" % "sbt-pgp" % "2.2.1")
 addSbtPlugin("com.github.sbt" % "sbt-dynver" % "5.0.1")