The cl-pack Reference Manual

Table of Contents

The cl-pack Reference Manual

This is the cl-pack Reference Manual, version 1.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Thu Mar 11 12:24:38 2021 GMT+0.

1 Introduction

cl-pack

www.cliki.net/cl-pack

cl-pack supplies Perl/PHP/Ruby/Python compatible pack() and unpack() functions to allow easy use of (binary format) protocols and files with the above mentioned languages and C. cl-pack was released by Dan Ballard dan@mindstab.net under the BSD-3-Clause license.

The purpose of cl-pack is to take native Lisp data like numbers, floats, and strings and encode it in a safe binary format in string that can then be written to a file or exchanged with another program while unpack can extract data from binary formats and protocols.

cl-pack has nearly full support for all features offered by Perl's pack. It boasts full support for most data types and formating rules from numbers and string to formating rules and grouping and templates. cl-pack also supports endian safe floats as outlined by ruby. cl-pack is supports ASDF so as to make it easy to integrate into your existing system.

Instalation

cl-pack is available in QuickLisp

CL-USER> (ql:quickload "cl-pack")

Example:

CL-PACK> (pack "VgA*c*" #x41424344 161.99 " a string " 69 70 71)
;; => "DCBAC!ýq a string EFG"

CL-PACK> (unpack "B8H2Ng" "ABCDEFC!ýq")
;; => "01000001"
;; => "42"
;; => 1128547654
;; => 161.99

Documentation is currently a bit sparse, but is contained in cl-pack.lisp. Additionally, a good overview of pack and unpack functions can be seen at http://perldoc.perl.org/functions/pack.html.

Nearly every feature except a few esoteric ones are supported, check the documentation inside cl-pack.lisp if in doubt and if a feature you need isn't currently supported feel free to contact me and I'll see if I can add it.

Note I think the this release is about as feature complete as I feel I need to get at the moment so I'm pushing it out.

Cavets cl-pack was developed on an x86 running Ubuntu with SBCL. It should be endian safe where required and conform to host CPU endianness where required but I haven't been able to test on anything but x86. I would hope that it would work with most Lisps out there. Please feel free to get a hold of me if you have issues that need fixing

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-pack

Author

Dan Ballard <dan@mindstab.net>

License

BSD-3-Clause

Description

Perl compatible binary pack() and unpack() library

Version

1.0.1

Dependency

ieee-floats

Source

cl-pack.asd (file)

Components

• package.lisp (file)
• cl-pack.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-pack.asd

Location

cl-pack.asd

Systems

cl-pack (system)

Packages

cl-pack-system

3.1.2 cl-pack/package.lisp

Parent

cl-pack (system)

Location

package.lisp

Packages

cl-pack

3.1.3 cl-pack/cl-pack.lisp

Parent

cl-pack (system)

Location

cl-pack.lisp

Exported Definitions

• pack (function)
• unpack (function)

Internal Definitions

• 2hex-to-byte (function)
• 8bits-to-byte (function)
• ber-decode (function)
• ber-encode (function)
• ber-str-length (function)
• bit-pack (function)
• bit-unpack (function)
• byte-to-2hex (function)
• byte-to-2hex-rev (function)
• byte-to-8bits (function)
• byte-to-8bits-rev (function)
• bytes-to-list (function)
• bytes-to-string (function)
• bytes-to-string-rev (function)
• cut-str (macro)
• def-form-parser (macro)
• endian-type-to-func (function)
• find-matching-paren (function)
• gen-modifiers-list (macro)
• handle-string (macro)
• hex-pack (function)
• hex-to-number (function)
• hex-unpack (function)
• inc-form (macro)
• next-char (function)
• pack-int (macro)
• pack-string (macro)
• set-modifiers (macro)
• strhead (function)
• string-to-bytes (function)
• string-to-bytes-rev (function)
• strtail (function)
• twos-complement (function)
• un-endian-type-to-func (function)
• un-twos-complement (function)
• unpack-bytes (function)
• unpack-int (macro)
• unpack-mod!-uint (macro)
• unpack-string (macro)
• unpack-uint (macro)

4 Packages

Packages are listed by definition order.

4.1 cl-pack-system

Source

cl-pack.asd

Use List

• common-lisp
• asdf/interface

4.2 cl-pack

Source

package.lisp (file)

Use List

• ieee-floats
• common-lisp

Exported Definitions

• pack (function)
• unpack (function)

Internal Definitions

• 2hex-to-byte (function)
• 8bits-to-byte (function)
• ber-decode (function)
• ber-encode (function)
• ber-str-length (function)
• bit-pack (function)
• bit-unpack (function)
• byte-to-2hex (function)
• byte-to-2hex-rev (function)
• byte-to-8bits (function)
• byte-to-8bits-rev (function)
• bytes-to-list (function)
• bytes-to-string (function)
• bytes-to-string-rev (function)
• cut-str (macro)
• def-form-parser (macro)
• endian-type-to-func (function)
• find-matching-paren (function)
• gen-modifiers-list (macro)
• handle-string (macro)
• hex-pack (function)
• hex-to-number (function)
• hex-unpack (function)
• inc-form (macro)
• next-char (function)
• pack-int (macro)
• pack-string (macro)
• set-modifiers (macro)
• strhead (function)
• string-to-bytes (function)
• string-to-bytes-rev (function)
• strtail (function)
• twos-complement (function)
• un-endian-type-to-func (function)
• un-twos-complement (function)
• unpack-bytes (function)
• unpack-int (macro)
• unpack-mod!-uint (macro)
• unpack-string (macro)
• unpack-uint (macro)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Functions

Function: pack FORM &rest REST

Package

cl-pack

Source

cl-pack.lisp (file)

Function: unpack FORM STRING &key CONSUMED MODIFIERS

Package

cl-pack

Source

cl-pack.lisp (file)

5.2 Internal definitions

5.2.1 Macros

Macro: cut-str STR LEN NEW-STR

Package

cl-pack

Source

cl-pack.lisp (file)

Macro: def-form-parser FN-NAME (&rest EXTRA-ARGS) END-TEST FINAL-ITEM &rest BODY

Package

cl-pack

Source

cl-pack.lisp (file)

Macro: gen-modifiers-list ()

Package

cl-pack

Source

cl-pack.lisp (file)

Macro: handle-string (REPEATER REPEATER-STAR) STAR-BODY COUNT-BODY ELSE-BODY

macro for building string type bodies for case statements in pack() or unpack()

Package

cl-pack

Source

cl-pack.lisp (file)

Macro: inc-form ()

create a subseq of form that skips the current syntax object

Package

cl-pack

Source

cl-pack.lisp (file)

Macro: pack-int SIZE ENDIAN

Macro to define the pack function for an int

Package

cl-pack

Source

cl-pack.lisp (file)

Macro: pack-string (REPEATER REPEATER-STAR) STAR-BODY COUNT-BODY ELSE-BODY

macro for building string type bodies for case statements in pack()

Package

cl-pack

Source

cl-pack.lisp (file)

Macro: set-modifiers MODIFIERS

Package

cl-pack

Source

cl-pack.lisp (file)

Macro: unpack-int SIZE ENDIAN

Macro to define the unpack function for a signed int

Package

cl-pack

Source

cl-pack.lisp (file)

Macro: unpack-mod!-uint SIZE ENDIAN

macro to define a normal uint that with the ! modifier is a signed int

Package

cl-pack

Source

cl-pack.lisp (file)

Macro: unpack-string (REPEATER REPEATER-STAR) STAR-BODY COUNT-BODY ELSE-BODY

macro for building string type bodies for case statements in unpack()

Package

cl-pack

Source

cl-pack.lisp (file)

Macro: unpack-uint SIZE ENDIAN

Macro to define the unpack function for an unsigned int

Package

cl-pack

Source

cl-pack.lisp (file)

5.2.2 Functions

Function: 2hex-to-byte 2HEX &optional MAPPER

Turn a 2 hex digit string into a number unpacked by mapper

Package

cl-pack

Source

cl-pack.lisp (file)

Function: 8bits-to-byte 8BITS &optional BYTE-FORM

turns a string of 8 or less bits into a byte
byte-form specifies the packing order of bits into the byte, deaulting to decending order

Package

cl-pack

Source

cl-pack.lisp (file)

Function: ber-decode STRING

Take a BER number as a binary string and returns a number

Package

cl-pack

Source

cl-pack.lisp (file)

Function: ber-encode NUMBER

function to encode a BER number into a binary byte string

Package

cl-pack

Source

cl-pack.lisp (file)

Function: ber-str-length STRING

Package

cl-pack

Source

cl-pack.lisp (file)

Function: bit-pack BIT-STR &optional BYTE-FORM

pack a bit string into a byte string, decending order by default

Package

cl-pack

Source

cl-pack.lisp (file)

Function: bit-unpack BYTE-STR &optional UNPACK-FN

turn a string of bytes into an extended string of bits unpacked by unpack-fn

Package

cl-pack

Source

cl-pack.lisp (file)

Function: byte-to-2hex BYTE

Turn a byte into a string of 2 hex characters

Package

cl-pack

Source

cl-pack.lisp (file)

Function: byte-to-2hex-rev BYTE

Package

cl-pack

Source

cl-pack.lisp (file)

Function: byte-to-8bits BYTE

turns a byte into a string of bits

Package

cl-pack

Source

cl-pack.lisp (file)

Function: byte-to-8bits-rev BYTE

convert a byte to a bit string, lowest bit first

Package

cl-pack

Source

cl-pack.lisp (file)

Function: bytes-to-list BYTES LENGTH

bytes: Some binary data in lisp number form that ldb can access bytes-to-list pulls out 8bit bytes from bytes and turns them into their corresponding characters and returns the list of them

Package

cl-pack

Source

cl-pack.lisp (file)

Function: bytes-to-string BYTES LENGTH

puts length bytes from bytes into a string

Package

cl-pack

Source

cl-pack.lisp (file)

Function: bytes-to-string-rev BYTES LENGTH

puts length bytes from bytes into a reversed string

Package

cl-pack

Source

cl-pack.lisp (file)

Function: endian-type-to-func ENDIAN

Package

cl-pack

Source

cl-pack.lisp (file)

Function: find-matching-paren STR

Package

cl-pack

Source

cl-pack.lisp (file)

Function: hex-pack HEX-STR &optional MAPPER

turn a string of hex digits into a string of packed bytes, unpacking 2 hex digits at a time by mapper

Package

cl-pack

Source

cl-pack.lisp (file)

Function: hex-to-number HEX

turn a character of 0-9 or a-f or A-F into a hex digit of 0-15

Package

cl-pack

Source

cl-pack.lisp (file)

Function: hex-unpack BYTE-STR &optional HEX-UNPACK-FN

Turn a string of bytes into a string of hex digits

Package

cl-pack

Source

cl-pack.lisp (file)

Function: next-char FORM OFFSET

Get the next char from a string of null if offset is past end of string

Package

cl-pack

Source

cl-pack.lisp (file)

Function: strhead STR

returns a char that is the first char of str

Package

cl-pack

Source

cl-pack.lisp (file)

Function: string-to-bytes STRING LENGTH

Package

cl-pack

Source

cl-pack.lisp (file)

Function: string-to-bytes-rev STRING LENGTH

Package

cl-pack

Source

cl-pack.lisp (file)

Function: strtail STR

returns the rest of str

Package

cl-pack

Source

cl-pack.lisp (file)

Function: twos-complement NUMBER MAX-SIZE

Package

cl-pack

Source

cl-pack.lisp (file)

Function: un-endian-type-to-func ENDIAN

Package

cl-pack

Source

cl-pack.lisp (file)

Function: un-twos-complement NUMBER MAX-SIZE

Package

cl-pack

Source

cl-pack.lisp (file)

Function: unpack-bytes STRING LENGTH

takes length bytes from string and returns an int

Package

cl-pack

Source

cl-pack.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types