GNU Flymake

https://www.gnu.org/software/emacs/manual/html_node/flymake/
Admin
GNU Flymake is an Emacs minor mode that provides on-the-fly syntax checking for source code files...
Tokens:17,465
Snippets:140
Trust Score:10
Update:5 days ago
Show doc for...
Tokens:
Raw
### Ruby Flymake backend: setup function and hook

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/An-annotated-example-backend.html

This defines a setup function that adds the backend to `flymake-diagnostic-functions` and hooks it into `ruby-mode-hook`.

```emacs-lisp
(defun ruby-setup-flymake-backend ()
  (add-hook 'flymake-diagnostic-functions 'ruby-flymake nil t))

(add-hook 'ruby-mode-hook 'ruby-setup-flymake-backend)
```

--------------------------------

### Ruby Flymake backend: header and variable declaration

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/An-annotated-example-backend.html

The backend file starts with a lexical-binding header and requires cl-lib. It declares a buffer-local variable to hold the process used for checking.

```emacs-lisp
;;; ruby-flymake.el --- A ruby Flymake backend  -*- lexical-binding: t; -*-
(require 'cl-lib)
(defvar-local ruby--flymake-proc nil)
```

--------------------------------

### Makefile check-syntax target with gcc

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Example_002d_002d_002dConfiguring-a-tool-called-via-make.html

Example Makefile target that runs gcc to syntax-check the source files. The || true prevents make from failing on syntax errors.

```makefile
check-syntax:
	gcc -o /dev/null -S ${CHK_SOURCES} || true

```

--------------------------------

### Ruby Flymake backend: main function

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/An-annotated-example-backend.html

The main backend function checks for a Ruby interpreter, kills any previous process, and starts a new process to run 'ruby -w -c'. It sends the buffer contents to the process and parses the output to create diagnostics.

```emacs-lisp
(defun ruby-flymake (report-fn &rest _args)
  ;; Not having a ruby interpreter is a serious problem which should cause
  ;; the backend to disable itself, so an error is signaled.
  ;;
  (unless (executable-find
           "ruby") (error "Cannot find a suitable ruby"))
  ;; If a live process launched in an earlier check was found, that
  ;; process is killed.  When that process's sentinel eventually runs,
  ;; it will notice its obsoletion, since it have since reset
  ;; `ruby--flymake-proc' to a different value
  ;;
  (when (process-live-p ruby--flymake-proc)
    (kill-process ruby--flymake-proc))

  ;; Save the current buffer, the narrowing restriction, remove any
  ;; narrowing restriction.
  ;;
  (let ((source (current-buffer)))
    (save-restriction
      (widen)
      ;; Reset the `ruby--flymake-proc' process to a new process
      ;; calling the ruby tool.
      ;;
      (setq
       ruby--flymake-proc
       (make-process
        :name "ruby-flymake" :noquery t :connection-type 'pipe
        ;; Make output go to a temporary buffer.
        ;;
        :buffer (generate-new-buffer " *ruby-flymake*")
        :command '("ruby" "-w" "-c")
        :sentinel
        (lambda (proc _event)
          ;; Check that the process has indeed exited, as it might
          ;; be simply suspended.
          ;;
          (when (memq (process-status proc) '(exit signal))
            (unwind-protect
                ;; Only proceed if `proc' is the same as
                ;; `ruby--flymake-proc', which indicates that
                ;; `proc' is not an obsolete process.
                ;;
                (if (with-current-buffer source (eq proc ruby--flymake-proc))
                    (with-current-buffer (process-buffer proc)
                      (goto-char (point-min))
                      ;; Parse the output buffer for diagnostic's
                      ;; messages and locations, collect them in a list
                      ;; of objects, and call `report-fn'.
                      ;;
                      (cl-loop
                       while (search-forward-regexp
                              "^\\(?:.*\\.rb\\|-\\):\\([0-9]+\\): \\(.*\\)$"
                              nil t)
                       for msg = (match-string 2)
                       for (beg . end) = (flymake-diag-region
                                          source
                                          (string-to-number (match-string 1)))
                       for type = (if (string-match "^warning" msg)
                                      :warning
                                    :error)
                       when (and beg end)
                       collect (flymake-make-diagnostic source
                                                        beg
                                                        end
                                                        type
                                                        msg)
                       into diags
                       finally (funcall report-fn diags)))
                  (flymake-log :warning "Canceling obsolete check %s"
                               proc))
              ;; Cleanup the temporary buffer used to hold the
              ;; check's output.
              ;;
              (kill-buffer (process-buffer proc)))))))
      ;; Send the buffer contents to the process's stdin, followed by
      ;; an EOF.
      ;;
      (process-send-region ruby--flymake-proc (point-min) (point-max))
      (process-send-eof ruby--flymake-proc))))
```

--------------------------------

### flymake-diagnostics

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Inspecting-diagnostics.html

Get a list of Flymake diagnostics in a specified region of the buffer. If neither beg nor end is supplied, the whole buffer is used; if beg is non-nil and end is nil, only diagnostics at beg are considered.

```APIDOC
## flymake-diagnostics

### Description
Get a list of Flymake diagnostics in the region determined by beg and end. If neither beg or end is supplied, use the whole buffer, otherwise if beg is non-nil and end is nil, consider only diagnostics at beg.

### Function Signature
`flymake-diagnostics beg end`

### Parameters
- `beg` - Optional - The beginning of the region. If nil and end is nil, the whole buffer is used. If non-nil and end is nil, only diagnostics at beg are considered.
- `end` - Optional - The end of the region. If nil and beg is nil, the whole buffer is used.

### Return Value
A list of Flymake diagnostic objects in the specified region.

### Example
```elisp
(flymake-diagnostics)
(flymake-diagnostics beg end)
```

```

--------------------------------

### Define key bindings for Flymake navigation

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Finding-diagnostics.html

Add these key bindings to your init file to map M-n and M-p to flymake-goto-next-error and flymake-goto-prev-error in flymake-mode.

```emacs-lisp
(define-key flymake-mode-map (kbd "M-n") 'flymake-goto-next-error)
(define-key flymake-mode-map (kbd "M-p") 'flymake-goto-prev-error)

```

--------------------------------

### Make command line built by flymake-proc-simple-make-init

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Example_002d_002d_002dConfiguring-a-tool-called-via-make.html

Shows the make command line that flymake-proc-simple-make-init constructs. It uses base-dir (the directory containing the Makefile) and passes CHK_SOURCES, SYNTAX_CHECK_MODE=1, and the check-syntax target.

```emacs-lisp
(list "make"
      (list "-s" "-C"
            base-dir
            (concat "CHK_SOURCES=" source)
            "SYNTAX_CHECK_MODE=1"
            "check-syntax"))

```

--------------------------------

### Define flymake-proc-perl-init init-function

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Example_002d_002d_002dConfiguring-a-tool-called-directly.html

Defines the init-function for perl syntax checking. It creates a temporary copy of the buffer and builds the command line using perl with the -wc option.

```emacs-lisp
(defun flymake-proc-perl-init ()
  (let* ((temp-file (flymake-proc-init-create-temp-buffer-copy
                     'flymake-proc-create-temp-inplace))
         (local-file (file-relative-name
                      temp-file
                      (file-name-directory buffer-file-name))))
    (list "perl" (list "-wc " local-file))))
```

--------------------------------

### Add entry to flymake-proc-allowed-file-name-masks

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Example_002d_002d_002dConfiguring-a-tool-called-directly.html

Adds a new entry to flymake-proc-allowed-file-name-masks for .pl files, using the init-function, standard cleanup-function, and getfname-function.

```emacs-lisp
(setq flymake-proc-allowed-file-name-masks
      (cons '(".+\\.pl$"
              flymake-proc-perl-init
              flymake-proc-simple-cleanup
              flymake-proc-get-real-file-name)
            flymake-proc-allowed-file-name-masks))
```

--------------------------------

### Restore original look for :note diagnostics

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Flymake-error-types.html

Sets the flymake-overlay-control property of :note to an empty list, restoring the original appearance of :note diagnostics.

```emacs-lisp
(put :note 'flymake-overlay-control '())

```

--------------------------------

### flymake-diagnostic-beg

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Inspecting-diagnostics.html

Access the beginning position of a Flymake diagnostic object.

```APIDOC
## flymake-diagnostic-beg

### Description
Access the beginning position of a Flymake diagnostic object.

### Function Signature
`flymake-diagnostic-beg diagnostic`

### Parameters
- `diagnostic` - Required - A Flymake diagnostic object.

### Return Value
The beginning position of the diagnostic.

```

--------------------------------

### Make :note diagnostics stand out with highlight face

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Flymake-error-types.html

Pushes a face property onto the flymake-overlay-control property of the :note symbol to make :note diagnostics more prominent. This overrides any previous face setting.

```emacs-lisp
(push '(face . highlight) (get :note 'flymake-overlay-control))

```

--------------------------------

### Makefile check-syntax target with Automake COMPILE variable

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Example_002d_002d_002dConfiguring-a-tool-called-via-make.html

Alternative Makefile target using the standard Automake variable COMPILE instead of gcc directly. This is recommended when using Automake.

```makefile
check-syntax:
	$(COMPILE) -o /dev/null -S ${CHK_SOURCES} || true

```

--------------------------------

### Add gcc via make to flymake-proc-allowed-file-name-masks

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Example_002d_002d_002dConfiguring-a-tool-called-via-make.html

Registers a new entry in flymake-proc-allowed-file-name-masks for C files, using Flymake's built-in make functions. This is the configuration step to enable syntax checking via make.

```emacs-lisp
(setq flymake-proc-allowed-file-name-masks
      (cons '(".+\\.c$"
              flymake-proc-simple-make-init
              flymake-proc-simple-cleanup
              flymake-proc-get-real-file-name)
            flymake-proc-allowed-file-name-masks))

```

--------------------------------

### Configure new :low-priority-note diagnostic type

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Flymake-error-types.html

Defines a new diagnostic type :low-priority-note that behaves like :note but without an overlay face. Sets flymake-overlay-control to remove the face and flymake-category to flymake-note.

```emacs-lisp
(put :low-priority-note 'flymake-overlay-control '((face . nil)))
(put :low-priority-note 'flymake-category 'flymake-note)

```

--------------------------------

### Bind mouse-3 to search for diagnostic text

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Flymake-error-types.html

Defines a command that searches the web for the text of the topmost diagnostic at the click position, and binds it to mouse-2 for :warning and :error types. Requires the Flymake API functions and uses eww-browse-url.

```emacs-lisp
(defun my-search-for-message (event)
  (interactive "e")
  (let* ((diags (flymake-diagnostics (posn-point (event-start event))))
         (topmost-diag (car diags)))
    (eww-browse-url
       (concat
        "https://duckduckgo.com/?q="
        (replace-regexp-in-string
          " " "+" (flymake-diagnostic-text topmost-diag)))
       t)))

(dolist (type '(:warning :error))
  (push '(mouse-face . highlight) (get type 'flymake-overlay-control))
  (push `(keymap . ,(let ((map (make-sparse-keymap)))
                      (define-key map [mouse-2]
                        'my-search-for-message)
                      map))
        (get type 'flymake-overlay-control)))
```

--------------------------------

### flymake-diagnostic-backend

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Inspecting-diagnostics.html

Access the backend property of a Flymake diagnostic object.

```APIDOC
## flymake-diagnostic-backend

### Description
Access the backend property of a Flymake diagnostic object.

### Function Signature
`flymake-diagnostic-backend diagnostic`

### Parameters
- `diagnostic` - Required - A Flymake diagnostic object.

### Return Value
The backend associated with the diagnostic.

```

--------------------------------

### Backend Function

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Backend-functions.html

A backend function is called by Flymake with a report-fn callback and optional keyword-value pairs. It should initiate a check and return quickly, scheduling expensive work asynchronously.

```APIDOC
## Backend Function

### Description
A backend function is called by Flymake to diagnose the contents of a buffer. It receives a report-fn callback and optional keyword arguments. It should initiate the check and return quickly, scheduling expensive work asynchronously.

### Call Signature
(backend-function report-fn &rest keyword-args)

### Parameters
- **report-fn** (function) - Required - A callback function to report diagnostics.
- **keyword-args** (keyword-value pairs) - Optional - Additional arguments passed by Flymake.

### Keyword Arguments
- **:recent-changes** (list) - Optional - List of recent changes since the last call. Each element is (beg end text). Not provided on first call.
- **:changes-start** (integer) - Optional - Minimum buffer position touched by recent changes. Provided only if :recent-changes is provided.
- **:changes-end** (integer) - Optional - Maximum buffer position touched by recent changes. Provided only if :recent-changes is provided.

### Behavior
- Must return quickly or signal an error (which disables the backend).
- Should cancel any ongoing processing from previous calls before starting new work.
- Should call report-fn with a report-action and optional report-key arguments.

### Report Actions
- **list of diagnostic objects** - A (possibly empty) list of diagnostics created by `flymake-make-diagnostic`. Causes Flymake to annotate the buffer.
- **:panic** - Signals an exceptional situation; the backend will be disabled.

### Report Keys
- **:explanation** (string) - Optional - User-readable details of the situation.
- **:force** (boolean) - Optional - Suggests Flymake consider the report even if unexpected.
- **:region** (cons) - Optional - A cons (beg . end) indicating the report applies to that region; previous reports for other parts remain valid.
```

--------------------------------

### Add entry to flymake-proc-err-line-patterns

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Example_002d_002d_002dConfiguring-a-tool-called-directly.html

Adds a new entry to flymake-proc-err-line-patterns to parse perl error messages, using the pattern for 'at line' errors.

```emacs-lisp
(setq flymake-proc-err-line-patterns
      (cons '("\\(.*\\) at \\([^ \\n]+\\) line \\([0-9]+\\)[,.\\n]"
              2 3 nil 1)
            flymake-proc-err-line-patterns))
```

--------------------------------

### flymake-diagnostic-origin

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Inspecting-diagnostics.html

Access the origin property of a Flymake diagnostic object.

```APIDOC
## flymake-diagnostic-origin

### Description
Access the origin property of a Flymake diagnostic object.

### Function Signature
`flymake-diagnostic-origin diagnostic`

### Parameters
- `diagnostic` - Required - A Flymake diagnostic object.

### Return Value
The origin of the diagnostic.

```

--------------------------------

### flymake-diagnostic-text

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Inspecting-diagnostics.html

Compose the diagnostic's origin, code, and message into a single string.

```APIDOC
## flymake-diagnostic-text

### Description
Compose the diagnostic's origin, code, and message into a single string.

### Function Signature
`flymake-diagnostic-text diagnostic`

### Parameters
- `diagnostic` - Required - A Flymake diagnostic object.

### Return Value
A string composed of the diagnostic's origin, code, and message.

```

--------------------------------

### Remove face from :note diagnostics

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Flymake-error-types.html

Pushes a nil face property onto the flymake-overlay-control property of :note, effectively removing the face from :note diagnostics. This overrides the previous face setting.

```emacs-lisp
(push '(face . nil) (get :note 'flymake-overlay-control))

```

--------------------------------

### flymake-diagnostic-end

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Inspecting-diagnostics.html

Access the end position of a Flymake diagnostic object.

```APIDOC
## flymake-diagnostic-end

### Description
Access the end position of a Flymake diagnostic object.

### Function Signature
`flymake-diagnostic-end diagnostic`

### Parameters
- `diagnostic` - Required - A Flymake diagnostic object.

### Return Value
The end position of the diagnostic.

```

--------------------------------

### flymake-diagnostic-buffer

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Inspecting-diagnostics.html

Access the buffer property of a Flymake diagnostic object.

```APIDOC
## flymake-diagnostic-buffer

### Description
Access the buffer property of a Flymake diagnostic object.

### Function Signature
`flymake-diagnostic-buffer diagnostic`

### Parameters
- `diagnostic` - Required - A Flymake diagnostic object.

### Return Value
The buffer associated with the diagnostic.

```

--------------------------------

### flymake-diagnostic-data

Source: https://www.gnu.org/software/emacs/manual/html_node/flymake/Inspecting-diagnostics.html

Access the data property of a Flymake diagnostic object.

```APIDOC
## flymake-diagnostic-data

### Description
Access the data property of a Flymake diagnostic object.

### Function Signature
`flymake-diagnostic-data diagnostic`

### Parameters
- `diagnostic` - Required - A Flymake diagnostic object.

### Return Value
The data associated with the diagnostic.

```
Tokens:
Raw