Classes
Members
(static) TYPE_NAMES
This is exported just for documentation value. Do not modify it.
Methods
(static) acceptableCharacters(regex) → {string}
Get all ASCII characters that match the given regex.
Parameters:
| Name | Type | Description |
|---|---|---|
regex |
RegExp | Regular expression to match acceptable character(s) |
Returns:
containing of all ASCII characters that match
- Type
- string
(static) addStackToMessage(error, excludeCommonBaseopt) → {Error}
Add error's stack trace to its message.
If you call this function multiple times (regardless of what
Beware: Some special errors don't have a detailed stack trace. E.g. if you create a Proxy (as per https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) with a 'set' handler function that doesn't return a value (but it should return a boolean), then in Firefox 39a01 error.stack will only contain stack down to the line that set a field on the proxy, but it won't contain any stack from the handler function.
If you call this function multiple times (regardless of what
excludeCommonBase), any successive call will replace any stack added to the message in the previous call.
Beware: Some special errors don't have a detailed stack trace. E.g. if you create a Proxy (as per https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) with a 'set' handler function that doesn't return a value (but it should return a boolean), then in Firefox 39a01 error.stack will only contain stack down to the line that set a field on the proxy, but it won't contain any stack from the handler function.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
error |
Error | Error (with a modified message, if applicable). | ||
excludeCommonBase |
boolean |
<optional> |
false | Essentially, this makes it shorten the stack trace by removing parts that come from Firefox code. That makes the stack trace usually more relevant. excludeCommonBase indicates whether to exclude any stack trace (base) that is the same for error's stack and the current stack. This serves to eliminate upper call levels that are of little interest to the end user. If error was already processed by SeLiteMisc.addStackToMessage() with excludeCommonBase==true, then this function doesn't modify error at all (regardless of what excludeCommonBase is now). That previous call (which would normally be at a deeper level) indicated that the shorter stack trace is meaningful, so there is no need to replace it with a longer trace. However, if error was processed by call(s) to SeLiteMisc.addStackToMessage() only with excludeCommonBase being false or undefined, then the first call of SeLiteMisc.addStackToMessage() with excludeCommonBase replaces and shortens the stack trace that is in error.message. This function doesn't modify error.stack itself. |
Returns:
The same error object.
- Type
- Error
(static) asArray(arrayOrItemopt, encloseInArrayEvenIfUndefinedopt) → {Array}
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
arrayOrItem |
object | Array |
<optional> |
|
encloseInArrayEvenIfUndefined |
boolean |
<optional> |
Returns:
arrayOrItem if it's an array; [arrayOrItem] if arrayOrItem is defined but not an array, or it's undefined but encloseInArrayEvenIfUndefined is true; an empty array otherwise.
- Type
- Array
(static) cascadeField(object, fieldNameDotEtc, doNotThrowopt, valueInsteadOfThrowopt) → {object}
It serves to access (potentially deeper) fields of objects. Used e.g. when dynamically accessing user-provided class (for its given name), which may be a sub(sub...)field of a namespace object (i.e. having dots in the name). See also SeLiteMisc.cascadeFieldEntries().
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
object |
object | |||
fieldNameDotEtc |
string | See the same parameter in SeLiteMisc.cascadeFieldEntries(). | ||
doNotThrow |
boolean |
<optional> |
false | See the same parameter in SeLiteMisc.cascadeFieldEntries(). |
valueInsteadOfThrow |
* |
<optional> |
See the same parameter in SeLiteMisc.cascadeFieldEntries(). |
Throws:
See SeLiteMisc.cascadeFieldEntries().
Returns:
keys: [string]
value: (sub...)field of object; undefined if no such field(s) and if doNotThrow equals to true.
- Type
- object
(static) cascadeFieldEntries(object, fieldNameDotEtc, doNotThrowopt, valueInsteadOfThrowopt) → {Array|undefined}
It serves to access (potentially deeper) fields of objects, collecting all entries on the way. Used e.g. when dynamically accessing user-provided class (for its given name), which may be a sub(sub...)field of a namespace object (i.e. having dots in the name).
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
object |
object | |||
fieldNameDotEtc |
string | Field name, or multiple field names separated by dot. | ||
doNotThrow |
boolean |
<optional> |
false | If true then it throws any appropriate errors (e.g. when object is not an object, or fieldNameDotEtc contains dot(s) but some intermediate objects are not present). |
valueInsteadOfThrow |
* |
<optional> |
What to return if a field is an intermediary entry (when evaluating the breadcrumb path) is null/undefined. |
Throws:
If there are no such field(s); not thrown if you set doNotThrow
Returns:
[field1Value, field2Value...]; valueInsteadOfThrow if no such field(s) and if doNotThrow equals to true.
- Type
- Array | undefined
(static) catchAllFunctions()
For use with '*' catch-all declaration through SeLiteMisc.proxyVerifyFields(), to allow any functions to be defined, but not redefined.
(static) classNameOf(objectOrConstructor)
Parameters:
| Name | Type | Description |
|---|---|---|
objectOrConstructor |
object | function | An object (instance), or a constructor of a class (a function). |
Returns:
string Either class name (constructor method name), or 'null', or a meaningful short message.
(static) collectByColumn(records, fieldNames, valuesUnique, result) → {Object}
This collects entries (objects) - from an array (or an object serving as an associative array) of objects (serving as associative arrays), indexed by value(s) of given field/column name(s) in those objects.
It returns those entries indexed by value of that given column/field, which becomes a key in the result
array/matrix. If indicated that the
chosen column (field) values may not be unique, then it returns the entries (objects/row) within
an extra enclosing array, one per each key value - even if there is just one object/row for any key value.
Parameters:
| Name | Type | Description |
|---|---|---|
records |
array | of objects or an object (serving as an associative array) of objects (or of arrays of objects); it can be a result of SeLite DB Objects - select() or a previous result of SeLiteMisc.collectByColumn(). Therefore any actual values must not be arrays themselves, because then you and existing consumers of result from this function couldn't tell them from the subindexed arrays. |
fieldNames |
array | string | String name of the index key or object field, or function to retrieve a field off an object, that we'll index by; or an array of them. If it's a function or an array containing function(s) then such function accepts one argument which is the object to be sub-indexed. |
valuesUnique |
boolean | whether the compound index (based on given fieldNames) is guaranteed to have unique values. Otherwise it generates an array for each (set of index) value(s) present. If valuesUnique is true but there are multiple records with the same (set of) index value(s), then only the last record (for any compound index - breadcrumb of index/field values) will be kept here. |
result |
Object | The result object, see description of the return value; optional - if not present, then a new anonymous object is used. Don't use the same object for records and result. |
Returns:
An object serving as an associative array of various structure and depth, depending on the parameters.
In the following, 'entry' means an original entry from records.
If valuesUnique==true:
object {
compound index value => entry
...
}
If v has one entry and valuesUnique==false:
object {
compound index value => Array( entry... )
...
}
The result can't be an array, because Javascript arrays must have consecutive
non-negative integer index range. General data doesn't fit that.
Users must not depend on compound index value, since its calculation may change in future. Users can get the compound index value from SeLiteMisc.compoundIndexValue().
- Type
- Object
(static) collectByColumnFromDeep(records, fieldNameDotEtcByLevel, depth, doNotThrowopt, resultopt) → {Object}
Collect deep entries from an object tree. It alternates: it collects any entries directly under given 'records' object; for each entry it evaluates its sub(sub...) field according to given fieldNameDotEtcByLevel[0]. If there's more levels in fieldNameDotEtcByLevel[], it repeats the process.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
records |
object | Array | { key: { // 1:N fieldNameDotEtcByLevel[0]'s first breadcrumb: { fieldNameDotEtcByLevel[0]'s second breadcrumb (if any): { ...: { // 1:1 deeperKey: { // 1:N fieldNameDotEtcByLevel[1]'s first breadcrumb: { ...: { // 1:1 fieldNameDotEtcByLevel[N]'s last breadcrumb: target of any type or deeper object } } }, anotherDeeperKey:... } }, } anotherKey: { ... } } | ||
fieldNameDotEtcByLevel |
Array | string | A (non-empty) array of field names or dot-separated field names (each entry in the array being a breadcrumb-like path), or a (non-empty) string: a field name or dot-separated field names. For any breadcrumbs that contain two or more field names, the result will contain subindexes based on the values of those breadcrumb fields (except for the last field) at each level. | ||
depth |
number | 1-based depth down to which this is collecting. If more than 1, then fieldNameDotEtcByLevel[ 0..depth-1 ] are skipped (they're processed at the higher level). | ||
doNotThrow |
boolean |
<optional> |
false | If true then it throws any appropriate errors (e.g. when object is not an object, or fieldNameDotEtc contains dot(s) but some intermediate objects are not present). |
result |
object |
<optional> |
The result object; if not provided, this creates a new one. |
Returns:
An object with deep entries from records, indexed by a compound key based on key, deeperKey etc. from each level (but not indexed by the breadcrumb path values).
Have fieldNameDotEtcByLevel with N levels [0..N-1]; then this returns {
topLevelKey-keyAfterFirstBreadcrumb-...-keyAfterN-2thBreadcrumb: target,
...
}
- Type
- Object
(static) collectByColumnRecord(fieldNames, result)
Internal only. Worker function called by SeLiteMisc.collectByColumn().
Parameters:
| Name | Type | Description |
|---|---|---|
fieldNames |
array | This is like the same named parameter of SeLiteMisc.collectByColumn(), but here it must be an array (of strings or functions). |
result |
object | Object (serving as an associative array) for results of indexing at the level of this function. |
(static) collectFromDepth(records, depth, resultopt, collectIndexesopt) → {Array}
Collect entries from 'records' object/array at given depth.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
records |
object | |||
depth |
number | The depth to collect from; non-negative. 0 means to collect items directly under records object. | ||
result |
Array |
<optional> |
Array to put the entries to. Otherwise this creates a new array. | |
collectIndexes |
boolean |
<optional> |
false | Whether to collect indexes (keys). Otherwise (and by default) this collect values. |
Returns:
The result array.
- Type
- Array
(static) compareAllFields(firstContainer, secondContainer, mixed, boolean)
Compare all fields of both given objects.
Parameters:
| Name | Type | Description |
|---|---|---|
firstContainer |
object (not a 'primitive' string) or array | |
secondContainer |
object (not a 'primitive' string) or array | |
mixed |
strictOrMethodName Bool or a string. Boolean false by default. - if true, it compares with strict operator === - if false, it compares using non-strict using == - if string, it's a name of a method (not the method itself) to call on each field, unless both are null (compared using strict ===) or unless first or second is not an object. If both objects are null, then they are deemed to be equal and the method is not called. | |
boolean |
throwOnDifference Whether to throw an error if different |
Returns:
boolean Whether both objects have same fields and their values
(static) compareAllFieldsOneWay(firstContainer, secondContainer, asArrayopt, strictopt, methodNameopt)
Compare whether all fields from firstContainer exist in secondContainer and are same. Throw an error if not.
See SeLiteMisc.compareAllFields().
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
firstContainer |
Array | object | |||
secondContainer |
Array | object | |||
asArray |
boolean |
<optional> |
false | |
strict |
boolean |
<optional> |
false | |
methodName |
string |
<optional> |
Throws:
If the containers are different (see description); otherwise the containers are equal.
Returns:
void
(static) compareAsNumbers(mixed, mixed)
Like SeLiteMisc.compareCaseInsensitively(), but for numbers.
Don't use first-second, because that can overrun integer type limits.
Parameters:
| Name | Type | Description |
|---|---|---|
mixed |
number or numeric string first | |
mixed |
number or numeric string second |
(static) compareCaseInsensitively() → {number}
- Source:
- To Do:
-
- DOC if we ever have SeLiteMisc.sortByKeys() again: You can pass this function SeLiteMisc.compareCaseInsensitively as a second parameter to SeLiteMisc.sortByKeys().
Returns:
A negative, 0 or positive number, depending on whether first is less
than, equal to or greater than second, in case insensitive dictionary order.
Use as a second parameter to array.sort().
This doesn't expects first and second to be string. That is true for object field names (keys),
even if they were declared using a number/boolean/false. Meaning
var o={ false:0, null:-1, 5: 5 }
for( var field in o ) { // typeof field is string. It's strictly equal to 'false' or 'null' or '5'
}
- Type
- number
(static) compareNatural()
A blend of SeLiteMisc.compareCaseInsensitively() and SeLiteMisc.compareAsNumbers().
Non-numeric strings are sorted case insensitively. Numbers are sorted among themselves. Numbers will be before non-numeric strings.
Returns:
a negative, 0 or positive number, depending on whether first is less
than, equal to or greater than second, in the order as described above.
(static) compoundIndexValue(record, fieldNames) → {string|number}
Generate a compound index value, which represents values of all fieldNames of record, as used by SeLiteMisc.collectByColumn(). If fieldNames contains one field name/function, then the result is a value of that field. Otherwise the result is implementation-specific - don't depend on its actual value.
Parameters:
| Name | Type | Description |
|---|---|---|
record |
object | |
fieldNames |
array | Array of strings - field names within given record. |
Returns:
Value of compound index, as used for keys of result of SeLiteMisc.collectByColumn(). Implementation-specific.
- Type
- string | number
(static) ensure(bool, string)
This asserts the condition to be true (compared non-strictly). If false, it fails with an error (containg the given message, if any).
It's not called assert(), so that it doesn't conflict with assert() defined by Selenium IDE.
Parameters:
| Name | Type | Description |
|---|---|---|
bool |
condition If false, then this fails. | |
string |
message Optional; see SeLiteMisc.fail(). Note that if you pass a non-constant expression
- e.g. concatenation of strings, a call to a function etc.,
it has to be evaluated before SeLiteMisc.ensure() is called, even if it's not used (i.e. if the condition is true).
Instead, you may want to chose to use:
condition || SeLiteMisc.fail( message expression );
instead. That evaluates message expression only if condition is not true.
On the other hand, if you have message ready anyway (e.g. a constant string or a value received as a parameter from a caller function),
then by using SeLiteMisc.ensure(..) you make your intention clearer. |
(static) ensureInstance(object, classes, variableNameopt, messageopt)
Validate that a parameter is an object and of a given class (or of one of given classes).
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
object |
Object | ||
classes |
Class (that is, a constructor function), or an array of them. | ||
variableName |
string |
<optional> |
See same parameter of ensureOneOf(). |
message |
string |
<optional> |
See same parameter of ensureOneOf(). |
- Source:
- See:
-
- SeLiteMisc.isInstance()
(static) ensureOneOf(item, choices, variableNameopt, messageopt)
It ensures that item is one of choices.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
item |
* | ||
choices |
array | ||
variableName |
string |
<optional> |
If other than undefined/null/false, then it should be name or description of the Javascript parameter that is being validated. If this function throws an error, the message will contain item, choices and variableName. |
message |
string |
<optional> |
Message for the error, if validation fails. Otherwise this generates a message containing item and choices. |
(static) ensureType(item, typeStringOrStrings, variableNameopt, messageopt)
Validates that typeof item is one of
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
item |
* | ||
typeStringOrStrings |
string | array | See same parameter of hasType(). | |
variableName |
string | function |
<optional> |
See same parameter of ensureOneOf(). Optional; however, if present then it has to contain a meaningful name/description (regardless of whether you provide parameter message or not). |
message |
string | function |
<optional> |
See same parameter of ensureOneOf(). |
(static) fail(errorOrMessageopt, excludeCommonBaseopt)
This throws the given error or a new error (containg the given message, if any). It also appends the stack trace to the message, which is useful since both Firefox Browser Console and Selenium IDE log don't report error stack trace. I do not log here to Browser Console, since that would polute logs when doing negative testing - when using try/catch to validate that incorrect invocation of functionality calls SeLiteMisc.fail().
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
errorOrMessage |
* |
<optional> |
An underlying Error, or a message for a new error. |
excludeCommonBase |
boolean |
<optional> |
See the same parameter of SeLiteMisc.addStackToMessage(). |
- Source:
- See:
(static) field(object, fieldName, defaultValue) → {*}
Used to streamline the code when accessing optional fields on objects that are a result of SeLiteMisc.proxyVerifyFieldsOnRead() or SeLiteMisc.proxyVerifyFields(). That's instead of object.fieldName || defaultValue, which fails for such objects.
Parameters:
| Name | Type | Description |
|---|---|---|
object |
object | |
fieldName |
string | |
defaultValue |
* |
Returns:
object[fieldName] if it's present (even if it equals to undefined); defaultValue otherwise
- Type
- *
(static) hasType(item, typeStringOrStrings, itemNameopt) → {boolean}
It finds out whether the item's type is one of the given type(s).
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
item |
* | ||
typeStringOrStrings |
string | array | string, one of: 'number', 'string', 'object', 'function', 'boolean', 'undefined' or meta-types 'null', 'some-object' or 'primitive'. 'some-object' stands for a non-null object; 'primitive' stands for number/string/boolean. | |
itemName |
string | function |
<optional> |
Name of the item, as it makes sense in the caller's scope (e.g. name of the variable passed as parameter 'item' down here); or a function that returns such a name. Only used for error reporting. |
Returns:
- Type
- boolean
(static) indexOfRecord(mixed, record)
Parameters:
| Name | Type | Description |
|---|---|---|
mixed |
recordSet A SeLiteData.RecordSet instance, or some other object serving as an associative array, potentially a result of SeLiteMisc.collectByColumn(), even if it used sub-indexing (but then the records must be instances of SeLiteData.Record - which is so by default; otherwise the subindexed groups (objects serving as associative arrays) couldn't be differentiated from target objects/records). | |
record |
object, record to search for. |
Returns:
int 0-based index of that record if found,-1 otherwise.
(static) isEmptyObject()
Throws:
Error if the parameter is not an object.
Returns:
true if the object is empty (no fields availabel to iterate through); false otherwise.
(static) isInstance(object, classes, variableNameopt, requireAnObjectopt)
Detect whether the given object is an instance of one of the given class(es). It works even if the object is an instance of one of Javascript 'global' classes ('objects') from a different Javascript code module, its class/constructor is different to this scope. That wouldn't work only if the other scope had a custom class/constructor with function name same as one of the global objects, which would be a bad practice, e.g.
var MyError= function Error() {... };
var myErrorInstance= new MyError();
SeLiteMisc.isInstance( myErrorInstance, Error ) returns true
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
object |
object | Object | ||
classes |
function | array | Class (that is, a constructor function), or its name, or an array of any number of one or the other. | ||
variableName |
string |
<optional> |
See same parameter of ensureOneOf(). Only used on failure, so that the error message is more meaningful. | |
requireAnObject |
boolean |
<optional> |
false | Whether it requires parameter object to be an object. If requireAnObject is true, but parameter object is not an object, then this throws an error. If requireAnObject is false and parameter object is not an object, then this returns false. Use for streamlining error messages. |
(static) item(mixed, mixed, Any)
Parameters:
| Name | Type | Description |
|---|---|---|
mixed |
Container - object or array | |
mixed |
Field - string field name, or integer/integer string index of the item | |
Any |
further parameters are treated as chained 'subfields' - useful for traversing deeper array/object/mixed structures |
Returns:
mixed The item. It returns an empty string if not found or if the actual item is null - that is benefitial
when using this function in parameters to Selenium actions (which fail if passing null).
(static) itemGeneric(array, mixed, mixed)
Internal use only. This serves like item(), but the container (object or array) and the field(s) are all in one array,
which is passed as the first parameter. Then come two optional parameters, which control handling
of missing values and null.
Parameters:
| Name | Type | Description |
|---|---|---|
array |
containerAndFields First item is the container (array or object, possibly multi-level). Second (and any further) items are optional; if present then they must be string or numbers or numeric strings, which are indexes to the respective level within the container. | |
mixed |
nullReplacement Value to return if the item is not present - i.e. the container doesn't contain given field/index, or a chained (sub...)subcontainer doesn't contain the field/index at its respective level. Optional; if not present, then null is returned. | |
mixed |
targetNullReplacement Value to return if the target item itself is present, but it's null. Optional; null by default. |
Returns:
mixed The item, as described
(static) itemOrNull()
Just like item(...), but nulls are not translated at all.
(static) loadVerifyScope(fileURL, initialScopeopt, initialScopeDefinitionsopt, charsetopt) → {object}
Load a given file in a 'verified' global scope. Such a scope requires any global variables to be declared first. The scope will contain 'SeLiteMisc' object and any entries from initialScope. The file has to declare any other global variables (other than functions) with SeLiteMisc.declareGlobals(). It allows 'unverified' functions declared/assigned once only. If you assign a function multiple times (e.g. you define a constructor and then you make a proxy of it), you need to declare it specifically.
If you'd like to control any functions in the file, then pass a definition for field '*' that is a function which always returns false.
If you'd like to control any functions in the file, then pass a definition for field '*' that is a function which always returns false.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
fileURL |
string | |||
initialScope |
object |
<optional> |
It's copied - so subsequent changes to initialScope have no effect. | |
initialScopeDefinitions |
object | array |
<optional> |
See parameter definitions of SeLiteMisc.proxyVerifyFields(). | |
charset |
string |
<optional> |
'UTF-8' |
Returns:
Scope, in which it loads the given file through _subScriptLoader.loadSubScript()_.
- Type
- object
(static) log() → {object}
Returns:
Log object for Selenium IDE 'Log' tab. Only valid for primary Selenium IDE instances (not for auxiliary instances - see http://selite.github.io/SeleniumIde).
- Type
- object
(static) loginManagerPassword(username, hostnameOrUseBaseURL, returnLoginInfoopt) → {string}
This retrieves a web form password for a user. It doesn't work with .htaccess/HTTP authentication,
but that can be retrieved too, see
https://developer.mozilla.org/En/Using_nsILoginManager
https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsILoginManager
https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsILoginInfo
https://developer.mozilla.org/En/Using_nsILoginManager
https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsILoginManager
https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsILoginInfo
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
username |
string | Case-sensitive username. | |
hostnameOrUseBaseURL |
mixed | String hostname in form 'https://server-name.some.domain'. It must contain http or https. It can contain the port (if not standard), but no trailing slash / neither any URI (path). Optional; if not present, then this uses the current website. If it's true (boolean), then the function uses Selenium IDE's "Base URL" field - which may be different to the test website (e.g. single-sign-on). @TODO Once/if https://github.com/SeleniumHQ/selenium/issues/1550 is fixed, I'd need to extract the protocol+host+port from Base URL here. | |
returnLoginInfo |
boolean |
<optional> |
Whether to return nsILoginInfo object (if any); otherwise (and by default) this returns a string password (if any). |
Returns:
password if found; undefined otherwise
- Type
- string
(static) nthRecord(mixed, int)
Parameters:
| Name | Type | Description |
|---|---|---|
mixed |
recordSet A SeLiteData.RecordSet instance or some other object serving as an associative array, potentially a result of SeLiteMisc.collectByColumn(), even if it used sub-indexing (but then the records must be instances of SeLiteData.Record - which is so by default; otherwise the subindexed groups (objects serving as associative arrays) couldn't be differentiated from target objects/records). | |
int |
position 0-based position of the value to return |
Throws:
Exception if position is negative, decimal or higher than the last available position
Returns:
object the leaf record
(static) numberOfRecords(mixed)
Parameters:
| Name | Type | Description |
|---|---|---|
mixed |
recordSet A SeLiteData.RecordSet instance, or some other object serving as an associative array, potentially a result of SeLiteMisc.collectByColumn(), even if it used sub-indexing (but then the records must be instances of SeLiteData.Record - which is so by default; otherwise the subindexed groups (objects serving as associative arrays) couldn't be differentiated from target objects/records). |
(static) objectClone(original, acceptableFieldsopt, requiredFieldsopt, resultopt, mixed)
This makes a shallow clone of a given object. If the original object had a prototype,
then this uses it, too - any fields of the protype won't be copied, but will be referenced.
The new object is based on a plain object {}, so if the original object was created
using a constructor function, the result object won't be; therefore operator instanceof
will return false for the result object.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
original |
Object | The original object. | |
acceptableFields |
array |
<optional> |
optional; if present, then it contains the only fields that will be copied (if present in original). If acceptableFields is not present/empty, then any fields are copied. |
requiredFields |
array |
<optional> |
Required fields; if any are missing, this fails. If this parameter is not provided, then no fields are required. |
result |
object |
<optional> |
Result object to use; if not provided, then it creates a new object. |
mixed |
requiredFields Array of fields that are required to exist in original (even though their value may be null). If requiredFields==='all' (as a string), then it will be set to be the same as acceptableFields See https://developer.mozilla.org/en/JavaScript/Reference/Operators/Operator_Precedence |
(static) objectCopyFields()
Copy all and any fields (iterable ones) from source object to target object.
If the same field exists in target object, it will be overwritten.
Returns:
object target
(static) objectDeleteFields()
This deletes all iterable fields from the given object.
Returns:
obj
(static) objectFillIn(target, keys, values, valuesFromProperObjectopt, dontSetMissingOnesopt) → {object}
This fills in fields from keys[] in target with values from values[]. It is not intended to work with fields that have numeric names.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
target |
object | ||
keys |
array | ||
values |
array | object | Either an array of values, in the same order as keys[]. Or an object serving as an associative array { key => value }. | |
valuesFromProperObject |
boolean |
<optional> |
This must be true if values is an object serving as an associative array, with fieldnames same as entries in keys[]. Then this essentially performs a clone of values into target. valuesFromProperObject must not be true if values is an array or an array-like object, with 'length' property and with all values at numeric indexes, starting from 0 (e.g. a result of keyword-like variable arguments, which can be passed from a body of a function). |
dontSetMissingOnes |
boolean |
<optional> |
If true, then this only sets field(s) that are present in values. It doesn't set any missing fields to undefined; this can be benefitial if target is a result of SeLiteMisc.proxyVerifyFieldsOnRead(...). If false (as is default), it sets any missing fields to undefined. |
Returns:
target
- Type
- object
(static) objectReverse()
Returns:
an anonymous object, which has all values from obj as keys, and their
respective original keys (field names) as values. If the same value is present for two or more
fields in the original object, then it will be mapped to name of one of those fields (unspecified).
If a value is not a string, it's appended to an empty string (i.e. its toString() will be used, or 'null').
(static) objectsMerge()
Returns:
an anonymous object, which has all fields from obj, and any
extra fields from overriden. If the same field is in both obj and overriden,
then the value from obj is used.
(static) objectToString(object, int, bool, array, array, bool)
Get a simple string representation of the given object/array. Used for debugging.
Parameters:
| Name | Type | Description |
|---|---|---|
object |
object to present | |
int |
recursionDepth How many deeper layers of objects/arrays to show details of; 0 by default (no deeper objects). | |
bool |
includeFunctions Whether to include functions; false by default. | |
array |
leafClassNames Names of classes (that would match [sub[sub...]]object.constructor.name) that are excluded from deeper recursive processing. Use 'Object' to exclude listing of fields of anonymous objects. E.g. ['MyBigClass', 'Object' ] will not list any fields of instances of MyBigClass or anonymous objects. Use '' for some internal Firefox/XUL/XPCOM? objects. | |
array |
higherObjects Optional; array of objects/arrays that are being processed by the direct/indirect caller of this function (i.e. recursive array/object reference). For internal use only - only set when this function calls itself recursively through objectFieldToString(). | |
bool |
includeNonEnumerable Whether to include non-enumerable fields; false by default. |
Returns:
string
(static) objectValues()
Returns:
mixed
- if asObject is false: Return an array containing values of all iterable fields in the given object.
Any values from obj occurring more than once (in obj) will be in the result array as many times.
- if asObject is true, return an anonymous object with those values being keys in the result object, mapped to a number
of occurrences of this value in the original object. Values of the original object are converted to strings by
appending them to an empty string. Indeed, values of different type may map to the same string.
(static) objectValueToField(object, mixed, bool)
Parameters:
| Name | Type | Description |
|---|---|---|
object |
obj Object to search the value in. | |
mixed |
value Value to search in the given object. | |
bool |
strict Whether to compare strictly (using ===); false by default. |
Returns:
string field name for the given value, or null. If there are several such
fields, this will return one of them (unspecified which one).
(static) proxyAllowFields(proxy, definitions, preventDefinitionOverrideopt)
Add definitions of field(s) to an existing proxy (either an object or a constructor/class), that has been created by SeLiteMisc.proxyVerifyFields() or by a constructor processed by SeLiteMisc.proxyVerifyFields().
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
proxy |
object | Either an object, or a constructor (a class), that is a proxy. | ||
definitions |
object | See the same parameter of SeLiteMisc.proxyVerifyFields(). | ||
preventDefinitionOverride |
boolean |
<optional> |
false | Whether to prevent override of any existing definition (inherited or own). |
Returns:
void
(static) proxyVerifyFields(target, givenObjectOrClassDefinitionsopt, prototypeDefinitionsopt, classInstanceDefinitionsopt)
Like SeLiteMisc.proxyVerifyFieldsOnRead(), but this creates a proxy that verifies fields on both read and write. If used with a constructor function (i.e. a class), it should define any fields added by that class, and any parent constructors should declare their own fields.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
target |
object | function | An object to be proxied, or a class (a constructor function). If it's a child class of a parent class that also went through SeLiteMisc.proxyVerifyFields(), then you must set the prototype of this child class *before* you call SeLiteMisc.proxyVerifyFields() on it. E.g.: function ChildClass(...) { ParentClass.call( this, ... ); } ChildClass.prototype= Object.create(ParentClass.prototype); ChildClass.prototype.constructor= ParentClass; ChildClass= SeLiteMisc.proxyVerifyFields( ChildClass, {...} ); | |
givenObjectOrClassDefinitions |
object | array |
<optional> |
Definition of fields for the proxy for the given target (either the given object, or given class/constructor function itself); optional. It doesn't define fields of instances of the proxy class (if target is a class) - use classInstanceDefinitions for that. It may be modified and/or frozen by this function, therefore don't re-use the same givenObjectOrClassDefinitions object (e.g. from variable in a closure) for different targets. Either an array of field names, or an object {
fieldName: either
- a string: one of SeLiteMisc.TYPE_NAMES or the name of a class, or
- a function: a constructor function of a class, or
- an array of such strings/functions
...
and optionally:
'*': function( name, value ) { return boolean }. That is only called for fields that are not specifically declared. So if a field is declared as above, then '*' doesn't apply to it.
}. If you have multiple fields with same definition, you can shorten the code by using SeLiteMisc.setFields() for value of givenObjectOrClassDefinitions and/or classInstanceDefinitions. |
prototypeDefinitions |
object | Array |
<optional> |
Definitions of fields of 'prototype' field of the given class to be proxied. Optional; it must not be present if target is not a class (a constructor function). Structure like that of givenObjectOrClassDefinitions. The actual instances of the class won't inherit thise definition set - so if you need to modify such fields per instance, include definition of those fields in classInstanceDefinitions. |
classInstanceDefinitions |
object | Array |
<optional> |
Definitions of fields of instances of the given class. Optional; it must not be present if target is not a class (a constructor function). Structure like that of givenObjectOrClassDefinitions. Side note: If we didn't have classInstanceDefinitions, the programmer could workaround by calling SeLiteMisc.proxyAllowFields(this) from the constructor function. However, that could be awkward. |
(static) proxyVerifyFieldsOnRead(target)
This generates a proxy for the given target object or class (constructor function). The proxy ensures that any fields read have been set already. This serves to prevent typing/renaming accidents that would access non-existing fields, doing which normally returns undefined. Such problems arise when you access fields directly, rather than via accessor methods, and when you don't access any properties/methods on the retrieved fields themselves. An example is when you compare the field values by operators.
Instead of using the fields directly you could have accessor methods, but those don't gurarentee correct code anyway (since they may contain typos, too), hence they don't solve the problem; however, they do make code more verbose and less hands-on.
This uses Proxy, which decreases execution speed a bit. However, it helps to identify mistakes earlier, while keeping code shorter.
If you need the code to determine whether the proxy contains a field with a given name, use expression: fieldName in target.
Instead of using the fields directly you could have accessor methods, but those don't gurarentee correct code anyway (since they may contain typos, too), hence they don't solve the problem; however, they do make code more verbose and less hands-on.
This uses Proxy, which decreases execution speed a bit. However, it helps to identify mistakes earlier, while keeping code shorter.
If you need the code to determine whether the proxy contains a field with a given name, use expression: fieldName in target.
Parameters:
| Name | Type | Description |
|---|---|---|
target |
object | function | An object, or a class (a constructor function). If it's a class, it may be an parent class, or a leaf-like. If used for non-leaf classes, then this doesn't protect instances of leaf classes: any classes that inherit from the proxy won't be protected by this mechanism - you need to use SeLiteMisc.proxyVerifyFieldsOnRead() for those subclasses, too. If target is a class (a function), then this covers both access to 'static' properties set on the class itself, and access to properties set on its instances. If used for multiple or all classes in the inheritance ancestry tree, this slows down access through prototype chain a bit; if that matters, then use it for leaf-classes only. |
- Source:
- See:
(static) random()
This returns random true or false, with threshold being the (average) ratio of true results against
the number of all results.
(static) randomChar(string)
Parameters:
| Name | Type | Description |
|---|---|---|
string |
acceptableChars String containign acceptable characters. |
Returns:
string 1 random character from within acceptableChars
(static) randomItem(array)
This picks up a random item from the given array, and returns it.
Parameters:
| Name | Type | Description |
|---|---|---|
array |
Array of items |
Returns:
mixed An item from within the array, at a random index
(static) randomString(string, number)
Parameters:
| Name | Type | Description |
|---|---|---|
string |
acceptableChars String containign acceptable characters. | |
number |
length Length of the result string (possibly 0) |
Returns:
string of given length, made of random characters from within acceptableChars
(static) registerOrExtendFramework()
This ensures that there's maximum one framework loaded per Firefox sessionAs per http://selite.github.io/GeneralFramework#limitations. TODO: link to [No hot switching between frameworks] and to [BootstrapLoader#Switching between files Switching between files].
(static) rowsToString(mixed, bool)
Get string representation of the given matrix or given array of objects.
Parameters:
| Name | Type | Description |
|---|---|---|
mixed |
rows Array of objects, or object of objects. | |
bool |
includeFunctions Whether to include functions; false by default. includeFunctions only applies to inner objects; no functions of rows itself are included at all. |
Returns:
string
Used for debugging.
(static) setFields(object, string, mixed)
A helper function, so that custom Selenium actions can store results within
fields/subfields of storedVars.
Parameters:
| Name | Type | Description |
|---|---|---|
object |
Object containing the field (its value must be an object, if there's another field) | |
string |
fieldsString Field name(s), separated by one dot between each. The first one points to a field within object. Its value must be an object again if there are any further field(s); then apply those fields. Any intermediary object(s) must exist; this function won't create them if they're missing, and it will fail. | |
mixed |
value Value to set to the leaf field. |
Returns:
void
(static) setFieldsPairs(object, value) → {object}
It sets field(s) with given names to given values (on given object). It accepts a flexible number (odd number) of parameters. It refuses to override an already set field (and hence it refuses the same field name passed in multiple times).
Parameters:
| Name | Type | Description |
|---|---|---|
object |
object | |
field. |
string | number | Array | If it's an array, then it represents zero, one or multiple fields, and the next value will be assigned to all listed fields. |
value |
* |
Returns:
object
- Type
- object
(static) setLoginManagerEntry()
It inserts or updates details in Firefox Login Manager.
(static) sortedObject(mixed)
This creates an object that manages/preserves order of the fields.
For now it works with for( .. in .. ) only. It doesn't keep the order when using Object.keys( .. )
Parameters:
| Name | Type | Description |
|---|---|---|
mixed |
sortCompare It indicates auto-ordering. Either - a function - bool true if it should order naturally - see SeLiteMisc.compareNatural() - false to just honour browser-given order (not working for now - it will honour the order, but not for e.g. mixed negative/positive numeric keys) |
Returns:
a new object
Old docs - relevant only if Firefox supprots object proxies properly. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators and https://bugzilla.mozilla.org/show_bug.cgi?id=783829 Especially useful if you have keys that are negative numbers (they get transformed to strings, but that doesn't matter here much). Order of such keys didn't get preserved in Firefox 22. That complies with 3.1 of ECMA-262: "The mechanics and order of enumerating the properties [...] is not specified." There are 2 possibilities of ordering the fields: - client-managed, no re-positioning (other than on removal of an item). A new entry is added to the end of the list items. - auto-ordered, with automatic re-shuffling - A new entry is added to where it belongs to, based on sortCompare(). If sortCompare is boolean true, then it uses natural sorting - see SeLiteMisc.compareNatural(). // See http://stackoverflow.com/questions/648139/is-the-order-of-fields-in-a-javascript-object-predictable-when-looping-through-t // and https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators I don't subclass Proxy - because it didn't work - the handler functions were not called. Also, in order to subclass Proxy, my constructor had to invoke Proxy.constructor.call(this, target, sortedObjectProxyHandler).
Old docs - relevant only if Firefox supprots object proxies properly. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators and https://bugzilla.mozilla.org/show_bug.cgi?id=783829 Especially useful if you have keys that are negative numbers (they get transformed to strings, but that doesn't matter here much). Order of such keys didn't get preserved in Firefox 22. That complies with 3.1 of ECMA-262: "The mechanics and order of enumerating the properties [...] is not specified." There are 2 possibilities of ordering the fields: - client-managed, no re-positioning (other than on removal of an item). A new entry is added to the end of the list items. - auto-ordered, with automatic re-shuffling - A new entry is added to where it belongs to, based on sortCompare(). If sortCompare is boolean true, then it uses natural sorting - see SeLiteMisc.compareNatural(). // See http://stackoverflow.com/questions/648139/is-the-order-of-fields-in-a-javascript-object-predictable-when-looping-through-t // and https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators I don't subclass Proxy - because it didn't work - the handler functions were not called. Also, in order to subclass Proxy, my constructor had to invoke Proxy.constructor.call(this, target, sortedObjectProxyHandler).
(static) timestampInSeconds()
Returns:
number Number of seconds since Epoch.
(static) treatError(errorOrMessageopt) → {Error}
Create a new Error object. Set it with the given message or with message and stack of the given error.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
errorOrMessage |
Error | string |
<optional> |
Returns:
New Error object.
- Type
- Error
(static) typeAndClassNameOf(objectOrConstructor) → {object|function}
Parameters:
| Name | Type | Description |
|---|---|---|
objectOrConstructor |
* |
Returns:
Either 'object of XXX' or 'class XXX', where XXX is objectOrConstructor (if it's a class), or a constructor of objectOrConstructor.
- Type
- object | function
(static) valueOf(valueOrFunctionopt) → {*}
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
valueOrFunction |
* |
<optional> |
Either a non-functional value, or a function that takes no parameters and returns a value. It serves for accepting closures (functions) instead of error messages (or parts of such messages, e.g. variable names/descriptions). That's useful when such a string is not constant and it needs to be generated. In such cases passing a closure (that encapsulates its scope) is more efficient, as that's what the closures are for. (Since we don't store the closure anywhere, there's no problem with scope/memory leaks.) |
Returns:
The value, or undefined if none. No other treatment - e.g. if valueOrFunction is a numeric string, this returns it unchanged as a string, not as a number.
- Type
- *