2019-12-30 08:51:20 +00:00
< img src = "logo/babashka.svg" width = "425px" >
2019-08-09 12:51:42 +00:00
[](https://circleci.com/gh/borkdude/babashka/tree/master)
[](https://clojars.org/borkdude/babashka)
2019-12-12 11:18:24 +00:00
[](https://app.slack.com/client/T03RZGPFR/CLX41ASCS)
2019-12-19 13:01:14 +00:00
<!-- [](https://cljdoc.org/d/borkdude/babashka/CURRENT) -->
2019-08-09 12:51:42 +00:00
2019-11-07 11:46:14 +00:00
A Clojure [babushka ](https://en.wikipedia.org/wiki/Headscarf ) for the grey areas of Bash.
2019-08-12 12:42:45 +00:00
2019-12-20 15:51:41 +00:00
< blockquote class = "twitter-tweet" data-lang = "en" >
2019-12-30 12:38:05 +00:00
< p lang = "en" dir = "ltr" > Life's too short to remember how to write Bash code. I feel liberated.< / p >
2019-12-20 15:51:41 +00:00
—
< a href = "https://github.com/laheadle" > @laheadle< / a > on Clojurians Slack
< / blockquote >
2019-08-12 12:42:45 +00:00
## Quickstart
``` shellsession
$ bash < (curl -s https://raw.githubusercontent.com/borkdude/babashka/master/install)
2019-12-20 22:51:24 +00:00
$ ls | bb --time -i '(filter #(-> % io/file .isDirectory) *input* )'
2019-08-18 10:44:51 +00:00
("doc" "resources" "sci" "script" "src" "target" "test")
2019-08-18 21:17:20 +00:00
bb took 4ms.
2019-08-12 12:42:45 +00:00
```
## Rationale
2019-11-03 22:13:06 +00:00
The sweet spot for babashka is executing Clojure snippets or scripts in the same
2019-11-07 11:46:14 +00:00
space where you would use Bash.
2019-08-15 09:05:59 +00:00
2019-11-07 11:25:51 +00:00
As one user described it:
2019-11-07 11:46:14 +00:00
> I’ m quite at home in Bash most of the time, but there’ s a substantial grey area of things that are too complicated to be simple in bash, but too simple to be worth writing a clj/s script for. Babashka really seems to hit the sweet spot for those cases.
2019-11-07 11:25:51 +00:00
2019-11-03 20:28:16 +00:00
Goals:
2019-11-03 22:14:57 +00:00
* Fast startup / low latency. This is achieved by compiling to native using [GraalVM ](https://github.com/oracle/graal ).
2019-11-03 22:18:32 +00:00
* Familiarity and portability. Keep migration barriers between bash and Clojure as low as possible by:
- Gradually introducing Clojure expressions to existing bash scripts
2019-11-03 22:19:30 +00:00
- Scripts written in babashka should also be able to run on the JVM without major changes.
2019-11-03 20:28:16 +00:00
* Multi-threading support similar to Clojure on the JVM
* Batteries included (clojure.tools.cli, core.async, ...)
Non-goals:
* Performance
2019-11-15 23:25:36 +00:00
* Provide a mixed Clojure/bash DSL (see portability).
2019-11-03 20:28:16 +00:00
* Replace existing shells. Babashka is a tool you can use inside existing shells like bash and it is designed to play well with them. It does not aim to replace them.
2019-08-17 22:31:39 +00:00
2019-12-28 22:18:44 +00:00
Babashka uses [sci ](https://github.com/borkdude/sci ) for interpreting Clojure. Sci
2019-12-28 22:21:15 +00:00
implements a subset of Clojure and is not as performant as compiled code. If your script is taking more than a few seconds, Clojure on the JVM may be a better fit.
2019-09-08 21:31:24 +00:00
2019-10-07 21:11:49 +00:00
Read more about the differences with Clojure [here ](#differences-with-clojure ).
2019-10-07 21:09:35 +00:00
2019-09-08 21:31:24 +00:00
## Status
2019-12-20 09:34:56 +00:00
Experimental. Breaking changes are expected to happen at this phase. Keep an eye
on [CHANGES.md ](CHANGES.md ) for a list of breaking changes.
2019-09-08 21:31:24 +00:00
## Examples
2019-08-17 22:31:39 +00:00
``` shellsession
2019-12-20 22:51:24 +00:00
$ ls | bb -i '*input*'
2019-09-08 21:31:24 +00:00
["LICENSE" "README.md" "bb" "doc" "pom.xml" "project.clj" "reflection.json" "resources" "script" "src" "target" "test"]
2019-08-17 22:31:39 +00:00
2019-12-20 22:51:24 +00:00
$ ls | bb -i '(count *input* )'
2019-09-08 21:31:24 +00:00
12
2019-08-17 22:31:39 +00:00
2019-12-20 22:51:24 +00:00
$ bb '(vec (dedupe *input* ))' <<< '[1 1 1 1 2]'
2019-09-08 21:31:24 +00:00
[1 2]
2019-08-15 09:16:15 +00:00
2019-12-20 22:51:24 +00:00
$ bb '(filterv :foo *input* )' <<< '[{:foo 1} {:bar 2}]'
2019-09-08 21:31:24 +00:00
[{:foo 1}]
2019-08-18 05:30:29 +00:00
2019-12-20 22:51:24 +00:00
$ bb '(#(+ %1 %2 %3) 1 2 *input* )' << < 3
2019-09-08 21:31:24 +00:00
6
2019-08-09 12:51:42 +00:00
2019-12-20 22:51:24 +00:00
$ ls | bb -i '(filterv #(re-find #"reflection" %) *input* )'
2019-09-08 21:31:24 +00:00
["reflection.json"]
$ bb '(run! #(shell/sh "touch" (str "/tmp/test/" %)) (range 100))'
2019-12-20 22:51:24 +00:00
$ ls /tmp/test | bb -i '*input*'
2019-09-08 21:31:24 +00:00
["0" "1" "10" "11" "12" "13" "14" "15" "16" "17" "18" "19" "2" "20" "21" ...]
2019-12-20 22:51:24 +00:00
$ bb -O '(repeat "dude")' | bb --stream '(str *input* "rino")' | bb -I '(take 3 *input* )'
2019-09-08 21:31:24 +00:00
("duderino" "duderino" "duderino")
```
More examples can be found in the [gallery ](#gallery ).
2019-08-09 12:51:42 +00:00
2019-08-09 14:02:08 +00:00
## Installation
2019-08-11 07:27:45 +00:00
### Brew
2019-08-09 14:02:08 +00:00
Linux and macOS binaries are provided via brew.
Install:
brew install borkdude/brew/babashka
Upgrade:
brew upgrade babashka
2019-11-21 10:14:38 +00:00
### Arch (Linux)
`babashka` is [available ](https://aur.archlinux.org/packages/babashka-bin/ ) in the [Arch User Repository ](https://aur.archlinux.org ). It can be installed using your favorite [AUR ](https://aur.archlinux.org ) helper such as
[yay ](https://github.com/Jguer/yay ), [yaourt ](https://github.com/archlinuxfr/yaourt ), [apacman ](https://github.com/oshazard/apacman ) and [pacaur ](https://github.com/rmarquis/pacaur ). Here is an example using `yay` :
yay -S babashka-bin
2019-08-11 07:27:45 +00:00
### Installer script
Install via the installer script:
``` shellsession
$ bash < (curl -s https://raw.githubusercontent.com/borkdude/babashka/master/install)
```
By default this will install into `/usr/local/bin` . To change this, provide the directory name:
``` shellsession
$ bash < (curl -s https://raw.githubusercontent.com/borkdude/babashka/master/install) /tmp
```
### Download
2019-08-09 14:02:08 +00:00
You may also download a binary from [Github ](https://github.com/borkdude/babashka/releases ).
2019-08-09 13:48:54 +00:00
## Usage
2019-08-09 12:51:42 +00:00
2019-08-09 17:58:11 +00:00
``` shellsession
2019-12-13 17:16:13 +00:00
Usage: bb [ -i | -I ] [ -o | -O ] [ --stream ] [--verbose]
2020-01-01 22:27:25 +00:00
[ ( --classpath | -cp ) < cp > ] [ --uberscript < file > ]
[ ( --main | -m ) < main-namespace > | -e < expression > | -f < file > |
--repl | --socket-repl [< host > :]< port > ]
[ arg* ]
2019-08-18 10:33:54 +00:00
Options:
2019-08-09 17:58:11 +00:00
2019-12-28 21:52:56 +00:00
--help, -h or -? Print this help text.
--version Print the current version of babashka.
2020-01-01 22:27:25 +00:00
2019-12-28 21:52:56 +00:00
-i Bind *input* to a lazy seq of lines from stdin.
-I Bind *input* to a lazy seq of EDN values from stdin.
-o Write lines to stdout.
-O Write EDN values to stdout.
--verbose Print entire stacktrace in case of exception.
--stream Stream over lines or EDN values from stdin. Combined with -i or -I *input* becomes a single value per iteration.
2020-01-01 22:27:25 +00:00
--uberscript < file > Collect preloads, -e, -f and -m and all required namespaces from the classpath into a single executable file.
2019-12-28 21:52:56 +00:00
-e, --eval < expr > Evaluate an expression.
-f, --file < path > Evaluate a file.
-cp, --classpath Classpath to use.
-m, --main < ns > Call the -main function from namespace with args.
--repl Start REPL
--socket-repl Start socket REPL. Specify port (e.g. 1666) or host and port separated by colon (e.g. 127.0.0.1:1666).
--time Print execution time before exiting.
2019-09-06 14:40:50 +00:00
If neither -e, -f, or --socket-repl are specified, then the first argument that is not parsed as a option is treated as a file if it exists, or as an expression otherwise.
Everything after that is bound to *command-line-args* .
2019-08-18 10:33:54 +00:00
```
2019-08-14 11:38:39 +00:00
The `clojure.core` functions are accessible without a namespace alias.
2019-09-08 21:31:24 +00:00
The following namespaces are required by default and available through the
2019-12-10 08:44:41 +00:00
pre-defined aliases in the `user` namespace. You may use `require` + `:as`
and/or `:refer` on these namespaces. If not all vars are available, they are
enumerated explicitly.
2019-08-14 11:38:39 +00:00
- `clojure.string` aliased as `str`
- `clojure.set` aliased as `set`
2019-08-18 10:33:54 +00:00
- `clojure.edn` aliased as `edn` :
- `read-string`
2019-12-30 10:28:07 +00:00
- `clojure.java.shell` aliases as `shell`
2019-08-18 10:33:54 +00:00
- `clojure.java.io` aliased as `io` :
2019-12-24 09:01:32 +00:00
- `as-relative-path` , `as-url` , `copy` , `delete-file` , `file` , `input-stream` ,
2019-12-29 22:37:57 +00:00
`make-parents` , `output-stream` , `reader` , `resource` , `writer`
2019-12-24 09:01:32 +00:00
- `clojure.main` : `repl`
2019-09-07 08:43:53 +00:00
- [`clojure.core.async` ](https://clojure.github.io/core.async/ ) aliased as
`async` . The `alt` and `go` macros are not available but `alts!!` does work as
it is a function.
2019-09-08 21:07:58 +00:00
- [`clojure.tools.cli` ](https://github.com/clojure/tools.cli ) aliased as `tools.cli`
2019-11-11 20:14:30 +00:00
- [`clojure.data.csv` ](https://github.com/clojure/data.csv ) aliased as `csv`
2019-12-10 08:44:41 +00:00
- [`cheshire.core` ](https://github.com/dakrone/cheshire ) aliased as `json`
2019-08-14 11:38:39 +00:00
2019-12-31 13:23:54 +00:00
A selection of java classes are available, see `reflection.json` .
Babashka supports `import` : `(import clojure.lang.ExceptionInfo)` .
2019-11-27 13:15:29 +00:00
Babashka supports a subset of the `ns` form where you may use `:require` and `:import` :
``` shellsession
(ns foo
(:require [clojure.string :as str])
(:import clojure.lang.ExceptionInfo))
2019-11-15 23:25:36 +00:00
```
2019-11-27 13:15:29 +00:00
For the unsupported parts of the ns form, you may use [reader
conditionals](#reader-conditionals) to maintain compatibility with JVM Clojure.
2019-12-20 20:17:27 +00:00
### Input and output flags
2019-08-15 04:28:00 +00:00
2019-12-20 22:51:24 +00:00
In one-liners the `*input*` value may come in handy. It contains the input read from stdin as EDN by default. If you want to read in text, use the `-i` flag, which binds `*input*` to a lazy seq of lines of text. If you want to read multiple EDN values, use the `-I` flag. The `-o` option prints the result as lines of text. The `-O` option prints the result as lines of EDN values.
2019-12-20 20:17:27 +00:00
The following table illustrates the combination of options for commands of the form
2019-12-20 22:51:24 +00:00
echo "{{Input}}" | bb {{Input flags}} {{Output flags}} "*input*"
2019-12-20 20:17:27 +00:00
2019-12-20 22:51:24 +00:00
| Input | Input flags | Output flag | `*input*` | Output |
2019-12-20 20:17:27 +00:00
|----------------|-------------|-------------|---------------|----------|
2019-12-20 20:23:51 +00:00
| `{:a 1}` < br > `{:a 2}` | | | `{:a 1}` | `{:a 1}` |
2019-12-20 20:17:27 +00:00
| hello < br > bye | `-i` | | `("hello" "bye")` | `("hello" "bye")` |
| hello < br > bye | `-i` | `-o` | `("hello" "bye")` | hello < br > bye |
2019-12-20 20:23:51 +00:00
| `{:a 1}` < br > `{:a 2}` | `-I` | | `({:a 1} {:a 2})` | `({:a 1} {:a 2})` |
2019-12-20 20:17:27 +00:00
| `{:a 1}` < br > `{:a 2}` | `-I` | `-O` | `({:a 1} {:a 2})` | `{:a 1}` < br > `{:a 2}` |
2019-12-20 23:06:00 +00:00
When combined with the `--stream` option, the expression is executed for each value in the input:
2019-12-20 20:17:27 +00:00
``` clojure
2019-12-20 22:51:24 +00:00
$ echo '{:a 1} {:a 2}' | bb --stream '*input*'
2019-12-20 20:17:27 +00:00
{:a 1}
{:a 2}
```
2019-12-21 10:39:28 +00:00
### Current file path
2019-12-21 10:50:05 +00:00
The var `*file*` contains the full path of the file that is currently being
executed:
2019-12-21 10:39:28 +00:00
``` shellsession
$ cat example.clj
(prn *file* )
$ bb example.clj
"/Users/borkdude/example.clj"
```
2019-12-20 20:17:27 +00:00
### Command-line arguments
Command-line arguments can be retrieved using `*command-line-args*` .
### Additional functions
2019-08-10 16:50:48 +00:00
2019-09-04 12:37:07 +00:00
Additionally, babashka adds the following functions:
2019-10-14 09:24:37 +00:00
- `wait/wait-for-port` . Usage:
2019-09-04 12:37:07 +00:00
``` clojure
2019-10-14 09:24:37 +00:00
(wait/wait-for-port "localhost" 8080)
(wait/wait-for-port "localhost" 8080 {:timeout 1000 :pause 1000})
2019-09-04 12:37:07 +00:00
```
2019-10-14 09:24:37 +00:00
Waits for TCP connection to be available on host and port. Options map supports `:timeout` and `:pause` . If `:timeout` is provided and reached, `:default` 's value (if any) is returned. The `:pause` option determines the time waited between retries.
- `wait/wait-for-path` . Usage:
``` clojure
(wait/wait-for-path "/tmp/wait-path-test")
(wait/wait-for-path "/tmp/wait-path-test" {:timeout 1000 :pause 1000})
```
Waits for file path to be available. Options map supports `:default` , `:timeout` and `:pause` . If `:timeout` is provided and reached, `:default` 's value (if any) is returned. The `:pause` option determines the time waited between retries.
2019-09-04 12:37:07 +00:00
2019-09-07 08:43:53 +00:00
- `sig/pipe-signal-received?` . Usage:
``` clojure
(sig/pipe-signal-received?)
```
Returns true if `PIPE` signal was received. Example:
``` shellsession
$ bb '((fn [x] (println x) (when (not (sig/pipe-signal-received?)) (recur (inc x)))) 0)' | head -n2
1
2
```
2019-08-14 11:38:39 +00:00
## Running a file
2019-08-15 10:55:58 +00:00
Scripts may be executed from a file using `-f` or `--file` :
2019-08-14 11:38:39 +00:00
``` shellsession
2019-08-15 07:08:30 +00:00
bb -f download_html.clj
2019-08-14 11:38:39 +00:00
```
2019-08-18 05:34:47 +00:00
Files can also be loaded inline using `load-file` :
``` shellsession
bb '(load-file "script.clj")'
```
2019-08-14 11:38:39 +00:00
Using `bb` with a shebang also works:
2019-08-15 07:04:14 +00:00
``` clojure
2019-09-07 08:49:31 +00:00
#!/usr/bin/env bb
2019-08-15 04:28:00 +00:00
(defn get-url [url]
(println "Fetching url:" url)
(let [{:keys [:exit :err :out]} (shell/sh "curl" "-sS" url)]
(if (zero? exit) out
(do (println "ERROR:" err)
(System/exit 1)))))
(defn write-html [file html]
2019-08-15 07:08:30 +00:00
(println "Writing file:" file)
2019-08-15 04:28:00 +00:00
(spit file html))
(let [[url file] *command-line-args* ]
(when (or (empty? url) (empty? file))
(println "Usage: < url > < file > ")
(System/exit 1))
(write-html file (get-url url)))
(System/exit 0)
2019-08-14 11:38:39 +00:00
```
2019-08-15 08:41:37 +00:00
``` shellsession
$ ./download_html.clj
Usage: < url > < file >
$ ./download_html.clj https://www.clojure.org /tmp/clojure.org.html
Fetching url: https://www.clojure.org
Writing file: /tmp/clojure.org.html
```
2019-09-07 08:49:31 +00:00
If `/usr/bin/env` doesn't work for you, you can use the following workaround:
``` shellsession
$ cat script.clj
#!/bin/sh
#_(
"exec" "bb" "$0" hello "$@"
)
(prn *command-line-args* )
./script.clj 1 2 3
("hello" "1" "2" "3")
```
2019-12-12 22:07:35 +00:00
## Preloads
The environment variable `BABASHKA_PRELOADS` allows to define code that will be
available in all subsequent usages of babashka.
``` shellsession
BABASHKA_PRELOADS='(defn foo [x] (+ x 2))'
BABASHKA_PRELOADS=$BABASHKA_PRELOADS' (defn bar [x] (* x 2))'
export BABASHKA_PRELOADS
```
Note that you can concatenate multiple expressions. Now you can use these functions in babashka:
``` shellsession
2019-12-20 22:51:24 +00:00
$ bb '(-> (foo *input* ) bar)' << < 1
2019-12-12 22:07:35 +00:00
6
```
You can also preload an entire file using `load-file` :
``` shellsession
export BABASHKA_PRELOADS='(load-file "my_awesome_prelude.clj")'
```
2019-12-20 22:51:24 +00:00
Note that `*input*` is not available in preloads.
2019-12-12 22:07:35 +00:00
## Classpath
Babashka accepts a `--classpath` option that will be used to search for
namespaces and load them:
``` clojure
$ cat src/my/namespace.clj
(ns my.namespace)
(defn -main [& _args]
(println "Hello from my namespace!"))
$ bb --classpath src --main my.namespace
Hello from my namespace!
```
Note that you can use the `clojure` tool to produce classpaths and download dependencies:
``` shellsession
$ cat deps.edn
{:deps
2019-12-28 21:52:56 +00:00
{my_gist_script
{:git/url "https://gist.github.com/borkdude/263b150607f3ce03630e114611a4ef42"
:sha "cfc761d06dfb30bb77166b45d439fe8fe54a31b8"}}
:aliases {:my-script {:main-opts ["-m" "my-gist-script"]}}}
2019-12-12 22:07:35 +00:00
$ CLASSPATH=$(clojure -Spath)
$ bb --classpath "$CLASSPATH" --main my-gist-script
Hello from gist script!
```
If there is no `--classpath` argument, the `BABASHKA_CLASSPATH` environment
2019-12-13 17:42:38 +00:00
variable will be used:
2019-12-12 22:07:35 +00:00
``` shellsession
$ export BABASHKA_CLASSPATH=$(clojure -Spath)
$ export BABASHKA_PRELOADS="(require '[my-gist-script])"
$ bb "(my-gist-script/-main)"
Hello from gist script!
```
2019-12-28 21:52:56 +00:00
Using the [deps.clj ](https://github.com/borkdude/deps.clj/ ) script, you can also
pass the classpath and main opts to `bb` :
``` shell
2019-12-28 22:06:48 +00:00
$ deps.clj -A:my-script -Scommand "bb -cp {{classpath}} {{main-opts}}"
2019-12-28 21:52:56 +00:00
Hello from gist script!
```
## Uberscript
2019-12-28 21:55:01 +00:00
The `--uberscript` option collects the expressions in
2019-12-28 21:52:56 +00:00
`BABASHKA_PRELOADS` , the command line expression or file, the main entrypoint
and all required namespaces from the classpath into a single file. This can be
2019-12-28 22:50:05 +00:00
convenient for debugging and deployment.
2019-12-28 21:52:56 +00:00
Given the `deps.edn` from above:
2019-12-28 22:04:38 +00:00
``` clojure
2019-12-28 22:06:48 +00:00
$ deps.clj -A:my-script -Scommand "bb -cp {{classpath}} {{main-opts}} --uberscript my-script.clj"
2019-12-28 21:52:56 +00:00
$ cat my-script.clj
(ns my-gist-script)
(defn -main [& args]
2019-12-28 22:11:25 +00:00
(println "Hello from gist script!"))
2019-12-28 23:15:07 +00:00
(ns user (:require [my-gist-script]))
(apply my-gist-script/-main *command-line-args* )
2019-12-28 21:52:56 +00:00
$ bb my-script.clj
Hello from gist script!
```
2019-09-11 21:37:25 +00:00
## Parsing command line arguments
Babashka ships with `clojure.tools.cli` :
``` clojure
(require '[clojure.tools.cli :refer [parse-opts]])
(def cli-options
;; An option with a required argument
[["-p" "--port PORT" "Port number"
:default 80
:parse-fn #(Integer/parseInt %)
:validate [#(< 0 % 0x10000 ) " Must be a number between 0 and 65536 " ] ]
["-h" "--help"]])
(:options (parse-opts *command-line-args* cli-options))
```
``` shellsession
$ bb script.clj
{:port 80}
$ bb script.clj -h
{:port 80, :help true}
```
2019-10-26 21:53:10 +00:00
## Reader conditionals
Babashka supports reader conditionals using the `:bb` feature:
``` clojure
2019-10-26 22:01:32 +00:00
$ cat example.clj
2019-10-26 21:53:10 +00:00
#?(:clj (in-ns 'foo) :bb (println "babashka doesn't support in-ns yet!"))
$ ./bb example.clj
babashka doesn't support in-ns yet!
```
2019-08-31 18:17:36 +00:00
## Socket REPL
Start the socket REPL like this:
``` shellsession
$ bb --socket-repl 1666
Babashka socket REPL started at localhost:1666
```
Now you can connect with your favorite socket REPL client:
``` shellsession
$ rlwrap nc 127.0.0.1 1666
2019-08-31 19:22:31 +00:00
Babashka v0.0.14 REPL.
2019-08-31 18:17:36 +00:00
Use :repl/quit or :repl/exit to quit the REPL.
Clojure rocks, Bash reaches.
bb=> (+ 1 2 3)
6
bb=> :repl/quit
$
```
A socket REPL client for Emacs is
[inf-clojure ](https://github.com/clojure-emacs/inf-clojure ).
2019-09-04 12:37:07 +00:00
## Spawning and killing a process
2019-12-17 10:27:40 +00:00
Use the `java.lang.ProcessBuilder` class.
2019-09-04 12:37:07 +00:00
Example:
``` clojure
2019-12-17 10:27:40 +00:00
user=> (def ws (-> (ProcessBuilder. ["python" "-m" "SimpleHTTPServer" "1777"]) (.start)))
#'user/ws
user=> (wait/wait-for-port "localhost" 1777)
{:host "localhost", :port 1777, :took 2}
user=> (.destroy ws)
nil
2019-09-04 12:37:07 +00:00
```
2019-12-17 10:27:40 +00:00
Also see this [example ](examples/process_builder.clj ).
2019-09-07 08:43:53 +00:00
## Async
2019-12-17 10:27:40 +00:00
Apart from `future` and `pmap` for creating threads, you may use the `async`
namespace, which maps to `clojure.core.async` , for asynchronous scripting. The
following example shows how to get first available value from two different
processes:
2019-09-07 08:43:53 +00:00
``` clojure
bb '
(defn async-command [& args]
(async/thread (apply shell/sh "bash" "-c" args)))
(-> (async/alts!! [(async-command "sleep 2 & & echo process 1")
(async-command "sleep 1 & & echo process 2")])
first :out str/trim println)'
process 2
```
2019-10-07 21:11:49 +00:00
## Differences with Clojure
2019-10-07 21:09:35 +00:00
Babashka is implemented using the [Small Clojure
Interpreter](https://github.com/borkdude/sci). This means that a snippet or
script is not compiled to JVM bytecode, but executed form by form by a runtime
which implements a subset of Clojure. Babashka is compiled to a native binary
using [GraalVM ](https://github.com/oracle/graal ). It comes with a selection of
built-in namespaces and functions from Clojure and other useful libraries. The
data types (numbers, strings, persistent collections) are the
same. Multi-threading is supported (`pmap`, `future` ).
2019-10-07 21:11:49 +00:00
Differences with Clojure:
2019-10-07 21:09:35 +00:00
2019-11-15 23:25:36 +00:00
- A subset of Java classes are supported.
2019-10-07 21:09:35 +00:00
2019-12-12 22:07:35 +00:00
- Only the `clojure.core` , `clojure.set` , `clojure.string` and `clojure.walk`
namespaces are available from Clojure.
2019-10-07 21:09:35 +00:00
- Interpretation comes with overhead. Therefore tight loops are likely slower
than in Clojure on the JVM.
- No support for unboxed types.
2019-12-20 09:46:31 +00:00
## External resources
2019-12-25 13:49:29 +00:00
### Tools and libraries
2019-12-24 10:31:31 +00:00
The following libraries are known to work with Babashka:
2019-12-25 13:49:29 +00:00
#### [deps.clj](https://github.com/borkdude/deps.clj)
A port of the [clojure ](https://github.com/clojure/brew-install/ ) bash script to
2019-12-29 13:56:16 +00:00
Clojure / babashka.
#### [spartan.test](https://github.com/borkdude/spartan.test/)
A minimal test framework compatible with babashka.
2019-12-25 13:49:29 +00:00
2019-12-24 10:31:31 +00:00
#### [clj-http-lite](https://github.com/borkdude/clj-http-lite)
2019-12-25 13:49:29 +00:00
This fork does not depend on any other libraries. Example:
2019-12-24 10:31:31 +00:00
``` shell
$ export BABASHKA_CLASSPATH="$(clojure -Sdeps '{:deps {limit-break {:git/url "https://github.com/borkdude/clj-http-lite" :sha "f44ebe45446f0f44f2b73761d102af3da6d0a13e"}}}' -Spath)"
$ bb "(require '[clj-http.lite.client :as client]) (:status (client/get \"https://www.clojure.org\"))"
200
```
#### [limit-break](https://github.com/technomancy/limit-break)
2019-12-25 13:49:29 +00:00
A debug REPL library. Example:
2019-12-24 10:31:31 +00:00
``` shell
$ export BABASHKA_CLASSPATH="$(clojure -Sdeps '{:deps {limit-break {:git/url "https://github.com/technomancy/limit-break" :sha "050fcfa0ea29fe3340927533a6fa6fffe23bfc2f" :deps/manifest :deps}}}' -Spath)"
$ bb "(require '[limit.break :as lb]) (let [x 1] (lb/break))"
Babashka v0.0.49 REPL.
Use :repl/quit or :repl/exit to quit the REPL.
Clojure rocks, Bash reaches.
break> x
1
```
2019-12-20 09:46:31 +00:00
### Blogs
2019-12-20 09:45:07 +00:00
2019-12-21 20:05:40 +00:00
- [Clojure Start Time in 2019 ](https://stuartsierra.com/2019/12/21/clojure-start-time-in-2019 ) by Stuart Sierra
2019-12-20 09:45:07 +00:00
- [Advent of Random
Hacks](https://lambdaisland.com/blog/2019-12-19-advent-of-parens-19-advent-of-random-hacks)
by Arne Brasseur
- [Clojure in the Shell ](https://lambdaisland.com/blog/2019-12-05-advent-of-parens-5-clojure-in-the-shell ) by Arne Brasseur
- [Clojure Tool ](https://purelyfunctional.tv/issues/purelyfunctional-tv-newsletter-351-clojure-tool-babashka/ ) by Eric Normand
2019-09-06 13:31:54 +00:00
## Developing Babashka
To work on Babashka itself make sure Git submodules are checked out.
``` shellsession
$ git clone https://github.com/borkdude/babashka --recursive
```
To update later on:
``` shellsession
$ git submodule update --recursive
```
You need [Leiningen ](https://leiningen.org/ ), and for building binaries you need GraalVM.
### REPL
`lein repl` will get you a standard REPL/nREPL connection. To work on tests use `lein with-profiles +test repl` .
2019-12-16 20:44:20 +00:00
### Generate reflection.json file
lein with-profiles +reflection run
2019-09-06 13:31:54 +00:00
### Test
2019-08-09 12:51:42 +00:00
2019-10-14 09:24:37 +00:00
Test on the JVM (for development):
2019-08-09 12:51:42 +00:00
script/test
Test the native version:
BABASHKA_TEST_ENV=native script/test
2019-09-06 13:31:54 +00:00
### Build
2019-08-17 20:27:13 +00:00
To build this project, set `$GRAALVM_HOME` to the GraalVM distribution directory.
Then run:
2019-08-09 12:51:42 +00:00
script/compile
2019-08-13 07:20:48 +00:00
## Related projects
- [planck ](https://planck-repl.org/ )
- [joker ](https://github.com/candid82/joker )
- [closh ](https://github.com/dundalek/closh )
- [lumo ](https://github.com/anmonteiro/lumo )
2019-08-10 16:50:48 +00:00
## Gallery
Here's a gallery of more useful examples. Do you have a useful example? PR
welcome!
2019-11-08 19:23:43 +00:00
### Delete a list of files returned by a Unix command
```
2019-12-20 22:51:24 +00:00
find . | grep conflict | bb -i '(doseq [f *input* ] (.delete (io/file f)))'
2019-11-08 19:23:43 +00:00
```
2019-11-27 21:55:21 +00:00
### Calculate aggregate size of directory
``` clojure
#!/usr/bin/env bb
(as-> (io/file (or (first *command-line-args* ) ".")) $
(file-seq $)
(map #(.length %) $)
(reduce + $)
(/ $ (* 1024 1024))
(println (str (int $) "M")))
```
``` shellsession
$ dir-size
130M
$ dir-size ~/Dropbox/bin
233M
```
2019-08-10 20:52:30 +00:00
### Shuffle the lines of a file
``` shellsession
$ cat /tmp/test.txt
1 Hello
2 Clojure
2019-08-13 11:43:15 +00:00
3 Babashka
2019-08-10 20:52:30 +00:00
4 Goodbye
2019-12-20 22:51:24 +00:00
$ < /tmp/test.txt bb -io '(shuffle *input* )'
2019-08-13 11:43:15 +00:00
3 Babashka
2019-08-10 20:52:30 +00:00
2 Clojure
4 Goodbye
1 Hello
```
2019-08-10 16:50:48 +00:00
### Fetch latest Github release tag
For converting JSON to EDN, see [jet ](https://github.com/borkdude/jet ).
``` shellsession
2019-08-11 07:05:25 +00:00
$ curl -s https://api.github.com/repos/borkdude/babashka/tags |
2019-08-12 07:28:37 +00:00
jet --from json --keywordize --to edn |
2019-12-20 22:51:24 +00:00
bb '(-> *input* first :name (subs 1))'
2019-08-10 18:34:24 +00:00
"0.0.4"
```
2019-08-10 18:52:13 +00:00
### Get latest OS-specific download url from Github
2019-08-10 18:34:24 +00:00
``` shellsession
2019-08-11 07:05:25 +00:00
$ curl -s https://api.github.com/repos/borkdude/babashka/releases |
2019-08-12 07:28:37 +00:00
jet --from json --keywordize |
2019-12-20 22:51:24 +00:00
bb '(-> *input* first :assets)' |
bb '(some #(re-find #".*linux.*" (:browser_download_url %)) *input* )'
2019-08-10 18:52:13 +00:00
"https://github.com/borkdude/babashka/releases/download/v0.0.4/babashka-0.0.4-linux-amd64.zip"
2019-08-10 16:50:48 +00:00
```
2019-11-03 20:38:06 +00:00
### View download statistics from Clojars
2019-12-18 07:53:32 +00:00
Contributed by [@plexus ](https://github.com/plexus ).
2019-11-03 20:38:06 +00:00
``` shellsession
2019-11-03 21:43:38 +00:00
$ curl https://clojars.org/stats/all.edn |
2019-12-20 22:51:24 +00:00
bb -o '(for [[[group art] counts] *input* ] (str (reduce + (vals counts)) " " group "/" art))' |
2019-11-03 20:39:36 +00:00
sort -rn |
less
2019-11-03 21:43:01 +00:00
14113842 clojure-complete/clojure-complete
9065525 clj-time/clj-time
8504122 cheshire/cheshire
...
2019-11-03 20:38:06 +00:00
```
2019-11-27 17:08:03 +00:00
### Portable tree command
2019-12-13 19:59:09 +00:00
See [examples/tree.clj ](https://github.com/borkdude/babashka/blob/master/examples/tree.clj ).
2019-11-27 17:20:50 +00:00
2019-11-27 17:08:03 +00:00
``` shellsession
$ clojure -Sdeps '{:deps {org.clojure/tools.cli {:mvn/version "0.4.2"}}}' examples/tree.clj src
src
└── babashka
├── impl
│ ├── tools
│ │ └── cli.clj
...
$ examples/tree.clj src
src
└── babashka
├── impl
│ ├── tools
│ │ └── cli.clj
2019-12-01 12:50:32 +00:00
...
2019-11-27 17:08:03 +00:00
```
2019-12-13 19:59:09 +00:00
### List outdated maven dependencies
See [examples/outdated.clj ](https://github.com/borkdude/babashka/blob/master/examples/outdated.clj ).
2019-12-13 20:00:20 +00:00
Inspired by an idea from [@seancorfield ](https://github.com/seancorfield ).
2019-12-13 19:59:09 +00:00
``` shellsession
$ cat /tmp/deps.edn
{:deps {cheshire {:mvn/version "5.8.1"}
clj-http {:mvn/version "3.4.0"}}}
$ examples/outdated.clj /tmp/deps.edn
clj-http/clj-http can be upgraded from 3.4.0 to 3.10.0
cheshire/cheshire can be upgraded from 5.8.1 to 5.9.0
```
2019-12-17 14:35:03 +00:00
### Convert project.clj to deps.edn
2019-12-18 07:52:14 +00:00
Contributed by [@plexus ](https://github.com/plexus ).
2019-12-18 07:51:40 +00:00
2019-12-17 14:37:05 +00:00
``` shellsession
$ cat project.clj |
sed -e 's/#=//g' -e 's/~@//g' -e 's/~//g' |
2019-12-20 22:51:24 +00:00
bb '(let [{:keys [dependencies source-paths resource-paths]} (apply hash-map (drop 3 *input* ))]
2019-12-17 14:37:05 +00:00
{:paths (into source-paths resource-paths)
:deps (into {} (for [[d v] dependencies] [d {:mvn/version v}]))}) ' |
jet --pretty > deps.edn
2019-12-17 14:35:03 +00:00
```
2019-12-18 15:38:21 +00:00
### Print current time in California
See [examples/pst.clj ](https://github.com/borkdude/babashka/blob/master/examples/pst.clj )
2019-11-03 20:28:16 +00:00
## Thanks
2019-11-03 20:33:01 +00:00
- [adgoji ](https://www.adgoji.com/ ) for financial support
2019-11-03 20:28:16 +00:00
2019-08-09 12:51:42 +00:00
## License
Copyright © 2019 Michiel Borkent
2019-09-04 12:37:07 +00:00
Distributed under the EPL License. See LICENSE.
This project contains code from:
- Clojure, which is licensed under the same EPL License.