chapters/40.markdown @ ee45fef4cd6b

Paths
=====

Vim is a text editor, and text editors (usually) work with text files.  Text
files live on filesystems, and to specify files we use paths.  Vimscript has
a few built-in utilities that can be extremely helpful when you need to work
with paths.

Absolute Paths
--------------

Sometimes it's handy to be able to get the absolute path of a certain file for
use with external scripts.  Run the following commands:

    :::vim
    :echom expand('%')
    :echom expand('%:p')
    :echom fnamemodify('foo.txt', ':p')

The first command displays the relative path of whatever file you're currently
editing.  `%` means "the current file".  Vim supports a bunch of other strings
you can use with `expand()` as well.

The second command displays the full, absolute path of that file.  The `:p` in
the string tells Vim that you want the absolute path.  There are a ton of other
modifiers you can use.

The third command displays an absolute path to the file `foo.txt` in the current
directory, regardless of whether that file actually exists.  `fnamemodify()` is
a Vim function that's more flexible than `expand()` in that you can specify any
file name, not just one of `expand()`'s special strings.

Listing Files
-------------

You might also want to get a listing of files in a specific directory.  Run the
following command:

    :::vim
    :echo globpath('.', '*')

Vim will display all of the files and directories in the current directory.  The
`globpath()` function returns a string, with each name separated by a newline.
To get a list you'll need to `split()` it yourself.  Run this command:

    :::vim
    :echo split(globpath('.', '*'), '\n')

This time Vim displays a Vimscript list containing each path.  If you've got
newlines in your filenames you're on your own, sorry.

`globpath()`'s wildcards work mostly as you would expect.  Run the following
command:

    :::vim
    :echo split(globpath('.', '*.txt'), '\n')

Vim displays a list of all `.txt` files in the current directory.

You can recursively list files with `**`.  Run this command:

    :::vim
    :echo split(globpath('.', '**'), '\n')

Vim will list all files and directories under the current directory.

`globpath()` is *extremely* powerful.  You'll learn more when you complete this
chapter's exercises.

Exercises
---------

Read `:help expand()`.

Read `:help fnamemodify()`.

Read `:help filename-modifiers`.

Read `:help simplify()`.

Read `:help resolve()`.

Read `:help globpath()`.

Read `:help wildcards`.