Skip to content

Commit

Permalink
Update documentation to include command skipping
Browse files Browse the repository at this point in the history
  • Loading branch information
@jeffvalk
jeffvalk committed Jul 4, 2023
1 parent ef3bcab commit c4e4929
Show file tree
Hide file tree
Showing 2 changed files with 36 additions and 10 deletions.
37 changes: 28 additions & 9 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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

Expand Down
9 changes: 8 additions & 1 deletion snap-indent.el
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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."
Expand Down

0 comments on commit c4e4929

Please sign in to comment.