Typed terms

[NotJustAnna]

This PR targets the creation of metadata for terms and optargs.

The idea:

• The terms/ directory contains a JSON file for each term type. Each JSON may be expanded with type information such as:
  • Signatures (a.k.a valid parameters)
  • Hierarchy (as in, is this included into top-level, table, expr, etc?)
• The types/ directory contains JSON files that describes extra term types.
  • One such use is to declare union types that terms and optargs may use.

Syntax:

Files will share a lot of syntax. Some type/signature definitions will be defined in the following pattern:

["union", ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]]
// or
["range", [0, 8]]
// or
["varags", []]

A lot of types will be declared in this way, to mimic function calling (and also due to how easy it should be to parse).

The main difference between terms/*.json and types/*.json will be that terms/*.json will declare actual term type information, while types/*.json will declare type aliases. By declaring type aliases, the overall size of files should be smaller and way more readable in general.

terms/*.json files should look like:

{
  "id": 78, // the numerical id of the term, available at ql2.proto
  "name": "GET_ALL", // the numerical id of the term, available at ql2.proto
  "include_in": ["terms/TABLE"] // can also be "model/toplevel", "model/expr", "model/ast", etc
  "signatures": [
    [ "terms/TABLE", [ "varargs", "model/EXPR" ] ] // this can be aliased to make the signature more readable.
  ],
  "optargs": {
    "index": "str"
  }
}

While types/*.json files should look like:

{
  "optargs/http_method": ["union", ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]],
  "varargs/expr": ["varargs", "model/EXPR"]
}

Extra documentation:

Explain the types and what should they mean.

Small documentation:

union

[ "union", [ literals, ...] ]

A union-based type accept only its' arguments as valid parameters.

• ["union", ["soft", "hard"]] may only accept "soft" and "hard", nothing else.
• Can be converted to union types in TypeScript. If all arguments are types, the type can be converted to a Java enum as well.

range

[ "range", [ from, to, step /* = 1 */ ] ]

A range-based type accepts values in a numerical range.

• ["range", [0, 8]] may only accept 0, 1, 2, 3, 4, 5, 6, 7, 8.
• This can generate runtime checks in a lot of languages. TypeScript may even be able to generate a type typeName = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8

varargs

[ "varargs", type ]

A varargs-based type should be the last type in a signature and will expand to a varargs/rest parameter.

[srh]

A few comments:

• I would add your comment in this PR as some form of README file in the repo.

• I don't know off-hand where ["range", ...] might be used. Oh, calendar stuff, I guess.

• Having type names and literal values be intermixed is kind of icky. Maybe some simple sort of discriminator for non-literal types like "@bool" is appropriate. At least coerce_to would run into problems with this. Also, coerce_to is case-insensitive, iirc. Maybe other string union types are, too, but coerce_to might be the only one.

• I would guess you want native_types.json to include the pseudotypes, binary, geometry, and time.

• There will need to be a way to represent non-datum types, like functions, selections, streams, and db: https://rethinkdb.com/api/javascript/type_of .

[srh]

Sorry, misclicked "close and comment".

[NotJustAnna]

• I would add your comment in this PR as some form of README file in the repo.

Yes, the comment is basically a initial version for a REQL.md file.

• I don't know off-hand where ["range", ...] might be used. Oh, calendar stuff, I guess.

Range was more a "if we can do unions, we can do range" sort of idea. Anyways, r.time is definitively a valid usage.

• Having type names and literal values be intermixed is kind of icky. Maybe some simple sort of discriminator for non-literal types like "@bool" is appropriate. At least coerce_to would run into problems with this. Also, coerce_to is case-insensitive, iirc. Maybe other string union types are, too, but coerce_to might be the only one.

My original idea was use @ to discriminate types, so I'll use the suggestion.

coerce_to might require union types to support some kind of "case_insensitive" flag.

• I would guess you want native_types.json to include the pseudotypes, binary, geometry, and time.
• There will need to be a way to represent non-datum types, like functions, selections, streams, and db: https://rethinkdb.com/api/javascript/type_of .

The idea of native_types.json is to let whatever interpreter replace it with it's native types (reason the types don't have meaning at all besides `"json_native"), so the pseudotypes and non-datum types should fit in those.