* 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]]. ** Rationale One of our goals is to make Common Lisp useful out of the box for mundane tasks -by today standards. As such, we ship libraries to handle JSON and CSV, as well as others to ease string manipulation, to do pattern matching, to bring regular expressions, for threads and jobs scheduling, for HTTP and URI handling, to create simple GUIs with Ltk, and so on. You can of course do all this without CIEL, but then you have to install the library manager first and load these libraries into your Lisp image every time you start it. Now, you have them at your fingertips whenever you start CIEL. We also aim to soften the irritating parts of standard Common Lisp. A famous one, puzzling for beginners and non-optimal for seasoned lispers, is the creaton of hash-tables. We include the =dict= function from the Serapeum library (which we enhanced further with a pull request): #+begin_src CIEL-USER> (dict :a 1 :b 2 :c 3) #+end_src which prints: #+begin_src txt (dict :A 1 :B 2 :C 3 ) #+end_src In standard Common Lisp, the equivalent is more convoluted: #+BEGIN_SRC lisp (let ((ht (make-hash-table :test 'equal))) (setf (gethash :a ht) 1) (setf (gethash :b ht) 2) (setf (gethash :c ht) 3) ht) ;; # ;; (and we don't get a readable representation, so our example is not even equivalent) #+end_src Moreover, we want to bring a **full featured REPL on the terminal** (see more below). See [[docs/README.md][the documentation]]. * 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 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: #+begin_src txt :help => Prints this general help message :doc => Prints the available documentation for this symbol :? => Gets help on a symbol : :? str :w => Writes the current session to a file :d => Dumps the disassembly of a symbol :t => Prints the type of a expression :lisp-critic => Toggles the lisp-critic :q => Ends the session. #+end_src See more in [[docs/README.md][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:

and now: #+html:

* How to generate the documentation See =src/ciel.lisp= and run =(generate-dependencies-page-reference)=.