* CIEL Is an Extended Lisp                                         :noexport:

STATUS: the API WILL change, but it is usable.


* What is this ?                                                   :noexport:

  CIEL is a collection of useful libraries.

  It's Common Lisp, batteries included.

  Questions, doubts? See the [[file:docs/FAQ.md][FAQ]].


* TODOs                                                            :noexport:

- settle on libraries that help newcomers
- automate the documentation
- distribute (Quicklisp, Qlot, Quicklisp distribution, Ultralisp,
  Ultralisp distribution (upcoming)…)
- ship a core image and a binary
- optionnal: create a tool that, given a CIEL code base, explains what
  packages to import in order to switch to "plain CL".

How to procede ?

This is an experiment. I'd be happy to give push rights to more
maintainers. We will send pull requests, discuss, and in case we don't
find a consensus for what should be on by default, we can create other
packages.

Rules

- don't install libraries that need a Slime helper to work in the REPL (cl-annot).
- reader syntax changes may not be enabled by default.

* Table of contents :TOC:
- [[#install][Install]]
  - [[#with-quicklisp][With Quicklisp]]
  - [[#with-a-core-image][With a core image]]
  - [[#with-a-binary-use-ciels-custom-repl][With a binary. Use CIEL's custom REPL.]]
- [[#libraries][Libraries]]
- [[#final-words][Final words]]
- [[#how-to-generate-the-documentation][How to generate the documentation]]

* Install

** With Quicklisp

You need a Lisp implementation and Quicklisp installed.

CIEL is not yet on Quicklisp (but it is on [[https://ultralisp.org][Ultralisp]]), so clone this
repository and load the .asd (with =load= or =C-c C-k= in
Slime).

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

Then, quickload it:

#+BEGIN_SRC lisp
(ql:quickload "ciel")
#+end_src

and enter the =ciel-user= package, instead of the default
=common-lisp-user= (or =cl-user=):

#+BEGIN_SRC lisp
(in-package :ciel-user)
#+end_src

** 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 --eval '(in-package :ciel-user)'

TODO: we will distribute ready-to-use core images.

** With a binary. Use CIEL's custom REPL.

   You don't need anything, just download the CIEL executable and run
   its REPL.

   TODO: build it on CI for different platforms.

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

   Start it with =./ciel-repl=.

   You are dropped into a custom Lisp REPL, freely based on [[https://github.com/hellerve/sbcli][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 also defines short helper commands:

#+begin_src txt
  :help => Prints this general help message
  :doc => Prints 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>
  :lisp-critic => Toggles the lisp-critic
  :q => Ends the session.
#+end_src

- it has a *shell pass-through*: try =!ls=.

See the documentation.

* 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 [[docs/README.md][the documentation]].

  To see the full list of dependencies, see the =ciel.asd= project
  definition or this [[file:doc/dependencies.md][dependencies list]].


* Final words

That was your life in CL:

#+html: <p align="center"><img src="docs/before.jpeg" /></p>

and now:

#+html: <p align="center"><img src="docs/after-plus.jpeg" /></p>

* How to generate the documentation

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