stdlib

• Index

Contents

• Functions
• Tables
• Types

Core Libraries

• std.debug
• std.io
• std.math
• std.package
• std.string
• std.table

Core Functions

• std

Module std.package

Additions to the core package module.

The module table returned by std.package also contains all of the entries from the core package table. An hygienic way to import this module, then, is simply to override core package locally:

local package = require 'std.package'

Manage package.path with normalization, duplicate removal, insertion & removal of elements and automatic folding of '/' and '?' onto package.dirsep and package.path_mark, for easy addition of new paths. For example, instead of all this:

lib = std.io.catfile('.', 'lib', package.path_mark .. '.lua')
paths = std.string.split(package.path, package.pathsep)
for i, path in ipairs(paths) do
   -- ... lots of normalization code...
end
i = 1
while i <= #paths do
   if paths[i] == lib then
      table.remove(paths, i)
   else
      i = i + 1
   end
end
table.insert(paths, 1, lib)
package.path = table.concat(paths, package.pathsep)

You can now write just:

package.path = package.normalize('./lib/?.lua', package.path)

Functions

find (pathstrings, patt[, init=1[, plain=false]])	Look for a path segment match of patt in pathstrings.
insert (pathstrings[, pos=n+1], value)	Insert a new element into a package.path like string of paths.
mappath (pathstrings, callback, ...)	Call a function with each element of a path string.
normalize (...)	Normalize a path list.
remove (pathstrings[, pos=n])	Remove any element from a package.path like string of paths.

Tables

package

Make named constants for package.config (undocumented in 5.1; see luaconf.h for C equivalents).

Types

mappathcb (element, ...)

Function signature of a callback for mappath.

Functions

find (pathstrings, patt[, init=1[, plain=false]])

Look for a path segment match of patt in pathstrings.

Parameters:

• pathstrings string pathsep delimited path elements
• patt string a Lua pattern to search for in pathstrings
• init integer

  element(not byte index!) to start search at.

  Negative numbers begin counting backwards from the last element
  

  (default 1)
• plain boolean

  unless false, treat patt as a plain

  string, not a pattern. Note that if *plain* is given, then *init*
  must be given as well.
  

  (default false)

Returns:

the matching element number(not byte index!) and full text

of the matching element, if any; otherwise nil

Usage:

i, s = find(package.path, '^[^' .. package.dirsep .. '/]')

insert (pathstrings[, pos=n+1], value)

Insert a new element into a package.path like string of paths.

Parameters:

• pathstrings string a package.path like string
• pos integer

  element index at which to insert value, where n is

  the number of elements prior to insertion
  

  (default n+1)
• value string new path element to insert

Returns:

string a new string with the new element inserted

Usage:

package.path = insert(package.path, 1, install_dir .. '/?.lua')

mappath (pathstrings, callback, ...)

Call a function with each element of a path string.

Parameters:

• pathstrings string a package.path like string
• callback mappathcb function to call for each element
• ... additional arguments passed to callback

Returns:

nil, or first non-nil returned by callback

Usage:

mappath(package.path, searcherfn, transformfn)

normalize (...)

Normalize a path list. Removing redundant . and .. directories, and keep only the first instance of duplicate elements. Each argument can contain any number of pathsep delimited elements; wherein characters are subject to / and ? normalization, converting / to dirsep and ? to path_mark(unless immediately preceded by a % character).

Parameters:

• ... path elements

Returns:

string a single normalized pathsep delimited paths string

Usage:

package.path = normalize(user_paths, sys_paths, package.path)

remove (pathstrings[, pos=n])

Remove any element from a package.path like string of paths.

Parameters:

• pathstrings string a package.path like string
• pos integer

  element index from which to remove an item, where n

  is the number of elements prior to removal
  

  (default n)

Returns:

string a new string with given element removed

Usage:

package.path = remove(package.path)

Tables

package

Make named constants for package.config (undocumented in 5.1; see luaconf.h for C equivalents).

Fields:

• dirsep string directory separator
• pathsep string path separator
• path_mark string string that marks substitution points in a path template
• execdir string (Windows only) replaced by the executable's directory in a path
• igmark string Mark to ignore all before it when building luaopen_ function name.

Types

mappathcb (element, ...)

Function signature of a callback for mappath.

Parameters:

• element string

  an element from a pathsep delimited string of

  paths
  

• ... additional arguments propagated from mappath

Returns:

non-nil to break, otherwise continue with the next element