QScript Rule

This feature is new in Q 4.8.

Rule

Represents a Rule. Rules can be applied to one or more tables, plots, or R outputs. See Q documentation for more information about Rules. Create new Rules using the RulesManager object. Add them to tables and plots using table.rules.add(). Change Rules by creating a new rule and using the replace() function in the RulesManager object. A Rule must always be applied to at least one item: one is deleted automatically the moment its last use is removed, so there is no way to end up with an orphaned Rule.

appliedTo

Returns every table, plot, or other analysis item that this Rule is currently applied to.

check(code, target)

Runs this Rule's JavaScript, or code when supplied, against a table or plot and reports whether the JavaScript succeeded. Use it before storing new JavaScript on a Rule. The run happens on a copy, so this Rule and the items using it are unchanged whatever the outcome. The JavaScript itself is not sandboxed: code that edits the project still edits the project. Rules applied to the target ahead of this one run first, as in a real calculation, so one of those failing leaves this Rule unchecked. Code that asks the user a question cannot be checked, because a check has no one to ask. Cancelling stops the calling script, the same as cancelling anywhere else.

code	Candidate JavaScript to run. When omitted, this Rule's own JavaScript runs. A built-in Rule's JavaScript cannot be replaced, so candidate code is run as the custom Rule you would have to create to keep it.
target	The table or plot to run the JavaScript against. Required if this Rule is not yet applied to anything; optional (defaults to the Rule's first user) otherwise.
Returns:	The outcome, and the reason and position when the JavaScript did not succeed.

code

The JavaScript source of this Rule. Readable for every kind of Rule, including built-in Rules. Assignable only when isCodeEditable is true; otherwise create a replacement with project.rules.newCustomRule() and swap it in with project.rules.replace().

duplicate()

Duplicates this Rule, leaving this Rule and its own current uses unchanged. The returned Rule must be promptly added to a table, plot, or R output to take effect, as Rules are automatically deleted the moment their last use is removed, and the returned Rule has no uses.

Returns:	The new, independent Rule.
Example:	var duplicate = rule.duplicate();

equals(obj)

Whether two objects are the same.

obj	The object to compare against.
Returns:	true or false
Example:	data_file.getQuestionByName('Q2').equals(data_file.questions()[0])

isCodeEditable

True for custom Rules and false for built-in Rules and Rules from the online library.

isDefault

Whether this Rule is applied as a default rule for new plots and tables.

summary

Describes the Rule. May contain more specific information if the rule has already been used to calculate a table or plot.

type

Returns the name we use to refer to this class in the documentation.