Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 11 additions & 5 deletions packages/marshal/docs/smallcaps-cheatsheet.md
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 |
| -----------------|---------------|-----------------------|----------------------|
Expand All @@ -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>}` |
Copy link
Contributor

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 and y? is it only string and thus the <x> and <y> are simply the encoded strings ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. Resolving.

Copy link
Contributor

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.

Copy link
Contributor Author

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.

| tagged | Tagged | `makeTagged(t,p)` | `{"#tag":<t>,"payload":<p>}` |
Expand All @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The 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).

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.
Copy link
Contributor

Choose a reason for hiding this comment

The 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 JSON.serialize that would similarly produce different encodings.

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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***.