From a952b2e992dd71a5489193d82e1d8d97eba7c2c7 Mon Sep 17 00:00:00 2001 From: Anders Rundgren Date: Fri, 27 Sep 2024 18:52:23 +0200 Subject: [PATCH] Added examples --- build/document-template.html | 7 ++- build/src/CreateDocument.java | 98 ++++++++++++++++++++++++++++++++++- doc/index.html | 25 +++++++-- doc/style.css | 2 +- 4 files changed, 125 insertions(+), 7 deletions(-) diff --git a/build/document-template.html b/build/document-template.html index a835001..956f79f 100644 --- a/build/document-template.html +++ b/build/document-template.html @@ -503,9 +503,14 @@

Table of Contents

Diagnostic Notation. + ${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 CBOR.version.
- Document version: 2024-09-25 + Document version: 2024-09-27 \ No newline at end of file diff --git a/build/src/CreateDocument.java b/build/src/CreateDocument.java index 4e9ca43..c7dc19d 100644 --- a/build/src/CreateDocument.java +++ b/build/src/CreateDocument.java @@ -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}"; @@ -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("
" + + htmlize(rawCode) + + "
"; + } + + String exampleEncode() { + return + """ + The following code shows how you can create 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 decode CBOR-encoded data, + here using the result of the encoding 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 decode CBOR specified in + Diagnostic Notation: + """ + + 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); } @@ -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(); diff --git a/doc/index.html b/doc/index.html index 63d2385..3f69666 100644 --- a/doc/index.html +++ b/doc/index.html @@ -140,7 +140,12 @@

Table of Contents

n/a7.  Diagnostic Notation
n/a8.  Deterministic Encoding
-
n/a9.  Version
+
n/a9.  Using the CBOR API
+
n/a9.1.  Encode CBOR
+
n/a9.2.  Decode CBOR
+
n/a9.3.  Using Diagnostic Notation
+
+
n/a10.  Version

1.  Introduction

@@ -1497,10 +1502,24 @@

8.  Deterministic Encoding

Diagnostic Notation. -

9.  Version

+

9.  Using the CBOR API

+ + This section provides a few examples on how to use the CBOR API. +
9.1.  Encode CBOR
+The following code shows how you can create CBOR-encoded data: +
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
+
9.2.  Decode CBOR
+The following code shows how you can decode CBOR-encoded data, +here using the result of the encoding example: +
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
+
9.3.  Using Diagnostic Notation
+The following code shows how you can decode CBOR specified in +Diagnostic Notation: +
let cbor = CBOR.diagDecode(`{
# Comments are also permitted
  1: 45.7,
  2: "Hi there!"
}`).encode();

console.log(CBOR.toHex(cbor));
------------------------------
a201fb4046d9999999999a0269486920746865726521
+

10.  Version

API version: 1.0.8. Note that the current API version is accessible through the static property CBOR.version.
- Document version: 2024-09-25 + Document version: 2024-09-27 \ No newline at end of file diff --git a/doc/style.css b/doc/style.css index 9498b1d..49022e4 100644 --- a/doc/style.css +++ b/doc/style.css @@ -191,7 +191,7 @@ li { .webpkibox, .webpkihexbox { padding: 0.8em 1em; font-family: "Noto Mono",monospace; - margin: 0 1em 1em 0; + margin: 1em; } .webpkisvg {