Function: forge-insert-topics

forge-insert-topics is a byte-compiled function defined in forge-topic.el.

Signature

(forge-insert-topics TYPE HEADING PREPARE)

Documentation

Insert a list of topics, according to PREPARE.

This function is not intended to be added to section hooks directly. Instead create a function, which calls this function, and add that wrapper to the mode's section hook.

PREPARE is a function which takes one arguments the repository object, and must return a filter object of type forge--topics-spec(var)/forge--topics-spec(fun) or nil. Insert no topics if PREPARE returns nil, or if the current repository isn't tracked or Forge hasn't been fully setup yet (in the latter two cases don't even call PREPARE).

The filter object can be created either using forge--topics-spec(var)/forge--topics-spec(fun) or by cloneing the object returned by forge--init-buffer-topics-spec, to share some settings with other topic lists in the same buffer. See forge--topics-spec(var)/forge--topics-spec(fun) for the valid slots and their values.

HEADING is used as the heading of the list section and TYPE is used as its type. TYPE should be a symbol of the form SUBSET-KIND, where KIND is one of topics, issues or pullreqs, and SUBSET should describe what subset of KIND is being listed.

For example, to insert a list of issues assigned to you use something like:

  (defun my-forge-insert-assigned-issues ()
    "Insert a list of issues that are assigned to me."
    (forge-insert-topics 'assigned-issues "Assigned issues"
      (lambda (repo)
        (and-let* ((me (ghub--username repo)))
          (forge--topics-spec :type 'issue :active t
                              :assignee me)))))

  (magit-add-section-hook 'magit-status-sections-hook
                          #'my-forge-insert-assigned-issues
                          #'forge-insert-issues)

Grep Forge for more examples.

Alternatively you can use forge-topics-setup-buffer to list a set of topics in a dedicated buffer.

Source Code

;; Defined in ~/.emacs.d/elpa/forge-20260408.1922/forge-topic.el
;;; Insert

(defun forge-insert-topics (type heading prepare)
  "Insert a list of topics, according to PREPARE.

This function is not intended to be added to section hooks directly.
Instead create a function, which calls this function, and add that
wrapper to the mode's section hook.

PREPARE is a function which takes one arguments the repository object,
and must return a filter object of type `forge--topics-spec' or nil.
Insert no topics if PREPARE returns nil, or if the current repository
isn't tracked or Forge hasn't been fully setup yet (in the latter two
cases don't even call PREPARE).

The filter object can be created either using `forge--topics-spec' or
by `clone'ing the object returned by `forge--init-buffer-topics-spec',
to share some settings with other topic lists in the same buffer.
See `forge--topics-spec' for the valid slots and their values.

HEADING is used as the heading of the list section and TYPE is used as
its type.  TYPE should be a symbol of the form `SUBSET-KIND', where KIND
is one of `topics', `issues' or `pullreqs', and SUBSET should describe
what subset of KIND is being listed.

For example, to insert a list of issues assigned to you use something
like:

  (defun my-forge-insert-assigned-issues ()
    \"Insert a list of issues that are assigned to me.\"
    (forge-insert-topics \\='assigned-issues \"Assigned issues\"
      (lambda (repo)
        (and-let* ((me (ghub--username repo)))
          (forge--topics-spec :type \\='issue :active t
                              :assignee me)))))

  (magit-add-section-hook \\='magit-status-sections-hook
                          #\\='my-forge-insert-assigned-issues
                          #\\='forge-insert-issues)

Grep Forge for more examples.

Alternatively you can use `forge-topics-setup-buffer' to list a set
of topics in a dedicated buffer."
  (declare (indent defun))
  (when-let* ((_(forge-db t))
              (repo (forge-get-repository :tracked?))
              (spec (funcall prepare repo)))
    (forge--insert-topics type heading (forge--list-topics spec repo))))