How to see docstrings and other symbol information in Common Lisp REPL?

Question

I'm completely new to CL, and I'd like to learn how to read documentation strings and get other help information from the REPL. Something like help(symbol) in Python, or symbol? in iPython, or :t and :i in Haskell's GHCi.

So, given a symbol name, I'd like to be able to know:

what kind of value it is bound to, if any (a function, a variable, none at all)
if it is a function or a macro, then what are its positional arguments
if it has a docstring, show it
what package or file it is coming from or when it was defined

I found there is (documentation '_symbol_ '_type_), but it is not exactly what I need. I need to know the type of value the symbol is bound to ('function, 'variable, 'compiler-macro, etc.) before I can use documentation. Then it returns only the docstring, it may be missing or not sufficient to use the symbol.

For example, in Lisp, the help for mapcar is not very useful (CLisp's REPL):

> (documentation 'mapcar 'function)
NIL

I'd like to be able to see something like this instead:

>>> map?
Type:       builtin_function_or_method
Base Class: <type 'builtin_function_or_method'>
String Form:    <built-in function map>
Namespace:  Python builtin
Docstring:
    map(function, sequence[, sequence, ...]) -> list

    Return a list of the results of applying the function to the items of
    the argument sequence(s).  If more than one sequence is given, the
    function is called with an argument list consisting of the corresponding
    item of each sequence, substituting None for missing values when not all
    sequences have the same length.  If the function is None, return a list of
    the items of the sequence (or a list of tuples if more than one sequence).

What compiler are you using? In my CL, `(documentation 'mapcar 'function)` gives: "Apply FUNCTION to successive elements of LIST. Return list of FUNCTION return values." — Ken, Feb 23 '11 at 16:23
`(inspect 'mapcar)` and `(describe 'mapcar)` may be what you're looking for, though the actual utility of those functions depends greatly on the particular implementation. — Daniel Dickison, Feb 23 '11 at 16:27
To be fair, the utility of *all* functions depends greatly on the implementation. :-) — Ken, Feb 23 '11 at 16:29
Thank you, @Daniel. Indeed, `inspect` and `describe` are just what I am looking for. Thank you. If you write it as an answer, I can accept it. @Ken: I have both CLisp an SBCL installed, but I used mostly CLisp until now (its readline-enabled REPL seems much nicer to me). SBCL's docstring is indeed much more useful, but it is still only a docstring (still need to find symbol type and arguments' list somehow). — sastanin, Feb 23 '11 at 16:39
@jetxee you seem to be misunderstanding the nature of symbols in CL. The "symbol type" is [SYMBOL](http://www.lispworks.com/documentation/HyperSpec/Body/t_symbol.htm), which is a first class entity with multiple attributes. — Ramarren, Feb 23 '11 at 18:13
@Ramarren, I edited the question. I suppose that it is more correct to tell "the type of the value which the symbol is bound to", right? Thank you. — sastanin, Feb 24 '11 at 09:15
@jetxee In global context symbols are not so much "bound to" values as they contain reference to values, possibly of many types at the same time. Note that docstrings are properties of objects, not symbols. Symbols can also name bindings in lexical context, but that is a property of lexical environments rather than symbols. Unfortunately the standardization committee ran out of time and money before introspection into those could be standardized, so it is implementation dependent. — Ramarren, Feb 24 '11 at 11:39
Use rlwrap sbcl if you want to have a more user friendly REPL, or Slime — coredump, Sep 14 '17 at 18:36

Rainer Joswig · Accepted Answer · 2017-09-13T16:25:21.083

31

As mentioned Common Lisp has standard functions: DESCRIBE, INSPECT and DOCUMENTATION. Typical Lisp IDEs also have these bound to keys and menus.

For standard Common Lisp functionality most IDEs directly link to the Common Lisp HyperSpec documentation with a keystroke.

Most IDEs also have keystrokes to show the arglist and the documentation. There is also the 'arglist on space' functionality.

LispWorks specific examples: LispWorks Argument list information and LispWorks Expressions menu

I can recommend to read the IDE manual for Slime, LispWorks Editor, Allegro CL's ELI, or whatever IDE you are using.

edited Sep 13 '17 at 16:25

answered Feb 23 '11 at 16:32

Rainer Joswig

136,269
10
221
346

in CLISP, directly from terminal, all DESCRIBE, INSPECT and DOCUMENTATION don't explain anything... – DPColombotto Jul 07 '21 at 08:20
@dpcolombotto: I have CLISP running here and these function explain quite a bit. – Rainer Joswig Jul 07 '21 at 08:45

score 9 · Answer 2 · edited Jan 04 '14 at 18:13

9

Regarding your question about getting the type of symbol: there is no such thing. Or, more precisely, symbols are not just names of other objects, but themselves objects of the type SYMBOL. Each symbol can have both a variable value and a function value. To check if it has a variable value, use BOUNDP, and to check for a function value FBOUNDP.

edited Jan 04 '14 at 18:13

BenMorel

34,448
50
182
322

answered Feb 23 '11 at 20:16

Rörd

6,556
21
27

1

Thank you. I understand that the symbol can be unbound. It is useful to know about `boundp` and `fboundp`. `describe` seems to be enough for interactive use. – sastanin Feb 24 '11 at 09:26

How to see docstrings and other symbol information in Common Lisp REPL?

2 Answers2

Linked