# 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"

## 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

Methods

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 int element (not byte index!) to start search at. Negative numbers begin counting backwards from the last element (default 1)
  - plain bool 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 int 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 int 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

generated by LDoc 1.4.3 Last updated 2018-09-03 17:48:42