kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

scopes.asciidoc (3569B)


      1 = Scopes
      2 
      3 == Description
      4 
      5 Scopes are groups in which a particular Kakoune object can have different
      6 values depending on the group the value was declared in.
      7 
      8 These scoped objects are:
      9 
     10 - aliases (See <<commands#,`:doc commands`>>)
     11 - faces (See <<faces#,`:doc faces`>>)
     12 - highlighters (See <<highlighters#,`:doc highlighters`>>)
     13 - hooks (See <<hooks#,`:doc hooks`>>)
     14 - keymaps (See <<mapping#,`:doc mapping`>>)
     15 - options (See <<options#,`:doc options`>>)
     16 
     17 == Names and hierarchy
     18 
     19 Scopes are named as follows:
     20 
     21 *window*::
     22     context linked to the window displaying a buffer.
     23 
     24     In Kakoune, the concept of a *window* must not be confused with
     25     the concept of a window at the OS level.
     26     In other terms, a window is *not* a client (like a terminal or GUI)
     27     but one of many 'views' into a buffer.
     28 
     29     There is a N:1 relationship between windows and buffers; once a
     30     window is linked to a buffer, the window's buffer never changes.
     31     Windows store a set of selections and the scroll position.
     32 
     33 *buffer*::
     34     context linked directly to the buffer
     35 
     36 *global*::
     37     global context linked to the instance of Kakoune
     38 
     39 *local*::
     40     A local scope is inserted by each *evaluate-commands* invocations
     41     for its duration. Nested *evaluate-commands* each inject a new
     42     local scope whose parent is the previous local scope. User declared
     43     commands defined with *define-command* also introduce a local scope
     44     while executing.
     45 
     46     A local scope is intended for temporarily overwriting some scoped
     47     value, such as an option or an alias.
     48 
     49 
     50 The following order of priority applies to the above scopes:
     51 
     52 -----------------------------------
     53 local ]> window ]> buffer ]> global
     54 -----------------------------------
     55 
     56 The above priority line implies that objects can have individual values
     57 that will be resolved first in the *local* scope (if it exists), then the
     58 *window* scope, then in the *buffer* scope, and finally in the *global*
     59 scope.
     60 
     61 Normally, the *buffer* scope keyword means the scope associated with the
     62 currently active buffer, but it's possible to specify any existing buffer by
     63 adding an `=` and the value of `%val{buffile}` for that buffer
     64 (See <<expansions#value-expansions,`:doc expansions value-expansions`>>).
     65 For example, to set the `indentwidth` option for the `/etc/fstab` buffer::
     66 
     67 ----
     68 set-option buffer=/etc/fstab indentwidth 8
     69 ----
     70 
     71 The `set-option` and `unset-option` commands also accept *current* as 
     72 a valid scope name. It refers to the narrowest scope the option is set in.
     73 
     74 == Uses
     75 
     76 The scope paradigm is very useful as it allows the user to customize the
     77 behavior of the editor without modifying the configuration globally, as
     78 is the case with other editors who only have a single *global* scope by
     79 default.
     80 
     81 Examples:
     82 
     83 *filetype*::
     84     A single buffer opened in two separate windows can have different
     85     filetypes declared in the *window* scope with 'set-option'.
     86     (See <<options#,`:doc options`>>)
     87 
     88 *status line*::
     89     All the buffers of the current session can have the same information
     90     displayed in the status line, except for a specific buffer (the
     91     'modelinefmt' option can be declared in the *global* scope, and
     92     customized in the *buffer* scope with 'set-option'.
     93     (See <<options#,`:doc options`>>)
     94 
     95 == Execution context
     96 
     97 Some commands work in a specific context that might exclude one or
     98 several scopes altogether, consequently ignoring some values of a given
     99 object.
    100 
    101 Example: the *window* scope is never considered when resolving the
    102 values of options when writing a buffer (e.g. 'BOM', 'eolformat').