diff options
Diffstat (limited to 'documentation/jsapi/fs.js.html')
| -rw-r--r-- | documentation/jsapi/fs.js.html | 350 |
1 files changed, 350 insertions, 0 deletions
diff --git a/documentation/jsapi/fs.js.html b/documentation/jsapi/fs.js.html new file mode 100644 index 0000000000..3ee1af8e61 --- /dev/null +++ b/documentation/jsapi/fs.js.html @@ -0,0 +1,350 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> + <title>JSDoc: Source: fs.js</title> + + <script src="scripts/prettify/prettify.js"> </script> + <script src="scripts/prettify/lang-css.js"> </script> + <!--[if lt IE 9]> + <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script> + <![endif]--> + <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css"> + <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css"> +</head> + +<body> + +<div id="main"> + + <h1 class="page-title">Source: fs.js</h1> + + + + + + + <section> + <article> + <pre class="prettyprint source linenums"><code>'use strict'; +'require rpc'; + +/** + * @typedef {Object} FileStatEntry + * @memberof LuCI.fs + + * @property {string} name - Name of the directory entry + * @property {string} type - Type of the entry, one of `block`, `char`, `directory`, `fifo`, `symlink`, `file`, `socket` or `unknown` + * @property {number} size - Size in bytes + * @property {number} mode - Access permissions + * @property {number} atime - Last access time in seconds since epoch + * @property {number} mtime - Last modification time in seconds since epoch + * @property {number} ctime - Last change time in seconds since epoch + * @property {number} inode - Inode number + * @property {number} uid - Numeric owner id + * @property {number} gid - Numeric group id + */ + +/** + * @typedef {Object} FileExecResult + * @memberof LuCI.fs + * + * @property {number} code - The exit code of the invoked command + * @property {string} [stdout] - The stdout produced by the command, if any + * @property {string} [stderr] - The stderr produced by the command, if any + */ + +var callFileList, callFileStat, callFileRead, callFileWrite, callFileRemove, + callFileExec, callFileMD5; + +callFileList = rpc.declare({ + object: 'file', + method: 'list', + params: [ 'path' ] +}); + +callFileStat = rpc.declare({ + object: 'file', + method: 'stat', + params: [ 'path' ] +}); + +callFileRead = rpc.declare({ + object: 'file', + method: 'read', + params: [ 'path' ] +}); + +callFileWrite = rpc.declare({ + object: 'file', + method: 'write', + params: [ 'path', 'data', 'mode' ] +}); + +callFileRemove = rpc.declare({ + object: 'file', + method: 'remove', + params: [ 'path' ] +}); + +callFileExec = rpc.declare({ + object: 'file', + method: 'exec', + params: [ 'command', 'params', 'env' ] +}); + +callFileMD5 = rpc.declare({ + object: 'file', + method: 'md5', + params: [ 'path' ] +}); + +var rpcErrors = [ + null, + 'InvalidCommandError', + 'InvalidArgumentError', + 'MethodNotFoundError', + 'NotFoundError', + 'NoDataError', + 'PermissionError', + 'TimeoutError', + 'UnsupportedError' +]; + +function handleRpcReply(expect, rc) { + if (typeof(rc) == 'number' && rc != 0) { + var e = new Error(rpc.getStatusText(rc)); e.name = rpcErrors[rc] || 'Error'; + throw e; + } + + if (expect) { + var type = Object.prototype.toString; + + for (var key in expect) { + if (rc != null && key != '') + rc = rc[key]; + + if (rc == null || type.call(rc) != type.call(expect[key])) { + var e = new Error(_('Unexpected reply data format')); e.name = 'TypeError'; + throw e; + } + + break; + } + } + + return rc; +} + +/** + * @class fs + * @memberof LuCI + * @hideconstructor + * @classdesc + * + * Provides high level utilities to wrap file system related RPC calls. + * To import the class in views, use `'require fs'`, to import it in + * external JavaScript, use `L.require("fs").then(...)`. + */ +var FileSystem = L.Class.extend(/** @lends LuCI.fs.prototype */ { + /** + * Obtains a listing of the specified directory. + * + * @param {string} path + * The directory path to list. + * + * @returns {Promise<LuCI.fs.FileStatEntry[]>} + * Returns a promise resolving to an array of stat detail objects or + * rejecting with an error stating the failure reason. + */ + list: function(path) { + return callFileList(path).then(handleRpcReply.bind(this, { entries: [] })); + }, + + /** + * Return file stat information on the specified path. + * + * @param {string} path + * The filesystem path to stat. + * + * @returns {Promise<LuCI.fs.FileStatEntry>} + * Returns a promise resolving to a stat detail object or + * rejecting with an error stating the failure reason. + */ + stat: function(path) { + return callFileStat(path).then(handleRpcReply.bind(this, { '': {} })); + }, + + /** + * Read the contents of the given file and return them. + * Note: this function is unsuitable for obtaining binary data. + * + * @param {string} path + * The file path to read. + * + * @returns {Promise<string>} + * Returns a promise resolving to a string containing the file contents or + * rejecting with an error stating the failure reason. + */ + read: function(path) { + return callFileRead(path).then(handleRpcReply.bind(this, { data: '' })); + }, + + /** + * Write the given data to the specified file path. + * If the specified file path does not exist, it will be created, given + * sufficient permissions. + * + * Note: `data` will be converted to a string using `String(data)` or to + * `''` when it is `null`. + * + * @param {string} path + * The file path to write to. + * + * @param {*} [data] + * The file data to write. If it is null, it will be set to an empty + * string. + * + * @param {number} [mode] + * The permissions to use on file creation. Default is 420 (0644). + * + * @returns {Promise<number>} + * Returns a promise resolving to `0` or rejecting with an error stating + * the failure reason. + */ + write: function(path, data, mode) { + data = (data != null) ? String(data) : ''; + mode = (mode != null) ? mode : 420; // 0644 + return callFileWrite(path, data, mode).then(handleRpcReply.bind(this, { '': 0 })); + }, + + /** + * Unlink the given file. + * + * @param {string} + * The file path to remove. + * + * @returns {Promise<number>} + * Returns a promise resolving to `0` or rejecting with an error stating + * the failure reason. + */ + remove: function(path) { + return callFileRemove(path).then(handleRpcReply.bind(this, { '': 0 })); + }, + + /** + * Execute the specified command, optionally passing params and + * environment variables. + * + * Note: The `command` must be either the path to an executable, + * or a basename without arguments in which case it will be searched + * in $PATH. If specified, the values given in `params` will be passed + * as arguments to the command. + * + * The key/value pairs in the optional `env` table are translated to + * `setenv()` calls prior to running the command. + * + * @param {string} command + * The command to invoke. + * + * @param {string[]} [params] + * The arguments to pass to the command. + * + * @param {Object.<string, string>} [env] + * Environment variables to set. + * + * @returns {Promise<LuCI.fs.FileExecResult>} + * Returns a promise resolving to an object describing the execution + * results or rejecting with an error stating the failure reason. + */ + exec: function(command, params, env) { + if (!Array.isArray(params)) + params = null; + + if (!L.isObject(env)) + env = null; + + return callFileExec(command, params, env).then(handleRpcReply.bind(this, { '': {} })); + }, + + /** + * Read the contents of the given file, trim leading and trailing white + * space and return the trimmed result. In case of errors, return an empty + * string instead. + * + * Note: this function is useful to read single-value files in `/sys` + * or `/proc`. + * + * This function is guaranteed to not reject its promises, on failure, + * an empty string will be returned. + * + * @param {string} path + * The file path to read. + * + * @returns {Promise<string>} + * Returns a promise resolving to the file contents or the empty string + * on failure. + */ + trimmed: function(path) { + return L.resolveDefault(this.read(path), '').then(function(s) { + return s.trim(); + }); + }, + + /** + * Read the contents of the given file, split it into lines, trim + * leading and trailing white space of each line and return the + * resulting array. + * + * This function is guaranteed to not reject its promises, on failure, + * an empty array will be returned. + * + * @param {string} path + * The file path to read. + * + * @returns {Promise<string[]>} + * Returns a promise resolving to an array containing the stripped lines + * of the given file or `[]` on failure. + */ + lines: function(path) { + return L.resolveDefault(this.read(path), '').then(function(s) { + var lines = []; + + s = s.trim(); + + if (s != '') { + var l = s.split(/\n/); + + for (var i = 0; i < l.length; i++) + lines.push(l[i].trim()); + } + + return lines; + }); + } +}); + +return FileSystem; +</code></pre> + </article> + </section> + + + + +</div> + +<nav> + <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="LuCI.html">LuCI</a></li><li><a href="LuCI.Class.html">Class</a></li><li><a href="LuCI.dom.html">dom</a></li><li><a href="LuCI.fs.html">fs</a></li><li><a href="LuCI.Headers.html">Headers</a></li><li><a href="LuCI.Network.html">Network</a></li><li><a href="LuCI.Network.Device.html">Device</a></li><li><a href="LuCI.Network.Hosts.html">Hosts</a></li><li><a href="LuCI.Network.Protocol.html">Protocol</a></li><li><a href="LuCI.Network.WifiDevice.html">WifiDevice</a></li><li><a href="LuCI.Network.WifiNetwork.html">WifiNetwork</a></li><li><a href="LuCI.Poll.html">Poll</a></li><li><a href="LuCI.Request.html">Request</a></li><li><a href="LuCI.Request.poll.html">poll</a></li><li><a href="LuCI.Response.html">Response</a></li><li><a href="LuCI.rpc.html">rpc</a></li><li><a href="LuCI.uci.html">uci</a></li><li><a href="LuCI.view.html">view</a></li><li><a href="LuCI.XHR.html">XHR</a></li></ul> +</nav> + +<br class="clear"> + +<footer> + Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Tue Nov 05 2019 09:33:05 GMT+0100 (Central European Standard Time) +</footer> + +<script> prettyPrint(); </script> +<script src="scripts/linenumber.js"> </script> +</body> +</html> |