diff options
Diffstat (limited to 'tools/addon-sdk-1.3/packages/api-utils/docs')
37 files changed, 0 insertions, 4168 deletions
diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/api-utils.md b/tools/addon-sdk-1.3/packages/api-utils/docs/api-utils.md deleted file mode 100644 index d87acdb..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/api-utils.md +++ /dev/null @@ -1,153 +0,0 @@ -<!-- contributed by Drew Willcoxon [adw@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> - -The `api-utils` module provides some helpers useful to the SDK's high-level API -implementations. - -Introduction ------------- - -The SDK high-level API design guidelines make a number of recommendations. -This module implements some of those patterns so that your own implementations -don't need to reinvent them. - -For example, public constructors should be callable both with and without the -`new` keyword. Your module can implement this recommendation using the -`publicConstructor` function. - -Options objects or "dictionaries" are also common throughout the high-level -APIs. The guidelines recommend that public constructors should generally define -a single `options` parameter rather than defining many parameters. Since one of -the SDK's principles is to be friendly to developers, ideally all properties on -options dictionaries should be checked for correct type, and informative error -messages should be generated when clients make mistakes. With the -`validateOptions` function, your module can easily do so. - -And objects are sometimes iterable over a custom set of key/value pairs. -Such objects should have custom iterators that let consumers iterate keys, -values, or [key, value] pairs. The `addIterator` function makes it easy to do -so in a way that is consistent with the behavior of default iterators during -`for...in`, `for each...in`, and `for...in Iterator()` loops. - -<api name="publicConstructor"> -@function -Returns a function *C* that creates an instance of `privateConstructor`. *C* -may be called with or without the `new` keyword. - -The prototype of each instance returned from *C* is *C*.`prototype`, and -*C*.`prototype` is an object whose prototype is -`privateConstructor.prototype`. Instances returned from *C* are therefore -instances of both *C* and `privateConstructor`. - -Additionally, the constructor of each instance returned from *C* is *C*. - -Instances returned from *C* are automatically memory tracked using -`memory.track` under the bin name `privateConstructor.name`. - -**Example** - - function MyObject() {} - exports.MyObject = apiUtils.publicConstructor(MyObject); - -@returns {function} -A function that makes new instances of `privateConstructor`. - -@param privateConstructor {constructor} -</api> - -<api name="validateOptions"> -@function -A function to validate an options dictionary according to the specified -constraints. - -`map`, `is`, and `ok` are used in that order. - -The return value is an object whose keys are those keys in `requirements` that -are also in `options` and whose values are the corresponding return values of -`map` or the corresponding values in `options`. Note that any keys not shared -by both `requirements` and `options` are not in the returned object. - -**Examples** - -A typical use: - - var opts = { foo: 1337 }; - var requirements = { - foo: { - map: function (val) val.toString(), - is: ["string"], - ok: function (val) val.length > 0, - msg: "foo must be a non-empty string." - } - }; - var validatedOpts = apiUtils.validateOptions(opts, requirements); - // validatedOpts == { foo: "1337" } - -If the key `foo` is optional and doesn't need to be mapped: - - var opts = { foo: 1337 }; - var validatedOpts = apiUtils.validateOptions(opts, { foo: {} }); - // validatedOpts == { foo: 1337 } - - opts = {}; - validatedOpts = apiUtils.validateOptions(opts, { foo: {} }); - // validatedOpts == {} - -@returns {object} -A validated options dictionary given some requirements. If any of the -requirements are not met, an exception is thrown. - -@param options {object} -The options dictionary to validate. It's not modified. If it's null or -otherwise falsey, an empty object is assumed. - -@param requirements {object} -An object whose keys are the expected keys in `options`. Any key in -`options` that is not present in `requirements` is ignored. Each -value in `requirements` is itself an object describing the requirements -of its key. The keys of that object are the following, and each is optional: - -@prop [map] {function} -A function that's passed the value of the key in the `options`. `map`'s -return value is taken as the key's value in the final validated options, -`is`, and `ok`. If `map` throws an exception it is caught and discarded, -and the key's value is its value in `options`. - -@prop [is] {array} -An array containing the number of `typeof` type names. If the key's value is -none of these types it fails validation. Arrays and nulls are identified by -the special type names "array" and "null"; "object" will not match either. -No type coercion is done. - -@prop [ok] {function} -A function that is passed the key's value. If it returns false, the value -fails validation. - -@prop [msg] {string} -If the key's value fails validation, an exception is thrown. This string -will be used as its message. If undefined, a generic message is used, unless -`is` is defined, in which case the message will state that the value needs to -be one of the given types. -</api> - -<api name="addIterator"> -@function -Adds an iterator to the specified object that iterates keys, values, -or [key, value] pairs depending on how it is invoked, i.e.: - - for (var key in obj) { ... } // iterate keys - for each (var val in obj) { ... } // iterate values - for (var [key, val] in Iterator(obj)) { ... } // iterate pairs - -If your object only iterates either keys or values, you don't need this -function. Simply assign a generator function that iterates the keys/values -to your object's `__iterator__` property instead, f.e.: - - obj.__iterator__ = function () { for each (var i in items) yield i; } - -@param obj {object} -the object to which to add the iterator - -@param keysValsGen {function} -a generator function that yields [key, value] pairs -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/app-strings.md b/tools/addon-sdk-1.3/packages/api-utils/docs/app-strings.md deleted file mode 100644 index 3e4d358..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/app-strings.md +++ /dev/null @@ -1,61 +0,0 @@ -The `app-strings` module gives you access to the host application's localized -string bundles (`.properties` files). - -The module exports the `StringBundle` constructor function. To access a string -bundle, construct an instance of `StringBundle`, passing it the bundle's URL: - - var StringBundle = require("app-strings").StringBundle; - var bundle = StringBundle("chrome://browser/locale/browser.properties"); - -To get the value of a string, call the object's `get` method, passing it -the name of the string: - - var accessKey = bundle.get("contextMenuSearchText.accesskey"); - // "S" in the en-US locale - -To get the formatted value of a string that accepts arguments, call the object's -`get` method, passing it the name of the string and an array of arguments -with which to format the string: - - var searchText = bundle.get("contextMenuSearchText", - ["universe", "signs of intelligent life"]); - // 'Search universe for "signs of intelligent life"' in the en-US locale - -To get all strings in the bundle, iterate the object, which returns arrays -of the form [name, value]: - - for (var [name, value] in Iterator(bundle)) - console.log(name + " = " + value); - -Iteration ---------- - -<code>for (var name in bundle) { ... }</code> - -Iterate the names of strings in the bundle. - -<code>for each (var val in bundle) { ... }</code> - -Iterate the values of strings in the bundle. - -<code>for (var [name, value] in Iterator(bundle)) { ... }</code> - -Iterate the names and values of strings in the bundle. - - -<api name="StringBundle"> -@class -The `StringBundle` object represents a string bundle. -<api name="StringBundle"> -@constructor -Creates a StringBundle object that gives you access to a string bundle. -@param url {string} the URL of the string bundle -@returns {StringBundle} the string bundle -</api> -<api name="get"> -@method Get the value of the string with the given name. -@param [name] {string} the name of the string to get -@param [args] {array} (optional) strings that replace placeholders in the string -@returns {string} the value of the string -</api> -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/byte-streams.md b/tools/addon-sdk-1.3/packages/api-utils/docs/byte-streams.md deleted file mode 100644 index f7cffe8..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/byte-streams.md +++ /dev/null @@ -1,64 +0,0 @@ -<!-- contributed by Drew Willcoxon [adw@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> - -The `byte-streams` module provides streams for reading and writing bytes. - -<api name="ByteReader"> -@class -<api name="ByteReader"> -@constructor - Creates a binary input stream that reads bytes from a backing stream. -@param inputStream {stream} - The backing stream, an <a href="http://mxr.mozilla.org/mozilla-central/ -source/xpcom/io/nsIInputStream.idl"><code>nsIInputStream</code></a>. -</api> -<api name="closed"> -@property {boolean} - True if the stream is closed. -</api> - -<api name="close"> -@method - Closes both the stream and its backing stream. If the stream is already - closed, an exception is thrown. -</api> - -<api name="read"> -@method - Reads a string from the stream. If the stream is closed, an exception is - thrown. -@param [numBytes] {number} - The number of bytes to read. If not given, the remainder of the entire stream - is read. -@returns {string} - A string containing the bytes read. If the stream is at the end, returns the - empty string. -</api> -</api> - -<api name="ByteWriter"> -@class -<api name="ByteWriter"> -@constructor - Creates a binary output stream that writes bytes to a backing stream. -@param outputStream {stream} - The backing stream, an <a href="http://mxr.mozilla.org/mozilla-central/ -source/xpcom/io/nsIOutputStream.idl"><code>nsIOutputStream</code></a>. -</api> -<api name="closed"> -@property {boolean} - True if the stream is closed. -</api> -<api name="close"> -@method - Closes both the stream and its backing stream. If the stream is already - closed, an exception is thrown. -</api> -<api name="write"> -@method - Writes a string to the stream. If the stream is closed, an exception is - thrown. -@param str {string} - The string to write. -</api> -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/collection.md b/tools/addon-sdk-1.3/packages/api-utils/docs/collection.md deleted file mode 100644 index 796289a..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/collection.md +++ /dev/null @@ -1,73 +0,0 @@ -<!-- contributed by Drew Willcoxon [adw@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> - -The `collection` module provides a simple list-like class and utilities for -using it. A collection is ordered, like an array, but its items are unique, -like a set. - -<api name="Collection"> -@class -A collection object provides for...in-loop iteration. Items are yielded in the -order they were added. For example, the following code... - - var collection = require("collection"); - var c = new collection.Collection(); - c.add(1); - c.add(2); - c.add(3); - for (item in c) - console.log(item); - -... would print this to the console: - -<pre> - 1 - 2 - 3 -</pre> - -Iteration proceeds over a copy of the collection made before iteration begins, -so it is safe to mutate the collection during iteration; doing so does not -affect the results of the iteration. - -<api name="Collection"> -@constructor -Creates a new collection. The collection is backed by an array. -@param [array] {array} -If *array* is given, it will be used as the backing array. This way the caller -can fully control the collection. Otherwise a new empty array will be used, and -no one but the collection will have access to it. -</api> -<api name="length"> -@property {number} -The number of items in the collection array. -</api> -<api name="add"> -@method -Adds a single item or an array of items to the collection. Any items already -contained in the collection are ignored. -@param itemOrItems {object} An item or array of items. -@returns {Collection} The Collection. -</api> -<api name="remove"> -@method -Removes a single item or an array of items from the collection. Any items not -contained in the collection are ignored. -@param itemOrItems {object} An item or array of items. -@returns {Collection} The Collection. -</api> -</api> - -<api name="addCollectionProperty"> -@function -Adds a collection property to the given object. Setting the property to a -scalar value empties the collection and adds the value. Setting it to an array -empties the collection and adds all the items in the array. -@param object {object} -The property will be defined on this object. -@param propName {string} -The name of the property. -@param [backingArray] {array} -If given, this will be used as the collection's backing array. -</api> - diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/content.md b/tools/addon-sdk-1.3/packages/api-utils/docs/content.md deleted file mode 100644 index b258d02..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/content.md +++ /dev/null @@ -1,11 +0,0 @@ -<!-- contributed by Irakli Gozalishvili [gozala@mozilla.com] --> - -The `content` module exports three different traits [Loader][], [Worker][] and -[Symbiont][]. None of this traits is intended to be used directly by programs. -Rather, they are intended to be used by other modules that provide high -level APIs to programs or libraries. - -[Loader]:packages/api-utils/docs/content/loader.html -[Worker]:packages/api-utils/docs/content/worker.html -[Symbiont]:packages/api-utils/docs/content/symbiont.html - diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/content/loader.md b/tools/addon-sdk-1.3/packages/api-utils/docs/content/loader.md deleted file mode 100644 index 83b6276..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/content/loader.md +++ /dev/null @@ -1,88 +0,0 @@ -<!-- contributed by Irakli Gozalishvili [gozala@mozilla.com] --> - -Loader is base trait and it provides set of core properties and associated -validations. Trait is useful for all the compositions providing high level -APIs for creating JavaScript contexts that can access web content. - -Loader is composed from the -[EventEmitter](packages/api-utils/docs/events.html) trait, therefore -instances of Loader and their descendants expose all the public properties -exposed by EventEmitter along with additional public properties: - -Value changes on all of the above mentioned properties emit `propertyChange` -events on an instances. - -**Example:** - -The following code creates a wrapper on hidden frame that reloads a web page -in frame every time `contentURL` property is changed: - - var hiddenFrames = require("hidden-frame"); - var { Loader } = require("content"); - var PageLoader = Loader.compose({ - constructor: function PageLoader(options) { - options = options || {}; - if (options.contentURL) - this.contentURL = options.contentURL; - this.on('propertyChange', this._onChange = this._onChange.bind(this)); - let self = this; - hiddenFrames.add(hiddenFrames.HiddenFrame({ - onReady: function onReady() { - let frame = self._frame = this.element; - self._emit('propertyChange', { contentURL: self.contentURL }); - } - })); - }, - _onChange: function _onChange(e) { - if ('contentURL' in e) - this._frame.setAttribute('src', this._contentURL); - } - }); - -<api name="Loader"> -@class -<api name="contentScriptFile"> -@property {array} -The local file URLs of content scripts to load. Content scripts specified by -this property are loaded *before* those specified by the `contentScript` -property. -</api> - -<api name="contentScript"> -@property {array} -The texts of content scripts to load. Content scripts specified by this -property are loaded *after* those specified by the `contentScriptFile` property. -</api> - -<api name="contentScriptWhen"> -@property {string} -When to load the content scripts. This may take one of the following -values: - -* "start": load content scripts immediately after the document -element for the page is inserted into the DOM, but before the DOM content -itself has been loaded -* "ready": load content scripts once DOM content has been loaded, -corresponding to the -[DOMContentLoaded](https://developer.mozilla.org/en/Gecko-Specific_DOM_Events) -event -* "end": load content scripts once all the content (DOM, JS, CSS, -images) for the page has been loaded, at the time the -[window.onload event](https://developer.mozilla.org/en/DOM/window.onload) -fires - -</api> - -<api name="contentURL"> -@property {string} -The URL of the content loaded. -</api> - -<api name="allow"> -@property {object} -Permissions for the content, with the following keys: -@prop script {boolean} - Whether or not to execute script in the content. Defaults to true. -</api> -</api> - diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/content/proxy.md b/tools/addon-sdk-1.3/packages/api-utils/docs/content/proxy.md deleted file mode 100644 index 012fbc7..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/content/proxy.md +++ /dev/null @@ -1,237 +0,0 @@ -<!-- contributed by Alexandre Poirot [apoirot@mozilla.com] --> - -Content scripts need access to the DOM of the pages they are attached to. -However, those pages should be considered to be hostile environments: we -have no control over any other scripts loaded by the web page that may be -executing in the same context. If the content scripts and scripts loaded -by the web page were to access the same DOM objects, there are two possible -security problems: - -First, a malicious page might redefine functions and properties of DOM -objects so they don't do what the add-on expects. For example, if a -content script calls `document.getElementById()` to retrieve a DOM -element, then a malicious page could redefine its behavior to return -something unexpected: - -<pre><code> -// If the web document contains the following script: -document.getElementById = function (str) { - // Overload indexOf method of all string instances - str.__proto__.indexOf = function () {return -1;}; - // Overload toString method of all object instances - str.__proto__.__proto__.toString = function () {return "evil";}; -}; -// After the following line, the content script will be compromised: -var node = document.getElementById("element"); -// Then your content script is totally out of control. -</code></pre> - -Second, changes the content script made to the DOM objects would be visible -to the page, leaking information to it. - -The general approach to fixing these problems is to wrap DOM objects in -[`XrayWrappers`](https://developer.mozilla.org/en/XPCNativeWrapper) -(also know as `XPCNativeWrapper`). This guarantees that: - -* when the content script accesses DOM properties and functions it gets the -original native version of them, ignoring any modifications made by the web -page -* changes to the DOM made by the content script are not visible to scripts -running in the page. - -However, `XrayWrapper` has some limitations and bugs, which break many -popular web frameworks. In particular, you can't: - -* define attributes like `onclick`: you have to use `addEventListener` syntax -* overload native methods on DOM objects, like this: -<pre><code> -proxy.addEventListener = function () {}; -</code></pre> -* access named elements using properties like `window[framename]` or -`document[formname]` -* use some other features that have bugs in the `XrayWrapper` -implementation, like `mozMatchesSelector` - -The `proxy` module uses `XrayWrapper` in combination with the -experimental -[Proxy API](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Proxy) -to address both the security vulnerabilities of content scripts and the -limitations of `XrayWrapper`. - -<pre> - /--------------------\ /------------------------\ - | Web document | | Content script sandbox | - | http://mozilla.org | | data/worker.js | - | | require('content-proxy'). | | - | window >-----------|- create(window) -|-> window | - \--------------------/ \------------------------/ -</pre> - - -## The Big Picture ## - -The implementation defines two different kinds of proxy: - - 1. Content script proxies that wrap DOM objects that are exposed to - content scripts as described above. - 2. XrayWrapper proxies that wrap objects from content scripts before handing - them over to XrayWrapper functions. These proxies are internal - and are not exposed to content scripts or document content. - -<pre> - /--------------------\ /------------------------\ - | Web document | | Content script sandbox | - | http://mozilla.org | | data/worker.js | - | | /-------|-> myObject = {} | - | | /----------------v--\ | | - | | | XrayWrapper Proxy | | - document | - | | \---------v---------/ \----^-------------------/ - | | v | - | | /-------------\ /----------\ | - | - document >-------|->| XrayWrapper |<-| CS proxy |-/ - \--------------------/ \-------------/ \----------/ -</pre> - -Everything begins with a single call to the `create` function exported by the -content-proxy module: - - // Retrieve the unwrapped reference to the current web page window object - var win = gBrowser.contentDocument.defaultView.wrappedJSObject; - // Or in addon sdk style - var win = require("tab-browser").activeTab.linkedBrowser.contentWindow.wrappedJSObject; - // Now create a content script proxy for the window object - var windowProxy = require("api-utils/content/content-proxy").create(win); - - // We finally use this window object as sandbox prototype, - // so that all web page globals are accessible in CS too: - var contentScriptSandbox = new Cu.Sandbox(win, { - sandboxPrototype: windowProxy - }); - -Then all other proxies are created from this one. Attempts to access DOM -attributes of this proxy are trapped, and the proxy constructs and returns -content script proxies for those attributes: - - // For example, if you simply do this: - var document = window.document; - // accessing the `document` attribute will be trapped by the `window` content script - // proxy, and that proxy will that create another content script proxy for `document` - -So the main responsibility of the content script proxy implementation is to -ensure that we always return content script proxies to the content script. - -## Internal Implementation ## - -Each content script proxy keeps a reference to the `XrayWrapper` that enables -it to be sure of calling native DOM methods. - -There are two internal functions to convert between content script proxy -values and `XrayWrapper` values. - -1. __`wrap`__ takes an XrayWrapper value and wraps it in a content script -proxy if needed. - This method is called when: - * a content script accesses an attribute of a content script proxy. - * XrayWrapper code calls a callback function defined in the content -script, so that arguments passed into the function by the XrayWrapper are -converted into content script proxies. For example, if a content script -calls `addEventListener`, then the listener function will expect any arguments -to be content script proxies. -<br/><br/> -2. __`unwrap`__ takes an object coming from the content script context and: - * if the object is a content script proxy, unwraps it back to an -XrayWrapper reference - * if the object is not a content script proxy, wraps it in an XrayWrapper -proxy. -<br/><br/> -This means we can call a XrayWrapper method either with: - - * a raw XrayWrapper object. - - // The following line doesn't work if child is a content script proxy, - // it has to be a raw XrayWrapper reference - xrayWrapper.appendChild(child) - - * an XrayWrapper proxy when you pass a custom object from the content -script context. - - var myListener = { - handleEvent: function(event) { - // `event` should be a content script proxy - } - }; - // `myListener` has to be another kind of Proxy: XrayWrapper proxy, - // that aims to catch the call to `handleEvent` in order to wrap its - // arguments in a content script proxy. - xrayWrapper.addEventListener("click", myListener, false); - - -## Stack Traces ## - -The following code: - - function listener(event) { - - } - csProxy.addEventListener("message", listener, false); - -generates the following internal calls: - - -> CS Proxy:: get("addEventListener") - -> wrap(xrayWrapper.addEventListener) - -> NativeFunctionWrapper(xrayWrapper.addEventListener) - // NativeFunctionWrapper generates: - function ("message", listener, false) { - return xraywrapper.addEventListener("message", unwrap(listener), false); - } - -> unwrap(listener) - -> ContentScriptFunctionWrapper(listener) - // ContentScriptFunctionWrapper generates: - function (event) { - return listener(wrap(event)); - } - -<br> - - // First, create an object from content script context - var myListener = { - handleEvent: function (event) { - - } - }; - // Then, pass this object as an argument to a CS proxy method - window.addEventListener("message", myListener, false); - - // Generates the following internal calls: - -> CS Proxy:: get("addEventListener") - -> wrap(xrayWrapper.addEventListener) - -> NativeFunctionWrapper(xrayWrapper.addEventListener) - // Generate the following function: - function ("message", myListener, false) { - return xraywrapper.addEventListener("message", unwrap(myListener), false); - } - -> unwrap(myListener) - -> ContentScriptObjectWrapper(myListener) - // Generate an XrayWrapper proxy and give it to xrayWrapper method. - // Then when native code fires an event, the proxy will catch it: - -> XrayWrapper Proxy:: get("handleEvent") - -> unwrap(myListener.handleEvent) - -> ContentScriptFunctionWrapper(myListener.handleEvent) - // Generate following function: - function (event) { - return myListener.handleEvent(wrap(event)); - } - - -<api name="create"> -@function - Create a content script proxy. <br/> - Doesn't create a proxy if we are not able to create a XrayWrapper for - this object: for example, if the object comes from system principal. - -@param object {Object} - The object to proxify. - -@returns {Object} - A content script proxy that wraps `object`. -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/content/symbiont.md b/tools/addon-sdk-1.3/packages/api-utils/docs/content/symbiont.md deleted file mode 100644 index 7519e52..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/content/symbiont.md +++ /dev/null @@ -1,136 +0,0 @@ -<!-- contributed by Myk Melez [myk@mozilla.org] --> -<!-- contributed by Irakli Gozalishvili [gozala@mozilla.com] --> - - -This module is not intended to be used directly by programs. Rather, it is -intended to be used by other modules that provide APIs to programs. - - -This module exports `Symbiont` trait that can be used for creating JavaScript -contexts that can access web content in host application frames (i.e. XUL -`<iframe>` and `<browser>` elements) and communicate with programs via -asynchronous JSON pipes. It is useful in the construction of APIs that -are compatible with the execution model codenamed "electrolysis" in which -programs run in separate processes from web content. - -Introduction ------------- - -`Symbiont` constructs a content symbiont for a given frame, it loads the -specified contentURL and scripts into it, and plumbs an asynchronous -JSON pipe between the content symbiont object and the content symbiont -context. If frame is not provided hidden frame will be created. - -Examples --------- - - var { Symbiont } = require('content'); - var Thing = Symbiont.resolve({ constructor: '_init' }).compose({ - constructor: function Thing(options) { - // `getMyFrame` returns the host application frame in which - // the page is loaded. - this._frame = getMyFrame(); - this._init(options) - } - }); - -See the [panel][] module for a real-world example of usage of this module. - -[panel]:packages/addon-kit/docs/panel.html - -Reference ---------- - -<api name="Symbiont"> -@class -Symbiont is composed from the [Worker][] trait, therefore instances -of Symbiont and their descendants expose all the public properties -exposed by [Worker][] along with additional public properties that -are listed below: - -[Worker]:packages/api-utils/docs/content/worker.html - -<api name="Symbiont"> -@constructor -Creates a content symbiont. -@param options {object} - Options for the constructor. Includes all the keys that -the [Worker](packages/api-utils/docs/content/worker.html) -constructor accepts and a few more: - - @prop [frame] {object} - The host application frame in which the page is loaded. - If frame is not provided hidden one will be created. - @prop [contentScriptWhen="end"] {string} - When to load the content scripts. This may take one of the following - values: - - * "start": load content scripts immediately after the document - element for the page is inserted into the DOM, but before the DOM content - itself has been loaded - * "ready": load content scripts once DOM content has been loaded, - corresponding to the - [DOMContentLoaded](https://developer.mozilla.org/en/Gecko-Specific_DOM_Events) - event - * "end": load content scripts once all the content (DOM, JS, CSS, - images) for the page has been loaded, at the time the - [window.onload event](https://developer.mozilla.org/en/DOM/window.onload) - fires - - This property is optional and defaults to "end". - - @prop [allow] {object} - Permissions for the content, with the following keys: - @prop [script] {boolean} - Whether or not to execute script in the content. Defaults to true. - Optional. - Optional. -</api> - -<api name="contentScriptFile"> -@property {array} -The local file URLs of content scripts to load. Content scripts specified by -this property are loaded *before* those specified by the `contentScript` -property. -</api> - -<api name="contentScript"> -@property {array} -The texts of content scripts to load. Content scripts specified by this -property are loaded *after* those specified by the `contentScriptFile` property. -</api> - -<api name="contentScriptWhen"> -@property {string} -When to load the content scripts. This may have one of the following -values: - -* "start": load content scripts immediately after the document -element for the page is inserted into the DOM, but before the DOM content -itself has been loaded -* "ready": load content scripts once DOM content has been loaded, -corresponding to the -[DOMContentLoaded](https://developer.mozilla.org/en/Gecko-Specific_DOM_Events) -event -* "end": load content scripts once all the content (DOM, JS, CSS, -images) for the page has been loaded, at the time the -[window.onload event](https://developer.mozilla.org/en/DOM/window.onload) -fires - -</api> - -<api name="contentURL"> -@property {string} -The URL of the content loaded. -</api> - -<api name="allow"> -@property {object} -Permissions for the content, with a single boolean key called `script` which -defaults to true and indicates whether or not to execute scripts in the -content. -</api> - -</api> - - diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/content/worker.md b/tools/addon-sdk-1.3/packages/api-utils/docs/content/worker.md deleted file mode 100644 index ec9bb3a..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/content/worker.md +++ /dev/null @@ -1,126 +0,0 @@ -<!-- contributed by Irakli Gozalishvili [gozala@mozilla.com] --> - -This module exports the `Worker` trait, which may be used to construct objects -implementing the [Worker][] interface defined by the W3C, with minor -differences. - -Content workers are message-passing facilities for communication between -[content scripts](dev-guide/addon-development/web-content.html) and the main -add-on code. - -It is important to note that unlike "web workers," these workers run in the -same process as web content and browser chrome, so code within workers can -block the UI. - -[Worker]:http://www.w3.org/TR/workers/#worker - -<api name="Worker"> -@class -Worker is composed from the [EventEmitter][] trait, therefore instances -of Worker and their descendants expose all the public properties -exposed by [EventEmitter][] along with additional public properties that -are listed below. - -**Example** - - var workers = require("content/worker"); - let worker = workers.Worker({ - window: require("window-utils").activeWindow, - contentScript: - "self.port.on('hello', function(name) { " + - " self.port.emit('response', window.location); " + - "});" - }); - worker.port.emit("hello", { name: "worker"}); - worker.port.on("response", function (location) { - console.log(location); - }); - -[EventEmitter]:packages/api-utils/docs/events.html - -<api name="Worker"> -@constructor -Creates a content worker. -@param options {object} -Options for the constructor, with the following keys: - @prop window {object} - The content window to create JavaScript sandbox for communication with. - @prop [contentScriptFile] {string,array} - The local file URLs of content scripts to load. Content scripts specified - by this option are loaded *before* those specified by the `contentScript` - option. Optional. - @prop [contentScript] {string,array} - The texts of content scripts to load. Content scripts specified by this - option are loaded *after* those specified by the `contentScriptFile` option. - Optional. - @prop [onMessage] {function} - Functions that will registered as a listener to a 'message' events. - @prop [onError] {function} - Functions that will registered as a listener to an 'error' events. -</api> - -<api name="port"> -@property {EventEmitter} -[EventEmitter](packages/api-utils/docs/events.html) object that allows you to: - -* send customized messages to the worker using the `port.emit` function -* receive events from the worker using the `port.on` function - -</api> - -<api name="postMessage"> -@method -Asynchronously emits `"message"` events in the enclosed worker, where content -script was loaded. -@param data {number,string,JSON} -The data to send. Must be stringifiable to JSON. -</api> - -<api name="destroy"> -@method -Destroy the worker by removing the content script from the page and removing -all registered listeners. A `detach` event is fired just before removal. -</api> - -<api name="url"> -@property {string} -The URL of the content. -</api> - -<api name="tab"> -@property {object} -If this worker is attached to a content document, returns the related -[tab](packages/addon-kit/docs/tabs.html). -</api> - -<api name="message"> -@event -This event allows the content worker to receive messages from its associated -content scripts. Calling the `self.postMessage()` function from a content -script will asynchronously emit the `message` event on the corresponding -worker. - -@argument {value} -The event listener is passed the message, which must be a -<a href = "dev-guide/addon-development/content-scripts/using-port.html#json_serializable">JSON-serializable value</a>. -</api> - -<api name="error"> -@event -This event allows the content worker to react to an uncaught runtime script -error that occurs in one of the content scripts. - -@argument {Error} -The event listener is passed a single argument which is an -[Error](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error) -object. -</api> - -<api name="detach"> -@event -This event is emitted when the document associated with this worker is unloaded -or the worker's `destroy()` method is called. -</api> - -</api> - diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/cortex.md b/tools/addon-sdk-1.3/packages/api-utils/docs/cortex.md deleted file mode 100644 index 87a8eda..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/cortex.md +++ /dev/null @@ -1,156 +0,0 @@ - -## Property Encapsulation ## - -In JavaScript it is not possible to create properties that have limited or -controlled accessibility. It is possible to create non-enumerable and -non-writable properties, but still they can be discovered and accessed. -Usually so called "closure capturing" is used to encapsulate such properties -in lexical scope: - - function Foo() { - var _secret = 'secret'; - this.hello = function hello() { - return 'Hello ' + _secret; - } - } - -This provides desired result, but has side effect of degrading code readability, -especially with object-oriented programs. Another disadvantage with this pattern -is that there is no immediate solution for inheriting access to the privates -(illustrated by the following example): - - function Derived() { - this.hello = function hello() { - return _secret; - } - this.bye = function bye() { - return _secret; - } - } - Derived.prototype = Object.create(Foo.prototype); - -## Facade Objects ## - -Alternatively constructor can returned facade objects - proxies to the -instance's public properties: - - function Foo() { - var foo = Object.create(Foo.prototype); - return { - bar: foo.hello.bind(foo); - } - } - Foo.prototype._secret = 'secret'; - Foo.prototype.hello = function hello() { - return 'Hello ' + this._secret; - } - - function Derived() { - var derived = Object.create(Derived.prototype); - return { - bar: derived.hello.bind(derived); - bye: derived.bye.bind(derived); - } - } - Derived.prototype = Object.create(Foo.prototype); - Derived.prototype.bye = function bye() { - return 'Bye ' + this._secret; - }; - -While this solution solves given issue and provides proper encapsulation for -both own and inherited private properties, it does not addresses following: - - - Privates defined on the `prototype` can be compromised, since they are - accessible through the constructor (`Foo.prototype._secret`). - - Behavior of `instanceof` is broken, since `new Derived() instanceof Derived` - is going to evaluate to `false`. - -## Tamper Proofing with Property Descriptor Maps ## - -In ES5 new property descriptor maps were introduced, which can be used as a -building blocks for defining reusable peace of functionality. To some degree -they are similar to a `prototype` objects, and can be used so to define pieces -of functionality that is considered to be private (In contrast to `prototype` -they are not exposed by default). - - function Foo() { - var foo = Object.create(Foo.prototype, FooDescriptor); - var facade = Object.create(Foo.prototype); - facade.hello = foo.hello.bind(foo); - return facade; - } - Foo.prototype.hello = function hello() { - return 'Hello ' + this._secret; - } - var FooDescriptor = { - _secret: { value: 'secret' }; - } - - function Derived() { - var derived = Object.create(Derived.prototype, DerivedDescriptor); - var facade = Object.create(Derived.prototype); - facade.hello = derived.hello.bind(derived); - facade.bye = derived.bye.bind(derived); - return facade; - } - Derived.prototype = Object.create(Foo.prototype); - Derived.prototype.bye = function bye() { - return 'Bye ' + this._secret; - }; - DerivedDescriptor = {}; - - Object.keys(FooDescriptor).forEach(function(key) { - DerivedDescriptor[key] = FooDescriptor[key]; - }); - -## Cortex Objects ## - -Last approach solves all of the concerns, but adds complexity, verbosity -and decreases code readability. Combination of `Cortex`'s and `Trait`'s -will gracefully solve all these issues and keep code clean: - - var Cortex = require('cortex').Cortex; - var Trait = require('light-traits').Trait; - - var FooTrait = Trait({ - _secret: 'secret', - hello: function hello() { - return 'Hello ' + this._secret; - } - }); - function Foo() { - return Cortex(FooTrait.create(Foo.prototype)); - } - - var DerivedTrait = Trait.compose(FooTrait, Trait({ - bye: function bye() { - return 'Bye ' + this._secret; - } - })); - function Derived() { - var derived = DerivedTrait.create(Derived.prototype); - return Cortex(derived); - } - -Function `Cortex` takes any object and returns a proxy for its public -properties. By default properties are considered to be public if they don't -start with `"_"`, but default behavior can be overridden if needed, by passing -array of public property names as a second argument. - -## Gotchas ## - -`Cortex` is just a utility function to create a proxy object, and it does not -solve the `prototype`-related issues highlighted earlier, but since traits make -use of property descriptor maps instead of `prototype`s, there aren't any -issues with using `Cortex` to wrap objects created from traits. - -If you want to use `Cortex` with an object that uses a `prototype` chain, -however, you should either make sure you don't have any private properties -in the prototype chain or pass the optional third `prototype` argument. - -In the latter case, the returned proxy will inherit from the given prototype, -and the `prototype` chain of the wrapped object will be inaccessible. -However, note that the behavior of the `instanceof` operator will vary, -as `proxy instanceof Constructor` will return false even if the Constructor -function's prototype is in the wrapped object's prototype chain. - diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/cuddlefish.md b/tools/addon-sdk-1.3/packages/api-utils/docs/cuddlefish.md deleted file mode 100644 index 6177c53..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/cuddlefish.md +++ /dev/null @@ -1,5 +0,0 @@ -`cuddlefish` is the name of the SDK's module loader. It builds on -`securable-module` to provide many SDK-specific globals such as `console` -and `memory`. - -This module still needs to be documented. diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/e10s.md b/tools/addon-sdk-1.3/packages/api-utils/docs/e10s.md deleted file mode 100644 index 3e2f047..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/e10s.md +++ /dev/null @@ -1,218 +0,0 @@ -<span class="aside"> -For a high-level overview of out-of-process add-ons, see the -[Out-of-Process Add-ons][] internals guide. -</span> - -The `e10s` module allows add-ons to execute in a separate process from Firefox -itself. - -## Adapters ## - -As explained in the [Out-of-Process Add-ons][] internals guide, an *e10s -adapter* is the primary mechanism through which chrome functionality is exposed -to add-on processes. It is a single piece of code evaluated *twice*—once -in each process—and typically has the following form: - - if (this.chrome) { - /* We're being evaluated in the add-on process. Export the - * module's API, proxying all calls to the chrome process - * as necessary. */ - } else exports.register = function register(addon) { - /* We're being evaluated in the chrome process. - * Set up chrome process listeners to communicate with - * the given add-on process. */ - }; - -In the above code, the `chrome` global is only visible to this code when it is -executed in the add-on process. It is an instance of `ChromeProcess`. - -The `register()` function, on the other hand, is only defined and called in the -chrome process, and the `addon` argument passed to it is an instance of -`AddonProcess`. - -`ChromeProcess` and `AddonProcess` instances come in pairs, and represent -opposite sides of an inter-process communication mechanism. - - [Out-of-Process Add-ons]: dev-guide/module-development/e10s.html - -## Events ## - -Chrome and add-on processes can asynchronously send arbitrary events to each -other. The <code>[EventEmitter][]</code> interface has been overloaded to make -handling these events simple and intuitive. For instance, here's a trivial e10s -adapter that uses events: - - if (this.chrome) { - exports.sendFoo = function(x) { - chrome.send('foo', x); - }; - } else exports.register = function register(addon) { - addon.on('foo', function(type, x) { - console.log("foo called with argument", x); - }); - }; - - [EventEmitter]: packages/api-utils/docs/events.html - -## Remote Function Calls ## - -The add-on process can synchronously call a function on the chrome process, but -not vice versa. Here's a trivial example of an e10s adapter using this -mechanism: - - if (this.chrome) { - exports.bar = function(x) { - return chrome.call('bar', x); - }; - } else exports.register = function register(addon) { - addon.registerCall('bar', function(name, x) { - return x * 3; - }); - }; - -## Arguments ## - -When sending events or calling functions in another process, the chrome and -add-on processes are allowed to send JSON-serializable arguments. Additionally, -they can send a special type of object called a *handle*. See the -[MDN Handle Documentation][] for more information on these. - -Here's a simple example of a handle being used to remember a callback function -on the add-on side: - - if (this.chrome) { - exports.baz = function(callback) { - var handle = chrome.createHandle(); - handle.callback = callback; - chrome.send('baz', handle); - }; - chrome.on('bazCallback', function(name, handle) { - try { handle.callback(); } except (e) { console.exception(e); } - handle.invalidate(); - }); - } else exports.register = function register(addon) { - addon.on('baz', function(name, handle) { - require('timer').setTimeout(function() { - addon.send('bazCallback', handle); - }, 1000); - }); - }; - - [MDN Handle Documentation]: https://developer.mozilla.org/en/Jetpack_Processes#Handles - -<api name="ChromeProcess"> -@class - In an add-on process, this represents the parent chrome process. This class is - a singleton and has no constructor. It is automatically injected into the - global scope of all `-e10s-adapter` modules as the `chrome` object. - -<api name="on"> -@method - Registers an event listener with the chrome process. -@param type {string} - The type of event to listen for. -@param listener {function} - The listener function that handles the event. Its first argument is always - `type`, and additional arguments vary depending on the event's originating - `addon.send()` call in the chrome process. -</api> - -<api name="removeListener"> -@method - Removes an event listener from the chrome process. -@param type {string} - The type of event for which `listener` was registered. -@param listener {function} - The listener function that was registered. -</api> - -<api name="send"> -@method - Sends an event asynchronously to the chrome process. Any additional arguments - after `type` are passed as arguments to event listeners in the chrome process. -@param type {string} - The type of event to send. -</api> - -<api name="call"> -@method - Synchronously calls a remote function in the chrome process and returns its - result. Any additional arguments after `name` are passed as arguments to the - function in the chrome process. -@param name {string} - The name of the function to call. -</api> - -<api name="createHandle"> -@method - Creates a [handle][] object, which can be passed to the chrome process via - `send()` or `call()`. - - [handle]: https://developer.mozilla.org/en/Jetpack_Processes#Handles -</api> - -</api> - -<api name="AddonProcess"> -@class - In the chrome process, this represents a child add-on process. - -<api name="AddonProcess"> -@constructor - Creates a new add-on process. - -@param options {object} - An optional object with the following keys, all of which are optional: - - @prop [console] {object} - An object whose interface corresponds to that of the `console` global. All - logging messages to the `console` object of the addon will be redirected to - this object. If this object isn't provided, then the global `console` object - of the chrome process will be used. -</api> - -<api name="destroy"> -@method - Terminates the add-on process. -</api> - -<api name="on"> -@method - Registers an event listener with the add-on process. -@param type {string} - The type of event to listen for. -@param listener {function} - The listener function that handles the event. Its first argument is always - `type`, and additional arguments vary depending on the event's originating - `chrome.send()` call in the add-on process. -</api> - -<api name="registerCall"> -@method - Registers a synchronous call handler with the add-on process. -@param name {string} - The name of the function. -@param handler {function} - The call handler. Its first argument is always `name`, and additional - arguments vary depending on the call's originating `chrome.call()` invocation - in the add-on process. The handler's return value is also passed back to the - original caller in the add-on process. -</api> - -<api name="send"> -@method - Sends an event asynchronously to the add-on process. Any additional arguments - after `type` are passed as arguments to event listeners in the add-on process. -@param type {string} - The type of event to send. -</api> - -<api name="createHandle"> -@method - Creates a [handle][] object, which can be passed to the add-on process via - `send()`. - - [handle]: https://developer.mozilla.org/en/Jetpack_Processes#Handles -</api> - -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/errors.md b/tools/addon-sdk-1.3/packages/api-utils/docs/errors.md deleted file mode 100644 index 3ce5b19..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/errors.md +++ /dev/null @@ -1,38 +0,0 @@ -<!-- contributed by Drew Willcoxon [adw@mozilla.com] --> - -The `errors` module provides helpers for safely invoking user callbacks. - -<api name="catchAndLog"> -@function - Wraps a callback in a function that when invoked will catch and log any - exception thrown by the callback. -@param callback {function} - The callback to wrap. -@param [defaultResponse] {value} - This value will be returned by the wrapper if `callback` throws an exception. - If not given, `undefined` is used. -@param [logException] {function} - When `callback` throws an exception, it will be passed to this function. If - not given, the exception is logged using `console.exception()`. -@returns {function} - A function that will invoke `callback` when called. The return value of this - function is the return value of `callback` unless `callback` throws an - exception. In that case, `defaultResponse` is returned or `undefined` if - `defaultResponse` is not given. -</api> - -<api name="catchAndLogProps"> -@function - Replaces methods of an object with wrapped versions of those methods returned - by `catchAndLog()`. -@param object {object} - The object whose methods to replace. -@param props {string,array} - The names of the methods of `object` to replace, either a string for a single - method or an array of strings for multiple methods. -@param [defaultResponse] {value} - This value will be returned by any wrapper whose wrapped method throws an - exception. If not given, `undefined` is used. -@param [logException] {function} - See `catchAndLog()`. -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/es5.md b/tools/addon-sdk-1.3/packages/api-utils/docs/es5.md deleted file mode 100644 index 0906b0d..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/es5.md +++ /dev/null @@ -1,52 +0,0 @@ -The `es5` module provides shim layer to a versions of Firefox that do not yet -implement certain EcmaScript 5 features. - -For more information on EcmaScript 5: - -* The new APIs are described in the official [ES5 specification][]. -* A good [introduction][] to the new APIs by John Resig. -* A Google tech talk on [changes to JavaScript][]. - -**There is no need to `require` this module** since it gets preloaded into -all sandboxes automatically. - -Usage of new ES5 API's is encouraged, but since not everything can be -provided to all the versions of firefox, there are few things to be aware of: - -`Object.freeze`, `Object.seal`, `Object.preventExtensions` does not really -prevents any mutations. One thing it guarantees though, `Object.isFrozen`, -`Object.isSealed`, `Object.isExtensible` checks will behave as defined in -specification. - -`Object.defineProperty` is only partially compliant with the specification: - -- Non configurable properties will be created as configurable ones. - -- Instead of non-writable properties getters and setters will be defined, -but `Object.getOwnPropertyDescriptor` will still behave as expected -(will return property descriptor for non-writable property not a getter) - -- Defining properties using ES5 functions will break your - [custom iterators][] if you have any. Think twice before employing - custom iterators, because in most cases you can just make properties - non enumerable. If you really need to have a custom iterator, add it - after running ES5 functions and don't ignore previous iterators. - For example: - - let object = Object.create({}, { - myField: { value: 6 } - }); - object.__iterator__ = (function(original) { - return function myIterator() { - this.__iterator__ = original; - for (let key in this) { - // your logic here - } - this.__iterator__ = myIterator; - } - })(object.__iterator__); - -[custom iterators]:https://developer.mozilla.org/en/New_in_JavaScript_1.7#Iterators -[ES5 specification]:http://www.ecmascript.org/docs/tc39-2009-043.pdf -[introduction]:http://ejohn.org/blog/ecmascript-5-objects-and-properties/ -[changes to JavaScript]:http://www.youtube.com/watch?v=Kq4FpMe6cRs diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/events.md b/tools/addon-sdk-1.3/packages/api-utils/docs/events.md deleted file mode 100644 index cb74c77..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/events.md +++ /dev/null @@ -1,74 +0,0 @@ -The `events` module provides base API for emitting events. - -This module is not intended to be used directly by programs. Rather, it is -intended to be used by other modules that provide APIs to programs. - -<api name="EventEmitter"> -@class -The EventEmitter is the base building block for all compositions that -would need to broadcast data to multiple consumers. - -Please note that `EventEmitter` does not expose either a method for emitting -events or a list of available event listeners as its public API. Obviously -both are accessible but from the instance itself through the private API. -<api name="EventEmitter"> -@constructor -Creates an EventEmitter object. -</api> - -<api name="on"> -@method -Registers an event `listener` that will be called when events of -specified `type` are emitted. - -If the `listener` is already registered for this `type`, a call to this -method has no effect. - -If the event listener is being registered while an event is being processed, -the event listener is not called during the current emit. - -**Example:** - - // worker is instance of EventEmitter - worker.on('message', function (data) { - console.log('data received: ' + data) - }); - -@param type {String} - The type of the event. -@param listener {Function} - The listener function that processes the event. -</api> - -<api name="once"> -@method -Registers an event `listener` that will only be called once, the next time -an event of the specified `type` is emitted. - -If the event listener is registered while an event of the specified `type` -is being emitted, the event listener will not be called during the current -emit. - -@param type {String} - The type of the event. -@param listener {Function} - The listener function that processes the event. -</api> - -<api name="removeListener"> -@method -Unregisters an event `listener` for the specified event `type`. - -If the `listener` is not registered for this `type`, a call to this -method has no effect. - -If an event listener is removed while an event is being processed, it is -still triggered by the current emit. After it is removed, the event listener -is never invoked again (unless registered again for future processing). - -@param type {String} - The type of the event. -@param listener {Function} - The listener function that processes the event. -</api> -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/file.md b/tools/addon-sdk-1.3/packages/api-utils/docs/file.md deleted file mode 100644 index 3dd4fb2..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/file.md +++ /dev/null @@ -1,147 +0,0 @@ -<!-- contributed by Drew Willcoxon [adw@mozilla.com] --> -<!-- contributed by Atul Varma [atul@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> - -The `file` module provides access to the local filesystem. - - -Paths ------ - -Path specifications in this API are platform-specific. This means that on -Windows paths are specified using the backslash path separator (`\`), and on -Unix-like systems like Linux and OS X paths are specified using the forward -slash path separator (`/`). - -If your add-on uses literal Windows-style path specifications with this API, -your add-on likely won't work when users run it on Unix-like systems. Likewise, -if your add-on uses literal Unix-style path specifications, it won't work for -users on Windows. - -To ensure your add-on works for everyone, generate paths using the -[`join`](packages/api-utils/docs/file.html#join(...)) function. Unfortunately -this API does not currently provide a way to obtain an absolute base path which -you could then use with `join`. For now, you need to -[`require("chrome")`](dev-guide/module-development/chrome.html) and use the -XPCOM directory service as described at -[MDN](https://developer.mozilla.org/en/Code_snippets/File_I%2F%2FO#Getting_special_files). - -Note that if you do decide to hardcode Windows-style paths, be sure to escape -backslashes in strings. For example, to specify the file at `C:\Users\Myk`, you -need to use the string `"C:\\Users\\Myk"`, not `"C:\Users\Myk"`. You can read -more about escaping characters in strings at -[MDN](https://developer.mozilla.org/en/JavaScript/Guide/Values,_Variables,_and_Literals#Escaping_Characters). - - -<api name="basename"> -@function - Returns the last component of the given path. For example, - `basename("/foo/bar/baz")` returns `"baz"`. If the path has no components, - the empty string is returned. -@param path {string} - The path of a file. -@returns {string} - The last component of the given path. -</api> - -<api name="dirname"> -@function - Returns the path of the directory containing the given file. If the file is - at the top of the volume, the empty string is returned. -@param path {string} - The path of a file. -@returns {string} - The path of the directory containing the file. -</api> - -<api name="exists"> -@function - Returns true if a file exists at the given path and false otherwise. -@param path {string} - The path of a file. -@returns {boolean} - True if the file exists and false otherwise. -</api> - -<api name="join"> -@function - Takes a variable number of strings, joins them on the file system's path - separator, and returns the result. -@param ... {strings} - A variable number of strings to join. The first string must be an absolute - path. -@returns {string} - A single string formed by joining the strings on the file system's path - separator. -</api> - -<api name="list"> -@function - Returns an array of file names in the given directory. -@param path {string} - The path of the directory. -@returns {array} - An array of file names. Each is a basename, not a full path. -</api> - -<api name="mkpath"> -@function - Makes a new directory named by the given path. Any subdirectories that do not - exist are also created. `mkpath` can be called multiple times on the same - path. -@param path {string} - The path to create. -</api> - -<api name="open"> -@function - Returns a stream providing access to the contents of a file. -@param path {string} - The path of the file to open. -@param [mode] {string} - An optional string, each character of which describes a characteristic of the - returned stream. If the string contains `"r"`, the file is opened in - read-only mode. `"w"` opens the file in write-only mode. `"b"` opens the - file in binary mode. If `"b"` is not present, the file is opened in text - mode, and its contents are assumed to be UTF-8. If *`mode`* is not given, - `"r"` is assumed, and the file is opened in read-only text mode. -@returns {stream} - If the file is opened in text read-only `mode`, a `TextReader` is returned, - and if text write-only mode, a `TextWriter` is returned. See - [`text-streams`](packages/api-utils/docs/text-streams.html) for information on - these text stream objects. If the file is opened in binary read-only `mode`, - a `ByteReader` is returned, and if binary write-only mode, a `ByteWriter` is - returned. See - [`byte-streams`](packages/api-utils/docs/byte-streams.html) for more - information on these byte stream objects. Opened files should always be - closed after use by calling `close` on the returned stream. -</api> - -<api name="read"> -@function - Opens a file and returns a string containing its entire contents. -@param path {string} - The path of the file to read. -@param [mode] {string} - An optional string, each character of which describes a characteristic of the - returned stream. If the string contains `"b"`, the contents will be returned - in binary mode. If `"b"` is not present or `mode` is not given, the file - contents will be returned in text mode. -@returns {string} - A string containing the file's entire contents. -</api> - -<api name="remove"> -@function - Removes a file from the file system. To remove directories, use `rmdir`. -@param path {string} - The path of the file to remove. -</api> - -<api name="rmdir"> -@function - Removes a directory from the file system. If the directory is not empty, an - exception is thrown. -@param path {string} - The path of the directory to remove. -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/hidden-frame.md b/tools/addon-sdk-1.3/packages/api-utils/docs/hidden-frame.md deleted file mode 100644 index 47cd23b..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/hidden-frame.md +++ /dev/null @@ -1,79 +0,0 @@ -<!-- contributed by Myk Melez [myk@mozilla.org] --> - -The `hidden-frame` module creates host application frames (i.e. XUL `<iframe>` -elements) that are not displayed to the user. It is useful in the construction -of APIs that load web content not intended to be directly seen or accessed -by users, like `page-worker`. It is also useful in the construction of APIs -that load web content for intermittent display, such as `panel`. - -This module is not intended to be used directly by programs. Rather, it is -intended to be used by other modules that provide APIs to programs. - -Introduction ------------- - -The module exports a constructor function, `HiddenFrame`, and two other -functions, `add` and `remove`. - -`HiddenFrame` constructs a new hidden frame. `add` registers a hidden frame, -preparing it to load content. `remove` unregisters a frame, unloading any -content that was loaded in it. - -Examples --------- - -The following code creates a hidden frame, loads a web page into it, and then -logs its title: - - var hiddenFrames = require("hidden-frame"); - let hiddenFrame = hiddenFrames.add(hiddenFrames.HiddenFrame({ - onReady: function() { - this.element.contentWindow.location = "http://www.mozilla.org/"; - let self = this; - this.element.addEventListener("DOMContentLoaded", function() { - console.log(self.element.contentDocument.title); - }, true, true); - } - })); - -See the `panel` module for a real-world example of usage of this module. - -Reference ---------- -<api name="HiddenFrame"> -@class -`HiddenFrame` objects represent hidden frames. -<api name="HiddenFrame"> -@constructor -Creates a hidden frame. -@param options {object} - Options for the frame, with the following keys: - @prop onReady {function,array} - Functions to call when the frame is ready to load content. You must specify - an `onReady` callback and refrain from using the hidden frame until - the callback gets called, because hidden frames are not always ready to load - content the moment they are added. -</api> - -<api name="add"> -@function -Register a hidden frame, preparing it to load content. -@param hiddenFrame {HiddenFrame} the frame to add -</api> - -<api name="remove"> -@function -Unregister a hidden frame, unloading any content that was loaded in it. -@param hiddenFrame {HiddenFrame} the frame to remove -</api> - -<api name="element"> -@property {DOMElement} -The host application frame in which the page is loaded. -</api> - -<api name="onReady"> -@property {array} -Functions to call when the frame is ready to load content. -</api> -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/light-traits.md b/tools/addon-sdk-1.3/packages/api-utils/docs/light-traits.md deleted file mode 100644 index 1257c2a..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/light-traits.md +++ /dev/null @@ -1,291 +0,0 @@ - -[Traits](http://en.wikipedia.org/wiki/Trait_%28computer_science%29) are a simple -mechanism for structuring object-oriented programs. They represent reusable and -composable building blocks of functionality that factor out the common -attributes and behavior of objects. - -They are a more robust alternative to -[mixins](http://en.wikipedia.org/wiki/Mixins) and -[multiple inheritance](http://en.wikipedia.org/wiki/Multiple_inheritance), -because name clashes must be explicitly resolved and composition is commutative -and associative (i.e. the order of traits in a composition is irrelevant). - -Use traits to share functionality between similar objects without duplicating -code or creating complex inheritance chains. - -## Trait Creation ## - -To create a trait, call the `Trait` constructor function exported by this -module, passing it a JavaScript object that specifies the properties of the -trait. - - let Trait = require('light-traits').Trait; - let t = Trait({ - foo: "foo", - bar: function bar() { - return "Hi!" - }, - baz: Trait.required - }); - -Traits can both provide and require properties. A *provided* property is a -property for which the trait itself provides a value. A *required* property is a -property that the trait needs in order to function correctly but for which -it doesn't provide a value. - -Required properties must be provided by another trait or by an object with a -trait. Creation of an object with a trait will fail if required properties are -not provided. Specify a required property by setting the value of the property -to `Trait.required`. - -## Object Creation ## - -Create objects with a single trait by calling the trait's `create` method. The -method takes a single argument, the object to serve as the new object's -prototype. If no prototype is specified, the new object's prototype will be -`Object.prototype`. - - let t = Trait({ - foo: 'foo', - bar: 2 - }); - let foo1 = t.create(); - let foo2 = t.create({ name: 'Super' }); - -## Trait Composition ## - -Traits are designed to be composed with other traits to create objects with the -properties of multiple traits. To compose an object with multiple traits, you -first create a composite trait and then use it to create the object. A composite -trait is a trait that contains all of the properties of the traits from which it -is composed. In the following example, MagnitudeTrait is a composite trait. - - let EqualityTrait = Trait({ - equal: Trait.required, - notEqual: function notEqual(x) { - return !this.equal(x) - } - }); - - let ComparisonTrait = Trait({ - less: Trait.required, - notEqual: Trait.required, - greater: function greater(x) { - return !this.less(x) && this.notEqual(x) - } - }); - - let MagnitudeTrait = Trait.compose(EqualityTrait, ComparisonTrait); - -<?xml version="1.0"?> -<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" version="1.1" viewBox="-11 121 490 190" width="490px" height="190px"> - <defs> - <marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="SharpArrow_Marker" viewBox="-4 -4 10 8" markerWidth="10" markerHeight="8" color="black"> - <g> - <path d="M 5 0 L -3 -3 L 0 0 L 0 0 L -3 3 Z" fill="currentColor" stroke="currentColor" stroke-width="1px"/> - </g> - </marker> - </defs> - <g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1"> - <g> - <rect x="9" y="165.33334" width="141" height="14"/> - <rect x="9" y="165.33334" width="141" height="14" stroke="black" stroke-width="1px"/> - <text transform="translate(14 165.33334)" fill="black"> - <tspan font-family="Helvetica" font-size="12" font-weight="500" x="0" y="11" textLength="47.373047">notEqual</tspan> - </text> - <rect x="9" y="151.33334" width="141" height="14"/> - <rect x="9" y="151.33334" width="141" height="14" stroke="black" stroke-width="1px"/> - <text transform="translate(14 151.33334)" fill="red"> - <tspan font-family="Helvetica" font-size="12" font-weight="500" fill="red" x="0" y="11" textLength="29.361328">equal</tspan> - </text> - <rect x="9" y="137.33334" width="141" height="14"/> - <rect x="9" y="137.33334" width="141" height="14" stroke="black" stroke-width="1px"/> - <text transform="translate(14 137.33334)" fill="black"> - <tspan font-family="Helvetica" font-size="12" font-weight="bold" x="38.49707" y="11" textLength="54.00586">EqualityTrait</tspan> - </text> - <rect x="9" y="273" width="141" height="14"/> - <rect x="9" y="273" width="141" height="14" stroke="black" stroke-width="1px"/> - <text transform="translate(14 273)" fill="black"> - <tspan font-family="Helvetica" font-size="12" font-weight="500" x="0" y="11" textLength="38.021484">greater</tspan> - </text> - <rect x="9" y="259" width="141" height="14"/> - <rect x="9" y="259" width="141" height="14" stroke="black" stroke-width="1px"/> - <text transform="translate(14 259)" fill="red"> - <tspan font-family="Helvetica" font-size="12" font-weight="500" fill="red" x="0" y="11" textLength="47.373047">notEqual</tspan> - </text> - <rect x="9" y="245" width="141" height="14"/> - <rect x="9" y="245" width="141" height="14" stroke="black" stroke-width="1px"/> - <text transform="translate(14 245)" fill="red"> - <tspan font-family="Helvetica" font-size="12" font-weight="500" fill="red" x="0" y="11" textLength="21.339844">less</tspan> - </text> - <rect x="9" y="231" width="141" height="14"/> - <rect x="9" y="231" width="141" height="14" stroke="black" stroke-width="1px"/> - <text transform="translate(14 231)" fill="black"> - <tspan font-family="Helvetica" font-size="12" font-weight="bold" x=".15332031" y="11" textLength="112.67578">ComparisonTrait</tspan> - </text> - <rect x="317.75" y="235.5" width="141" height="14"/> - <rect x="317.75" y="235.5" width="141" height="14" stroke="black" stroke-width="1px"/> - <text transform="translate(322.75 235.5)" fill="black"> - <tspan font-family="Helvetica" font-size="12" font-weight="500" x="0" y="11" textLength="38.021484">greater</tspan> - </text> - <rect x="317.75" y="221.5" width="141" height="14"/> - <rect x="317.75" y="221.5" width="141" height="14" stroke="black" stroke-width="1px"/> - <text transform="translate(322.75 221.5)" fill="red"> - <tspan font-family="Helvetica" font-size="12" font-weight="500" fill="red" x="0" y="11" textLength="21.339844">less</tspan> - </text> - <rect x="317.75" y="207.5" width="141" height="14"/> - <rect x="317.75" y="207.5" width="141" height="14" stroke="black" stroke-width="1px"/> - <text transform="translate(322.75 207.5)" fill="black"> - <tspan font-family="Helvetica" font-size="12" font-weight="500" x="0" y="11" textLength="47.373047">notEqual</tspan> - </text> - <rect x="317.75" y="193.5" width="141" height="14"/> - <rect x="317.75" y="193.5" width="141" height="14" stroke="black" stroke-width="1px"/> - <text transform="translate(322.75 193.5)" fill="red"> - <tspan font-family="Helvetica" font-size="12" font-weight="500" fill="red" x="0" y="11" textLength="29.361328">equal</tspan> - </text> - <rect x="317.75" y="179.5" width="141" height="14"/> - <rect x="317.75" y="179.5" width="141" height="14" stroke="black" stroke-width="1px"/> - <text transform="translate(322.75 179.5)" fill="black"> - <tspan font-family="Helvetica" font-size="12" font-weight="bold" x="31.83789" y="11" textLength="67.32422">MagnitudeTrait</tspan> - </text> - <path d="M 150 248.83887 L 158.89999 248.83887 L 235.9 248.83887 L 235.9 224.66113 L 308.85 224.66113 L 310.85 224.66113" marker-end="url(#SharpArrow_Marker)" stroke="black" stroke-linecap="butt" stroke-linejoin="miter" stroke-width="1px"/> - <path d="M 150 171.15845 L 158.89999 171.15845 L 233.9 171.15845 L 233.9 201.6749 L 308.85 201.6749 L 310.85 201.6749" marker-end="url(#SharpArrow_Marker)" stroke="black" stroke-linecap="butt" stroke-linejoin="miter" stroke-width="1px"/> - </g> - </g> -</svg> - -## Trait Resolution ## - -Composite traits have conflicts when two of the traits in the composition -provide properties with the same name but different values (when compared using -the `===` strict equality operator). In the following example, `TC` has a -conflict because `T1` and `T2` both define a `foo` property: - - let T1 = Trait({ - foo: function () { - // do something - }, - bar: 'bar', - t1: 1 - }); - - let T2 = Trait({ - foo: function() { - // do something else - }, - bar: 'bar', - t2: 2 - }); - - let TC = Trait.compose(T1, T2); - -Attempting to create an object from a composite trait with conflicts throws a -`remaining conflicting property` exception. To create objects from such traits, -you must resolve the conflict. - -You do so by excluding or renaming the conflicting property of one of the -traits. Excluding a property removes it from the composition, so the composition -only acquires the property from the other trait. Renaming a property gives it a -new, non-conflicting name at which it can be accessed. - -In both cases, you call the `resolve` method on the trait whose property you -want to exclude or rename, passing it an object. Each key in the object is the -name of a conflicting property; each value is either `null` to exclude the -property or a string representing the new name of the property. - -For example, the conflict in the previous example could be resolved by excluding -the `foo` property of the second trait. - - let TC = Trait(T1, T2.resolve({ foo: null })); - -It could also be resolved by renaming the `foo` property of the first trait to -`foo2`: - - let TC = Trait(T1.resolve({ foo: "foo2" }), T2); - -When you resolve a conflict, the same-named property of the other trait (the one -that wasn't excluded or renamed) remains available in the composition under its -original name. - -## Constructor Functions ## - -When your code is going to create more than one object with traits, you may want -to define a constructor function to create them. To do so, create a composite -trait representing the traits the created objects should have, then define a -constructor function that creates objects with that trait and whose prototype is -the prototype of the constructor: - - let PointTrait = Trait.compose(T1, T2, T3); - function Point(options) { - let point = PointTrait.create(Point.prototype); - return point; - } - -## Property Descriptor Maps ## - -Traits are designed to work with the new object manipulation APIs defined in -[ECMAScript-262, Edition -5](http://www.ecma-international.org/publications/standards/Ecma-262.htm) (ES5). -Traits are also property descriptor maps that inherit from `Trait.prototype` to -expose methods for creating objects and resolving conflicts. - -The following trait definition: - - let FooTrait = Trait({ - foo: "foo", - bar: function bar() { - return "Hi!" - }, - baz: Trait.required - }); - -Creates the following property descriptor map: - - { - foo: { - value: 'foo', - enumerable: true, - configurable: true, - writable: true - }, - - bar: { - value: function b() { - return 'bar' - }, - enumerable: true, - configurable: true, - writable: true - }, - - baz: { - get baz() { throw new Error('Missing required property: `baz`') } - set baz() { throw new Error('Missing required property: `baz`') } - }, - - __proto__: Trait.prototype - } - -Since Traits are also property descriptor maps, they can be used with built-in -`Object.*` methods that accept such maps: - - Object.create(proto, FooTrait); - Object.defineProperties(myObject, FooTrait); - -Note that conflicting and required properties won't cause exceptions to be -thrown when traits are used with the `Object.*` methods, since those methods are -not aware of those constraints. However, such exceptions will be thrown when the -property with the conflict or the required but missing property is accessed. - -Property descriptor maps can also be used in compositions. This may be useful -for defining non-enumerable properties, for example: - - let TC = Trait.compose( - Trait({ foo: 'foo' }), - { bar: { value: 'bar', enumerable: false } } - ); - -_When using property descriptor maps in this way, make sure the map is not the -only argument to `Trait.compose`, since in that case it will be interpreted as -an object literal with properties to be defined._ - diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/list.md b/tools/addon-sdk-1.3/packages/api-utils/docs/list.md deleted file mode 100644 index 8e1a522..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/list.md +++ /dev/null @@ -1,94 +0,0 @@ -<!-- contributed by Irakli Gozalishvili [gozala@mozilla.com] --> - -The `"list"` module provides base building blocks for composing lists. - -<api name="Iterable"> -@class -Base trait that can be used to compose traits with non-standard -enumeration behaviors. - -This trait is supposed to be used as part of a composition, since it only -provides custom enumeration behavior to a composed object. -It defines one required `_keyValueMap` property, that is used as a hash of -"key-values" to iterate on during enumeration. - -<api name="Iterable"> -@constructor -Constructs an `Iterable` object. -</api> - -<api name="_keyValueMap"> -@property {Object} -Hash map of key-values to iterate over. _Required_ property: that is, the -property must be supplied by objects that compose this trait. -_Note: That this property can be a getter if you need dynamic behavior._ -</api> - -</api> - -<api name="List"> -@class -An ordered collection (also known as a sequence) disallowing duplicate -elements. List is composed out of `Iterable`, therefore it provides custom -enumeration behavior that is similar to array (enumerates only on the -elements of the list). - -List is a base trait and is meant to be part of a -composition, since all of its API is private except for the `length` property. - -**Examples:** - - var MyList = List.compose({ - add: function add(item1, item2, /*item3...*/) { - Array.slice(arguments).forEach(this._add.bind(this)); - }, - remove: function remove(item1, item2, /*item3...*/) { - Array.slice(arguments).forEach(this._remove.bind(this)); - } - }); - MyList('foo', 'bar', 'baz').length == 3; // true - new MyList('new', 'keyword').length == 2; // true - MyList.apply(null, [1, 2, 3]).length == 3; // true - let list = MyList(); - list.length == 0; // true - list.add(1, 2, 3) == 3; // true - -<api name="List"> -@constructor -Constructor can takes any number of elements and creates an instance of -`List` populated with the specified elements. -@param [element1] {Object|String|Number} -@param [element2] {Object|String|Number} -@param [...] {Object|String|Number} -</api> - -<api name="length"> -@property {Number} -Number of elements in this list. -</api> - -<api name="_has"> -@method -@param element {Object|Number|String} -Returns `true` if this list contains the specified `element`. -</api> -<api name="_add"> -@method -@param element {Object|Number|String} -Appends the specified `element` to the end of this list, if it doesn't -contain it. - -_Ignores the call if `element` is already contained._ -</api> -<api name="_remove"> -@method -@param element {Object|Number|String} -Removes specified `element` from this list, if it contains it. - -_Ignores the call if `element` is not contained._ -</api> -<api name="_clear"> -@method -Removes all of the elements from this list. -</api> -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/match-pattern.md b/tools/addon-sdk-1.3/packages/api-utils/docs/match-pattern.md deleted file mode 100644 index 125f89e..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/match-pattern.md +++ /dev/null @@ -1,242 +0,0 @@ -The `match-pattern` module can be used to test strings containing URLs -against simple patterns. - -## Specifying Patterns ## - -There are three ways you can specify patterns: - -* as an exact match string -* using a wildcard in a string -* using a regular expression - -### Exact Matches ### - -**A URL** matches only that URL. The URL must start with a scheme, end with a -slash, and contain no wildcards. - -<table> - - <colgroup> - <col width="30%"> - <col width="35%"> - <col width="35%"> - </colgroup> - - <tr> - <th>Example pattern</th> - <th>Example matching URLs</th> - <th>Example non-matching URLs</th> - </tr> - - <tr> - <td><code>"http://example.com/"</code></td> - <td><code>http://example.com/</code></td> - <td><code>http://example.com</code><br> - <code>http://example.com/foo</code><br> - <code>https://example.com/</code><br> - <code>http://foo.example.com/</code></td> - </tr> - -</table> - -### Wildcards ### - -**A single asterisk** matches any URL with an `http`, `https`, or `ftp` -scheme. For other schemes like `file`, use a scheme followed by an -asterisk, as below. - -<table> - - <colgroup> - <col width="30%"> - <col width="35%"> - <col width="35%"> - </colgroup> - - <tr> - <th>Example pattern</th> - <th>Example matching URLs</th> - <th>Example non-matching URLs</th> - </tr> - - <tr> - <td><code>"*"</code></td> - <td><code>http://example.com/</code><br> - <code>https://example.com/</code><br> - <code>ftp://example.com/</code><br> - <code>http://bar.com/foo.js</code><br> - <code>http://foo.com/</code></td> - <td><code>file://example.js</code></td> - </tr> - -</table> - -**A domain name prefixed with an asterisk and dot** matches any URL of that -domain or a subdomain, using any of `http`, `https`, `ftp`. - -<table> - - <colgroup> - <col width="30%"> - <col width="35%"> - <col width="35%"> - </colgroup> - - <tr> - <th>Example pattern</th> - <th>Example matching URLs</th> - <th>Example non-matching URLs</th> - </tr> - - <tr> - <td><code>"*.example.com"</code></td> - <td><code>http://example.com/</code><br> - <code>http://foo.example.com/</code><br> - <code>https://example.com/</code><br> - <code>http://example.com/foo</code><br> - <code>ftp://foo.example.com/</code></td> - <td><code>ldap://example.com</code><br> - <code>http://example.foo.com/</code></td> - </tr> - -</table> - -**A URL followed by an asterisk** matches that URL and any URL prefixed with -the pattern. - -<table> - - <colgroup> - <col width="30%"> - <col width="35%"> - <col width="35%"> - </colgroup> - - <tr> - <th>Example pattern</th> - <th>Example matching URLs</th> - <th>Example non-matching URLs</th> - </tr> - - <tr> - <td><code>"https://foo.com/*"</code></td> - <td><code>https://foo.com/</code><br> - <code>https://foo.com/bar</code></td> - <td><code>http://foo.com/</code><br> - <code>https://foo.com</code><br> - <code>https://bar.foo.com/</code></td> - </tr> - -</table> - -**A scheme followed by an asterisk** matches all URLs with that scheme. To -match local files, use `file://*`. - -<table> - - <colgroup> - <col width="30%"> - <col width="70%"> - </colgroup> - - <tr> - <th>Example pattern</th> - <th>Example matching URLs</th> - </tr> - - <tr> - <td><code>"file://*"</code></td> - <td><code>file://C:/file.html</code><br> - <code>file:///home/file.png</code></td> - </tr> - -</table> - -### Regular Expressions ### - -You can specify patterns using a -[regular expression](https://developer.mozilla.org/en/JavaScript/Guide/Regular_Expressions): - - var { MatchPattern } = require("match-pattern"); - var pattern = new MatchPattern(/.*example.*/); - -The regular expression is subject to restrictions based on those applied to the -[HTML5 pattern attribute](http://dev.w3.org/html5/spec/common-input-element-attributes.html#attr-input-pattern). In particular: - -* The pattern must match the entire value, not just any subset. For example, the -pattern `/moz.*/` will not match the URL `http://mozilla.org`. - -* The expression is compiled with the `global`, `ignoreCase`, and `multiline` flags - disabled. The `MatchPattern` constructor will throw an exception - if you try to set any of these flags. - -<table> - - <colgroup> - <col width="30%"> - <col width="35%"> - <col width="35%"> - </colgroup> - - <tr> - <th>Example pattern</th> - <th>Example matching URLs</th> - <th>Example non-matching URLs</th> - </tr> - - <tr> - <td><code>/.*moz.*/</code></td> - <td><code>http://foo.mozilla.org/</code><br> - <code>http://mozilla.org</code><br> - <code>https://mozilla.org</code><br> - <code>http://foo.com/mozilla</code><br> - <code>http://hemozoon.org</code><br> - <code>mozscheme://foo.org</code><br></td> - <td><code>http://foo.org</code><br> - </tr> - - <tr> - <td><code>/http:\/\/moz.*/</code></td> - <td><code>http://mozilla.org</code><br> - <code>http://mozzarella.com</code></td> - <td><code>https://mozilla.org</code><br> - <code>http://foo.mozilla.org/</code><br> - <code>http://foo.com/moz</code></td> - </tr> - - <tr> - <td><code>/http.*moz.*/</code><br></td> - <td><code>http://foo.mozilla.org/</code><br> - <code>http://mozilla.org</code><br> - <code>http://hemozoon.org/</code></td> - <td><code>ftp://http/mozilla.org</code></td> - </tr> - -</table> - -## Examples ## - - var { MatchPattern } = require("match-pattern"); - var pattern = new MatchPattern("http://example.com/*"); - console.log(pattern.test("http://example.com/")); // true - console.log(pattern.test("http://example.com/foo")); // true - console.log(pattern.test("http://foo.com/")); // false! - -<api name="MatchPattern"> -@class -<api name="MatchPattern"> -@constructor - This constructor creates match pattern objects that can be used to test URLs. -@param pattern {string} - The pattern to use. See Patterns above. -</api> - -<api name="test"> -@method - Tests a URL against the match pattern. -@param url {string} - The URL to test. -@returns {boolean} - True if the URL matches the pattern and false otherwise. -</api> -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/memory.md b/tools/addon-sdk-1.3/packages/api-utils/docs/memory.md deleted file mode 100644 index c90f613..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/memory.md +++ /dev/null @@ -1,3 +0,0 @@ -The `memory` module provides a concrete default implementation for the SDK's -`memory` global. For documentation on the `memory` global, see the -[Globals](dev-guide/module-development/globals.html) reference. diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/observer-service.md b/tools/addon-sdk-1.3/packages/api-utils/docs/observer-service.md deleted file mode 100644 index a2041f3..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/observer-service.md +++ /dev/null @@ -1,69 +0,0 @@ -<!-- contributed by Atul Varma [atul@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> - -The `observer-service` 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 the MDC page on -[Observer Notifications](https://developer.mozilla.org/en/Observer_Notifications). - -## Observer Callbacks ## - -Observer callbacks are functions of the following form: - - function callback(subject, data) { - /* Respond to the event notification here... */ - } - -In the above example, `subject` is any JavaScript object, as is -`data`. The particulars of what the two contain are specific -to the notification topic. - -<api name="add"> -@function - Adds an observer callback to be triggered whenever a notification matching the - topic is broadcast throughout the application. - -@param topic {string} - The topic to observe. - -@param callback {function,object} - Either a function or an object that implements [`nsIObserver`](http://mxr.mozilla.org/mozilla-central/source/xpcom/ds/nsIObserver.idl). - If a function, then it is called when the notification occurs. If an object, - then its `observe()` method is called when the notification occurs. - -@param [thisObject] {object} - An optional object to use as `this` when a function callback is called. -</api> - -<api name="remove"> -@function - Unsubscribes a callback from being triggered whenever a notification - matching the topic is broadcast throughout the application. - -@param topic {string} - The topic being observed by the previous call to `add()`. - -@param callback {function,object} - The callback subscribed in the previous call to `add()`, either a function or - object. - -@param [thisObject] {object} - If `thisObject` was passed to the previous call to `add()`, it should be - passed to `remove()` as well. -</api> - -<api name="notify"> -@function - Broadcasts a notification event for a topic, passing a subject and data to all - applicable observers in the application. - -@param topic {string} - The topic about which to broadcast a notification. - -@param [subject] {value} - Optional information about the topic. This can be any JS object or primitive. - If you have multiple values to pass to observers, wrap them in an object, - e.g., `{ foo: 1, bar: "some string", baz: myObject }`. -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/plain-text-console.md b/tools/addon-sdk-1.3/packages/api-utils/docs/plain-text-console.md deleted file mode 100644 index 3c7a5a6..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/plain-text-console.md +++ /dev/null @@ -1,3 +0,0 @@ -The `plain-text-console` module provides a minimalist implementation -of the [console](dev-guide/addon-development/console.html) global, -which simply logs all messages to standard output. diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/preferences-service.md b/tools/addon-sdk-1.3/packages/api-utils/docs/preferences-service.md deleted file mode 100644 index 145f943..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/preferences-service.md +++ /dev/null @@ -1,51 +0,0 @@ -<!-- contributed by Myk Melez [myk@mozilla.org] --> -<!-- contributed by Daniel Aquino [mr.danielaquino@gmail.com] --> -<!-- contributed by Atul Varma [atul@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> - -The `preferences-service` module provides access to the -application-wide preferences service singleton. - - -<api name="set"> -@function -Sets the application preference `name` to `value`. -@param name {string} Preference name. -@param value {string,number,bool} Preference value. -</api> - - -<api name="get"> -@function -Gets the application preference `name`. -@param name {string} -@param defaultValue {string,number,bool} Preference value. -@returns {string,number,bool} Preference value, returns a default value if no -preference is set. -</api> - - -<api name="has"> -@function -@param name {string} Preference name. -@returns {bool} Returns whether or not the application preference `name` exists. -</api> - - -<api name="isSet"> -@function -@param name {string} Preference name. -@returns {bool} -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). -</api> - - -<api name="reset"> -@function -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. -@param name {string} Preference name. -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/runtime.md b/tools/addon-sdk-1.3/packages/api-utils/docs/runtime.md deleted file mode 100644 index e4a7ee5..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/runtime.md +++ /dev/null @@ -1,71 +0,0 @@ -<!-- contributed by Wes Kocher [kwierso@gmail.com] --> - -The `runtime` module provides access to information about Firefox's -runtime environment. All properties exposed are read-only. - -For more information, see [nsIXULRuntime][nsIXULRuntime]. -[nsIXULRuntime]: https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIXULRuntime - -<api name="inSafeMode"> -@property {boolean} - This value is `true` if Firefox was started in safe mode, - otherwise `false`. -</api> - -<api name="OS"> -@property {string} - A string identifying the current operating system. For example, . - `"WINNT"`, `"Darwin"`, or `"Linux"`. See [OS_TARGET][OS_TARGET] - for a more complete list of possible values. - -[OS_TARGET]: https://developer.mozilla.org/en/OS_TARGET -</api> - -<api name="processType"> -@property {long} - The type of the caller's process, which will be one of these constants\: -<table> - <tr> - <th>Constant</th> - <th>Value</th> - <th>Description</th> - </tr> - - <tr> - <td>PROCESS_TYPE_DEFAULT</td> - <td>0</td> - <td>The default (chrome) process.</td> - </tr> - - <tr> - <td>PROCESS_TYPE_PLUGIN</td> - <td>1</td> - <td>A plugin subprocess.</td> - </tr> - - <tr> - <td>PROCESS_TYPE_CONTENT</td> - <td>2</td> - <td>A content subprocess.</td> - </tr> - - <tr> - <td>PROCESS_TYPE_IPDLUNITTEST</td> - <td>3</td> - <td>An IPDL unit testing subprocess.</td> - </tr> -</table> -</api> - -<api name="widgetToolkit"> -@property {string} - A string identifying the target widget toolkit in use. -</api> - -<api name="XPCOMABI"> -@property {string} - A string identifying the [ABI][ABI] of the current processor and compiler vtable. - This string takes the form \<`processor`\>-\<`compilerABI`\>, - for example\: "`x86-msvc`" or "`ppc-gcc3`". -[ABI]: https://developer.mozilla.org/en/XPCOM_ABI -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/securable-module.md b/tools/addon-sdk-1.3/packages/api-utils/docs/securable-module.md deleted file mode 100644 index d1d392d..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/securable-module.md +++ /dev/null @@ -1,93 +0,0 @@ -The `securable-module` module allows for the recursive loading -and sandboxing of -[CommonJS Modules](http://wiki.commonjs.org/wiki/Modules/1.0) -(formerly called SecurableModules). This allows, for instance, -the creation of "mini platforms" that manage the sandboxed evaluation of code. - -## Loader Objects ## - -Loader objects encapsulate the sandboxed loading of SecurableModules -and the execution of code that relies upon them. - -<code>Loader.**runScript**(*options*)</code> - -Runs JavaScript code in the context of the Loader. *options* is an -object with the following keys: - -<table> - <tr> - <td><code>contents</code></td> - <td>A string of JavaScript code.</td> - </tr> - <tr> - <td><code>filename</code></td> - <td>An absolute URL naming the file from which the code - originates; useful for error reporting and debugging. If omitted, - this option defaults to <code>"<string>"</code>.</td> - </tr> - <tr> - <td><code>lineNo</code></td> - <td>An integer representing the line from the file which the - beginning of the code corresponds to. If ommitted, this option - defaults to <code>1</code>.</td> - </tr> - <tr> - <td><code>jsVersion</code></td> - <td>A string representing the JavaScript version that the code - should be interpreted under. If omitted, this options defaults to - the latest version of JavaScript supported by the platform.</td> - </tr> -</table> - -This method returns the most recent value evaluated by the given code. - -<code>Loader.**runScript**(*code*)</code> - -If *code* is a string of JavaScript code, this is a convenient -shorthand for `Loader.runScript({contents: code}}`. - -<code>Loader.**require**(*module*)</code> - -This loads the given module name using the standard `require()` -semantics and returns the loaded module. - -## Functions ## - -<code>securable-module.**Loader**(*options*)</code> - -Creates a new SecurableModule Loader. *options* is an object with -the following keys: - -<table> - <tr> - <td><code>rootPaths</code></td> - <td>A list of absolute URLs that will be searched, in order, for - SecurableModules when <code>require()</code> is called by any code - executing within the context of the Loader.</td> - </tr> - <tr> - <td><code>rootPath</code></td> - <td>A single absolute URL; this is a convenience option, - synonymous with setting <code>rootPaths</code> to an array containing - a single URL.</td> - </tr> - <tr> - <td><code>defaultPrincipal</code></td> - <td>A string representing the default principal given to any code - that is executed by the Loader. This can be <code>"system"</code>, in - which case code executed has full chrome access (including access - to the <code>Components</code> object which allows it to access the - Mozilla platform unrestricted). - Alternatively, it can be a URL, such as <code>"http://www.foo.com"</code>, - in which case it is treated like web content. If left unspecified, - the default value of this option is <code>"http://www.mozilla.org"</code>. - </td> - </tr> - <tr> - <td><code>globals</code></td> - <td>An object containing the names and values of all variables - that will be injected into the global scope of all code executed - by the Loader.</td> - </tr> -</table> - diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/tab-browser.md b/tools/addon-sdk-1.3/packages/api-utils/docs/tab-browser.md deleted file mode 100644 index b844206..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/tab-browser.md +++ /dev/null @@ -1,136 +0,0 @@ -<!-- contributed by Dietrich Ayala [dietrich@mozilla.com] --> - -The `tab-browser` module is a low-level API that provides privileged -access to browser tab events and actions. - -Introduction ------------- - -The `tab-browser` module contains helpers for tracking tabbrowser elements -and tabs, as well as a few utilities for actions such as opening a new -tab, and catching all tab content loads. - -This is a low-level API that has full privileges, and is intended to be used -by SDK internal modules. If you just need easy access to tab events for your -add-on, use the Tabs module (JEP 110). - -<api name="activeTab"> -@property {element} -The XUL tab element of the currently active tab. -</api> - -<api name="addTab"> -@function -Adds a new tab. - -**Example** - - var tabBrowser = require("tab-browser"); - tabBrowser.addTab("http://google.com"); - - var tabBrowser = require("tab-browser"); - tabBrowser.addTab("http://google.com", { - inBackground: true - }); - - var tabBrowser = require("tab-browser"); - tabBrowser.addTab("http://google.com", { - inNewWindow: true, - onLoad: function(tab) { - console.log("tab is open."); - } - }); - -@returns {element} -The XUL tab element of the newly created tab. - -@param URL {string} -The URL to be opened in the new tab. - -@param options {object} -Options for how and where to open the new tab. - -@prop [inNewWindow] {boolean} -An optional parameter whose key can be set in `options`. -If true, the tab is opened in a new window. Default is false. - -@prop [inBackground] {boolean} -An optional parameter whose key can be set in `options`. -If true, the tab is opened adjacent to the active tab, but not -switched to. Default is false. - -@prop [onLoad] {function} -An optional parameter whose key can be set in `options`. -A callback function that is called once the tab has loaded. -The XUL element for the tab is passed as a parameter to -this function. -</api> - -<api name="Tracker"> -@function -Register a delegate object to be notified when tabbrowsers are created -and destroyed. - -The onTrack method will be called once per pre-existing tabbrowser, upon -tracker registration. - -**Example** - - var tabBrowser = require("tab-browser"); - let tracker = { - onTrack: function(tabbrowser) { - console.log("A new tabbrowser is being tracked."); - }, - onUntrack: function(tabbrowser) { - console.log("A tabbrowser is no longer being tracked."); - } - }; - tabBrowser.Tracker(tracker); - -@param delegate {object} -Delegate object to be notified each time a tabbrowser is created or destroyed. -The object should contain the following methods: - -@prop [onTrack] {function} -Method of delegate that is called when a new tabbrowser starts to be tracked. -The tabbrowser element is passed as a parameter to this method. - -@prop [onUntrack] {function} -Method of delegate that is called when a tabbrowser stops being tracked. -The tabbrowser element is passed as a parameter to this method. -</api> - -<api name="TabTracker"> -@function -Register a delegate object to be notified when tabs are opened and closed. - - -The onTrack method will be called once per pre-existing tab, upon -tracker registration. - -**Example** - - var tabBrowser = require("tab-browser"); - let tracker = { - onTrack: function(tab) { - console.log("A new tab is being tracked."); - }, - onUntrack: function(tab) { - console.log("A tab is no longer being tracked."); - } - }; - tabBrowser.TabTracker(tracker); - -@param delegate {object} -Delegate object to be notified each time a tab is opened or closed. -The object should contain the following methods: - -@prop [onTrack] {function} -Method of delegate that is called when a new tab starts to be tracked. -The tab element is passed as a parameter to this method. - -@prop [onUntrack] {function} -Method of delegate that is called when a tab stops being tracked. -The tab element is passed as a parameter to this method. -</api> - diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/text-streams.md b/tools/addon-sdk-1.3/packages/api-utils/docs/text-streams.md deleted file mode 100644 index c057e06..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/text-streams.md +++ /dev/null @@ -1,98 +0,0 @@ -<!-- contributed by Drew Willcoxon [adw@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> - -The `text-streams` module provides streams for reading and writing text using -particular character encodings. - -<api name="TextReader"> -@class -<api name="TextReader"> -@constructor - Creates a buffered input stream that reads text from a backing stream using a - given text encoding. -@param inputStream {stream} - The backing stream, an [`nsIInputStream`](http://mxr.mozilla.org/mozilla-central/source/xpcom/io/nsIInputStream.idl). - It must already be opened. -@param [charset] {string} - `inputStream` is expected to be in the character encoding named by this value. - If not specified, "UTF-8" is assumed. See [`nsICharsetConverterManager.idl`](http://mxr.mozilla.org/mozilla-central/source/intl/uconv/idl/nsICharsetConverterManager.idl) - for documentation on how to determine other valid values for this. -</api> - -<api name="closed"> -@property {boolean} - True if the stream is closed. -</api> - -<api name="close"> -@method - Closes both the stream and its backing stream. -</api> - -<api name="read"> -@method - Reads and returns a string from the stream. If the stream is closed, an - exception is thrown. -@param [numChars] {number} - The number of characters to read. If not given, the remainder of the stream - is read. -@returns {string} - The string read. If the stream is at the end, the empty string is returned. -</api> - -</api> - - -<api name="TextWriter"> -@class -<api name="TextWriter"> -@constructor - Creates a buffered output stream that writes text to a backing stream using a - given text encoding. -@param outputStream {stream} - The backing stream, an [`nsIOutputStream`](http://mxr.mozilla.org/mozilla-central/source/xpcom/io/nsIOutputStream.idl). - It must already be opened. -@param [charset] {string} - Text will be written to `outputStream` using the character encoding named by - this value. If not specified, "UTF-8" is assumed. See [`nsICharsetConverterManager.idl`](http://mxr.mozilla.org/mozilla-central/source/intl/uconv/idl/nsICharsetConverterManager.idl) - for documentation on how to determine other valid values for this. -</api> - -<api name="closed"> -@property {boolean} - True if the stream is closed. -</api> - -<api name="close"> -@method - Flushes the backing stream's buffer and closes both the stream and the backing - stream. If the stream is already closed, an exception is thrown. -</api> - -<api name="flush"> -@method - Flushes the backing stream's buffer. -</api> - -<api name="write"> -@method - Writes a string to the stream. If the stream is closed, an exception is - thrown. -@param str {string} - The string to write. -</api> - -<api name="writeAsync"> -@method - Writes a string on a background thread. After the write completes, the - backing stream's buffer is flushed, and both the stream and the backing stream - are closed, also on the background thread. If the stream is already closed, - an exception is thrown immediately. -@param str {string} - The string to write. -@param [callback] {callback} - *`callback`*, if given, must be a function. It's called as `callback(error)` - when the write completes. `error` is an `Error` object or undefined if there - was no error. Inside *`callback`*, `this` is the `TextWriter` object. -</api> -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/traceback.md b/tools/addon-sdk-1.3/packages/api-utils/docs/traceback.md deleted file mode 100644 index fd7ddb5..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/traceback.md +++ /dev/null @@ -1,62 +0,0 @@ -<!-- contributed by Atul Varma [atul@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> - - -The `traceback` module contains functionality similar to -Python's [traceback](http://docs.python.org/library/traceback.html) module. - -## JSON Traceback Objects ## - -Tracebacks are stored in JSON format. The stack is represented as an -array in which the most recent stack frame is the last element; each -element thus represents a stack frame and has the following keys: - -<table> - <tr> - <td><code>filename</code></td> - <td>The name of the file that the stack frame takes place in.</td> - </tr> - <tr> - <td><code>lineNo</code></td> - <td>The line number is being executed at the stack frame.</td> - </tr> - <tr> - <td><code>funcName</code></td> - <td>The name of the function being executed at the stack frame, or - <code>null</code> if the function is anonymous or the stack frame is - being executed in a top-level script or module.</td> - </tr> -</table> - -<api name="fromException"> -@function - Attempts to extract the traceback from *`exception`*. - -@returns {traceback} - JSON representation of the traceback or `null` if not found. - -@param exception {exception} - exception where exception is an `nsIException`. -</api> - -See [nsIException](https://developer.mozilla.org/en/NsIException) for more -information. - -<api name="get"> -@function - -@returns {JSON} - Returns the JSON representation of the stack at the point that this - function is called. -</api> - -<api name="format"> -@function -Given a JSON representation of the stack or an exception instance, -returns a formatted plain text representation of it, similar to -Python's formatted stack tracebacks. If no argument is provided, the -stack at the point this function is called is used. - -@param [tbOrException] {object} -</api> - diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/traits.md b/tools/addon-sdk-1.3/packages/api-utils/docs/traits.md deleted file mode 100644 index 66e8f02..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/traits.md +++ /dev/null @@ -1,240 +0,0 @@ -<!-- contributed by Irakli Gozalishvil [gozala@mozilla.com] --> - -The `traits` module provides base building blocks for secure object -composition. It exports base trait / constructor function that -constructs an instance of `Trait`. - -[Traits](http://en.wikipedia.org/wiki/Trait_%28computer_science%29) are a -simple composition mechanism for structuring object-oriented programs. Traits -are similar to -[interfaces](http://en.wikipedia.org/wiki/Interface_%28object-oriented_programming%29), -except that they often define only a part of an object's data and behavior and -are intended to be used in conjunction with other traits to completely define -the object. - -Traits are also considered to be a more robust alternative to -[mixins](http://en.wikipedia.org/wiki/Mixins) because, name conflicts have to -be resolved explicitly by composer & because trait composition is -order-independent (hence more declarative). - - -There are some other implementations of traits in JavaScript & some ideas / -APIs are borrowed from them: - -- [traitsjs](http://www.traitsjs.org/) -- [joose](http://code.google.com/p/joose-js/) - -Object-capability security model --------------------------------- - -Implementation uses an -[object-capability security model](http://en.wikipedia.org/wiki/Object-capability_model) -to allow protection of private APIs. At the same private APIs can be shared -between among trait composition parties. To put it simply: All the properties -whose names start with `"_"` are considered to be **private**, and are -unaccessible from anywhere except other **public** methods / accessors of the -instance that had been defined during composition. - -<api name="Trait"> -@class -<api name="Trait"> -@constructor -Creates an instance of Trait and returns it if it has no `constructor` method -defined. If instance has `constructor` method, then it is called with all the -arguments passed to this function and returned value is returned instead, -unless it's `undefined`. In that case instance is returned. - -`Trait` function represents a base trait. As with any other trait it represents -a constructor function for creating instances of its own & a placeholder -for a trait compositions functions. -</api> - -<api name="compose"> -@method -Composes new trait out of itself and traits / property maps passed as an -arguments. If two or more traits / property maps have properties with the same -name, the new trait will contain a "conflict" property for that name (see -examples in Examples section to find out more about "conflict" properties). -This is a commutative and associative operation, and the order of its -arguments is not significant. - -**Examples:** - -Let's say we want to define a reusable piece of code for a lists of elements. - - var { Trait } = require('traits'); - var List = Trait.compose({ - // private API: - _list: null, - // public API - constructor: function List() { - this._list = []; - }, - get length() this._list.length, - add: function add(item) this._list.push(item), - remove: function remove(item) { - let list = this._list; - let index = list.indexOf(item); - if (0 <= index) list.splice(index, 1); - } - }); - -Instances of `List` can be created by calling `List` function with or without -`new` keyword. - - let l1 = List(); - l1 instanceof List; // true - let l2 = new List(); - l2 instanceof List; // true - -As you can see `add` and `remove` functions are capable of accessing private -`_list` property, but thats about it, there's nothing else that will be able -to access this property: - - '_list' in l1; // false - '_list' in l2; // false - '_list' in List.protoype; // false - l1.has = function(name) name in this - l1.has('_list'); // false - l1.length; // 0 - l1.add('test') - l1.length // 1 - -@param trait1 {Object|Function} - Trait or property map to compose new trait from. -@param trait2 {Object|Function} - Trait or property map to compose new trait from. -@param ... {Object|Function} - Traits or property maps to compose new trait from. - -@returns {Function} - New trait containing the combined properties of all the traits. -</api> - -<api name="required"> -@property {Object} -Singleton, used during trait composition to define "required" properties. - -**Example:** - - var Enumerable = Trait.compose({ - list: Trait.required, - forEach: function forEach(consumer) { - return this.list.forEach(consumer); - } - }); - - let c1 = Enumerable(); // Error: Missing required property: list - - var EnumerableList = List.compose({ - get list() this._list.slice(0) - }, Enumerable); - - let c2 = EnumerableList(); - c2.add('test') - c2.length // 1 - c2.list[0] // 'test' - c2.forEach(console.log) // > info: 'test 0 test' - -</api> - - -<api name="resolve"> -@method -Composes a new trait that has all the same properties -as the trait on which it is called, except that each property listed -in the `resolutions` argument will be renamed from the name -of the property in the `resolutions` argument to its value. -And if its value is `null`, the property will become required. - -**Example:** - - var Range = List.resolve({ - constructor: null, - add: '_add', - }).compose({ - min: null, - max: null, - get list() this._list.slice(0), - constructor: function Range(min, max) { - this.min = min; - this.max = max; - this._list = []; - }, - add: function(item) { - if (item <= this.max && item >= this.min) - this._add(item) - } - }); - - - let r = Range(0, 10); - r.min; // 0 - r.max; // 10 - r.length; // 0; - r.add(5); - r.length; // 1 - r.add(12); - r.length; // 1 (12 was not in a range) - -@param resolutions {Object} -@returns {Function} - New resolved trait. -</api> - -<api name="override"> -@method -Composes a new trait with all of the combined properties of `this` and the -argument traits. In contrast to `compose`, `override` immediately resolves -all conflicts resulting from this composition by overriding the properties of -later traits. Trait priority is from left to right. I.e. the properties of -the leftmost trait are never overridden. - -**Example:** - - // will compose trait with conflict property 'constructor' - var ConstructableList = List.compose({ - constructor: function List() this._list = Array.slice(arguments) - }); - // throws error with message 'Remaining conflicting property: constructor' - ConstructableList(1, 2, 3); - - var ConstructableList = List.override({ - constructor: function List() this._list = Array.slice(arguments) - }); - ConstructableList(1, 2, 3).length // 3 - -@param trait1 {Object|Function} - Trait or property map to compose new trait from. -@param trait2 {Object|Function} - Trait or property map to compose new trait from. -@param ... {Object|Function} - Traits or property maps to compose new trait from. - -@returns {Function} - New trait containing the combined properties of all the traits. -</api> - -<api name="_public"> -@property {Object} -Internal property of instance representing public API that is exposed to the -consumers of an instance. -</api> - -<api name='toString'> -@method -Textual representation of an object. All the traits will return: -`'[object Trait]'` string, unless they have `constructor` property, in that -case string `'Trait'` is replaced with the name of `constructor` property. - -**Example:** - - var MyTrait = Trait.compose({ - constructor: function MyTrait() { - // do your initialization here - } - }); - MyTrait().toString(); // [object MyTrait] - -</api> -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/unit-test.md b/tools/addon-sdk-1.3/packages/api-utils/docs/unit-test.md deleted file mode 100644 index 401b551..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/unit-test.md +++ /dev/null @@ -1,389 +0,0 @@ -<!-- contributed by Atul Varma [atul@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> -<!-- edited by Shane Tomlinson[stomlinson@mozilla.com] --> - -The `unit-test` module makes it easy to find and run unit tests. - -<api name="test"> -@class -Each function which represents a test case is passed a single argument -`test`, which represents the test runner. - -<api name="pass"> -@method - Marks a test as passing, with the given optional message. - -@param [message] {string} - Optional passing message. -</api> - - -<api name="fail"> -@method - Marks a test as failing, with the given optional message. - -@param [message] {string} - Optional failure message. -</api> - -<api name="expectFail"> -@method - *experimental* Expect the test enclosed within `func` to fail. - -@param func {function} - A function that should contain a test that is expected to fail. -</api> - -<api name="exception"> -@method - Marks a test as failing due to the given exception having been thrown. - This can be put in a `catch` clause. - -@param e {exception} - An exception. -</api> - -<api name="assert"> -@method - Ensures that `a` has a truthy value. - -@param a {value} - Value to verify. -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. -</api> - - -<api name="assertEqual"> -@method - Ensures that `a == b` without recursing into `a` or `b`. - -@param a {value} - A value. - -@param b {value} - Another value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. -</api> - -<api name="assertNotEqual"> -@method - Ensures that `a != b` without recursing into `a` or `b`. - -@param a {value} - A value. - -@param b {value} - Another value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. -</api> - -<api name="assertStrictEqual"> -@method - Ensures that `a === b` without recursing into `a` or `b`. - -@param a {value} - A value. - -@param b {value} - Another value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. -</api> - - -<api name="assertNotStrictEqual"> -@method - Ensures that `a !== b` without recursing into `a` or `b`. - -@param a {value} - A value. - -@param b {value} - Another value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. -</api> - -<api name="assertMatches"> -@method - Ensures that the given string matches the given regular expression. - If it does, marks a test as passing, otherwise marks a test as - failing. - -@param string {string} - The string to test. - -@param regexp {regexp} - The string should match this regular expression. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. -</api> - - -<api name="assertRaises"> -@method - 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 `message` property is - compared with `predicate`: if `predicate` is a string, then a - simple equality comparison is done with `message`. Otherwise, - if `predicate` is a regular expression, `message` is tested - against it. - -@param func {function} - A function that should raise an exception when called. - -@param predicate {string,regexp} - A string or regular expression to compare to the exception's message. - -@param [message] {string} - Depending on the outcome, a test is marked as passing or failing, and - *message* is logged. -</api> - - -<api name="assertFunction"> -@method - Ensures that `a` is a function. - -@param a {value} - A value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. - -</api> - - -<api name="assertUndefined"> -@method - Ensures that `a` is `undefined`. `null`, `0`, and `false` will all fail. - -@param a {value} - A value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. - -</api> - - -<api name="assertNotUndefined"> -@method - Ensures that `a` is not `undefined`. `null`, `0`, and `false` will all pass. - -@param a {value} - A value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. - -</api> - - -<api name="assertNull"> -@method - Ensures that `a` is `null`. `undefined`, `0`, and `false` will all fail. - -@param a {value} - A value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. - -</api> - - -<api name="assertNotNull"> -@method - Ensures that `a` is not `null`. `undefined`, `0`, and `false` will all pass. - -@param a {value} - A value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. - -</api> - - -<api name="assertObject"> -@method - Ensures that `a` is an object. A function, string, or number will fail. - -@param a {value} - A value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. - -</api> - - -<api name="assertString"> -@method - Ensures that `a` is a string. - -@param a {value} - A value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. - -</api> - - -<api name="assertArray"> -@method - Ensures that `a` is an array. - -@param a {value} - A value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. - -</api> - - -<api name="assertNumber"> -@method - Ensures that `a` is a number. - -@param a {value} - A value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. - -</api> - - -<api name="waitUntilDone"> -@method - Puts the test runner into asynchronous testing mode, waiting up to - *timeout* milliseconds for `test.done()` to be called. This - is intended for use in situations where a test suite schedules a - callback, calls `test.waitUntilDone()`, and then calls - `test.done()` in the callback. - -@param [timeout] {integer} - If this number of milliseconds elapses and `test.done()` has not yet been - called, the test is marked as failing. -</api> - - -<api name="done"> -@method - Marks a test as being complete. Assumes a previous call to - `test.waitUntilDone()`. -</api> - -</api> - - -<api name="waitUntil"> -@method - Ensures that `a` returns a truthy value within a reasonable amount of time. - -@param a {function} - Function that returns the value to verify. -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. -</api> - - -<api name="waitUntilEqual"> -@method - Ensures that `a == b` returned values or values without without recursing - into `a` or `b`. - -@param a {Function} - A value, or a function that returns a value. - -@param b {value} - Another value, or a function that returns value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. -</api> - -<api name="waitUntilNotEqual"> -@method - Ensures that `a != b` without recursing into `a` or `b`. - -@param a {Function} - A value, or a function that returns a value. - -@param b {value} - Another value, or a function that returns another value. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. -</api> - - -<api name="waitUntilMatches"> -@method - Ensures that the given string matches the given regular expression. - If it does, marks the test as passing, otherwise marks the test as - failing. - -@param string {Function} - A function that returns the string to test. - -@param regexp {regexp} - The string should match this regular expression. - -@param [message] {string} - The test is marked as passing or failing depending on the result, logging - *message* with it. -</api> - - - -<api name="findAndRunTests"> -@function - The list of directories is searched for SecurableModules that start - with the prefix `test-`. 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 - Object. - -@param options {object} - An object with the following properties: - @prop dirs {string} - 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 - `require()`. - @prop onDone {function} - A function to call when testing is complete. -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/unload.md b/tools/addon-sdk-1.3/packages/api-utils/docs/unload.md deleted file mode 100644 index a7e3f3f..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/unload.md +++ /dev/null @@ -1,57 +0,0 @@ -<!-- contributed by Atul Varma [atul@mozilla.com] --> -<!-- contributed by Drew Willcoxon [adw@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> - -The `unload` module allows modules to register callbacks that are called -when they are unloaded. It is similar to the CommonJS module of the same -name in the [Narwhal][] platform. - -[Narwhal]: http://narwhaljs.org/ - -<api name="ensure"> -@function - Calling `ensure()` on an object does two things: - - 1. It replaces a destructor method with a wrapper method that will never call - the destructor more than once. - 2. It ensures that this wrapper method is called when `send()` is - called. - - Therefore, when you register an object with `ensure()`, you can call its - destructor method yourself, you can let it happen for you, or you can do both. - - The destructor will be called with a single argument describing the reason - for the unload; see `when()`. If `object` does not have the expected - destructor method, then an exception is thrown when `ensure()` is called. - -@param object {object} - An object that defines a destructor method. -@param [name] {string} - Optional name of the destructor method. Default is `unload`. -</api> - -<api name="when"> -@function - Registers a function to be called when `send()` is called. - -@param callback {function} - A function that will be called when `send()` is called. It is called with a - single argument, one of the following strings describing the reason for - unload: `"uninstall"`, `"disable"`, `"shutdown"`, `"upgrade"`, or - `"downgrade"`. (On Gecko 1.9.2-based applications such as Firefox 3.6, - `"upgrade"` and `"downgrade"` are not available, and `"shutdown"` will be sent - in their place.) If a reason could not be determined, `undefined` will be - passed instead. Note that if an add-on is unloaded with reason `"disable"`, - it will not be notified about `"uninstall"` while it is disabled. A solution - to this issue is being investigated; see bug 571049. -</api> - -<api name="send"> -@function - Sends an "unload signal", thereby triggering all callbacks registered via - `when()`. In general, this function need not be manually called; it is - automatically triggered by the embedder. - -@param [reason] {string} - An optional string describing the reason for unload; see `unload.when()`. -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/url.md b/tools/addon-sdk-1.3/packages/api-utils/docs/url.md deleted file mode 100644 index dee0580..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/url.md +++ /dev/null @@ -1,81 +0,0 @@ -<!-- contributed by Atul Varma [atul@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> - - -The `url` module provides functionality for the parsing and retrieving of URLs. - -<api name="URL"> -@class -<api name="URL"> -@constructor - The URL constructor creates an object that represents a URL, verifying that - the provided string is a valid URL in the process. Any API in the SDK which - has a URL parameter will accept `URL` objects, not raw strings, unless - otherwise noted. - -@param source {string} - A string to be converted into a URL. If `source` is not a valid URI, this - constructor will throw an exception. - -@param [base] {string} - An optional string used to resolve relative `source` URLs into absolute ones. -</api> - -<api name="scheme"> -@property {string} - The name of the protocol in the URL. -</api> - -<api name="userPass"> -@property {string} - The username:password part of the URL, `null` if not present. -</api> - -<api name="host"> -@property {string} - The host of the URL, `null` if not present. -</api> - -<api name="port"> -@property {integer} - The port number of the URL, `null` if none was specified. -</api> - -<api name="path"> -@property {string} - The path component of the URL. -</api> - -<api name="toString"> -@method - Returns a string representation of the URL. -@returns {string} - The URL as a string. -</api> -</api> - -<api name="toFilename"> -@function - Attempts to convert the given URL to a native file path. This function will - automatically attempt to resolve non-file protocols, such as the `resource:` - 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. - -@param url {string} - The URL, as a string, to be converted. - -@returns {string} - The converted native file path as a string. -</api> - -<api name="fromFilename"> -@function - Converts the given native file path to a `file:` URL. - -@param path {string} - The native file path, as a string, to be converted. - -@returns {string} - The converted URL as a string. -</api> - diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/window-utils.md b/tools/addon-sdk-1.3/packages/api-utils/docs/window-utils.md deleted file mode 100644 index 3de84b5..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/window-utils.md +++ /dev/null @@ -1,84 +0,0 @@ -<!-- contributed by Drew Willcoxon [adw@mozilla.com] --> -<!-- edited by Erik Vold [erikvvold@gmail.com] --> - -The `window-utils` module provides helpers for accessing and tracking -application windows. These windows implement the [`nsIDOMWindow`][nsIDOMWindow] -interface. - -[nsIDOMWindow]: http://mxr.mozilla.org/mozilla-central/source/dom/interfaces/base/nsIDOMWindow.idl - -<api name="WindowTracker"> -@class -`WindowTracker` objects make it easy to "monkeypatch" windows when a program is -loaded and "un-monkeypatch" those windows when the program is unloaded. For -example, if a Firefox add-on needs to add a status bar icon to all browser -windows, it can use a single `WindowTracker` object to gain access to windows -when they are opened and closed and also when the add-on is loaded and unloaded. - -When a window is opened or closed, a `WindowTracker` notifies its delegate -object, which is passed to the constructor. The delegate is also notified of -all windows that are open at the time that the `WindowTracker` is created and -all windows that are open at the time that the `WindowTracker` is unloaded. The -caller can therefore use the same code to act on all windows, regardless of -whether they are currently open or are opened in the future, or whether they are -closed while the parent program is loaded or remain open when the program is -unloaded. - -When a window is opened or when a window is open at the time that the -`WindowTracker` is created, the delegate's `onTrack()` method is called and -passed the window. - -When a window is closed or when a window is open at the time that the -`WindowTracker` is unloaded, the delegate's `onUntrack()` method is called and -passed the window. (The `WindowTracker` is unloaded when its its `unload()` -method is called, or when its parent program is unloaded, disabled, or -uninstalled, whichever comes first.) - -**Example** - - var delegate = { - onTrack: function (window) { - console.log("Tracking a window: " + window.location); - // Modify the window! - }, - onUntrack: function (window) { - console.log("Untracking a window: " + window.location); - // Undo your modifications! - } - }; - var winUtils = require("window-utils"); - var tracker = new winUtils.WindowTracker(delegate); - -<api name="WindowTracker"> -@constructor - A `WindowTracker` object listens for openings and closings of application - windows. -@param delegate {object} - An object that implements `onTrack()` and `onUntrack()` methods. -@prop onTrack {function} - A function to be called when a window is open or loads, with the window as the - first and only argument. -@prop [onUntrack] {function} - A function to be called when a window unloads, with the window as the first - and only argument. -</api> -</api> - -<api name="windowIterator"> -@function - An iterator for windows currently open in the application. - -**Example** - - var winUtils = require("window-utils"); - for (window in winUtils.windowIterator()) - console.log("An open window! " + window.location); - -</api> - -<api name="closeOnUnload"> -@function - Marks an application window to be closed when the program is unloaded. -@param window {window} - The window to close. -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/xhr.md b/tools/addon-sdk-1.3/packages/api-utils/docs/xhr.md deleted file mode 100644 index f2d3ee3..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/xhr.md +++ /dev/null @@ -1,91 +0,0 @@ -<!-- contributed by Atul Varma [atul@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> - -The `xhr` module provides access to `XMLHttpRequest` functionality, also known -as AJAX. - -## Limitations ## - -The `XMLHttpRequest` object is currently fairly limited, and does not -yet implement the `addEventListener()` or `removeEventListener()` -methods. It also doesn't yet implement the `upload` property. - -Furthermore, the `XMLHttpRequest` object does not currently support -the `mozBackgroundRequest` property. All security UI, such as -username/password prompts, are automatically suppressed, so if -required authentication information isn't passed to the `open()` -method, the request will fail. - -## Resource Use ## - -Whenever this module is unloaded, all in-progress requests are immediately -aborted. - -## Security Concerns ## - -By default, the `XMLHttpRequest` object grants full access to any -protocol scheme, which means that it can be used to read from (but not -write to) the host system's entire filesystem. It also has unfettered -access to any local area networks, VPNs, and the internet. - -### Threat Model ### - -The `XMLHttpRequest` object can be used by an add-on to "phone -home" and transmit potentially sensitive user data to third -parties. - -If access to the filesystem isn't prevented, it could easily be used -to access sensitive user data, though this may be inconsequential if -the client can't access the network. - -If access to local area networks isn't prevented, malicious code could access -sensitive data. - -If transmission of cookies isn't prevented, malicious code could access -sensitive data. - -Attenuating access based on a regular expression may be ineffective if -it's easy to write a regular expression that *looks* safe but contains -a special character or two that makes it far less secure than it seems -at first glance. - -### Possible Attenuations ### - -<span class="aside"> -We may also want to consider attenuating further based on domain name -and possibly even restricting the protocol to `https:` only, to reduce -risk. -</span> - -Before being exposed to unprivileged code, this object needs -to be attenuated in such a way that, at the very least, it can't -access the user's filesystem. This can probably be done most securely -by white-listing the protocols that can be used in the URL passed to -the `open()` method, and limiting them to `http:`, `https:`, and -possibly a special scheme that can be used to access the add-on's -packaged, read-only resources. - -Finally, we need to also consider attenuating http/https requests such -that they're "sandboxed" and don't communicate potentially sensitive -cookie information. - -<api name="XMLHttpRequest"> -@class - -<api name="XMLHttpRequest"> -@constructor - Creates an `XMLHttpRequest`. This is a constructor, so its use should always - be preceded by the `new` operator. For more information about - `XMLHttpRequest` objects, see the MDC page on - [Using XMLHttpRequest](https://developer.mozilla.org/En/Using_XMLHttpRequest) - and the Limitations section in this page. -</api> -</api> - -<api name="getRequestCount"> -@function - Returns the number of `XMLHttpRequest` objects that are alive (i.e., currently - active or about to be). -@returns {integer} - The number of live `XMLHttpRequest` objects. -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/xpcom.md b/tools/addon-sdk-1.3/packages/api-utils/docs/xpcom.md deleted file mode 100644 index 6cb5428..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/xpcom.md +++ /dev/null @@ -1,223 +0,0 @@ -Using this module you can: - -* register a component with -[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components), -making it available to all XPCOM clients -* retrieve a factory for a given XPCOM component -* generate a UUID - -The module also exposes the -[XPCOMUtils](https://developer.mozilla.org/en/JavaScript_code_modules/XPCOMUtils.jsm) -module. - -<api name="register"> -@function - -Makes a component available through XPCOM. - -This function creates and registers a factory for a component given a -constructor for it and some metadata: a -[class ID](https://developer.mozilla.org/en/Creating_XPCOM_Components/An_Overview_of_XPCOM#CID), a [contract ID](https://developer.mozilla.org/en/Creating_XPCOM_Components/An_Overview_of_XPCOM#Contract_ID), -and a name. - -<span class="aside">In this example the HelloWorld component is available to JavaScript only, so we use the technique documented under the "Using wrappedJSObject" section of [How to Build an XPCOM Component in JavaScript](https://developer.mozilla.org/en/How_to_Build_an_XPCOM_Component_in_Javascript).</span> - - var xpcom = require("xpcom"); - - function HelloWorld() { - this.wrappedJSObject = this; - } - - HelloWorld.prototype = { - QueryInterface: xpcom.utils.generateQI(), - hello: function() { - return "Hello World!"; - } - }; - - xpcom.register({name: "Hello World Component", - contractID: "@me.org/myComponent", - create: HelloWorld}); - -XPCOM clients can subsequently access this factory and use it to create -instances of the component. - - var {Ci} = require("chrome"); - - var factory = xpcom.getClass("@me.org/myComponent", Ci.nsIFactory); - var helloWorld = factory.createInstance(null, Ci.nsISupports).wrappedJSObject; - console.log(helloWorld.hello()); - -`register()` returns a Factory object for the component which implements -the `createInstance()` and `QueryInterface()` functions of the -[`nsIFactory`](https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIFactory) and -[`nsISupports`](https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsISupports) -interfaces, as well as defining an `unregister()` function to remove the -component from XPCOM. - -When the module is unloaded, all components registered via the `register()` -function are automatically unregistered. - -@param options {object} - -@prop [uuid] {nsIDPtr} -A [UUID](https://developer.mozilla.org/en/Generating_GUIDs) which will be -used as the -[class ID](https://developer.mozilla.org/en/Creating_XPCOM_Components/An_Overview_of_XPCOM#CID) -for this component. If you don't include this option, the `register()` -function will generate a new UUID. - -@prop create {function} -The constructor for the component. - -@prop name {string} -A human-readable name for the component. - -@prop contractID {string} -A human-readable string which will be used as the -[contract ID](https://developer.mozilla.org/en/Creating_XPCOM_Components/An_Overview_of_XPCOM#Contract_ID) -for the component. An XPCOM client will be able to use this value to access -the component. - -@returns {Factory} -See the documentation for the `Factory` class in this page. -</api> - -<api name="getClass"> -@function -Returns the factory object for the class specified by `contractID`. - -For example, given a registered XPCOM component which is identified with -the contract ID "@me.org/myComponent", we can access a factory and then -use it to instantiate the component in the following way: - - var xpcom = require("xpcom"); - var {Ci} = require("chrome"); - - var factory = xpcom.getClass("@me.org/myComponent", Ci.nsIFactory); - var helloWorld = factory.createInstance(null, Ci.nsISupports).wrappedJSObject; - console.log(helloWorld.hello()); - -@param contractID {string} -The -[contract ID](https://developer.mozilla.org/en/Creating_XPCOM_Components/An_Overview_of_XPCOM#Contract_ID) -for the component whose factory will be returned. - -@param [iid] {iid} -The interface type to be returned. These objects are usually accessed through -the `Components.interfaces`, or `Ci`, object. - -The methods of this interface will be callable on the returned factory object. -Usually you want this to be -[`Ci.nsIFactory`](https://developer.mozilla.org/En/nsIFactory), but if you know -a component has a factory that implements a more specific type of factory -interface, you can pass that interface here. If you don't include this option -only the methods of -[`nsISupports`](https://developer.mozilla.org/En/NsISupports) -will be callable, which is probably not what you want. - -@returns {object} -The factory object. The type of this object will depend on the value of the -`iid` argument. If no `iid` argument is specified it will be of type -[`nsISupports`](https://developer.mozilla.org/En/NsISupports). - -Note that this object is not a `Factory` object as defined by this module. -If you previously registered the component by calling the `register()` -function and you need to access the `Factory` object for the component, for -example to call the `Factory`'s `unregister()` method, you can do so by -getting the -[`wrappedJSObject`](https://developer.mozilla.org/en/wrappedJSObject) -property of the returned object: - - var factory = xpcom.getClass("@me.org/myComp", Ci.nsIFactory).wrappedJSObject; - factory.unregister(); - -</api> - -<api name="utils"> -@property {object} -The -[XPCOMUtils](https://developer.mozilla.org/en/JavaScript_code_modules/XPCOMUtils.jsm) -module. -</api> - -<api name="makeUuid"> -@function -Generates and returns a new -[UUID](https://developer.mozilla.org/en/Generating_GUIDs). - -Calling `toString()` on this object will yield the UUID in string form. -@returns {nsIDPtr} -</api> - -<api name="Factory"> -@class - -When a component is made available through XPCOM using the `register()` -function, `register()` returns a `Factory` object that can be used to -instantiate the component using its `createInstance()` function: - - var factory = require("xpcom").register({ - name: "My Component", - contractID: "@me.org/myComponent", - create: MyComponent - }); - - var {Ci} = require("chrome"); - var component = factory.createInstance(null, Ci.nsISupports).wrappedJSObject; - -In this example we haven't defined a custom interface ID for the component. -Instead we pass `Ci.nsISupports` as the interface ID, and use `wrappedJSObject` -to retrieve the component. For more details on this technique see the -[guide to building XPCOM components in JavaScript](https://developer.mozilla.org/en/How_to_Build_an_XPCOM_Component_in_Javascript). - -`Factory` also implements its own `unregister()` function, -which unregisters the component from XPCOM. - -<api name="createInstance"> -@method -Creates an instance of the component associated with this factory. - -@param outer {nsISupports} -This argument must be `null`, or the function throws -`Cr.NS_ERROR_NO_AGGREGATION`. - -@param iid {iid} -Interface identifier. These objects are usually accessed through -the `Components.interfaces`, or `Ci`, object. The methods of this -interface will be callable on the returned object. - -If the object implements an interface that's already defined in XPCOM, you -can pass that in here: - - var about = aboutFactory.createInstance(null, Ci.nsIAboutModule); - // You can now access the nsIAboutModule interface of the 'about' object - -If you will be getting the `wrappedJSObject` property from the returned -object to access its JavaScript implementation, pass `Ci.nsISupports` here: - - var custom = factory.createInstance(null, Ci.nsISupports).wrappedJSObject; - // You can now access the interface defined for the 'custom' object - -</api> - -<api name="QueryInterface"> -@method -This method is called automatically by XPCOM, so usually you don't need -to call it yourself. It returns the `Factory` object itself such that the -methods of the given interface are callable on it. - -@param interfaces {iid} -There are only two legal values for this parameter: `Ci.nsIFactory` and -`Ci.nsISupports`. Any other value will cause this method to throw -`Cr.NS_ERROR_NO_INTERFACE`. - -@returns {Factory} -</api> - -<api name="unregister"> -@method -Unregisters the factory's component. -</api> - -</api> diff --git a/tools/addon-sdk-1.3/packages/api-utils/docs/xul-app.md b/tools/addon-sdk-1.3/packages/api-utils/docs/xul-app.md deleted file mode 100644 index 00379db..0000000 --- a/tools/addon-sdk-1.3/packages/api-utils/docs/xul-app.md +++ /dev/null @@ -1,72 +0,0 @@ -<!-- contributed by Drew Willcoxon [adw@mozilla.com] --> - -The `xul-app` module provides facilities for introspecting the application on -which your program is running. - -With the exception of `ids`, each of these properties exposes the attribute of -the same name on the [`nsIXULAppInfo`][nsIXULAppInfo] interface. For more -information, see the [MDC documentation][]. - -[nsIXULAppInfo]: http://mxr.mozilla.org/mozilla-central/source/xpcom/system/nsIXULAppInfo.idl -[MDC documentation]: https://developer.mozilla.org/en/nsIXULAppInfo - -<api name="ID"> -@property {string} - The GUID of the host application. For example, for Firefox this value is - `"{ec8030f7-c20a-464f-9b0e-13a3a9e97384}"`. -</api> - -<api name="name"> -@property {string} - The host application name. For example, `"Firefox"`. -</api> - -<api name="version"> -@property {string} - The host application version. -</api> - -<api name="platformVersion"> -@property {string} - The Gecko/XULRunner platform version. -</api> - -<api name="ids"> -@property {object} - A mapping of application names to their IDs. For example, - `ids["Firefox"] == "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}"`. -</api> - -<api name="is"> -@function - Checks whether the host application is the given application. -@param name {string} - A host application name. -@returns {boolean} - True if the host application is `name` and false otherwise. -</api> - -<api name="isOneOf"> -@function - Checks whether the host application is one of the given applications. -@param names {array} - An array of host application names. -@returns {boolean} - True if the host application is one of the `names` and false otherwise. -</api> - -<api name="versionInRange"> -@function - Compares a given version to a version range. See the [MDC documentation](https://developer.mozilla.org/en/Toolkit_version_format#Comparing_versions) - for details on version comparisons. -@param version {string} - The version to compare. -@param lowInclusive {string} - The lower bound of the version range to compare. The range includes this - bound. -@param highExclusive {string} - The upper bound of the version range to compare. The range does not include - this bound. -@returns {boolean} - True if `version` falls in the given range and false otherwise. -</api> |