bareline.txt

*bareline* A statusline plugin for the pragmatic.

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

 Contents ~

1. Introduction                                   |bareline-introduction|
2. Quickstart                                     |bareline-quickstart|
3. Configuration                                  |bareline.config|
4. Custom components                              |bareline-custom-components|
5. Built-in components                            |bareline-built-in-components|

                  Press `gO` to load the table of contents in the location list.
==============================================================================
                                                         *bareline-introduction*
Introduction ~

Key design ideas

1. Ease of configuration.
2. Batteries included experience.
3. No timer required. Update immediately as changes happen.

Concepts

Bareline conceptualizes a statusline in this way:
• A statusline is a list of sections.
• Each section is a list of components.

Visualized example

Statusline: | NOR  lua/bareline.lua                        (main)  22,74/454 |
              Section 1                                    Section 2
              └── Components                               └── Components
                  ├── Vim mode                                 ├── Git HEAD
                  └── Relative file path                       └── Location

------------------------------------------------------------------------------
                                                           *bareline-quickstart*
Quickstart ~

To enable the plugin with the defaults, call the `setup()` function. Usage:
>lua
  local bareline = require("bareline")
  bareline.setup() -- You may provide a table for your config, or pass no
                      argument to hit the ground running with the defaults.
  vim.o.showmode = false -- Optional, recommended.
<
                                                              *bareline.setup()*
                           `bareline.setup`({config})
Module setup.
Parameters ~
{config} `(table|nil)` If a table is provided, it's merged with the default
config (|bareline.default_config|) and the keys in the user's config take
precedence. If `config` is nil, then the default config is used.

------------------------------------------------------------------------------
                                                               *bareline.config*
Configuration ~

The merged config (defaults with user overrides) is in `bareline.config`. The
default config is in `bareline.default_config`. The defaults use distinct
statuslines for active, inactive and plugin windows.

Below is the default config; `bareline` is the value of `require("bareline")`.
>lua
  {
    statuslines = {
      -- Active window.
      active = {
        { -- Section 1: Left.
          bareline.components.vim_mode,
          bareline.components.file_path_relative_to_cwd,
          bareline.components.lsp_servers,
          "%m",
          "%h",
          "%r",
        },
        { -- Section 2: Right.
          bareline.components.diagnostics,
          bareline.components.indent_style,
          bareline.components.end_of_line,
          bareline.components.git_head,
          bareline.components.cwd,
          bareline.components.position,
        },
      },
      -- Inactive windows.
      inactive = {
        { -- Section 1: Left.
          bareline.components.vim_mode:mask(" "),
          bareline.components.file_path_relative_to_cwd,
          bareline.components.lsp_servers,
          "%m",
          "%h",
          "%r",
        },
        { -- Section 2: Right.
          bareline.components.diagnostics,
          bareline.components.indent_style,
          bareline.components.end_of_line,
          bareline.components.cwd,
          bareline.components.position,
        },
      },
      -- Plugin windows.
      plugin = {
        { -- Section 1: Left.
          bareline.components.plugin_name,
          "%m",
        },
        { -- Section 2: Right.
          bareline.components.position,
        },
      },
    },
  }
<
To override the defaults, change only the values of the keys that you need.
You do not have to copy/paste the entire defaults. For example, if you want to
make the inactive statusline be the same as the default active one, you can
call |bareline.setup()| like this:
>lua
  local bareline = require("bareline")
  bareline.setup({
    statuslines = {
      inactive = bareline.default_config.statuslines.active
    }
  })
<
The remaining tags in this section explain each configuration key.

                                                   *bareline.config.statuslines*
Configures the statusline. Each field holds a statusline table definition per
window state. All the fields are of the same type: a list of lists of objects.
The lists are the sections (i.e. left, right) and the objects are the
components (strings, functions or |BareComponent|s).

 Fields: ~

                                            *bareline.config.statuslines.active*
• {active}
Definition for the statusline of the win focused by the cursor.

                                          *bareline.config.statuslines.inactive*
• {inactive}
Definition for the statuslines of the wins which are:
1. NOT focused by the cursor and
2. NOT displaying a plugin's UI.

                                            *bareline.config.statuslines.plugin*
• {plugin}
Definition for the statusline of the wins displaying a plugin's UI.

------------------------------------------------------------------------------
                                                    *bareline-custom-components*
Custom components ~

Each statusline sections is a list-like table of components. These components
can be Bareline's built-in components (|bareline-built-in-components|) or a
type as below:

1. String: Gets evaluated as a statusline string (see 'statusline'). Examples:
   • Arbitrary string: `"PROSE"`. In the statusline you'll see `PROSE`.
   • Options: `vim.bo.fileformat`. In the statusline you might see `unix`.
   • Statusline item: `"%r"`. In the statusline you might see `[RO]`.

2. Function: Returns a string or nil. When a string, it's placed in the
   statusline; when nil, the component is skipped. Example:
>lua
   -- Current working directory.
   local component_cwd = function ()
     local cwd = vim.uv.cwd() or ""
     if cwd == vim.uv.os_getenv("HOME", 60) then return "~" end
     return vim.fn.fnamemodify(cwd, ":t")
   end
   -- Possible output: "bareline.nvim".
<
3. |bareline.BareComponent|: Create one of this type if you need to specify a
   watching config on when to redraw the statusline to keep the component
   up-to-date. This is for when you need to watch a file or directory or
   register autocommands. Use: |bareline-BareComponentWatcher|

   For several use cases, you don't need to specify a watching config, so you
   can get away with a string or function component. The autocmds configured
   by default might be enough to monitor what you are displaying in your
   statusline:

     |BufEnter|, |BufWinEnter|, |WinEnter|, |VimResume|,
     |FocusGained|, |OptionSet|, |DirChanged|, |TermLeave|.

------------------------------------------------------------------------------
                                                        *bareline.BareComponent*
                            `bareline.BareComponent`
Standardized statusline component.
All |bareline-built-in-components| are a |bareline.BareComponent|. To create
your own components, you can use this class or, more simply, follow the
alternate component types described in |bareline-custom-components|.
Class ~
{BareComponent}
Fields ~
{value} `(string|fun():any)` Provides the value displayed in the statusline,
like the Vim mode or diagnostics.
{opts} BareComponentOpts Options.

                                                    *bareline-BareComponentOpts*
Options of a |bareline.BareComponent|.
Class ~
{BareComponentOpts}
Fields ~
{watcher} BareComponentWatcher Watcher. Triggers a statusline redraw.
{cache_on_vim_modes} `(string[]|fun():string[])` Use cache in these Vim modes.
Each Vim mode is expected as the first char returned by |mode()|.

                                                 *bareline-BareComponentWatcher*
Defines watcher configuration for a |bareline.BareComponent| component.
With Bareline, you don't need a timer to have the statusline update when you
expect it to. Since there is no fixed redraw, the plugin needs a way to know
when to do a redraw. That knowledge is provided to Bareline in a per component
basis through this watcher configuration.
Class ~
{BareComponentWatcher}
Fields ~
{autocmd} `(table)` Expects a table with the keys `event` and `opts`. These
values are passed as-is to |vim.api.nvim_create_autocmd()|.
{filepath} `(string|fun():string)` Filepath to watch.

                                                  *bareline.BareComponent:new()*
                 `bareline.BareComponent:new`({value}, {opts})
Constructor.
Parameters ~
{value} `function|string` As a function, it expects no args and returns a
single value of any type. As a string, is used as-is.
{opts} BareComponentOpts Options.
Return ~
Bareline.BareComponent

                                                 *bareline.BareComponent:mask()*
                     `bareline.BareComponent:mask`({char})
Mask with char.
Replace each character of the component with the provided character.
Parameters ~
{char} `(string)` Single character.
Return ~
`(function)` When called returns the masked value.

                                            *bareline.BareComponent:get_value()*
                      `bareline.BareComponent:get_value`()
Retrieve the value of the component.
Return ~
`(string|nil)` Component value.

------------------------------------------------------------------------------
                                                  *bareline-built-in-components*
Built-in components ~

Built-in components for use for |bareline.setup()|. These are all structured
as a |bareline.BareComponent|. User created components may have a simpler
structure. See |bareline-custom-components|.

                                                  *bareline.components.vim_mode*
                         `bareline.components.vim_mode`
Vim mode.
The Vim mode in 3 characters.
Mockups: `NOR`, `VIS`
Type ~
BareComponent

                                               *bareline.components.plugin_name*
                       `bareline.components.plugin_name`
Plugin name.
When on a plugin window, the formatted name of the plugin window.
Mockup: `[nvimtree]`
Type ~
BareComponent

                                              *bareline.components.indent_style*
                       `bareline.components.indent_style`
Indent style.
The indent style. Relies on 'expandtab' and 'tabstop'. This component is
omitted when the buffer has 'modifiable' disabled.
Mockups: `spaces:2`, `tabs:4`
Type ~
BareComponent

                                               *bareline.components.end_of_line*
                       `bareline.components.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 ~
BareComponent

                                                  *bareline.components.git_head*
                         `bareline.components.git_head`
Git HEAD.
Displays the Git HEAD based on the cwd (|pwd|). Useful to show the Git branch.
Mockup: `(main)`
Type ~
BareComponent

                                               *bareline.components.lsp_servers*
                       `bareline.components.lsp_servers`
LSP servers.
The LSP servers attached to the current buffer.
Mockup: `[lua_ls]`
Type ~
BareComponent

                                 *bareline.components.file_path_relative_to_cwd*
                `bareline.components.file_path_relative_to_cwd`
Stable `%f`.
The file path relative to the current working directory (|:pwd|). When the
user home directory appears in the file path, `~` is used to shorten the path.
Mockup: `lua/bareline.lua`
Type ~
BareComponent

                                               *bareline.components.diagnostics*
                       `bareline.components.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 ~
BareComponent

                                                  *bareline.components.position*
                         `bareline.components.position`
Cursor position.
The current cursor position in the format: line,column/total-lines.
Mockup: `181:43/329`
Type ~
BareComponent

                                                       *bareline.components.cwd*
                           `bareline.components.cwd`
Current working directory.
When the current working directory (cwd) is the home dir, then `~` is shown.
Otherwise, the name of the directory is shown, excluding the path.
Mockup: `bareline.nvim`
Type ~
BareComponent

 vim:tw=78:ts=8:noet:ft=help:norl: