HsLua Module: System ==================== This module provides access to system information and functionality via Haskell's `System` module. Intended usage for this package is to preload it by adding the loader function to `package.preload`. Note that the Lua `package` library must have already been loaded before the loader can be added. Example ------- ``` haskell loadProg :: Lua Status loadProg = do openlibs preloadModule documentedModule -- create a temporary directory, print it's path, then delete it again. dostring $ "system = require 'system'\n" <> "system.with_tmpdir('.', 'foo', print)" ``` Documentation ------------- ### Fields #### arch The machine architecture on which the program is running. #### compiler_name The Haskell implementation with which the host program was compiled. #### compiler_version The version of `compiler_name` with which the host program was compiled. #### cputime_precision The smallest measurable difference in CPU time that the implementation can record, and is given as an integral number of picoseconds. #### os The operating system on which the program is running. ### General Functions #### cmd `cmd (command, args[, input[, opts]])` Executes a system command with the given arguments and `input` on *stdin*. Parameters: `command` : command to execute (string) `args` : command arguments ({string,...}) `input` : input on stdin (string) `opts` : process options (table) Returns: - exit code – `false` on success, an integer otherwise (integer|boolean) - stdout (string) - stderr (string) #### cputime `cputime ()` Returns the number of picoseconds CPU time used by the current program. The precision of this result may vary in different versions and on different platforms. See also the field `cputime_precision`. #### env `env ()` Retrieve the entire environment. Returns: - A table mapping environment variables names to their string value (table). #### getenv `getenv (var)` Return the value of the environment variable `var`, or `nil` if there is no such value. Parameters: `var` : name of the environment variable (string) Returns: - value of the variable, or nil if the variable is not defined (string or nil). #### getwd `getwd ()` Obtain the current working directory as an absolute path. Returns: - The current working directory (string). #### ls `ls ([directory])` List the contents of a directory. Parameters: `directory` : Path of the directory whose contents should be listed (string). Defaults to `.`. Returns: - A table of all entries in `directory` without the special entries (`.` and `..`). #### mkdir `mkdir (dirname [, create_parent])` Create a new directory which is initially empty, or as near to empty as the operating system allows. The function throws an error if the directory cannot be created, e.g., if the parent directory does not exist or if a directory of the same name is already present. If the optional second parameter is provided and truthy, then all directories, including parent directories, are created as necessary. Parameters: `dirname` : name of the new directory `create_parent` : create parent directories if necessary #### rmdir `rmdir (dirname [, recursive])` Remove an existing, empty directory. If `recursive` is given, then delete the directory and its contents recursively. Parameters: `dirname` : name of the directory to delete `recursive` : delete content recursively #### setenv `setenv (var, value)` Set the specified environment variable to a new value. Parameters: `var` : name of the environment variable (string). `value` : new value (string). #### setwd `setwd (directory)` Change the working directory to the given path. Parameters: `directory` : Path of the directory which is to become the new working directory (string) #### tmpdirname `tmpdirname ()` Returns the current directory for temporary files. On Unix, `tmpdirname()` returns the value of the `TMPDIR` environment variable or "/tmp" if the variable isn't defined. On Windows, the function checks for the existence of environment variables in the following order and uses the first path found: - TMP environment variable. - TEMP environment variable. - USERPROFILE environment variable. - The Windows directory The operation may fail if the operating system has no notion of temporary directory. The function doesn't verify whether the path exists. Returns: - The current directory for temporary files (string). #### with\_env `with_env (environment, callback)` Run an action within a custom environment. Only the environment variables given by `environment` will be set, when `callback` is called. The original environment is restored after this function finishes, even if an error occurs while running the callback action. Parameters: `environment` : Environment variables and their values to be set before running `callback`. (table with string keys and string values) `callback` : Action to execute in the custom environment (function) Returns: - The result(s) of the call to `callback` #### with\_tmpdir `with_tmpdir ([parent_dir,] templ, callback)` Create and use a temporary directory inside the given directory. The directory is deleted after use. Parameters: `parent_dir` : Parent directory to create the directory in (string). If this parameter is omitted, the system's canonical temporary directory is used. `templ` : Directory name template (string). `callback` : Function which takes the name of the temporary directory as its first argument (function). Returns: - The result of the call to `callback`. #### with\_wd `with_wd (directory, callback)` Run an action within a different directory. This function will change the working directory to `directory`, execute `callback`, then switch back to the original working directory, even if an error occurs while running the callback action. Parameters: `directory` : Directory in which the given `callback` should be executed (string) `callback` : Action to execute in the given directory (function) Returns: - The result(s) of the call to `callback` License ------- This package is licensed under the MIT license. See [`LICENSE`](LICENSE) for details.