chapters/17.markdown @ cacf10f606ba

Status Lines
============

Vim allows you to customize the text in the status line at the bottom of each
window.  This is done through the `statusline` option.  Run the following
command:

    :::vim
    :set statusline=%f

You should see the path to the file (relative to the current directory) in the
status line.  Now run this command:

    :::vim
    :set statusline=%f\ -\ FileType:\ %y

Now you'll see something like `foo.markdown - FileType: [markdown]` in the
status line.

If you're familiar with C's `printf` or Python's string interpolation the format
of this option may look familiar.  If not, the only trick is that things that
start with `%` are expanded to different text depending on what comes after
them.  In our example `%f` is replaced with the filename and `%y` is replaced
with the type of the file.

Notice how the spaces in the status line need to be escaped with backslashes.
This is because `set` allows you to set multiple options at once, as we saw in
the second chapter.

Status lines can get extremely complicated very quickly, so there's a better way
to set them that will let us be more clear.  Run the following commands:

    :::vim
    :set statusline=%f         " Path to the file
    :set statusline+=\ -\      " Separator
    :set statusline+=FileType: " Label
    :set statusline+=%y        " Filetype of the file

In the first command we used `=` to wipe out any existing value present.  In the
rest we used `+=` to build up the option one piece at a time.  We also added
comments explaining each piece for other people reading the code (or ourselves
several months later).

Run the following commands:

    :::vim
    :set statusline=%l    " Current line
    :set statusline+=/    " Separator
    :set statusline+=%L   " Total lines

Now the status line contains only the current line number and number of lines in
the file, and looks something like `12/223`.

Width and Padding
-----------------

Additional characters can be used in some of the various `%` codes to change how
the information is displayed.  Run the following command:

    :::vim
    :set statusline=[%4l]

The line number in the status line will now be preceded by enough spaces to make
it at least four characters wide (for example: `[  12]`).  This can be useful to
prevent the text in the status line from shifting around distractingly.

By default the padding spaces are added on the left side of the value.  Run this
command:

    :::vim
    :set statusline=Current:\ %4l\ Total:\ %4L

Your status line will now look like this:

    :::text
    Current:   12 Total:  223

You can use `-` to place padding on the right instead of the left.  Run this
command:

    :::vim
    :set statusline=Current:\ %-4l\ Total:\ %-4L

Your status line will now look like this:

    :::text
    Current: 12   Total: 223 

This looks much nicer because the numbers are next to their labels.

For codes that result in a number you can tell Vim to pad with zeros instead of
spaces.  Run the following command:

    :::vim
    :set statusline=%04l

Now your status line will read `0012` when on line twelve.

Finally, you can also set the maximum width of a code's output.  Run this
command:

    :::vim
    :set statusline=%F

`%F` displays the *full* path to the current file.  Now run this command to
change the maximum width:

    :::vim
    :set statusline=%.20F

The path will be truncated if necessary, looking something like this:

    :::text
    <hapters/17.markdown

This can be useful for preventing paths and other long codes from taking up the
entire line.

General Format
--------------

The general format for a code in a status line is shown in `:help statusline`:

    :::text
    %-0{minwid}.{maxwid}{item}

Everything except the `%` and the item is optional.

Splitting
---------

We're not going to cover status lines in too much detail here (Vim's own
documentation on them is very extensive if you want to learn more), but there's
one more simple code that can be very useful immediately.  Run the following
commands:

    :::vim
    :set statusline=%f         " Path to the file
    :set statusline+=%=        " Switch to the right side
    :set statusline+=%l        " Current line
    :set statusline+=/         " Separator
    :set statusline+=%L        " Total lines

Now the status line will contain the path to the file on the left side, and the
current/total lines on the right side.  The `%=` code tells Vim that everything
coming after that should be aligned (as a whole) to the right instead of the
left.

Exercises
---------

Skim the list of available codes in `:help statusline`.  Don't worry if you
don't understand some of them just yet.

Add some lines to your `~/.vimrc` file to build yourself a custom status line.
Be sure to use the `+=` form of `set` to split the definition across multiple
lines, and add a comment on each line to document what each piece does.

Try using autocommands and `setlocal` to define different status lines for
different filetypes.  Make sure to wrap the autocommands in groups to prevent
duplication (as always).