The REPL and main entry points


The clojure.main namespace

The clojure.main namespace provides functions that allow Clojure programs and interactive sessions to be launched via Java's application launcher tool java.

clojure.main --help

The clojure.main/main entry point accepts a variety of arguments and flags as described in its usage message:
Usage: java -cp clojure.jar clojure.main [init-opt*] [main-opt] [arg*]
 
With no options or args, runs an interactive Read-Eval-Print Loop
 
init options:
-i, --init path Load a file or resource
-e, --eval string Evaluate expressions in string; print non-nil values
 
main options:
-r, --repl Run a repl
path Run a script from from a file or resource
- Run a script from standard input
-m, --main A namespace to find a -main function for execution
-h, -?, --help Print this help message and exit
 
operation:
 
- Establishes thread-local bindings for commonly set!-able vars
- Enters the user namespace
- Binds *command-line-args* to a seq of strings containing command line
args that appear after any main option
- Runs all init options in order
- Runs a repl or script if requested
 
The init options may be repeated and mixed freely, but must appear before
any main option. The appearance of any eval option before running a repl
suppresses the usual repl greeting message: "Clojure ~(clojure-version)".
 
Paths may be absolute or relative in the filesystem or relative to
classpath. Classpath-relative paths have prefix of @ or @/

Launching a REPL

The simplest way to launch a Clojure repl is to use the following command line from within Clojure's home directory:
java -cp clojure.jar clojure.main
The REPL prompt shows the name of the current namespace (*ns*), which defaults to user.

Several special vars are available when using the REPL:
  • *1, *2, *3 - hold the result of the last three expressions that were evaluated
  • *e - holds the result of the last exception.

The clojure.repl namespace has a number of useful functions for inspecting the source and documentation of available functions:
  • doc - prints the docstring for a var given its name
  • find-doc - prints the docstring for any var whose doc or name matches the pattern
  • apropos - returns a seq of definitions matching a regex
  • source - prints the source for a symbol
  • pst - print stack trace for a given exception or *e by default

Launching a Script

To run a file full of Clojure code as a script, pass the path to the script to clojure.main as an argument:
java -cp clojure.jar clojure.main /path/to/myscript.clj

Passing arguments to a Script

To pass in arguments to a script, pass them in as further arguments when launching clojure.main:
java -cp clojure.jar clojure.main /path/to/myscript.clj arg1 arg2 arg3
The arguments will be provided to your program as a seq of strings bound to the var *command-line-args*:
*command-line-args* => ("arg1" "arg2" "arg3")

Related functions


Main Entry Point: clojure.main/main

Reusable REPL: clojure.main/repl

Allowing set! for the customary REPL vars: clojure.main/with-bindings
Logo & site design by Tom Hickey.