IDL for JavaScript

The purpose of this project is simply to provide IDL definitions to JavaScript in a JavaScript friendly manner. IDL is converted to JSON, types are normalized to their JavaScript counterpart, and definitions are flattened down from multiple "implements", etc. The result is something that's actually usable and useful directly in JavaScript.

Usage

For regular usage, simply use the specific json files needed. If using from Node.js, install this module:

npm install idl4js

A function for each json file is exported that will load it for you.

var html5 = require('idl4js').html5(),
    dom4 = require('id4js').dom4();

Schema

At the top level is the definition type. The vast majority of definitions are interfaces. A handful are dictionaries which are exclusively used for initializing event objects. A smaller handful are enums.

type: one of ["interface", "dictionary", "exception", "enum", "callback"]
inherits: an array containing the names that the item inherits from. Items in idl can have multiple inheritance which is manifested in JavaScript as a flattening of all but the primary one together onto the prototype.
readonly: a list of attributes that instances have which can't be changed from JavaScript. List as a dict of name -> type.
methods: a list of methods that appear on the prototype. Methods can have the following:
- returns: the type of value returned. If missing then the method doesn't return anything.
- args: a list of arguments by name -> type, in order.
properties: a list of mutable properties by name -> type
constants: A list of constant names and their values.
defaults: For dictionaries, a list of dictionary members and their default values
indexed: if an item is indexed then it will have numbered properties, an "item" method, and a length. The type of value is indicated, as well as whether the items are writable, deletable, and creatable.
keyed: similar to indexed, except the items are named instead of indexed. CSS properties are an example of this.
construct: if an item is constructable via new in JavaScript then it will have this property, which includes the name of the constructor and args.

Arrays of items are listed with '...' after their name. This indicates that JavaScript Array type is either accepted or returned as opposed to some DOM Collection type.

Multiple accepted types in args lists are indicated as arrays.

Example

An abbreviated version of Window:

{
  "Window": {
    "type": "interface",
    "inherits": ["EventTarget"],
    "readonly": {
      "window": "Window",
      "self": "Window"
    },
    "properties": {
      "name": "String",
      "status": "String",
      "opener": "Window",
      "onabort": "EventHandler",
    },
    "methods": {
      "close": {},
      "stop": {},
      "open": {
        "returns": "Window",
        "args": {
          "url": "String",
          "target": "String",
          "features": "String",
          "replace": "Boolean"
        }
      },
      "setTimeout": {
        "returns": "Int32",
        "args": {
          "handler": ["Function", "String"],
          "timeout": "Int32",
          "arguments": "Any"
        }
      },
      "clearTimeout": {
        "args": {
          "handle": "Int32"
        }
      }
    }
  }
}

Included

html5 also includes a few extras like ShadowDOM and XHR

sgml / idl-for-javascript Goto Github PK