update readme, remove ieee-floats dependancy

This commit is contained in:
mhsjlw 2016-05-20 06:38:34 -04:00
parent d38b98aa5e
commit 3a255096b7
9 changed files with 22 additions and 448 deletions

24
CHANGES
View File

@ -1,24 +0,0 @@
0.2 2009-08-12
- added support for signed numbers that mirrors perl's
- fixed native endian selection bug
- added w (BER: Binary Encoded Representation)
- added X (backup) in pack
- added support for <> modifiers
on native endian directives (sSiIlLqQdf)
they can be forced to big or small endian with < > modifiers
- added support for ! modifier
on nNvV it turns them to signed integers
- added . and @ support to pack
- added full group support to pack and unpack
- fixed string types to accept numbers and cast them to strings on the fly (ala perl)
- added / template to pack and unpack
- added more test cases to cover all the new additions and bug fixes
- Setup a git repository at git.mindstab.net/git/cl-pack
0.1.1 2009-07-04
simple speed increase and code reduction improvements suggested by Zach
0.1 2009-06-16
initial release
Basic packing/unpacking for most data types (numbers, strings,
floats) and repeater syntax supported.

7
README
View File

@ -1,7 +0,0 @@
CL-PACK
Dan Ballard <http://mindstab.net>
August 2009
CL-PACK supplier perl/php/ruby compatible pack() and unpack() functions to allow easy use of binary protocols with the above mentioned languages and C.
Documentation inside cl-pack.lisp

View File

@ -1,30 +1,29 @@
# cl-pack #
August 2009
cl-pack
=======
[www.cliki.net/cl-pack](http://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 under the BSD license.
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 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.
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.
## 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
;; => "DCBAC!ýq a string EFG"
**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](http://perldoc.perl.org/functions/pack.html).
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](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 0.2 release is about as feature complete as I feel I need to get at the moment so I'm pushing it out. If there are not major complaints, then in a bit it will be rereleased as 1.0, and if there are complaints, well more code and another pre 1.0 release :)
**Note** I think the 0.2 release is about as feature complete as I feel I need to get at the moment so I'm pushing it out. If there are not major complaints, then in a bit it will be re-released as 1.0, and if there are complaints, well more code and another pre-1.0 release :smile:
**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 ahold of me if you have issues that need fixing.
**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.

View File

@ -1,7 +1,7 @@
;;;; -*- Mode: Lisp; Syntax: ANSI-Common-Lisp; Base: 10 -*-
;;;; ******************************************************
;;;; FILE IDENTIFICATION
;;;;
;;;;
;;;; Name: cl-pack.asd
;;;; Purpose: System definition for CL-PACK
;;;; Author: Dan Ballard <http://mindstab.net>
@ -17,36 +17,18 @@
(defpackage #:cl-pack-system (:use #:asdf #:cl))
(in-package #:cl-pack-system)
; Try to find ieee-floats in the system,
; otherwise we'll load the copy we ship with
;(eval-when (:compile-toplevel :load-toplevel :execute)
(handler-case
(unless (find-package 'ieee-floats)
(progn
(asdf:operate 'asdf:load-op 'ieee-floats)
(push :native-ieee-floats *features*)))
(MISSING-COMPONENT (e) nil))
(defsystem #:cl-pack
:name "cl-pack"
:author "Dan Ballard <haplo@mindstab.net>"
:version "0.1"
:licence "BSD"
:description "perl compatible binary pack() and unpack() library"
:depends-on #+native-ieee-floats(:ieee-floats)
#-native-ieee-floats()
:components (#-native-ieee-floats
(:module ieee-floats
:components ((:file "ieee-floats")))
(:file "package"
:depends-on (ieee-floats))
(:file "cl-pack"
:depends-on ("package" ieee-floats))))
:licence "BSD-3-Clause"
:description "Perl compatible binary pack() and unpack() library"
:depends-on (:ieee-floats)
:components ((:file "package")
(:file "cl-pack")))
(defsystem #:cl-pack-test
:depends-on (:cl-pack)
:components ((:file "tests")))

View File

@ -1,90 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>IEEE Floats</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
</head>
<body>
<div class="header">
<h1>IEEE Floats</h1>
</div>
<p>IEEE-Floats provides a way of converting values of type
<tt>float</tt> and <tt>double-float</tt> to and from their binary
representation as defined by IEEE 754 (which is commonly used by
processors and network protocols).</p>
<p>The library defines encoding and decoding functions for the common
32-bit and 64-bit formats, and a macro for defining similar functions
for other formats. The default functions do not detect the special
cases for NaN or infinity, but functions can be generated which do, in
which case the keywords <tt>:not-a-number</tt>,
<tt>:positive-infinity</tt>, and <tt>:negative-infinity</tt> are used
to represent them.</p>
<h2>Download and installation</h2>
<p>IEEE-Floats is released under a BSD-style license. The latest
release can be downloaded from <a
href="http://common-lisp.net/project/ieee-floats/ieee-floats.tgz">http://common-lisp.net/project/ieee-floats/ieee-floats.tgz</a>,
or installed with <a
href="http://www.cliki.net/ASDF-Install">asdf-install</a>.</p>
<p>A <a href="http://www.darcs.net/">darcs</a> repository with the most recent changes can be checked out with:</p>
<pre>&gt; darcs get http://common-lisp.net/project/ieee-floats/darcs/ieee-floats</pre>
<p>Or look at it <a
href="http://common-lisp.net/cgi-bin/darcsweb/darcsweb.cgi?r=ieee-floats-ieee-floats;a=summary">online</a>.</p>
<h2>Support and mailing lists</h2>
<p>The <a
href="http://common-lisp.net/mailman/listinfo/ieee-floats-devel">ieee-floats-devel</a>
mailing list can be used for any questions, discussion, bug-reports,
patches, or anything else relating to this library. You can also e-mail the author/maintainer, <a href="mailto:marijnh@gmail.com">Marijn Haverbeke</a>, directly.</p>
<h2>Reference</h2>
<p class="def">function <tt>encode-float32</tt> (float) => integer</p>
<p class="desc">Convert a float into its 32-bit binary
representation.</p>
<p class="def">function <tt>decode-float32</tt> (integer) => float</p>
<p class="desc">Create a float from a 32-bit binary representation.</p>
<p class="def">function <tt>encode-float64</tt> (float) => integer</p>
<p class="desc">Convert a float into its 64-bit binary
representation.</p>
<p class="def">function <tt>decode-float64</tt> (integer) => double-float</p>
<p class="desc">Create a float from a 64-bit binary representation.</p>
<p class="def">macro <tt>make-float-converters</tt> (encoder-name decoder-name exponent-bits significand-bits support-nan-and-infinity-p)</p>
<p class="desc">Writes an encoder and decoder function for floating
point numbers with the given amount of exponent and significand bits
(plus an extra sign bit). If support-nan-and-infinity-p is true, the
decoders will also understand these special cases. NaN is represented
as :not-a-number, and the infinities as :positive-infinity and
:negative-infinity. Note that this means that the in- or output of
these functions is not just floating point numbers anymore, but also
keywords.</p>
<hr/>
<p>Back to <a href="http://common-lisp.net/">Common-lisp.net</a>.</p>
<div class="check">
<a href="http://validator.w3.org/check/referer">Valid XHTML 1.0 Strict</a>
</div>
</body>
</html>

View File

@ -1,72 +0,0 @@
.header {
font-size: medium;
background-color:#336699;
color:#ffffff;
border-style:solid;
border-width: 5px;
border-color:#002244;
padding: 1mm 1mm 1mm 5mm;
}
.footer {
font-size: small;
font-style: italic;
text-align: right;
background-color:#336699;
color:#ffffff;
border-style:solid;
border-width: 2px;
border-color:#002244;
padding: 1mm 1mm 1mm 1mm;
}
.footer a:link {
font-weight:bold;
color:#ffffff;
text-decoration:underline;
}
.footer a:visited {
font-weight:bold;
color:#ffffff;
text-decoration:underline;
}
.footer a:hover {
font-weight:bold;
color:#002244;
text-decoration:underline; }
.check {font-size: x-small;
text-align:right;}
.check a:link { font-weight:bold;
color:#a0a0ff;
text-decoration:underline; }
.check a:visited { font-weight:bold;
color:#a0a0ff;
text-decoration:underline; }
.check a:hover { font-weight:bold;
color:#000000;
text-decoration:underline; }
tt {
font-size: 1.1em;
font-weight: bold;
}
.def {
margin-top: 1.5em;
font-family: tahoma, arial, sans-serif;
}
.desc {
padding-left: .6em;
}
h2 {
font-size: 14pt;
}

View File

@ -1,10 +0,0 @@
(defpackage :ieee-floats-system
(:use :common-lisp :asdf))
(in-package :ieee-floats-system)
(defsystem :ieee-floats
:components ((:file "ieee-floats")))
(defsystem :ieee-floats-tests
:depends-on (:ieee-floats :fiveam)
:components ((:file "tests")))

View File

@ -1,138 +0,0 @@
;;; Functions for converting floating point numbers represented in
;;; IEEE 754 style to lisp numbers.
;;;
;;; See http://common-lisp.net/project/ieee-floats/
(in-package :common-lisp)
(defpackage :ieee-floats
(:use :common-lisp)
(:export :make-float-converters
:encode-float32
:decode-float32
:encode-float64
:decode-float64))
(in-package :ieee-floats)
;; The following macro may look a bit overcomplicated to the casual
;; reader. The main culprit is the fact that NaN and infinity can be
;; optionally included, which adds a bunch of conditional parts.
;;
;; Assuming you already know more or less how floating point numbers
;; are typically represented, I'll try to elaborate a bit on the more
;; confusing parts, as marked by letters:
;;
;; (A) Exponents in IEEE floats are offset by half their range, for
;; example with 8 exponent bits a number with exponent 2 has 129
;; stored in its exponent field.
;;
;; (B) The maximum possible exponent is reserved for special cases
;; (NaN, infinity).
;;
;; (C) If the exponent fits in the exponent-bits, we have to adjust
;; the significand for the hidden bit. Because decode-float will
;; return a significand between 0 and 1, and we want one between 1
;; and 2 to be able to hide the hidden bit, we double it and then
;; subtract one (the hidden bit) before converting it to integer
;; representation (to adjust for this, 1 is subtracted from the
;; exponent earlier). When the exponent is too small, we set it to
;; zero (meaning no hidden bit, exponent of 1), and adjust the
;; significand downward to compensate for this.
;;
;; (D) Here the hidden bit is added. When the exponent is 0, there is
;; no hidden bit, and the exponent is interpreted as 1.
;;
;; (E) Here the exponent offset is subtracted, but also an extra
;; factor to account for the fact that the bits stored in the
;; significand are supposed to come after the 'decimal dot'.
(defmacro make-float-converters (encoder-name
decoder-name
exponent-bits
significand-bits
support-nan-and-infinity-p)
"Writes an encoder and decoder function for floating point
numbers with the given amount of exponent and significand
bits (plus an extra sign bit). If support-nan-and-infinity-p is
true, the decoders will also understand these special cases. NaN
is represented as :not-a-number, and the infinities as
:positive-infinity and :negative-infinity. Note that this means
that the in- or output of these functions is not just floating
point numbers anymore, but also keywords."
(let* ((total-bits (+ 1 exponent-bits significand-bits))
(exponent-offset (1- (expt 2 (1- exponent-bits)))) ; (A)
(sign-part `(ldb (byte 1 ,(1- total-bits)) bits))
(exponent-part `(ldb (byte ,exponent-bits ,significand-bits) bits))
(significand-part `(ldb (byte ,significand-bits 0) bits))
(nan support-nan-and-infinity-p)
(max-exponent (1- (expt 2 exponent-bits)))) ; (B)
`(progn
(defun ,encoder-name (float)
,@(unless nan `((declare (type float float))))
(multiple-value-bind (sign significand exponent)
(cond ,@(when nan `(((eq float :not-a-number)
(values 0 1 ,max-exponent))
((eq float :positive-infinity)
(values 0 0 ,max-exponent))
((eq float :negative-infinity)
(values 1 0 ,max-exponent))))
((zerop float)
(values 0 0 0))
(t
(multiple-value-bind (significand exponent sign) (decode-float float)
(let ((exponent (+ (1- exponent) ,exponent-offset))
(sign (if (= sign 1.0) 0 1)))
(unless (< exponent ,(expt 2 exponent-bits))
(error "Floating point overflow when encoding ~A." float))
(if (< exponent 0) ; (C)
(values sign (ash (round (* ,(expt 2 significand-bits) significand)) exponent) 0)
(values sign (round (* ,(expt 2 significand-bits) (1- (* significand 2)))) exponent))))))
(let ((bits 0))
(declare (type (unsigned-byte ,total-bits) bits))
(setf ,sign-part sign
,exponent-part exponent
,significand-part significand)
bits)))
(defun ,decoder-name (bits)
(declare (type (unsigned-byte ,total-bits) bits))
(let* ((sign ,sign-part)
(exponent ,exponent-part)
(significand ,significand-part))
,@(when nan `((when (= exponent ,max-exponent)
(return-from ,decoder-name
(cond ((not (zerop significand)) :not-a-number)
((zerop sign) :positive-infinity)
(t :negative-infinity))))))
(if (zerop exponent) ; (D)
(setf exponent 1)
(setf (ldb (byte 1 ,significand-bits) significand) 1))
(unless (zerop sign)
(setf significand (- significand)))
(scale-float (float significand ,(if (> total-bits 32) 1.0d0 1.0))
(- exponent ,(+ exponent-offset significand-bits)))))))) ; (E)
;; And instances of the above for the common forms of floats.
(make-float-converters encode-float32 decode-float32 8 23 nil)
(make-float-converters encode-float64 decode-float64 11 52 nil)
;;; Copyright (c) 2006 Marijn Haverbeke
;;;
;;; This software is provided 'as-is', without any express or implied
;;; warranty. In no event will the authors be held liable for any
;;; damages arising from the use of this software.
;;;
;;; Permission is granted to anyone to use this software for any
;;; purpose, including commercial applications, and to alter it and
;;; redistribute it freely, subject to the following restrictions:
;;;
;;; 1. The origin of this software must not be misrepresented; you must
;;; not claim that you wrote the original software. If you use this
;;; software in a product, an acknowledgment in the product
;;; documentation would be appreciated but is not required.
;;;
;;; 2. Altered source versions must be plainly marked as such, and must
;;; not be misrepresented as being the original software.
;;;
;;; 3. This notice may not be removed or altered from any source
;;; distribution.

View File

@ -1,66 +0,0 @@
(defpackage :ieee-floats-tests
(:use :common-lisp :ieee-floats :fiveam))
(in-package :ieee-floats-tests)
;; After loading, run the tests with (fiveam:run! :ieee-floats)
;; The tiny-XX tests will error on systems that do not support 64-bit
;; floats, CLISP is one of those.
(def-suite :ieee-floats)
(in-suite :ieee-floats)
(defmacro pairs-correspond (decode encode &body pairs)
`(progn ,@(loop :for (float bits) :in pairs
:collect `(is (eql ,float (,decode ,bits)))
:collect `(is (eql ,bits (,encode ,float))))))
(def-fixture special-converters ()
(make-float-converters encode-float64* decode-float64* 11 52 t)
(make-float-converters encode-float32* decode-float32* 8 23 t))
(test sanity-32
(pairs-correspond decode-float32 encode-float32
(0.0 #b00000000000000000000000000000000)
(5.0 #b01000000101000000000000000000000)
(-5.0 #b11000000101000000000000000000000)
(3.3333333e20 #b01100001100100001000111101101111)
(-.44e-30 #b10001101000011101100100111000101)))
(test tiny-32
(pairs-correspond decode-float32 encode-float32
(9.949219e-44 #b00000000000000000000000001000111)))
(test overflow-32
(signals error
(encode-float32 1.0d60)))
(test specials-32
(with-fixture special-converters ()
(pairs-correspond decode-float32* encode-float32*
(5.0e2 #b01000011111110100000000000000000)
(-5.0e-2 #b10111101010011001100110011001101)
(:not-a-number #b01111111100000000000000000000001)
(:positive-infinity #b01111111100000000000000000000000)
(:negative-infinity #b11111111100000000000000000000000))))
(test sanity-64
(pairs-correspond decode-float64 encode-float64
(0.0d0 #b0000000000000000000000000000000000000000000000000000000000000000)
(42d42 #b0100100011111110001000100010111010000010011001101101001001111111)
(-42d42 #b1100100011111110001000100010111010000010011001101101001001111111)
(.555555555d-30 #b0011100110100110100010010011011111111110011011000100011010001000)))
(test tiny-64
(pairs-correspond decode-float64 encode-float64
(4.1995579896505956d-322 #b0000000000000000000000000000000000000000000000000000000001010101)))
(test specials-64
(with-fixture special-converters ()
(pairs-correspond decode-float64* encode-float64*
(42d42 #b0100100011111110001000100010111010000010011001101101001001111111)
(-42d42 #b1100100011111110001000100010111010000010011001101101001001111111)
(:not-a-number #b0111111111110000000000000000000000000000000000000000000000000001)
(:positive-infinity #b0111111111110000000000000000000000000000000000000000000000000000)
(:negative-infinity #b1111111111110000000000000000000000000000000000000000000000000000))))