Common Lisp apropos and documentation

Question

I am aware of the powerful features offered by the Common Lisp REPL. I am specifically using the SBCL implementation. However, I am not sure my REPL is setup properly and would like to know how to get more power out of the REPL.

For example, I wanted to find the power function to computer 2^3 = 8. This is called pow or power in many other languages. So I did:

CL-USER> (apropos 'pow)
    POW                                                                                                                                                                          
    POWER                                                                                                                                                                        
    :OP-POWER-EXT (bound)                                                                                                                                                        
    :POWERPC (bound)                                                                                                                                                             
    SB-IMPL::*INTEGER-READER-BASE-POWER* (bound)                                                                                                                                 
    SB-IMPL::*POWER-CACHE* (bound)                                                                                                                                               
    SB-IMPL::+POWER-CACHE-INTEGER-LENGTH-LIMIT+ (bound)                                                                                                                          
    SB-IMPL::COMPUTE-POWERS                                                                                                                                                      
    SB-IMPL::POWER                                                                                                                                                               
    SB-IMPL::POWERS-FOR-BASE (fbound)                                                                                                                                            
    SB-INT:POWER-OF-TWO-CEILING (fbound)                                                                                                                                         
    SB-KERNEL:%POW (fbound)                                                                                                                                                      
    SB-KERNEL::POWER                                                                                                                                                             
    SB-KERNEL:SCRUB-POWER-CACHE (fbound)                                                                                                                                         
    ; No value

How would I view the documentation of any of these functions? Would I have to "import" any of these "libraries" before I view the documentation? Often I find that the documentation is missing, as the REPL will return nil. Where is the documentation? For example I did:

CL-USER> (documentation 'power 'function)

and it just returned NIL but as you can see from the list above given by apropos, power exists!

Summarizing:

1. How do I find the documentation of functions, data-types, variables etc... (what else is there to look-up documentation for?)?
2. Are SB-IMPL and SB-KERNEL libraries that are already imported?

Thanks for all the help!

Answer 1

CL-USER> (documentation 'power 'function)

and it just returned NIL but as you can see from the list above given by apropos, power exists!

The symbol power exists, but note that it's not bound or fbound like some of the other symbols are. Thus is doesn't have a function or value binding. Lots of symbols exist, even if they don't have a function or value binding. This can be particularly frustrating in apropos, because if you do (apropos 'name), then in reading the form, you've already ensured that there's a symbol name. Sometimes you'll see people use the uninterned symbol notation to avoid this problem. E.g.:

CL-USER> (apropos 'this-already-got-interned)
THIS-ALREADY-GOT-INTERNED
; No value
CL-USER> (apropos '#:but-this-didnt\!)
; No value

However, even if power did have a function or value binding, there's no guarantee that there'd be documentation available for it. Note that the documentation for documentation says:

Documentation strings are made available for debugging purposes. Conforming programs are permitted to use documentation strings when they are present, but should not depend for their correct behavior on the presence of those documentation strings. An implementation is permitted to discard documentation strings at any time for implementation-defined reasons.

That said, you can still try, and sometimes you'll get useful results:

CL-USER> (apropos '#:expt)
EXPT (fbound)
SB-C::EXPT-DERIVE-TYPE-AUX (fbound)
SB-C::EXPT-DERIVE-TYPE-OPTIMIZER (fbound)
...
; No value
CL-USER> (documentation 'expt 'function)
"Return BASE raised to the POWER."

In general, if you want to know more about an object, you can use describe (sds pointed this out before I did). The output isn't specifically defined, but it may well include the documentation:

CL-USER> (describe 'expt)
COMMON-LISP:EXPT
  [symbol]

EXPT names a compiled function:
  Lambda-list: (BASE POWER)
  Declared type: (FUNCTION (NUMBER NUMBER) (VALUES NUMBER &OPTIONAL))
  Documentation:
    Return BASE raised to the POWER.
  Source file: SYS:SRC;CODE;IRRAT.LISP
; No value

In general, these tools can be useful, but if you're looking for a particular function to achieve some task, Google is probably going to be more helpful unless you've already got a good idea of what you're looking for. After all, the first result in a Google search for “common lisp hyperspec exponent power” is a link to the page for expt.

Answer 2

The standard way to find out more about a lisp object is describe.

E.g.,

* (describe 'expt)

COMMON-LISP:EXPT
  [symbol]

EXPT names a compiled function:
  Lambda-list: (BASE POWER)
  Declared type: (FUNCTION (NUMBER NUMBER) (VALUES NUMBER &OPTIONAL))
  Derived type: (FUNCTION (T T) (VALUES T &OPTIONAL))
  Documentation:
    Return BASE raised to the POWER.
  Known attributes: foldable, flushable, unsafely-flushable, movable, recursive, explicit-check
  Source file: SYS:SRC;CODE;IRRAT.LISP

To answer your second question: import manipulates packages (namespaces), while load and require load libraries from disk. I suggest that you read up the manual and ask a more specific question.

Answer 3

APROPOS just looks for symbols which contain a string in the current running image. It will also indicate if the symbol has a function, macro and/or value.

If you search for POWER amongst the symbols and there is such a symbol, then it does not mean there is such a function.

CL-USER 1 > (defun foobar (a) a)
FOOBAR

CL-USER 2 > 'foosym
FOOSYM

CL-USER 3 > (apropos "foo")
FOOBAR (defined)
FOOSYM

Thus it makes sense to check out the function FOOBAR. There is also a symbol FOOSYM, but it has no function definition.

Some Lisp Implementations have enhanced versions or variants of APROPOS. LispWorks for example has a GUI-based symbol browser with many search options.

For SBCL your best option is to use it together with GNU Emacs + SLIME.

To lookup the documentation for a function you have basically two direct options:

1: call DOCUMENTATION:

CL-USER 4 > (defun foobar (a) "my foobar is silly" a)
FOOBAR

CL-USER 5 > (documentation 'foobar 'function)
"my foobar is silly"

2: use the IDE command to find documentation. Task: read the SLIME manual.

For example in LispWorks I would use the keyboard commands:

• documentation string: Meta-Control-Shift-a on the symbol
• LispWorks documentation: Control-Shift-d on the symbol

Alternative, I could also use the menu or the context-menu to find the documentation.

To get an overview about built-in math functionality

Look at the Common Lisp HyperSpec Numbers Dictionary.