feat: ex.relative_filename

[vladimir-popov]

ex.relative_filename

This component shows a filename: a file name and a path to the current file relative to the current working directory, and may be used effectively together with ex.cwd. The filename has a prefix, which shows a file's place in the file system relative to the cwd:

File path relative to cwd	Options	Component example
inside cwd
outside cwd	external_prefix = "/..."
outside cwd, but inside $HOME

Some path may be very long and takes significant part in the statusline. It's possible to specify the {max_length} of the filename. To achieve that the follow algorithm is used:

• every part of the path is shorten till the {shorten.length} except parts from the {shorten.exclude} list;
• then the {shorten.length} will be repeatedly decreased until 1 or until the {max_length} will be achieved;
• if it's not enough then the {exclude} setting will be ignored and all parts will be shorten;
• if the result is still longer than {max_length} than only the file name will be used with the prefix {filename_only_prefix}.

Example of the shorten filename with follow options { shorten: { length = 3, exclude = { 1 } } }:

Space for component enough to show ...	Component example
the whole path
the path with specified options (shorten.length = 3)
the path with shorten.length = 2
the path with shorten.length = 1
the path ignoring exclude section
only the file name

The {max_length} may be a number, or a function which receives the current component value and returns a number:

• Every value less than 0 means that the filename never should be shorten;
• Zero means that filename should be always shorten;
• A value more or equal to 1 represents a length, after which the filename should be shorten;
• A value between 0 and 1 represents a fraction of the current window width if the {laststatus} == 2, or a fraction of the terminal width.

Default configuration:

{
    -- The prefix which is used when the current file is outside cwd
    external_prefix = nil,

    -- The prefix which is used when the length of the filename after shorten
    -- is longer than {max_length}
    filename_only_prefix = '…/',

    -- The max length of the component value.
    -- < 0          - never shorten; 
    -- 0            - always shorten; 
    -- > 0 and  < 1 - shorten when longer than {max_length} * {vim.o.columns} 
    --                for {laststatus} == 3;
    --                and shorten when longer than 
    --                {max_length} * {vim.api.nvim_win_get_width(0)} overwise; 
    -- >= 1         - shorten when longer then N symbols;
    max_length = 0.3,

    -- The configuration of the shorten algorithm.
    shorten = { 
        -- The count of letters, which will be taken from every part of the path
        lenght = 5, 
        -- The list of indexes of filename parts, which should not be shorten at all
        -- (the file name { -1 } is always excluded)
        exclude = nil 
    },
}

_ex.relative_filename component doesn't provide options to show file states, because it easily possible to do with standard approach:_

-- readonly mode indicator example:
{
    '%{""}',
    draw_empty = true,
    icon = { '' },
    cond = function()
        return not vim.bo.modifiable
    end,
}