*cheatsheet.txt*	Neovim version 0.10	Last Change: 02 Jul 2024


			  NEOVIM PERSONAL CHEATSHEET


This file describes the list of additional commands and utilities available on
top of Neovim default commands.

==============================================================================
1. Additional commands				 *additional-commands-cheat*

							*MakeTags*  >
  (Re)generate tags in current project directory.

It is assumed that |ctags| is available in system PATH and that appropriate
ctags definition exist for the current filetype. To geenrate tags for
Universal ctags (not Exuberant ctags), you need to add individual files in
$HOME/.ctags.d. Here is an example for BibTeX (bib.bib:

	--langdef=bib
	--langmap=bib:.bib
	--regex-bib=/^@{[A-Za-z]+\,
	}{([^,]+),/\1/e,entry/i
	--regex-bib=/^@article{\,
	}{([^,]*)/\1/a,article/i
	--regex-bib=/^@book{\,
	}{([^,]*)/\1/b,book/i

							*Grep*  >
  Custom Grep command

This custom |grep| utility was written by Matthew (strager) Glazar. It
replaces Telescope fuzzy finder when one requires more control or more
Grep-like features. In particular it allows to specify the search directory or
the file extensions as additional filters. Note that FzfLua provides almost
similar features, and it allows to further refine any search query with regex
or fuzzy pattern.

							*Align*  >
  Align text on a specific delimiter

This command was written by Matthew (strager) Glazar and it is used to "easy
align" any region of text on a custom delimiter. Other alternative are more
powerful (e.g., https://github.com/Vonr/align.nvim) as they allow to work with
regex instead of single character and to customize the spacing.

							*Bibopen*  >
  Open PDF file for bibtex entry at point (defunct)

When on a BibTeX entry, open the corresponding PDF or EPUB file.

Deprecated and removed: Now implemented as Lua or VimL function in init.lua
and after/ftplugin/bib.vim.

							*Gist*  >
  Send region as a Gist

Send the selected region to GitHub as a Gist. By default, a public Gist is
assumed.

==============================================================================
2. Debugging with gdb and pdb				*debugging-cheat*

							*About*  >
  Notation and available debuggers

Notation for key sequences:

	‹Module›  A language module or file
	‹Var›     A variable name
	‹Cmd›     A language command
	‹expr›    A language expression
	‹*p›      A language pointer address
	‹args›    A program arguments
	‹n›       A (possibly optional) number
	‹c›       A single character
	«CR»      Press Enter

Debuggers available:

	‹c›       gdb (termdebug)
	‹cpp›     gdb (termdebug)
	‹rust›    rust-gdb (termdebug)
	‹haskell› ghci (terminal)
	‹python›  pdb  (terminal)

Documentation:

- gdb: https://is.gd/ZjzJP3
- ghci: https://is.gd/vQ1Gdi
- pdb: https://is.gd/1aHQ09

See also Beej's Quick Guide to GDB (https://beej.us/guide/bggdb/) for a
getting started guide.

							*Python*  >
  How to debug Python code with pdb

Termdebug does not allow to use the Python debugger directly, but it is
possible to run python -m pdb in an embedded terminal and work as if it was a
Termdebug console. There are subtle differences from classical gdb shortcuts,
that are highlighted below.

Available commands:

	Run program              run ‹args›
	Set breakpoint (line)    b(reak) ‹n›
	Set breakpoint (fn)      b(reak) ‹expr›
	Set temp breakpoint      tbreak ‹n›
	Clear breakpoints        cl(ear)
	Disable breakpoint       disable ‹n›
	Enable breakpoint        enable ‹n›
	Set condition for bp     condition ‹n› ‹expr›
	List src around bp       l(ist) ‹n› ‹n›
	Show long list           ll
	Print args current fn    args
	Print types              whatis ‹Var›
	display value of ‹expr›  display ‹expr›
	Print variable           p ‹Var›
	Pretty print variable    pp ‹Var›
	Show stack trace         w(here)
	Single-stepping mode     c(ontinue)
	Normal stepping mode     s(tep)
	Move current frame down  d(own)
	Move current frame up    u(p)
	Resume execution         n(ext)
	Continue until line      un(til) ‹n›
	Continue until fn end    r(eturn)
	Set next line            j(ump) ‹n›
	Show fn return value     retval

							*C*  >
  How to debug C code with gdb

Termdebug provides a console which runs gdb and where we can use standard gdb
features and instructions (see below). In the source buffer, it is also
possible to use Termdebug commands, e.g., *:Run*, *:Over* (instead of
*:Next*), or *:Evaluate*, which print value of <Var> at point. See
*terminal-debug* for more information. The following commands also applies to
cpp filetype, as well as Rust if you use the rust-gdb debugger (let
g:termdebugger='rust-gdb').

Available commands:

	Set breakpoint (line)    b(reak) ‹n›
	Set breakpoint (fn)      b(reak) ‹expr›
	Set breakpoint (addr)    b(reak) ‹*p›
	Set temp breakpoint      tbreak
	Set watchpoint           watch ‹expr›
	Clear breakpoints        delete ‹n›
	Clear specific bp        clear ‹expr›
	Disable breakpoint       disable ‹n›
	Enable breakpoint        enable ‹n›
	List breakpoint(s)       i(nfo) b(reakpoints) ‹n›
	List checkpoint(s)       i(nfo) checkpoints ‹n›
	List watchpoints         i(nfo) watchpoints
	List registers           i(nfo) r(egisters)
	List threads             i(nfo) threads
	Display fn ‹args›        i(nfo) args
	Run program              r(un) ‹args›
	Normal stepping mode     s(tep) ‹n›
	Show program arguments   show args
	Resume execution (times) c(ontinue) ‹n›
	Resume execution fn end  finish
	Resume execution         n(ext)
	Print variable           p(rint) ‹Var›
	Show stack trace         backtrace
	Assign value to ‹Var›    set ‹Var›=val

							*Haskell*  >
  How to debug Haskell code with ghci

For Haskell, debugging is performed from ghci directly, using the in-built
debugger which is turned on by default. A major restriction is that
breakpoints and single-stepping are only available in interpreted modules, and
compiled code remains invisible to the debugger. More information at
https://downloads.haskell.org/ghc/latest/docs/users_guide/ghci.html#ghci-debugger.

Available commands:

	Set breakpoint (line)    :b(reak) ‹n›
	Set breakpoint (fn)      :b(reak) ‹Module› ‹expr›
	Show breakpoints         :show breaks
	Delete breakpoint        :delete ‹n›
	List src around bp       :l(ist)
	Run program ‹expr›       ‹expr›
	Print variable           :p(rint) ‹Var›
	Reuse Show instances     :set -fprint-evld-with-show to reuse
	Print eval variable      :force ‹Var›
	Print reconstruct types  :show bindings
	Print types              :t ‹Var›
	Print with bindings      ‹Var›
	Resume execution         :continue
	Single-stepping mode     :step ‹expr›
	Normal stepping mode     :step
	Run ‹Cmd› on hitting bp  :set stop :‹Cmd›
	Show stack of contexts   :show context
	Cancel current operation :abandon
	Show current ‹expr›      _result
	Tracing                  :trace ‹expr›
	Show evaluation history  :hist
	Inspect step in history  :back
	Inspect step in history  :forward
	Log steps to exception   :set -fbreak-on-exception

==============================================================================
3. Fixers							*fixers-cheat*

							*Linters*  >
  Preconfigured linters per filetype

Compilers are used to manage linting for specific filetypes via *makeprg*:

- lua: luacheck
- python: pytest (default), mypy, flake8
- markdown: markdownlint
- tex: chktex (default) or textidote
- haskell: stack
- rust: cargo

Linting in normal mode is performed by LSP for the following filetype:
clojure, c, haskell, javascript, lisp.vim, mma, purescript, python, racket, r,
sh, typescript.


							*Formatters*  >
  Preconfigured formatters per filetype

When available, *formatprg* is used to ensure proper formatting on save or using
a common mapping (g= for whole file or gq for selected regions).

- bib: bibclean
- css: prettier
- haskell: ormulu (default) or stylish-haskell
- html: prettier
- json: jq or python -m json.tool
- lua: stylua
- markdown: prettier
- python: black or python3 -m macchiato
- r: styler
- sh: shfmt
- tex: latexindent

Auto-formatting on save is performed by LSP for the following filetype:
clojure, c, haskell, javascript, lisp.vim, mma, purescript, racket, r, sh,
typescript.

==============================================================================
4. Structural editing						*sexp-cheat*

							*Treesitter*  >
  Structural editing with TS text-objects

Treesitter (TS) offer AST-based syntax highlighting. This differs from the
original regex-based syntax highlighting inherited from Vim. Additional
plugins extend TS capabilities, notably nvim-treesitter-textobjects.

Current configuration defines the following mappings: vv to start a selection,
va to increment the selection according to the AST nodes, and vx to decrement
the selection. This is helpful to select inner s-expression and to go outward
up to a defun in Lisp, for instance.

For text objects, the following keymaps are defined:

- aa = "@parameter.outer"
- ia = "@parameter.inner"
- af = "@function.outer"
- if = "@function.inner"
- ac = "@class.outer"
- ic = "@class.inner"

This allows to delete a whole Python function, even when it includes one or
several blank lines with daf in normal mode, for instance.

							*Paredit*  >
  Structural editing with paredit

NOTE: defunct

The vim-paredit [1] plugin (not to be confounded with nvim-paredit [2]) is
part of slimv but it is also available as an independent plugin. It will boost
the in-built Lisp mode (d%, daw, da( and di(, in addition to automatic
indentation) in Neovim. Paredit mode is set by default for the following
filetypes: lisp, clojure, scheme, and racket. Other Lisp dialect are
supported, though: Hy, Shen, and Janet.

Among other things, it provides slurp and barf operators, which are useful to
"extend" or "shrink" an s-expression like 1 2 (3 4) 5 6:

	;; slurp right
	1 2 (3 4 5) 6

	;; barf right
	1 2 (3 4) 5 6

Other interesting features are listed below, but see *paredit* documentation
for more.

- ( and ): find opening and closing parens, up to the top level form
- [[ and ]]: go to start of current or previous defun, or next defun
- ,< and ,>: slurping and barfing
- ,J and ,O: join or split lists or strings
- ,W: wrap the current symbol in parens (,w[ / ,w{ / ,w" are used for other
  delimiters)
- ,S: splice the current list into the sublist (i.e., the opposite of wrap)
- D and dd: delete whole line or characters but keep parens balanced

The leader key (,) can be removed for some of the normal mode mappings (<, >,
J, O, W, S) if we set |g:paredit_shortmaps|.

[1]: https://github.com/kovisoft/paredit
[2]: https://github.com/julienvincent/nvim-paredit

===============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:
