Two assignment operators. Plain = grows the target's capacity as needed; := is capacity-bounded — it never grows, fills up to the declared capacity, and sets Overflow to 1 on truncation. With = a shorter source replaces the full value (new length = source length); with := the existing tail beyond the source is preserved.
Use = for general assignment; use := for fixed-size fields (e.g. a string member of a packed struct) where the buffer must not reallocate. See Language basics → Assignment for the full table and a worked example.
Written from a line-by-line source review; every example output is from a real run.
Introduction
The blob plugin provides a few convenience helpers for working with binary data (blobs): it turns text into a blob, builds a human-readable hexdump of a blob for inspection, and forms a non-copying (zero-copy) blob reference from a raw memory address. The plugin itself holds no state: every call is standalone and stateless.
What is a blob?
A blob is the language's raw byte-sequence type: it stores arbitrary binary data, including 0 bytes (unlike a string, which ends at the first 0 byte). A local blob must be declared with a size — blob $B[64]; — its length is given by .Length, and you access individual bytes with $B[i] indexing. The blob plugin makes working with this type easier.
Loading the plugin
Mind the load path: blob.FromText and the other functions described here are in the blob PLUGIN (../plugins/blob/BlobPlugin), NOT in the builtin:blob module. The latter provides the language's built-in blob operations; the two are not the same.
plugin "../plugins/print/PrintPlugin"; plugin "../plugins/blob/BlobPlugin";
A typical flow
blob $B[64];
$B = blob.FromText("Hello, blob!");
printf("%d bytes\n", $B.Length);
printf("%s", blob.ToDump($B));What to know about every function (the basics)
Every call is stateless and standalone: no open/close, no handle. The functions are thread-safe.
FromText copies the whole text into the blob (its length is strlen, i.e. up to the first 0 byte); a NULL text is treated as an empty text.
The output of ToDump / ToDumpWidth is for INSPECTION (a human-readable hexdump), not for data interchange. For round-trippable encoding, crypto.ToHexBlob / FromHexBlob are the right choice.
The hexdump layout follows the classic `hexdump -C` / `xxd` format: an 8-digit offset, uppercase hex bytes (with an extra gap at the half-width point), then the ASCII rendering between | marks.
The width of ToDumpWidth must be between 1 and 256; outside that it raises a runtime error.
RefFromPointer is an unsafe, low-level primitive (see the function's description); most scripts never need it.
How to read the signatures
The type after the -> arrow is the return type. For example, blob.ToDumpWidth(data, width) -> string takes a blob and an integer width and returns a string (the hexdump).
Creation
Producing a blob from text, or from a raw memory address.
blob.FromText
blob.FromText(text) -> blob
Creates a new blob whose contents are the bytes of the given text. This is the usual way to turn a string into a blob.
| Parameter | Type | Description |
|---|---|---|
| text | string | The text to turn into a blob. The whole text is copied; NULL behaves as an empty text. |
A new blob with the text's bytes. Its length is the length of the text (up to the first 0 byte).
blob $B[64];
$B = blob.FromText("Hello, blob!");
printf("%d\n", $B.Length);12
When you must pass a text to a function that expects a blob (such as hash or network operations), or you want to inspect a text's contents at the byte level with ToDump.
blob.RefFromPointer
blob.RefFromPointer(pointer, size) -> blob
Forms a non-copying (zero-copy) blob reference to an existing memory area. The returned blob does NOT own the data: when it is freed, only the wrapper is freed, the referenced bytes stay untouched.
| Parameter | Type | Description |
|---|---|---|
| pointer | int | The raw address of the memory area as an integer. |
| size | int | The size of the area in bytes (cannot be negative; if non-zero, the pointer cannot be 0 either). |
A non-owning blob pointing at the given memory. A negative size, or a null pointer with a non-zero size, causes a runtime error.
// A low-level, unsafe primitive. // Typically used by plugin authors who export a raw // pointer+size pair (e.g. a video frame buffer) so the // script can access the bytes without a copy. // Ordinary script code almost never needs it.
(no runtime output — see the description)
Only when you received a raw pointer+size pair from a plugin and want to access the bytes without a copy. IMPORTANT: you are responsible for ensuring the referenced area outlives the blob pointing at it — otherwise you cause a use-after-free. If you are not sure you need this, use FromText or copy the data instead.
Inspection
Building a human-readable hexdump of a blob for debugging.
blob.ToDump
blob.ToDump(data) -> string
Builds a human-readable hexdump of the blob in the classic `hexdump -C` / `xxd` layout, with 16 bytes per row.
| Parameter | Type | Description |
|---|---|---|
| data | blob | The binary data to display. |
The hexdump as a string: per row an 8-digit offset, the bytes in uppercase hex (with an extra gap at the half-width point), then the ASCII rendering between | marks.
blob $B[64];
$B = blob.FromText("Hello, blob!");
printf("%s", blob.ToDump($B));00000000 48 65 6C 6C 6F 2C 20 62 6C 6F 62 21 |Hello, blob! |
For a quick, eyeball inspection of binary data (file contents, a network packet, a hash) while debugging. For inspection only — for machine data interchange or round-trip encoding use crypto.ToHexBlob / FromHexBlob.
blob.ToDumpWidth
blob.ToDumpWidth(data, width) -> string
Like ToDump, but you choose the number of bytes per row.
| Parameter | Type | Description |
|---|---|---|
| data | blob | The binary data to display. |
| width | int | The number of bytes per row (between 1 and 256). |
The hexdump as a string, with the given row width. A width outside the range causes a runtime error.
blob $B[64];
$B = blob.FromText("Hello, blob!");
printf("%s", blob.ToDumpWidth($B, 8));00000000 48 65 6C 6C 6F 2C 20 62 |Hello, b| 00000008 6C 6F 62 21 |lob! |
When 16 bytes per row is not ideal — for example for narrower output (8 bytes), or to align the rows to a particular record size for easier reading.
Practical notes
What the blob plugin is good for
Turning text into a blob so you can pass it to functions that expect a blob (hash, network, file).
Eyeball inspection of binary data: the hexdump immediately shows the bytes and the ASCII content.
Customizing the row width in the hexdump when 16 bytes per row does not match the data's structure.
A special, low-level case: wrapping a raw pointer+size pair into a blob, without a copy (RefFromPointer).
Inspection vs interchange
The output of ToDump / ToDumpWidth is meant for humans and is NOT suitable for data interchange or reading back: it contains the offsets, the gaps, and the ASCII column. If you want to store or transmit a blob in text form and then convert it back exactly, use the pair crypto.ToHexBlob (blob → hex string) and crypto.FromHexBlob (hex string → blob).
Safety — RefFromPointer
RefFromPointer wraps a raw memory address into a blob without a copy, and does not own the data. This is fast but dangerous: if the referenced area is freed or becomes invalid while the blob still points at it, a use-after-free occurs. Use it only when you know exactly how long the referenced memory lives; otherwise FromText gives a safe copy.
Error handling
A wrong argument count or type, an out-of-range hexdump width (1..256), an invalid pointer/size pair for RefFromPointer, and out of memory are reported by the runtime as a runtime error, and the script stops. FromText and the hexdump functions always give a deterministic result for a valid input; they have no “neutral-return” error state, so it is worth ensuring the validity of the input beforehand.
The json plugin
Parsing, navigating, and building JSON — complete function reference