For various reasons I've been forced to use Emacs git master for development. In this version I'm regularly getting lots of warnings in the form
No docstring slot for tags-lazy-completion-table
No docstring slot for etags--xref-backend
No docstring slot for gnus-intersection
No docstring slot for grep-compute-defaults
...
which often are so many that it slows down my interaction. Is it possible to set the docstring of a an already defined Emacs Lisp function without modifying its existing body definition?
Stefan has addressed your actual problem, but to answer the stated question:
Is it possible to set the docstring of a an already defined Emacs
Lisp function without modifying its existing body definition?
Yes, you can, via the function-documentation symbol property.
(put FUNCTIONSYMBOL 'function-documentation VALUE)
In most cases VALUE would be a string.
See:
C-hig (elisp)Documentation Basics
C-hig (elisp)Accessing Documentation
The No docstring slot for ... warnings are your problem, not the absence of docstrings (which is copmpletely normal). I suggest you try
(setq debug-on-message "\\`No docstring slot for")
and then look at the backtrace you'll (hopefully) get to try and figure out which packages emits this warning and why (and especially why it only does so in Emacs-master: might be a bug in Emacs-master, or an incompatibility ... in either case Emacs maintainers may want to hear about it).
Related
The geiser documentation suggests that setting geiser-default-implementation is one way to prevent run-geiser from prompting for a scheme implementation. Another approach suggested by the geiser docs is to set the geiser-implementations-alist to the following value:
(((regexp "\\.scm$") guile)
((regexp "\\.ss$") racket)
((regexp "\\.rkt$") racket))
In neither case do the docs give examples of how to set. I've tried various incantations involving setq, defcustom, etc., but I continue to be prompted for the desired scheme implementation whenever I run run-geiser. The alist doesn't even evaluate properly: for one thing, the regexp function seems not to exist; for another, I'm thinking some sort of quoting is needed to prevent errors on the undefined guile/racket symbols. Would be grateful if someone could give an example of exactly what would need to be added (e.g.) to .emacs in both cases.
Would also like to understand why something like...
(setq geiser-default-implementation 'racket)
...doesn't seem to work.
You could remove the other implementations from the list of active implementations:
(setq geiser-active-implementations '(racket))
No matter how many times I reload my .emacs file,
M-x load-file RET ~/.emacs RET
I want the results to be the same as the first time. I want to make my .emacs file be idempotent.
Motivation
I know I can surgically evaluate a region (C-c C-r), a defun (C-M-x), or the last sexp (C-x C-e). I often take such a more refined approach when making small changes. However, when re-working a .emacs file, I sometimes want to check results of the change conclusively by reloading the entire .emacs file. Restarting emacs each time gets old quick, especially when doing major .emacs housekeeping.
Specific Steps
What specific steps must I take to update my .emacs file to replace non-idempotent operations with idempotent ones?
For example,
Search for "-hook" and replace direct additions to hooks with calls to add-hook, which
will not re-add a function to the hook if already there.
Replace toggling of any flags with direct setting or clearing. Beware of ?? in particular.
...
A comprehensive check-and-correct list would be ideal, but any key individual checks that occur to you would be helpful as well.
I don't know as it's possible to ensure this completely, as most .emacs files depend on libraries which may not have idempotent initialization routines. However, there are a few useful tricks to reduce problems:
Use named functions for add-hook, and keybindings instead of anonymous functions. For add-hook in particular, this allows it to swap out the existing reference.
Careful use of defvar, by default the body is only evaluated if the variable is undefined. C-M-x on a defvar will re-eval the body, but eval-buffer will not if the variable is already initialized.
Careful use of (quote function) instead of function to reference a named function instead of the value of the function. See Anonymous Functions for more advanced discussion about this.
Remember that require will only load the corresponding library the first time it is executed, it will not re-eval on repeated calls as load does. Autoload also uses require to load the corresponding library.
Prefer add-to-list instead of cons to only add an element if it doesn't exist.
For older mode activation, make sure to use (mode-name-mode t) to activate instead of the toggle function. Likewise for turn-on- minor mode functions instead of the mode toggle.
Guard blocks that do have side effects if executed repeatedly. In particular for server mode, (unless (server-running-p) (server-start)), and similar guards for installing packages.
Being careful about side effects in eval-after-load or custom mode hooks. Remember the default mode hooks run when a mode is first enabled, and on each subsequent buffer, but will not rerun in existing buffers when the hook function is modified. eval-after-load is less likely to trip things up, it's still important to remember when it's evaluated.
Related to #2, makunbound may be useful if a chain of vars that depend on each other need to be re-evaluated, as it will force the defvar to always execute on evaluation of the file.
Running eval-buffer on an init file should be as idempotent as possible, but it's important to remember that emacs lisp is fond of side effects and state. While it's possible to ameliorate this to some extent, re-evaling init will never return emacs to the state it was when it first started.
Limit yourself to things you know are idempotent:
defun.
setq to a constant.
add-to-list with a constant.
add-hook, but preferably adding a symbol rather than a lambda expression.
enabling/disabling a minor mode.
wrapping some of the above in conditions.
Of course idempotent doesn't actually mean that the result is the same as re-starting (e.g. removing a setq and then re-evaluating your .emacs won't remove the effect of the previous setq), but the above is pretty much the principles I try to follow in my own ~/.emacs.
In addition to what others have said, load (e.g. require) libraries, including 3rd-party libraries, whose loading is idempotent.
Yes, to find that out for a given library you might need to either read the code or experiment. But nowadays libraries are supposed to be idempotent (or close to it), and many are.
Tried to use the persp-mode https://github.com/Bad-ptr/persp-mode.el/blob/master/persp-mode.el to retrieve the emacs windows session after restart. Unable to get it working.
So trying to understand the datastructure used to store the state of the emacs by reading the source code.
The following is the function which is used to store the session state.
(defun* persp-save-state-to-file (&optional (fname persp-auto-save-fname)
(phash *persp-hash*)
respect-persp-file-parameter)
(interactive (list (read-file-name "Save perspectives to file: "
persp-save-dir)))
In the above function two unusual things are observed using edebug (unusual according to my current understanding of elisp).
The optional argument expressions are evaluated.
The expression "(interactive..." is evaluated first and then the optional argument expressions are evaluated.
Any ideas how to debug the code. Also the emacs documentation says "defun*" is related to common-lisp, but no further information is available in emacs docs on how defun* is different from defun. Is there a quick tutorial oh what defun* does without having to learn common-lisp.
Emacs says:
Define NAME as a function. Like normal `defun', except ARGLIST allows
full Common Lisp conventions, and BODY is implicitly surrounded by
(cl-block NAME ...).
Common Lisp arglists provide optional, rest, keyword and aux arguments. Historically this comes from Lisp Machine Lisp and Mumble - two earlier Lisp dialects.
For details see: http://www.gnu.org/software/emacs/manual/html_node/cl/Argument-Lists.html
Have a look at this post for a simplistic snippet explaining
how optional works. The gist is that e.g. persp-auto-save-fname will be the value of fname
if none is given.
And obviously interactive has to be run first, because it provides the arguments.
So if interactive doesn't provide a value for fname it will be persp-auto-save-fname.
I am byte-compiling a module. It gives me this warning:
Warning: cl package required at runtime
Why is this a warning? I am well aware that I am using the cl package. In fact there is a (require 'cl) statement in the module.
Is there something wrong with using the cl stuff?
If so, is there a list of published workarounds? The main things I use are mapcan and delete-duplicates.
The reason of this warning is a GNU policy which does not want a package cl to be used in Elisp. But it would be foolish as well to prohibit it completely. So they decided to show a warning.
You can find more information here
Just in case someone reads this on his quest for proper use of cl: The methods described here are now deprecated.
As least as of emacs 24, instead of cl you should use cl-lib or, if the macros suffice, cl-macs. These are new versions of cl that work with a clean namespace. E.g. instead of defun* you have cl-defun.
The old cl-package now is only for backward-compatibility and shouldn't be used in new code.
There are namespace clashes between Elisp and Common Lisp but the cl package gets round them by appending an asterisk to the repeated names. For instance it implements the Common Lisp version of defun but calls it defun*. The upshot is that there are no namespaces clashes between cl and Elisp and it is quite safe to (require 'cl).
If you want to get rid of the silly warning, customize the variable byte-compiler-warnings.[1] This will turn off the warning when you compile the code. If you distribute the code the warning will probably came back when someone else compiles it. If you don't want this to happen use the code:
(with-no-warnings
(require 'cl))
You can stop the byte compiler warning about any Lisp form in a similar way.[2] It's probably a not good idea in general, but you may be able to justify it in this case.
The code:
(eval-when-compile
(require 'cl))
will get rid of the warning, but you will only be able to use the macros from the package if you do this. Macros are evaluated at compile time and Elisp does not need to know about them at run time. If you only use the macros from any package, not just cl, then it is a good idea to use eval-when-compile as it will stop unnecessary packages loading at run time, both saving memory and making the code faster. But it seems to me that it's a misuse of the function to use it just to avoid a warning. And, of course, if you do want to use any of the functions from cl, you can't use eval-when-compile anyway.
[1] You may need to add (require 'bytecomp) to your .emacs file to get access to this variable.
[2] In theory, anyway, but there's a bug in with-no-warnings that means it doesn't supress some warnings about lexical variables.
Common Lisp has lots of namespace clashes with elisp, often the functions seem to do the same thing, but differ in some subtle detail. Mixing the two is a risk that is best not done behind the user's back. For this reason, most of the more useful functions in cl.el are defined as macros, so that cl.el can be required at compile time only, and the macros will then only affect the code that uses them in future sessions of Emacs.
I wasn't able to suppress this message after reading the comments before mine.
However, I received the following instruction from a kind person on the GNU emacs mailing list:
Require cl-lib, and then change the call to use cl-remove-if-not,
instead of remove-if-not.
Which proved to be the remedy.
In sum: by 'requiring cl-lib, one must also change the name of the function/macro call.
HTH....
I have been using Emacs for more than three years now but it still takes me days to write even small functions in Lisp. I've looked through GNU Emacs Lisp Reference Manual but it's huge and structured completely opposite from JavaDoc, not from functions to descriptions but the other way around.
What will make my life much easier is some sort of small JavaDoc like document with most commonly used Emacs internal functions and they quick description.
(point) - returns current position in buffer
(save-excursion (p)) - saves current position in buffer before
executing (p) and restores it afterward.
Does anyone know where I can find something like that?
Have you tried the build-in manual in emacs? Open any lisp buffer (or any buffer in lisp mode), move your point to any function or variable, and hit C-h f (for function) or C-h v (for variable). Emacs will give you a fairly concise description of the function/variable.
For example, the manual content for (save-excursion) is
save-excursion is a special form in `C source code'.
(save-excursion &rest BODY)
Save point, mark, and current buffer; execute BODY; restore those things.
Executes BODY just like `progn'.
The values of point, mark and the current buffer are restored
even in case of abnormal exit (throw or error).
The state of activation of the mark is also restored.
This construct does not save `deactivate-mark', and therefore
functions that change the buffer will still cause deactivation
of the mark at the end of the command. To prevent that, bind
`deactivate-mark' with `let'.
The good thing also is the build-in manual give you "link" to to the source code of the function and to other functions that might be related, which make it nice to browse around.
Of course you can't learn lisp this way, but for looking up documentation of function this is a nice starter. When you find the build-in manual not understandable (which sometimes does happen), then it's time for you to google the function ;)
This site has some emacs lisp summary information that may be useful: http://xahlee.org/emacs/elisp.html.
In particularly, check out these links on that page: Basic Text-editing Functions, Emacs Lisp Idioms and Batch Text Processing
The GNU Introduction to emacs lisp is certainly more approachable than the reference manual.
I would add a couple of things:
M-x apropos - searches functions and variables for whatever string you specify (e.g. directory). Note that this is slightly different than C-h a, which only finds interactive functions
find a similar piece of code and copy it - you can learn an awful lot about how to do things by looking at what's already done. If you have a particular function you want to see examples of, one good way is to visit the main lisp source directory in dired (e.g. d:/product/emacs/lisp or /usr/share/lib/emacs/lisp) and do % g which will grep through all files looking for whatever string you type. Open up that file and see what other people have done with it.
C-h f and C-h v - as someone else mentioned, you can open up source, position point over a function or variable and then get documentation on it.
Check out the Emacs wiki, which has a crap-load of Emacs lisp modules for you to peruse.
I think you are taking the wrong approach. When learning a
programming language and set of libraries (collectively, "Emacs
Lisp"), you need to approach it on both the micro and macro scale.
Before you can start writing software, you need to know what tools you
have available. That is what the Emacs Lisp manual aims to educate
you on. You really need to sit down and read the whole thing. That
way you know what features Emacs provides.
After you do that, you need "micro-level" information. There are
a number of sources that provide this. If you have a general idea of
what you need to do ("working with buffers"), then the Lisp reference
is a good place to figure out what you need to know. If you know that
there's a function that does what you want, but don't quite remember
the name, then M-x apropos (C-u C-h a) will help you search the
documentation. If you know what function you want to use, but don't
remember quite how it works, then M-x describe-function (C-h f)
will sort that out for you.
So anyway, the key is to learn Emacs Lisp, and then let Emacs help you
with the details. A list of functions isn't going to teach you much.
(Oh, one more thing -- you should familiarize yourself with Common
Lisp. Most Emacs libraries use cl, which are the useful CL
functions implemented in Emacs Lisp. loop, destructuring-bind,
defun*, and so on are all there, and they are very helpful.)
Good suggestions from others -- Emacs help system is your friend.
In addition:
http://www.emacswiki.org/emacs/EmacsNewbieWithIcicles
http://www.emacswiki.org/emacs/Icicles_-_Progressive_Completion
http://www.emacswiki.org/emacs/Icicles_-_Nutshell_View#ChippingAway
In order to understand what's on, quite often it's useful having a look at the source code.
http://repo.or.cz/w/elbb.git/blob/HEAD:/code/Go-to-Emacs-Lisp-Definition.el
Have you tryed <f1> f ? It is bound to describe-function. Example with point:
point is a built-in function in C source code.
(point)
Return value of point, as an integer.
Beginning of buffer is position (point-min).
[back]
Like most Lisp systeme, Emacs has an integrated documentation tool!
Any Lisp function or variable can declare an optional doc string.
Almost all standard command or function do declare a usefull doc string.
Emacs (like most Lisp systems) allows you to display the doc string of any function or variable (<f1> f and <f1> v) at any time.
When displayed, the doc string is browsable, meaning that you can click on symbols to see their doc string, or go to the source of the corresponding function or variable.
As soon as you evaluate any defun or defvar, its doc string is available through describe-function or describe-variable: this doc is alive!
M-x find-library RET <library name> is all you really need
If you're willing to fork over money for a dead tree, I'd recommend
(source: oreilly.com)
In XEmacs, and I believe in Emacs as well,
pressing C-h f, then the tab key for tab completion, which at that point is all functions, will give you a list of functions the editor knows about.
You just use cursor keys and scroll to one you want to know about and press enter to see details.
If a list of functions, with further info available, is what you want, that will give it to you.
This list is all currently available functions, so if you have packages of lisp installed, it shows the functions those packages supply as well as native functions. In my copy of XEmacs, today, I have 6,586 functions in the list. Emacs will be similar.
The problem is that not all functions have names that make them context-meaningful (ie not all menu variables/functions have the word menu in them, so you will miss some things if you go by names only.
You can use the INFO pages (on the menu) to view them more topically arranged, and get to the same usage information.
Download source code for Emacs. Go to src/ folder and type:
grep -r DEFUN *
You will get list of all primitive Lisp functions of Emacs.