documentation: add JS api docs

Signed-off-by: Jo-Philipp Wich <jo@mein.io> (cherry picked from commit d9452d1157aef6b8752fac0f4ed1e0b9221abb31)
author: Jo-Philipp Wich <jo@mein.io> 2019-11-05 09:33:40 +0100
committer: Jo-Philipp Wich <jo@mein.io> 2019-11-05 09:37:52 +0100
commit: 3942789dc62d6a0e7fcfb0a935bfe5c8d372245b (patch)
tree: 9ec432a1dc31c7d837575e7989a47d7cca93e86b /documentation/jsapi/fs.js.html
parent: 9b92b2c8f9ce69cfe89c231311d37177ecaa8d43 (diff)
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' &amp;&amp; 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 &amp;&amp; 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&lt;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&lt;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&lt;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&lt;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&lt;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.&lt;string, string>} [env]
+	 * Environment variables to set.
+	 *
+	 * @returns {Promise&lt;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&lt;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&lt;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 &lt; 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>
author	Jo-Philipp Wich <jo@mein.io>	2019-11-05 09:33:40 +0100
committer	Jo-Philipp Wich <jo@mein.io>	2019-11-05 09:37:52 +0100
commit	3942789dc62d6a0e7fcfb0a935bfe5c8d372245b (patch)
tree	9ec432a1dc31c7d837575e7989a47d7cca93e86b /documentation/jsapi/fs.js.html
parent	9b92b2c8f9ce69cfe89c231311d37177ecaa8d43 (diff)