Module pl.app
Application support functions.
See the Guide
Dependencies: pl.utils, pl.path
Functions
| script_name () | return the name of the current script running. | 
| require_here (base, nofollow) | prefixes the current script's path to the Lua module path. | 
| appfile (file) | return a suitable path for files private to this application. | 
| platform () | return string indicating operating system. | 
| lua () | return the full command-line used to invoke this script. | 
| parse_args (args, flags_with_values, flags_valid) | parse command-line arguments into flags and parameters. | 
Functions
- script_name ()
- 
    return the name of the current script running.
 The name will be the name as passed on the command line
    Returns:- 
        string filename
    
 
- require_here (base, nofollow)
- 
    prefixes the current script's path to the Lua module path.
 Applies to both the source and the binary module paths. It makes it easy for
 the main file of a multi-file program to access its modules in the same directory.
 baseallows these modules to be put in a specified subdirectory, to allow for cleaner deployment and resolve potential conflicts between a script name and its library directory.Note: the path is prefixed, so it is searched first when requiring modules. Parameters:- base string optional base directory (absolute, or relative path).
- nofollow boolean always use the invocation's directory, even if the invoked file is a symlink
 Returns:- 
           string
        the current script's path with a trailing slash
    
 
- appfile (file)
- 
    return a suitable path for files private to this application.
 These will look like '~/.SNAME/file', with '~' as with expanduser and
 SNAME is the name of the script without .lua extension.
 If the directory does not exist, it will be created.
    Parameters:- file string a filename (w/out path)
 Returns:- a full pathname, or nil
- cannot create directory error
 Usage:-- when run from a script called 'testapp' (on Windows): local app = require 'pl.app' print(app.appfile 'test.txt') -- C:\Documents and Settings\steve\.testapp\test.txt 
- platform ()
- 
    return string indicating operating system.
    Returns:- 
        'Windows','OSX' or whatever uname returns (e.g. 'Linux')
    
 
- lua ()
- 
    return the full command-line used to invoke this script.
 It will not include the scriptname itself, see app.script_name.
    Returns:- command-line
- name of Lua program used
 Usage:-- execute: lua -lluacov -e 'print(_VERSION)' myscript.lua -- myscript.lua print(require("pl.app").lua()) --> "lua -lluacov -e 'print(_VERSION)'", "lua" 
- parse_args (args, flags_with_values, flags_valid)
- 
    parse command-line arguments into flags and parameters.
 Understands GNU-style command-line flags; short (-f) and long (--flag).These may be given a value with either '=' or ':' ( -k:2,--alpha=3.2,-n2), a number value can be given without a space. If the flag is marked as having a value, then a space-separated value is also accepted (-i hello), see theflags_with_valuesargument).Multiple short args can be combined like so: ( -abcd).When specifying the flags_validparameter, its contents can also contain aliases, to convert short/long flags to the same output name. See the example below.Note: if a flag is repeated, the last value wins. Parameters:- args
            {string}
         an array of strings (default is the global arg)
- flags_with_values
            table
         any flags that take values, either list or hash
 table e.g. { out=true }or{ "out" }.
- flags_valid
            table
         (optional) flags that are valid, either list or hashtable.
 If not given, everything
 will be accepted(everything in flags_with_valueswill automatically be allowed)
 Returns:- a table of flags (flag=value pairs)
- an array of parameters
 Raises:if args is nil, then the globalargsmust be available!Usage:-- Simple form: local flags, params = app.parse_args(nil, { "hello", "world" }, -- list of flags taking values { "l", "a", "b"}) -- list of allowed flags (value ones will be added) -- More complex example using aliases: local valid = { long = "l", -- if 'l' is specified, it is reported as 'long' new = { "n", "old" }, -- here both 'n' and 'old' will go into 'new' } local values = { "value", -- will automatically be added to the allowed set of flags "new", -- will mark 'n' and 'old' as requiring a value as well } local flags, params = app.parse_args(nil, values, valid) -- command: myapp.lua -l --old:hello --value world param1 param2 -- will yield: flags = { long = true, -- input from 'l' new = "hello", -- input from 'old' value = "world", -- allowed because it was in 'values', note: space separated! } params = { [1] = "param1" [2] = "param2" } 
- args
            {string}
         an array of strings (default is the global