The cl-pack Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-pack Reference Manual

This is the cl-pack Reference Manual, version 1.0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed Jun 15 03:56:27 2022 GMT+0.

Table of Contents


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.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-pack

Perl compatible binary pack() and unpack() library

Author

Dan Ballard <dan@mindstab.net>

License

BSD-3-Clause

Version

1.0.1

Dependency

ieee-floats (system).

Source

cl-pack.asd.

Child Components

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 cl-pack/cl-pack.asd

Source

cl-pack.asd.

Parent Component

cl-pack (system).

ASDF Systems

cl-pack.

Packages

cl-pack-system.


3.1.2 cl-pack/package.lisp

Source

cl-pack.asd.

Parent Component

cl-pack (system).

Packages

cl-pack.


Previous: , Up: Lisp   [Contents][Index]

3.1.3 cl-pack/cl-pack.lisp

Source

cl-pack.asd.

Parent Component

cl-pack (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 cl-pack

Source

package.lisp.

Use List
  • common-lisp.
  • ieee-floats.
Public Interface
Internals

Previous: , Up: Packages   [Contents][Index]

4.2 cl-pack-system

Source

cl-pack.asd.

Use List
  • asdf/interface.
  • common-lisp.

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Ordinary functions

Function: pack (form &rest rest)
Package

cl-pack.

Source

cl-pack.lisp.

Function: unpack (form string &key consumed modifiers)
Package

cl-pack.

Source

cl-pack.lisp.


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Macros

Macro: cut-str (str len new-str)
Package

cl-pack.

Source

cl-pack.lisp.

Macro: def-form-parser (fn-name (&rest extra-args) end-test final-item &rest body)
Package

cl-pack.

Source

cl-pack.lisp.

Macro: gen-modifiers-list ()
Package

cl-pack.

Source

cl-pack.lisp.

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.

Macro: inc-form ()

create a subseq of form that skips the current syntax object

Package

cl-pack.

Source

cl-pack.lisp.

Macro: pack-int (size endian)

Macro to define the pack function for an int

Package

cl-pack.

Source

cl-pack.lisp.

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.

Macro: set-modifiers (modifiers)
Package

cl-pack.

Source

cl-pack.lisp.

Macro: unpack-int (size endian)

Macro to define the unpack function for a signed int

Package

cl-pack.

Source

cl-pack.lisp.

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.

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.

Macro: unpack-uint (size endian)

Macro to define the unpack function for an unsigned int

Package

cl-pack.

Source

cl-pack.lisp.


Previous: , Up: Internals   [Contents][Index]

5.2.2 Ordinary 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.

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.

Function: ber-decode (string)

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

Package

cl-pack.

Source

cl-pack.lisp.

Function: ber-encode (number)

function to encode a BER number into a binary byte string

Package

cl-pack.

Source

cl-pack.lisp.

Function: ber-str-length (string)
Package

cl-pack.

Source

cl-pack.lisp.

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.

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.

Function: byte-to-2hex (byte)

Turn a byte into a string of 2 hex characters

Package

cl-pack.

Source

cl-pack.lisp.

Function: byte-to-2hex-rev (byte)
Package

cl-pack.

Source

cl-pack.lisp.

Function: byte-to-8bits (byte)

turns a byte into a string of bits

Package

cl-pack.

Source

cl-pack.lisp.

Function: byte-to-8bits-rev (byte)

convert a byte to a bit string, lowest bit first

Package

cl-pack.

Source

cl-pack.lisp.

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.

Function: bytes-to-string (bytes length)

puts length bytes from bytes into a string

Package

cl-pack.

Source

cl-pack.lisp.

Function: bytes-to-string-rev (bytes length)

puts length bytes from bytes into a reversed string

Package

cl-pack.

Source

cl-pack.lisp.

Function: endian-type-to-func (endian)
Package

cl-pack.

Source

cl-pack.lisp.

Function: find-matching-paren (str)
Package

cl-pack.

Source

cl-pack.lisp.

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.

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.

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.

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.

Function: strhead (str)

returns a char that is the first char of str

Package

cl-pack.

Source

cl-pack.lisp.

Function: string-to-bytes (string length)
Package

cl-pack.

Source

cl-pack.lisp.

Function: string-to-bytes-rev (string length)
Package

cl-pack.

Source

cl-pack.lisp.

Function: strtail (str)

returns the rest of str

Package

cl-pack.

Source

cl-pack.lisp.

Function: twos-complement (number max-size)
Package

cl-pack.

Source

cl-pack.lisp.

Function: un-endian-type-to-func (endian)
Package

cl-pack.

Source

cl-pack.lisp.

Function: un-twos-complement (number max-size)
Package

cl-pack.

Source

cl-pack.lisp.

Function: unpack-bytes (string length)

takes length bytes from string and returns an int

Package

cl-pack.

Source

cl-pack.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   2   8  
B   C   D   E   F   G   H   I   M   N   P   S   T   U  
Index Entry  Section

2
2hex-to-byte: Private ordinary functions

8
8bits-to-byte: Private ordinary functions

B
ber-decode: Private ordinary functions
ber-encode: Private ordinary functions
ber-str-length: Private ordinary functions
bit-pack: Private ordinary functions
bit-unpack: Private ordinary functions
byte-to-2hex: Private ordinary functions
byte-to-2hex-rev: Private ordinary functions
byte-to-8bits: Private ordinary functions
byte-to-8bits-rev: Private ordinary functions
bytes-to-list: Private ordinary functions
bytes-to-string: Private ordinary functions
bytes-to-string-rev: Private ordinary functions

C
cut-str: Private macros

D
def-form-parser: Private macros

E
endian-type-to-func: Private ordinary functions

F
find-matching-paren: Private ordinary functions
Function, 2hex-to-byte: Private ordinary functions
Function, 8bits-to-byte: Private ordinary functions
Function, ber-decode: Private ordinary functions
Function, ber-encode: Private ordinary functions
Function, ber-str-length: Private ordinary functions
Function, bit-pack: Private ordinary functions
Function, bit-unpack: Private ordinary functions
Function, byte-to-2hex: Private ordinary functions
Function, byte-to-2hex-rev: Private ordinary functions
Function, byte-to-8bits: Private ordinary functions
Function, byte-to-8bits-rev: Private ordinary functions
Function, bytes-to-list: Private ordinary functions
Function, bytes-to-string: Private ordinary functions
Function, bytes-to-string-rev: Private ordinary functions
Function, endian-type-to-func: Private ordinary functions
Function, find-matching-paren: Private ordinary functions
Function, hex-pack: Private ordinary functions
Function, hex-to-number: Private ordinary functions
Function, hex-unpack: Private ordinary functions
Function, next-char: Private ordinary functions
Function, pack: Public ordinary functions
Function, strhead: Private ordinary functions
Function, string-to-bytes: Private ordinary functions
Function, string-to-bytes-rev: Private ordinary functions
Function, strtail: Private ordinary functions
Function, twos-complement: Private ordinary functions
Function, un-endian-type-to-func: Private ordinary functions
Function, un-twos-complement: Private ordinary functions
Function, unpack: Public ordinary functions
Function, unpack-bytes: Private ordinary functions

G
gen-modifiers-list: Private macros

H
handle-string: Private macros
hex-pack: Private ordinary functions
hex-to-number: Private ordinary functions
hex-unpack: Private ordinary functions

I
inc-form: Private macros

M
Macro, cut-str: Private macros
Macro, def-form-parser: Private macros
Macro, gen-modifiers-list: Private macros
Macro, handle-string: Private macros
Macro, inc-form: Private macros
Macro, pack-int: Private macros
Macro, pack-string: Private macros
Macro, set-modifiers: Private macros
Macro, unpack-int: Private macros
Macro, unpack-mod!-uint: Private macros
Macro, unpack-string: Private macros
Macro, unpack-uint: Private macros

N
next-char: Private ordinary functions

P
pack: Public ordinary functions
pack-int: Private macros
pack-string: Private macros

S
set-modifiers: Private macros
strhead: Private ordinary functions
string-to-bytes: Private ordinary functions
string-to-bytes-rev: Private ordinary functions
strtail: Private ordinary functions

T
twos-complement: Private ordinary functions

U
un-endian-type-to-func: Private ordinary functions
un-twos-complement: Private ordinary functions
unpack: Public ordinary functions
unpack-bytes: Private ordinary functions
unpack-int: Private macros
unpack-mod!-uint: Private macros
unpack-string: Private macros
unpack-uint: Private macros

Jump to:   2   8  
B   C   D   E   F   G   H   I   M   N   P   S   T   U  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables