Labs/Jetpack/JEP/28: Difference between revisions

{{Jetpack/Moved to SDK}}
({{Jetpack/Moved to SDK}})
 
(43 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Introduction ==
{{Jetpack/Moved to SDK}}


The Cuddlefish Minilib builds on [[Labs/Jetpack/JEP/25|JEP 25 - Boosters]] to provide a basic infrastructure for developing traditional XULRunner Extensions.  It will also be the basis for Jetpack, as Jetpack itself is a XULRunner Extension.
== Abstract ==
 
The Cuddlefish Minilib builds on [[Labs/Jetpack/JEP/25|JEP 25]] to provide a basic infrastructure for developing traditional XULRunner Extensions and applications.  It will also be the basis for Jetpack, as Jetpack itself is a XULRunner Extension.
 
It's assumed that readers of this document are familiar with JEP 25 and the SecurableModule standard.


== Motivation and Rationale ==
== Motivation and Rationale ==


In many ways, this JEP is a refactored formalization of Jetpack's current implementation that will allow many of Jetpack's core benefits to be leveraged by any XULRunner Extension. Another way of putting this is that Cuddlefish nicely decouples functionality that is specific to Jetpack from functionality that many other extensions—Labs extensions in particular—would like to have, and which they often end up re-implementing from scratch to some extent.
Cuddlefish will allow many of the core benefits of Jetpack and CommonJS to be leveraged by any XULRunner Extension or application.


Additionally, by moving to a SecurableModule-based architecture, Jetpack's runtime can easily be decoupled from the about:jetpack page, which will resolve a number of deficiencies (such as the inability to look at the API documentation and use the built-in code editor simultaneously).
Additionally, by moving Jetpack to a SecurableModule-based architecture, a number of deficiencies with its runtime will be resolved, such as the inability to look at the API documentation and use the built-in code editor simultaneously.


== Requirements and Scope ==
== Requirements and Scope ==


To address issues present in traditional Extension development, Cuddlefish provides the following:
To address issues present in traditional Extension development, Cuddlefish provides mechanisms for:


* A simple, straightforward mechanism for writing and executing test cases, inspired by Python's [http://code.google.com/p/python-nose/ nose] package.
* writing and executing test cases, inspired by Python's [http://code.google.com/p/python-nose/ nose] package,
* A mechanism for tracking JS objects of interest to aid in memory profiling and leak detection.
* tracking JS objects of interest to aid in memory profiling and leak detection,
* A mechanism for registering callbacks that perform cleanup tasks when modules are unloaded.
* registering callbacks that perform cleanup tasks when modules are unloaded,
* A mechanism for easily reporting errors with full stack tracebacks.
* easily reporting errors with full stack tracebacks,
* A simple mechanism for dropping-in optional third-party packages or SecurableModules.
* dropping-in optional third-party packages or SecurableModules.


Cuddlefish should also have the following characteristics:
Cuddlefish should also have the following characteristics:
Line 30: Line 34:


* Cuddlefish doesn't "touch" the command line at all; it's just a drop-in library to include in existing XULRunner Extensions or applications. As such, the following are out of scope:
* Cuddlefish doesn't "touch" the command line at all; it's just a drop-in library to include in existing XULRunner Extensions or applications. As such, the following are out of scope:
:* A tool for creating new XULRunner Extension or application directory structures "from scratch".
** A tool for creating new XULRunner Extension or application directory structures "from scratch".
:* A build system for creating XPIs or XULRunner applications.
** A build system for creating XPIs or XULRunner applications.
* A documentation system.
* A documentation system.
* A package management system.
* A package management system.
* A user interface. Cuddlefish doesn't make any assumptions about whether you're using XUL, HTML, stdout, or something else.  The exception to this is the logging console, which obviously needs ''something'' to output to, but multiple implementations will be built-in to the minilib, with the option for clients to provide their own.
* Functionality specific to any particular XULRunner application, such as Firefox or Thunderbird.
* Any user interface, such as a debugger or a DOM inspector. Cuddlefish doesn't make any assumptions about whether you're using XUL, HTML, stdout, or something else; the exception to this is the logging console, which obviously needs ''something'' to output to, but multiple targets will be built-in to the minilib, with the option for clients to provide their own.


== Usage ==
== Usage ==
Line 44: Line 49:
<pre class="brush:html;">
<pre class="brush:html;">
<html>
<html>
   <script src="lib/booster.js"></script>
   <script src="lib/cuddlefish.js"></script>
  <script src="lib/cuddle.js"></script>
   <script>
   <script>
   var loader = new Cuddlefish.Loader({rootPath: "lib/",
   var loader = new Cuddlefish.Loader({rootPath: "lib/"});
                                      SecurableModule: SecurableModule});
   loader.runScript("console.log('hello');");
   loader.runScript({contents: "console.log('hello');",
  loader.unload();
                    lineNo: 1,
                    filename: "<string>"});
   </script>
   </script>
</html>
</html>
</pre>
</pre>
The <tt>Loader</tt> class encapsulates the Cuddlefish library and runtime; the caller has full control (and responsibility!) over its lifecycle. This means, for instance, that a document can instantiate a <tt>Loader</tt> that continues existing long after the document is closed; alternatively, a JS module can instantiate a <tt>Loader</tt> that stops existing well before the containing application process terminates.  This freedom of control allows for a wide range of behavior, including the ability for application-wide functionality to be "streamed in" and automatically updated without requiring a restart.


== Globals ==
== Globals ==
Line 68: Line 72:


In addition to these, the following globals are available to all modules.
In addition to these, the following globals are available to all modules.
=== <tt>__url__</tt> ===
The <tt>__url__</tt> global is a string identifying the URL from which the module or script's code has been retrieved.  If the module or script has no identifiable URL, this value may be <tt>null</tt>.


=== <tt>console</tt> ===
=== <tt>console</tt> ===
Line 73: Line 81:
<tt>console</tt> is an object with methods similar to Firebug's [http://getfirebug.com/console.html console] object:
<tt>console</tt> is an object with methods similar to Firebug's [http://getfirebug.com/console.html console] object:


<tt>console.'''log'''(''object''[[, ''object2''], ''...''])</tt>
<tt>console.'''log'''(''object''[, ''object'', ...])</tt>


Logs an informational message to the console. Depending on console's underlying implementation and user interface, you may be able to introspect into the properties of non-primitive objects that are logged.
Logs an informational message to the console. Depending on console's underlying implementation and user interface, you may be able to introspect into the properties of non-primitive objects that are logged.


<tt>console.'''warn'''(''object''[[, ''object2''], ''...''])</tt>
<tt>console.'''info'''(''object''[, ''object'', ...])</tt>
 
A synonym for <tt>console.log()</tt>.
 
<tt>console.'''warn'''(''object''[, ''object'', ...])</tt>


Logs a warning message to the console.
Logs a warning message to the console.


<tt>console.'''error'''(''object''[[, ''object2''], ''...''])</tt>
<tt>console.'''error'''(''object''[, ''object'', ...])</tt>


Logs an error message to the console.
Logs an error message to the console.


<tt>console.'''debug'''(''object''[[, ''object2''], ''...''])</tt>
<tt>console.'''debug'''(''object''[, ''object'', ...])</tt>


Logs a debug message to the console.
Logs a debug message to the console.
<tt>console.'''exception'''(''exception'')</tt>
Logs the given exception instance as an error, outputting information about the exception's stack traceback if one is available.


<tt>console.'''trace'''()</tt>
<tt>console.'''trace'''()</tt>
Line 95: Line 111:
=== <tt>memory</tt> ===
=== <tt>memory</tt> ===


<tt>memory</tt> is an object that exposes functionality to track objects of interest and help prevent memory leaks.
<tt>memory</tt> is an object that exposes functionality to track objects of interest and help diagnose and prevent memory leaks.


<tt>memory.'''track'''(''object'', [''name''])</tt>
<tt>memory.'''track'''(''object'', [''bin''])</tt>


Marks ''object'' for being tracked, and categorizes it with the given name. If ''name'' isn't specified, the memory tracker attempts to infer the name by first checking the object's <tt>constructor.name</tt>; if that fails or results in the generic <tt>Object</tt>, the stack is inspected and the name of the current function being executed&mdash;which is assumed to be a constructor function&mdash;is used.
Marks ''object'' for being tracked, and categorizes it with the given bin name. If ''bin'' isn't specified, the memory tracker attempts to infer a bin name by first checking the object's <tt>constructor.name</tt>; if that fails or results in the generic <tt>Object</tt>, the stack is inspected and the name of the current function being executed&mdash;which is assumed to be a constructor function&mdash;is used. If that fails, then the object is placed in a bin named <tt>generic</tt>.
 
<tt>memory.'''getObjects'''([''bin''])</tt>
 
Returns an <tt>Array</tt> containing information about tracked objects that have been categorized with the given bin name. If ''bin'' isn't provided, information about all live tracked objects are returned.
 
Each element of the array is an object with the following keys:
 
{|cellpadding="5" cellspacing="0" border="1" width="100%"
|<tt>weakref</tt>
|A weak reference to the object being tracked. Call <tt>get()</tt> on this object to retrieve its strong reference; if a strong reference to the object no longer exists, <tt>get()</tt> will return <tt>null</tt>.
|-
|<tt>created</tt>
|A <tt>Date</tt> representing the date and time that <tt>memory.track()</tt> was called on the object being tracked.
|-
|<tt>filename</tt>
|The name of the file that called <tt>memory.track()</tt> on the object being tracked.
|-
|<tt>lineNo</tt>
|The line number of the file that called <tt>memory.track()</tt> on the object being tracked.
|}


<tt>memory.'''getLiveObjects'''([''name''])</tt>
<tt>memory.'''getBins'''()</tt>


Returns an <tt>Array</tt> of all live tracked objects that have been categorized with the given name. If ''name'' isn't provided, all live tracked objects are returned.
Returns an <tt>Array</tt> containing the names of all bins that aren't currently empty.


== Modules ==
== Modules ==


The following modules come built-in with Cuddlefish and can be retrieved with a call to <tt>require()</tt>.
The following modules come built-in with Cuddlefish and can be retrieved with a call to <tt>require()</tt>.
=== <tt>file</tt> ===
The <tt>file</tt> module provides access to the local filesystem.
<tt>file.'''dirname'''(''path'')</tt>
Returns the path of a file’s containing directory, albeit the parent directory if the file is a directory.
<tt>file.'''list'''(''path'')</tt>
Returns an array of files in the given directory.
<tt>file.'''join'''(''...'')</tt>
Takes a variable number of strings, joins them on the file system’s path separator, and returns the result.
=== <tt>securable-module</tt> ===
The <tt>securable-module</tt> module allows for the recursive loading and sandboxing of SecurableModules. This allows, for instance, the creation of "mini platforms" that manage the sandboxed evaluation of code.
The module's interface is the same as that specified in [[Labs/Jetpack/JEP/25|JEP 25]].
=== <tt>unit-test</tt> ===
The <tt>unit-test</tt> module makes it easy to find and run unit tests.
==== Test Runner Objects ====
Each function which represents a test case is passed a single argument <tt>test</tt>, which represents the test runner.  It has the following methods:
<tt>test.'''pass'''([''message''])</tt>
Marks a test as passing, with the given optional message.
<tt>test.'''fail'''([''message''])</tt>
Marks a test as failing, with the given optional message.
<tt>test.'''exception'''(''e'')</tt>
Marks a test as failing due to the given exception having been thrown.  This can be put in a <tt>catch</tt> clause.
<tt>test.'''assert'''(''a''[, ''message''])</tt>
Ensures that ''a'' has a truthy value.  A test is marked as passing or failing depending on the result, logging ''message'' with it.
<tt>test.'''assertEqual'''(''a'', ''b''[, ''message''])</tt>
Simply ensures that ''a'' <tt>==</tt> ''b'' without recursing into ''a'' or ''b''.  A test is marked as passing or failing depending on the result, logging ''message'' with it.
<tt>test.'''assertNotEqual'''(''a'', ''b''[, ''message''])</tt>
Simply ensures that ''a'' <tt>!=</tt> ''b'' without recursing into ''a'' or ''b''.  A test is marked as passing or failing depending on the result, logging ''message'' with it.
<tt>test.'''assertMatches'''(''string'', ''regexp''[, ''message''])</tt>
Ensures that the given string matches the given regular expression.  If it does, marks a test as passing, otherwise marks a test as failing.  ''message'' is logged with the pass or fail.
<tt>test.'''assertRaises'''(''func'', ''predicate''[, ''message''])</tt>
Calls the function ''func'' with no arguments, expecting an exception to be raised. If nothing is raised, marks the test as failing. If an exception is raised, the exception's <tt>message</tt> property is compared with ''predicate'': if ''predicate'' is a string, then a simple equality comparison is done with <tt>message</tt>. Otherwise, if ''predicate'' is a regular expression, <tt>message</tt> is tested against it. Depending on the outcome, a test is marked as passing or failing, and ''message'' is logged.
<tt>test.'''waitUntilDone'''([''timeout''])</tt>
Puts the test runner into asynchronous testing mode, waiting up to ''timeout'' milliseconds for <tt>test.done()</tt> to be called.  This is intended for use in situations where a test suite schedules a callback, calls <tt>test.waitUntilDone</tt>, and then calls <tt>test.done()</tt> in the callback.
<tt>test.'''done'''()</tt>
Marks a test as being complete.  Assumes a previous call to <tt>test.waitUntilDone()</tt>.
==== Functions ====
<tt>unit-test.'''findAndRunTests'''(''options'')</tt>
''options'' should contain the following properties:
{|cellpadding="5" cellspacing="0" border="1" width="100%"
|<tt>dirs</tt>
|A list of absolute paths representing directories to search for tests in.  It's assumed that all of these directories are also in the module search path, i.e. any JS files found in them are SecurableModules that can be loaded via a call to <tt>require()</tt>.
|-
|<tt>onDone</tt>
|A function to call when testing is complete.
|}
The list of directories is searched for SecurableModules that start with the prefix <tt>test-</tt>.  Each module matching this criteria is expected to export functions that are test cases or a suite of test cases; each is called with a single argument, which is a [[#Test Runner Objects|Test Runner Object]].
=== <tt>xhr</tt> ===
The <tt>xhr</tt> module provides access to <tt>XMLHttpRequest</tt> functionality, also known as AJAX.
<tt>xhr.'''XMLHttpRequest'''()</tt>
Creates an <tt>XMLHttpRequest</tt>. For more information, see [https://developer.mozilla.org/En/Using_XMLHttpRequest Using XMLHttpRequest].
<tt>xhr.'''getRequestCount'''()</tt>
Returns the number of <tt>XMLHttpRequest</tt> objects that are alive (i.e., currently active or about to be).
=== <tt>observer-service</tt> ===
The <tt>observer-service</tt> module provides access to the application-wide observer service singleton.
For a list of common observer topics across a variety of Mozilla-based applications, see [https://developer.mozilla.org/en/Observer_Notifications Observer Notifications].
==== Observer Callbacks ====
Observer callbacks are functions of the following form:
<pre class="brush:js;">
function callback(subject, data) {
  /* Respond to the event notification here... */
}
</pre>
In the above example, <tt>subject</tt> is any JavaScript object, as is <tt>data</tt>.  The particulars of what the two contain are specific to the notification topic.
==== Functions ====
<tt>observer-service.'''add'''(''topic'', ''callback'')</tt>
Adds an observer callback to be triggered whenever a notification matching the string ''topic'' is broadcast throughout the application.
<tt>observer-service.'''remove'''(''topic'', ''callback'')</tt>
Unsubscribes ''callback'' from being triggered whenever a notification matching the string ''topic'' is broadcast throughout the application.
<tt>observer-service.'''notify'''(''topic'', ''subject'', ''data'')</tt>
Broadcasts a notification event with the string ''topic'', passing ''subject'' and ''data'' to all applicable observers in the application.
=== <tt>preferences-service</tt> ===
The <tt>preferences-service</tt> module provides access to the application-wide preferences service singleton.
<tt>preferences-service.'''set'''(''name'', ''value'')</tt>
Sets the application preference ''name'' to ''value''.  ''value'' must be a string, boolean, or number.
<tt>preferences-service.'''get'''(''name'', ''defaultValue'')</tt>
Gets the application preference ''name'', returning ''defaultValue'' if no such preference exists.
<tt>preferences-service.'''has'''(''name'')</tt>
Returns whether or not the application preference ''name'' exists.
<tt>preferences-service.'''isSet'''(''name'')</tt>
Returns whether or not the application preference ''name'' both exists and has been set to a non-default value by the user (or a program acting on the user's behalf).
<tt>preferences-service.'''reset'''(''name'')</tt>
Clears a non-default, user-set value from the application preference ''name''. If no user-set value is defined on ''name'', the function does nothing.
=== <tt>timer</tt> ===
The <tt>timer</tt> module provides access to web-like timing functionality.
<tt>timer.'''setTimeout'''(''callback'', ''ms'')</tt>
Schedules ''callback'' to be called in ''ms'' milliseconds. Returns an integer ID that can later be used to undo this scheduling, if ''callback'' hasn't yet been called.
<tt>timer.'''clearTimeout'''(''id'')</tt>
Given an integer ID passed back from <tt>setTimeout()</tt>, prevents the callback with the ID from being called (if it hasn't yet been called).
=== <tt>url</tt> ===
The <tt>url</tt> module provides functionality for the parsing and retrieving of URLs.
<tt>url.'''toFilename'''(''url'')</tt>
Attempts to convert the given URL to a native file path.  This function will automatically attempt to resolve non-file protocols, such as the <tt>resource:</tt> protocol, to their place on the file system. An exception is raised if the URL can't be converted; otherwise, the native file path is returned as a string.
<tt>url.'''fromFilename'''(''path'')</tt>
Converts the given native file path to a <tt>file:</tt> URL.
<tt>url.'''resolve'''(''base'', ''relative'')</tt>
Returns an absolute URL given a base URL and a relative URL.
<tt>url.'''parse'''(''url'')</tt>
Parses the URL and returns an object with following keys:
{|cellpadding="5" cellspacing="0" border="1" width="100%"
|<tt>scheme</tt>
|The name of the protocol in the URL.
|-
|<tt>userPass</tt>
|The username:password part of the URL; <tt>null</tt> if not present.
|-
|<tt>host</tt>
|The host of the URL, <tt>null</tt> if not present.
|-
|<tt>port</tt>
|The port number of the URL, <tt>null</tt> if none was specified.
|-
|<tt>path</tt>
|The path component of the URL.
|}


=== <tt>traceback</tt> ===
=== <tt>traceback</tt> ===
Line 145: Line 384:


The <tt>unload</tt> module allows modules to register callbacks that are called when Cuddlefish is unloaded.  It is similar to the SecurableModule of the same name in the [http://narwhaljs.org/ Narwhal] platform.
The <tt>unload</tt> module allows modules to register callbacks that are called when Cuddlefish is unloaded.  It is similar to the SecurableModule of the same name in the [http://narwhaljs.org/ Narwhal] platform.
<tt>unload.'''when'''(''callback'')</tt>
Registers ''callback'' to be called when <tt>unload.send()</tt> is called.
<tt>unload.'''send'''()</tt>
Sends an unload signal, thereby triggering all callbacks registered via <tt>unload.when()</tt>. In general, this function need not be manually called; it is automatically triggered when the containing Cuddlefish Loader's <tt>unload()</tt> method is called.
== Reference Implementation ==
An in-progress reference implementation for Cuddlefish can be found at:
  http://hg.mozilla.org/users/avarma_mozilla.com/jep-28/
Just check out the Mercurial repository and read the [http://hg.mozilla.org/users/avarma_mozilla.com/jep-28/raw-file/tip/README.txt README].
It's also possible to play around with the latest version of the Minilib in Firefox and Thunderbird using the Cuddlefish Lab extension:
  https://addons.mozilla.org/en-US/firefox/addon/14634/
Once you've installed the extension, just go to the "Tools" menu and select "Cuddlefish Lab" to start experimenting with code.
== Related Materials ==
* [[Labs/Jetpack/JEP/25|JEP 25 - Boosters]]
874

edits