Naming Conventions

This is a collection of naming conventions used by the Sunroof project.

Sunroof API

Whan writing function in Sunroof the following naming conventions should comply:

• No Prefix/Suffix: General combinators and API methods that return a JS t a do not get a suffix or prefix.

  Examples: apply, function, new;

• Suffix JS: Everything that takes a JS t a as argument has the suffix JS.

  Examples: forkJS, sunroofCompileJS;

• Prefix JS: Types that directly represent Javascript values (generaly all that implement Sunroof) should have JS as prefix.

  Examples: JSBool, JSString, JSDate;

• Prefix Sunroof: Classes that are tightly connected with Sunroof should have the prefix Sunroof.

  Examples: SunroofArgument, SunroofThread;

Javascript API Bindings

When providing bindings for Javascript APIs use the following naming conventions:

• General Rule: In general name the API functions and bindings exactly as the functions or objects are named in Javascript. Also be as specific about the types as possible in Sunroof without reducing the usability (there is always the possibility to cast values, but this should not happen all over the place).

  Example: document becomes document :: JSObject

• Group Arguments: Methods in Javascript may take many arguments. If there is a logical way to group them (e.g. coordinates as a tuple) do so. This will improve the usability of the API.

  Example: fillText(t,x,y) becomes fillText :: JSString -> (JSNumber, JSNumber) -> JS t () (example from Canvas API)

• Getters & Setters: Often Javascript objects provide a function o.foo() as getter and o.foo(v) as setter for a certain value foo of o. In the Haskell version of the API create a foo function for the getter and a setFoo function for the setter.

  Example: html([htmlString]) becomes html :: JSObject -> JS t JSString and setHtml :: JSString -> JSObject -> JS t JSObject (example from jQuery)

• Optional Arguments: Javascript functions allow for optional parameters. In the Haskell version of the API there are two ways to solve this:

  • If the Javascript function is very flexible (i.e. no constraints on the types and number of parameters) directly expose the arguments as a SunroofArgument.
  • If the Javascript function is not flexible (i.e. arguments are constrained in type and number) create a version that offers all parameters and one with only the most commonly used parameters. The version with all parameters has a prime at the end of its name.

  Example: new Array(...) becomes newArray :: (SunroofArgument args, Sunroof a) => args -> JS t (JSArray a)

  Example: fillText(t,x,y[,m]) becomes fillText :: JSString -> (JSNumber, JSNumber) -> JSCanvas -> JS t () and fillText' :: JSString -> (JSNumber, JSNumber) -> JSNumber -> JSCanvas -> JS t () (example from Canvas API)

• Keywords: If the name of a object or function collides with a keyword or common function in Haskell, append a prime to the name.

  Example: data becomes data' :: JSSelector JSObject (example from Canvas API)

• Higher Order Functions: If a function or method takes a function or continuation as argument, the parameter is given as a Haskell function, not as JSFunction or JSContinuation.

  Example: setTimeout :: (() -> JSB ()) -> JSNumber -> JSObject -> JS t JSNumber instead of setTimeout :: JSContinuation () -> JSNumber -> JSObject -> JS t JSNumber (example from JavaScript API)