forked from xapi-project/xen-api
-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add internal links to XenAPI reference (xapi-project#6315)
Adds a simple parser for Xapi type expressions that is used to rewrite the types shown in the XenAPI class reference to include links to relevant documentation. ---  --- The parser is structured in the form of a Pratt parser. This may seem like overkill, but it keeps the door open to extension. Also, the parser must work with limited information (it has no knowledge of XenAPI object names). It works by noting that object types are always (?) suffixed by a type constructor, e.g. `VM ref` - therefore, it assumes any prefix form must be a valid class name, then subsequent left denotations take the left as a type parameter (for which all are unary, except `map` which has an alternative syntax that is special cased). Currently, the only interesting parts of the "rendered" type are: - Enum names become links that should scroll and temporarily highlight (flash) the relevant details. - Object names become links to their relevant page in the documentation. However, other structure is retained, such as where builtin (primitive) types are (e.g. int, bool, string, etc.), constructors names (ref, set, option, etc.). In future, these could link to relevant portions of a new article that explains all the types (for example, the format of datetime is perhaps non-obvious to someone reading the XenAPI reference pages).
- Loading branch information
Showing
3 changed files
with
214 additions
and
5 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -123,3 +123,7 @@ th { text-align: left; | |
| margin: 0; | ||
| vertical-align: middle; | ||
| } | ||
|
|
||
| div[id$='_details'] { | ||
| cursor: default; | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,146 @@ | ||
|
|
||
| class Type {}; | ||
|
|
||
| class Builtin extends Type { | ||
| constructor(name) { | ||
| super(); | ||
| this.name = name; | ||
| } | ||
|
|
||
| static ofString(s) { | ||
| const concrete = ['string', 'bool', 'int', 'float', 'void', 'datetime']; | ||
| if (!concrete.includes(s)) | ||
| return null; | ||
|
|
||
| return new Builtin(s); | ||
| } | ||
| }; | ||
|
|
||
| class Enum extends Type { | ||
| constructor(name) { | ||
| super(); | ||
| this.name = name; | ||
| } | ||
| }; | ||
|
|
||
| class Ctor extends Type { | ||
| constructor(params, name) { | ||
| super(); | ||
| this.params = params; | ||
| this.name = name; | ||
| } | ||
| }; | ||
|
|
||
| function lex(str) { | ||
| if (str.indexOf('$') >= 0) | ||
| throw new Error('Not allowed to contain $'); | ||
|
|
||
| let ts = str.replaceAll('(', ' ( '); | ||
| ts = ts.replaceAll(')', ' ) '); | ||
| ts = ts.split(' '); | ||
| ts = ts.filter(x => x !== ''); | ||
| ts.push('$'); | ||
| return ts; | ||
| } | ||
|
|
||
| class Lexer { | ||
| constructor(tokens) { | ||
| this.tokens = tokens; | ||
| this.pos = 0; | ||
| } | ||
|
|
||
| shift() { | ||
| if (this.pos >= this.tokens.length - 1) | ||
| return '$'; | ||
|
|
||
| return this.tokens[this.pos++]; | ||
| } | ||
|
|
||
| peek() { | ||
| const prev = this.pos; | ||
| let t = this.shift(); | ||
| this.pos = prev; | ||
| return t; | ||
| } | ||
|
|
||
| expect(ts) { | ||
| if (!Array.isArray(ts)) | ||
| ts = [ts]; | ||
|
|
||
| let l = this.shift(); | ||
| for (const t of ts) | ||
| if (l == t) return; | ||
|
|
||
| throw new Error(`Expected ${t}, got ${l}`); | ||
| } | ||
| }; | ||
|
|
||
| function lbp(t) { | ||
| switch (t) { | ||
| case '(': | ||
| case ')': | ||
| case '->': | ||
| case '\u2192': | ||
| return 0; | ||
| case '$': | ||
| return -1; | ||
| } | ||
|
|
||
| return 1; | ||
| } | ||
|
|
||
| function nud(l, t) { | ||
| switch (t) { | ||
| case 'enum': | ||
| return new Enum(l.shift()); | ||
|
|
||
| case '(': | ||
| let left = parseType(l, 0); | ||
| l.expect(['->', '\u2192']); | ||
| let right = parseType(l, 0); | ||
| l.expect(')'); | ||
| l.expect('map'); | ||
| return new Ctor([left, right], 'map'); | ||
| } | ||
|
|
||
| let bty = Builtin.ofString(t); | ||
| if (bty != null) | ||
| return bty; | ||
|
|
||
| const fmt = /^[a-zA-Z_]+$/; | ||
| if (fmt.test(t)) | ||
| return new Ctor([], t); | ||
|
|
||
| throw new Error(`No null denotation for ${t}`); | ||
| } | ||
|
|
||
| function led(l, left, t) { | ||
| const known = ['set', 'ref', 'option', 'record']; | ||
| if (!known.includes(t)) | ||
| throw new Error(`Invalid type constructor: ${t}`); | ||
|
|
||
| return new Ctor([left], t); | ||
| } | ||
|
|
||
| function parseType(l, rbp) { | ||
| let left = nud(l, l.shift()); | ||
|
|
||
| while (lbp(l.peek()) > rbp) | ||
| left = led(l, left, l.shift()); | ||
|
|
||
| return left; | ||
| } | ||
|
|
||
| function parseSingleType(input) { | ||
| try { | ||
| let lexer = new Lexer(lex(input)); | ||
| let ty = parseType(lexer, 0); | ||
| if (lexer.peek() != '$') | ||
| throw new Error('Did not consume entire input'); | ||
| return ty; | ||
| } catch (e) { | ||
| } | ||
|
|
||
| return null; | ||
| } | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters