From 42ec7286b2d36a9ba22925f816a17cb1cc2aa5ce Mon Sep 17 00:00:00 2001 From: chai Date: Sat, 30 Oct 2021 11:32:16 +0800 Subject: + Penlight --- Data/Libraries/Penlight/docs/libraries/pl.app.html | 397 +++++++++++++++++++++ 1 file changed, 397 insertions(+) create mode 100644 Data/Libraries/Penlight/docs/libraries/pl.app.html (limited to 'Data/Libraries/Penlight/docs/libraries/pl.app.html') diff --git a/Data/Libraries/Penlight/docs/libraries/pl.app.html b/Data/Libraries/Penlight/docs/libraries/pl.app.html new file mode 100644 index 0000000..4417e8f --- /dev/null +++ b/Data/Libraries/Penlight/docs/libraries/pl.app.html @@ -0,0 +1,397 @@ + + + + + Penlight Documentation + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

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)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) +
+
+ 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. + base allows 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). +
    • +
+ +

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:

+
    +
  1. + a full pathname, or nil
    2. +
  2. + cannot create directory error
    3. +
+ + + +

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:

+
    +
  1. + command-line
    2. +
  2. + name of Lua program used
    3. +
+ + + +

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 the flags_with_values argument).

+ +

Multiple short args can be combined like so: ( -abcd).

+ +

When specifying the flags_valid parameter, its contents can also contain + aliasses, 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 + tab + any flags that take values, either list or hash + table e.g. { out=true } or { "out" }. +
    • +
  • flags_valid + tab + (optional) flags that are valid, either list or hashtable. + If not given, everything + will be accepted(everything in flags_with_values will automatically be allowed) +
    • +
+ +

Returns:

+
    +
  1. + a table of flags (flag=value pairs)
    2. +
  2. + an array of parameters
    3. +
+ +

Raises:

+ if args is nil, then the global args must 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 aliasses:
+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"
+}
    +
+ +
+
+ + +
+
+
+generated by LDoc 1.4.6 +
+
+ + -- cgit v1.1-26-g67d0