• Table of contents
• Install
  • With Quicklisp
  • With a core image
  • With a binary. Use CIEL's custom REPL.
• Usage
  • Scripting
  • Shell REPL
  • Lisp library
  • Core image: use CIEL in your current developer setup
• Libraries
• Language extensions
• Final words
• How to generate the documentation

Table of contents   TOC

• Install

  • With Quicklisp
  • With a core image
  • With a binary. Use CIEL's custom REPL.

• Usage

  • Scripting
  • Shell REPL
  • Lisp library
  • Core image: use CIEL in your current developer setup
• Libraries
• Language extensions
• Final words
• How to generate the documentation

Install

You will probably need the following system dependencies (names for a Debian system):

libmagic-dev libc6-dev gcc  # from magicffi

With Quicklisp

You need a Lisp implementation and Quicklisp installed.

CIEL is not yet on Quicklisp, but it is on Ultralisp.

So, either clone this repository:

git clone https://github.com/ciel-lang/CIEL ~/quicklisp/local-projects/CIEL

either install the Ultralisp distribution and pull the library from there:

(ql-dist:install-dist "http://dist.ultralisp.org/" :prompt nil)

Then, load the .asd file (with asdf:load-asd or C-c C-k in Slime), quickload "ciel":

(ql:quickload "ciel")

and enter the ciel-user package:

(in-package :ciel-user)

With a core image

You need a Lisp implementation, but you don't need Quicklisp.

Build a core image for your lisp with all CIEL's dependencies:

sbcl --load build-image.lisp

and use it:

sbcl --core ciel-core --eval '(in-package :ciel-user)'

Then you can configure Slime to have the choice of the Lisp image to start. See below in /mirrors/ciel/src/commit/2804f115d0c35df1aa52993feb733abb81e96fa2/%2AUse%20CIEL%20at%20startup

We will distribute ready-to-use core images can not distribute core images, you must build it yourself.

With a binary. Use CIEL's custom REPL.

You don't need anything, just download the CIEL executable and run its REPL. You need to build the core image yourself though.

• we provide an experimental binary for Debian systems: go to https://gitlab.com/vindarel/ciel/-/pipelines, download the latest artifacts, unzip the ciel-v0.zip archive and run ciel-v0/ciel.

TODO: build it for different platforms.

To build it, clone this repository and run make build.

Start it with ./ciel.

You are dropped into a custom Lisp REPL, freely based on sbcli.

This REPL is more user friendly than the default SBCL one:

• it has readline capabilities, meaning that the arrow keys work by default (wouhou!) and there is a persistent history, like in any shell.
• it has multiline input.
• it has TAB completion.
• it handles errors gracefully: you are not dropped into the debugger and its sub-REPL, you simply see the error message.
• it has optional syntax highlighting.
• it has an optional lisp critic that scans the code you enter at the REPL for instances of bad practices.
• it has a shell pass-through: try !ls.
• it has documentation lookup shorthands: use :doc symbol or ? after a symbol to get its documentation: ciel-user> (dict ?.
• it has developer friendly macros: use (printv code) for an annotated trace output.
• and it defines more helper commands:

  %help => Prints this general help message
  %doc => Prints the available documentation for this symbol
  %? => Inspect a symbol: %? str
  %w => Writes the current session to a file <filename>
  %d => Dumps the disassembly of a symbol <sym>
  %t => Prints the type of a expression <expr>
  %lisp-critic => Toggles the lisp-critic
  %q => Ends the session.

See more in the documentation.

Usage

Scripting

NOTE: this is brand new! Expect limitations and changes.

Get the ciel binary and call it with a .lisp file:

$ ciel script.lisp

An example script:

;; Start your script with this to access all CIEL goodies:
(in-package :ciel-user)

;; We have access to the STR library:
(print (str:join "-" (list "I" "am" "a" "lisper")))

;; We have access to the DICT notation for hash-tables:
(print "testing dict:")
(print (dict :a 1 :b 2))

;; format! prints on standard output and flushes the streams.
(format! t "cmd?")

;; We can run shell commands:
(cmd:cmd "ls")

(format! t "Let's define an alias to run shell commands with '!'. This gives: ")
(defalias ! #'cmd:cmd)
(! "pwd")

;; In cas of an error, we can ask for a CIEL toplevel REPL:
(handler-case
    (error "oh no")
  (error (c)
    (format! t "An error occured: ~a" c)
    (format! t "Here's a CIEL top level REPL: ")
    (sbcli::repl :noinform t)))

Output:

"I-am-a-lisper"
"testing dict:"

 (dict
  :A 1
  :B 2
 )
cmd? ABOUT.org	    ciel		     ciel-core
 bin		    docs		     src
 […]
Let's define an alias to run shell commands with '!'. This gives:
/home/vindarel/projets/ciel
ciel-user>

Shell REPL

Run ciel with no arguments:

$ ciel

       _..._
    .-'_..._''.                         .---.
  .' .'      '..--.      __.....__     |   |
 / .'           |__|  .-''         '.   |   |
. '             .--. /     .-''''-.  `. |   |
| |             |  |/     /________   |   |
| |             |  ||                  ||   |
. '             |  |    .-------------'|   |
  '.          .|  |     '-.____...---.|   |
  '. `._____.-'/|__|  `.             .' |   |
    `-.______ /         `''-...... -'   '---'
             `


--------------------------------------------------------------------------------
OS: Linux 5.4.0-124-generic
Lisp: SBCL 2.0.1.debian
ASDF: 3.3.4.15
Quicklisp: (#<DIST quicklisp 2022-07-08>)
--------------------------------------------------------------------------------
CIEL's REPL version 0.1.5
Read more on packages with readme or summary. For example: (summary :str)
Special commands:
  %help => Prints this general help message
  %doc => Print the available documentation for this symbol.
  %? => Gets help on a symbol <sym>: :? str
  %w => Writes the current session to a file <filename>
  %d => Dumps the disassembly of a symbol <sym>
  %t => Prints the type of a expression <expr>
  %q => Ends the session.
  %lisp-critic => Enable or disable the lisp critic. He critizes the code you type before compiling it.
  %edit => Edit a file with EDITOR and evaluate it.
Press CTRL-D or type :q to exit

ciel-user>

Lisp library

You can install and quickload CIEL like any other Common Lisp library.

To use it in your project, create a package and "use" ciel in addition of cl:

  (defpackage yourpackage
    (:use :cl :ciel))

You can also use generic-ciel, based on generic-cl:

  (defpackage yourpackage
    (:use :cl :generic-ciel))

generic-cl allows us to define our + or equalp methods for our own objects (and more).

Core image: use CIEL in your current developer setup

You can enter the CIEL-USER package when you start your Lisp image from your editor.

A working, but naive and slow-ish approach would be to add this in your ~/.sbclrc:

(ql:quickload "ciel")
(in-package :ciel-user)
(ciel-user-help)

A faster way is to use CIEL's core image and to use SLIME's or your editor's feature to configure multiple Lisps.

You need to:

• build CIEL's core image for your machine (make image),
• add this to your Emacs init file:

  (setq slime-lisp-implementations
        `((sbcl    ("sbcl" "--dynamic-space-size" "2000"))  ;; default. Adapt if needed.
          (ciel-sbcl  ("sbcl" "--core" "/path/to/ciel/ciel-core" "--eval" "(in-package :ciel-user)"))))
  (setq slime-default-lisp 'ciel-sbcl)

• and start a new Lisp process.
• optional: if you didn't set it as default with slime-default-lisp, then start a new Lisp process with M-- M-x slime (alt-minus prefix), and choose ciel-sbcl. You can start more than one Lisp process from SLIME.

The Lisp process should start instantly, as fast as the default SBCL, you won't wait for the quicklisp libraries to load.

Libraries

We import, use and document libraries to fill various use cases: generic access to data structures, functional data structures, string manipulation, JSON, database access, web, URI handling, GUI, iteration helpers, type checking helpers, syntax extensions, developer utilities, etc.

See the documentation.

To see the full list of dependencies, see the ciel.asd project definition or this dependencies list.

Language extensions

We provide arrow macros, easy type declaratons in the function lambda list, macros for exhaustiveness type checking, pattern matching, etc.

See the documentation.

Final words

That was your life in CL:

and now:

How to generate the documentation

See src/ciel.lisp and run (generate-dependencies-page-reference).