### Install Apheleia with straight.el Source: https://github.com/radian-software/apheleia/blob/main/README.md Use this command to install the Apheleia package via the straight.el package manager. ```emacs-lisp (straight-use-package 'apheleia) ``` -------------------------------- ### Enable Global Formatting Mode Source: https://context7.com/radian-software/apheleia/llms.txt Activates Apheleia for all buffers. Add this to your init file or use M-x apheleia-global-mode interactively. ```elisp ;; Enable Apheleia globally in your init file (apheleia-global-mode +1) ``` ```elisp ;; Or enable it interactively M-x apheleia-global-mode ``` -------------------------------- ### Enable Apheleia globally Source: https://github.com/radian-software/apheleia/blob/main/README.md Add this form to your init-file to enable Apheleia globally. It will not load until the first file save. ```elisp (apheleia-global-mode +1) ``` -------------------------------- ### Configure Deno Formatter for TypeScript Projects Source: https://github.com/radian-software/apheleia/wiki/Changing-the-formatter-for-a-single-project Configure .dir-locals.el to use Deno's built-in formatter and enable the Deno language server for TypeScript projects. ```elisp ;;; Directory Local Variables -*- no-byte-compile: t -*- ;;; For more information see (info "(emacs) Directory Variables") ((typescript-ts-mode . ((apheleia-formatter . denofmt) (lsp-enabled-clients . 'deno-ls)))) ``` -------------------------------- ### Configure local formatter in .dir-locals.el Source: https://github.com/radian-software/apheleia/blob/main/README.md Set the formatter for a specific major mode using a directory-local variables file. ```elisp ((python-mode . ((apheleia-formatter . (isort black))))) ``` -------------------------------- ### Enable Buffer-Local Formatting Mode Source: https://context7.com/radian-software/apheleia/llms.txt Activates Apheleia only for the current buffer. Useful for selective formatting. Use M-x apheleia-mode interactively. ```elisp ;; Enable Apheleia for the current buffer only (apheleia-mode +1) ``` ```elisp ;; Or toggle interactively M-x apheleia-mode ``` -------------------------------- ### Configure Formatters (apheleia-formatters) Source: https://context7.com/radian-software/apheleia/llms.txt Defines how external formatters are invoked. Supports command-line arguments, file paths, and Elisp functions. Special symbols like `filepath`, `input`, `output`, and `inplace` can be used. ```elisp ;; Add custom formatter with command-line arguments (setf (alist-get 'black apheleia-formatters) '("black" "--line-length" "100" "-")) ``` ```elisp ;; Define formatter using file path (content passed via stdin) (setf (alist-get 'prettier apheleia-mode-alist) '("apheleia-npx" "prettier" "--stdin-filepath" filepath)) ``` ```elisp ;; Define formatter using input/output temp files (setf (alist-get 'my-formatter apheleia-formatters) '("my-formatter" "--input" input "--output" output)) ``` ```elisp ;; Define formatter that modifies file in-place (setf (alist-get 'oxfmt apheleia-formatters) '("apheleia-npx" "oxfmt" inplace)) ``` ```elisp ;; Formatter with dynamic arguments based on buffer state (setf (alist-get 'beautysh apheleia-formatters) '("beautysh" (when indent-tabs-mode "--tab") (when-let ((indent (bound-and-true-p sh-basic-offset))) (list "--indent-size" (number-to-string indent))) "-")) ``` ```elisp ;; Define an Elisp function as formatter (setf (alist-get 'lisp-indent apheleia-formatters) 'apheleia-indent-lisp-buffer) ``` -------------------------------- ### Configure Biome Formatter for JavaScript/TypeScript Projects Source: https://github.com/radian-software/apheleia/wiki/Changing-the-formatter-for-a-single-project Set Biome as the formatter for various JavaScript and TypeScript modes within a project using a .dir-locals.el file. ```elisp ;;; Directory Local Variables -*- no-byte-compile: t -*- ;;; For more information see (info "(emacs) Directory Variables") ((json-ts-mode . ((apheleia-formatter . biome))) (js-ts-mode . ((apheleia-formatter . biome))) (tsx-ts-mode . ((apheleia-formatter . biome))) (typescript-ts-mode . ((apheleia-formatter . biome)))) ``` -------------------------------- ### Configure Ruff Formatter for Python Projects Source: https://github.com/radian-software/apheleia/wiki/Changing-the-formatter-for-a-single-project Use this snippet in a .dir-locals.el file to set Ruff as the formatter for Python files. Applies to both python-mode and python-ts-mode. ```elisp ;;; Directory Local Variables -*- no-byte-compile: t -*- ;;; For more information see (info "(emacs) Directory Variables") ((python-mode . ((apheleia-formatter . ruff))) (python-ts-mode . ((apheleia-formatter . ruff)))) ``` -------------------------------- ### Manual Buffer Formatting Source: https://context7.com/radian-software/apheleia/llms.txt Manually triggers code formatting for the current buffer. With a prefix argument, it prompts for a specific formatter. Supports callbacks for success and error handling. ```elisp ;; Format the current buffer with the configured formatter M-x apheleia-format-buffer ``` ```elisp ;; Programmatically format with a specific formatter (apheleia-format-buffer 'black) ``` ```elisp ;; Format with multiple chained formatters (apheleia-format-buffer '(isort black)) ``` ```elisp ;; Format with a success callback (apheleia-format-buffer 'prettier (lambda () (message "Formatting complete!"))) ``` ```elisp ;; Format with error handling callback (apheleia-format-buffer 'prettier nil :callback (lambda (&key error) (if error (message "Format failed: %s" error) (message "Format succeeded")))) ``` -------------------------------- ### Define dynamic formatter commands Source: https://github.com/radian-software/apheleia/blob/main/README.md Use evaluated entries in `apheleia-formatters` to conditionally pass flags based on buffer state. ```elisp (push '(shfmt . ("beautysh" "-filename" filepath (when-let ((indent (bound-and-true-p sh-basic-offset))) (list "--indent-size" (number-to-string indent))) (when indent-tabs-mode "--tab") "-")) apheleia-formatters) ``` -------------------------------- ### Chain multiple formatters Source: https://github.com/radian-software/apheleia/blob/main/README.md Configure multiple formatters for a single mode by providing a list of formatter symbols in `apheleia-mode-alist`. ```elisp (setf (alist-get 'isort apheleia-formatters) '("isort" "--stdout" "-")) (setf (alist-get 'python-mode apheleia-mode-alist) '(isort black)) ``` -------------------------------- ### Set Buffer-Local Formatter Override Source: https://context7.com/radian-software/apheleia/llms.txt Override the formatter for a specific buffer using the buffer-local variable `apheleia-formatter`. Can be set in `.dir-locals.el` for project-wide configuration. Use `nil` to disable formatting. ```elisp (setq-local apheleia-formatter 'ruff) ``` ```elisp (setq-local apheleia-formatter '(ruff-isort ruff)) ``` ```elisp ((python-mode . ((apheleia-formatter . ruff))) (python-ts-mode . ((apheleia-formatter . ruff))) (typescript-ts-mode . ((apheleia-formatter . denofmt)))) ``` ```elisp ((python-mode . ((apheleia-formatter . nil)))) ``` -------------------------------- ### Configure Point Alignment Size Source: https://context7.com/radian-software/apheleia/llms.txt Control the dynamic programming algorithm that maintains cursor position during reformatting by setting `apheleia-max-alignment-size`. Larger values may impact performance on large files. ```elisp (setq apheleia-max-alignment-size 400) ``` ```elisp (setq apheleia-max-alignment-size 1000) ``` -------------------------------- ### Configure git-gutter with Apheleia Source: https://github.com/radian-software/apheleia/wiki/Interaction-with-git-gutters.org Use this Emacs Lisp code to ensure git-gutter updates correctly after Apheleia modifies a buffer. It removes conflicting hooks and adds new ones to monitor buffer and window changes. ```emacs-lisp (remove-hook 'post-command-hook #'git-gutter:post-command-hook) (advice-remove #'quit-window #'git-gutter:quit-window) (advice-remove #'switch-to-buffer #'git-gutter:switch-to-buffer) ``` ```emacs-lisp (defvar git-gutter-last-buffer-and-window nil "Cons of current buffer and selected window before last command. This is used to detect when the current buffer or selected window changes, which means that `git-gutter' needs to be re-run.") ``` ```emacs-lisp (defun git-gutter--on-buffer-or-window-change () "Update `git-gutter' when current buffer or selected window changes." (let ((new (cons (current-buffer) (selected-window)))) (unless (equal new git-gutter-last-buffer-and-window) (setq git-gutter-last-buffer-and-window new) ;; Sometimes the current buffer has not gotten updated yet ;; after switching window, for example after `quit-window'. (with-current-buffer (window-buffer) (when git-gutter-mode (when buffer-file-name (unless (file-remote-p buffer-file-name) (git-gutter)))))))) ``` ```emacs-lisp (defun git-gutter--init-maybe () (when (and (buffer-file-name (buffer-base-buffer)) (file-remote-p buffer-file-name) (bound-and-true-p git-gutter-mode)) (git-gutter-mode))) ``` ```emacs-lisp (add-hook 'post-command-hook #'git-gutter--on-buffer-or-window-change) (add-hook 'apheleia-post-format-hook #'git-gutter--on-buffer-or-window-change) ``` -------------------------------- ### Configure Remote File Handling Source: https://context7.com/radian-software/apheleia/llms.txt Configure how Apheleia handles files on remote systems via TRAMP. Set `apheleia-remote-algorithm` to 'cancel' (default), 'remote' (run on remote), or 'local' (run locally, write back remotely). ```elisp (setq apheleia-remote-algorithm 'cancel) ``` ```elisp (setq apheleia-remote-algorithm 'remote) ``` ```elisp (setq apheleia-remote-algorithm 'local) ``` -------------------------------- ### Configure Apheleia Logging Source: https://context7.com/radian-software/apheleia/llms.txt Control how Apheleia logs formatter output and debug information. Set `apheleia-hide-log-buffers` to `nil` to show log buffers in the buffer list. Enable `apheleia-log-debug-info` for detailed logging. ```elisp (setq apheleia-hide-log-buffers nil) ``` ```elisp (setq apheleia-log-only-errors nil) ``` ```elisp (setq apheleia-log-debug-info t) ``` ```elisp (switch-to-buffer "*apheleia-debug-log*") ``` ```elisp (switch-to-buffer "*apheleia-black-log*") ``` -------------------------------- ### Configure Mode-to-Formatter Mapping (apheleia-mode-alist) Source: https://context7.com/radian-software/apheleia/llms.txt Maps Emacs major modes and filename patterns to specific formatters or chains of formatters. Can also be used to disable formatters for certain modes. ```elisp ;; Map a major mode to a single formatter (setf (alist-get 'python-mode apheleia-mode-alist) 'black) (setf (alist-get 'python-ts-mode apheleia-mode-alist) 'black) ``` ```elisp ;; Chain multiple formatters (run in sequence) (setf (alist-get 'python-mode apheleia-mode-alist) '(isort black)) ``` ```elisp ;; Map by filename pattern (regexp) (push '("\.jsx\'" . prettier-javascript) apheleia-mode-alist) ``` ```elisp ;; Disable formatter for a specific mode (set to nil) (setf (alist-get 'jinja2-mode apheleia-mode-alist) nil) ``` ```elisp ;; Override formatter for specific file types (push '("\.mm\'" . clang-format) apheleia-mode-alist) ; Objective-C++ ``` -------------------------------- ### Define Custom Elisp Formatter Source: https://context7.com/radian-software/apheleia/llms.txt Define a formatter as an Elisp function for integration with language servers or custom logic. Register the formatter using `setf` and `alist-get`, then associate it with a mode using `apheleia-mode-alist`. ```elisp (cl-defun my-custom-formatter (&key buffer scratch callback &allow-other-keys) "Custom formatter that uppercases the buffer." (with-current-buffer scratch ;; scratch contains buffer contents to modify (upcase-region (point-min) (point-max)) ;; Call callback when done (nil = success) (funcall callback))) ``` ```elisp (setf (alist-get 'my-upcase apheleia-formatters) 'my-custom-formatter) ``` ```elisp (setf (alist-get 'text-mode apheleia-mode-alist) 'my-upcase) ``` -------------------------------- ### Configure Apheleia Mode Lighter Source: https://context7.com/radian-software/apheleia/llms.txt Customize the text displayed in the mode line or disable the indicator entirely. ```elisp ;; Change the lighter text (default: " Apheleia") (setq apheleia-mode-lighter " Fmt") ;; Disable the lighter entirely (setq apheleia-mode-lighter nil) ``` -------------------------------- ### Navigate to Formatter Errors Source: https://context7.com/radian-software/apheleia/llms.txt Jump to the most recent formatter error message in the log buffer using `apheleia-goto-error`. Programmatically check `apheleia--last-error-marker` before navigating. ```elisp M-x apheleia-goto-error ``` ```elisp (when apheleia--last-error-marker (apheleia-goto-error)) ``` -------------------------------- ### Post-Format Hooks Source: https://context7.com/radian-software/apheleia/llms.txt Execute custom code after successful formatting operations using `apheleia-post-format-hook`. The `apheleia-formatter-exited-hook` runs per formatter in a chain and provides formatter status. ```elisp (add-hook 'apheleia-post-format-hook (lambda () (message "Buffer formatted successfully"))) ``` ```elisp (add-hook 'apheleia-formatter-exited-hook (lambda (&key formatter error log &allow-other-keys) (if error (message "Formatter %s failed" formatter) (message "Formatter %s succeeded" formatter)))) ``` -------------------------------- ### Modify formatter command-line options Source: https://github.com/radian-software/apheleia/blob/main/README.md Use standard Emacs functions to update the `apheleia-formatters` alist for specific command-line arguments. ```elisp (setf (alist-get 'black apheleia-formatters) '("black" "--option" "..." "-")) ``` -------------------------------- ### Inhibit Apheleia Formatting Source: https://context7.com/radian-software/apheleia/llms.txt Prevent Apheleia from automatically enabling in certain buffers using the buffer-local variable `apheleia-inhibit` or hook functions. Add functions to `apheleia-inhibit-functions` or `apheleia-skip-functions` for conditional inhibition. ```elisp (setq-local apheleia-inhibit t) ``` ```elisp ((nil . ((apheleia-inhibit . t)))) ``` ```elisp (add-hook 'apheleia-inhibit-functions (lambda () (string-match-p "vendor" (or buffer-file-name "")))) ``` ```elisp (add-hook 'apheleia-skip-functions (lambda () (> (buffer-size) 1000000))) ; Skip large files ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.