-
Notifications
You must be signed in to change notification settings - Fork 78
docs(marshal): expand smallcaps readability invariants #2954
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,6 @@ | ||
# Smallcaps Cheatsheet | ||
|
||
An example-based summary of the Smallcaps encoding on the OCapN [Abstract Syntax](https://github.com/ocapn/ocapn/blob/28af626441da888c4a520309222e18266dd2f1f2/draft-specifications/Model.md) (as of https://github.com/ocapn/ocapn/pull/125). (TODO revise link once that PR is merged.) | ||
An example-based summary of the Smallcaps encoding of the OCapN [Abstract Syntax](https://github.com/ocapn/ocapn/blob/main/draft-specifications/Model.md). | ||
|
||
| pass-style name | OCapn name | JS example | JSON encoding | | ||
| -----------------|---------------|-----------------------|----------------------| | ||
|
@@ -11,7 +11,7 @@ An example-based summary of the Smallcaps encoding on the OCapN [Abstract Syntax | |
| number | Float64 | `Infinity`<br>`-Infinity`<br>`NaN`<br>`-0`<br>`7.1` | `"#Infinity"`<br>`"#-Infinity"`<br>`"#NaN"`<br>`"#-0"` // unimplemented<br>`7.1` | | ||
| string | String | `'#foo'`<br>`'foo'` | `"!#foo"` // special strings<br>`"foo"` // other strings | | ||
| byteArray | ByteArray | `buf.toImmutable()` | // undecided & unimplemented | | ||
| selector | Selector | `makeSelector('foo')` | `"%foo"` // converting from symbol | | ||
| passable symbols | Symbol | `passableSymbolForName('foo')` | `"%foo"` // in transition | | ||
| copyArray | List | `[a,b]` | `[<a>,<b>]` | | ||
| copyRecord | Struct | `{x:a,y:b}` | `{<x>:<a>,<y>:<b>}` | | ||
| tagged | Tagged | `makeTagged(t,p)` | `{"#tag":<t>,"payload":<p>}` | | ||
|
@@ -20,14 +20,20 @@ An example-based summary of the Smallcaps encoding on the OCapN [Abstract Syntax | |
| error | Error | `TypeError(msg)` | `{"#error":<msg>,"name":"TypeError"}` | | ||
|
||
* The `-0` encoding is defined as above, but not yet implemented in JS. | ||
* In JS, selectors in transition from symbols to their own representation | ||
* In JS, passable symbols are in transition from JavaScript symbols to their own representation | ||
* The number after `"$"` or `"&"` is an index into a separate slots array. | ||
* Special strings begin with any of the `!"#$%&'()*+,-` characters. | ||
* ***Special strings*** begin with any of the `!"#$%&'()*+,-` characters. | ||
* `<expr>` is nested encoding of `expr`. | ||
* To be passable, arrays, records, and errors must also be hardened. | ||
* Structs [can only have string-named properties](https://github.com/endojs/endo/blob/master/packages/pass-style/doc/copyRecord-guarantees.md). | ||
* Errors can also carry an optional `errorId` string property. | ||
* We expect to expand the optional error properties over time. | ||
* The ByteArray encoding is not yet designed or implemented. | ||
|
||
Every JSON encoding with no special strings anywhere decodes to itself. | ||
## Readability Invariants | ||
|
||
For every JSON encoding with no special strings, the JSON and smallcaps decodings are the same. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think copilot had a point here. What does it mean for a "JSON encoding" to be with a special string? Special string is in the realm of the value to be encoded (or that was decoded). There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. In any JSON encoding, there is a concrete lexical element for "string" that is always quoted. https://www.json.org/json-en.html |
||
|
||
For every value with no special strings that round trips through JSON, the JSON and smallcaps encodings are the same. | ||
erights marked this conversation as resolved.
Show resolved
Hide resolved
erights marked this conversation as resolved.
Show resolved
Hide resolved
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I thought we established that the ocapn specification does not define a canonical encoding. Isn't it allowed for the encoding to be different yet equivalent, and as such a small caps implementation is not required to follow the exact semantics of json encoding (e.g. in struct field order). Furthermore there are many ways to encode strings, and there are indentation settings in There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't understand. I'm not referring to any concrete encoding mandated by ocapn. Indeed, ocaps itself is likely to mandate something completely different. I only speaking here about the smallcaps vs JSON, and about the smallcaps concrete encoding of the ocapn abstract-syntax/data-model. |
||
|
||
In other words, for these simple values, ***you can ignore the differences between smallcaps and JSON***. | ||
erights marked this conversation as resolved.
Show resolved
Hide resolved
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
what pass-styles are allowed for
x
andy
? is it only string and thus the<x>
and<y>
are simply the encoded strings ?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes. Resolving.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not in scope for this PR, but it would be nice to clarify that in this doc. I ended up finding the information in the ocapn spec, but besides that, most of the doc is pretty standalone.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Unresolving this one because it should be simple enough to do. I'll consider it as a drive-by.