I would like to know the best way to customize auto-formatting/auto-indenting in vim for Common Lisp.
Auto-formatting (I usually do this by typing '==' in command mode per line) works very well for the base lisp language in vim (e.g., defmacro, defun, lambda, if, with-output-to-string), but any time that new language constructs are defined (e.g., using macros), I find that the formatting for the new construct is often not what I'd like it to be.
For example, here's how vim formats 'when (standard lisp construct) and 'awhen (commonly-used anaphoric version of 'when; not part of lisp standard)
(when 'this
(process 'this))
(awhen 'this
(process it))
I would like 'awhen to auto-format like 'when. Any ideas how I can do this?
Edit: Thanks Gilligan and Tamas for the Slimv recommendation. As a test, I downloaded MacVim (will need this working with terminal vim, but that's a different problem) and slimv, rsynched the slimv download into ~/.vim, launched MacVim, and loaded a .lisp file.
I then started up the lisp server (done through a GUI with MacVim), which loaded up my default lisp executable and core file.
And* since my core file is already loaded with the language extensions that I commonly use (awhen being one of them), awhen formatted correctly right out of the box.
I really like this solution. Instead of [1] having to learn how to tell vim to indent particular functions properly, and [2] writing the code that does this explicitly for each language extension that I define, and [3] updating that code every time I add a new language construct. Instead I leverage slimv to do the formatting for me. And slimv can 'learn' new language extensions, as long as those macros are already loaded into the lisp core that the server session is using. Pretty slick!
I have found that this works well for a particular class of language extensions. Usually ones defined as a macro, using the &body keyword. This seems to 'do the right thing' most of the time, but there are macros I use that still don't properly auto-format. Although I'd say that this is more likely to be an issue with how the macro is written (non-standard language extension) than anything else.
So, this solution works well for me for most cases, and I didn't have to code (and maintain) anything. Great stuff!
This might not be a direct answer to your question but I strongly suggest that you install
the slimv plugin: http://www.vim.org/scripts/script.php?script_id=2531
Its a great plugin which integrates SLIME functionality into vim and besides many other things it also comes with an improved indentation for clisp&clojure. It won't indent awhen the way you want though.
For those who are looking for this topic and don't want to run Slimv, because they aren't working with Common Lisp or other reasons, here is the scoop.
Vim's Lisp indentation is not like that for other languages; it has a special "Lisp mode". This mode is turned on by
:set lisp
which is done automatically for .lisp files. Lisp mode isn't a Vim invention; classic Vi implementations have a Lisp mode turned on with :set lisp. (It's not described by POSIX, unfortunately).
Vim's Lisp mode has a simple mechanism for recognizing forms that require operator-style indentation: namely, there is a parameter called lispwords which holds a comma-separated list of identifiers.
You can prove to yourself that this is the identifier list which is used, even when you're editing a Common Lisp .lisp file with syntax highlighting and all. Simply do :set listwords[TAB] and edit the list to remove something from it, such as defun. Then try to reindent a defun: you will see the function-style indentation now instead of the operator-style.
The syntax highlighting support for Common Lisp is separate from Lisp mode's lispwords parameter; it has its own list of identifiers. For example, in Vim 7.3 if you enter this:
(symbol-macrolet ((foo bar))
you get indented out to here!)
This is in spite of the fact that symbol-macrolet is recognized and colored. Why? It's because symbol-macrolet does not appear in the rather scanty lispwords list, whereas it does appear in the lisp.vim syntax highlighting definition file.
The upshot is that you can cob together some script which scans your directory of .lisp files for macros and generates a set lispwords=... command that is placed into a directory .vimrc.
Or if you are working on a custom Lisp dialect, you can just make its Vim syntax highlighting file customize lispwords when it loads.
Here is an implementation oversight: the lispwords option has no local value; you cannot use setlocal lispwords ... to give it a buffer-specific value. In other words, it appears that (at least in the Vim 7.3 I'm using under Ubuntu) you can't have two or more buffers open holding different dialects of Lisp with different identifiers for indentation. The default contents of lispwords contains a smattering of Lisp and Scheme symbols to try to be a kind of "one size almost fits all" solution.
If you filetype is 'lisp' then I think you need to add indenting rules for your special case in the 'lisp.vim' file in the '/vim7x/indent' directory. You can find a bit more info in help at :h indent-expr and :h indentexpr.
Someone may be able to tell you better, but I believe the default lisp.vim indent file basically does nothing because the built-in function lispindent() is used to get indent values. You will want to:
(1) set function used to get indent values (i.e., indentexpr) to a function in your own indent/lisp.vim file, e.g., GetLispIndent().
(2) in your your GetLispIndent() function you will use lispindent() to get indent values to return for all lines except your special case. See other languages' indent files and read the docs to get an idea for how indentexpr works, e.g, java.vim.
#Kaz's answer is completely correct, but they don't go all the way to answering the original question. Vim's lispwords config string is a comma-delimited list of words; when any of the words in lispwords is found at the beginning of an S-expression, Vim will change the way that S-expression is indented. In other words, it defines the "standard lisp constructs" to which the OP refers. If you view your current lispwords config with :set lispwords, you'll see "when" is included, but "awhen" is not, resulting in the following indentation:
(when 'this
(process 'this))
(awhen 'this
(process it))
To fix this, simply add "awhen" to the config string somewhere in your config, like so:
set lispwords+=awhen,
The trailing comma isn't strictly necessary, but the default value includes it, and is probably wise in case you or a plugin modifier elsewhere. That would turn the original formatting into this:
(when 'this
(process 'this))
(awhen 'this
(process it))
(Tested on my current installation of Vim 9.0)
Note that, as #Kaz points out, this config string is universal, so if you have different dialects of lisp their indentation will all be controlled by this setting. Vim is pretty good about auto-detecting lisps, but you may need so :set lisp if it doesn't recognize your filetype or dialect.
Related
As described here, emacs-lisp-mode provides for special handling of s-expressions in docstrings that start in the first column. This requires them to be escaped with a backslash to avoid mucking up font-lock later on in the file.
This may be a feature for elisp, but is unfortunate in other lisp modes that reuse emacs-lisp-mode for convenience that don't have special handling of expressions in docstrings, as described/shown here.
My question is, is there any way for such "descendant" modes to configure emacs-lisp-mode to disregard "calling convention expressions" in docstrings?
The short answer is no.
The longer answer is that those other modes are simply broken. They should adapt to Emacs Lisp in this regard. There is no reason not to, is there? It is simply a bad idea to use workarounds (e.g. indent all doc-string lines), such are suggested in the link you provided (and its linked duplicate post).
Emacs doc string are not trivial strings. They have several special properties, including the handling of \\[...], \\{...}, and \\<...>, as well as the property you mention here.
If some mode cannot adjust to Emacs doc strings then it should use macros that define the things it needs without creating Emacs doc strings for them but by handling a different string argument in the special way desired. IOW, create pseudo doc strings that correspond to what the mode wants instead of what Emacs wants.
Of course, that means that you cannot directly take advantage of the Emacs documentation features. You would need to also define mode-specific doc commands that would, for example, wrap the existing doc functions such as describe-function with code that picks up the mode's pseudo-doc string and DTRT, following the mode's conventions instead of the Emacs doc-string conventions.
But I would think that the easiest approach would be to just adapt the mode to the existing Emacs behavior, so that it DTRT.
Many Emacs programming modes, and various Lisp modes are no exception, have been implemented based on parsers with regular expressions. This, unfortunately, gives the editor little idea of the document being edited. Eclipse, for example, has a very different idea of how to edit code, which is more structured, and JetBrain MPS editors are even more rigid and structured in this sense (almost like spreadsheets).
This makes Emacs modes faster and easier to implement, but it also means the code that supports the proper indentation, syntactic validation and highlighting has to re-parse more text every time it is being edited. CEDET, afaik, is trying to address this issue.
Thus, historically, there had been conventions designed to reduce the amount of code to parse on each edit. Parenthesis in the first column is one such convention. However, it also has been known to be an annoyance some times, that's why there's a open-paren-in-column-0-is-defun-start variable one can set to nil to inhibit this behaviour.
But It's hard to say what exactly the performance issues you may face when changing this setting. Lisp grammar is very regular, unless you are using many reader macros, so, perhaps, that won't be a problem.
If beginning-of-defun-function is set accordingly, i.e. checking if inside a comment or string, should be no need for such escaping.
I am not a very good at using Emacs, but the feature I would like the most would be some integration with help/documentation for a particular language/API I use at the moment. I would imagine that there would be help displayed in another buffer depending on where I put my cursor while editing.
I wonder if there is a package that does that, even if it would be very simple, just displaying some file based on the keyword. I think there is, but I cannot find it ("help" is a too generic word).
(In particular, I would like to have this help for Common Lisp, but other languages, such as Java or C, could be useful.)
ILISP and SLIME provide several methods for looking up a function; see the Emacs wiki and the SLIME documentation. Or just built into Emacs itself, there are functions like C-h f to get function help or M-x man; both use the text at the point by default. You could pretty easily adapt them to work for another language of your choice.
Assuming you are using SLIME for common-lisp, you can take a look at slime-autodoc-mode.
Sorry, can't help with a generic solution for this.
You can set up the CLHS root for SLIME in your .emacs file:
(setq common-lisp-hyperspec-root "/usr/share/doc/hyperspec/HyperSpec/")
Adjust the path to where you put your HyperSpec.
Then, C-c C-d h with point at a symbol will look it up there in your browser.
One thing you might like to enable is eldoc-mode, by adding (turn-on-eldoc-mode) to your mode hook functions for the appropriate programming modes.
In ElDoc mode, the echo area displays information about a
function or variable in the text where point is. If point is
on a documented variable, it displays the first line of that
variable's doc string. Otherwise it displays the argument list
of the function called in the expression point is on.
This is probably less than you were after, but it still makes a good companion to a fuller-featured contextual help system, and there are a number of programming modes that support it.
When I run Emacs command ispell-buffer on an Emacs buffer which is in the LaTeX mode, ispell checks spelling also inside math expressions.
I'd very much like to disable this. Is there an easy way to do it?
I've read about detex but detex does not seem to be integrated into Emacs.
It shouldn't do this, if you are using latexisms (eg. \[ ... \], equation environments, &c) to invoke math mode. Check the contents of ispell-tex-skip-alists; cf. section 6 of the ispell FAQ for what kind of thing should be there.
You can use $..$, $$..$$ to mark out maths using ispell-tex-skip-alists, but beware getting them out of kilter...
Postscript
Check also the value of the ispell-parser variable: this should be 'tex, otherwise ispell will not look for $...$ and $$...$$ regions.
Yes, you can: install aspell instead of ispell, and use flyspell with it.
This doesn't answer your question directly, but I have found Flyspell, an on-the-fly spell checker, incredibly useful when editing LaTeX documents. It still spellchecks inside equations, but it is much easier to ignore a few extra red underlines than ispell's interactive commands.
You may know this, but you can press A during spell checking to add a word to the buffer-local dictionary (that's capital A, lowercase a adds it to the global dictionary). It's not ideal, but this is how I usually suppress spell-checking of technical terms and variable names, etc., in my LaTeX documents.
This AUCTeX mailing list thread : "spell checker (ispell-buffer) complains about products in math modes" has some workarounds and the answer demonstrates how to use ispell-tex-skip-alists.
Another approach is to use ispell-skip-region-alist. The following example is to exclude org-mode src blocks:
(add-to-list 'ispell-skip-region-alist '("#\\+begin_src". "#\\+end_src"))
I want to fully-justify latex code on EMACS so that my latex code will look better. For example, I remember my advisor sending me latex in fully justified way like this:
In ~\cite{Hummel2004}, authors described an approach for harvesting
software components from the Web. The basic idea is to use the Web as
the underlying repository, and to utilize standard search engines,
such as Google, as the means of discovering appropriate software
assets. Other researchers have crawled through Internet publicly
available CVS repositories to build their own source code search
engines (e.g., SPARS-J)~\cite{Matsushita2005}.
I suppose that his column-width is set to 70 columns.
Could someone give me a hint?
The standard fill.el package includes the command justify-current-line which is part of what you need. From the function help:
Do some kind of justification on this line.
Normally does full justification: adds spaces to the line to make it end at
the column given by `current-fill-column'.
Optional first argument how specifies alternate type of justification:
it can be `left', `right', `full', `center', or `none'.
If how is t, will justify however the `current-justification' function says to
And other posters have already given you the magicall invokation:
M-x set-justification
As a philosophical side note, the point of fixed-wdith text justification is to fake real typography on a inflexible output device. So applying it to LaTeX source seems a little odd to me. Moreover, I have been using the "one sentence to a line" approach to LaTeX documents for some months now, and find that it really does improves both the editability and the source-control behavior of LaTeX, so I would recommend against doing this.
If you select the region, and then press Ctrl-u M-x fill-region you get "full justification".
M-x set-justification-full
Use Refill mode afterwards to not have to run the command again after typing.
To get line wrap in the file itself (as opposed to something like longlines-mode that does not alter the structure of the file), I use auto-fill-mode, which automatically applies M-q (fill-paragraph) to each paragraph. For example, I use auto-fill-mode in mail-mode. You could do something similar with your LaTeX mode with a hook like this:
(add-hook 'TeX-mode-hook 'turn-on-auto-fill)
Assuming your TeX mode's hook is TeX-mode-hook.
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.