This is the shelly Reference Manual, version 0.8.6, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 06:41:32 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
shelly
Run Common Lisp from shell easily.
Eitaro Fukamachi
BSD 2-Clause
# Shelly - Make Common Lisp shell-friendly.
## Announcement: Release of v0.7.5
Perl5 isn’t required to use Shelly from v0.7.0 because I rewrote it in shell script.
You can install the latest version by this command:
$ curl -L http://shlyfile.org/shly | /bin/sh
If you already have an older version of it, you can upgrade it by this command:
$ shly install –version latest
## Usage
Usage: shly [option,..] <command> [arg1,arg2..]
Examples:
$ shly asdf:test-system :clack
$ shly ql:update-all-dists –prompt nil
$ shly -Lclack clackup /path/to/project/app.lisp
$ shly -Lclack clack.app.directory:start-server
$ shly -Ldrakma http-request http://www.hatena.com/
$ shly -Lcl-project make-project /path/to/myapp/ –description "My sample app." –author "Eitaro Fukamachi"
## Description
Shelly enables you to execute Common Lisp functions like a shell command. And it also can be used as a Make-like build-tool.
Shelly has the following features:
* Provides shell command-like interface for Common Lisp functions
* Dumps a Lisp core for fast execution.
* Allows to define project specific commands. (shlyfile)
* Implementation independent.
<strong><span style="color:red">Warning</span>: This software is still ALPHA quality. The APIs will be likely to change.</strong>
## Why use it?
In Common Lisp world, most libraries and applications are designed to run on REPL. It is convenient for interactive development, but it would be an obstacle in some cases.
For example, Common Lisp isn’t good for writing a small script. No common way to write it in a portable way. Parsing command-line arguments is really annoying. And, the startup time would be very slow, especially when it uses some libraries.
Shelly solves these problems by providing a shell-friendly interface of Common Lisp. If your application need to run with Cron, Supervisord or other CUI applications, this may help you.
### 1. Implementation independent
Shelly should work fine with one of SBCL, Clozure CL, Allegro CL, ABCL, GNU CLISP and ECL.
### 2. Function as a shell command
Shelly treats general functions as its sub-commands, so you don’t even need to write a script in most cases.
(in-package :myapp)
(defun do-something (&key verbose)
;; Do something.
)
$ shly myapp:do-something –verbose t
Command-line options and arguments will be delivered to a function.
### 3. Fast startup
Shelly reduces the startup time by storing a Lisp core image. In a simple case, the execution is about 33 times faster than CIM’s ‘cl‘ command and even 25 times faster than SBCL (with Quicklisp) at the maximum.
# Uses SBCL v1.2.1, Shelly v0.7.0
$ time shly + 1 2
3
shly + 1 2 0.02s user 0.03s system 102% cpu 0.047 total
# CIM v1.0.0
$ time cl –eval ’(princ (+ 1 2))’
3
cl –eval ’(princ (+ 1 2))’ 0.67s user 0.11s system 96% cpu 0.805 total
# SBCL with Quicklisp
$ time sbcl –noinform –eval ’(princ (+ 1 2))’ –eval ’(quit)’
3
sbcl –noinform –eval ’(princ (+ 1 2))’ –eval ’(quit)’ 0.51s user 0.09s system 99% cpu 0.606 total
# SBCL without Quicklisp
$ time sbcl –noinform –no-userinit –eval ’(princ (+ 1 2))’ –eval ’(quit)’
3
sbcl –noinform –no-userinit –eval ’(princ (+ 1 2))’ –eval ’(quit)’ 0.00s user 0.01s system 89% cpu 0.012 total
## How does it work
Shelly provides a shell script "shly". It takes some options, a command, and arguments for the command.
Usage: shly [option,..] <command> [arg1,arg2..]
In this example, ‘ql:system-apropos‘ would be the command and ‘web‘ would be an argument.
;; Same as (ql:system-apropos "web")
$ shly ql:system-apropos web
#<SYSTEM bknr.modules / bknr-web-20140616-git / quicklisp 2014-06-16>
#<SYSTEM bknr.web / bknr-web-20140616-git / quicklisp 2014-06-16>
#<SYSTEM cl-web-crawler / cl-web-crawler-20130128-svn / quicklisp 2014-06-16>
#<SYSTEM cl-webdav / cl-webdav-0.2.1 / quicklisp 2014-06-16>
#<SYSTEM crane-web / crane-20140616-git / quicklisp 2014-06-16>
#<SYSTEM hh-web / hh-web-20140616-git / quicklisp 2014-06-16>
...
If an argument starts with ":", it would be converted into a keyword.
;; Same as (asdf:system-source-file :hunchentoot).
$ shly asdf:system-source-file :hunchentoot
#P"/Users/nitro_idiot/quicklisp/dists/quicklisp/software/hunchentoot-1.2.21/hunchentoot.asd"
If an argument starts with "–", it also would be a keyword. This is just like common shell commands.
;; Same as (ql:update-all-dists :prompt nil)
$ shly ql:update-all-dists –prompt nil
If the command is imported to ‘COMMON-LISP-USER‘ package, you can omit the package prefix.
$ shly list 1 2 3
(1 2 3)
Or, if the package name is the same as the system name that is loaded by ‘-L‘ option, you can also omit it.
$ shly -Ldrakma http-request http://www.hatena.com/
$ shly -Lcl-project make-project /path/to/myapp/ –description "My sample app." –author "Eitaro Fukamachi"
## As a replacement of Makefile
Shelly loads a local file which is named ‘shlyfile.lisp‘ if it exists. You can define project specific commands by writing functions in it. This is just like a "Makefile" in Common Lisp.
“‘common-lisp
;; shlyfile.lisp
(defun test ()
(asdf:test-system :your-app))
(defun build ()
;; Somthing to build your app.
)
“‘
Then, ‘shly test‘ and ‘shly build‘ would be available only in the directory.
“‘
$ shly test
$ shly build
“‘
Shelly also loads ‘~/.shelly/shlyfile.lisp‘ every time if it exists. If you have some commands you’d like to use everywhere, put them into that file.
## Requirements
* Common Lisp implementation
* [Quicklisp](http://www.quicklisp.org/beta/)
If you’ve installed [CIM](https://github.com/KeenS/CIM), Shelly will use its setting.
## Installation
### Installing the latest version
Currently, the install script always installs the latest version because the stable version requires Perl5 and I suppose you may not expect it.
$ curl -L http://shlyfile.org/shly | /bin/sh
You can also install from the source code.
“‘
$ git clone https://github.com/fukamachi/shelly.git
$ cd shelly
$ SHELLY_PATH=. bin/shly install
“‘
As "shelly" directory will be copied to ~/.shelly, you don’t need the cloned repository after installation.
### Installing to other than ~/.shelly
If you want to install Shelly to the different location, set SHELLY_HOME to the directory path.
$ curl -L http://shlyfile.org/shly | SHELLY_HOME=~/.shly /bin/sh
### System-Wide installation
If ‘–global t‘ is specified to ‘install‘ command, it would be installed under ‘/usr/local‘.
$ curl -L http://shlyfile.org/shly | /bin/sh -s install –global t
## Configuration
If you use bash, zsh, csh or tcsh, the initialization code will be appended into your .*rc file automatically.
Otherwise, set SHELLY_HOME and add ~/.shelly/bin to PATH manually.
SHELLY_HOME="$HOME/.shelly"
[ -s "$SHELLY_HOME/lib/shelly/init.sh" ] && . "$SHELLY_HOME/lib/shelly/init.sh"
## Upgrading
“‘
shly upgrade
“‘
## Uninstalling
“‘
$ shly uninstall
$ rm -rf ~/.shelly
“‘
## Built-in Commands
### help [&optional command]
Show the usage of the specified ‘command‘.
$ shly help ql:quickload
Usage: ql:quickload (systems &key verbose prompt explain
(verbose *quickload-verbose*) (prompt *quickload-prompt*)
&allow-other-keys)
Load SYSTEMS the quicklisp way. SYSTEMS is a designator for a list
of things to be loaded.
If ‘command‘ is not specified, it shows all available commands. This is the same as ‘shly –help‘.
$ shly help
### install [&key version global directory]
Install Shelly into your environment under "~/.shelly". You can install a specific version by using "–version".
$ shly install –version v0.6.1
If ‘–directory‘ is specified, it would be installed to the directory.
$ shly install –directory ~/.local
If ‘–global‘ is specified with non-NIL value, it would be installed to ‘/usr/local/‘ (Same as ‘–directory /usr/local‘).
$ shly install –global t
### uninstall [&key directory]
Uninstall Shelly.
$ shly uninstall
### available-versions
Show all the possible Shelly versions.
$ shly available-versions
### dump-core
Dump Lisp core image file for faster startup.
$ shly dump-core
### rm-core
Remove saved core image file which created by ‘dump-core‘.
$ shly rm-core
### local-dump-core [&rest systems] \(Experimental)
Dump Lisp core image file to the current directory. This command takes system names to be included in the core.
$ shly local-dump-core :myapp
### install-command [package-or-function-name]
Make an executable file under SHELLY_HOME/bin/.
# Making a function executable.
$ shly -Lclack install-command clack:clackup
# Same as (clack:clackup #P"/path/to/app.lisp")
$ clackup /path/to/app.lisp
# Making a package executable.
$ shly -Lclack install-command clack.app.directory
# Same as (clack.app.directory:start-server :port 50032)
$ clack.app.directory start-server –port 50032
## History (roughly)
### v0.8.6 (Oct 27, 2014)
* Support Cygwin even for CCL. Thanks to [@lambdasakura](https://github.com/lambdasakura).
### v0.8.5 (Oct 3, 2014)
* Support Cygwin (only with SBCL). Thanks to [@lambdasakura](https://github.com/lambdasakura).
### v0.8.1 (Aug 4, 2014)
* Allow to specify where to install (‘–directory‘ option).
* Add ‘–global‘ to ‘install‘.
* Add ‘uninstall‘ command.
### v0.8.0 (Aug 2, 2014)
* Add ‘install-command‘ command (for SBCL, CCL and GNU CLISP).
### v0.7.0 (July 15, 2014)
* Use CIM for CL implementation management if it is installed.
* Rewrite "bin/shly" in Shell script.
* Remove the dependency on SWANK.
* Allow to specify where to install with ‘SHELLY_HOME‘.
* Add ‘upgrade‘ command.
### v0.6.0 (Mar 31, 2014)
* Add ‘local-dump-core‘ (experimental).
* Allow multiple ‘-L‘ options.
* Add a new option ‘-I‘ to add a directory path to ‘asdf:*central-registry*‘.
### v0.5.8 (Nov 12, 2013)
* Muffle outputs of ‘ql:quickload‘ when ‘–verbose‘ isn’t specified.
### v0.5.0 (Aug 29, 2013)
* Allow to install the specific version of Shelly.
* Show commands even in "shlyfile"s.
### v0.4.0 (Aug 26, 2013)
* Add "shlyfile" feature.
## Note: Conversion rules
### Number
$ shly type-of 24
(INTEGER 0 4611686018427387903)
$ shly type-of 3.141592653589793d0
DOUBLE-FLOAT
### Cons
$ shly type-of ’(list 1 2 3)’
CONS
### Boolean
If it is "t" or "nil", it would be ‘T‘ or ‘NIL‘.
$ shly type-of t
BOOLEAN
$ shly type-of nil
NULL
### Keyword
If it starts with ":" or "–", it would be a keyword.
$ shly type-of :web
KEYWORD
$ shly type-of –verbose
### Pathname
If the same name file exists, it would be a pathname. Otherwise, it would be just a string.
$ shly type-of test.lisp
(SIMPLE-ARRAY CHARACTER (9))
$ touch test.lisp
$ shly type-of test.lisp
PATHNAME
### Symbol
If the same name symbol exists, it would be a symbol.
$ shly pi
DOUBLE-FLOAT
$ shly asdf:\*central-registry\*
CONS
### String
Otherwise, it would be treated as a string.
$ shly common-lisp-is-great
(SIMPLE-ARRAY CHARACTER (20))
## Copyright
Copyright (c) 2012-2014 Eitaro Fukamachi and [contributors](https://github.com/fukamachi/shelly/graphs/contributors).
## License
Licensed under the BSD (2-Clause) License. See LICENSE.
0.8.6
split-sequence
(system).
cl-fad
(system).
bordeaux-threads
(system).
local-time
(system).
trivial-signal
(system).
babel
(system).
uiop
(system).
src
(module).
Modules are listed depth-first from the system components tree.
shelly/src
shelly
(system).
shelly.lisp
(file).
core.lisp
(file).
install.lisp
(file).
versions.lisp
(file).
util.lisp
(file).
impl.lisp
(file).
error.lisp
(file).
Files are sorted by type and then listed depth-first from the systems components trees.
shelly/shelly.asd
shelly/src/shelly.lisp
shelly/src/core.lisp
shelly/src/install.lisp
shelly/src/versions.lisp
shelly/src/util.lisp
shelly/src/impl.lisp
shelly/src/error.lisp
shelly/src/shelly.lisp
core.lisp
(file).
install.lisp
(file).
versions.lisp
(file).
util.lisp
(file).
src
(module).
available-versions
(function).
help
(function).
shelly/src/core.lisp
impl.lisp
(file).
error.lisp
(file).
util.lisp
(file).
src
(module).
canonicalize-arg
(function).
print
(function).
prompt
(function).
read
(function).
shelly/src/install.lisp
core.lisp
(file).
impl.lisp
(file).
versions.lisp
(file).
util.lisp
(file).
src
(module).
dump-core
(function).
install
(function).
install-command
(macro).
local-dump-core
(function).
rm-core
(function).
uninstall
(function).
upgrade
(function).
configure-shell
(function).
csh-style-init
(function).
dumped-core-path
(function).
install-from-path
(function).
install-function-command
(function).
install-package-command
(function).
sh-style-init
(function).
uninstall-with-path
(function).
shelly/src/versions.lisp
src
(module).
download-version
(function).
find-version
(function).
find-version-name
(function).
release-versions
(function).
version<
(function).
version<=
(function).
extract-tarball
(function).
i
(macro).
qlrequire
(function).
retrieve-releases
(function).
version-tarball-url
(function).
shelly/src/util.lisp
error.lisp
(file).
impl.lisp
(file).
src
(module).
add-load-path
(function).
arglist
(function).
check-version
(function).
copy-directory
(function).
load-global-shlyfile
(function).
load-local-shlyfile
(function).
load-systems
(function).
local-command-symbols
(function).
print-package-commands
(function).
shadowing-use-package
(function).
shelly-home
(function).
terminate
(function).
with-retrying-when-system-not-found
(macro).
load-shlyfile
(function).
shelly/src/impl.lisp
src
(module).
*current-lisp-name*
(special variable).
*current-lisp-path*
(special variable).
*eval-option*
(special variable).
command-line-args
(function).
condition-undefined-function-name
(function).
save-app
(function).
save-core-image
(function).
shelly/src/error.lisp
src
(module).
shelly-command-not-found-error
(condition).
shelly-error
(condition).
shelly-read-error
(condition).
Packages are listed by definition order.
shelly.install
common-lisp
.
split-sequence
.
dump-core
(function).
install
(function).
install-command
(macro).
local-dump-core
(function).
rm-core
(function).
uninstall
(function).
upgrade
(function).
configure-shell
(function).
csh-style-init
(function).
dumped-core-path
(function).
install-from-path
(function).
install-function-command
(function).
install-package-command
(function).
sh-style-init
(function).
uninstall-with-path
(function).
shelly.error
common-lisp
.
shelly-command-not-found-error
(condition).
shelly-error
(condition).
shelly-read-error
(condition).
shelly.util
common-lisp
.
split-sequence
.
add-load-path
(function).
arglist
(function).
check-version
(function).
copy-directory
(function).
load-global-shlyfile
(function).
load-local-shlyfile
(function).
load-systems
(function).
local-command-symbols
(function).
print-package-commands
(function).
shadowing-use-package
(function).
shelly-home
(function).
terminate
(function).
with-retrying-when-system-not-found
(macro).
load-shlyfile
(function).
shelly.core
common-lisp
.
canonicalize-arg
(function).
print
(function).
prompt
(function).
read
(function).
shelly
common-lisp
.
split-sequence
.
available-versions
(function).
help
(function).
shelly.impl
common-lisp
.
*current-lisp-name*
(special variable).
*current-lisp-path*
(special variable).
*eval-option*
(special variable).
command-line-args
(function).
condition-undefined-function-name
(function).
save-app
(function).
save-core-image
(function).
shelly.versions
common-lisp
.
split-sequence
.
download-version
(function).
find-version
(function).
find-version-name
(function).
release-versions
(function).
version<
(function).
version<=
(function).
extract-tarball
(function).
i
(macro).
qlrequire
(function).
retrieve-releases
(function).
version-tarball-url
(function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Make an executable file under SHELLY_HOME/bin/.
Example:
$ shly -Lclack install-command clack:clackup
$ shly -Lclack install-command clack.app.directory
$ clackup /path/to/app.lisp
$ clack.app.directory start-server –port 50032
Show all the possible Shelly versions.
Dump Lisp core image file for faster startup.
Show a list of Built-In Commands.
If ‘command’ is specified, its usage will be displayed.
Install Shelly into your environment under "~/.shelly". You can install a specific version by using "–version".
(Experimental)
Dump Lisp core image file to the current directory.
This command takes system names to be included in the core.
Remove saved core image file which created by ‘dump-core’.
Start Read-Eval-Print Loop for interactive execution.
Uninstall Shelly.
Upgrade Shelly to the latest version.
:command
simple-error
.
:expression
Jump to: | A C D E F H I L M P Q R S T U V W |
---|
Jump to: | A C D E F H I L M P Q R S T U V W |
---|
Jump to: | *
C E S |
---|
Jump to: | *
C E S |
---|
Jump to: | C E F I M P S U V |
---|
Jump to: | C E F I M P S U V |
---|