clojure-lanterna / docs / index.markdown

clojure-lanterna is a thin wrapper around the Lanterna Java library to make it more Clojure-friendly.

It's still pre-1.0, so expect brokenness and backwards incompatibility. Once it hits 1.0 you can be confident I'll stop breaking your shit all the time.

License: GNU Lesser GPL (yes, you can link with code under another license!)

What is It?

Lanterna is a Java library for interacting with terminals. It's kind of like curses, except it's pure Java so it'll run anywhere. It lets you move the cursor around, draw colored text, and so on.

It also contains a simple Swing "terminal emulator", so you can run your code either in the terminal or in a separate Swing window when you don't have a real terminal available (inside an IDE or on a certain terrible OS).

It's particularly nice for writing Roguelikes.

How to Use It

There are three main layers to Lanterna. Currently clojure-lanterna supports the first two layers of Lanterna: Terminal and Screen. At some point support may be added for the GUI layer, but not any time soon.

To get started:

  1. Read the first page of the Lanterna documentation. It sums up some main concepts and things you'll need to watch out for.

  2. Come back here and read the Installation docs to get clojure-lanterna on your machine.

  3. Read the Terminal and Screen documents here in order.

  4. Have fun! Consult the Reference document if you need more detailed information about something. Most functions also have docstrings.

I Want a Hello, World!

Okay, fine:

(require '[lanterna.screen :as s])

(def scr (s/get-screen))

(s/stop scr)

(s/put-string scr 10 10 "Hello, world!")
(s/put-string scr 10 11 "Press any key to exit!")
(s/get-key-blocking scr)

(s/stop scr)

But really, please read the docs if you actually want to use this. They're not that long.