Scala Scripting

A Modernized Scala REPL.
With syntax highlighting,
multi-line editing, the ability to load maven artifacts
directly in the REPL, and many other quality-of-life
improvements missing in the default Scala REPL.

A modern replacement for the Bash system shell.
Provides a systems shell in the high-level Scala language, letting you
seamlessly mix system operations with real code without the hassle or
the frustration of trying to write complex code in Bash.

Ammonite is a project by Li Haoyi. If
you use Ammonite and enjoyed it, please chip in to support our development
at:

Any amount will help us develop Ammonite into the best possible REPL and
script runner for the Scala community!

The goal of Ammonite is to liberate your Scala code from heavyweight
"projects", using the lightweight Ammonite runtime: if you want to run some
Scala, open the Ammonite-REPL and run it, interactively! If you
want to run it later, save it into some Scala Scripts and run
those later.

For a video overview of the project and it's motivation, check out this talk:

If you are already working in Scala,
you no longer have to drop down to Python or Bash for your scripting needs:
you can use Scala Scripts for your scripting needs, and avoid
the overhead of working in multiple languages.

Each of the above projects is usable standalone; click on the links to jump
straight to their docs, or scroll around and browse through the navigation
bar on the left. If you're wondering what you can do with Ammonite,
there is an

The bulk of this page describes the latest stable release of Ammonite,
1.1.2. If you're willing to live on the edge,
we also publish Unstable Versions from any commits that get pushed
or pull-requests that land in the master branch:

Rally Health: putting healthcare
in the hands of consumers, we work on critical applications at a
massive scale in Scala, C# and JavaScript. If you're smart and like moving
fast, work with us.

Ammonite-REPL

A Modernized Scala REPL

The Ammonite-REPL is an improved Scala REPL, re-implemented from first
principles. It is much more featureful than the default REPL and comes
with a lot of ergonomic improvements and
configurability that may be familiar to
people coming from IDEs or other REPLs such as IPython or Zsh.

You can also pass a string to the Main call containing any
commands or imports you want executed at the start of every run, along
with other configuration.
If you want Ammonite to be available in all projects, simply add the
above snippet to a new file ~/.sbt/0.13/global.sbt.

Note: Ammonite-REPL does not support Windows, even though
Ammonite-Ops does. See #119 if you are interested
in details or want to try your hand at making it work.

Features

Ammonite-REPL supports many more features than the default REPL, including:

Ammonite-REPL uses PPrint to display its output by default. That means that everything is nicely formatted to fit within the width of the terminal, and is copy-paste-able!

By default, Ammonite truncates
the pretty-printed output to avoid flooding your terminal. If you want
to disable truncation, call show(...) on your expression to
pretty-print it's full output. You can also pass in an optional
height = ... parameter to control how much you want to show
before truncation.

Ammonite-REPL intelligently truncates your output when it's beyond a
certain size. You can request for the full output to be printed
on-demand, print a certain number of lines, or even change the implicit
pprintConfig so subsequent lines all use your new configuration.

Editing

Ammonite by default ships with a custom implementation of readline, which
provides...

Syntax Highlighting

Ammonite syntax highlights both the code you're entering as well as any
output being echoed in response. This should make it much easier to
work with larger snippets of input.

All colors are configurable, and you can easily turn off colors entirely
via the Configuration.

Stack traces are similarly highlighted, for easier reading:

Multi-line editing

You can use the Up and Down arrows to navigate between lines
within your snippet. Enter only executes the code when you're
on the last line of a multi-line snippet, meaning you can take your
time, space out your code nicely, and fix any mistakes anywhere in your
snippet. History is multi-line too, meaning re-running a multi-line
snippet is trivial, even with tweaks.

Long gone are the days where you're desperately trying to cram
everything in a single line, or curse quietly when you notice a mistake
in an earlier line you are no longer able to fix. No more painstakingly
crafting a multi-line snippet, and then having to painstakingly fish it
line by individual line out of the history so you can run it again!

Desktop key-bindings

You can use Alt-Left/Right to move forward/backwards by one
word at a time or hold down Shift to select text to delete. These
compose as you'd be used to: e.g. Shift-Up selects all the text
between your current cursor and the same column one row up.

Tab and Shift-Tab now work to block-indent and -dedent
sections of code, as you'd expect in any desktop editor like Sublime
Text or IntelliJ. This further enhances the multi-line editing
experience, letting your nicely lay-out your more-complex REPL commands
the same way you'd format code in any other editor.

Console key-bindings

All the readline-style navigation hotkeys like Ctrl-W to delete a
word or Esc-Left/Right to navigate one word left/right still
work. If you're comfortable with consoles like Bash, Python, IPython or
even the default Scala console, you should have no trouble as all the
exact same hotkeys work in Ammonite

History Search

Apart from browsing your command-line history with UP, you can
also perform a history search by entering some search term and then
pressing UP. That will pull up the most recent history line with
that term in it, underlined. You can continue to press UP or
DOWN to cycle through the matches, or Backspace or
continue typing characters to refine your search to what you want.

You can press TAB, or any other command character (LEFT,
RIGHT, ...) to end the search and let you continue working with
the currently-displayed command. Pressing ENTER will end the
search and immediately submit the command to be run.

You can also kick off a history search using Ctrl-R, and use
Ctrl-R to cycle through the matches.

Block Input

To enter block input (many independent lines all at once) into the
Ammonite-REPL, simply wrap the multiple lines in curly braces
{ ... }, and Ammonite will wait until you close it before
evaluating the contents:

As you can see, the contents of the { ... } block are
unwrapped and evaluated as top-level statements. You can use this to
e.g. declare mutually recursive functions or classes &
companion-objects without being forced to squeeze everything onto a
single line.

If you don't want this un-wrapping behavior, simply add another set of
curlies and the block will be evaluated as a normal block, to a single
expression:

@ {{
@ val x = 1
@ val y = 2
@ x + y
@ }}
res0: Int = 3

Undo & Redo

The Ammonite command-line editor allows you to undo and re-do portions
of your edits:

Ctrl -: Undo last change

Alt/Esc -: Redo last change

Each block of typing, deletes, or navigation counts as one undo. This
should make it much more convenient to recover from botched copy-pastes
or bulk-deletions.

Magic Imports

Ammonite provides a set of magic imports that let you load additional
code into a REPL session: these are imports which start with a $,
and are *top-level* inside the REPL command or your
Scala Scripts.

import $file

This lets you load Scala Scripts into the REPL. For
example given a small script defining one value we want

While this is a trivial example, your MyScript.sc file can
contain anything you want, not just vals: function
defs, classes objects or
traits, or imports from other scripts. For more
documentation on how these scripts work, check out the
Scala Scripts section.

There are some subtleties when dealing with $file imports
that are worth remembering

Note you can also perform file imports from your
predef file, which are resolved relative to
that file's path. This is useful if your predef is large and you want to
break it up into multiple files.

Imported Scripts are Re-used

Note that script files imported multiple times are re-used; even if
the same script is imported multiple times, it will only be compiled
once, and its top-level definitions or statements will only be
evaluated once. If you want to run code over and over, def
a function in the script you are importing and you can call it
repeatedly.

If you want to re-load a script, you should use Ammonite's
Save/Load Session functionality to sess.save()
the session before importing the script, and sess.load()ing
to reset the script before re-importing it.

Cannot directly import from inside a Script

You cannot import things from "inside" that script in

one chain:

@ import $file.MyScript._

Rather, you must always import the script-object first, and then import
things from the script object after:

@ import $file.MyScript, MyScript._

Renamed-scripts and multiple-scripts

You can re-name scripts on-import if you find their names are
colliding:

@ import $file.{MyScript => FooBarScript}, FooBarScript._

Or import multiple scripts at once

@ import $file.{MyScript, MyOtherScript}

These behave as you would expect imports to work. Note that when
importing multiple scripts, you have to name them explicitly and
cannot use wildcard `._` imports:

@ import $file._ // doesn't work

import $exec

This is similar to import $file, except that it dumps the
definitions and imports from the script into your REPL session. This is
useful if you are using a script to hold a set of common imports:
using import $file to import a script doesn't propagate
imports from that script into your REPL.

Alternatively, this is also useful if you want to split up your
~/.ammonite/predef.sc file into multiple scripts: e.g. if you
want to break up your predef.sc into two scripts
~/.ammonite/predef.sc and ~/.ammonite/helper.sc. While
you could use import $file to
import $file.helper within your predef.sc file, it
will only bring the helper object into scope within
predef.sc or within your REPL. import $exec.helper
will properly "dump" all the definitions from helper.sc into
your local scope, which is often what you want when dealing with
predef files.

See the docs for Scala Scripts for more on how script
files work in general.

import $ivy

Lets you import Ivy dependencies from Maven Central, or anywhere else.
For example, here is loading Scalaz and using it in the Ammonite-REPL:

Note that the different portions of the $ivy import are
in a org::library:version format; the :: is used to represent
Scala dependencies, similar to %% in SBT's dependency syntax.
If you want Java dependencies, you can load them using the
org:library:version format, e.g. here we load the
Google Guava Java library

If you need more detailed control over what you are importing, e.g.
with attributes, classifiers or exclusions, you can fall back to
using the interp.load.ivy(deps: coursier.Dependency*)
function and configure each Dependency to your heart's content:

Builtins

The Ammonite REPL contains a bunch of built-in imports and definitions by
default. This includes:

repl: the object representing the Repl API, aliased as
repl. This allows you (e.g. repl.history)
and you can use autocomplete or typeOf on the
repl object to see what is available.

Utilities: tools such as time, grep
or browse that are independent from the REPL, but are
extremely useful to have in it.

All of these are imported by default into any Ammonite REPL, in order to
provide a rich and consistent REPL experience. If you want to disable
these imports and run the REPL with a clean namespace (with only the core
implicits needed for result pretty-printing/type-printing to work) pass
in defaultPredef = false to the REPL's Main API or
--no-default-predef to the REPL from the command-line.

trait ReplAPI {
/**
* Read/writable prompt for the shell. Use this to change the
* REPL prompt at any time!
*/
val prompt: Ref[String]
/**
* The front-end REPL used to take user input. Modifiable!
*/
val frontEnd: Ref[FrontEnd]
/**
* Display help text if you don't know how to use the REPL
*/
def help: String
/**
* The last exception that was thrown in the REPL; `null` if nothing has
* yet been thrown. Useful if you want additional information from the
* thrown exception than the printed stack trace (e.g. many exceptions have
* additional metadata attached) or if you want to show the stack trace
* on an exception that doesn't normally print it (e.g. seeing the stack
* when a Ctrl-C interrupt happened) via `lastException.printStackTrace`.
*/
def lastException: Throwable
/**
* History of commands that have been entered into the shell, including
* previous sessions
*/
def fullHistory: History
/**
* History of commands that have been entered into the shell during the
* current session
*/
def history: History
/**
* Get the `Type` object of [[T]]. Useful for finding
* what its methods are and what you can do with it
*/
def typeOf[T: WeakTypeTag]: Type
/**
* Get the `Type` object representing the type of `t`. Useful
* for finding what its methods are and what you can do with it
*
*/
def typeOf[T: WeakTypeTag](t: => T): Type
/**
* Throw away the current scala.tools.nsc.Global and get a new one
*/
def newCompiler(): Unit
/**
* Access the compiler to do crazy things if you really want to!
*/
def compiler: scala.tools.nsc.Global
/**
* Shows all imports added that bring values into scope for the commands a
* user runs; *includes* imports from the built-in predef and user predef files
*/
def fullImports: Imports
/**
* Shows the imports added to scope by the commands a user has entered so far;
* *excludes* imports from the built-in predef and user predef files
*/
def imports: Imports
/**
* If class wrapping is enabled, this lists the names of the previous commands
* that the current commands actually references (as told by the scalac).
*
* E.g. in a session like
* ```
* @ val n = 2
* n: Int = 2
*
* @ val p = 1
* p: Int = 1
*
* @ n + p
* res2: Int = 3
* ```
* this would have returned an empty list if called from the same line as `val n = 2`
* or `val p = 1`. This would have returned `Seq("cmd0", "cmd1")` if called
* from the same line as `n + p`, as both `cmd0`, that defines `n`, and `cmd1`, that
* defines `p`, are referenced from this line.
*/
def usedEarlierDefinitions: Seq[String]
/**
* Controls how things are pretty-printed in the REPL. Feel free
* to shadow this with your own definition to change how things look
*/
implicit def tprintColorsImplicit: pprint.TPrintColors
implicit def codeColorsImplicit: CodeColors
val pprinter: Ref[pprint.PPrinter]
implicit def pprinterImplicit = pprinter()
/**
* Current width of the terminal
*/
def width: Int
/**
* Current height of the terminal
*/
def height: Int
def show(t: Any): Unit
/**
* Lets you configure the pretty-printing of a value. By default, it simply
* disables truncation and prints the entire thing, but you can set other
* parameters as well if you want.
*/
def show(t: Any,
width: Integer = null,
height: Integer = null,
indent: Integer = null): Unit
/**
* Functions that can be used to manipulate the current REPL session:
* check-pointing progress, reverting to earlier checkpoints, or deleting
* checkpoints by name.
*
* Frames get pushed on a stack; by default, a saved frame is
* accessible simply by calling `load`. If you provide a name
* when `save`ing a checkpoint, it can later be `load`ed directly
* by providing the same name to `load`
*
* Un-named checkpoints are garbage collected, together with their
* classloader and associated data, when they are no longer accessible
* due to `restore`. Named checkpoints are kept forever; call `delete`
* on them if you really want them to go away.
*/
def sess: Session
def load: ReplLoad
}
trait ReplLoad{
/**
* Loads a command into the REPL and
* evaluates them one after another
*/
def apply(line: String): Unit
/**
* Loads and executes the scriptfile on the specified path.
* Compilation units separated by `@\n` are evaluated sequentially.
* If an error happens it prints an error message to the console.
*/
def exec(path: Path): Unit
}
trait Session{
/**
* The current stack of frames
*/
def frames: List[Frame]
/**
* Checkpoints your current work, placing all future work into its own
* frames. If a name is provided, it can be used to quickly recover
* that checkpoint later.
*/
def save(name: String = ""): Unit
/**
* Discards the last frames, effectively reverting your session to
* the last `save`-ed checkpoint. If a name is provided, it instead reverts
* your session to the checkpoint with that name.
*/
def load(name: String = ""): SessionChanged
/**
* Resets you to the last save point. If you pass in `num`, it resets
* you to that many savepoints since the last one.
*/
def pop(num: Int = 1): SessionChanged
/**
* Deletes a named checkpoint, allowing it to be garbage collected if it
* is no longer accessible.
*/
def delete(name: String): Unit
}

All of these are available as part of the repl object
which is imported in scope by default. Additional
functionality available under the interp object, which is also
available in scripts:

trait InterpAPI {
/**
* When running a script in `--watch` mode, re-run the main script if this
* file changes. By default, this happens for all script files, but you can
* call this to watch arbitrary files your script may depend on
*/
def watch(p: Path): Unit
/**
* The colors that will be used to render the Ammonite REPL in the terminal,
* or for rendering miscellaneous info messages when running scripts.
*/
val colors: Ref[Colors]
/**
* Tools related to loading external scripts and code into the REPL
*/
def load: InterpLoad
/**
* resolvers to use when loading jars
*/
def repositories: Ref[List[coursier.Repository]]
/**
* Functions that will be chained and called on coursier
* Resolutions right before they are run
*/
val resolutionHooks: mutable.Buffer[coursier.Resolution => coursier.Resolution]
/**
* Exit the Ammonite REPL. You can also use Ctrl-D to exit
*/
def exit = throw AmmoniteExit(())
/**
* Exit the Ammonite REPL. You can also use Ctrl-D to exit
*/
def exit(value: Any) = throw AmmoniteExit(value)
/**
* Functions that will be chained and called on the
* exitValue before the repl exits
*/
val beforeExitHooks: mutable.Buffer[Any => Any]
/**
* Configures the current compiler, or if the compiler hasn't been initialized
* yet, registers the configuration callback and applies it to the compiler
* when it ends up being initialized later
*/
def configureCompiler(c: scala.tools.nsc.Global => Unit): Unit
/**
* Pre-configures the next compiler. Useful for tuning options that are
* used during parsing such as -Yrangepos
*/
def preConfigureCompiler(c: scala.tools.nsc.Settings => Unit): Unit
}
trait LoadJar {
/**
* Load a `.jar` file or directory into your JVM classpath
*/
def cp(jar: Path): Unit
/**
* Load one or more `.jar` files or directories into your JVM classpath
*/
def cp(jars: Seq[Path]): Unit
/**
* Load a library from its maven/ivy coordinates
*/
def ivy(coordinates: coursier.Dependency*): Unit
}
trait InterpLoad extends LoadJar{
def module(path: Path): Unit
def plugin: LoadJar
}

Utilities

Apart from the core Builtins of the REPL, the Ammonite REPL
also includes many helpers that are not strictly necessarily but are
very useful in almost all REPL sessions. Here are a few of them

The REPL also imports the pipe-operators
from Ammonite-Ops by default to make it easy for you to use tools like
grep interactively, and imports all the Builtins
from the repl.

These tools are useful but not strictly necessary;

source

Ammonite provides the src built-in, which lets you easily
peek at the source code of various functions or classes. You can
use this to read their doc-comments or inspect their implementation,
to help you figure out how to use them.

src accepts two kinda of inputs:

A method call foo.bar(...), in which case it will try to
bring you to concrete implementation of that method bar.
You can also leave the method arguments empty using `_`.

An arbitrary expression foo, in which case it will try to
bring you to the implementation of foo's runtime class

src works on both Scala and Java APIs, both the standard
library as well as third-party dependencies. src opens source
files using the less pager by default; if you wish to change
this, you can pass in a replacement command as a second argument
e.g. src(..., "vim") or e.g. src(..., Seq("vim", "--flag"))

When used within a SBT project src requires the following
SBT setting in order to make the source code of third-party
dependencies available:

Ammonite also automatically downloads the source jars of any
libraries you import via import $ivy, and makes them
browsable via src.

src is experimental: it may not always be able to find the
source code of a particular method or class, and the source
location it brings you to may be a few lines away from the source
you really want. Furthermore, src also does not find sources
that are within your own local scripts or SBT project: you likely
already have access to those via your text editor anyway.

Nevertheless, it should work in the bulk of cases,
so try it out and come by the
Gitter Channel if you
face any issues!

Just as bash provides a time command that you can use to see
how long a command took to run, Ammonite-Shell provides a
time function which serves the same purpose.

While the bash version spits out the time in an ad-hoc table format,
stuck together with the output of the command, Ammonite-Shell's
time instead returns a tuple containing the expression
that was evaluated, and the time taken to evaluate it.

Ammonite provides its own grep command, which lets you
easily perform ad-hoc searches within a list.

As shown above, Ammonite's grep can be used via
|| (flatMap) or |?
(filter). In the case of ||, it displays the
matches found, highlighted, with some additional context before and
after the match. When used with |?, it simply returns the
relevant items. In general, || is useful for manual
exploration, while |? is useful in scripts where you want
to deal with the list of matched results later.

By default, Ammonite's grep matches a string as a literal.
If you want to match via a regex, append a .r to the
string literal to turn it into a regex:

In general, Ammonite's grep serves the same purpose of
grep in the Bash shell: a quick and dirty way to explore large
amounts of semi-structured data. You probably don't want to build
your enterprise business logic on top of grep's string
matching. While you're working, though, grep can be a
quick way to find items of interest in collections of things
(anything!) too large to sift through by hand, when you're not yet
sure exactly what you want.

browse

browse is a utility that lets you open up far-too-large
data structures in the less pager, letting you page through
large quantities of text, navigating around it and searching through
it, without needing to spam your terminal output with its contents
and losing your earlier work to the output-spam. Simple call
browse on whatever value you want, e.g. this 50 thousand
line ls.rec result show above.

If you're dealing with large blobs of data that you want to dig
through manually, you might normally format it nicely, write it to
a file, and open it in vim or less or an editor such
as Sublime Text. browse makes that process quick and
convenient.

You can customize the browse call like you would a
show call or pprint.pprintln call, e.g. setting
an optional width, colors or indent.
You can also choose a viewer program in case you don't
want to use less: e.g. here's a command that would open it up
in vim:

Apart from using viewer="vim", we also set the
colors to black and white because Vim by default doesn't
display ANSI colors nicely. You can also pass in a Seq of
strings to viewer if you want to pass additional flags to
your editor, and of course use any other editor you would like such
as "emacs" or "nano" or "subl"

desugar

desugar allows you to easily see what the compiler is
doing with your code before it gets run. For example, in the above
calls to desugar, you can see:

for comprehensions with if filters being
converted into the relevant withFilter and map
calls

In general, if you are having trouble understanding the combination
of implicit parameters, implicit conversions, macros, and other odd
Scala features, desugar could you see what is left after
all the magic happens.

desugar only works in Scala 2.11.x and above, not in 2.10.x

Save/Load Session

Ammonite allows you to save your work half way through, letting you
discard and future changes and returning to the state of the world you
saved.

Defined some memory-hogging variable you didn't need? Loaded the wrong
version of some third-party library? Reluctant to reload the REPL
because reloading is slow? Fear not! With Ammonite, you can save your
important work, do whatever you want later, and simply discard all the
jars you loaded, variables you defined

Apart from plain saves and loads, which simply
discard everything after the most recent save, you can also provide a
name to these functions. That lets you stop working on a branch, go do
something else for a while, and be able to come back later to continue
where you left off:

Lastly, you have the repl.sess.pop() function. Without any
arguments, it behaves the same as repl.sess.load(), reseting you
to your last savepoint. However, you can pass in a number of session
frames which you'd like to pop, allow you to reset your session to even
earlier save points. repl.sess.pop(2) would put you two
save-points ago, repl.sess.pop(3) would put you three save-points
ago, letting you reach earlier save-points even if you did not give
them names. Passing in a large number like repl.sess.pop(999)
would reset your session all the way until the start.

Superior Autocomplete

The original Scala REPL provides no autocomplete except for the most
basic scenarios of value.<complete>. In the Ammonite-REPL,
you get the same autocomplete-anywhere support that you get in a modern
IDE.

Interrupting run-away execution with Ctrl-C

@ while(true) ()
... hangs ...
^Ctrl-C
Interrupted!
@

The traditional Scala REPL doesn't handle runaway code, and gives you
no option but to kill the process, losing all your work. Ammonite-REPL
lets you interrupt the thread, stop the runaway-command and keep going.

Compiler-crash Robustness

The default Scala REPL throws away all your work if the compiler
crashes. This doesn't make any sense, because all the compiler is is
a dumb String => Array[Byte] pipe. In the Ammonite, we
simply swap out the broken compiler for a new one and let you continue
your work.

Other Fixes

Apart from the above features, the Ammonite REPL fixes a large number
of bugs in the default Scala REPL, including but not limited to:

Configuration

Ammonite is configured via Scala code, that can live in the
~/.ammonite/predef.sc file, passed in through SBT's
initialCommands, or passed to the command-line executable as
--predef='...'.

Anything that you put in predef.sc will be executed when you
load the Ammonite REPL. This is a handy place to put common imports,
setup code, or even call import $ivy to
load third-party jars. The compilation
of the predef is cached, so after the first run it should not noticeably
slow down the initialization of your REPL.

Refs

By default, all the values you're seeing here with the () after
them are Refs, defined as

trait StableRef[T]{
/**
* Get the current value of the this [[StableRef]] at this instant in time
*/
def apply(): T
/**
* Set the value of this [[StableRef]] to always be the value `t`
*/
def update(t: T): Unit
}
trait Ref[T] extends StableRef[T]{
/**
* Return a function that can be used to get the value of this [[Ref]]
* at any point in time
*/
def live(): () => T
/**
* Set the value of this [[Ref]] to always be the value of the by-name
* argument `t`, at any point in time
*/
def bind(t: => T): Unit
}

As you can see from the signature, you can basically interact with the
Refs in two ways: either getting or setting their values as
values, or binding their values to expressions that will be evaluated
every time the Ref's value is needed.

As an example of the latter, you can use bind to set your
prompt to always include your current working directory

repl.prompt.bind(wd.toString + "@ ")

As is common practice in other shells. Further modifications to make it
include e.g. your current branch in Git (which you can call through
Ammonite's subprocess API or the
current timestamp/user are similarly possible.

Compiler Flags

Apart from configuration of the rest of the shell through
Refs, configuration of the Scala compiler takes place
separately through the compiler's own configuration mechanism. You have
access to the compiler as compiler, and can modify its settings
as you see fit. Here's an example of this in action:

If you want these changes to always be present, place them in your
~/.ammonite/predef.sc.

JVM Flags

Ammonite also supports the JAVA_OPTS environment variable for
passing arguments to the JVM that it runs inside, e.g. you can pass in
a custom memory limit via

bash$ JAVA_OPTS="-Xmx1024m" amm

To start the REPL while letting it use only up to 1024 megabytes of memory

Embedding

The Ammonite REPL is just a plain-old-Scala-object, just like any other
Scala object, and can be easily used within an existing Scala program.
This is useful for things like interactive Debugging or
hosting a Remote REPL to interact with a long-lived Scala
process, or Instantiating Ammonite inside an existing program
to serve as a powerful interactive console.

Instantiating Ammonite

To use Ammonite inside an existing Scala program, you need to first add
it to your dependencies:

You can configure the instantiated REPL by passing in arguments to the
Main() call, e.g. to redirect the input/output streams or to
run a predef to configure it further.

Debugging

Ammonite can be used as a tool to debug any other Scala program, by
conveniently opening a REPL at any point within your program with which
you can interact with live program data, similar to pdb/ipdb in Python.
To do so, first add Ammonite to your classpath, e.g. through this SBT
snippet:

Note that unlike the snippet given above, we
leave out the % "test" because we may want ammonite to be
available within the "main" project, and not just in the unit tests.
Then, anywhere within your program, you can place a breakpoint via:

And when your program reaches that point, it will pause and open up an
Ammonite REPL with the values you provided it bound to the names you
gave it. From there, you can interact with those values as normal Scala
values within the REPL. Use Ctrl-D or exit to exit the
REPL and continue normal program execution. Note that the names given
must be plain Scala identifiers.

In this case, we added the debug statement within the
websocket frame handler, so we can inspect the values that are taking
part in the client-server data exchange. You can also put the
run statement inside a conditional, to make it break only
when certain interesting situations (e.g. bugs) occur.

As you can see, you can bind the values you're interested in to names
inside the debug REPL, and once in the REPL are free to explore them
interactively.

The debug() call returns : Any; by default, this
is (): Unit, but you can also return custom values by
passing in an argument to exit(...) when you exit the REPL.
This value will then be returned from debug(), and can be
used in the rest of your Scala application.

Remote REPL

Ammonite can also be used to remotely connect to your running
application and interact with it in real-time, similar to Erlang's
erl -remsh command.

This is useful if e.g. you have multiple Scala/Java processes running
but aren't sure when/if you'd want to inspect them for debugging, and
if so which ones. With Ammonite, you can leave a ssh server running in
each process. You can then and connect-to/disconnect-from each one at
your leisure, working with the in-process Scala/Java objects and
methods and classes interactively, without having to change code and
restart the process to add breakpoints or instrumentation.

To do this, add ammonite-sshd to your classpath, for example with SBT:

And start your application. You will be able to connect to it using ssh
like this: ssh repl@localhost -p22222 and interact with your
running app. Invoke stop() method whenever you want to
shutdown ammonite sshd server. Here for example sshd repl server is
embedded in the Akka HTTP microservice example:

Here we can interact with code live, inspecting values or calling
methods on the running system. We can try different things, see which
works and which not, and then put our final bits in application code.
In this example app is located on local machine, but you are free to
connect to any remote node running your code.

Security notes: It is probably unsafe to run this server publicly
(on host "0.0.0.0") in a production, public-facing
application. If you insist on doing so, you probably want key-based
authentication, available by supplying publicKeyAuthenticator
in the SshServerConfig.

Despite this, it is perfectly possible to run these on production
infrastructure: simply leave the host set to
"localhost", and rely on the machine's own SSH access to
keep out unwanted users: you would first ssh onto the machine
itself, and then ssh into the Ammonite REPL running on
localhost.

Typically most organizations already have bastions, firewalls, and
other necessary infrastructure to allow trusted parties SSH access to
the relevant machines. Running on localhost lets you leverage
that and gain all the same security properties without having to
re-implement them in Scala.

Scala Scripts

Lightweight Programming in Scala

Scala scripts are lightweight files containing Scala code that
can be directly run from the command line. Unlike normal Scala projects,
Scala scripts let you save and run code without setting up a "build-file"
or "project". Scala Scripts are useful for writing small pieces of code,
and are much quicker to write and deploy than a full-fledged SBT project.

Creating an Ammonite Script is just a matter of creating a
MyScript.sc with some Scala code in it, and running it
from your terminal. Deploying the script is
a matter of copying the script file to where-ever you want to run it, and
running it. No project/ folder, no worrying about .jar files
or uber-jars. No worrying about compiling your code: scripts are
automatically compiled the first time they are run, and subsequently start
quickly with minimal overhead. Writing and running Scala code
doesn't get much easier than that!

As an example, Ammonite's own
Continuous Integration Scripts
are written as .sc Scala Scripts, as are Haoyi's blog and resume. These are all examples of using
Scala Scripts to do some simple (or not so simple!) tasks in just a few
files, without the hassle of setting up a heavyweight SBT project.

Script Files

Ammonite defines a format that allows you to load external scripts into
the REPL; this can be used to save common functionality so it can be
used at a later date. In the simplest case, a script file is simply a
sequence of Scala statements, e.g.

You can write any Scala code you want in an Ammonite script, including
top-level statements and definitions (e.g. the println and
val x = 123 above) that are not valid in "normal" Scala
projects. You do not need to wrap these sorts of top-level statements
or expressions in boilerplate object Foo{...} wrappers:
this is all done automatically for you by Ammonite.

Script Imports

No code stands alone; scripts depend on other scripts. Often they depend
on third party libraries, as there's so much code out there already
written it doesn't make sense to re-invent everything yourself.

Ammonite Scripts allow you to import Other Scripts, just like
any Bash or Python scripts do. Furthermore, they let you cleanly depend
on third party libraries: since Ammonite runs on the JVM, this means
Ivy Dependencies. Ammonite will ensure that the relevant
dependencies are always downloaded and used, and you never need to worry
about remembering to "install" things before running your scripts!

Other Scripts

Like other scripting languages, Ammonite Scripts allow you to break your
script into multiple files, and import them from each other in order to
use what is in each file. Unlike "Normal" Scala projects, there is no
need to set up a src/main/scala folder, and create a build file,
and all these other things: simply split your script into two files, and
import one from the other using import $file:

And so on, importing files as many or as deep as you want. You can
use ^ segments at the start of your import $file
to import things from outside the current script's enclosing folder, e.g.
import $file.^.^.foo will import the script file
../../foo.sc and make it available for you to use.

$file imports inside Scala Scripts behave the same as
$file imports within the Ammonite-REPL, and have the same characteristics:

Ivy Dependencies

You can easily make use of external Ivy artifacts right in your
scripts, without needing to set up a separate build file. Simply use a
import $ivy, just as you would in the
Ammonite-REPL, and it will be available in the script for you
to use, e.g. here we make use of the Scalatags library:

Note that to use this function, your script needs to be a
multi-stage script as listed below, and the interp.load.ivy
call needs to be in an earlier block

Multi-stage Scripts

By default, everything in a script is compiled and executed as a single
block. While you can use Magic Imports to load other scripts
or Ivy artifacts before your script runs, those can only load "hardcoded"
scripts or artifacts, and cannot e.g. load different scripts depending on
some runtime variables.

If you want to load different scripts or ivy artifacts depending on
runtime values, you can use the runtime-equivalent of magic imports:

import $cp becomes interp.load.cp

import $file becomes interp.load.module

import $ivy becomes interp.load.ivy

These are plain-old-Scala-functions that let you pass in a
Path to a script to load, or load different Ivy artifacts
depending on runtime values. Additionally, there is an overloaded
version of interp.load.cp which takes a Seq[Path]
of classpath entries. This variant is much more efficient for adding
multiple classpath entries at once.

Since these functions get run *after* the current compilation block is
compiled, you need to split your script into two compilation blocks,
and can only use the results of the loaded code in
subsequent blocks:

In general, this should not be necessary very often: usually you should
be able to load what you want using Magic Imports.
Nevertheless, sometimes you may find yourself needing to get "under the
hood" and use these loading functions directly. When that
happens, using Multi-stage Scripts is the way to go.

Script Arguments

Often when calling a script from the external command-line (e.g.
Bash), you need to pass arguments to configure its behavior. With
Ammonite, this is done by defining a @main method, e.g.

The top-level definitions execute first (e.g. setting x),
and then the @main method is called with the arguments you
passed in. Note that the return-value of the script is pretty-printed
by default, which quotes strings and may nicely format/indent lists or
other data-structures. If you want to avoid this default pretty-printing
behavior, annotate your @main method as returning
: Unit and add your own printlns:

Default arguments behave as you would expect (i.e. they allow you to
omit it when calling) and arguments are parsed using the
scopt.Read typeclass, which provides parsers for primitives
like Int, Double, String, as well as basic
data-structures like Seqs (taken as a comma-separated list) and
common types like Paths.

If you pass in the wrong number of arguments, or if an argument fails
to deserialize, the script will fail with an error message.

The main method does not get automatically called when you
load.module or load.exec a script from within
the Ammonite REPL. It gets imported into scope like any other method or
value defined in the script, and you can just call it normally.

vararg* arguments work as you would expect as well, allowing one or
more arguments to be passed from the command-line and aggregated into
a Seq for your function to use. This also allows you to use a
custom argument-parser (e.g. Eugene Yokota's excellent Scopt) library by defining your function
as taking String*:

@main
def entrypoint(args: String*) = {
...
}

In which case Ammonite will take all arguments and forward them to your
main method un-checked and un-validated, from which point you can deal
with the raw Seq[String] however you wish. Note that
vararg* arguments cannot be passed by-name, e.g. via
--args foo

Ammonite Arguments in Scripts

Ammonite passing any arguments that come before the script file to
Ammonite itself, while arguments that come after the script file are
given to the script:

Here, "Ammonite Arguments" go on the left of the Args.sc, while
Script Arguments go on the right of the Args.sc. The script
arguments on the right can also be empty if you don't want to pass
any arguments to the script.

If you want to define a script with a Shebang line that runs Ammonite
with particular arguments, you can use

#!/bin/bash
exec amm --predef 'println("welcome!")' "$0" "$@"
!#

And which will pass in the --predef flag to Ammonite while
running the script via ./Args.sc. If you want to then pass
in different sets of arguments, you can run the script using amm
e.g. amm --predef 'println("Hello!")' Args.sc 3 Moo as before.
(Note that while a single-line #!/usr/bin/env amm --predef '...'
shebang may work on some systems such as OS-X, it is not portable and
would not work on Linux)

Multiple Main Methods

If you have only a single @main method, any arguments that
you pass to the script get used as arguments to that @main.
But if you have multiple@main methods, the first
argument to the script is used to select which @main method
to call. e.g. given:

Need to specify a subcommand to call when running MultiMainDoc.sc
Available subcommands:
mainA
functionB
This explains what the function does
--i Int: how many times to repeat the string to make it very very long,
more than it originally was
--s String: the string to repeat
--path ammonite.ops.Path (default $pwd)

Bundled Libraries

While Ammonite allows you to load any Java or Scala library for use
via the import $ivy syntax, it also comes bundled with some
basic libraries, e.g. Scalaj-HTTP
for making HTTP calls, or the
uPickle
library with it's JSON Api
for dealing with the common JSON format.

For example, here's a tiny script that offers two main methods, one
to shorten a github link using Scalaj-HTTP and the git.io API,
and one that pulls out a list of release-names from a given github
project using Scalaj-HTTP, uPickle's JSON package, and the Github API:

Script Builtins

Apart from bundling some third-party libraries for convenience,
Ammonite also provides some builtins you can use from scripts to
inspect and manipulate the interpreter itself. Note that this is
a much smaller set of functionality than the set of
Builtins available to the REPL: it won't have things
like the repl.prompt, repl.history, and other things
that only really make sense in the interactive REPL.

trait InterpAPI {
/**
* When running a script in `--watch` mode, re-run the main script if this
* file changes. By default, this happens for all script files, but you can
* call this to watch arbitrary files your script may depend on
*/
def watch(p: Path): Unit
/**
* The colors that will be used to render the Ammonite REPL in the terminal,
* or for rendering miscellaneous info messages when running scripts.
*/
val colors: Ref[Colors]
/**
* Tools related to loading external scripts and code into the REPL
*/
def load: InterpLoad
/**
* resolvers to use when loading jars
*/
def repositories: Ref[List[coursier.Repository]]
/**
* Functions that will be chained and called on coursier
* Resolutions right before they are run
*/
val resolutionHooks: mutable.Buffer[coursier.Resolution => coursier.Resolution]
/**
* Exit the Ammonite REPL. You can also use Ctrl-D to exit
*/
def exit = throw AmmoniteExit(())
/**
* Exit the Ammonite REPL. You can also use Ctrl-D to exit
*/
def exit(value: Any) = throw AmmoniteExit(value)
/**
* Functions that will be chained and called on the
* exitValue before the repl exits
*/
val beforeExitHooks: mutable.Buffer[Any => Any]
/**
* Configures the current compiler, or if the compiler hasn't been initialized
* yet, registers the configuration callback and applies it to the compiler
* when it ends up being initialized later
*/
def configureCompiler(c: scala.tools.nsc.Global => Unit): Unit
/**
* Pre-configures the next compiler. Useful for tuning options that are
* used during parsing such as -Yrangepos
*/
def preConfigureCompiler(c: scala.tools.nsc.Settings => Unit): Unit
}
trait LoadJar {
/**
* Load a `.jar` file or directory into your JVM classpath
*/
def cp(jar: Path): Unit
/**
* Load one or more `.jar` files or directories into your JVM classpath
*/
def cp(jars: Seq[Path]): Unit
/**
* Load a library from its maven/ivy coordinates
*/
def ivy(coordinates: coursier.Dependency*): Unit
}
trait InterpLoad extends LoadJar{
def module(path: Path): Unit
def plugin: LoadJar
}

Script Predef

If you want code to be loaded before you run any script, you can place
it in ~/.ammonite/predefScript.sc. This is distinct from the REPL
pre-defined code which lives in ~/.ammonite/predef.sc. If you want
code that is pre-initialized in both the REPL and in scripts, you can place
it in ~/.ammonite/predefShared.sc.

All types, values and imports defined in scripts are available to
commands entered in REPL after loading the script.

You can also make an Ammonite script self-executable by using a shebang
#!. This is an example script named hello. There
is no need to add the .sc extension. The amm
command needs to be in the PATH:

#!/usr/bin/env amm
println("hello world")

make it executable and run it from an external shell (e.g. bash):

$ chmod +x /path/to/script
$ /path/to/script

Ammonite also supports the JAVA_OPTS environment variable for
passing arguments to the JVM that it runs inside, e.g. you can pass in
a custom memory limit via

bash$ JAVA_OPTS="-Xmx1024m" amm path/to/script.sc

To let it use only up to 1024 megabytes of memory

Watch and Reload

Ammonite provides the -w/--watch flag, which tells it to
not exit when a script completes, but instead watch the files that were
run, and re-run them when any of them change. You can use this flag via

$ amm -w foo.sc

Within your scripts, you can also flag other files you want Ammonite
to watch, via the interp.watch(p: Path) function. This is useful
if you are iterating on a script together with some external data files
the script depends on, and you want to

Script Debug REPL

When a script is not working as intended, it is useful to be able to
poke around in a REPL after the script has run, in order to see what
values are stored in which variables or what methods are available via
autocomplete. To do so, you can run the script using the
--predef/-p flag.

$ amm --predef foo.sc

This will run the script as normal, but on completion open up a REPL
which has all the values defined in that script imported and ready to
use. You can then poke around within the REPL as you wish.

Using --predef/-p to run a script and then open an
interactive REPL can be combined with the --watch/-w
flag:

$ amm --watch --predef foo.sc

This will open up a REPL after the script runs, and when you exit the
REPL it will watch the script file and the files that the script depends
on, re-running the script and REPL if any of them change.

--predef/-p can be used to include a script file as a
predef before running any script or REPL, which is useful for a range
of things apart from serving as a debug REPL on any script.

From the REPL

You can load any script into the Ammonite REPL using the
import $file syntax, for example here we import the above
MyScript.sc file to access its x value:

As you can see, now mutable is available, and so is x even
though we did not directly import it.

While $file imports are useful for defining re-usable modules with
common functions and definitions, $exec imports are useful as
aliases for common setup to get your REPL environment just the way you
want it. Of course, any files you import via import $file or
import $exec can themselves import other Scala scripts in the
same way, and the same rules apply.

If the script has already been previously compiled and cached, the
cached bytecode that was read off of disk earlier is executed.

Otherwise, the source code for this script is then wrapped in a
package/object wrapper, corresponding to the
path to the script from the current script's enclosing folder.
For example, a script at path foo/bar/baz/Qux.sc will be
wrapped in:

package foo.bar.baz
object Qux{
// script code
}

The script is then compiled and executed.

In general, due to Scala's slow compiler, Scala Scripts rely heavily
on caching to achieve reasonable performance. While the first run of a
modified script has a few-seconds overhead due to the Scala compiler,
subsequent runs of the same script should be fast-ish, with only a few
100ms overhead for spinning up a JVM.

Although this is much slower than other scripting languages like Bash
(which starts up in ~4ms) or Python (~30ms), in practice it is
acceptable for many use cases. You probably do not want to
find . | xargs amm Foo.sc on large numbers of files, where
the 100ms overhead will add up, but for individual scripts it should
be fine.

Furthermore, Ammonite makes it really easy to include that sort of
recursive/iterative logic inside a single script: you can use
ls! or ls.rec! from Ammonite-Ops to
traverse the filesystem and work on multiple files all within the same
process, which avoids duplicating the startup overhead on all the files
you are manipulating.

SBT Integration

If you have an existing SBT project and you'd like to access those
classes from an ammonite script, you can achieve this by running
your script through SBT itself. This requires adding ammonite to your
SBT project and creating a "bridge" class to pass arguments from SBT
into an ammonite Main class.

If you have already started an SBT repl, then you can run the above without the quotes:
test:run /path/to/script.sc arg1 arg2 arg3

Running a script from your SBT project can be achieved with
ammonite.Main.main(Array("--predef-code", """println("welcome!")""", "file.sc"))

Ammonite-Ops

A Rock-solid Filesystem Library for Scala

Ammonite-Ops is a library to make common filesystem operations in Scala as concise and easy-to-use as from the Bash shell, while being robust enough to use in large applications without getting messy. It lives in the same repo as the Ammonite REPL, but can easily be used stand-alone in a normal SBT/maven project.

To get started with Ammonite-Ops, add this to your build.sbt:

libraryDependencies += "com.lihaoyi" %% "ammonite-ops" % "1.1.2"

And you're all set! Here's an example of some common operations you can do with Ammonite-Ops

That handles the common case for you: recursively deleting folders, not-failing if the file doesn't exist, etc.

Note: Ammonite-Ops supports Windows experimentally, even if Ammonite-REPL does not. That means you can use these convenient filesystem operations and commands in your Scala programs that run on Windows. Try it out and let me know if there are problems.

With a number of useful operations that can be performed on them. Absolute paths can be created in a few ways:

// Get the process' Current Working Directory. As a convention
// the directory that "this" code cares about (which may differ
// from the pwd) is called `wd`
val wd = pwd
// A path nested inside `wd`
wd/'folder/'file
// A path starting from the root
root/'folder/'file
// A path with spaces or other special characters
wd/"My Folder"/"My File.txt"
// Up one level from the wd
wd/up
// Up two levels from the wd
wd/up/up

Note that there are no in-built operations to change the pwd. In general you should not need to: simply defining a new path, e.g.

val target = pwd/'target

Should be sufficient for most needs.

Above, we made use of the pwd built-in path. There are a number of Paths built into Ammonite:

pwd: The current working directory of the process. This can't be changed in Java, so if you need another path to work with the convention is to define a wd variable.

root: The root of the filesystem.

home: The home directory of the current user.

tmp()/tmp.dir(): Creates a temporary file/folder and returns the path.

RelPaths

RelPaths represent relative paths. These are basically defined as:

class RelPath private[ops] (segments0: Array[String], val ups: Int)

The same data structure as Paths, except that they can represent a number of ups before the relative path is applied. They can be created in the following ways:

So you don't need to worry about canonicalizing your paths before comparing them for equality or otherwise manipulating them.

Path Operations

Ammonite's paths are transparent data-structures, and you can always access the segments and ups directly. Nevertheless, Ammonite defines a number of useful operations that handle the common cases of dealing with these paths:

In this definition, ThisType represents the same type as the current path; e.g. a Path's / returns a Path while a RelPath's / returns a RelPath. Similarly, you can only compare or subtract paths of the same type.

Apart from RelPaths themselves, a number of other data structures are convertible into RelPaths when spliced into a path using /:

Strings

Symbolss

Array[T]s where T is convertible into a RelPath

Seq[T]s where T is convertible into a RelPath

Constructing Paths

Apart from built-ins like pwd or root or home, you can also construct Ammonite's Paths from Strings, java.io.Files or java.nio.file.Paths:

As you can see, attempting to parse a relative path with Path or an absolute path with RelPath throws an exception. If you're uncertain about what kind of path you are getting, you could use BasePath to parse it:

For example, if you wanted the common behavior of converting relative paths to absolute based on your current working directory, you can pass in pwd as the second argument to Path(...). Apart from passing in Strings or java.io.Files or java.nio.file.Paths, you can also pass in BasePaths you parsed early as a convenient way of converting it to a absolute path, if it isn't already one.

In general, Ammonite is very picky about the distinction between relative and absolute paths, and doesn't allow "automatic" conversion between them based on current-working-directory the same way many other filesystem APIs (Bash, Java, Python, ...) do. Even in cases where it's uncertain, e.g. you're taking user input as a String, you have to either handle both possibilities with BasePath or explicitly choose to convert relative paths to absolute using some base.

While this adds some boilerplate, it should overall result in more robust filesystem code that doesn't contain bugs like this one.

Operations

Paths not aren't interesting on their own, but serve as a base to use to perform filesystem operations in a concise and easy to use way. Here is a quick tour of the core capabilities that Ammonite-Ops provides:

In these definitions, Op1 and Op2 are isomorphic to Function1 and Function2. The main difference is that ops can be called in two ways:

rm(filepath)
rm! filepath

The latter syntax allows you to use it more easily from the command line, where remembering to close all your parenthesis is a hassle. Indentation signifies nesting, e.g. in addition to write! you also have write.append! and write.over!

Operator Reference

All of these operations are pre-defined and strongly typed, so feel free to jump to their implementation to look at what they do or what else is available. Here's a shortlist of the one that may interest you:

read! path[doc] returning a String, and read.lines! path and read.bytes! path returning Seq[String] and Array[Byte]. You can also use the various read! commands for Reading Resources or reading java.io.InputStreams

write(path, contents), [doc], which lets you write Strings, Array[Byte]s, and Seqs of those

write also does not stomp over existing files by default. You need to use write.over

In general, this should make these operations much easier to use; the defaults should cover the 99% use case without needing any special flags or fiddling.

Extensions

Ammonite-Ops contains a set of extension methods on common types, which serve no purpose other than to make things more concise. These turn Scala from a "relatively-concise" language into one as tight as Bash scripts, while still maintaining the high level of type-safety and maintainability that comes with Scala code.

Traversable

These extensions apply to any Traversable: Seqs, Lists, Arrays, and others.

things | f is an alias for things map f

things || f is an alias for things flatMap f

things |? f is an alias for things filter f

things |& f is an alias for things reduce f

things |! f is an alias for things foreach f

These should behave exactly the same as their implementations; their sole purpose is to make things more concise at the command-line.

Pipeable

thing |> f is an alias for f(thing)

This lets you flip around the function and argument, and fits nicely into the Ammonite's | pipelines.

Callable

f! thing is an alias for f(thing)

This is another syntax-saving extension, that makes it easy to call functions without having to constantly be opening and closing brackets. It does nothing else.

Chaining

The real value of Ammonite is the fact that you can pipe things together as easily as you could in Bash. No longer do you need to write reams of boilerplate. to accomplish simple tasks. Some of these chains are listed at the top of this readme, here are a few more fun examples:

Reading Resources

In addition to manipulating paths on the filesystem, you can also manipulate resource paths in order to read resources off of the Java classpath. By default, the path used to load resources is absolute, using the Thread.currentThread().getContextClassLoader. You can also pass in a classloader explicitly to the resource call:

In both cases, reading resources is performed as if you did not pass a leading slash into the getResource("foo/bar") call. In the case of ClassLoader#getResource, passing in a leading slash is never valid, and in the case of Class#getResource, passing in a leading slash is equivalent to calling getResource on the ClassLoader.

Ammonite-Ops ensures you only use the two valid cases in the API, without a leading slash, and not the two cases with a leading slash which are redundant (in the case of Class#getResource, which can be replaced by ClassLoader#getResource) or invalid (a leading slash with ClassLoader#getResource)

Note that you can only read! from paths; you can't write to them or perform any other filesystem operations on them, since they're not really files.

Note also that resources belong to classloaders, and you may have multiple classloaders in your application e.g. if you are running in a servlet or REPL. Make sure you use the correct classloader (or a class belonging to the correct classloader) to load the resources you want, or else it might not find them.

Spawning Subprocesses

Ammonite-Ops provides easy syntax for anyone who wants to spawn sub-processes, e.g. commands like ls or git commit -am "wip". This is provided through the % and %% operators, which are used as follows:

In short, % lets you run a command as you would in bash, and dumps the output to standard-out in a similar way, returning the zero return-code upon successful command completion. This lets you run git commands, edit files via vim, open ssh sessions or even start SBT or Python shells right from your Scala REPL!

% throws an InteractiveShelloutException if the return-code is non-zero.

%% on the other hand is intended for programmatic usage: rather than printing to stdout, it returns a CommandResult, which contains the standard output .out and standard error .err of the subprocess. These provide helper methods to retrieve the stdout or stderr as a list of lines

Ammonite-Ops currently does not provide many convenient ways of piping together multiple processes, but support may come in future if someone finds it useful enough to implement.

% calls subprocesses in a way that is compatible with a normal terminal. That means you can easily call things like %vim to open a text editor, %python to open up a Python terminal, or %sbt to open up the SBT prompt!

Note how passing it in explicitly, you need to use a . before the command-name in order for it to parse properly. That's a limitation of the Scala syntax that isn't likely to change. Another limitation is that when invoking a file, you need to call .apply explicitly rather than relying on the plain-function-call syntax:

Ammonite-Shell

Replacing Bash for the 21st Century

The Ammonite-Shell is a rock-solid system shell that can replace Bash as the interface to your operating system, using Scala as the primary command and scripting language, running on the JVM. Apart from system operations, Ammonite-Shell provides the full-range of Java APIs for usage at the command-line, including loading libraries from Maven Central.

Why would you want to use Ammonite-Shell instead of Bash? Possible reasons include:

Shell Basics

Ammonite-Shell isn't backwards compatible with Bash. It isn't even the same language, giving you access to all of Scala instead of the quirky Bash scripting language. Nevertheless, lots of things you'd expect in Bash turn up in Ammonite-Shell:

Working Directory

bash$ pwd
/home/travis/build/lihaoyi/Ammonite

@ wd
res0: Path = root/'home/'travis/'build/'lihaoyi/'Ammonite

Bash's pwd is instead called wd. Instead of being a subprocess that prints to stdout, wd is simply a variable holding the working directory.

As you can see, the path syntax is also different: as an absolute path, wd must start from root and the path segments must be quoted as Scala "string"s or 'symbols. Apart from that, however, it is basically the same. The documentation about Paths goes over the syntax and semantics of Paths in more detail.

You can navigate around the filesystem using cd!, instead of Bash's cd:

Again, we have to use the quoted 'symbol/"string" syntax when defining Paths, but otherwise it behaves identically. You can press <tab> at any point after a / or halfway through a file-name to auto-complete it, just like in Bash.

ls, ls.rec and other commands are all functions defined by Ammonite-Ops.

Filesystem Operations

Ammonite-Shell uses Ammonite-Ops to provide a nice API to use filesystem operations. The default setup will import ammonite.ops._ into your Ammonite-REPL, gives the nice path-completion shown above, and also provides some additional command-line-friendly functionality on top of the default Ammonite-Ops commands:

Here, we're using the |? pipe, which basically performs a filter on the paths coming in on the left. In this case, we're checking that for each path, the first character of the last segment of that path is the character '.'. This is slightly more verbose than Bash the bash equivalent shown above, but not by too much.

For more examples of how to use Ammonite's pipes, check out the section on Extensions and Chaining

Subprocesses

Ammonite provides a convenient way to spawn subprocesses using the % and %% commands:

%cmd(arg1, arg2): Spawn a subprocess with the command cmd and command-line arguments arg1, arg2. print out any stdout or stderr, take any input from the current console, and return the exit code when all is done.

%%cmd(arg1, arg2): Spawn a subprocess similar to using %, but return the stdout of the subprocess as a String, and throw an exception if the exit code is non-zero.

For example, this is how you use the bash command to run a standalone bash script in Bash and Ammonite:

bash$ bash ops/src/test/resources/scripts/echo HELLO
HELLO

@ %bash('ops/'src/'test/'resources/'scripts/'echo, "HELLO")
HELLO

Note that apart from quoting each path segment as a 'symbol, we also need to quote "HELLO" as a string. That makes things slightly more verbose than a traditional shell, but also makes it much clearer when arguments are literals v.s. variables.

If you are only passing a single argument, or no arguments, Scala allows you to leave off parentheses, as shown:

bash$ git branch
* (HEAD detached at 5ef5ee1)
master

@ %git 'branch
* (HEAD detached at 5ef5ee1)
master

bash$ date
Mon Aug 13 09:49:01 UTC 2018

@ %date
Mon Aug 13 09:49:10 UTC 2018

You can use Ammonite-Ops' support for Spawning Subprocesses to call any external programs, even interactive ones like Python or SBT!

Scripting

Ammonite-Shell uses Scala as its command and scripting language. Although the commands seem short and concise, you have the full power of the language available at any time. This lets you do things that are difficult or infeasible to do when using a traditional shell like Bash.

Typed Values

In Ammonite-Shell, everything is a typed value and not just a stream of bytes as is the case in Bash. That means you can assign them to variables and call methods on them just like you can in any programming language:

This is often not required (e.g. in the earlier example), since Scala has type inference, but it may make your code clearer. Furthermore, if you make a mistake, having types annotated will help the compiler give a more specific error message.

The fact that variables are typed means if you try to perform the wrong operation on a variable, you get an error even before the code runs:

In general, apart from the filesystem-specific commands, you should be able to do anything you would expect to be able to do in a Scala shell or Java project. This documentation isn't intended to be a full tutorial on the Scala language, check out the Scala Documentation if you want to learn more!

Scala/Java APIs

Apart from the pipe operators described in the earlier section on Piping, Ammonite-Shell allows you to call any valid Scala method on any value; it's just Scala after all! Here's an example using normal Scala collection operations to deal with a list of files, counting how many files exist for each extension:

In fact, Ammonite-Shell allows you to ask for any published third-party Java/Scala library for usage in the shell, and have them downloaded, automatically cached, and made available for use. e.g. we can load popular libraries like Google Guava and using it in the shell:

Writing/Loading Scripts

You can write scripts in the same way you write commands, and load them using import $file. To read more about this, check out the documentation on Script Files.

Design Decisions & Tradeoffs

Ammonite-Shell takes a fundamentally different architecture from traditional shells, or even more-modern shell-alternatives. Significant differences include:

The command & scripting language is a standard, well-known application language (Scala) rather than one specially-designed for the shell

The shell runs on the JVM, and can execute or integrate-with arbitrary Java/JVM code or libraries.

In this section we'll examine each of these decisions and their consequences in turn. As the incumbents in this space, we'll be looking at traditional system shells like Bash, Zsh or Fish, as well as popular non-system REPLs like the Python/IPython REPL.

Scala as the Language

The use of Scala as the command & scripting language is unusual among shells, for many reasons. Firstly, most shells implement their own, purpose built language: Bash, Zsh, Fish, and even more obscure ones like Xonsh each implement their own language. Secondly, all of these languages are extremely dynamic, and apart from those most popular languages with REPLs (Python, Ruby, Javascript, ...) tend to be dynamical, interpreted languages. Scala falls at the opposite end of the spectrum: statically typed and compiled.

The code being entered in the shell takes time to compile. The first command easily takes 3-4 to compile, and even when the compiler is "warm" there is a 0.2-0.3 second delay before any command begins executing.

Many mistakes get caught even before a command begins executing. This is less valuable for small commands that execute quickly, but for slower commands processing more data, it is nice to get an error after 0.2s of compilation rather than 10s into execution.

Apart from the differences between Scala and dynamic languages (Python, Ruby, etc.) for REPL usage, Scala is even further away from the sort of ad-hoc, ultra-dynamic languages most often associated with traditional shells (Bash, sh, zsh, etc.). In particular:

Scala provides a set of proper data structures for you to work with. Rather than just byte-streams, you have unicode Strings, proper numbers like Int or Double, absolute Paths and relative RelPaths, Arrays, Maps, Iterators and all sorts of other handy data-structures. Many commands return objects which have fields: this sounds simple until you realize that none of bash/zsh/fish behave this way.

Scala is a general-purpose language: you can do math, you can work with Strings, you can write non-trivial algorithms quickly and easily. While this is not surprising coming from a Python REPL, these simple tasks are difficult-to-impossible in traditional system shells like Bash.

Scala runs most code in the same process. While you can shell-out to subprocesses in Ammonite using the % syntax, most commands like ls! and rm! are simple functions living in-process rather than in separate processes. This reduces the overhead as compared to spawning new processes each time, but does cause some additional risk: if a command causes the process to crash hard, the entire shell fails. In bash, only that command would fail.

The latter set of tradeoffs would be also present in many of the shell-replacements written in dynamic languages, like Xonsh which is written in Python. The earlier set, on the other hand, are pretty unique to Ammonite using Scala. There are both positive and negative points in this list.

Running on the JVM

Running Ammonite directly on the JVM again is very different from how most shells work: most have their own scripting language, and their own interpreter. Most are implemented in C. What is it like running your code directly as bytecode on the JVM? Here are some of the negatives:

You get JVM boot time; although some of the initial several-second delay is due to the Scala compiler's slowness, some of it is also due to the cost of JVM classloading and initialization. While a hello-world JVM project loads instantly, one which uses a large number of class-files takes longer. In contrast, shells written in C load basically instantly.

You get the JVM bloat: Ammonite, implemented in only a few thousand lines of code, wraps up to become a 30mb .jar file. That's already larger than most other shells out there, and gets >100mb larger if you bundle the JVM along with it! In general, the JVM class-file format is bloated and inefficient, and there is no way to exclude to numerous un-needed parts of the JVM during the initial download. Project Jigsaw will help with this when it finally lands in Java 9.

Ammonite uses hundreds of megabytes (~500mb at last count) of memory, again orders-of-magnitude more than an interpreter written in C or Python. The JVM has traditionally been a very pointer-heavy, memory-intensive platform for running code, and it shows. Project Valhalla would help with this, also scheduled to land in Java 9.

In general, the JVM has traditionally been used as a server-side platform for long-running services, and its slow-startup and bloated disk/memory footprints are a symptom of that. Running on the JVM also has some upsides, though:

Ammonite code runs ridiculously fast, once you've paid 0.2-0.3s for its compilation. 50x faster than Python or Bash! This is not a trivial multiplier, and really makes a different if you're dealing with non-trivial data sets: a computation that takes a minute in Ammonite might take an hour if done at the Python REPL! This means that a moderately-large computation which may require special tools, libraries or optimizations to perform in Python might be trivial to implement naively in Ammonite while still enjoying reasonable speed.

Ammonite can make use of any JVM APIs, and there are a lot of them! The JVM is a general-purpose platform for a general purpose language (Java), and thus has APIs for doing all sorts of things: dealing with dates and times, math, networks, threads, and many other things. While you may not always need all of these capabilities, it is nice to have them at your disposal where necessary.

Ammonite can make use of any Java/JVM libraries, and the excellent infrastructure used by Java developers to download and manage them! Any library is just a import $ivy away. Need to parse Python source into an AST? Load Jython and just do it. Need a high-performance web server? Load Akka-HTTP. Need some data someone stored in a YAML file? Load SnakeYAML and parse it. You don't even need to download and manage these libraries yourself: just import $ivy them from Ammonite, and Java's excellent dependency-management infrastructure will download them (along with any transitive dependencies!), cache them locally, and make them available to your code.

There are both pros and cons with running Ammonite on the JVM: we gain its heavy startup/memory overhead, but also get access to its high-performance JIT, massive ecosystem of available packages.

Goals of Ammonite-Shell

Overall, Ammonite-Shell blurs the line between a "programming language REPL" like IPython or Ruby's IRB and a "system shell" like Bash or Zsh. Like system shells, Ammonite-Shell provides concise filesystem operations, path-completion, and easy spawning of subprocesses. Like programming language REPLs, it provides a full-fledged, general-purpose language for you to use, rather than a crippled cut-down command-language that is available in most system shells.

The goal is to provide something general enough to use as both a system shell and a general-purpose programming language. Traditionally, there has always been some tension when deciding between these:

Should I write this script in Bash? I'm already using Bash as my shell

It's getting complicated, I can't follow the logic in Bash. Should I re-write it in Python?

If I write it in Python, I'll need to deal with argument-parsing and forwarding between Bash and Python and Bash, which is annoying

Since my scripts are in Python, should I use Python/IPython as my shell instead of Bash when dealing with these things?

But if I use Python/IPython as my shell, basic filesystem operations becomes impossible

Traditionally, there really has been no good answer to this dilemma: whether you use Bash or Python to write your scripts, whether you use Bash or Python as your shell, there is always something frustrating about the set-up.

With Ammonite-Shell, there is no dilemma. You can use the same concise, general-purpose language for your shell as you would for your scripts, large or small. In Ammonite-Shell, you can concisely deal with files at the command-line with the same language you use to write maintainable scripts, large or small, and the same language that you use to write rock-solid application code.

Ammonite Cookbook

Fun with Scala-Scripting!

The Ammonite Scala REPL and Scripts are meant to be extended: you can load
in arbitrary Java/Scala modules from the internet via
import $ivy. Using this third-party code, you
extend the REPL to do anything you wish to do, and tools like
Ammonite-Shell are simply modules like any other. Simple
install Java, download Ammonite onto any
Linux/OSX machine, and try out one of these fun snippets! They work
directly in the Ammonite-REPL, or you can save them to
Scala Scripts if you want something more permanent.

In this example, we use the Scalaj HTTP library to download a URL, and we use uPickle and Ammonite-Ops to parse the JSON and write it into files. uPickle and Ammonite-Ops are bundled with the Ammonite REPL and are used internally, and while Scalaj HTTP isn't, we can simply load it from the public repositories via load.ivy.

This is a small example, but it illustrates the potential: if you find yourself needing to scrape some website or bulk-download large quantities of data from some website's HTTP/JSON API, you can start doing so within a matter of seconds using Ammonite. The results are given to you in nicely structured data, and you can deal with them using any Java or Scala libraries or tools you are used to rather than being forced to munge around in Bash. Sometimes, you may find that you need to get data from somewhere without a nice JSON API, which means you'd need to fall back to Scraping HTML...

Scraping HTML

Not every website has an API, and not every website is meant to be accessed programmatically. That doesn't mean you can't do it! Using libraries like JSoup, you can quickly and easily get the computer to extract useful information from HTML that was meant to humans. Using the Ammonite REPL, you can do it interactively and without needing to set up annoying project scaffolding.

If you wanted to scrape headlines off some news-site or scrape video game reviews off of some gaming site, you don't need to worry about setting up a project and installing libraries and all that stuff. You can simply load libraries like Jsoup right into the Ammonite REPL, copy some example from their website, and start scraping useful information in less than a minute.

GUI Applications

The Ammonite REPL runs on the Java virtual machine, which means you can use it to create Desktop GUI applications like anyone else who uses Java! Here's an example of how to create a hello-world interactive desktop app using Swing

This can be run inside the Ammonite REPL without installing anything, and will show the following window with a single button:

When clicked, it changes text:

Although this is just a small demo, you can use Ammonite yourself to experiment with GUI programming without needing to go through the hassle of setting up an environment and project and all that rigmarole. Just run the code right in the console! You can even interact with the GUI live in the console, e.g. running this snippet of code to add another action listener to keep count of how many times you clicked the button

Even while you're clicking on the button, you can still access count in the console:

@ count
res12: Int = 6

This is a level of live interactivity which is traditionally hard to come by in the world of desktop GUI applications, but with the Ammonite REPL, it's totally seamless

Office Automation

Apart from writing code, you very often find yourself dealing with documents and spreadsheets of various sorts. This is often rather tedious. Wouldn't it be cool if you could deal with these things programmatically? It turns out that there are open-source Java libraries such as Apache POI that let you do this, and with the Ammonite-REPL you can quickly and easily load these libraries and get to work on your favorite documents. Here's an example extracting some data from my old Resume, in .docx format:

As you can see, loading the Apache POI library is just a single command, reading in my resume file is just one or two more, and then you can immediately start exploring the document's data model to see what inside interests you. You even get tab-completion on the methods of the document, making it really easy for you to interactively explore all the things that a word document has to offer!

This is just a small example, but you can easily do more things in the same vein: Apache POI lets you create/modify/save .docx files in addition to reading from them, meaning you can automatically perform batch operations on large numbers of documents. The library also provides mechanisms to load in Excel spreadsheets and Powerpoint slide decks, meaning you have easy, programmable access to the great bulk of any Microsoft-Office files you find yourself dealing with.

Image Processing

You can perform lots of image operations in Java. You can use BufferedImage if you want to access the low-level details or read/write individual pixels, and using Java2D you can draw shapes, perform transforms, or do anything you could possibly want to do with the images.

There are also simple libraries like Thumbnailator if you're doing basic things like renaming/resizing/rotating and don't need pixel-per-pixel access. This is an example of using Thumbnailator to resize a folder of images and put them somewhere else:

Machine Learning

The word "Machine Learning" sounds big and intimidating, like something you'd need to spend 6 years getting a PhD before you understand. What if you could "do some machine-learning" (whatever that means) in your spare time, in a minute or two? It turns out there are many Java libraries that can help you with basics, and with the Ammonite REPL getting started is easy.

Here's one example of how you can get started using the OpenNLP project to do some natural-language processing in just a few minutes. The example was found online, and shows how to extract English names from a raw String using NLP:

This took a while, but only in comparison to the earlier cookbook recipes: this one is still less than 20 steps, which is not bad for something that installs multiple third-party modules, pulls down training data off the internet, and then does natural language processing to extract the English names from a text blob!

Obviously we did not go very deep into the field. If you did, it would definitely be a lot more reading and understanding than just blindly following tutorials like I did above, and you probably would find it worth the time to set up a proper project. Nevertheless, this quick 5-minute run through of how to perform the basics of NLP is a fun way to get started whether or not you decide to take it further, and is only possible because of the Ammonite REPL!

Ammonite's script-running capabilities can also be used as a way to set up lightweight Scala projects without needing SBT or an IDE to get started. For example, here is a single-file Play Framework test that

Spins up a HTTP server and

Makes a single HTTP request against it and prints the response

Shuts down the server.

And can be run via

./amm PlayFramework.sc

Although this is just a hello world example, you can easily keep the server running (instead of exiting after a test request) and extend it with more functionality, possibly splitting it into multiple Script Files.

SQL Database

Ammonite is great for those database jobs that are too complicated for SQL alone. This example uses ScalikeJDBC to update some rows.

1.0.1

Ammonite REPL now prints an additional newline after the output of
each command, which should visually separate each command and make it
easier to skim over your command history in the terminal or when
copy-pasted elsewhere.

Fix for issue #668 where comments in identifiers are not properly
backticked causing the repl to stop working correctly

1.0.0

We recently launched a Patreon page
to raise money to fund future development of Ammonite. If you've enjoyed using
Ammonite, and use it day to day, please
chip in to support our project!

Output now defaults to colored if the console is interactive, and
non-colored otherwise. This should be a default most people would
be happy with.

Scripts now have colored output by default if the script-runner is
interactive, following the above rules. Much of the script "info"
output like "Compiling" or "Watching for changes" messages are now
colored.

There is now a cli-flag --color which can be set to
true or false to force colors on or off if you
are not happy with the default behavior.

The repl.colors builtin has been moved to interp.colors,
and allows you to fine-grained customize colors for e.g. error
messages and info messages when running scripts.

Using import $file on an empty script files no longer
causes spurious errors

Caches are properly invalidated if a script you import $file
is deleted

-w/--watch now watches predef files as well. This means
if you make changes to your predef (e.g. if it was crashing and you're
trying to fix it), Ammonite will re-run your scripts automatically

Improved error handling of failures within predef; they should no
longer show large stack traces containing irrelevant stack frames

Predef files no longer cause problems with autocomplete in the REPL

Parse errors within a file will now show the proper file-name, rather
than <console>.

Ctrl C interrupts now place an exception with a useful stack
trace in repl.lastException, which can help debug where your
code was at when you interrupted it.

Ctrl C no longer crashes the REPL if you perform it after
entering a command but before your code starts running

Ammonite's REPL now warms up the compiler while you are typing your
first command; this makes it likely that the compilation will be fast
if you take a moment to enter your command, and shouldn't
significantly effect the time taken otherwise

interp.load.exec and interp.load.apply
have been moved to repl.load.exec and repl.load.apply,
and are now not available when running scripts: they never had a
really well-defined semantic when run within scripts. Using
repl.load.exec or repl.load.apply within the
predef.sc of your REPL is still possible

The interp.watch built-in now works on folders as well as
files, watching all files within that folder and restarting your
script if any of them change

Fix regression that broke binding of variables in Main#run

Make --watch flag more robust against files being deleted
during mtimeing, and make it properly re-run scripts when a
file in a watched folder is renamed.

Display @doc annotations on a script's @main
methods as part of the script's help text, thanks to
mgedigian

You can now use ::: as part of your import $ivy
calls to load Scala libraries cross-published against the full
Scala version (e.g. 2.12.2 rather than just 2.12, thanks
to aeffrig

Ammonite now supports opening a Script Debug REPL after a
script runs, with your script's scope loaded so you can poke around
it interactively

The command line flags --predef/--predef-file are now
--predef-code/--predef respectively, to reflect that
using a custom predef file is much more common than a custom predef
code snippet.

ammonite.Main's argument predef has been renamed to
predefCode, and a new argument predefFile has been
added to match the command-line interface

--predef (previously --predef-file) now adds a file
in addition to the existing predef.sc or predefScript.sc
in ~/.ammonite. If you want it to replace the predef in
~/.ammonite, there is a new flag --no-home-predef that
disables the predef in ~/.ammonite so your --predef
file stands alone

~/.ammonite/predefShared.sc is gone; if you want it back, you
can do it yourself by adding import $exec.predefShared
within your predef.sc and predefScript.sc files. You
can also import any others files into your predef.sc and
predefScript.sc the same way

Ammonite now loads linux HTTP proxy environment variables into your
JVM's sys.props by default, when running as a standalone
executable. When using Ammonite within a SBT project, you will need
to do this manually, e.g. calling
ammonite.main.ProxyFromEnv.setPropProxyFromEnv() within the
predefCode that you pass to ammonite.Main

0.9.9

Ammonite scripts now show their usage text in Bash/Linux format,
rather than in Scala format, to better fit into the scripting ecosystem

0.9.8

Modified the way Ammonite Arguments in Scripts get passed.
Rather than separating Ammonite's args and a script's args with a
--, now any arguments before the script file are used by
Ammonite and any arguments after the script file get forwarded
to the script's @main method

Error messages for scripts are now consistently not colored, rather
than mostly being uncolored but sometimes turning up red

Scripts without a main method now properly show an error if arguments
are passed

Error messages from scripts are now more reliably sent to stderr
rather than stdout

All code within Ammonite's REPL and scripts now run within the context
of the ammonite package; this lets us avoid littering the
top-level package namespace with miscellaneous names like $file
and $sess

Remove foo ! bar ! baz implicit syntax, and
ChainableConversions implicit. They're cool, but not simple
enough to be worth including by default

0.9.7

0.9.6

Fixed an issue where down-stream scripts would not properly recompile
when the scripts they import changed

Ensure that importing the same script twice via a diamond-dependency
does not end up compiling it twice, and instead uses the first version
that was compiled

Path(...) no longer automatically expands ~ to your home
directory, for consistency with other filesystem APIs. Use
Path.expandUser to do so manually.

Add the -w/--watchWatch and Reload flag,
which lets you run a script repeatedly every time you change its code,
via amm -w foo.sc. This is useful when you are actively
working on the script and greatly reduces the iteration time. You can
also manually include files you wish to watch, e.g. if you are
iterating on external data or config files.

Experimental Apache Spark
support! You can now run basic Spark commands in Ammonite scripts,
as well as in the REPL. To do so, look up the Spark.sc
and Spark2.sc scripts in the repository as examples to
get started. Spark support is currently experimental, so feel free
to contribute fixes when you notice something missing or wrong!

Introduced a new interp.configureCompiler builtin, which lets
you configure the compiler in a way that's robust in the case of
caching and late/lazy initialization, fixing #472.
You should use interp.configureCompiler instead
of repl.compiler to configure it safely.

Properly run import hooks in multi-block scripts in the block that
they are defined, allowing you to add resolvers/repositories before
performing import $ivys in subsequent blocks. Fixes
#491

Revamped how Script Arguments are passed. When running
scripts, now the script file must *always* be the first argument to
the amm command. Any arguments after the script file get
delegated to the script's @main method(s) unless
there is a -- present, in which case arguments after the
-- get delegated to the script while those before get
passed to Ammonite. This allows you to define a @main
method with a vararg String* that accepts in all arguments
by default, letting you use your own custom arg parsers on the input
strings. Fixes #423, #479, #538

The return values of Ammonite scripts' @main methods
or exit(...) calls now gets pretty-printed by default when
the script completes. This make composing scripts much more convenient:
the same @main methods you use when printing output to the
command-line can also be used from Scala code when imported from
other scripts. To disable this, annotate your main method as returning
: Unit

exit can now be cleanly used in Scripts without failing
with a NullPointerException, in addition to its existing use
in the REPL.

Avoid crashes when non-existent paths are on the classpath, thanks to
Olivier Roland

Ammonite now anonymously logs the times you start a REPL session and
the count of how many commands get run. This is to allow the author
to understand usage patterns and prioritize improvements. If you wish
to disable it, pass in the --no-remote-logging command-line
flag or the remoteLogging=false argument to Main.

0.8.x

0.8.5

A nicer error message when you try to run a non-existent script (#522)

ammonite.ops.Path(s: String) now resolves ~ to the
home directory of the current user

Many improvements to classpath scanning and re-compilation logic (#542)
which should greatly reduce the time taken start Ammonite in an SBT project,
and avoid many existing problems with stale compilation caches.

Fix crash when you try to run an empty script

Miscellaneous info messages now go to stderr rather than stdout, so they
don't get mixed into your script output if you pipe into a file (#574)

0.7.6

When running scripts, Ammonite now prints out a "Compiling foo.sc..."
message if they're being compiled for the first time. If you want
this to not be the case, you can silence it using the same -s
switch, thanks to coderabhishek

The --predef-file switch now allows multiple inputs, allowing
you to pass in multiple files that all get evaluated as the predef

#448 Deprecate ammonite.ops.cwd in preference to ammonite.ops.pwd,
to help clear up confusion between cwd and local wds,
thanks to Julie Pitt

Set a default heap limit of 500 megabytes to the amm standalone
executable, so it no longer grows to the "default" of 1/4 your system
memory (typically multiple gigabytes) unnecessarily. If you need to
give it more memory, start it with JAVA_OPTS=-Xmx1500M amm

#453 Avoid un-wrapping {...} blocks in scripts, leaving
the unwrapping of Block Input only a feature of the interactive
REPL

0.7.5

-s cmd line switch makes ivy logs silent, though failures
will still be thrown as exception. Thanks to coderabhishek.

Added show and typeOf back into the default REPL
imports, since they are pretty useful

write.over in Ammonite-Ops should now properly
truncate files if the thing being written is shorter than the
original #441

Ammonite no longer incorrectly allows multiple expressions to be
evaluated on the same line #446

Compilation errors when there are multiple statements in a block
will no longer have redundant semicolons prefixed onto them #439

Improved the line-number-reporting in certain cases where you use
import $file.*

0.7.4

0.7.3

Actually avoid importing all the Repl API functions into
local scope, for reals

0.7.2

Hygienified the default namespace by avoiding importing all the
Repl API functions into local scope, instead leaving them
inside the repl object. This is a backwards incompatible
change!

Separated the APIs available from scripts (load.* and
resolvers in the interp object)
from those available from the REPL (in the repl object).
repl is not available when running scripts, unless you pass in
the --repl-api flag at the command line.

If you want to maintain the old behavior, e.g. for backwards-compat,
put a import repl._ in your ~/.ammonite/predef.sc and
import interp._ in your ~/.ammonite/predefShared.sc to
bring everything back into scope again.

predef.sc now only applies to the interactive REPL. If you
want predef code that applies to scripts use predefScript.sc,
or if you want predef code that applies to both you can use
predefShared.sc.

Added a version of desugar to Scala 2.10.x. It doesn't
print things as prettily/accurately as the 2.11.x version, but it's
better than nothing.

Changed the syntax for import $file segments outside your
current directory from import $file.`..`.foo to
import $file.^.foo. This makes it a lot shorter and
mitigates a problems caused by the file-name being too long.

You can now use a JAVA_OPTS environment variable to pass flags
to the JVM when starting Ammonite, thanks to Simon Scarduzio

Running scripts outside the current working directory tree, as well as
scripts with non-alphanumeric symbols in their file path, now works
thanks to coderabhishek

Scripts without the .sc can now be run directly from the command line
rather than throwing an IndexOutOfBoundsException, thanks to
coderabhishek

Modularized Ammonite's internals; the main module ammonite has now
been broken into 5 smaller modules for maintainability. This in
itself should not be visible to the outside world, but be sure to
report any bugs!

0.7.0

Backwards incompatibly changes the extensions from Scripts and Predef
files from .scala to .sc, to avoid problems with SBT
discovering and trying (and failing) to compile them as normal Scala
files.

Script files vastly faster to run once cached (~0.5s fixed overhead,
instead of ~5s I was seeing before): faster classpath scanning, with
much more aggressive and robust caching, thanks to coderabhishek who is
working on this over GSOC

Fixed a performance regression and greatly sped up pasting text into
the REPL

The behavior of Ctrl p and Ctrl n have been tweaked to
be more consistent with other readline implementations.

Magic Imports now exist! This should provide a much more
intuitive way of importing other files and depending on ivy
artifacts, without all the fumbling with @ that the
old load.foo functions required

The way you pass in Script Arguments to a script, has been
totally revamped, and should be faster, more intuitive, and provide
better error messages when things go wrong

Added a new top-level doc-site chapter on Scala Scripts.
This reflects their promotion from "quick hack that was a pain in
the neck to actually use" to
"something that actually feels pretty nice to use". If you've tried
running Ammonite scripts earlier and was totally turned off, it's
worth another shot.

Most of Ammonite now works on Windows, with the exception of the
interactive REPL using AmmoniteFrontEnd, thanks to
coderabhishek who worked
on this over GSOC.

Started doing Continuous Deployment of the Ammonite project's
artifacts and executables; now, any set of commits that get pushed
or merged into master will be published immediately, with this
documentation-site being updated, the standalone executable being
uploaded to Github Releases,
the Ivy artifacts being uploaded to maven central, and instructions
for downloading/installing it shown in the Unstable Versions
section below. Any PRs that get merged are published and become
available within an hour or two, so the author and anyone else can
begin using them.

0.5.x

0.5.9

Introduced the desugar helper to Ammonite-REPL,
letting you easily see what the compiler is transforming your code
into before it gets run.

Prefix _root_ to imports from packages, which should
reduce the chance of naming collisions

Improved source locations for error messages: now failures in
scripts have a filename matching the name of the script (instead of
Main.scala), and line numbers matching the original line
numbers (instead of the line numbers in the synthetic code) thanks
to coderabhishek

Failures in scripts run using Ammonite from the command line or via
load.module should show only the meaningful error and not
irrelevant internal stacktraces

Wrapper names are now greatly simplified; now the names of wrapper
objects for scripts match the name of the script (e.g.
MyScript) rather than based on the code hash (e.g.
cache5a8890cd7c2ab07eea3fe8d605c7e188)

Placed most synthetic code into packages; loaded scripts go into
ammonite.scripts and code entered at the REPL goes in
ammonite.session.

Wrote some basic Internals Documentation
in case people want to read about the internal workings of Ammonite
in a way that's easier than digging through tons of code.

Changed the interface for Embedding Ammonite to make
configuring the Ammonite REPL before invoking it programmatically
much more consistent.

Unknown Ansi escape codes now have their '\u001b'
escape character removed, rather than messing up the REPL rendering

0.5.8

write has been generalized to work on any combination of
Array, Traversable and Iterator.
e.g. write(foo: Iterator[Iterator[Array[String]]])

write no longer inserts newlines between items by default.

Introduced the browse helper to Ammonite-Shell,
letting you easily open up large data structures in external editors
like Vim or Emacs to browse them without spamming the console

Improved the error messages for invalid Path segments to
make them more specific and suggest alternatives to what a user is
trying to do.

Broke out the FilePath sub-trait from the
BasePath trait, to differentiate those
BasePaths are filesystem paths and can be constructed from
java.nio.file.Path or java.io.Files
(RelPath and Path)from those which can't
(ResourcePath)

Path.makeTemp has been renamed tmp() and
tmp.dir()

Arrow-keys now work properly in the previously odd case where they
were creating \u033O{A,B,C,D}" codes instead of
\u033[{A,B,C,D} codes

Converted all string-encoding methods to take a
scala.io.Codec instead of a String or
Charset, letting you pass in either of those types and
having it be implicitly converted.

0.5.7

Improved performance of various read! commands to be
competitive with java.nio (#362)

read! and read.lines! now take an optional
charset, passed via read(file, charSet: String) or
read.lines(file, charSet: String) which defaults to
"utf-8"

Make read! resource read from the
Thread.currentThread.getContextClassLoader by default,
fixing #348

Re-organize Reading Resources in Ammonite-Ops to allow
proper handling of absolute and relative resources by passing in
Classs or ClassLoaders

Make read! work on InputStreams

Renamed InputPath to Readable, a more
appropriate name now that it works on two different non-path entities
(resources and InputStreams)

Page-up and Page-down (fn-up and fn-down on Macs) scrolls through
history when used at the start/end of input, allowing you to use
page-up/page-down to quickly scroll through history with lots of
multi-line blocks.

0.5.5

Experimental support for Ammonite-Ops in Windows! I haven't tested
it but basic CI passes here, so try it out
and let me know if there are problems (#120)

Changes around Ammonite-Ops's definition of Paths: they
now wrap a java.nio.file.Path (#346), and thus can be used on
Windows, on multiple drives, or with virtual filesystems such as
JimFS.

Construction of Paths from various types
(Strings, java.nio.file.Path,
java.io.File) is much more well behaved & consistent now.
See Constructing Paths for details.

read.resource! root/'foo is now
read! resource/'foo

Parser improvements which fix bugs when trying to write some
multi-line snippets #343

Wrapping content is automatically shifted onto a new line, to avoid
problems when copying and pasting #205

Thrown exceptions are now made available to you in the REPL under
the repl.lastException variable #289, in case you need more
metadata from it or you want the stack-trace of a
non-printed-by-default exception (e.g. ThreadDeath due to
Ctrl-C). Thanks to coderabhishek!

Exception stack traces are now highlighted as well, to make them easier to read

Pretty-printing has been
extracted into a separate project, and aside from that is greatly
improved. Many more common cases (e.g. sealed trait hierarchies)
are now pretty-printed rather than falling back to toString

Exposed the show function
by default, letting you pretty-print any value with custom
configuration (wrapping-width, truncation-height, colors, ...)

Fixed cases where PPrint/TPrint was causing compilation errors

Persistent data is now stored in a ~/.ammonite folder. This
includes ~/.ammonite/history,
~/.ammonite/predef.scala, and various cache, thanks to
Laszlo Mero

You can now define a ~/.ammonite/predef.scalaConfiguration file which will be executed the first
thing when the Ammonite REPL is loaded. This is useful for common
imports, load.ivying libraries, or other configuration
for your REPL

Performance improvements to the startup time of the REPL, with
more to come

Third-party library resolution via load.ivy is now cached
after the first call, letting you e.g. load libraries in your
~/.ammonite/predef.scala without waiting for the slow
ivy-resolution every startup

Standardized the use of Refs for configuration, including
the ability to bind them "live" to the value of an expression.

Allows you to trivially spawn subprocesses, letting you run git commands, edit
files via vim, open ssh sessions or even start
SBT or Python shells right from your Scala REPL

0.3.x

0.3.2

Fix pretty-printing of higher-kinded types.

Drop support for 2.10.x; ammonite is 2.11.x-only now

0.3.1

Many of the collection PPrints are much lazier and will
avoid stringifying the whole collection if it's going to get truncated
anyway.

Types now get printed semi-qualified (depending on what's in scope),
with simple highlighting.

You can define custom TPrint[T]s to provide custom
printing for any type.

Operator-named two-param generic types are now printed infix by
default.

0.3.0

allow predef parameter to be passed into
Main.run() call, letting you configure initialization
commands or imports

Compilation errors in expressions no longer show synthetic code in
the message

Ivy module loading now lets you configure verbosity level

Defining macros in the REPL and using them in subsequent lines now
works

Output lines are now truncated past a certain length, which is
configurable, thanks to Laszlo Mero

0.2.x

0.2.9

Lots of improvements to Ctrl-C and Ctrl-D handling, to
make it behave more like other REPLs

Capture Exceptions and expose them to repl as repl.lastException
including exceptions causing Failures

Unstable Versions

The page above contains the documentation for the latest stable version
of Ammonite, 1.1.2. Ammonite also publishes
unstable versions, the latest of which is
1.1.2-25-5ef5ee1 and is available for direct
download:

These unstable versions will contain any brand-new features that are
currently being worked on, with the caveat that they are unstable and
these features are subject to change or experimentation. They will
generally work - the automated test suite is pretty comprehensive - but
they are still more-likely to have bugs than numbered releases.

Any pull-request that gets merged into master is published as an unstable
version automatically within an hour or two of being merged, so if you
notice some problem and know how to fix it, send a PR, get it merged, and
you can use the published unstable version with your fix until the next
numbered release.