The magic-ed Reference Manual

Table of Contents

The magic-ed Reference Manual

This is the magic-ed Reference Manual, version 0.2, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 16:58:23 2021 GMT+0.

1 Introduction

Magic (ed)

Magic (ed) is a tiny editing facility for Common Lisp, where you can directly load, edit, manipulate and evaluate file or file content from REPL.

I find myself often running the REPL for various things but lazy enough to engage Emacs/SLIME when I need just a small edit: I'm a UNIX guy and I got used to start vi/vim/emacsclient for writing small throw-away programs.

This package also can be a starting point for people who are not accustomed to Emacs or SLIME and would like to continue using their default terminal/console editor with Common Lisp.

Quickinstall and start

Install via Quicklisp, which updates distro about once a month.

(ql:quickload "magic-ed")

For simple editing from the REPL, launch your system configured EDitor

(ed "file-name.lisp")

For the daily updates track, install via Ultralisp. You can also install manually. See instructions for other installation options and use below.

Usage

You start it with:

(magic-ed:magic-ed "/tmp/test.lisp")

and it will start editor assigned to EDITOR environment variable. When you are done with editing, save it and quit: magic-ed will load that file and evaluate it. If file saving somehow failed, nothing will be evaluated.

In background, magic-ed will try to use (ed) standard function and will try to obey implementation specific features. For example, in SBCL, if sb-ext:*ed-functions* was set, magic-ed will not use environment value.

If you do not want edited file to be evaluated, you use :eval parameter like:

(magic-ed:magic-ed "/tmp/test.lisp" :eval nil)

and file will be only saved. Also, if you would like file content to be returned as escaped string, use :output parameter (accepts only :file and :string):

(setf content (magic-ed:magic-ed "/tmp/test.lisp" :output :string))

Installation options

First setup EDITOR environment variable to point to your favorite editor (on *nix, often nano or vi, distribution dependent config and change) and download magic-ed code via Quicklisp, Ultralisp, or manually (clone it from this repository).

Ultralisp via Quicklisp

Magic-ed is available on Ultralisp. Ultralisp updates more often than Quicklisp, so this install is recommended.

Install Quicklisp, install Ultralisp. Then use the standard Quicklisp installation method.

Manual download or via Quicklisp

Do an update of the QL database and install:

(ql:update-dist "quicklisp")
(ql:quickload "magic-ed")

ASDF

(asdf:load-system :magic-ed)

Manual install:

Download or git clone magic-ed to Your quicklisp directory manually
( usually ~/quicklisp/local-projects/ )

For example, execute in terminal:

cd ~/quicklisp/local-projects/

git clone https://github.com/sanel/magic-ed 

Then, launch Your Common Lisp of choice and in the REPL:

(ql:quickload :magic-ed)

Automatic loading on REPL start with Quicklisp

Update Your Common Lisp configuration, adding the following line to the same file responcible for loading quicklisp on start.

In SBCL: edit Your ~/.sbclrc and add to the end, after ql lines:

(ql:quickload :magic-ed)

Compatibility

The magic-ed code was tested on SBCL, ECL, Clozure CL and CMUCL.

License

Copyright (c) 2013-2020 Sanel Zukan. You can use this code however you like, in accordance with the MIT license.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 magic-ed

Author

Sanel Zukan. https://github.com/sanel/magic-ed/

License

MIT

Description

Edit your code from REPL.

Version

0.2

Dependency

sb-introspect

Source

magic-ed.asd (file)

Component

src/magic-ed.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 magic-ed.asd

Location

magic-ed.asd

Systems

magic-ed (system)

3.1.2 magic-ed/src/magic-ed.lisp

Parent

magic-ed (system)

Location

src/magic-ed.lisp

Packages

magic-ed

Exported Definitions

• ed-editor (function)
• magic-ed (function)

Internal Definitions

• namestring-for-editor (function)
• slurp-file (function)

4 Packages

Packages are listed by definition order.

4.1 magic-ed

Source

src/magic-ed.lisp (file)

Use List

• sb-alien
• common-lisp

Exported Definitions

• ed-editor (function)
• magic-ed (function)

Internal Definitions

• namestring-for-editor (function)
• slurp-file (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Functions

Function: ed-editor THING

Package

magic-ed

Source

src/magic-ed.lisp (file)

Function: magic-ed &optional FILE &key OUTPUT EVAL

Call editor from REPL and depending on options, return to REPL or evaluate the file content in REPL. This function will try to use implmentation specific (ed) function, which will in turn invoke editor set in EDITOR environment variable. Some Common Lisp implementations uses different strategy for setting external editor, so if unsure what they are, make sure to consult your implementation documentation first.

If called without file, this function will invoke editor without file argument.

Supported options are:

:eval (t or nil) - if :eval was set to nil, saved content will not be evaluated
:output (:file or :string) - by default, content will be saved to file; if you want the content to
be returned as escaped string, set ’:output :string’.

Package

magic-ed

Source

src/magic-ed.lisp (file)

5.2 Internal definitions

5.2.1 Functions

Function: namestring-for-editor EDITOR THING

Package

magic-ed

Source

src/magic-ed.lisp (file)

Function: slurp-file PATH

Slurp file from given path.

Package

magic-ed

Source

src/magic-ed.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types