Functions

Adds an element to the end of the SVG document being created.

This function is only needed if you are using the lower-level Analemma SVG functions to draw custom SVG content. Call this function with the Clojure data structure returned by the SVG function and it will become part of the diagram.

It’s beyond the current scope of these instructions to try to explain Analemma, so you will need to study its own documentation and source if you want to engage in this kind of low-level drawing. But as a small example, you could draw a circle at coordinates (20, 10) with radius 5 by calling:

The analemma.svg functions available in bytefield-svg are all organized under the svg namespace alias, and include: svg/add-style, svg/animate, svg/animate-color, svg/animate-motion, svg/animate-transform, svg/circle, svg/defs, svg/draw, svg/ellipse, svg/group, svg/image, svg/line, svg/parse-inline-css, svg/path, svg/polygon, svg/rect, svg/rgb, svg/rotate, svg/style, svg/style-map, svg/svg, svg/text, svg/text-path, svg/transform, svg/translate, svg/translate-value, svg/tref, and svg/tspan.

You can also manipulate the hiccup-like structures returned by these functions using the even-lower level Analemma XML functions. These are organized under the xml namespace alias, and include: xml/add-attrs, xml/add-content, xml/emit, xml/emit-attrs, xml/emit-tag, xml/get-attrs, xml/get-content, xml/get-name, xml/has-attrs?, xml/has-content?, xml/merge-attrs, xml/set-attrs, xml/set-content, and xml/update-attrs.

If you understand the structures built and used by Analemma, you can also build them directly yourself and pass them to append-svg.

Get the UTF-16 code unit of a character.

This is equivalent to e.g. (int \H) in Clojure.

Example:

Register a attribute map for later use in your diagram.

To add a new named attribute or update one of the predefined attributes, pass the keyword you want to define as the first argument, and attribute expression that you want that keyword to represent as the second argument.

For example, if you want to have some of your byte boxes have a green background, you could make :bg-green a named attribute that achieves that by calling:

From then on, you can use :bg-green in any attribute expression to stand in for this fill color.

If you want to build on an existing predefined attribute, your attribute expression can combine attributes concisely. The vertical text example for draw-box takes advantage of this approach.

Close the bottom of a gap drawn by draw-gap.

none

This function isn’t needed if you are continuing to draw enough boxes after your gap to span an entire row, because the top borders of those boxes will draw the bottom of the gap. But if your diagram ends after the gap, or after a partial row after the gap, you will want to call (draw-bottom) to draw the line across the bottom of the gap.

This isn’t done automatically because some diagrams want the gap to extend into some of the boxes of the line after the gap, which can be achieved by setting those boxes to not have a top border, but that only works if the gap doesn’t close itself.

This is probably the most-used function in bytefield-svg. It draws the next cell in your byte field diagram.

If the previous box completed a row, drawing this new box will advance to the start of the next row, and draw the row header.

If you call draw-box with just a label, it will draw a box with a default set of attributes that contains that label. If you want to change the way the box is drawn, you can pass an attribute expression as the second argument (see below).

This is a shortcut for drawing multiple labels with the same attributes for each. It calls draw-box for each value in labels.

If you pass attr-spec it will be used when calling draw-box for each value in labels. See the draw-box documentation for details about how labels and attributes are used to control the drawing of each box.

Draws the row of byte offsets at the top of the diagram, making it easy to visually determine the addresses of boxes below. This is not done until you ask for it, to give you an opportunity to first adjust predefined values that will affect the result.

If you supply attr-spec, it is parsed as an attribute expression that you can use to further customize the column headers (in ways that don’t affect the structure of the rest of the diagram):

Draws an indication of discontinuity. Takes a full row (consuming the rest of the current row first, if there have been any boxes drawn in it). Also optionally labels the contents of the gap.

If label is provided, draws it to identify the content of the gap. If there are at least :min-label-columns (which defaults to 8, see the attributes below) remaining on the current row, will center the label in the remaining space on that row before drawing the gap. Otherwise it will advance to the next row, draw the label centered on the entire row, then draw the gap. label is passed to draw-box, so it is interpreted in the same way.

When finishing off the previous row, a box is drawn in the predefined box-above style. You can change that by passing different attributes under the :box-above-style key in your attribute expression (the optional second argument). For example, use {:box-above-style :box-above-related} if the gap relates to the preceding box.

Draws an indication of discontinuity for a single-row diagram. Takes the space of a single box in the row.

Adds a line to the SVG being built up. This is used extensively by the other functions here to draw the diagram, but you can use it yourself to draw your own custom content, either in your diagram itself, or as a part of a custom label function in draw-box.

The four required arguments are the coordinates of the endpoints of the line segment to be drawn. If those are the only arguments you supply, the line will be drawn with a :stroke-width of 1 and a :stroke of #000000 (black). But you can override those (and other SVG attributes) by passing an attribute expression as the fifth argument.

Draws enough related boxes to reach the specified memory address (useful if you know where the next chunk of useful information in the diagram occurs, and you don’t want to calculate how many boxes it will take to get there). The address is the value shown in the row header, plus the column header. It is either relative to the start of the diagram, or if a gap has been drawn, to the end of the most recent gap.

If no label is supplied, draws a zero byte in each box. If attr-spec is supplied, it is passed along to draw-related-boxes along with each copy of the label.

This is a shortcut for drawing multiple labels with the same basic attributes for each, which are a related group, so the internal borders between boxes inside the group are rendered differently than the borders with boxes outside the group (as illustrated in the example at the end of the draw-box discussion. It calls draw-box for each value in labels, merging any attributes you supply with appropriate border styles on whether this is the first, a middle, or the final box.

If you pass attr-spec it will be used when calling draw-box for each value in labels. See the draw-box documentation for details about how labels and attributes are used to control the drawing of each box, but keep in mind that the :borders attribute is controlled by this function so that borders between related cells are drawn with the line style specified by the :border-related predefined attribute, and borders with unrelated cells are drawn with the line style specified by :border-unrelated.

The default definitions of those line styles result in a solid line for borders with unrelated cells, and a light dashed line between related cells. You can change those defaults using defattrs to redefine :border-related and :border-unrelated.

Generates the label in the left margin which identifies the starting address of a row.

Defaults to a :font-size of 11 and :font-family of "Courier New, monospace" but these can be overridden, and other SVG text attributes) can be supplied, through an attribute expression in attr-spec.

In the most common case, label is a string and the SVG text object is constructed as described above. If you need to draw a more complex structure, you can pass in your own SVG text object (with potentially nested tspan objects), and it will simply be positioned.

This is the function that evaluates attribute expressions. It accepts the mini-language described in that section, and boils it down to a single map of attributes. It’s available for use in your own code so that helper functions you write are able to accept attribute expressions just like the built-in functions do.

Creates an SVG text object suitable for use as a box label representing a hexadecimal value. This is the function used internally when you pass a number as the label argument to draw-box.

If you just pass a number in n it is formatted as a two-digit hexadecimal value, using the text styles specified in the predefined attribute :hex. You can specify the number of digits by also passing length, and you can override or augment the SVG text attributes) by passing an attribute expression in attr-spec.

Calculates the memory address corresponding to the next box that will be drawn. (If a gap has been drawn, this will be relative to the end of the gap.)

Advances drawing to the next row of boxes.

The height of the row defaults to the predefined value :row-height but can be changed by passing height.

Converts a value to either true or false. All non-zero numbers become true, zero becomes false. Other values are tested for truthiness (in Clojurescript all values other than false and nil are truthy) and translated to true or false accordingly.

Returns a value which when passed as a label to draw-box will be drawn as either 0 or 1 in the hex style.

Takes a a number and transforms it into a sequence of boolean bit values of the specified length.

This can be used to explode a number into the corresponding bit field by passing the result to draw-boxes or draw-related-boxes.

Builds an SVG text object for drawing. This is used by hex-text and by draw-box when you pass it a string. If you need to do something more complicated with styling (including nested tspan objects with different styles), this function lets you.

If you just pass a single argument, it is rendered as a text string with the styles specified by the predefined attribute :plain. The optional second argument is an attribute expression you can use to pick your own SVG text attributes).

Any arguments after attr-spec are additional text content to be rendered, but if they are vectors they are given special treatment and rendered as a nested tspan object. The first element of the vector is parsed as an attribute expression for the styles to apply to that tspan, and the remaining elements are rendered as its content. (And even here you can embed new tspan objects with new styling by embedding more vectors.)

The first example shows a common pattern in my own diagrams: the main text is styled using the :math predefined attributes to look like an equation, and it is followed by a vector representing a nested tspan that uses the :sub predefined attributes to be positioned as a subscript.

The second example has a lot going on: The first text is rendered in the default style, which we have to make explicit by passing {} as the attribute expression so that we can move on to the nested content arguments (using nil would have worked as well).

That content has multiple values this time. The first is again a vector representing a nested tspan object, this time using an explicit attribute map to style its text as italics, and the second is just more text, so it gets styled the same way as the original text.

Following the end of the text function invocation, which makes up the label argument of the draw-box function, we have the attribute expression for the box itself. We use that to make it wide enough to hold the text we’re drawing.

Builds an SVG tspan object with attributes parsed as an attribute expression.

Any lists or vectors in the content will be recursively parsed as nested tspan objects with their own attribute expressions as the first element.

This is a macro that nests any drawing commands in its body inside an a element, turning the nested drawings into a hyperlink with the specified href.

If the form immediately following the href is a map, it is parsed as an attribute expression and establishes the attributes for the a element. (The most common use would be to have the link open in a new window by passing {:target "_blank"}).

The body can include any number of drawing function calls and other Clojure expressions. Notice that in the example below, the text and lines (including the separately-drawn bottom line of the gap) are hyperlinks, and the Clojure one opens in a new window.

This is a macro that nests any drawing commands in its body inside an arbitrary SVG element, which you specify as a vector containing a keyword that identifies the desired element and a map of its attributes and values.

The body can include any number of drawing function calls and other Clojure expressions. Here is how we could create the wrap-link example above using this lower-level approach, although wrap-link is more convenient: