The cl-indentify Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-indentify Reference Manual

This is the cl-indentify Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Nov 04 12:19:05 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-indentify

A library and command line utility to automatically indent Common Lisp source files.

Installation

For command line usage cl-indentify currently requires roswell. Once roswell is installed enter the following in a shell.

$ ros install yitzchak/cl-indentify

Functionality

Inspired by scmindent/lispindent cl-indentify attempts to deal with more complex indention by using with a template system that can specify the indention characteristics of subforms in addition to the top level form.

Templates are generally selected by the head form of a list. For example, in the following cl-indentify will attempt to select a template with a key name of "LET".

(let
    ((fu 1)
     (bar 2))
  (+ fu bar))

Templates can configure a number of aspects of the indention characteristic, but the main behavior is controlled by the template :style key.

:call Style

The default style is :call which calculates indention based a fixed length "primary" group and a variable "secondary" group. For example, with-slots is defined to have two subforms in the primary group and the remaining in the secondary group. The primary group is indented by four columns and the secondary group is indented by two columns by default.

(with-slots
    (fu bar) wibble
  (quux bar)
  (+ fu bar))

If the first subform is on the same line as with-slots the following subforms that begin on a newline are aligned with the first subform.

(with-slots (fu bar)
            wibble
  (quux bar)
  (+ fu bar))

Likewise, if the first secondary subform is on the same line as the last primary subform the following subforms that begin on a newline are aligned with the first secondary subform. This can be seen in the case of if which has a primary count of one. Normally would be indented as

(if fu
  bar
  quux)

When the "then" class is on the same line as the test expression then the "else" clause will be aligned to the "then" clause.

(if fu bar
       quux)

If a template cannot be found for the head subform then the :call style is assumed with a primary count of zero.

The template for subforms can be explicitly specified using the :sub key. The value is a list of templates or a nil if the default template should be used. For :call and :tag style the first item in the list should always be a nil as this is the template for head subform. This is only used for :list styles. If the length of the :sub value is less then the length of the form then the last item in :sub will be used.

For example, the template for cond is the following, which specifies that all secondary group subforms will have a style of :call with a primary count of zero.

(:style :call
 :count 0
 :sub (nil
       (:style :call
        :count 0)))

This results in

(cond
  ((not ch)
    :eof)
  ((char= ch #\!)
    :bang)
  (t
    ch))

:tag Style

:tag style behaves exactly as :call in respect to primary and secondary groups, but will align tag names that appear in special forms such as tagbody with the head subform. For example do*

(do* ((pos 0 (1+ pos))
      (wibble 7))
     ((= pos 20))
  (when (= pos 20)
    (go fu))
  (format t "~A~%" pos)
 fu
  (format t "~A~%" wibble))

:quote Style

:quote style will indent the form and any subforms as if it a quoted literal. List subforms will aligned the head subform.

(1
 2
 3)

'(fu bar
  3
  (wibble
   quux))

:list Style

:list style is like :quote style but subforms will be indented according to their own templates or may be specified by the :sub key as in :call. For example, let has its primary subform style as :list with the following template

(:style :call
 :count 1
 :sub (nil
       (:style :list
        :sub ((:style :call :count 0)))
       nil))

This results in

(let (quux
      (fu 1)
      (bar
        (wibble 7)))
  (+ fu bar))

Command Line Usage

Using cl-indentify as a stdin/stdout filter is simple.

$ echo bar.lisp | cl-indentify

To read directly from a file just specify the filename on the command line.

$ cl-indentify bar.lisp

The output can be sent to a specific file versus stdout via the --outfile option.

$ cl-indentify -o fu.lisp bar.lisp

Multiple files can be processed at one time by specifying them on the command line. The output will be sent to the file in the --outfile option or stdout unless the --replace option is used to replace the original files.

$ cl-indentify -r fu.lisp bar.lisp

Configuration

Unless the --no-defaults option is specified then cl-indentify will load a set of default templates. After these templates are loaded then cl-indentify will look in the user's config home for a template file according the XDG specification. For instance, on Linux this would be ~/.config/cl-indentify/templates.lisp, which can be supressed by using the --no-user option. Additional template files can be loaded using the --templates options. For example, the following suppresses defaults and user templates and loads the template files wibble and quux.

$ cl-indentify --no-defaults --no-user --templates wibble -t quux fu.lisp

Template files should be in Sexpr format with each item a list that specifies the indention characteristics of a function or macro. For instance, the following specifies that defun has a primary count of two. It also specifies that defmethod has a primary count of two but that quantifiers :before, :after, and :around should be ignored in accumulating the primary count. case is defined to have a primary count of one and secondary forms are defined to have a primary count of zero.

(defun :style :call
       :count 2
       :sub (nil nil
             (:style :list)
             nil))

(defmethod :style :call
           :count 2 
           :ignore (:before :after :around) 
           :sub ((:style :list)
                 (:style :list)
                 nil))

(case :style :call
      :count 1 
      :sub (nil nil 
            (:style :call :count 0)))

Editor Usage

Text editors often provide the ability to interface with an external code filter/beautifier. The following are instructions for various editors.

Gnome Builder Usage

Create a file ~/.config/gnome-builder/beautifier_plugin/commonlisp/config.ini with the following contents. Please note that GtkSourceView must support Common Lisp syntax highlighting (v4.5.91).

[global]
default = indentify

[indentify]
command-pattern = cl-indentify @s@
name = Indentify

Vim Usage

To set a local variant of the equal command based on extension add the following to ~/.vimrc or approriate config file.

autocmd bufread,bufnewfile *.lisp,*.asd,*.ros setlocal equalprg=cl-indentify

If you are using the filetype plugin you can use the following

autocmd filetype lisp setlocal equalprg=cl-indentify

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 cl-indentify

Author

Tarn W. Burton

License

MIT

Description

A code beautifier for Common Lisp.

Version

0.1

Dependencies
Source

cl-indentify.asd (file)

Component

src (module)


Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 cl-indentify/src

Parent

cl-indentify (system)

Location

src/

Components

Next: , Previous: , Up: Top   [Contents][Index]

4 Files

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


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 cl-indentify.asd

Location

cl-indentify.asd

Systems

cl-indentify (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 cl-indentify/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

indentify


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 cl-indentify/src/verbatim-stream.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/verbatim-stream.lisp

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.4 cl-indentify/src/defaults.lisp

Dependency

verbatim-stream.lisp (file)

Parent

src (module)

Location

src/defaults.lisp

Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

4.1.5 cl-indentify/src/indenter.lisp

Dependency

defaults.lisp (file)

Parent

src (module)

Location

src/indenter.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

5.1 indentify

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Special variables

Special Variable: *indent-templates*
Package

indentify

Source

indenter.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Functions

Function: indent-template NAME
Package

indentify

Source

indenter.lisp (file)

Writer

(setf indent-template) (generic function)

Function: indentify &optional INPUT-STREAM OUTPUT-STREAM
Package

indentify

Source

indenter.lisp (file)

Function: initialize-templates ()
Package

indentify

Source

indenter.lisp (file)

Function: load-default-templates ()
Package

indentify

Source

indenter.lisp (file)

Function: load-template-file PATH
Package

indentify

Source

indenter.lisp (file)

Function: load-user-templates ()
Package

indentify

Source

indenter.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.3 Generic functions

Generic Function: (setf indent-template) VALUE NAME
Package

indentify

Source

indenter.lisp (file)

Reader

indent-template (function)

Methods
Method: (setf indent-template) VALUE (SYM symbol)
Method: (setf indent-template) VALUE (NAME string)

Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Special variables

Special Variable: +alexandria-templates+
Package

indentify

Source

defaults.lisp (file)

Special Variable: +asdf-templates+
Package

indentify

Source

defaults.lisp (file)

Special Variable: +common-lisp-templates+
Package

indentify

Source

defaults.lisp (file)

Special Variable: +uiop-templates+
Package

indentify

Source

defaults.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Macros

Macro: increment-column COLUMN CHAR
Package

indentify

Source

verbatim-stream.lisp (file)

Macro: with-verbatim STREAM &body BODY
Package

indentify

Source

verbatim-stream.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Functions

Function: align-with-spaces STREAM
Package

indentify

Source

verbatim-stream.lisp (file)

Function: load-templates &rest TEMPLATE-GROUPS
Package

indentify

Source

indenter.lisp (file)

Function: normalize-template TEMPLATE
Package

indentify

Source

indenter.lisp (file)

Function: number-token-p TOKEN
Package

indentify

Source

indenter.lisp (file)

Function: scan-chunk STREAM &optional TEMPLATE
Package

indentify

Source

indenter.lisp (file)

Function: scan-form STREAM &optional TEMPLATE
Package

indentify

Source

indenter.lisp (file)

Function: scan-forms STREAM &optional TEMPLATE
Package

indentify

Source

indenter.lisp (file)

Function: scan-indent STREAM &optional TEMPLATE
Package

indentify

Source

indenter.lisp (file)

Function: scan-line-comment STREAM &optional TEMPLATE
Package

indentify

Source

indenter.lisp (file)

Function: scan-sharpsign STREAM &optional TEMPLATE
Package

indentify

Source

indenter.lisp (file)

Function: scan-sharpsign-asterisk STREAM &optional TEMPLATE
Package

indentify

Source

indenter.lisp (file)

Function: scan-sharpsign-backslash STREAM &optional TEMPLATE
Package

indentify

Source

indenter.lisp (file)

Function: scan-sharpsign-rational DIGITS STREAM &optional TEMPLATE
Package

indentify

Source

indenter.lisp (file)

Function: scan-sharpsign-vertical-bar STREAM &optional TEMPLATE
Package

indentify

Source

indenter.lisp (file)

Function: scan-string STREAM &optional TEMPLATE
Package

indentify

Source

indenter.lisp (file)

Function: scan-token STREAM &optional TEMPLATE
Package

indentify

Source

indenter.lisp (file)

Function: select-subtemplate POS TEMPLATES
Package

indentify

Source

indenter.lisp (file)

Function: select-template TEMPLATE COMPLETED-FORM-COUNT
Package

indentify

Source

indenter.lisp (file)

Function: symbol-char-p CHAR
Package

indentify

Source

indenter.lisp (file)

Function: symbol-names SYM
Package

indentify

Source

indenter.lisp (file)

Function: write-symbol-to-string PACKAGE-NAME SYMBOL-NAME &key EXPORTED
Package

indentify

Source

indenter.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.4 Generic functions

Generic Function: input-column OBJECT
Generic Function: (setf input-column) NEW-VALUE OBJECT
Package

indentify

Methods
Method: input-column (VERBATIM-STREAM verbatim-stream)

automatically generated reader method

Source

verbatim-stream.lisp (file)

Method: (setf input-column) NEW-VALUE (VERBATIM-STREAM verbatim-stream)

automatically generated writer method

Source

verbatim-stream.lisp (file)

Generic Function: input-stream OBJECT
Generic Function: (setf input-stream) NEW-VALUE OBJECT
Package

indentify

Methods
Method: input-stream (VERBATIM-STREAM verbatim-stream)

automatically generated reader method

Source

verbatim-stream.lisp (file)

Method: (setf input-stream) NEW-VALUE (VERBATIM-STREAM verbatim-stream)

automatically generated writer method

Source

verbatim-stream.lisp (file)

Generic Function: output-column OBJECT
Generic Function: (setf output-column) NEW-VALUE OBJECT
Package

indentify

Methods
Method: output-column (VERBATIM-STREAM verbatim-stream)

automatically generated reader method

Source

verbatim-stream.lisp (file)

Method: (setf output-column) NEW-VALUE (VERBATIM-STREAM verbatim-stream)

automatically generated writer method

Source

verbatim-stream.lisp (file)

Generic Function: output-stream OBJECT
Generic Function: (setf output-stream) NEW-VALUE OBJECT
Package

indentify

Methods
Method: output-stream (VERBATIM-STREAM verbatim-stream)

automatically generated reader method

Source

verbatim-stream.lisp (file)

Method: (setf output-stream) NEW-VALUE (VERBATIM-STREAM verbatim-stream)

automatically generated writer method

Source

verbatim-stream.lisp (file)

Generic Function: verbatim OBJECT
Generic Function: (setf verbatim) NEW-VALUE OBJECT
Package

indentify

Methods
Method: verbatim (VERBATIM-STREAM verbatim-stream)

automatically generated reader method

Source

verbatim-stream.lisp (file)

Method: (setf verbatim) NEW-VALUE (VERBATIM-STREAM verbatim-stream)

automatically generated writer method

Source

verbatim-stream.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.5 Classes

Class: verbatim-stream ()
Package

indentify

Source

verbatim-stream.lisp (file)

Direct superclasses
  • fundamental-character-input-stream (class)
  • fundamental-character-output-stream (class)
Direct methods
  • stream-line-column (method)
  • stream-unread-char (method)
  • stream-peek-char (method)
  • stream-read-char (method)
  • stream-listen (method)
  • stream-finish-output (method)
  • stream-write-char (method)
  • verbatim (method)
  • verbatim (method)
  • output-column (method)
  • output-column (method)
  • input-column (method)
  • input-column (method)
  • output-stream (method)
  • output-stream (method)
  • input-stream (method)
  • input-stream (method)
Direct slots
Slot: input-stream
Initargs

:input-stream

Readers

input-stream (generic function)

Writers

(setf input-stream) (generic function)

Slot: output-stream
Initargs

:output-stream

Readers

output-stream (generic function)

Writers

(setf output-stream) (generic function)

Slot: input-column
Initargs

:input-column

Initform

0

Readers

input-column (generic function)

Writers

(setf input-column) (generic function)

Slot: output-column
Initargs

:output-column

Initform

0

Readers

output-column (generic function)

Writers

(setf output-column) (generic function)

Slot: verbatim
Initargs

:verbatim

Readers

verbatim (generic function)

Writers

(setf verbatim) (generic function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
cl-indentify.asd: The cl-indentify․asd file
cl-indentify/src: The cl-indentify/src module
cl-indentify/src/defaults.lisp: The cl-indentify/src/defaults․lisp file
cl-indentify/src/indenter.lisp: The cl-indentify/src/indenter․lisp file
cl-indentify/src/package.lisp: The cl-indentify/src/package․lisp file
cl-indentify/src/verbatim-stream.lisp: The cl-indentify/src/verbatim-stream․lisp file

F
File, Lisp, cl-indentify.asd: The cl-indentify․asd file
File, Lisp, cl-indentify/src/defaults.lisp: The cl-indentify/src/defaults․lisp file
File, Lisp, cl-indentify/src/indenter.lisp: The cl-indentify/src/indenter․lisp file
File, Lisp, cl-indentify/src/package.lisp: The cl-indentify/src/package․lisp file
File, Lisp, cl-indentify/src/verbatim-stream.lisp: The cl-indentify/src/verbatim-stream․lisp file

L
Lisp File, cl-indentify.asd: The cl-indentify․asd file
Lisp File, cl-indentify/src/defaults.lisp: The cl-indentify/src/defaults․lisp file
Lisp File, cl-indentify/src/indenter.lisp: The cl-indentify/src/indenter․lisp file
Lisp File, cl-indentify/src/package.lisp: The cl-indentify/src/package․lisp file
Lisp File, cl-indentify/src/verbatim-stream.lisp: The cl-indentify/src/verbatim-stream․lisp file

M
Module, cl-indentify/src: The cl-indentify/src module

Jump to:   C   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   F   G   I   L   M   N   O   S   V   W  
Index Entry  Section

(
(setf indent-template): Exported generic functions
(setf indent-template): Exported generic functions
(setf indent-template): Exported generic functions
(setf input-column): Internal generic functions
(setf input-column): Internal generic functions
(setf input-stream): Internal generic functions
(setf input-stream): Internal generic functions
(setf output-column): Internal generic functions
(setf output-column): Internal generic functions
(setf output-stream): Internal generic functions
(setf output-stream): Internal generic functions
(setf verbatim): Internal generic functions
(setf verbatim): Internal generic functions

A
align-with-spaces: Internal functions

F
Function, align-with-spaces: Internal functions
Function, indent-template: Exported functions
Function, indentify: Exported functions
Function, initialize-templates: Exported functions
Function, load-default-templates: Exported functions
Function, load-template-file: Exported functions
Function, load-templates: Internal functions
Function, load-user-templates: Exported functions
Function, normalize-template: Internal functions
Function, number-token-p: Internal functions
Function, scan-chunk: Internal functions
Function, scan-form: Internal functions
Function, scan-forms: Internal functions
Function, scan-indent: Internal functions
Function, scan-line-comment: Internal functions
Function, scan-sharpsign: Internal functions
Function, scan-sharpsign-asterisk: Internal functions
Function, scan-sharpsign-backslash: Internal functions
Function, scan-sharpsign-rational: Internal functions
Function, scan-sharpsign-vertical-bar: Internal functions
Function, scan-string: Internal functions
Function, scan-token: Internal functions
Function, select-subtemplate: Internal functions
Function, select-template: Internal functions
Function, symbol-char-p: Internal functions
Function, symbol-names: Internal functions
Function, write-symbol-to-string: Internal functions

G
Generic Function, (setf indent-template): Exported generic functions
Generic Function, (setf input-column): Internal generic functions
Generic Function, (setf input-stream): Internal generic functions
Generic Function, (setf output-column): Internal generic functions
Generic Function, (setf output-stream): Internal generic functions
Generic Function, (setf verbatim): Internal generic functions
Generic Function, input-column: Internal generic functions
Generic Function, input-stream: Internal generic functions
Generic Function, output-column: Internal generic functions
Generic Function, output-stream: Internal generic functions
Generic Function, verbatim: Internal generic functions

I
increment-column: Internal macros
indent-template: Exported functions
indentify: Exported functions
initialize-templates: Exported functions
input-column: Internal generic functions
input-column: Internal generic functions
input-stream: Internal generic functions
input-stream: Internal generic functions

L
load-default-templates: Exported functions
load-template-file: Exported functions
load-templates: Internal functions
load-user-templates: Exported functions

M
Macro, increment-column: Internal macros
Macro, with-verbatim: Internal macros
Method, (setf indent-template): Exported generic functions
Method, (setf indent-template): Exported generic functions
Method, (setf input-column): Internal generic functions
Method, (setf input-stream): Internal generic functions
Method, (setf output-column): Internal generic functions
Method, (setf output-stream): Internal generic functions
Method, (setf verbatim): Internal generic functions
Method, input-column: Internal generic functions
Method, input-stream: Internal generic functions
Method, output-column: Internal generic functions
Method, output-stream: Internal generic functions
Method, verbatim: Internal generic functions

N
normalize-template: Internal functions
number-token-p: Internal functions

O
output-column: Internal generic functions
output-column: Internal generic functions
output-stream: Internal generic functions
output-stream: Internal generic functions

S
scan-chunk: Internal functions
scan-form: Internal functions
scan-forms: Internal functions
scan-indent: Internal functions
scan-line-comment: Internal functions
scan-sharpsign: Internal functions
scan-sharpsign-asterisk: Internal functions
scan-sharpsign-backslash: Internal functions
scan-sharpsign-rational: Internal functions
scan-sharpsign-vertical-bar: Internal functions
scan-string: Internal functions
scan-token: Internal functions
select-subtemplate: Internal functions
select-template: Internal functions
symbol-char-p: Internal functions
symbol-names: Internal functions

V
verbatim: Internal generic functions
verbatim: Internal generic functions

W
with-verbatim: Internal macros
write-symbol-to-string: Internal functions

Jump to:   (  
A   F   G   I   L   M   N   O   S   V   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *   +  
I   O   S   V  
Index Entry  Section

*
*indent-templates*: Exported special variables

+
+alexandria-templates+: Internal special variables
+asdf-templates+: Internal special variables
+common-lisp-templates+: Internal special variables
+uiop-templates+: Internal special variables

I
input-column: Internal classes
input-stream: Internal classes

O
output-column: Internal classes
output-stream: Internal classes

S
Slot, input-column: Internal classes
Slot, input-stream: Internal classes
Slot, output-column: Internal classes
Slot, output-stream: Internal classes
Slot, verbatim: Internal classes
Special Variable, *indent-templates*: Exported special variables
Special Variable, +alexandria-templates+: Internal special variables
Special Variable, +asdf-templates+: Internal special variables
Special Variable, +common-lisp-templates+: Internal special variables
Special Variable, +uiop-templates+: Internal special variables

V
verbatim: Internal classes

Jump to:   *   +  
I   O   S   V  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   I   P   S   V  
Index Entry  Section

C
cl-indentify: The cl-indentify system
Class, verbatim-stream: Internal classes

I
indentify: The indentify package

P
Package, indentify: The indentify package

S
System, cl-indentify: The cl-indentify system

V
verbatim-stream: Internal classes

Jump to:   C   I   P   S   V