From 158f600938549d338642acd2444e2fe59711a8ad Mon Sep 17 00:00:00 2001 From: zetashift Date: Tue, 4 Apr 2023 22:15:59 +0200 Subject: [PATCH 1/7] Add typelevel toolkit blog post --- _data/authors.yml | 3 + .../_posts/2023-04-03-typelevel_toolkit.md | 108 ++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 collections/_posts/2023-04-03-typelevel_toolkit.md diff --git a/_data/authors.yml b/_data/authors.yml index 440b86f9..f13312ab 100644 --- a/_data/authors.yml +++ b/_data/authors.yml @@ -413,3 +413,6 @@ matthicks: full_name: "Matt Hicks" twitter: "darkfrog26" github: "darkfrog26" +zetashift: + full_name: "Rishad Sewnarain" + github: "zetashift" diff --git a/collections/_posts/2023-04-03-typelevel_toolkit.md b/collections/_posts/2023-04-03-typelevel_toolkit.md new file mode 100644 index 00000000..a0a4d7c3 --- /dev/null +++ b/collections/_posts/2023-04-03-typelevel_toolkit.md @@ -0,0 +1,108 @@ +--- +layout: post +title: Typelevel Toolkit +category: technical + +meta: + nav: blog + author: zetashift + pygments: true +--- + +Getting started in the wondrous world of functional programming using [Typelevel libraries](https://typelevel.org/projects) can be daunting. Before you can even write your first pure "Hello, World!" you'll need to install a Java runtime, editor tooling and build tools. Then you'll need to setup some project using [sbt]() or [mill](). As an added consequence, after all the setup, the idea of using these battle-tested libraries for small scripts will seem like a chore. This is where [Typelevel Toolkit](https://typelevel.org/toolkit/) comes in. It provides an easy start for beginning and experienced developers with Scala and functional programming. + +# `scala-cli` to the rescue + +[scala-cli](https://scala-cli.virtuslab.org/) is a command-line interface to quickly develop and experiment with Scala, it's even on track to [becoming the new scala command](https://docs.scala-lang.org/sips/scala-cli.html). The interface has a lot of advantages, but one of the most important ones is that it makes learning, developing and building Scala scripts and small applications friction-less and easy to use. + +You can get `scala-cli` by following the installation instructions described here: [https://scala-cli.virtuslab.org/docs/overview](https://scala-cli.virtuslab.org/docs/overview#installation)#installation. The great part here is that once you have `scala-cli` installed, it will take care of the rest: Java runtimes, editor tooling, compilation targets(including a native target!) and you can even use dependencies in your scripts! + +## An example of setting up your script + +First off, let's create a new directory that will contain our script(s). + +```sh +mkdir myscript && cd myscript +``` + +Now we can use `scala-cli` to create all the files necessary for editor tooling to work: + +```sh +scala-cli setup-ide . +``` + +Finally, let's create a Scala file and try to compile it. + +```sh +touch Main.scala +scala-cli compile --watch Main.scala +``` + + +The last command also includes a `--watch` flag, so we can hack on our script and `scala-cli` will try to compile the file on every save. +This creates a very nice feedback loop! + +# Putting the fun in functional + +[Typelevel Toolkit](https://typelevel.org/toolkit/) uses `scala-cli` and Typelevel libraries to provide a runway for your next Scala script or command-line interface. You can use the toolkit with `scala-cli` with just a single line and you'll get [Cats Effect](https://typelevel.org/cats-effect/), [fs2](https://fs2.io) and a few other libraries to develop scripts quickly using pure functional programming. +
+Typelevel Toolkit shines with `scala-cli`, but it can also be used by sbt or mill if that is preferred. +

+More concretely this means your next ad-hoc script won't be Bash or Python spaghetti, but Scala code that can be a joy to hack on as time goes on, without the boilerplate. + +You can use the toolkit by using a +[scala-cli directive](https://scala-cli.virtuslab.org/docs/guides/using-directives) + +```scala +//> using dep "org.typelevel::toolkit::0.0.4" +``` + +This will pull in the `typelevel/toolkit` dependency and then you're just an import away from your first pure functional "Hello, World!": + +```scala +import cats.effect.* + +object Hello extends IOApp.Simple { + def run = IO.println("Hello, World!") +} +``` + +You can compile and run this program by using a single command: `scala-cli run Main.scala`. + + +A "Hello, World!" is only the start, the goal here is to make functional programming friendly and practical. As such, Typelevel toolkit comes with [examples](https://typelevel.org/toolkit/examples.html) that introduces beginners on how one can use the included libraries to achieve common tasks. + + +For the full list of libraries included in Typelevel Toolkit, please see the overview: [https://typelevel.org/toolkit/#overview](https://typelevel.org/toolkit/#overview). If you feel like anything is missing, [join the discussion](https://github.com/typelevel/toolkit/issues/1). + +# We can have nice things + +Typelevel libraries are production-proven, well tested, build upon rock solid semantics, and almost all have Scala 3 support. +However their entry-point is higher than your usual scripting language. Pure functional programming has a reputation of being hard to learn, and Typelevel Toolkit is a way to play in that world, without learning an entire ecosystem first. + +The toolkit includes, among others, a [HTTP client](https://http4s.org/), [CSV parsing library](https://fs2-data.gnieh.org/documentation/csv/) and functions for [handling files cross-platform](https://fs2.io/#/io), **with support for other runtimes besides the JVM**. This means that your scripts can run in a [JavaScript environment](https://scala-cli.virtuslab.org/docs/guides/scala-js), thanks to [scala-js]() or you can use [scala-native]() to get a [native binary](https://scala-cli.virtuslab.org/docs/guides/scala-native), just like Rust and Go. + +`scala-cli` again, makes things easy for us by having simple commands to compile to a certain target: + +```sh +# To compile to JavaScript +scala-cli Main.scala --js + +# To target native +scala-cli Main.scala --native +``` + +If you just want to explore Typelevel Toolkit, you can open up a REPL using a file that has the `using dep "org.typelevel::toolkit::0.0.4"` directive and you can use all the libraries in the REPL: + +```sh +scala-cli repl Main.scala +``` + +With `scala-cli`, there a few other cool things you get here: +- [export current build into sbt or mill](https://scala-cli.virtuslab.org/docs/guides/sbt-mill) +- [create and share gists](https://scala-cli.virtuslab.org/docs/cookbooks/gists) +- [package your script using GraalVM](https://scala-cli.virtuslab.org/docs/cookbooks/native-images) + +# Summary + +`scala-cli` is great. It's easy to get started with and great to use. Typelevel Toolkit leverages its versatility and provides a "pure functional standard library" in a single directive. This will enable you to create and develop scripts fast with high refactorability, an awesome developer experience and lots of functions that compose well! All those benefits while remaining beginner-friendly. \ No newline at end of file From 5595c4f53202d334c9719ece74306fa4f85630cb Mon Sep 17 00:00:00 2001 From: zetashift Date: Tue, 4 Apr 2023 22:19:39 +0200 Subject: [PATCH 2/7] Improve message about ScalaJS and Native --- collections/_posts/2023-04-03-typelevel_toolkit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/collections/_posts/2023-04-03-typelevel_toolkit.md b/collections/_posts/2023-04-03-typelevel_toolkit.md index a0a4d7c3..f1947ead 100644 --- a/collections/_posts/2023-04-03-typelevel_toolkit.md +++ b/collections/_posts/2023-04-03-typelevel_toolkit.md @@ -80,7 +80,7 @@ For the full list of libraries included in Typelevel Toolkit, please see the ove Typelevel libraries are production-proven, well tested, build upon rock solid semantics, and almost all have Scala 3 support. However their entry-point is higher than your usual scripting language. Pure functional programming has a reputation of being hard to learn, and Typelevel Toolkit is a way to play in that world, without learning an entire ecosystem first. -The toolkit includes, among others, a [HTTP client](https://http4s.org/), [CSV parsing library](https://fs2-data.gnieh.org/documentation/csv/) and functions for [handling files cross-platform](https://fs2.io/#/io), **with support for other runtimes besides the JVM**. This means that your scripts can run in a [JavaScript environment](https://scala-cli.virtuslab.org/docs/guides/scala-js), thanks to [scala-js]() or you can use [scala-native]() to get a [native binary](https://scala-cli.virtuslab.org/docs/guides/scala-native), just like Rust and Go. +The toolkit includes, among others, a [HTTP client](https://http4s.org/), [CSV parsing library](https://fs2-data.gnieh.org/documentation/csv/) and functions for [handling files cross-platform](https://fs2.io/#/io), **with support for other runtimes besides the JVM**. This means that your scripts can run in a [JavaScript environment](https://scala-cli.virtuslab.org/docs/guides/scala-js), thanks to [scala-js](https://www.scala-js.org/). Or you can use [scala-native](https://github.com/scala-native/scala-native) to get a [native binary](https://scala-cli.virtuslab.org/docs/guides/scala-native), just like Rust and Go! `scala-cli` again, makes things easy for us by having simple commands to compile to a certain target: From 5a32256356a4aa0835eed78faea35776e69fd2ca Mon Sep 17 00:00:00 2001 From: zetashift Date: Wed, 5 Apr 2023 19:29:04 +0200 Subject: [PATCH 3/7] Replace br tags with whitespace and improve REPL introduction --- collections/_posts/2023-04-03-typelevel_toolkit.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/collections/_posts/2023-04-03-typelevel_toolkit.md b/collections/_posts/2023-04-03-typelevel_toolkit.md index f1947ead..0ec23a95 100644 --- a/collections/_posts/2023-04-03-typelevel_toolkit.md +++ b/collections/_posts/2023-04-03-typelevel_toolkit.md @@ -45,9 +45,8 @@ This creates a very nice feedback loop! # Putting the fun in functional [Typelevel Toolkit](https://typelevel.org/toolkit/) uses `scala-cli` and Typelevel libraries to provide a runway for your next Scala script or command-line interface. You can use the toolkit with `scala-cli` with just a single line and you'll get [Cats Effect](https://typelevel.org/cats-effect/), [fs2](https://fs2.io) and a few other libraries to develop scripts quickly using pure functional programming. -
+ Typelevel Toolkit shines with `scala-cli`, but it can also be used by sbt or mill if that is preferred. -

More concretely this means your next ad-hoc script won't be Bash or Python spaghetti, but Scala code that can be a joy to hack on as time goes on, without the boilerplate. You can use the toolkit by using a @@ -92,10 +91,10 @@ scala-cli Main.scala --js scala-cli Main.scala --native ``` -If you just want to explore Typelevel Toolkit, you can open up a REPL using a file that has the `using dep "org.typelevel::toolkit::0.0.4"` directive and you can use all the libraries in the REPL: +If you just want to explore Typelevel Toolkit, you can quickly open a REPL using the following command: ```sh -scala-cli repl Main.scala +scala-cli repl --dep "org.typelevel::toolkit::0.0.4" ``` With `scala-cli`, there a few other cool things you get here: From 89e106a432de5128164cb7b12fa58c7c014e9e38 Mon Sep 17 00:00:00 2001 From: zetashift Date: Thu, 6 Apr 2023 13:39:04 +0200 Subject: [PATCH 4/7] Fix formatting of a subtitle because it rendered funky --- collections/_posts/2023-04-03-typelevel_toolkit.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/collections/_posts/2023-04-03-typelevel_toolkit.md b/collections/_posts/2023-04-03-typelevel_toolkit.md index 0ec23a95..bcc4377d 100644 --- a/collections/_posts/2023-04-03-typelevel_toolkit.md +++ b/collections/_posts/2023-04-03-typelevel_toolkit.md @@ -11,7 +11,7 @@ meta: Getting started in the wondrous world of functional programming using [Typelevel libraries](https://typelevel.org/projects) can be daunting. Before you can even write your first pure "Hello, World!" you'll need to install a Java runtime, editor tooling and build tools. Then you'll need to setup some project using [sbt]() or [mill](). As an added consequence, after all the setup, the idea of using these battle-tested libraries for small scripts will seem like a chore. This is where [Typelevel Toolkit](https://typelevel.org/toolkit/) comes in. It provides an easy start for beginning and experienced developers with Scala and functional programming. -# `scala-cli` to the rescue +# scala-cli to the rescue [scala-cli](https://scala-cli.virtuslab.org/) is a command-line interface to quickly develop and experiment with Scala, it's even on track to [becoming the new scala command](https://docs.scala-lang.org/sips/scala-cli.html). The interface has a lot of advantages, but one of the most important ones is that it makes learning, developing and building Scala scripts and small applications friction-less and easy to use. @@ -44,7 +44,9 @@ This creates a very nice feedback loop! # Putting the fun in functional -[Typelevel Toolkit](https://typelevel.org/toolkit/) uses `scala-cli` and Typelevel libraries to provide a runway for your next Scala script or command-line interface. You can use the toolkit with `scala-cli` with just a single line and you'll get [Cats Effect](https://typelevel.org/cats-effect/), [fs2](https://fs2.io) and a few other libraries to develop scripts quickly using pure functional programming. +[Typelevel Toolkit](https://typelevel.org/toolkit/) uses `scala-cli` and Typelevel libraries to provide a runway for your next Scala script or command-line interface. You can use the toolkit with `scala-cli` with just a single line and you'll get: +- [Cats Effect](https://typelevel.org/cats-effect/) +- [fs2](https://fs2.io) Typelevel Toolkit shines with `scala-cli`, but it can also be used by sbt or mill if that is preferred. More concretely this means your next ad-hoc script won't be Bash or Python spaghetti, but Scala code that can be a joy to hack on as time goes on, without the boilerplate. From 2490bbcd86c0c7b341118a904170b47d30b0da92 Mon Sep 17 00:00:00 2001 From: zetashift Date: Thu, 6 Apr 2023 13:57:41 +0200 Subject: [PATCH 5/7] Improve libraries included parts --- collections/_posts/2023-04-03-typelevel_toolkit.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/collections/_posts/2023-04-03-typelevel_toolkit.md b/collections/_posts/2023-04-03-typelevel_toolkit.md index bcc4377d..fc85f6b7 100644 --- a/collections/_posts/2023-04-03-typelevel_toolkit.md +++ b/collections/_posts/2023-04-03-typelevel_toolkit.md @@ -44,9 +44,14 @@ This creates a very nice feedback loop! # Putting the fun in functional -[Typelevel Toolkit](https://typelevel.org/toolkit/) uses `scala-cli` and Typelevel libraries to provide a runway for your next Scala script or command-line interface. You can use the toolkit with `scala-cli` with just a single line and you'll get: -- [Cats Effect](https://typelevel.org/cats-effect/) -- [fs2](https://fs2.io) +[Typelevel Toolkit](https://typelevel.org/toolkit/) uses `scala-cli` and Typelevel libraries to provide a runway for your next Scala script or command-line interface. With a single line, Typelevel Toolkit gives you: +- [Cats Effect](https://typelevel.org/cats-effect/) a production proven pure asynchronous runtime. +- [fs2](https://fs2.io) an amazing streaming I/O library. +- [http4s-ember-client](https://http4s.org/v0.23/docs/client.html) for a full-fledged HTTP client. +- [circe](https://circe.github.io/circe/) for dealing with JSON. +- [MUnit](https://github.com/typelevel/munit-cats-effect) an unit testing library and an integration to easily unit test pure functional programs. +- [fs2-data-csv](https://fs2-data.gnieh.org/documentation/csv/) for handling CSV files. +- [decline](https://ben.kirw.in/decline/effect.html) a composable commandline parser and it's integration with Cats Effect. Typelevel Toolkit shines with `scala-cli`, but it can also be used by sbt or mill if that is preferred. More concretely this means your next ad-hoc script won't be Bash or Python spaghetti, but Scala code that can be a joy to hack on as time goes on, without the boilerplate. @@ -81,7 +86,7 @@ For the full list of libraries included in Typelevel Toolkit, please see the ove Typelevel libraries are production-proven, well tested, build upon rock solid semantics, and almost all have Scala 3 support. However their entry-point is higher than your usual scripting language. Pure functional programming has a reputation of being hard to learn, and Typelevel Toolkit is a way to play in that world, without learning an entire ecosystem first. -The toolkit includes, among others, a [HTTP client](https://http4s.org/), [CSV parsing library](https://fs2-data.gnieh.org/documentation/csv/) and functions for [handling files cross-platform](https://fs2.io/#/io), **with support for other runtimes besides the JVM**. This means that your scripts can run in a [JavaScript environment](https://scala-cli.virtuslab.org/docs/guides/scala-js), thanks to [scala-js](https://www.scala-js.org/). Or you can use [scala-native](https://github.com/scala-native/scala-native) to get a [native binary](https://scala-cli.virtuslab.org/docs/guides/scala-native), just like Rust and Go! +The libraries in the toolkit compliment each other and target common usecases, thus providing a coherent mini-ecosystem, that scales extremely well, thanks to Cats Effect. **With support for other runtimes besides the JVM**. This means that your scripts can run in a [JavaScript environment](https://scala-cli.virtuslab.org/docs/guides/scala-js), thanks to [scala-js](https://www.scala-js.org/). Or you can use [scala-native](https://github.com/scala-native/scala-native) to get a [native binary](https://scala-cli.virtuslab.org/docs/guides/scala-native), just like Rust and Go! `scala-cli` again, makes things easy for us by having simple commands to compile to a certain target: From 3488fa4db5c6c23420fe0fbd14bb73d23b2b4b8e Mon Sep 17 00:00:00 2001 From: zetashift Date: Fri, 7 Apr 2023 15:41:42 +0200 Subject: [PATCH 6/7] Fix scala-cli installation link Co-authored-by: Justin du Coeur, AKA Mark Waks --- collections/_posts/2023-04-03-typelevel_toolkit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/collections/_posts/2023-04-03-typelevel_toolkit.md b/collections/_posts/2023-04-03-typelevel_toolkit.md index fc85f6b7..fb173519 100644 --- a/collections/_posts/2023-04-03-typelevel_toolkit.md +++ b/collections/_posts/2023-04-03-typelevel_toolkit.md @@ -15,7 +15,7 @@ Getting started in the wondrous world of functional programming using [Typelevel [scala-cli](https://scala-cli.virtuslab.org/) is a command-line interface to quickly develop and experiment with Scala, it's even on track to [becoming the new scala command](https://docs.scala-lang.org/sips/scala-cli.html). The interface has a lot of advantages, but one of the most important ones is that it makes learning, developing and building Scala scripts and small applications friction-less and easy to use. -You can get `scala-cli` by following the installation instructions described here: [https://scala-cli.virtuslab.org/docs/overview](https://scala-cli.virtuslab.org/docs/overview#installation)#installation. The great part here is that once you have `scala-cli` installed, it will take care of the rest: Java runtimes, editor tooling, compilation targets(including a native target!) and you can even use dependencies in your scripts! +You can get `scala-cli` by following the installation instructions described here: [https://scala-cli.virtuslab.org/docs/overview#installation](https://scala-cli.virtuslab.org/docs/overview#installation). The great part here is that once you have `scala-cli` installed, it will take care of the rest: Java runtimes, editor tooling, compilation targets(including a native target!) and you can even use dependencies in your scripts! ## An example of setting up your script From 39f3c532fe99fd0279c6bee157ad3eef4f148c80 Mon Sep 17 00:00:00 2001 From: zetashift Date: Fri, 7 Apr 2023 17:39:22 +0200 Subject: [PATCH 7/7] Fix sbt and mill links --- collections/_posts/2023-04-03-typelevel_toolkit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/collections/_posts/2023-04-03-typelevel_toolkit.md b/collections/_posts/2023-04-03-typelevel_toolkit.md index fb173519..14fed6f7 100644 --- a/collections/_posts/2023-04-03-typelevel_toolkit.md +++ b/collections/_posts/2023-04-03-typelevel_toolkit.md @@ -9,7 +9,7 @@ meta: pygments: true --- -Getting started in the wondrous world of functional programming using [Typelevel libraries](https://typelevel.org/projects) can be daunting. Before you can even write your first pure "Hello, World!" you'll need to install a Java runtime, editor tooling and build tools. Then you'll need to setup some project using [sbt]() or [mill](). As an added consequence, after all the setup, the idea of using these battle-tested libraries for small scripts will seem like a chore. This is where [Typelevel Toolkit](https://typelevel.org/toolkit/) comes in. It provides an easy start for beginning and experienced developers with Scala and functional programming. +Getting started in the wondrous world of functional programming using [Typelevel libraries](https://typelevel.org/projects) can be daunting. Before you can even write your first pure "Hello, World!" you'll need to install a Java runtime, editor tooling and build tools. Then you'll need to setup some project using [sbt](https://www.scala-sbt.org/) or [mill](https://github.com/com-lihaoyi/mill). As an added consequence, after all the setup, the idea of using these battle-tested libraries for small scripts will seem like a chore. This is where [Typelevel Toolkit](https://typelevel.org/toolkit/) comes in. It provides an easy start for beginning and experienced developers with Scala and functional programming. # scala-cli to the rescue