Merge pull request #50 from simonarnell/main

Added examples to documentation

doc/antora.yml

@@ -8,7 +8,7 @@ asciidoc:
   attributes:
     icons: font
     experimental: ''
-    page-copyright: 2020–2023
+    page-copyright: 2020–2024
     page-pagination: ''
 nav:
 - modules/ROOT/nav.adoc

doc/modules/ROOT/examples/ccsds.edn

@@ -0,0 +1,23 @@
+(defattrs :vertical [:plain {:writing-mode "vertical-rl"}])
+
+(def row-height 60)
+(draw-column-headers)
+(draw-box "version" {:span 3})
+(draw-box (text "type" :vertical) {:span 1})
+(draw-box "dfh" {:span 1})
+(draw-box "apid" {:span 11})
+
+(draw-box "seq. flags" {:span 2 :next-row-height 30})
+(draw-box "sequence count" {:span 14})
+
+(draw-box "packet length" {:span 16})
+
+(draw-box "shf" {:span 1})
+(draw-box "pusvers" {:span 3})
+(draw-box "ack" {:span 4})
+(draw-box "service type" {:span 8})
+(draw-box "service subtype" {:span 8})
+
+(draw-gap)
+
+(draw-box "packet error control" {:span 16})

doc/modules/ROOT/examples/ethernet.edn

@@ -0,0 +1,9 @@
+(draw-column-headers)
+(draw-box "Destination MAC" {:span 6})
+(draw-box "Source MAC" {:span 6})
+(draw-box "(802.1Q tag)" {:span 4})
+
+(draw-box (text "Ethertype" {:font-size 16}) {:span 2})
+(draw-gap "Payload")
+(draw-bottom)
+(draw-box "FCS" {:span 4})

doc/modules/ROOT/examples/ipv4.edn

@@ -0,0 +1,20 @@
+(draw-column-headers)
+(draw-box "Version" {:span 4})
+(draw-box "IHL" {:span 4})
+(draw-box "DSCP" {:span 6})
+(draw-box "ECN" {:span 2})
+(draw-box "Total length" {:span 16})
+(draw-box "Identification" {:span 16})
+(draw-box "Flags" {:span 3})
+(draw-box "Fragment offset" {:span 13})
+(draw-box "Time to live" {:span 8})
+(draw-box "Protocol" {:span 8})
+(draw-box "Header checksum" {:span 16})
+(draw-box "Source IP address" [{:span 16}, :box-above])
+(draw-box nil [{:span 16}, :box-below])
+
+(draw-box "Destination IP address" [{:span 16}, :box-above])
+(draw-box nil [{:span 16}, :box-below])
+
+(draw-gap "Options (if IHL > 5)")
+(draw-bottom)

doc/modules/ROOT/examples/ipv6.edn

@@ -0,0 +1,21 @@
+(defattrs :vertical [:plain {:writing-mode "vertical-rl"}])
+(defattrs :box-middle {:borders #{:left :right}})
+(def column-labels (mapv #(number-as-hex % 2) (range 32)))
+
+(def boxes-per-row 32)
+
+(draw-column-headers)
+(draw-box "Version" {:span 4})
+(draw-box "Traffic class" {:span 8})
+(draw-box "Flow label" {:span 20})
+(draw-box "Payload length" {:span 16})
+(draw-box "Next header" {:span 8})
+(draw-box "Hop limit" {:span 8})
+(draw-box "Source address"  [{:span 32}, :box-above])
+(draw-box nil [{:span 32} :box-middle])
+(draw-box nil [{:span 32} :box-middle])
+(draw-box nil [{:span 32} :box-middle])
+(draw-box "Destination address"  [{:span 32}, :box-above])
+(draw-box nil [{:span 32} :box-middle])
+(draw-box nil [{:span 32} :box-middle])
+(draw-box nil [{:span 32} :box-below])

doc/modules/ROOT/examples/tcp.edn

@@ -0,0 +1,23 @@
+(def column-labels (mapv #(number-as-hex % 2) (range 32)))
+(def boxes-per-row 32)
+(defattrs :vertical [:plain {:writing-mode "vertical-rl"}])
+(draw-column-headers)
+(draw-box "Source port" {:span 16})
+(draw-box "Destination port" {:span 16})
+(draw-box "Sequence number" {:span 32})
+(draw-box "Acknowledgement number" {:span 32})
+(draw-box "Data offset" [{:span 4}, {:next-row-height 60}])
+(draw-box (text "0000" :hex [:plain " (Reserved)"]) {:span 4})
+(draw-box (text "CWR" :vertical))
+(draw-box (text "ECE" :vertical))
+(draw-box (text "URG" :vertical))
+(draw-box (text "ACK" :vertical))
+(draw-box (text "PSH" :vertical))
+(draw-box (text "RST" :vertical))
+(draw-box (text "SYN" :vertical))
+(draw-box (text "FIN" :vertical))
+(draw-box "Window size" {:span 16})
+(draw-box "Checksum" [{:span 16}, {:next-row-height 40}])
+(draw-box "Urgent pointer" {:span 16})
+(draw-gap "Options (size set in data offset)")
+(draw-bottom)

doc/modules/ROOT/examples/udp.edn

@@ -0,0 +1,7 @@
+(def column-labels (mapv #(number-as-hex % 2) (range 32)))   ;; creates column labels 0 .. 1f
+(def boxes-per-row 32)
+(draw-column-headers)
+(draw-box "Source port" {:span 16})
+(draw-box "Destination port" {:span 16})
+(draw-box "Length" {:span 16})
+(draw-box "Checksum" {:span 16})

doc/modules/ROOT/nav.adoc

@@ -2,3 +2,4 @@
 * xref:values.adoc[Predefined Values]
 * xref:attrs.adoc[Attributes]
 * xref:funcs.adoc[Functions]
+* xref:examples.adoc[Examples]

doc/modules/ROOT/pages/examples.adoc

@@ -0,0 +1,78 @@
+= Examples
+James Elliott <james@deepsymmetry.org>; Simon Arnell <simon[email protected]>
+
+The following are some examples of protocols contributed by the community.
+
+##  Mattias Holm (https://github.com/lorrden[@lorrden])
+
+### User Datagram Protocol header (https://www.ietf.org/rfc/rfc768.txt[RFC768])
+
+[bytefield]
+----
+include::example$udp.edn[]
+----
+
+[source, clojure]
+----
+include::example$udp.edn[]
+----
+
+### Transmission Control Protocol header (https://www.ietf.org/rfc/rfc793.txt[RFC793])
+
+[bytefield]
+----
+include::example$tcp.edn[]
+----
+
+[source, clojure]
+----
+include::example$tcp.edn[]
+----
+
+### Internet Protocol Version 4 header (https://www.ietf.org/rfc/rfc791.txt[RFC791])
+
+[bytefield]
+----
+include::example$ipv4.edn[]
+----
+
+[source, clojure]
+----
+include::example$ipv4.edn[]
+----
+
+### Internet Protocol Version 6 header (https://www.ietf.org/rfc/rfc2460.txt[RFC2460])
+
+[bytefield]
+----
+include::example$ipv6.edn[]
+----
+
+[source, clojure]
+----
+include::example$ipv6.edn[]
+----
+
+### Ethernet II frame (DIX v2.0)
+
+[bytefield]
+----
+include::example$ethernet.edn[]
+----
+
+[source, clojure]
+----
+include::example$ethernet.edn[]
+----
+
+### Consultative Committee for Space Data Systems Space Packet Standard - Packet Utilisation Standard A (https://ecss.nl/standard/ecss-e-70-41a-ground-systems-and-operations-telemetry-and-telecommand-packet-utilization/[ECSS-E-70-41A])
+
+[bytefield]
+----
+include::example$ccsds.edn[]
+----
+
+[source, clojure]
+----
+include::example$ccsds.edn[]
+----

src/org/deepsymmetry/bytefield/core.cljs

@@ -326,6 +326,13 @@
   [number length]
   (map #(normalize-bit (bit-test number %)) (reverse (range length))))
 
+(defn number-as-hex
+  "Takes a number and transforms it into a hexadecimal value of the specified
+  length."
+  [number length]
+  (let [fmt (str "~" length ",'0x")]
+  (pprint/cl-format nil fmt number)))
+
 (defn- center-baseline
   "Recursively ensures that the a tag and any content tags it contains
   have their dominant baseline set to center them vertically, so
@@ -793,6 +800,7 @@
                       next-row
                       normalize-bit
                       number-as-bits
+                      number-as-hex
                       text
                       tspan
                       wrap-link
@@ -885,7 +893,7 @@
     'bottom-margin 1  ; Space at bottom, currently just enough to avoid clipping bottom box edges.
     'box-width     40 ; How much room each byte (or bit) box takes up.
 
-    'column-labels (str/split "0,1,2,3,4,5,6,7,8,9,a,b,c,d,e,f" #",") ; The default column headers.
+    'column-labels (mapv #(number-as-hex % 1) (range 16)) ; The default column headers.
     'boxes-per-row 16 ; How many individual byte/bit boxes fit on each row.
     'row-height    30 ; The height of a standard row of boxes.
     'svg-attrs     {} ; Allows arbitrary customization of the top-level SVG node attributes.