jden/jsig — pull request #13 by Raynos (2013-07-07 19:27:48+00:00)
Title: Added examples & updated README with my variantion

This is a discussion issue. I will list all the changes I made and then we can battle it out.

# Examples folder

I added an examples folder which the majority of my type definitions so far. The examples folder does contain constructs that I have not defined in the README yet.

# Grammar

I've added the start of a grammar definition which is far from complete.

## `name := `

I don't allow anonymous type declarations. I allow two types of declarations. The first one is saying `name := ` which generally means a lexical variable `name` has the type ``. I also use `name` to mean reference to name in npm.

Example (npm name):

```ocaml
continuable/map := (Continuable, (A) => B) => Continuable
```

Example (local name):

```ocaml
xhr := (XhrOptions, Callback) => HTTPRequest
```

## Removal of dot notation

I think I've removed it from the README because it's not needed. You can actually define the type of a lexical variable to just be an object

## consistent optional types

Optional types is now done purely through `String?` and `(opts?: Object)` is invalid and should be replaced with `(opts: Object?)`

## Introduce explicit type declarations

The second type of declaration is declaring a named type. Named types are not related to the npm namespace or the lexical variables in your program. Named types are purely defined and reference in other type signatures.

An example would be

```ocaml
type Callback := (err: Error, value: T) => void
type Continuable := (callback: Callback) => void
```

## Rename `Value` to `Any`

I've basically renamed the usage of `Value` to mean "any" type to usage of `Any` to mean "any" type

## Compound function types

Instead of defining the same lexical variable multiple times, one for each function signature you can use a compound signature

```ocaml
getOrSet :=
(Object, String) => T &
(Object, String, T) => void
```

## Replacing the notion of "named paramters" with "labelled types"

Instead of saying that we can name paramters, I've changed the wording to say that you can label any type.

Example:

```ocaml
add := (left: Number, right: Number) => result: Number
```

## Introducing the enum type

Enum is like the or type but more human readable. For example `type: "create" | "update" | "delete"` can be expressed as `type: Enum("create", "update", "delete")`

Example:

```ocaml
type Delta := {
id: String,
type: Enum("create", "update", "delete"),
changes: Object
}
```