Skip to content

Commit

Permalink
Add warning for Infra to JSON-JS-value algorithm
Browse files Browse the repository at this point in the history 
Also add some <div algorithm> and wrapping to the JSON section while there.
  • Loading branch information
@annevk
annevk authored Nov 14, 2024
1 parent 8bc6202 commit 79b945d
Showing 1 changed file with 43 additions and 22 deletions.
65 changes: 43 additions & 22 deletions infra.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1848,24 +1848,28 @@ without breaking literal syntax used by their dependencies. In that case a tuple
<p class=note>The conventions used in the algorithms in this section are those of the JavaScript
specification. [[!ECMA-262]]

<p>To <dfn export lt="parse a JSON string to a JavaScript value|parsing a JSON string to a JavaScript value">parse a JSON string to a JavaScript value</dfn>,
given a <a>string</a> |string|:
<div algorithm>
<p>To <dfn export>parse a JSON string to a JavaScript value</dfn>, given a <a>string</a> |string|:

<ol>
<li><p>Return ? [$Call$](<a>%JSON.parse%</a>, undefined, « |string| »).
</ol>
</div>

<p>To <dfn export lt="parse JSON bytes to a JavaScript value|parsing JSON bytes to a JavaScript value|parse JSON from bytes">parse JSON bytes to a JavaScript value</dfn>,
given a <a>byte sequence</a> |bytes|:
<div algorithm>
<p>To <dfn export>parse JSON bytes to a JavaScript value</dfn>, given a <a>byte sequence</a>
|bytes|:

<ol>
<li><p>Let |string| be the result of running <a>UTF-8 decode</a> on |bytes|. [[!ENCODING]]

<li><p>Return the result of <a>parsing a JSON string to a JavaScript value</a> given |string|.
</ol>
</div>

<p>To <dfn export lt="serialize a JavaScript value to a JSON string|serializing a JavaScript value to a JSON string">serialize a JavaScript value to a JSON string</dfn>,
given a JavaScript value |value|:
<div algorithm>
<p>To <dfn export>serialize a JavaScript value to a JSON string</dfn>, given a JavaScript value
|value|:

<ol>
<li>
Expand All @@ -1884,16 +1888,19 @@ given a JavaScript value |value|:

<li><p>Return |result|.
</ol>
</div>

<p>To <dfn export lt="serialize a JavaScript value to JSON bytes|serializing a JavaScript value to JSON bytes|serialize JSON to bytes">serialize a JavaScript value to JSON bytes</dfn>,
given a JavaScript value |value|:
<div algorithm>
<p>To <dfn export>serialize a JavaScript value to JSON bytes</dfn>, given a JavaScript value
|value|:

<ol>
<li><p>Let |string| be the result of <a>serializing a JavaScript value to a JSON string</a> given
|value|.

<li><p>Return the result of running <a>UTF-8 encode</a> on |string|. [[!ENCODING]]
</ol>
</div>

<hr>

Expand All @@ -1902,7 +1909,9 @@ the involved objects or arrays are tied to a particular <a lt="realm">JavaScript
standards, it is often more convenient to convert between JSON and realm-independent <a>maps</a>,
<a>lists</a>, <a>strings</a>, <a>booleans</a>, numbers, and nulls.

<p>To <dfn export lt="parse a JSON string to an Infra value|parsing a JSON string to an Infra value|parse JSON into Infra values">parse a JSON string to an Infra value</dfn>,
<div algorithm>
<p>To
<dfn export lt="parse a JSON string to an Infra value|parse JSON into Infra values">parse a JSON string to an Infra value</dfn>,
given a <a>string</a> |string|:

<ol>
Expand All @@ -1911,18 +1920,21 @@ given a <a>string</a> |string|:
<li><p>Return the result of [=converting a JSON-derived JavaScript value to an Infra value=], given
|jsValue|.
</ol>
</div>

<p>To <dfn export lt="parse JSON bytes to an Infra value|parsing JSON bytes to an Infra value">parse JSON bytes to an Infra value</dfn>,
given a <a>byte sequence</a> |bytes|:
<div algorithm>
<p>To <dfn export>parse JSON bytes to an Infra value</dfn>, given a <a>byte sequence</a> |bytes|:

<ol>
<li><p>Let |string| be the result of running <a>UTF-8 decode</a> on |bytes|. [[!ENCODING]]

<li><p>Return the result of <a>parsing a JSON string to an Infra value</a> given |string|.
</ol>
</div>

<p>To <dfn lt="convert a JSON-derived JavaScript value to an Infra value|converting a JSON-derived JavaScript value to an Infra value">convert a JSON-derived JavaScript value to an Infra value</dfn>,
given a JavaScript value |jsValue|:
<div algorithm>
<p>To <dfn>convert a JSON-derived JavaScript value to an Infra value</dfn>, given a JavaScript value
|jsValue|:

<ol>
<li><p>If |jsValue| is <emu-val>null</emu-val>, |jsValue| [=is a Boolean=], |jsValue|
Expand Down Expand Up @@ -1972,10 +1984,11 @@ given a JavaScript value |jsValue|:

<li><p>Return |result|.
</ol>
</div>

<p>To <dfn export lt="serialize an Infra value to a JSON string|serializing an Infra value to a JSON string">serialize an Infra value to a JSON string</dfn>,
given a <a>string</a>, <a>boolean</a>, number, null, <a>list</a>, or <a>string</a>-keyed <a>map</a>
|value|:
<div algorithm>
<p>To <dfn export>serialize an Infra value to a JSON string</dfn>, given a <a>string</a>,
<a>boolean</a>, number, null, <a>list</a>, or <a>string</a>-keyed <a>map</a> |value|:

<ol>
<li><p>Let |jsValue| be the result of
Expand All @@ -1987,21 +2000,22 @@ given a <a>string</a>, <a>boolean</a>, number, null, <a>list</a>, or <a>string</
<p class=note>Since no additional arguments are passed to <a>%JSON.stringify%</a>, the resulting
string will have no whitespace inserted.
</ol>
</div>

<p>To <dfn export lt="serialize an Infra value to JSON bytes|serializing an Infra value to JSON bytes">serialize an Infra value to JSON bytes</dfn>,
given a <a>string</a>, <a>boolean</a>, number, null, <a>list</a>, or <a>string</a>-keyed <a>map</a>
|value|:
<div algorithm>
<p>To <dfn export>serialize an Infra value to JSON bytes</dfn>, given a <a>string</a>,
<a>boolean</a>, number, null, <a>list</a>, or <a>string</a>-keyed <a>map</a> |value|:

<ol>
<li><p>Let |string| be the result of <a>serializing an Infra value to a JSON string</a>, given
|value|.

<li><p>Return the result of running <a>UTF-8 encode</a> on |string|. [[!ENCODING]]
</ol>
</div>

<p>To
<dfn export lt="convert an Infra value to a JSON-compatible JavaScript value|converting an Infra value to a JSON-compatible JavaScript value">convert an Infra value to a JSON-compatible JavaScript value</dfn>,
given |value|:
<div algorithm>
<p>To <dfn export>convert an Infra value to a JSON-compatible JavaScript value</dfn>, given |value|:

<ol>
<li><p>If |value| is a <a>string</a>, <a>boolean</a>, number, or null, then return |value|.
Expand Down Expand Up @@ -2050,6 +2064,13 @@ given |value|:
</ol>
</ol>

<p class=warning>Because it is rarely appropriate to manipulate JavaScript values directly in
specifications, prefer using <a>serialize an Infra value to a JSON string</a> or
<a>serialize an Infra value to JSON bytes</a> instead of using this algorithm. Please
<a href="https://github.com/whatwg/infra/issues/new">file an issue</a> to discuss your use case if
you believe you need to use <a>convert an Infra value to a JSON-compatible JavaScript value</a>.
</div>


<h2 id=forgiving-base64>Forgiving base64</h2>

Expand Down

0 comments on commit 79b945d

Please sign in to comment.