The datum-comments Reference Manual

Table of Contents

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

The datum-comments Reference Manual

This is the datum-comments Reference Manual, version 0.0.2, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 15:51:44 2021 GMT+0.


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

1 Introduction

#+title: datum comments for common lisp

[[img:https://travis-ci.org/tgbugs/datum-comments.svg?branch=master][https://travis-ci.org/tgbugs/datum-comments]]

Racket style =#;= comments implemented as a dispatch macro.

#+begin_src lisp
#; ; regular comments are treated as whitespace
(and the next datum is skipped by the reader)
#; (so you can skip a datum inline) (print "and not just a line or block")
#+end_src

* Installation
** [[https://www.quicklisp.org/][Quicklisp]]
#+begin_src lisp
(ql:quickload :datum-comments)
#;(skip) '(show)  ; datum comments work immediately after quickload
#+end_src

** Manual install
Using =sbcl= as an example.
#+begin_src bash
git clone https://github.com/tgbugs/datum-comments.git
cat "(push (truename #p\"datum-comments\") asdf:*central-registry*)" >> ~/.sbclrc
sbcl --eval "(asdf:load-system :datum-comments) #;(i im a comment) (print 'hello)"
#+end_src

* Usage
Since comments are a fundamental part of a language datum-comments automatically
registers itself as a dispatch macro for the =#;= symbol. Install via one of the
methods above and then include =:datum-comments= in the =:use= section of
=defpackage= where you want to be able to use datum comments, e.g. as

#+begin_src lisp
(defpackage :my-package
  (:use :cl :datum-comments))
#+end_src

at which point you can =#;(use datum comments to your heart's content)=

* Implementation support
This should work on any cl that has =asdf=, and the copy/paste version
below should work on pretty much anything.
See [[https://travis-ci.org/tgbugs/datum-comments][travis]] for the list
of tested working implementations.

* Standalone
#+begin_src lisp
(defpackage :datum-comments
  (:use :cl))
(in-package :datum-comments)
(defun datum-comment (stream char arg)
  (declare (ignore char arg))
  (read-preserving-whitespace stream t nil t)
  (values))
(set-dispatch-macro-character #\# #\; #'datum-comment)
#+end_src

* Syntax highlighting and editing
An experimental [[./datum-comments.el][datum-comments-mode]] is available for emacs. A minimal
entry for [[${HOME}/.emacs][~/.emacs]]/[[${HOME}/.emacs.d/init.el][init.el]]
is below.
#+begin_src emacs-lisp :eval never
(use-package lisp-mode
  :init
  (use-package datum-comments
    :load-path "~/git/datum-comments" ;; adjust accordingly
    :hook (lisp-mode . datum-comments-mode)))
#+end_src

This will probably fail right now unless you also have slime enabled,
and has not been sufficiently tested.

Support for named readtables or detection by slime of a datum-comments
feature has not been implemented but is planned.

There are also known bugs with the interaction between regular comments
and datum comments causing datum comments to be highlighted incorrectly.
* Racket behavior for comparison
#+begin_src racket :results none
#lang racket/base
#;(this is commented out) '(this is not) ; this is
#;(this should break how does greg avoid the issue? ; this is a comment)
        and this is open ended)

#;
(test this should ;be ok right?)
      #; nothing)

;; double, the racket behavior is as expected, comments are comments
#; ; help I'm
#; ; trapped in
(one fish) ; yay!
(two fish) ; woo!

#; #; 'one 'two 'three
#+end_src


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 datum-comments

Author

Tom Gillespie <tgbugs@gmail.com>

License

Public Domain (Unlicense)

Description

datum #;(comments) for common lisp

Version

0.0.2

Source

datum-comments.asd (file)

Components

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

3 Files

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


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

3.1 Lisp


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

3.1.1 datum-comments.asd

Location

datum-comments.asd

Systems

datum-comments (system)

Packages

datum-comments-asd


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

3.1.2 datum-comments/packages.lisp

Parent

datum-comments (system)

Location

packages.lisp

Packages

datum-comments


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

3.1.3 datum-comments/read.lisp

Dependency

packages.lisp (file)

Parent

datum-comments (system)

Location

read.lisp

Internal Definitions

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

3.1.4 datum-comments/enable.lisp

Dependency

read.lisp (file)

Parent

datum-comments (system)

Location

enable.lisp


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

4 Packages

Packages are listed by definition order.


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

4.1 datum-comments-asd

Source

datum-comments.asd

Use List

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

4.2 datum-comments

Source

packages.lisp (file)

Use List

common-lisp

Internal Definitions

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

5 Definitions

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


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

5.1 Internal definitions


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

5.1.1 Functions

Function: datum-comment STREAM CHAR ARG
Package

datum-comments

Source

read.lisp (file)

Function: enable-datum-comments ()
Package

datum-comments

Source

read.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   D   F   L  
Index Entry  Section

D
datum-comments.asd: The datum-comments․asd file
datum-comments/enable.lisp: The datum-comments/enable․lisp file
datum-comments/packages.lisp: The datum-comments/packages․lisp file
datum-comments/read.lisp: The datum-comments/read․lisp file

F
File, Lisp, datum-comments.asd: The datum-comments․asd file
File, Lisp, datum-comments/enable.lisp: The datum-comments/enable․lisp file
File, Lisp, datum-comments/packages.lisp: The datum-comments/packages․lisp file
File, Lisp, datum-comments/read.lisp: The datum-comments/read․lisp file

L
Lisp File, datum-comments.asd: The datum-comments․asd file
Lisp File, datum-comments/enable.lisp: The datum-comments/enable․lisp file
Lisp File, datum-comments/packages.lisp: The datum-comments/packages․lisp file
Lisp File, datum-comments/read.lisp: The datum-comments/read․lisp file

Jump to:   D   F   L  

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

A.2 Functions

Jump to:   D   E   F  
Index Entry  Section

D
datum-comment: Internal functions

E
enable-datum-comments: Internal functions

F
Function, datum-comment: Internal functions
Function, enable-datum-comments: Internal functions

Jump to:   D   E   F  

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

A.3 Variables


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

A.4 Data types

Jump to:   D   P   S  
Index Entry  Section

D
datum-comments: The datum-comments system
datum-comments: The datum-comments package
datum-comments-asd: The datum-comments-asd package

P
Package, datum-comments: The datum-comments package
Package, datum-comments-asd: The datum-comments-asd package

S
System, datum-comments: The datum-comments system

Jump to:   D   P   S