gryf/pentadactyl-pm
1
0
Fork 0
mirror of https://github.com/gryf/pentadactyl-pm.git synced 2025-12-20 09:48:00 +01:00
Code Issues Projects Releases Wiki Activity

Add some API documentation for Options and others.

Browse Source
This commit is contained in:
Doug Kearns
2009-05-20 14:23:32 +10:00
parent 9d26a8a20d
commit f834cfcd6b
8 changed files with 611 additions and 184 deletions
Download Patch File Download Diff File Expand all files Collapse all files

453
common/content/commands.js
View File

@@ -41,14 +41,15 @@ the terms of any one of the MPL, the GPL or the LGPL.
* @param {function} action The action invoked by this command when executed.
* @param {Object} extraInfo An optional extra configuration hash. The
* following properties are supported.
* argCount - See (@link Command#argCount)
* bang - See (@link Command#bang)
* completer - See (@link Command#completer)
* count - See (@link Command#count)
* heredoc - See (@link Command#heredoc)
* literal - See (@link Command#literal)
* options - See (@link Command#options)
* serial - See (@link Command#serial)
* argCount - see {@link Command#argCount}
* bang - see {@link Command#bang}
* completer - see {@link Command#completer}
* count - see {@link Command#count}
* heredoc - see {@link Command#heredoc}
* literal - see {@link Command#literal}
* options - see {@link Command#options}
* serial - see {@link Command#serial}
* @optional
* @private
*/
function Command(specs, description, action, extraInfo) //{{{
@@ -91,64 +92,84 @@ function Command(specs, description, action, extraInfo) //{{{
};
let expandedSpecs = parseSpecs(specs);
/** @property {string[]} All of this command's name spacs. e.g., "com[mand]" */
/**
* @property {string[]} All of this command's name specs. e.g., "com[mand]"
*/
this.specs = specs;
/** @property {string[]} All of this command's short names, e.g., "com" */
this.shortNames = expandedSpecs.shortNames;
/** @property {string[]} All of this command's long names, e.g., "command" */
this.longNames = expandedSpecs.longNames;
/**
* @property {string[]} All of this command's long names, e.g., "command"
*/
this.longNames = expandedSpecs.longNames;
/** @property {string} The command's canonical name. */
this.name = this.longNames[0];
this.name = this.longNames[0];
/** @property {string[]} All of this command's long and short names. */
this.names = expandedSpecs.names; // return all command name aliases
this.names = expandedSpecs.names; // return all command name aliases
/** @property {string} This command's description, as shown in :exusage */
this.description = description || "";
/** @property {function (Args)} The function called to execute this command. */
this.action = action;
/** @property {string} This command's argument count spec. @see Commands#parseArguments */
this.argCount = extraInfo.argCount || 0;
/** @property {function (CompletionContext, Args)} This command's completer. @see CompletionContext */
this.completer = extraInfo.completer || null;
/**
* @property {function (Args)} The function called to execute this command.
*/
this.action = action;
/**
* @property {string} This command's argument count spec.
* @see Commands#parseArguments
*/
this.argCount = extraInfo.argCount || 0;
/**
* @property {function (CompletionContext, Args)} This command's completer.
* @see CompletionContext
*/
this.completer = extraInfo.completer || null;
/** @property {boolean} Whether this command accepts a here document. */
this.hereDoc = extraInfo.hereDoc || false;
/** @property {Array} The options this command takes. @see Commands@parseArguments */
this.options = extraInfo.options || [];
/** @property {boolean} Whether this command may be called with a bang, e.g., :com! */
this.bang = extraInfo.bang || false;
/** @property {boolean} Whether this command may be called with a count, e.g., :12bdel */
this.count = extraInfo.count || false;
this.hereDoc = extraInfo.hereDoc || false;
/**
* @property {boolean} At what index this command's literal
* arguments begin. For instance, with a value of 2, all arguments
* starting with the third are parsed as a single string, with all
* quoting characters passed literally. This is especially useful for
* commands which take key mappings or Ex command lines as
* arguments.
* @property {Array} The options this command takes.
* @see Commands@parseArguments
*/
this.literal = extraInfo.literal == null ? null : extraInfo.literal;
this.options = extraInfo.options || [];
/**
* @property {function} Should return an array of <b>Object</b>s
* suitable to be passed to {@link Commands#commandToString}, one
* for each past invocation which should be restored on subsequent
* @liberator startups.
* @property {boolean} Whether this command may be called with a bang,
* e.g., :com!
*/
this.serial = extraInfo.serial;
this.bang = extraInfo.bang || false;
/**
* @property {boolean} Whether this command may be called with a count,
* e.g., :12bdel
*/
this.count = extraInfo.count || false;
/**
* @property {boolean} At what index this command's literal arguments
* begin. For instance, with a value of 2, all arguments starting with
* the third are parsed as a single string, with all quoting characters
* passed literally. This is especially useful for commands which take
* key mappings or Ex command lines as arguments.
*/
this.literal = extraInfo.literal == null ? null : extraInfo.literal;
/**
* @property {function} Should return an array of <b>Object</b>s suitable
* to be passed to {@link Commands#commandToString}, one for each past
* invocation which should be restored on subsequent @liberator
* startups.
*/
this.serial = extraInfo.serial;
/**
* @property {boolean} Specifies whether this is a user command.
* User commands may be created by plugins, or directly by users,
* and, unlike basic commands, may be overwritten. Users and
* plugin authors should create only user commands.
* @property {boolean} Specifies whether this is a user command. User
* commands may be created by plugins, or directly by users, and,
* unlike basic commands, may be overwritten. Users and plugin authors
* should create only user commands.
*/
this.isUserCommand = extraInfo.isUserCommand || false;
this.isUserCommand = extraInfo.isUserCommand || false;
/**
* @property {string} For commands defined via :command, contains
* the Ex command line to be executed upon invocation.
* @property {string} For commands defined via :command, contains the Ex
* command line to be executed upon invocation.
*/
this.replacementText = extraInfo.replacementText || null;
};
}
Command.prototype = {
@@ -286,6 +307,66 @@ function Commands() //{{{
ArgType("list", function (arg) arg && arg.split(/\s*,\s*/))
];
// returns [count, parsed_argument]
function parseArg(str)
{
let arg = "";
let quote = null;
let len = str.length;
while (str.length && !/^\s/.test(str))
{
let res;
switch (QUOTE_STYLE)
{
case "vim-sucks":
if (res = str.match = str.match(/^()((?:[^\\\s]|\\.)+)((?:\\$)?)/))
arg += res[2].replace(/\\(.)/g, "$1");
break;
case "vimperator":
if (res = str.match(/^()((?:[^\\\s"']|\\.)+)((?:\\$)?)/))
arg += res[2].replace(/\\(.)/g, "$1");
else if (res = str.match(/^(")((?:[^\\"]|\\.)*)("?)/))
arg += eval(res[0] + (res[3] ? "" : '"'));
else if (res = str.match(/^(')((?:[^\\']|\\.)*)('?)/))
arg += res[2].replace(/\\(.)/g, function (n0, n1) /[\\']/.test(n1) ? n1 : n0);
break;
case "rc-ish":
if (res = str.match = str.match(/^()((?:[^\\\s"']|\\.)+)((?:\\$)?)/))
arg += res[2].replace(/\\(.)/g, "$1");
else if (res = str.match(/^(")((?:[^\\"]|\\.)*)("?)/))
arg += eval(res[0] + (res[3] ? "" : '"'));
else if (res = str.match(/^(')((?:[^']|'')*)('?)/))
arg += res[2].replace("''", "'", "g");
break;
case "pythonesque":
if (res = str.match = str.match(/^()((?:[^\\\s"']|\\.)+)((?:\\$)?)/))
arg += res[2].replace(/\\(.)/g, "$1");
else if (res = str.match(/^(""")((?:.?.?[^"])*)((?:""")?)/))
arg += res[2];
else if (res = str.match(/^(")((?:[^\\"]|\\.)*)("?)/))
arg += eval(res[0] + (res[3] ? "" : '"'));
else if (res = str.match(/^(')((?:[^\\']|\\.)*)('?)/))
arg += res[2].replace(/\\(.)/g, function (n0, n1) /[\\']/.test(n1) ? n1 : n0);
break;
}
if (!res)
break;
if (!res[3])
quote = res[1];
if (!res[1])
quote = res[3];
str = str.substr(res[0].length);
}
return [len - str.length, arg, quote];
}
function addCommand(command, isUserCommand, replace)
{
if (!command) // XXX
@@ -321,29 +402,93 @@ function Commands() //{{{
const self = {
// FIXME: remove later, when our option handler is better
OPTION_ANY: 0, // can be given no argument or an argument of any type,
// caller is responsible for parsing the return value
OPTION_NOARG: 1,
OPTION_BOOL: 2,
/**
* @property The option argument is unspecified. Any argument is
* accepted and caller is responsible for parsing the return value.
* @final
*/
OPTION_ANY: 0,
/**
* @property The option doesn't accept an argument.
* @final
*/
OPTION_NOARG: 1,
/**
* @property The option accepts a boolean argument.
* @final
*/
OPTION_BOOL: 2,
/**
* @property The option accepts a string argument.
* @final
*/
OPTION_STRING: 3,
OPTION_INT: 4,
OPTION_FLOAT: 5,
OPTION_LIST: 6,
/**
* @property The option accepts an integer argument.
* @final
*/
OPTION_INT: 4,
/**
* @property The option accepts a float argument.
* @final
*/
OPTION_FLOAT: 5,
/**
* @property The option accepts a string list argument. E.g. "foo,bar"
* @final
*/
OPTION_LIST: 6,
/**
* @property Indicates that no count was specified for this command
* invocation.
* @final
*/
COUNT_NONE: -1,
COUNT_ALL: -2, // :%...
/**
* @property Indicates that the full buffer range (1,$) was specified
* for this command invocation.
* @final
*/
// FIXME: this isn't a count at all
COUNT_ALL: -2, // :%...
/** @property {Iterator(Command)} @private */
__iterator__: function ()
{
let sorted = exCommands.sort(function (a, b) a.name > b.name);
return util.Array.itervalues(sorted);
},
/**
* Adds a new default command.
*
* @param {string[]} names The names by which this command can be
* invoked. The first name specified is the command's canonical
* name.
* @param {string} description A description of the command.
* @param {function} action The action invoked by this command.
* @param {Object} extra An optional extra configuration hash.
* @optional
*/
add: function (names, description, action, extra)
{
return addCommand(new Command(names, description, action, extra), false, false);
},
/**
* Adds a new user-defined command.
*
* @param {string[]} names The names by which this command can be
* invoked. The first name specified is the command's canonical
* name.
* @param {string} description A description of the command.
* @param {function} action The action invoked by this command.
* @param {Object} extra An optional extra configuration hash.
* @param {boolean} replace Overwrite an existing command with the same
* canonical name.
*/
addUserCommand: function (names, description, action, extra, replace)
{
extra = extra || {};
@@ -353,6 +498,13 @@ function Commands() //{{{
return addCommand(new Command(names, description, action, extra), true, replace);
},
/**
* Returns the specified command invocation object serialized to
* an executable Ex command string.
*
* @param {Object} args The command invocation object.
* @returns {string}
*/
commandToString: function (args)
{
let res = [args.command + (args.bang ? "!" : "")];
@@ -373,111 +525,96 @@ function Commands() //{{{
return res.join(" ");
},
/**
* Returns the command with matching <b>name</b>.
*
* @param {string} name The name of the command to return. This can be
* any of the command's names.
* @returns {Command}
*/
get: function (name)
{
return exCommands.filter(function (cmd) cmd.hasName(name))[0] || null;
},
/**
* Returns the user-defined command with matching <b>name</b>.
*
* @param {string} name The name of the command to return. This can be
* any of the command's names.
* @returns {Command}
*/
getUserCommand: function (name)
{
return exCommands.filter(function (cmd) cmd.isUserCommand && cmd.hasName(name))[0] || null;
},
/**
* Returns all user-defined commands.
*
* @returns {Command[]}
*/
getUserCommands: function ()
{
return exCommands.filter(function (cmd) cmd.isUserCommand);
},
// returns [count, parsed_argument]
parseArg: function parseArg(str)
{
let arg = "";
let quote = null;
let len = str.length;
while (str.length && !/^\s/.test(str))
{
let res;
switch (QUOTE_STYLE)
{
case "vim-sucks":
if (res = str.match = str.match(/^()((?:[^\\\s]|\\.)+)((?:\\$)?)/))
arg += res[2].replace(/\\(.)/g, "$1");
break;
case "vimperator":
if (res = str.match(/^()((?:[^\\\s"']|\\.)+)((?:\\$)?)/))
arg += res[2].replace(/\\(.)/g, "$1");
else if (res = str.match(/^(")((?:[^\\"]|\\.)*)("?)/))
arg += eval(res[0] + (res[3] ? "" : '"'));
else if (res = str.match(/^(')((?:[^\\']|\\.)*)('?)/))
arg += res[2].replace(/\\(.)/g, function (n0, n1) /[\\']/.test(n1) ? n1 : n0);
break;
case "rc-ish":
if (res = str.match = str.match(/^()((?:[^\\\s"']|\\.)+)((?:\\$)?)/))
arg += res[2].replace(/\\(.)/g, "$1");
else if (res = str.match(/^(")((?:[^\\"]|\\.)*)("?)/))
arg += eval(res[0] + (res[3] ? "" : '"'));
else if (res = str.match(/^(')((?:[^']|'')*)('?)/))
arg += res[2].replace("''", "'", "g");
break;
case "pythonesque":
if (res = str.match = str.match(/^()((?:[^\\\s"']|\\.)+)((?:\\$)?)/))
arg += res[2].replace(/\\(.)/g, "$1");
else if (res = str.match(/^(""")((?:.?.?[^"])*)((?:""")?)/))
arg += res[2];
else if (res = str.match(/^(")((?:[^\\"]|\\.)*)("?)/))
arg += eval(res[0] + (res[3] ? "" : '"'));
else if (res = str.match(/^(')((?:[^\\']|\\.)*)('?)/))
arg += res[2].replace(/\\(.)/g, function (n0, n1) /[\\']/.test(n1) ? n1 : n0);
break;
}
if (!res)
break;
if (!res[3])
quote = res[1];
if (!res[1])
quote = res[3];
str = str.substr(res[0].length);
}
return [len - str.length, arg, quote];
},
// in '-quoted strings, only ' and \ itself are escaped
// in "-quoted strings, also ", \n and \t are translated
// in non-quoted strings everything is taken literally apart from "\ " and "\\"
//
// @param str: something like "-x=foo -opt=bar arg1 arg2"
// "options" is an array [name, type, validator, completions] and could look like:
// options = [[["-force"], OPTION_NOARG],
// [["-fullscreen", "-f"], OPTION_BOOL],
// [["-language"], OPTION_STRING, validateFunc, ["perl", "ruby"]],
// [["-speed"], OPTION_INT],
// [["-acceleration"], OPTION_FLOAT],
// [["-accessories"], OPTION_LIST, null, ["foo", "bar"]],
// [["-other"], OPTION_ANY]];
// @param argCount can be:
// "0": no arguments
// "1": exactly one argument
// "+": one or more arguments
// "*": zero or more arguments (default if unspecified)
// "?": zero or one arguments
// @param allowUnknownOptions: -foo won't result in an error, if -foo isn't
// specified in "options"
// TODO: should it handle comments?
// : it might be nice to be able to specify that certain quoting
// should be disabled E.g. backslash without having to resort to
// using literal etc
// using literal etc.
// : I'm not sure documenting the returned object here, and
// elsewhere, as type Args rather than simply Object makes sense,
// especially since it is further augmented for use in
// Command#action etc.
/**
* Parses <b>str</b> for options and plain arguments.
*
* The returned <b>Args</b> object is an augmented array of arguments.
* Any key/value pairs of <b>extra</b> will be available and the
* following additional properties:
* -opt - the value of the option -opt if specified
* string - the original argument string <b>str</b>
* literalArg - any trailing literal argument
*
* Quoting rules:
* '-quoted strings - only ' and \ itself are escaped
* "-quoted strings - also ", \n and \t are translated
* non-quoted strings - everything is taken literally apart from "\
* " and "\\"
*
* @param {string} str The Ex command-line string to parse. E.g.
* "-x=foo -opt=bar arg1 arg2"
* @param {Array} options The options accepted. These are specified as
* an array [name, type, validator, completions]. E.g.
* options = [[["-force"], OPTION_NOARG],
* [["-fullscreen", "-f"], OPTION_BOOL],
* [["-language"], OPTION_STRING, validateFunc, ["perl", "ruby"]],
* [["-speed"], OPTION_INT],
* [["-acceleration"], OPTION_FLOAT],
* [["-accessories"], OPTION_LIST, null, ["foo", "bar"]],
* [["-other"], OPTION_ANY]];
* @param {string} argCount The number of arguments accepted.
* "0": no arguments
* "1": exactly one argument
* "+": one or more arguments
* "*": zero or more arguments (default if unspecified)
* "?": zero or one arguments
* @param {boolean} allowUnknownOptions Whether unspecified options
* should cause an error.
* @param {number} literal The index at which any literal arg begins.
* See {@link Command#literal}.
* @param {CompletionContext} complete The relevant completion context
* when the args are being parsed for completion.
* @param {Object} extra Extra keys to be spliced into the returned
* Args object.
* @returns {Args}
*/
parseArgs: function (str, options, argCount, allowUnknownOptions, literal, complete, extra)
{
function getNextArg(str)
{
let [count, arg, quote] = commands.parseArg(str);
let [count, arg, quote] = parseArg(str);
if (quote == "\\" && !complete)
return [,,,"Trailing \\"];
if (quote && !complete)
@@ -737,6 +874,21 @@ function Commands() //{{{
return args;
},
/**
* Parses a complete Ex command.
*
* The parsed string is returned as an Array like
* [count, command, bang, args]:
* count - any count specified
* command - the Ex command name
* bang - whether the special "bang" version was called
* args - the commands full argument string
* E.g. ":2foo! bar" -> [2, "foo", true, "bar"]
*
* @param {string} str The Ex command line string.
* @returns {Array}
*/
// FIXME: why does this return an Array rather than Object?
parseCommand: function (str)
{
// remove comments
@@ -759,16 +911,37 @@ function Commands() //{{{
return [count, cmd, !!special, args || ""];
},
get complQuote() complQuote,
/** @property @private */
get complQuote() complQuote, // XXX: needed?
get quoteArg() quoteArg,
/** @property @private */
get quoteArg() quoteArg, // XXX: needed?
/**
* Remove the user-defined command with matching <b>name</b>.
*
* @param {string} name The name of the command to remove. This can be
* any of the command's names.
*/
removeUserCommand: function (name)
{
exCommands = exCommands.filter(function (cmd) !(cmd.isUserCommand && cmd.hasName(name)));
},
// FIXME: still belong here? Also used for autocommand parameters
// FIXME: still belong here? Also used for autocommand parameters.
/**
* Returns a string with all tokens in <b>string</b> matching "<key>"
* replaced with "value". Where "key" is a property of the specified
* <b>tokens</b> object and "value" is the corresponding value. The
* <lt> token can be used to include a literal "<" in the returned
* string. Any tokens prefixed with "q-" will be quoted except for
* <q-lt> which is treated like <lt>.
*
* @param {string} str The string with tokens to replace.
* @param {Object} tokens A map object whose keys are replaced with its
* values.
* @returns {string}
*/
replaceTokens: function replaceTokens(str, tokens)
{
return str.replace(/<((?:q-)?)([a-zA-Z]+)?>/g, function (match, quote, token)

18
common/content/editor.js
View File

@@ -1062,7 +1062,8 @@ function Editor() //{{{
/**
* Expands an abbreviation in the currently active textbox.
*
* @param {string} filter The mode filter. (@see #addAbbreviation)
* @param {string} filter The mode filter.
* @see #addAbbreviation
*/
expandAbbreviation: function (filter)
{
@@ -1099,10 +1100,10 @@ function Editor() //{{{
/**
* Returns all abbreviations matching <b>filter</b> and <b>lhs</b>.
*
* @param {string} filter The mode filter. (@see #addAbbreviation)
* @param {string} filter The mode filter.
* @param {string} lhs The LHS of the abbreviation.
* (@see #addAbbreviation)
* @returns {Array} The matching abbreviations [mode, lhs, rhs]
* @see #addAbbreviation
*/
getAbbreviations: function (filter, lhs)
{
@@ -1115,9 +1116,9 @@ function Editor() //{{{
/**
* Lists all abbreviations matching <b>filter</b> and <b>lhs</b>.
*
* @param {string} filter The mode filter. (@see #addAbbreviation)
* @param {string} filter The mode filter.
* @param {string} lhs The LHS of the abbreviation.
* (@see #addAbbreviation)
* @see #addAbbreviation
*/
listAbbreviations: function (filter, lhs)
{
@@ -1143,9 +1144,9 @@ function Editor() //{{{
/**
* Deletes all abbreviations matching <b>filter</b> and <b>lhs</b>.
*
* @param {string} filter The mode filter. (@see #addAbbreviation)
* @param {string} filter The mode filter.
* @param {string} lhs The LHS of the abbreviation.
* (@see #addAbbreviation)
* @see #addAbbreviation
*/
removeAbbreviation: function (filter, lhs)
{
@@ -1196,7 +1197,8 @@ function Editor() //{{{
/**
* Removes all abbreviations matching <b>filter</b>.
*
* @param {string} filter The mode filter. (@see #addAbbreviation)
* @param {string} filter The mode filter.
* @see #addAbbreviation
*/
removeAllAbbreviations: function (filter)
{

14
common/content/hints.js
View File

@@ -136,9 +136,9 @@ function Hints() //{{{
* If it finds a hint it returns it, if the hint is not the caption of the
* element it will return showtext=true.
*
* @param {object} elem The element.
* @param {Object} elem The element.
* @param {string} tagname Its tagname.
* @param {doc} The document it is in.
* @param {Document} doc The document it is in.
*
* @returns [text, showtext]
*/
@@ -201,9 +201,9 @@ function Hints() //{{{
*
* Only called by generate()
*
* @param {object} elem The <area> element.
* @param {Number} leftpos The left offset of the image.
* @param {Number} toppos The top offset of the image.
* @param {Object} elem The <area> element.
* @param {number} leftpos The left offset of the image.
* @param {number} toppos The top offset of the image.
* @returns [leftpos, toppos] The updated offsets.
*/
function getAreaOffset(elem, leftpos, toppos)
@@ -274,7 +274,7 @@ function Hints() //{{{
*
* Pushes the hints into the pageHints object, but does not display them.
*
* @param {object} win The window,defaults to window.content
* @param {Window} win The window,defaults to window.content
*/
function generate(win)
{
@@ -368,7 +368,7 @@ function Hints() //{{{
/**
* Toggle the highlight of a hint.
*
* @param {object} elem The element to toggle.
* @param {Object} elem The element to toggle.
* @param {boolean} active Whether it is the currently active hint or not.
*/
function setClass(elem, active)

1
common/content/liberator.js
View File

@@ -633,7 +633,6 @@ const liberator = (function () //{{{
// "complete"
// TODO: "zoom": if the zoom value of the current buffer changed
// TODO: move to ui.js?
// Yes --djk
registerCallback: function (type, mode, func)
{
if (!(type in callbacks))

24
common/content/mappings.js
View File

@@ -41,10 +41,11 @@ the terms of any one of the MPL, the GPL or the LGPL.
* @param {function} action The action invoked by each key sequence.
* @param {Object} extraInfo An optional extra configuration hash. The
* following properties are supported.
* flags - See (@link Map#flags)
* noremap - See (@link Map#noremap)
* rhs - See (@link Map#rhs)
* silent - See (@link Map#silent)
* flags - see {@link Map#flags}
* noremap - see {@link Map#noremap}
* rhs - see {@link Map#rhs}
* silent - see {@link Map#silent}
* @optional
* @private
*/
function Map(modes, keys, description, action, extraInfo) //{{{
@@ -59,7 +60,8 @@ function Map(modes, keys, description, action, extraInfo) //{{{
/** @property {function (number)} The function called to execute this mapping. */
this.action = action;
/** @property {number} See (@link Mappings#flags) */
/** @property {number} @see Mappings#flags */
// FIXME: flags is incongruent with the other properties
this.flags = extraInfo.flags || 0;
/** @property {string} This mapping's description, as shown in :viusage. */
this.description = description || "";
@@ -69,7 +71,7 @@ function Map(modes, keys, description, action, extraInfo) //{{{
this.noremap = extraInfo.noremap || false;
/** @property {boolean} Whether any output from the mapping should be echoed on the command line. */
this.silent = extraInfo.silent || false;
};
}
Map.prototype = {
@@ -329,6 +331,7 @@ function Mappings() //{{{
return {
// NOTE: just normal mode for now
/** @property {Iterator(Map)} @private */
__iterator__: function () mappingsIterator([modes.NORMAL], main),
// used by :mkvimperatorrc to save mappings
@@ -342,7 +345,7 @@ function Mappings() //{{{
getUserIterator: function (mode) mappingsIterator(mode, user),
/**
* Add a new default key mapping.
* Adds a new default key mapping.
*
* @param {number[]} modes The modes that this mapping applies to.
* @param {string[]} keys The key sequences which are bound to
@@ -350,6 +353,7 @@ function Mappings() //{{{
* @param {string} description A description of the key mapping.
* @param {function} action The action invoked by each key sequence.
* @param {Object} extra An optional extra configuration hash.
* @optional
*/
add: function (modes, keys, description, action, extra)
{
@@ -357,14 +361,16 @@ function Mappings() //{{{
},
/**
* Add a new user-defined key mapping.
* Adds a new user-defined key mapping.
*
* @param {number[]} modes The modes that this mapping applies to.
* @param {string[]} keys The key sequences which are bound to
* <b>action</b>.
* @param {string} description A description of the key mapping.
* @param {function} action The action invoked by each key sequence.
* @param {Object} extra An optional extra configuration hash.
* @param {Object} extra An optional extra configuration hash (see
* {@link Map#extraInfo}).
* @optional
*/
addUserMap: function (modes, keys, description, action, extra)
{

281
common/content/options.js
View File

@@ -30,30 +30,92 @@ the terms of any one of the MPL, the GPL or the LGPL.
// do NOT create instances of this class yourself, use the helper method
// options.add() instead
/**
* A class representing configuration options. Instances are created by the
* {@link Options} class.
*
* @param {string[]} names The names by which this option is identified.
* @param {string} description A short one line description of the option.
* @param {string} type The option's value data type (see {@link Option#type}).
* @param {string} defaultValue The default value for this option.
* @param {Object} extraInfo An optional extra configuration hash. The
* following properties are supported.
* scope - see {@link Option#scope}
* setter - see {@link Option#setter}
* getter - see {@link Option#getter}
* completer - see {@link Option#completer}
* valdator - see {@link Option#validator}
* checkHas - see {@link Option#checkHas}
* @optional
* @private
*/
function Option(names, description, type, defaultValue, extraInfo) //{{{
{
if (!extraInfo)
extraInfo = {};
/** @property {string} The option's canonical name. */
this.name = names[0];
/** @property {string[]} All names by which this option is identified. */
this.names = names;
/**
* @property {string} The option's data type. One of:
* "boolean" - Boolean E.g. true
* "number" - Integer E.g. 1
* "string" - String E.g. "Vimperator"
* "charlist" - Character list E.g. "rb"
* "stringlist" - String list E.g. "homepage,quickmark,tabopen,paste"
*/
this.type = type;
this.scope = (extraInfo.scope & options.OPTION_SCOPE_BOTH) ||
options.OPTION_SCOPE_GLOBAL;
// XXX set to BOTH by default someday? - kstep
/**
* @property {number} The scope of the option. This can be local, global,
* or both.
* @see Options#OPTION_SCOPE_LOCAL
* @see Options#OPTION_SCOPE_GLOBAL
* @see Options#OPTION_SCOPE_BOTH
*/
this.scope = (extraInfo.scope & options.OPTION_SCOPE_BOTH) || options.OPTION_SCOPE_GLOBAL; // XXX set to BOTH by default someday? - kstep
/**
* @property {string} This option's description, as shown in :optionusage.
*/
this.description = description || "";
// "", 0 are valid default values
this.defaultValue = (defaultValue === undefined) ? null : defaultValue;
/**
* @property {value} The option's default value. This value will be used
* unless the option is explicitly set either interactively or in an RC
* file or plugin.
*/
this.defaultValue = (defaultValue === undefined) ? null : defaultValue; // "", 0 are valid default values
/**
* @property {function} The function called when the option value is set.
*/
this.setter = extraInfo.setter || null;
/**
* @property {function} The function called when the option value is read.
*/
this.getter = extraInfo.getter || null;
/**
* @property {function(CompletionContext, Args)} This option's completer.
* @see CompletionContext
*/
this.completer = extraInfo.completer || null;
/**
* @property {function} The function called to validate the option's value
* when set.
*/
this.validator = extraInfo.validator || null;
/**
* @property The function called to determine whether the option already
* contains a specified value.
* @see #has
*/
this.checkHas = extraInfo.checkHas || null;
// this property is set to true whenever the option is first set
// useful to see whether it was changed by some rc file
/**
* @property {boolean} Set to true whenever the option is first set. This
* is useful to see whether it was changed from its default value
* interactively or by some RC file.
*/
this.hasChanged = false;
// add no{option} variant of boolean {option} to this.names
@@ -70,10 +132,20 @@ function Option(names, description, type, defaultValue, extraInfo) //{{{
if (this.globalvalue == undefined)
this.globalvalue = this.defaultValue;
}
Option.prototype = {
/** @property {value} The option's global value. @see #scope */
get globalvalue() options.store.get(this.name),
set globalvalue(val) { options.store.set(this.name, val); },
/**
* Returns <b>value</b> as an array of parsed values if the option type is
* "charlist" or "stringlist" or else unchanged.
*
* @param {value} value The option value.
* @returns {value|string[]}
*/
parseValues: function (value)
{
if (this.type == "stringlist")
@@ -83,6 +155,13 @@ Option.prototype = {
return value;
},
/**
* Returns <b>values</b> packed in the appropriate format for the option
* type.
*
* @param {value|string[]} values The option value.
* @returns {value}
*/
joinValues: function (values)
{
if (this.type == "stringlist")
@@ -92,16 +171,41 @@ Option.prototype = {
return values;
},
/** @property {value|string[]} The option value or array of values. */
get values() this.parseValues(this.value),
set values(values) this.setValues(values, this.scope),
/**
* Returns the option's value as an array of parsed values if the option
* type is "charlist" or "stringlist" or else the simple value.
*
* @param {number} scope The scope to return these values from (see
* {@link Option#scope}).
* @returns {value|string[]}
*/
getValues: function (scope) this.parseValues(this.get(scope)),
/**
* Sets the option's value from an array of values if the option type is
* "charlist" or "stringlist" or else the simple value.
*
* @param {number} scope The scope to apply these values to (see
* {@link Option#scope}).
*/
setValues: function (values, scope)
{
this.set(this.joinValues(values), scope || this.scope);
},
/**
* Returns the value of the option in the specified <b>scope</b>. The
* (@link Option#getter) callback, if it exists, is invoked with this value
* before it is returned.
*
* @param {number} scope The scope to return this value from (see
* {@link Option#scope}).
* @returns {value}
*/
get: function (scope)
{
if (scope)
@@ -127,6 +231,15 @@ Option.prototype = {
return aValue;
},
/**
* Sets the option value to <b>newValue</b> for the specified <b>scope</b>.
* The (@link Option#setter) callback, if it exists, is invoked with
* <b>newValue</b>.
*
* @param {value} newValue The option's new value.
* @param {number} scope The scope to apply this value to (see
* {@link Option#scope}).
*/
set: function (newValue, scope)
{
scope = scope || this.scope;
@@ -153,9 +266,19 @@ Option.prototype = {
this.hasChanged = true;
},
/**
* @property {value} The option's current value. The option's local value,
* or if no local value is set, this is equal to the (@link #globalvalue).
*/
get value() this.get(),
set value(val) this.set(val),
/**
* Returns whether the option value contains one or more of the specified
* arguments.
*
* @returns {boolean}
*/
has: function ()
{
let self = this;
@@ -167,8 +290,18 @@ Option.prototype = {
return Array.some(arguments, function (val) test(val));
},
/**
* Returns whether this option is identified by <b>name</b>.
*
* @param {string} name
* @returns {boolean}
*/
hasName: function (name) this.names.indexOf(name) >= 0,
/**
* Returns whether the specified <b>values</b> are valid for this option.
* @see Option#validator
*/
isValidValue: function (values)
{
if (this.validator)
@@ -177,11 +310,23 @@ Option.prototype = {
return true;
},
/**
* Resets the option to its default value.
*/
reset: function ()
{
this.value = this.defaultValue;
},
/**
* Sets the option's value using the specified set <b>operator</b>.
*
* @param {string} operator The set operator.
* @param {value|string[]} values The value (or values) to apply.
* @param {number} scope The scope to apply this value to (see
* {@link #scope}).
* @param {boolean} invert Whether this is an invert boolean operation.
*/
op: function (operator, values, scope, invert)
{
let newValue = null;
@@ -281,15 +426,23 @@ Option.prototype = {
this.setValues(newValue, scope);
}
};
// TODO: Run this by default?
// TODO: Run this by default?
/**
* Validates the specified <b>values</b> against values generated by the
* option's completer function.
*
* @param {value|string[]} values The value or array of values to validate.
* @returns {boolean}
*/
Option.validateCompleter = function (values)
{
liberator.log(values instanceof Array)
let context = CompletionContext("");
let res = context.fork("", 0, this, this.completer);
if (!res)
res = context.allItems.items.map(function (item) [item.text]);
return Array.concat(values).every(
function (value) res.some(function (item) item[0] == value));
return Array.concat(values).every(function (value) res.some(function (item) item[0] == value));
}; //}}}
/**
@@ -807,16 +960,33 @@ function Options() //{{{
const self = {
/**
* @property {number} Global option scope.
* @final
*/
OPTION_SCOPE_GLOBAL: 1,
OPTION_SCOPE_LOCAL: 2,
OPTION_SCOPE_BOTH: 3,
/**
* @property {number} Local option scope. Options in this scope only
* apply to the current tab/buffer.
* @final
*/
OPTION_SCOPE_LOCAL: 2,
/**
* @property {number} Both local and global option scope.
* @final
*/
OPTION_SCOPE_BOTH: 3,
/** @property {Iterator(Option)} @private */
__iterator__: function ()
{
let sorted = [o for ([i, o] in Iterator(optionHash))].sort(function (a, b) String.localeCompare(a.name, b.name));
return (v for ([k, v] in Iterator(sorted)));
},
/** @property {Object} Observes preference value changes. */
prefObserver: {
register: function ()
{
@@ -848,6 +1018,18 @@ function Options() //{{{
}
},
/**
* Adds a new option.
*
* @param {string[]} names All names for the option.
* @param {string} description A description of the option.
* @param {string} type The option type (see {@link Option#type}).
* @param {value} defaultValue The option's default value.
* @param {Object} extra An optional extra configuration hash (see
* {@link Map#extraInfo}).
* @optional
* @returns {boolean} Whether the option was created.
*/
add: function (names, description, type, defaultValue, extraInfo)
{
if (!extraInfo)
@@ -873,6 +1055,14 @@ function Options() //{{{
return true;
},
/**
* Returns the option with <b>name</b> in the specified <b>scope</b>.
*
* @param {string} name The option's name.
* @param {number} scope The option's scope (see {@link Option#scope}).
* @optional
* @returns {Option} The matching option.
*/
get: function (name, scope)
{
if (!scope)
@@ -890,6 +1080,15 @@ function Options() //{{{
return null;
},
/**
* Lists all options in <b>scope</b> or only those with changed values
* if <b>onlyNonDefault</b> is specified.
*
* @param {boolean} onlyNonDefault Limit the list to prefs with a
* non-default value.
* @param {number} scope Only list options in this scope (see
* {@link Option#scope}).
*/
list: function (onlyNonDefault, scope)
{
if (!scope)
@@ -929,6 +1128,16 @@ function Options() //{{{
commandline.echo(list, commandline.HL_NORMAL, commandline.FORCE_MULTILINE);
},
/**
* Lists all preferences matching <b>filter</b> or only those with
* changed values if <b>onlyNonDefault</b> is specified.
*
* @param {boolean} onlyNonDefault Limit the list to prefs with a
* non-default value.
* @param {string} filter The list filter. A null filter lists all
* prefs.
* @optional
*/
listPrefs: function (onlyNonDefault, filter)
{
if (!filter)
@@ -961,6 +1170,15 @@ function Options() //{{{
commandline.echo(list, commandline.HL_NORMAL, commandline.FORCE_MULTILINE);
},
/**
* Parses a :set command.
*
* @param {string} args The :set command's argument string.
* @param {Object} modifiers A hash of parsing modifiers. These are:
* scope - see {@link Option#scope}
* @optional
* @returns {Object} The parsed command object.
*/
parseOpt: function parseOpt(args, modifiers)
{
let ret = {};
@@ -1005,15 +1223,29 @@ function Options() //{{{
return ret;
},
/** @property {Object} The options store. */
get store() storage.options,
/**
* Returns the value of the preference <b>name</b>.
*
* @param {string} name The preference name.
* @param {value} forcedDefault The the default value for this
* preference. Used for internal liberator preferences.
*/
getPref: function (name, forcedDefault)
{
return loadPreference(name, forcedDefault);
},
// Set a pref, but warn the user if it's changed from its default
// value.
/**
* Sets the preference <b>name</b> to </b>value</b> but warns the user
* if the value is changed from its default.
*
* @param {string} name The preference name.
* @param {value} value The new preference value.
*/
// FIXME: Well it used to. I'm looking at you mst! --djk
safeSetPref: function (name, value)
{
let val = loadPreference(name, null, false);
@@ -1025,11 +1257,22 @@ function Options() //{{{
storePreference(SAVED + name, value);
},
/**
* Sets the preference <b>name</b> to </b>value</b>.
*
* @param {string} name The preference name.
* @param {value} value The new preference value.
*/
setPref: function (name, value)
{
storePreference(name, value);
},
/**
* Resets the preference <b>name</b> to its default value.
*
* @param {string} name The preference name.
*/
resetPref: function (name)
{
try
@@ -1042,7 +1285,11 @@ function Options() //{{{
}
},
// this works only for booleans
/**
* Toggles the value of the boolean preference <b>name</b>.
*
* @param {string} name The preference name.
*/
invertPref: function (name)
{
if (services.get("pref").getPrefType(name) == Ci.nsIPrefBranch.PREF_BOOL)
@@ -1079,7 +1326,7 @@ function Options() //{{{
* previous values.
*
* @param {function} fn The function to call.
* @param {object} fn The 'this' object with which to call <b>fn</b>
* @param {Object} fn The 'this' object with which to call <b>fn</b>
* @see #pushContext
* @see #popContext
*/

2
common/content/tabs.js
View File

@@ -1229,7 +1229,7 @@ function Tabs() //{{{
// shouldn't be one yet.
/**
* Called on each TabSelect event to update the tab selection history.
* See (@link tabs.alternate).
* @see tabs#alternate
*/
updateSelectionHistory: function ()
{

2
common/content/ui.js
View File

@@ -1220,7 +1220,7 @@ function CommandLine() //{{{
*
* @param {string} prompt The input prompt to use.
* @param {function(string)} callback
* @param {object} extra
* @param {Object} extra
* @... {function} onChange - A function to be called with the current
* input every time it changes.
* @... {function(CompletionContext)} completer - A completion function