Class fs.VPath

The internal representation of a pathname.

Pathnames are usually represented in source code, and configuration files, by simple strings. For example:

local my_image_file = "/tmp/pictures.rar/urar://london/big ben.jpg"

Internally, however, MC represents all pathnames as a C structure called vfs_path_t

The VPath Lua class represents this C structure.

This structure breaks down a pathname into its components. So, for example, the above pathname is represented internally as the following structure:

{
  path = {
    {
      path = "/tmp/pictures.rar",
      vfs_class_name = "localfs"
    },
    {
      path = "london/big ben.jpg",
      vfs_class_name = "extfs",
      vfs_prefix = "urar"
    }
  },
  relative = false,
  str = "/tmp/pictures.rar/urar://london/big ben.jpg"
}

You can see this structure by doing:

devel.view( fs.VPath(my_image_file):extract() )

fs.VPath() is a function (a “constructor”) that converts a path string to a VPath object.

Let’s inspect a more complex path:

local my_diff_file = "sh://john:pokemon@www.typo.co.il/tmp/uClibc-snapshot.tar.bz2/utar://uClibc/extra/config/kconfig-to-uclibc.patch.gz/patchfs://config/lxdialog/menubox.c.diff"

doing

devel.view( fs.VPath(my_diff_file):extract() )

…gives:

{
  path = {
    {
      path = "/home/mooffie",
      vfs_class_name = "localfs"
    },
    {
      host = "www.typo.co.il",
      password = "pokemon",
      path = "tmp/uClibc-snapshot.tar.bz2",
      user = "john",
      vfs_class_name = "fish",
      vfs_prefix = "sh"
    },
    {
      path = "uClibc/extra/config/kconfig-to-uclibc.patch.gz",
      vfs_class_name = "tarfs",
      vfs_prefix = "utar"
    },
    {
      path = "config/lxdialog/menubox.c.diff",
      vfs_class_name = "extfs",
      vfs_prefix = "patchfs"
    }
  },
  relative = false,
  str = "/home/mooffie/sh://john:pokemon@www.typo.co.il/tmp/uClibc-snapshot.tar.bz2/utar://uClibc/extra/config/kconfig-to-uclibc.patch.gz/patchfs://config/lxdialog/menubox.c.diff"
}

The first path element points to “/home/mooffie”. This happened to be the cwd when fs.VPath() was called. You can tell fs.VPath() to construct a relative path to get rid of this element.

You can pass a VPath to any function that accepts a path. E.g., you can do either fs.chdir("/") or fs.chdir(fs.VPath("/")).

Fields

path An array of path elements.
relative Whether the vpath is relative or absolute.
str A string representation of the vpath.

Methods

extract() Converts a vpath to a Lua table.
is_local() Determines whether a vpath points to the local filesystem.
last() Returns the last path element.
parent() Returns the vpath with the last path element removed.
tail() Returns the path field of the last path element.
to_str([flags]) Converts a vpath to a string.


Fields

path
An array of path elements.

The full path is broken into “path element"s, which are stored in this array. Each path element belongs to a different filesystem.

A path element contains the following fields:

  • path: The substring of the full path belonging to this filesystem (this field, unfortunately, has the same name as that of the array itself; don’t let this confuse you).
  • vfs_prefix: The prefix of the filesystem (nil for the local filesystem).
  • vfs_class_name: The name of the module implementing the filesystem.
  • user, password, host, port: The components of paths like ftp://joe:password@hostname.net:8192/.

At the time of this writing, a filesystem implemented in Lua doesn’t get its pathnames analyzed for user/password/host/port. The reason is a deficiency in MC (explained in the source).

relative
Whether the vpath is relative or absolute.
str
A string representation of the vpath.

Methods

extract()
Converts a vpath to a Lua table.

This is for debugging/educational purposes.

is_local()
Determines whether a vpath points to the local filesystem.

It’s somewhat like doing vpath:last().vfs_class_name == "localfs", but more efficient.

last()
Returns the last path element.

Equivalent to vpath.path[#vpath.path].

parent()
Returns the vpath with the last path element removed.

If there’s only a single path element, it is not removed: a copy of the original vpath is returned.

See example in the default implementation of a filesystem’s is_same_session.

tail()
Returns the path field of the last path element.

Equivalent to vpath:tail().path.

to_str([flags])

Converts a vpath to a string.

Accepts an optional flags argument. Example:

local bor = utils.bit32.bor

local function longname(path)
  return fs.VPath(path):to_str(bor(fs.VPF_STRIP_HOME, fs.VPF_STRIP_PASSWORD))
end
generated by LDoc 1.4.3 Last updated 2016-08-23 17:29:40