nvim-frameline/README.md

# Frameline

### Very minimal framework to write a status/tabline

Frameline is a Lua library for writing your own statusline (and also a tabline)
for Neovim. This is not a ready-made statusline plugin, it's essential just the
*frame*, you have to built the rest by yourself.

Frameline is around 200 lines of Lua with no external dependencies.

## Examples

1. A statusline with the usual components: mode, git branch, filename,
   encoding, etc.

    ```lua
    local frameline = require 'frameline'
    local utils = frameline.utils

    -- Some components
    function mode(win, buf)
      if not win.is_active then return end

      local k = vim.api.nvim_get_mode().mode
      local modes = {
        n={'Normal', 'Normal'},
        i={'Insert', 'Insert'},
        R={'Replas', 'Insert'},
        v={'Visual', 'Visual'},
        V={'V⋅Line', 'VLine'},
        t={'Termin', 'Term'},
        ['']={'V⋅Bloc', 'VBloc'}
      }
      return utils.highlight('Mode'..modes[k][2], ' '..modes[k][1]..' ')
    end

    function branch(_, buf)
      local head = vim.fn.FugitiveHead()
      if buf.modifiable and head ~= "" then return '⚑ '..head end
    end

    function filename(_, buf)
      local delta = ""
      if buf.modified then delta = 'Δ' end
      if not buf.modifiable then delta = '∇' end
      local fname = buf.name ~= "" and utils.filename or 'new-file'
      return delta..fname
    end

    function readonly(_, buf)
      if buf.modifiable and buf.readonly then return '∅' end
    end

    function encoding(_, buf)
      return buf.fileencoding ~= "" and buf.fileencoding or nil
    end

    function filetype(_, buf)
      return buf.filetype ~= "" and buf.filetype or 'no ft'
    end

    -- Statusline
    frameline.setup_statusline(function()
      local segments = {}

      -- Left section
      table.insert(segments, utils.subsection{items={mode}})
      table.insert(segments, utils.subsection{
        separator=' → ',
        items={branch, filename, readonly},
      })
      table.insert(segments, utils.split)

      -- Right section
      table.insert(segments, utils.subsection{
        user=2,
        separator=':', stop=' ',
        items={utils.line_number, utils.column_number},
      })
      table.insert(segments, utils.subsection{
        user=1,
        separator=' ∘ ',
        items={utils.percent, encoding, filetype}
      })

      return segments
    end)
    ```

2. A tabline that shows the current tab, open tabs and date.

    ```lua
      -- Tabline
      frameline.setup_tabline(function()
        local segments = {}
        local api = vim.api
        local color = '%#StatusLine#'

        -- Tabs
        local current = api.nvim_get_current_tabpage()
        local label = ' %d %s '
        for i, tab in pairs(api.nvim_list_tabpages()) do
          -- tab -> active win -> active buf -> name
          local active_buf = api.nvim_win_get_buf(api.nvim_tabpage_get_win(tab))
          local name = api.nvim_buf_get_name(active_buf)
          name = vim.fn.fnamemodify(name, ':t')  -- filename only

          local group = tab == current and 'TablineTabCur' or 'TablineTab'
          table.insert(segments, utils.highlight(group, label:format(i, name)))
        end

        table.insert(segments, color)
        table.insert(segments, utils.split)

        -- Current date
        table.insert(segments, vim.fn.strftime("%a %H:%M"))

        return table.concat(segments)
      end)
    ```

## License

Frameline is licensed under the MIT license.
See the accompanying file LICENSE or https://mit-license.org/.