Skip to content

Purpose Configuration

Jump to bottom Edit New page
bmag edited this page Feb 23, 2015 · 13 revisions

The "purpose configuration" is a collection of variables that define the purpose of each buffer. The configuration is split into 3 layers: user settings, extensions settings, and default settings. Furthermore, each layer of settings is built from 3 mappings: mode-purposes, name-purposes and regexp-purposes. On top of that, each layer has 2 sets of variables: compiled and interface (non-compiled).

The Configuration

User Settings

The user settings are intended for use by Emacs users (duh!). These settings take precedence over extensions settings and default settings.

Interface variables:

  • purpose-user-mode-purposes: a mapping of modes to purposes. This is an alist that satisfies purpose-mode-alist-p. This is a custom variable and can be changed through the customize interface. When setting this variable from elisp code, you should call purpose-compile-user-configuration for the changes to take effect.
  • purpose-user-name-purposes: a mapping of names to purposes. This is an alist that satisfies purpose-name-alist-p. This is a custom variable and can be changed through the customize interface. When setting this variable from elisp code, you should call purpose-compile-user-configuration for the changes to take effect.
  • purpose-user-regexp-purposes: a mapping of regexps to purposes. This is an alist that satisfies purpose-regexp-alist-p. This is a custom variable and can be changed through the customize interface. When setting this variable from elisp code, you should call purpose-compile-user-configuration for the changes to take effect.

Compiled variables:

  • purpose--user-mode-purposes: this variable is compiled according to purposer-user-mode-purposes when purpose-compile-user-configuration is called, or when purpose-user-mode-purposes is changed through the customize interface. This is a hash-table of mode-purpose pairs.
  • purpose--user-name-purposes: this variable is compiled according to purposer-user-name-purposes when purpose-compile-user-configuration is called, or when purpose-user-name-purposes is changed through the customize interface. This is a hash-table of name-purpose pairs.
  • purpose--user-regexp-purposes: this variable is compiled according to purposer-user-regexp-purposes when purpose-compile-user-configuration is called, or when purpose-user-regexp-purposes is changed through the customize interface. This is a hash-table of regexp-purpose pairs.

Extensions Settings

The extensions settings should be used by code and packages that extend Purpose or need to define their own purpose configuration. The extensions settings have a lower priority than the user settings, and a higher priority than the default settings.

Interface:

  • purpose-conf: purpose-conf is a class (defined with defclass), that contains three members: mode-purposes (satisfies purpose-mode-alist-p), name-purposes (satisfies purpose-name-alist-p) and regexp-purposes (satisfies purpose-regexp-alist-p).
  • purpose-extended-configuration: this is a plist (property-list) that contains purpose-conf objects. You shouldn't change it directly, but use one of the two functions given below. If you do change it directly, you should call purpose-compile-extended-configuration for the changes to take effect.
    For example, the contents of purpose-extended-configuration may look like this:
(list :python (purpose-conf 
                :mode-purposes '((python-mode . python)
                                (python-inferior-mode . interpreter)))
       :popups (purpose-conf
                :mode-purposes '((help-mode . right)
                                 (occur-mode . bottom)
                                 (grep-mode . bottom))))
  • purpose-set-extension-configuration: use this function to add a purpose-conf object to purpose-extended-configuration. This function also calls purpose-compile-extended-configuration.
  • purpose-del-extension-configuration: use this function to remove a purpose-conf object from purpose-extended-configuration. This function also calls purpose-compile-extended-configuration.
  • purpose-compile-extended-configuration: compiles the extensions settings. This generats purpose--extended-mode-purposes, purpose--extended-name-purposes and purpose--extended-regexp-purposes according to purpose-extended-configuration. You don't need to call this function directly - call the two functions given above instead.

Compiled variables:

  • purpose--extended-mode-purposes: this is a hash-table of mode-purpose pairs. It contains the combined mode settings of all purpose-conf objects in purpose-extended-configuration.
  • purpose--extended-name-purposes: this is a hash-table of name-purpose pairs. It contains the combined name settings of all purpose-conf objects in purpose-extended-configuration.
  • purpose--extended-regexp-purposes: this is a hash-table of regexp-purpose pairs. It contains the combined regexp settings of all purpose-conf objects in purpose-extended-configuration.

Example:

;; set configuration for some python-related extension
(purpose-set-extension-configuration :python
    (purpose-conf :mode-purposes '((python-mode . python)
                                   (python-inferior-mode . interpreter))
                  :regexp-purposes '(("^test-.*\\.py$" . test))))
;; delete :python's configuration
(purpose-del-extension-configuration :python)

Default Settings

These are the default settings, which have a lower priority than the user settings and extensions settings. The default settings are hard-coded, and are not meant to be changed (though you could if you try hard). The exact default configuration is listed in the function purpose-compile-default-configuration.

  • purpose--default-mode-purposes: a hash-table of mode-purpose pairs.
  • purpose--default-name-purposes: a hash-table of name-purpose pairs.
  • purpose--default-regexp-purposes: a hash-table of regexp-purpose pairs.
  • purpose-compile-default-configuration: this function generates the contents of purpose--default-mode-purposes, purpose--default-name-purposes and purpose--default-regexp-purposes.
  • purpose-use-default-configuration: toggles whether the default settings sould be considered when getting a buffer's purpose. When this is nil, the default settings are ignored. When this is non-nil, the default settings are used for cases where the user settings and the extensions settings don't produce a purpose. This is a custom variable and can be changed through the customize interface.

Types

  • purpose-mode-alist-entry-p: a predicate that checks if a given object is a cons cell whose car and cdr are both non-nil symbols. This checks that an object is a valid entry in an alist such as purpose-user-mode-purposes.
  • purpose-mode-alist-p: a predicate that checks if a given object can serve as an alist mapping modes to purposes, such as purpose-user-mode-purposes. This works by checking that the given object is a list whose all elements satisfy purpose-mode-alist-entry-p.
  • purpose-name-alist-entry-p: like purpose-mode-alist-entry-p, but the car should be a string. This checks that an object is a valid entry in an alist such as purpose-user-name-purposes.
  • purpose-name-alist-p: like purpose-mode-alist-p, but for mappings of names to purposes, such as purpose-user-name-purposes.
  • purpose-regexp-alist-entry-p: like purpose-mode-alist-entry-p, but the car should be a regexp (actually, a string). This checks that an object is a valid entry in an alist such as purpose-user-regexp-purposes.
  • purpose-regexp-alist-p: like purpose-mode-alist-p, but for mappings of regexps to purposes, such as purpose-user-regexp-purposes.

Getting a Buffer's Purpose

When Purpose needs to get a buffer's purpose, it checks the purpose configuration. The checks are performed in this order:

    1. is the buffer a dummy buffer?
    1. does the buffer's name match a name in the user's name-purpose settings?
    1. does the buffer's name match a regexp in the user's regexp-purpose settings?
    1. does the buffer's major mode match a mode in the user's mode-purpose settings?
    1. does the buffer's name match a name in the extensions' name-purpose settings?
    1. does the buffer's name match a regexp in the extensions' regexp-purpose settings?
    1. does the buffer's major mode match a mode in the extensions' mode-purpose settings?

If purpose-use-default-configuration is non-nil, check also:

    1. does the buffer's name match a name in the default name-purpose settings?
    1. does the buffer's name match a regexp in the default regexp-purpose settings?
    1. does the buffer's major mode match a mode in the default mode-purpose settings?
Add a custom footer
Add a custom sidebar
Clone this wiki locally