bareline.txt

*bareline* A statusline plugin for the pragmatic.

MIT License Copyright (c) 2024 Hernán Cervera.

Contents:

1. Introduction                                          |bareline-introduction|
2. Configuration                                        |bareline-configuration|
3. Item structure                                      |bareline-item-structure|
4. Custom items                                          |bareline-custom-items|
5. Built-in items                                      |bareline-built-in-items|
6. Built-in alt statuslines                  |bareline-built-in-alt-statuslines|
7. Vimscript functions                            |bareline-vimscript-functions|
8. Functions                                                |bareline-functions|

==============================================================================
                                                         *bareline-introduction*
Introduction ~

Goals

1. Simple configuration.
2. Batteries included experience.
3. Async. No timer. The statusline is updated immediately as changes happen.

Design

Bareline takes this approach to statusline configuration:

1. The statusline DSL ('statusline') is not abstracted away from the user.
   See: |bareline.config.statusline.value|.
2. Helper functions are provided to improve the experience of using the DSL.
   See: |bareline-vimscript-functions|.
3. The plugin exposes "statusline items", which group a buf-local var, a
   callback which sets the var, and autocmds firing the callback.
   See: |bareline.item-structure|.
4. When using any buf-local var in the statusline, reference it either
   directly (`%{b:foo}`) or with a `get` call, `%{get(b:,'foo','')}`. This is
   so the stl is updated by Neovim immediately when the var is updated.

With this design, all Bareline items are asynchronous.

Quickstart

To enable the plugin you need to call the |bareline.setup()| function. To use
the defaults, call it without arguments:
>lua
  require("bareline").setup()
  vim.o.showmode = false -- Optional.
<
                                                              *bareline.setup()*
                           `bareline.setup`({config})
Module setup.
Parameters ~
{config} `(table?)` Merged with the default config (|bareline.default_config|)
and the former takes precedence on duplicate keys.

------------------------------------------------------------------------------
                                                               *bareline.config*
                                                       *bareline.default_config*
                                                        *bareline-configuration*
Configuration ~

The merged config (defaults with user overrides) is in `bareline.config`. The
default config is available in `bareline.default_config`.

Below is the default config, where `bareline` equals `require("bareline")`.
>lua
  {
    statusline = {
      value = "%{BlIs(1)}"
        .. "%{BlInahide(get(b:,'bl_vim_mode',''))}"
        .. "%{BlIs(1)}"
        .. "%<"
        .. "%{BlPad(get(b:,'bl_filepath',''))}"
        .. "%{BlPad(get(b:,'bl_lsp_servers',''))}"
        .. "%{%BlPad(get(b:,'bl_mhr',''))%}"
        .. "%="
        .. "%{BlPad(get(b:,'bl_diagnostics',''))}"
        .. "%{BlPad(get(b:,'bl_end_of_line',''))}"
        .. "%{BlPad(get(b:,'bl_indent_style',''))}"
        .. "%{BlInarm(BlPad(BlWrap(get(b:,'gitsigns_head',''),'(',')')))}"
        .. "%{BlPad(get(b:,'bl_current_working_dir',''))}"
        .. "%{BlIs(1)}"
        .. "%02l:%02c/%02L"
        .. "%{BlIs(1)}",
      items = {
        bareline.items.vim_mode,
        bareline.items.filepath,
        bareline.items.lsp_servers,
        bareline.items.mhr,
        bareline.items.diagnostics,
        bareline.items.end_of_line,
        bareline.items.indent_style,
        bareline.items.current_working_dir,
      },
    },
    alt_statuslines = {
      bareline.alt_statuslines.plugin,
    },
    items = {
      mhr = {
        display_modified = true,
      },
    },
    logging = {
      enabled = false,
      level = vim.log.levels.INFO,
    },
  }
<
                                                    *bareline.config.statusline*
The main statusline.

                                              *bareline.config.statusline.value*
    {value} `(string)`
      String directly assigned to window local 'statusline'.

                                              *bareline.config.statusline.items*
    {items} `(BareItem[])`
      What you are "paying" for in `value`. List here the |bareline.BareItem|s
      in use. You can list here the |bareline-built-in-items|. This is used by
      Bareline to keep the statusline always showing up to date values.
      Failing to do this can lead to seeing values not being updated.

                                               *bareline.config.alt_statuslines*
Alternate statuslines to |bareline.config.statusline|. These can be used to
assign a different statusline on windows that meet some criteria. For example,
Bareline internally uses this feature to assign a different statusline for
plugin windows (e.g., nvim-tree). This list is traversed in order and the
statusline picked is the first one which its `when` function returns true.
See: |bareline-built-in-alt-statuslines|.

                                                         *bareline.config.items*
Provide item-specific configuration.

                                                     *bareline.config.items.mhr*
    {mhr} `(boolean|fun():boolean)`
      See |bareline.items.mhr|.

                                                       *bareline.config.logging*
Log file location: `stdpath("data")` .. `/bareline.nvim/bareline.log`.

                                               *bareline.config.logging.enabled*
    {enabled} `(boolean)`
      Whether to write to the log file. Default: `false`.

                                                 *bareline.config.logging.level*
    {level} `(integer)`
      Log statements on this level and up are written to the log file.
      Default: `vim.log.levels.INFO`.

------------------------------------------------------------------------------
                                                       *bareline-item-structure*
Item structure ~

All custom and built-in items are a |bareline.BareItem|. See:
• |bareline-custom-items|.
• |bareline-built-in-items|.

                                                             *bareline.BareItem*
                              `bareline.BareItem`
Statusline item.
Class ~
{BareItem}
Fields ~
{var} `(string)` Name of buf-local var holding the value of the item. The
value is set directly by `callback`.
{callback} `(fun(var:string))` Sets `var` (`vim.b[var] = "foo"`). The option
`autocmds` (|bareline.BareItemCommonOpts|) decides when to call the callback.
To improve performance on intensive workloads, distribute the processing among
several event loop cycles. Common ways to do this are using the async form of
the function |vim.system()| and using |vim.defer_fn()|.
{opts} `(BareItemCommonOpts)`

                                                   *bareline-BareItemCommonOpts*
Options applicable to any |bareline.BareItem|.
Class ~
{BareItemCommonOpts}
Fields ~
{autocmds} `(table[]?)` Expects tables each with the keys `event` and `opts`,
which are passed to: |vim.api.nvim_create_autocmd()|.

                                                       *bareline.BareItem:new()*
               `bareline.BareItem:new`({var}, {callback}, {opts})
Constructor.
Parameters ~
{var} `(string)`
{callback} `(fun(var:string))`
{opts} `(BareItemCommonOpts)`
Return ~
`(BareItem)`

------------------------------------------------------------------------------
                                                         *bareline-custom-items*
Custom items ~

All custom items are a |bareline.BareItem|. Example item indicating soft wrap:
>lua
  local item_soft_wrap = bareline.BareItem:new(
    "bl_x_soft_wrap",
    function(var)
      local label = nil
      if vim.wo.wrap then
        label = "s-wrap"
      end
      vim.b[var] = label
    end, {
    autocmds = {
      -- IMPORTANT: The autocmds need to account for all the cases where the
      -- value of the buf-local var indicated by `var` would change.
      {
        event = "OptionSet",
        opts = { pattern = "wrap" }
      }
    }
  })
<
Use it:
>lua
  require("bareline").setup({
    statuslines = {
      active = {
        statusline = "%{get(b:,'bl_x_soft_wrap','')}",
        items = {
          -- IMPORTANT: Do not forget to add the item in the `items` list,
          -- otherwise the value won't be updated as expected.
          item_soft_wrap,
        },
      },
    },
  })
>lua
------------------------------------------------------------------------------
                                                       *bareline-built-in-items*
Built-in items ~

All built-in items are a |bareline.BareItem|.

                                                       *bareline.items.vim_mode*
                           `bareline.items.vim_mode`
Vim mode.
The Vim mode in 3 characters.
Mockups: `NOR`, `VIS`
Type ~
`(BareItem)`

                                                    *bareline.items.plugin_name*
                          `bareline.items.plugin_name`
Plugin name.
When on a plugin window, the formatted name of the plugin window.
Mockup: `[nvimtree]`
Type ~
`(BareItem)`

                                                   *bareline.items.indent_style*
                         `bareline.items.indent_style`
Indent style.
Relies on 'expandtab' and 'tabstop'. Omitted when the buf is 'nomodifiable'.
Mockups: `spaces:2`, `tabs:4`
Type ~
`(BareItem)`

                                                    *bareline.items.end_of_line*
                          `bareline.items.end_of_line`
End of line (EOL).
Indicates when the buffer does not have an EOL on its last line. Return `noeol`
in this case, nil otherwise. This uses the option 'eol'.
Type ~
`(BareItem)`

                                                    *bareline.items.lsp_servers*
                          `bareline.items.lsp_servers`
LSP servers.
The LSP servers attached to the current buffer.
Mockup: `[lua_ls]`
Type ~
`(BareItem)`

                                                       *bareline.items.filepath*
                           `bareline.items.filepath`
Stable `%f`.
If the file is in the cwd (|:pwd|) at any depth level, the filepath relative
to the cwd is displayed. Otherwise, the full filepath is displayed.
Mockup: `lua/bareline.lua`
Type ~
`(BareItem)`

                                                    *bareline.items.diagnostics*
                          `bareline.items.diagnostics`
Diagnostics.
The diagnostics of the current buffer. Respects the value of:
`update_in_insert` from |vim.diagnostic.config()|.
Mockup: `e:2,w:1`
Type ~
`(BareItem)`

                                            *bareline.items.current_working_dir*
                      `bareline.items.current_working_dir`
Current working directory (cwd).
The tail of the current working directory.
Mockup: `bareline.nvim`
Type ~
`(BareItem)`

                                                            *bareline.items.mhr*
                              `bareline.items.mhr`
%m%h%r
Display the modified, help and read-only markers using the built-in statusline
fields, see 'statusline' for a list of fields where these are included.
Options (set in |bareline.config.items|):
 • {display_modified} `(boolean|fun():boolean)` Control when the modified
   field (`%m`) is included. When `true`, the field is always displayed except
   when the buf has set 'nomodifiable'. Default: `true`.

Mockups: `[+]`, `[Help][RO]`
Type ~
`(BareItem)`

------------------------------------------------------------------------------
                                             *bareline-built-in-alt-statuslines*
Built-in alt statuslines ~

All custom ad built-in alt stls are structured as a `BarelineAltStatusline`.

Statuslines defined as this class are meant to be used in the configuration
key being |bareline.config.alt_statuslines|, which accepts a list. The list
gets walked in order to find a match (`when`). The first match is used.
Class ~
{BarelineAltStatusline}
Fields ~
{value} `(string)` Value for 'statusline'.
{items} `(BareItem[])` List of bare items.
{when} `((fun():boolean)?)` Indicates a match. The stl should be used.

                                               *bareline.alt_statuslines.plugin*
                       `bareline.alt_statuslines.plugin`
Statusline for plugin windows, including the plugin name.
Type ~
`(BarelineAltStatusline)`

------------------------------------------------------------------------------
                                                  *bareline-vimscript-functions*
Vimscript functions ~

The functions in this section have the goal of facilitating writing the value
for |bareline.config.statusline.value| (i.e., 'statusline'). So the functions
are intended to be used in the statusline string.

                                                                        *BlIs()*
                             `BlIs`({length})
Invisible space. Return a {length} amount of Unicode Thin Space (U+2009)
chars. This is useful to control empty space in the statusline, since ASCII
whitespace is sometimes trimmed by Neovim, while this Unicode char is not.
Parameters:
• {length} `(string)` Amount of consecutive U+2009 chars to return.
Return:
`(string)`

                                                                       *BlIna()*
                         `BlIna`({value},{mapper})
Inactive. In inactive windows return {value} mapped via the funcref {mapper}.
In active windows return {value} as-is.
Parameters:
• {value} `(string)` Any.
• {mapper} `(Funcref)` Takes `{value}` as its single arg. See |Funcref|.
Return:
`(string)`

                                                                     *BlInarm()*
                             `BlInarm`({value})
Inactive remove. In inactive windows return an empty string. In active windows
return {value} as-is.
Parameters:
• {value} `(string)` Any.
Return:
`(string)`

                                                                   *BlInahide()*
                            `BlInahide`({value})
Inactive hide. In inactive windows return {value} masked using |BlIs()|. In
active windows return {value} as-is.
Parameters:
• {value} `(string)` Any.
Return:
`(string)`

                                                                      *BlPadl()*
                             `BlPadl`({value})
Return {value} padded on the left with `BlIs(1)`.
Parameters:
• {value} `(string)` Any.
Return:
`(string)`

                                                                      *BlPadr()*
                             `BlPadr`({value})
Return {value} padded on the right with `BlIs(1)`.
Parameters:
• {value} `(string)` Any.
Return:
`(string)`

                                                                       *BlPad()*
                              `BlPad`({value})
Return {value} padded on both the left and right with `BlIs(1)`.
Parameters:
• {value} `(string)` Any.
Return:
`(string)`

                                                                      *BlWrap()*
                    `BlWrap`({value},{prefix},{suffix})
Return {value} wrapped with {prefix} and {suffix}. Example usage to wrap with
parens the Git HEAD returned by `https://github.com/lewis6991/gitsigns.nvim`:
`BlWrap(get(b:,'gitsigns_head',''),'(',')')`
Parameters:
• {value} `(string)` Any.
• {prefix} `(string)` Any.
• {suffix} `(string)` Any.
Return:
`(string)`

------------------------------------------------------------------------------
                                                            *bareline-functions*
Functions ~

                                                 *bareline.refresh_statusline()*
                        `bareline.refresh_statusline`()
Reassign the proper value to the window local 'statusline'. Use this to
integrate with plugins which provide statusline integration through buf-local
vars and user autocmds.

For example, consider the integration with `lewis6991/gitsigns.nvim`. Out of
the box, Bareline provides this. If it did not provide it, this is how a user
could define it themselves:
>lua
  vim.api.nvim_create_autocmd("User", {
    group = h.statusline_augroup,
    pattern = "GitSignsUpdate",
    callback = function()
      bareline.refresh_statusline()
    end,
  })
<
 vim:tw=78:ts=8:noet:ft=help:norl: