Skip to content

Commit

Permalink
Added examples
Browse files Browse the repository at this point in the history
  • Loading branch information
@cyberphone
cyberphone committed Sep 27, 2024
1 parent 9fcc801 commit a952b2e
Show file tree
Hide file tree
Showing 4 changed files with 125 additions and 7 deletions.
7 changes: 6 additions & 1 deletion build/document-template.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -503,9 +503,14 @@ <h3 id='toc'>Table of Contents</h3>
<a href='#main.diagnostic'>Diagnostic Notation</a>.
</li>
</ul>
${EXAMPLES}
This section provides a few examples on how to use the CBOR API.
${EXAMPLES_ENC}
${EXAMPLES_DEC}
${EXAMPLES_DN_DEC}
${VERSION_INFO}
API version: 1.0.8. Note that the current API version is accessible through
the static property <code>CBOR.version</code>.<br>
Document version: 2024-09-25
Document version: 2024-09-27
</body>
</html>
98 changes: 96 additions & 2 deletions build/src/CreateDocument.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -773,7 +773,15 @@ the mentioned exceptional floating point values will (if encountered),

static final String DIAGNOSTIC_NOTATION = "${DIAGNOSTIC_NOTATION}";

static final String DETERMINISTIC_ENCODING = "${DETERMINISTIC_ENCODING}";
static final String DETERMINISTIC_ENCODING = "${DETERMINISTIC_ENCODING}";

static final String EXAMPLES = "${EXAMPLES}";

static final String EXAMPLES_ENC = "${EXAMPLES_ENC}";

static final String EXAMPLES_DEC = "${EXAMPLES_DEC}";

static final String EXAMPLES_DN_DEC = "${EXAMPLES_DN_DEC}";

static final String VERSION_INFO = "${VERSION_INFO}";

Expand Down Expand Up @@ -1224,7 +1232,8 @@ String printTableOfContents() {
String image = "empty.svg' style='height:1em;margin-right:1em";
if (next > tocEntry.indent && next < 3) {
startOf = true;
image = "closed.svg' onclick='tocSwitch(this)' style='height:1em;margin-right:1em;cursor:pointer";
image = "closed.svg' onclick='tocSwitch(this)' " +
"style='height:1em;margin-right:1em;cursor:pointer";
}
s.append("<div style='margin:0 0 0.4em ")
.append((tocEntry.indent * 2) + 2)
Expand Down Expand Up @@ -1252,6 +1261,78 @@ String printTableOfContents() {
return s.toString();
}

String htmlize(String text) {
return text.replace("&", "&amp;")
.replace("\"", "&quot;")
.replace("<", "&lt;")
.replace(">", "&gt;")
.replace(" ", "&nbsp;")
.replace("\n", "<br>");
}

String codeBlock(String rawCode) {
return
"<div class='webpkifloat'><div class='webpkibox' style='margin-left:2em;width:50em'>" +
htmlize(rawCode) +
"</div></div>";
}

String exampleEncode() {
return
"""
The following code shows how you can <i>create</i> CBOR-encoded data:
""" +
codeBlock("""
let cbor = CBOR.Map()
.set(CBOR.Int(1), CBOR.Float(45.7))
.set(CBOR.Int(2), CBOR.String("Hi there!")).encode();
console.log(CBOR.toHex(cbor));
--------------------------------------------
a201fb4046d9999999999a0269486920746865726521
""");
}

String exampleDecode() {
return
"""
The following code shows how you can <i>decode</i> CBOR-encoded data,
here using the result of the <i>encoding</i> example:
""" +
codeBlock("""
let map = CBOR.decode(cbor);
console.log(map.toString()); // Diagnostic notation
----------------------------------------------------
{
1: 45.7,
2: "Hi there!"
}
console.log('Value=' + map.get(CBOR.Int(1)));
---------------------------------------------
Value=45.7
""");
}

String exampleDNDecode() {
return
"""
The following code shows how you can <i>decode</i> CBOR specified in
<a href='#main.diagnostic'>Diagnostic&nbsp;Notation</a>:
""" +
codeBlock("""
let cbor = CBOR.diagDecode(`{
# Comments are also permitted
1: 45.7,
2: "Hi there!"
}`).encode();
console.log(CBOR.toHex(cbor));
------------------------------
a201fb4046d9999999999a0269486920746865726521
""");
}

void replace(String handle, String with) {
template = template.replace(handle, with);
}
Expand Down Expand Up @@ -1617,6 +1698,19 @@ void intMethods(Wrapper wrapper) {
replace(DETERMINISTIC_ENCODING, printMainHeader("deterministic", "Deterministic Encoding"));
outline.increment();

replace(EXAMPLES, printMainHeader("examples", "Using the CBOR API"));
outline.indent();
replace(EXAMPLES_ENC, printSubHeader("examples.encoding", "Encode CBOR") +
exampleEncode());
outline.increment();
replace(EXAMPLES_DEC, printSubHeader("examples.decoding", "Decode CBOR") +
exampleDecode());
outline.increment();
replace(EXAMPLES_DN_DEC, printSubHeader("examples.dn-decoding", "Using Diagnostic Notation") +
exampleDNDecode());
outline.undent();
outline.increment();

replace(VERSION_INFO, printMainHeader("version", "Version"));
outline.increment();

Expand Down
25 changes: 22 additions & 3 deletions doc/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,12 @@ <h3 id='toc'>Table of Contents</h3>
</div>
<div style='margin:0 0 0.4em 2em'><img alt='n/a' src='empty.svg' style='height:1em;margin-right:1em'><a href='#main.diagnostic'>7.&nbsp;&nbsp;Diagnostic Notation</a></div>
<div style='margin:0 0 0.4em 2em'><img alt='n/a' src='empty.svg' style='height:1em;margin-right:1em'><a href='#main.deterministic'>8.&nbsp;&nbsp;Deterministic Encoding</a></div>
<div style='margin:0 0 0.4em 2em'><img alt='n/a' src='empty.svg' style='height:1em;margin-right:1em'><a href='#main.version'>9.&nbsp;&nbsp;Version</a></div>
<div style='margin:0 0 0.4em 2em'><img alt='n/a' src='closed.svg' onclick='tocSwitch(this)' style='height:1em;margin-right:1em;cursor:pointer'><a href='#main.examples'>9.&nbsp;&nbsp;Using the CBOR API</a></div><div style='display:none'>
<div style='margin:0 0 0.4em 4em'><img alt='n/a' src='empty.svg' style='height:1em;margin-right:1em'><a href='#examples.encoding'>9.1.&nbsp;&nbsp;Encode CBOR</a></div>
<div style='margin:0 0 0.4em 4em'><img alt='n/a' src='empty.svg' style='height:1em;margin-right:1em'><a href='#examples.decoding'>9.2.&nbsp;&nbsp;Decode CBOR</a></div>
<div style='margin:0 0 0.4em 4em'><img alt='n/a' src='empty.svg' style='height:1em;margin-right:1em'><a href='#examples.dn-decoding'>9.3.&nbsp;&nbsp;Using Diagnostic Notation</a></div>
</div>
<div style='margin:0 0 0.4em 2em'><img alt='n/a' src='empty.svg' style='height:1em;margin-right:1em'><a href='#main.version'>10.&nbsp;&nbsp;Version</a></div>

<h3 id='main.intro'>1.&nbsp;&nbsp;Introduction</h3>

Expand Down Expand Up @@ -1497,10 +1502,24 @@ <h3 id='main.deterministic'>8.&nbsp;&nbsp;Deterministic Encoding</h3>
<a href='#main.diagnostic'>Diagnostic Notation</a>.
</li>
</ul>
<h3 id='main.version'>9.&nbsp;&nbsp;Version</h3>
<h3 id='main.examples'>9.&nbsp;&nbsp;Using the CBOR API</h3>

This section provides a few examples on how to use the CBOR API.
<h5 id='examples.encoding'>9.1.&nbsp;&nbsp;Encode CBOR</h5>
The following code shows how you can <i>create</i> CBOR-encoded data:
<div class='webpkifloat'><div class='webpkibox' style='margin-left:2em;width:50em'>let&nbsp;cbor&nbsp;=&nbsp;CBOR.Map()<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.set(CBOR.Int(1),&nbsp;CBOR.Float(45.7))<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.set(CBOR.Int(2),&nbsp;CBOR.String(&quot;Hi&nbsp;there!&quot;)).encode();<br><br>console.log(CBOR.toHex(cbor));<br>--------------------------------------------<br>a201fb4046d9999999999a0269486920746865726521<br></div></div>
<h5 id='examples.decoding'>9.2.&nbsp;&nbsp;Decode CBOR</h5>
The following code shows how you can <i>decode</i> CBOR-encoded data,
here using the result of the <i>encoding</i> example:
<div class='webpkifloat'><div class='webpkibox' style='margin-left:2em;width:50em'>let&nbsp;map&nbsp;=&nbsp;CBOR.decode(cbor);<br>console.log(map.toString());&nbsp;&nbsp;//&nbsp;Diagnostic&nbsp;notation<br>----------------------------------------------------<br>{<br>&nbsp;&nbsp;1:&nbsp;45.7,<br>&nbsp;&nbsp;2:&nbsp;&quot;Hi&nbsp;there!&quot;<br>}<br><br>console.log('Value='&nbsp;+&nbsp;map.get(CBOR.Int(1)));<br>---------------------------------------------<br>Value=45.7<br></div></div>
<h5 id='examples.dn-decoding'>9.3.&nbsp;&nbsp;Using Diagnostic Notation</h5>
The following code shows how you can <i>decode</i> CBOR specified in
<a href='#main.diagnostic'>Diagnostic&nbsp;Notation</a>:
<div class='webpkifloat'><div class='webpkibox' style='margin-left:2em;width:50em'>let&nbsp;cbor&nbsp;=&nbsp;CBOR.diagDecode(`{<br>#&nbsp;Comments&nbsp;are&nbsp;also&nbsp;permitted<br>&nbsp;&nbsp;1:&nbsp;45.7,<br>&nbsp;&nbsp;2:&nbsp;&quot;Hi&nbsp;there!&quot;<br>}`).encode();<br><br>console.log(CBOR.toHex(cbor));<br>------------------------------<br>a201fb4046d9999999999a0269486920746865726521<br></div></div>
<h3 id='main.version'>10.&nbsp;&nbsp;Version</h3>

API version: 1.0.8. Note that the current API version is accessible through
the static property <code>CBOR.version</code>.<br>
Document version: 2024-09-25
Document version: 2024-09-27
</body>
</html>
2 changes: 1 addition & 1 deletion doc/style.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,7 @@ li {
.webpkibox, .webpkihexbox {
padding: 0.8em 1em;
font-family: "Noto Mono",monospace;
margin: 0 1em 1em 0;
margin: 1em;
}

.webpkisvg {
Expand Down

0 comments on commit a952b2e

Please sign in to comment.