Lisp mode doc, and Lisp indentation props

Lisp mode doc, and Lisp indentation props

[Ian Zimmerman]

Is there a document (Info format preferred, but another format would be
ok of course) describing the Emacs Lisp mode, from a _user_ POV,
similarly to how CC mode is documented, for example?  Strangely, I
cannot find one.

The specific information I'm after is about those little properties on
symbols that make some forms indent specially.  For example, what is
responsible for this difference:

(call-foo-with-args (nested-call arg1)
                    arg2)

vers.

(when (nested-call arg1)
  arg2)

?

-- 
Please *no* private copies of mailing list or newsgroup messages.
Rule 420: All persons more than eight miles high to leave the court.

Re: Lisp mode doc, and Lisp indentation props

[Andy Moreton]

On Sun 09 Aug 2015, Ian Zimmerman wrote:

> Is there a document (Info format preferred, but another format would be
> ok of course) describing the Emacs Lisp mode, from a _user_ POV,
> similarly to how CC mode is documented, for example?  Strangely, I
> cannot find one.
>
> The specific information I'm after is about those little properties on
> symbols that make some forms indent specially.  For example, what is
> responsible for this difference:
>
> (call-foo-with-args (nested-call arg1)
>                     arg2)
>
> vers.
>
> (when (nested-call arg1)
>   arg2)

The declare macro can be used to add an indent property to a function or
macro, which tells the mode how to compute required indentation. This is
described in the Emacs Lisp manual at (info "(elisp) Declare Form").

    AndyM

Re: Lisp mode doc, and Lisp indentation props

[Ian Zimmerman]

On 2015-08-09 18:56 +0100, Andy Moreton wrote:

> The declare macro can be used to add an indent property to a function
> or macro, which tells the mode how to compute required
> indentation. This is described in the Emacs Lisp manual at (info
> "(elisp) Declare Form").

Ok, thanks for your answer.  But is there a way to _change_ this for an
already existing function or macro?  That's why I asked in terms of
properties, because I'm pretty sure the declaration just results into
some proerties set on the symbol.  If so, I thought I could control the
indentation by modifying those properties.

-- 
Please *no* private copies of mailing list or newsgroup messages.
Rule 420: All persons more than eight miles high to leave the court.

Re: Lisp mode doc, and Lisp indentation props

[John Mastro]

> Ok, thanks for your answer.  But is there a way to _change_ this for an
> already existing function or macro?  That's why I asked in terms of
> properties, because I'm pretty sure the declaration just results into
> some proerties set on the symbol.  If so, I thought I could control the
> indentation by modifying those properties.

The property is `lisp-indent-function'.

-- 
john

Re: Lisp mode doc, and Lisp indentation props

[Andy Moreton]

On Sun 09 Aug 2015, Ian Zimmerman wrote:

> On 2015-08-09 18:56 +0100, Andy Moreton wrote:
>
>> The declare macro can be used to add an indent property to a function
>> or macro, which tells the mode how to compute required
>> indentation. This is described in the Emacs Lisp manual at (info
>> "(elisp) Declare Form").
>
> Ok, thanks for your answer.  But is there a way to _change_ this for an
> already existing function or macro?  That's why I asked in terms of
> properties, because I'm pretty sure the declaration just results into
> some proerties set on the symbol.  If so, I thought I could control the
> indentation by modifying those properties.

I don't know the proper way to achieve this. From reading the code, it
appears that this is handled by the indent property from the declare
form, the value of lisp-body-indent, and the value of the
lisp-indent-function property of the forms within the defun/macro being
indented.

See (info "(elisp) Indenting Macros") and lisp-indent-function in
lisp-mode.el for the details.

    AndyM

Re: Lisp mode doc, and Lisp indentation props

[Michael Heerdegen]

Andy Moreton <andrewjmoreton@gmail.com> writes:

> I don't know the proper way to achieve this.

There is absolutely no magic behind this; just call `put' (and `get') on
the symbol.  The `declare' specification is just a convenient way to set
the property in the function definition.


Michael.

RE: Lisp mode doc, and Lisp indentation props

[Drew Adams]

> > I don't know the proper way to achieve this.
> 
> There is absolutely no magic behind this; just call `put' (and
> `get') on the symbol.  The `declare' specification is just a
> convenient way to set the property in the function definition.

I think that there _is_ something missing from the doc, which might
help a bit in this case.  I agree that this kind of thing is not so
easy to discover.  You really have to find it in the code and see
how it is used.

This is the original request/question:

> The specific information I'm after is about those little properties
> on symbols that make some forms indent specially.

There are a few places in Emacs Lisp where some programming takes place
by setting and getting properties on symbols.  This just involves a
function of two symbols, one of which is used as a property of the other.
The function is `get'.  Since other code can change the property value
dynamically, this, like dynamically scoped variables, is one way for some
code to manipulate or otherwise affect other code.  It is an old technique.

Some places where this technique is used include the following:

* Customize - Things like the standard, customized, and set-but-not-saved
  value of a user option are stored on the option symbol (see properties
  `standard-value', `customized-value', and `custom-set').

* Lisp indentation - The case that was asked about.  Properties like
  `common-lisp-indent-function' with values like `(4 4 4 2 &body)'.
  The values are documented in (elisp) `Indenting Macros', but
  nothing there tells you that these are the same values that are
  used by `(declare (indent...))'.

* Byte-compiler - This used to be hinted at, if only indirectly, in
  the Elisp manual, node `Property Lists'.  Before Emacs 24.3 it said:

   Here is an example of a property list, found on the symbol `progn'
   when the compiler is loaded:

     (lisp-indent-function 0 byte-compile byte-compile-progn)

   Here `lisp-indent-function' and `byte-compile' are property names,
   and the other two elements are the corresponding values.

  In the byte-compiler code you will see code like this: 

  (put 'defvar 'byte-hunk-handler 'byte-compile-file-form-defvar)

* Delete-Selection Mode - Property `delete-selection' on a command
  symbol tells `delete-selection-mode' how to treat it, depending on
  its value: `yank' (a yank command - make sure the region to be
  deleted is not yanked), `supersede' (just delete the region),
  `kill' (kill the region), and `t' (delete the region and let
  the command insert a replacement).

Stefan will no doubt chime in to say that this is not a great way
to control or organize code.  For one thing, it cannot be used
for anonymous functions (Emacs Lisp does not allow property lists
for such things).  More importantly, a Lisp symbol is not a Lisp
function; it is just a name (one name) for a function.

This technique is what it is.  IMO, it can be handy, including for
users (for `delete-selection-mode', for instance, though Stefan
will disagree). But it is somewhat primitive and fragile, and not
always easy to discover/notice/analyze/manage.

Re: Lisp mode doc, and Lisp indentation props

[Marcin Borkowski]

On 2015-08-09, at 18:36, Ian Zimmerman <itz@buug.org> wrote:

> Is there a document (Info format preferred, but another format would be
> ok of course) describing the Emacs Lisp mode, from a _user_ POV,
> similarly to how CC mode is documented, for example?  Strangely, I
> cannot find one.
>
> The specific information I'm after is about those little properties on
> symbols that make some forms indent specially.  For example, what is
> responsible for this difference:
>
> (call-foo-with-args (nested-call arg1)
>                     arg2)
>
> vers.
>
> (when (nested-call arg1)
>   arg2)
>
> ?

Not exactly what you are asking for, but wrt macros:

http://www.gnu.org/software/emacs/manual/html_node/elisp/Indenting-Macros.html

Hth,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: Lisp mode doc, and Lisp indentation props

[Emanuel Berg]

Ian Zimmerman <itz@buug.org> writes:

> Is there a document (Info format preferred, but
> another format would be ok of course) describing the
> Emacs Lisp mode, from a _user_ POV, similarly to how
> CC mode is documented, for example? Strangely,
> I cannot find one.

I know of the following places to look:

    1. The Emacs manual.

    2. The Elisp manual.

    3. The on-line help (`describe-mode', but also
       individual functions etc.)

    4. The comments in the source. In this case, in
       lisp-mode.el - do `C-h m' and hit the first
       button after the "Enabled minor modes"
       harangue. You need the source for this
       (the pack emacs24-el in the Debian repos) -
       I know you know this (or the equivalence for
       your distro/system), but perhaps you are not
       the only one reading.

    5. Use the source, Luke.

-- 
underground experts united
http://user.it.uu.se/~embe8573