Specs: default arguments

sky/specs/apis.md

 APIs
 ====
 
 The Sky core API
 ----------------
 
 ```javascript
 module 'sky:core' {
 
   // EVENTS
 
   class Event {
-    constructor (String type, Boolean bubbles, any data); // O(1)
+    constructor (String type, Boolean bubbles = true, any data = null); // O(1)
     readonly attribute String type; // O(1)
     readonly attribute Boolean bubbles; // O(1)
     attribute any data; // O(1)
 
     readonly attribute EventTarget target; // O(1)
     void preventDefault(); // O(1)
     attribute any result; // O(1) // defaults to undefined
 
     // TODO(ianh): do events get blocked at scope boundaries, e.g. focus events when both sides are in the scope?
     // TODO(ianh): do events ger retargetted, e.g. focus when leaving a custom element?
@@ skipping 29 matching lines @@
     readonly attribute ParentNode? parentNode; // O(1)
     readonly attribute Element? parentElement; // O(1) // if parentNode isn't an element, returns null
     readonly attribute ChildNode? previousSibling; // O(1)
     readonly attribute ChildNode? nextSibling; // O(1)
     
     // the following all throw if parentNode is null
     void insertBefore(ChildArgument... nodes); // O(N) in number of arguments plus all their descendants
     void insertAfter(ChildArgument... nodes); // O(N) in number of arguments plus all their descendants
     void replaceWith(ChildArgument... nodes); // O(N) in number of descendants plus arguments plus all their descendants
     void remove(); // O(N) in number of descendants
-    Node cloneNode(Boolean deep); // O(1) if deep=false, O(N) in the number of descendants if deep=true
+    Node cloneNode(Boolean deep = false); // O(1) if deep=false, O(N) in the number of descendants if deep=true
 
     // called when parentNode changes
     virtual void parentChangeCallback(ParentNode? oldParent, ParentNode? newParent, ChildNode? previousSibling, ChildNode? nextSibling); // O(N) in descendants (calls attached/detached)
     virtual void attachedCallback(); // noop
     virtual void detachedCallback(); // noop
   }
 
   abstract class ParentNode : Node {
     readonly attribute ChildNode? firstChild; // O(1)
     readonly attribute ChildNode? lastChild; // O(1)
     
     // Returns a new Array every time.
     Array<ChildNode> getChildNodes(); // O(N) in number of child nodes
     Array<Element> getChildElements(); // O(N) in number of child nodes // TODO(ianh): might not be necessary if we have the parser drop unnecessary whitespace text nodes
 
     void append(ChildArgument... nodes); // O(N) in number of arguments plus all their descendants
     void prepend(ChildArgument... nodes); // O(N) in number of arguments plus all their descendants
     void replaceChildrenWith(ChildArgument... nodes); // O(N) in number of descendants plus arguments plus all their descendants
   }
 
   class Attr {
-    constructor (String name, String value); // O(1)
+    constructor (String name, String value = ''); // O(1)
     readonly attribute String name; // O(1)
     readonly attribute String value; // O(1)
   }
 
   abstract class Element : ParentNode {
     readonly attribute String tagName; // O(1)
 
     Boolean hasAttribute(String name); // O(N) in arguments
     String getAttribute(String name); // O(N) in arguments
-    void setAttribute(String name, String value); // O(N) in arguments
+    void setAttribute(String name, String value = ''); // O(N) in arguments
     void removeAttribute(String name); // O(N) in arguments
     
     // Returns a new Array and new Attr instances every time.
     Array<Attr> getAttributes(); // O(N) in arguments
 
     readonly attribute ShadowRoot? shadowRoot; // O(1) // returns the shadow root
     Array<ContentElement> getDestinationInsertionPoints(); // O(N) in number of insertion points the node is in
 
     virtual void attributeChangeCallback(String name, String? oldValue, String? newValue); // noop
     // TODO(ianh): does a node ever need to know when it's been redistributed?
   }
 
   class Text : Node {
-    constructor (String value); // O(1)
+    constructor (String value = ''); // O(1)
     attribute String value; // O(1)
 
     void replaceWith(String node); // O(1) // special case override of Node.replaceWith()
 
     virtual void valueChangeCallback(String? oldValue, String? newValue); // noop
   }
 
   class DocumentFragment : ParentNode {
     constructor (ChildArguments... nodes); // O(N) in number of arguments plus all their descendants
   }
@@ skipping 83 matching lines @@
     constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
     constructor (ChildArguments... nodes); // shorthand
     constructor (Dictionary attributes); // shorthand
     constructor (); // shorthand
   }
 
 
 
   dictionary ElementRegistration {
     String tagName;
-    Boolean shadow;
-    Object prototype;
+    Boolean shadow = false;
+    Object prototype = Element;
   }
 
   interface ElementConstructor {
     constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
     constructor (ChildArguments... nodes); // shorthand
     constructor (Dictionary attributes); // shorthand
     constructor (); // shorthand
 
     constructor attribute String tagName;
   }
@@ skipping 83 matching lines @@
     // properties
     readonly attribute ReturnType attributeName; // getter
     attribute ReturnType attributeName; // getter and setter
 
     // methods and constructors
     constructor ();
     ReturnType method();
       // When the platform calls this method, it always invokes the "real" method, even if it's been
       // deleted from the prototypes (as if it took a reference to the method at startup, and stored
       // state using Symbols)
+      // Calling a method with fewer arguments than defined will throw.
+      // Calling a method with more arguments ignores the extra arguments.
     virtual ReturnType methodCallback();
       // when the platform calls this, it actually calls it the way JS would, so author overrides do
       // affect what gets called. Make sure if you override it that you call the superclass implementation!
       // The default implementations of 'virtual' methods all end by calling the identically named method
       // on the superclass, if there is such a method.
 
     // properties on the constructor
     constructor readonly attribute ReturnType staticName;
 
     // private APIs - see below
     private void method();
 
     // arguments and overloading are done as follows
     // note that the argument names are only for documentation purposes
     ReturnType method(ArgumentType argumentName1, ArgumentType argumentName2);
     // the last argument's type can have "..." appended to it to indicate a varargs-like situation
     ReturnType method(ArgumentType argumentName1, ArgumentType... allSubsequentArguments);
+    // trailing arguments can have a default value, which must be a literal of the given type
+    ReturnType method(ArgumentType argumentName1, ArgumentType argumentName2 = defaultValue);
   }
 
   dictionary Options {
-    String foo;
-    Integer bar;
+    String foo; // if there's no default, the property must be specified or it's a TypeError
+    Integer bar = 4; // properties can have default values
   }
 
   // the module can have properties and methods also
   attribute String Foo;
   void method();
 
   interface InterfaceName {
     // describes a template of a prototype, in the same syntax as a class
     // not actually exposed in the runtime
   }
@@ skipping 27 matching lines @@
 ```
 
 ### Types ###
 
 The following types are available:
 
 * ``Integer`` - WebIDL ``long long``
 * ``Float`` - WebIDL ``double``
 * ``String`` - WebIDL ``USVString``
 * ``Boolean`` - WebIDL ``boolean``
-# ``Object`` - WebIDL ``object``
+# ``Object`` - WebIDL ``object`` (``ClassName`` can be used as a literal for this type)
 * ``ClassName`` - an instance of the class ClassName
 * ``DictionaryName`` - an instance of the dictionary DictionaryName
 * ``Promise<Type>`` - WebIDL ``Promise<T>``
 * ``Array<Type>`` - WebIDL ``sequence<T>``
 * ``Dictionary`` - unordered set of name-value String-String pairs with no duplicate names
-* ``Type?`` - union of Type and the singleton type with value "null" (WebIDL nullable)
+* ``Type?`` - union of Type and the singleton type with value ``null`` (WebIDL nullable)
 * ``(Type1 or Type2)`` - union of Type1 and Type2 (WebIDL union)
 * ``any`` - union of all types (WebIDL ``any``)
 
 Methods that return nothing (undefined, in JS) use the keyword "void"
 instead of a type.
 
-TODO(ianh): Figure out what should happen with omitted and extraneous parameters
 
 TODO(ianh): Define in detail how this actually works
 
 
 Mojom IDL
 ---------
 
 The Mojom IDL language is used to describe the APIs exposed over Mojo
 pipes.
 
@@ skipping 12 matching lines @@
   the core mojo fabric JS API   sky:mojo:fabric:core
   the asyncWait/cancelWait mojo fabric JS API (interface to IPC thread)  sky:mojo:fabric:ipc
   the mojom for the shell, proxying through C++ so that the shell pipe isn't exposed  sky:mojo:shell
   the sky API  sky:core
   the sky debug symbols for private APIs  sky:debug
 ```
 
 TODO(ianh): determine if we want to separate the "this" from the
 Document, especially for Modules, so that exposing a module's element
 doesn't expose the module's exports attribute.