diff --git a/README.md b/README.md index 0c971f1..7e4bdf0 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,13 @@ Snap-indent provides simple automatic indentation (and optional formatting) when - Indent buffer text according to major mode on save (optional) - When indenting, additionally format text, e.g. tabify, untabify, remove trailing whitespace, etc (optional) - Prevent minor mode activation in certain major modes (optional) +- Skip indentation systematically by maximum text length or according to any user-defined predicate (optional) +- Skip indentation for a single operation using an argument prefix (optional) Snap-indent's additional formatting behavior is very flexible. Any function that operates on a region may be used, and multiple functions may be specified. +Snap-indent can be configured to skip indentation with equal flexibility. Any predicate function can be set control this behavior systematically, and indentation may be suppressed for a single operation with key input. + ## Related packages ### Complement to electric-indent-mode @@ -52,14 +56,18 @@ To configure via `use-package`, adapt the following example as desired: ### Customization -| Variable | Type | Default | Description | -|:---------------------------------|:-----------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------| -| `snap-indent-excluded-modes` | symbol list | `(cmake-ts-mode coffee-mode conf-mode elm-mode haml-mode haskell-mode makefile-automake-mode makefile-bsdmake-mode makefile-gmake-mode makefile-imake-mode makefile-makepp-mode makefile-mode occam-mode python-mode python-ts-mode slim-mode yaml-mode yaml-ts-mode)` | Major modes in which to ignore activation | -| `snap-indent-format` | function or list | `nil` | Additional formatting to apply when indenting | -| `snap-indent-on-save` | boolean | `nil` | Whether to indent the entire buffer on save | -| `snap-indent-length-limit` | integer | `nil` | Maximum text length to indent | -| `snap-indent-skip-on-prefix-arg` | boolean | `nil` | Whether a prefix command argument causes indentation to be skipped | -| `snap-indent-skip-on-condition` | function | `nil` | Predicate function to cause indentation to be skipped | +The following customization variables are available: + +| Variable | Type | Default | Description | +|:---------------------------------|:-----------------|:------------------|:-----------------------------------------------------------| +| `snap-indent-excluded-modes` | symbol list | [See list][modes] | Major modes in which to ignore activation | +| `snap-indent-format` | function or list | `nil` | Additional formatting to apply when indenting | +| `snap-indent-on-save` | boolean | `nil` | Whether to indent the entire buffer on save | +| `snap-indent-length-limit` | integer | `nil` | Maximum text length to indent | +| `snap-indent-skip-on-prefix-arg` | boolean | `nil` | Whether a prefix argument causes indentation to be skipped | +| `snap-indent-skip-on-condition` | function | `nil` | Predicate function to cause indentation to be skipped | + +[modes]: snap-indent.el#L60-L77 ### Additional formatting @@ -70,7 +78,18 @@ Snap-indent can optionally apply additional formatting when indenting. This is h (setq snap-indent-format '(untabify delete-trailing-whitespace ...)) ; list of functions ``` -Each function must accept two arguments: the beginning and end positions of the region on which to operate. Functions may be specified as symbols or lambda forms. +Each function must accept two arguments: the beginning and end positions of the region on which to operate. Functions may be specified as symbols or lambda forms. Useful built-in functions include `tabify` and `untabify` for tab/space conversion and `delete-trailing-whitespace`. + +### Controlling activation + +- **Prevention by major mode**. To prevent enabling of `snap-indent-mode` in certain major modes, include these in the `snap-indent-excluded-modes` list. This permits activation for `prog-mode` while excluding certain modes derived from `prog-mode`, for example. + +- **Skipping individual operations**. +When `snap-indent-mode` is enabled, its indentation behavior may still be skipped for an individual operation. + + - To skip indentation on large blocks for text (for performance reasons), set `snap-indent-length-limit`. + - To skip indentation manually for a single command, set `snap-indent-skip-on-prefix-arg` to `t`, then use a prefix argument (e.g. `C-u`) when invoking the command. + - To skip indentation systematically according to any user-specified logic, set `snap-indent-skip-on-condition` to a predicate function. The function must accept two arguments, which specify the start and end positions of the region on which to (potentially) operate. The function should return non-nil to skip indentation, and nil otherwise. ## License diff --git a/snap-indent.el b/snap-indent.el index aecacee..a9fb607 100644 --- a/snap-indent.el +++ b/snap-indent.el @@ -37,10 +37,17 @@ ;; - When indenting, additionally format text, e.g. tabify, untabify, remove ;; trailing whitespace, etc (optional) ;; - Prevent minor mode activation in certain major modes (optional) +;; - Skip indentation systematically by maximum text length or according to any +;; user-defined predicate (optional) +;; - Skip indentation for a single operation using an argument prefix (optional) ;; ;; Snap-indent's additional formatting behavior is very flexible. Any function ;; that operates on a region may be used, and multiple functions may be ;; specified. +;; +;; Snap-indent can be configured to skip indentation with equal flexibility. +;; Any predicate function can be set control this behavior systematically, and +;; indentation may be suppressed for a single operation with key input. ;;; Code: @@ -156,7 +163,7 @@ return non-nil to skip indentation, and nil otherwise." (when (memq this-command '(yank yank-pop)) (snap-indent-maybe-indent (region-beginning) (region-end)))) -;;;###Autoload +;;;###autoload (define-minor-mode snap-indent-mode "Toggle snap-indent mode on or off. Turn snap-indent on if ARG is positive, or off otherwise."