JSIDL

Working Draft — 12 April 2013

This version:
http://wycats.github.io/jsidl/jsidl.html
Editors:
Yehuda Katz, jQuery Foundation,

CC0
To the extent possible under law, Yehuda Katz has waived all copyright and related or neighboring rights to JSIDL.

Abstract

This document is an attempt to define an ECMAScript focused IDL for use by web specifications.

It is a work in progress and is still missing a significant amount of semantics provided by the current WebIDL specification.

Status

This is a work in progress.

Among many other things, it still needs a formal description of the syntax of JSIDL, a description of the programming environment, and a description and specification of a branding mechanism.

This document is not yet ready for wide feedback and is being circulated to get the work I'm doing on this topic into the open. It is still at an extremely early stage.

Table of Contents

  1. 1 Coercions
  2. 2 Coercion Rules
    1. 2.1 any
    2. 2.2 ToBoolean
    3. 2.3 ToInteger
    4. 2.4 ToPositiveInteger
    5. 2.5 ToNumber
    6. 2.6 ToString
    7. 2.7 ToObject
    8. 2.8 class or interface
    9. 2.9 options
    10. 2.10 enum
  3. 3 Function Arguments
    1. 3.1 Default Arguments
  4. Acknowledgements

1 Coercions

Note

JSIDL does not define any "types". Instead, it defines a series of coercion rules that can be applied to an input value and produce an output value.

In some cases, those coercion rules may produce an error, either by virtue of delegation to ECMAScript algorithms, or as defined in the algorithms themselves.

2 Coercion Rules

This section describes how to coerce values when:

Each sub-section below describes how to coerce a value using the specified coercion rule.

2.1 any

No coercion is performed.

2.2 ToBoolean

A value V is coerced to a ToBoolean value using the ECMAScript ToBoolean abstract operation.

2.3 ToInteger

A value V is coerced to a ToInteger value using the ECMAScript ToInteger abstract operation.

2.4 ToPositiveInteger

A value V is coerced to a ToPositiveInteger value using the ECMAScript ToPositiveInteger abstract operation.

2.5 ToNumber

A value V is coerced to a ToNumber value using the ECMAScript ToNumber abstract operation.

2.6 ToString

A value V is coerced to a ToString value using the ECMAScript ToString abstract operation.

2.7 ToObject

A value V is coerced to a ToObject value using the ECMAScript ToObject abstract operation.

Note

WebIDL requires that the value V return Object for Type(V).

However, this coercion is not uniformly implemented, and coercing primitives to objects in this situation is more consistent with similar built-in ECMAScript operations.

2.8 class or interface

Each platform-defined class or interface installs a non-forgable Brand on each object using its @@create method.

A value V is coerced to a class or interface value by performing the following algorithm.

  1. If V has the brand B, return V.
  2. Throw a TypeError.

2.9 options

An options type is an ObjectBindingPattern with type annotations.

Note

This algorithm boils down to:

  1. Checking whether ECMAScript would throw if attempting to perform the destructuring assignment represented by the options pattern.
  2. Recursively running the coercions for the specified types.
  3. Returning the coerced value
TODO

Work through the most elegant way to define these coercion in terms of ECMAScript

2.10 enum

An enum is a set of strings E.

A value V is coerced into an enum E as follows.

  1. Let S be the result of calling ToString(V).
  2. If S is not in E, throw a RangeError.
  3. return S.

3 Function Arguments

Function parameters are specified in JSIDL as a coercion-annotated FormalParameterList.

If a parameter is specified without a default, it is a TypeError to call the function without specifying that parameter.

3.1 Default Arguments

Default arguments are specified as in ECMAScript, by following the parameter's name with an Initialiser.

As a shortcut, =undefined may be replaced with ?.

Example
IDL

class ColorCreator {
  object createColor(number v1, number v2, number v3, number alpha?);
}

In this example, createColor must be called with three or four arguments. If the fourth argument is omitted, its value will be undefined.

Acknowledgements

Thanks to Dave Herman and Sam Tobin-Hochstadt for helping me work through some semantic differences with WebIDL. Thanks to Anne van Kesteren and Boris Zbarsky for helping me with the precise semantics of existing specs. Thanks to Alex Russell for the inspiration to begin this project.