Commit 2c1b7ccf authored by Nathan Froyd's avatar Nathan Froyd
Browse files

add rudimentary documentation

parent 6caf614c

doc/index.html

0 → 100644
+32 −0
Original line number Diff line number Diff line 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"

        "http://www.w3.org/TR/html4/strict.dtd">

<HTML><HEAD><TITLE>nibbles</TITLE><LINK TYPE="text/css" TITLE="default" REL="stylesheet" MEDIA="screen" HREF="style.css" /></HEAD><BODY><H1>nibbles</H1><P>nibbles is a library for accessing multibyte integers from

octet arrays and streams.  While such accessors are straightforward to

write, nibbles aims to centralize such facilities and also

provide optimizations for them when appropriate.</P><H2>Installation</H2><P>nibbles can be downloaded at <A HREF="http://www.method-combination.net/lisp/files/nibbles.tar.gz">http://www.method-combination.net/lisp/files/nibbles.tar.gz</A>.  The latest version is 0.1.</P><P>It comes with an ASDF system definition, so <TT>(ASDF:OOS

'ASDF:LOAD-OP :NIBBLES)</TT> should be all that you need to get started.</P><H2>License</H2><P>nibbles is released under a MIT-like license; you can do pretty

much anything you want to with the code except claim that you wrote

it.</P><H2>Integer array accessors</H2><DIV CLASS="lisp-symbol"><A NAME="ub16ref/le"></A><TT><STRONG>ub16ref/le</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="ub32ref/le"></A><TT><STRONG>ub32ref/le</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="ub64ref/le"></A><TT><STRONG>ub64ref/le</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>This family of functions accesses an unsigned 16-bit, 32-bit or

64-bit value stored in little-endian order starting at <EM>index</EM> in <EM>vector</EM>.  <EM>vector</EM> must be a <TT>(VECTOR (UNSIGNED-BYTE 8))</TT>. These functions are SETFable.  For instance:</P><PRE>CL-USER> (nibbles:ub16ref/le (coerce #(42 53) '(vector (unsigned-byte 8))) 0)

13610

CL-USER> (format nil "~X" *)

"352A"</PRE><DIV CLASS="lisp-symbol"><A NAME="ub16ref/be"></A><TT><STRONG>ub16ref/be</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="ub32ref/be"></A><TT><STRONG>ub32ref/be</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="ub64ref/be"></A><TT><STRONG>ub64ref/be</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>As the above, only the value is accessed in big-endian order.  For instance:</P><PRE>CL-USER> (nibbles:ub16ref/be (coerce #(42 53) '(vector (unsigned-byte 8))) 0)

10805

CL-USER> (format nil "~X" *)

"2A35"</PRE><DIV CLASS="lisp-symbol"><A NAME="sb16ref/le"></A><TT><STRONG>sb16ref/le</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="sb32ref/le"></A><TT><STRONG>sb32ref/le</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="sb64ref/le"></A><TT><STRONG>sb64ref/le</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /></DIV><DIV CLASS="lisp-symbol"><A NAME="sb16ref/be"></A><TT><STRONG>sb16ref/be</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="sb32ref/be"></A><TT><STRONG>sb32ref/be</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="sb64ref/be"></A><TT><STRONG>sb64ref/be</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>As the above, only the value accessed is a signed value.  For instance:</P><PRE>CL-USER> (nibbles:sb16ref/be (coerce #(81 92) '(vector (unsigned-byte 8))) 0)

20828

CL-USER> (nibbles:sb16ref/be (coerce #(129 135) '(vector (unsigned-byte 8))) 0)

-32377

CL-USER> (format nil "~X ~X" * **)

"-7E79 515C"

CL-USER> (nibbles:sb16ref/le (coerce #(81 92) '(vector (unsigned-byte 8))) 0)

23633

CL-USER> (nibbles:sb16ref/le (coerce #(129 135) '(vector (unsigned-byte 8))) 0)

-30847

CL-USER> (format nil "~X ~X" * **)

"-787F 5C51"</PRE><H2>Stream readers</H2><DIV CLASS="lisp-symbol"><A NAME="read-ub16/le"></A><TT><STRONG>read-ub16/le</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-ub32/le"></A><TT><STRONG>read-ub32/le</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-ub64/le"></A><TT><STRONG>read-ub64/le</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>This family of functions reads an unsigned 16-bit, 32-bit, or

64-bit value from <EM>stream</EM> in little-endian order.  <EM>stream</EM>

must have an element-type of <TT>(UNSIGNED-BYTE 8)</TT>.</P><DIV CLASS="lisp-symbol"><A NAME="read-ub16/be"></A><TT><STRONG>read-ub16/be</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-ub32/be"></A><TT><STRONG>read-ub32/be</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-ub64/be"></A><TT><STRONG>read-ub64/be</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>As the above, only the value is read in big-endian order.</P><DIV CLASS="lisp-symbol"><A NAME="read-sb16/le"></A><TT><STRONG>read-sb16/le</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-sb32/le"></A><TT><STRONG>read-sb32/le</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-sb64/le"></A><TT><STRONG>read-sb64/le</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><DIV CLASS="lisp-symbol"><A NAME="read-sb16/be"></A><TT><STRONG>read-sb16/be</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-sb32/be"></A><TT><STRONG>read-sb32/be</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-sb64/be"></A><TT><STRONG>read-sb64/be</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>As the above, only the value is signed, rather than unsigned.</P><H2>Stream writers</H2><DIV CLASS="lisp-symbol"><A NAME="write-ub16/le"></A><TT><STRONG>write-ub16/le</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-ub32/le"></A><TT><STRONG>write-ub32/le</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-ub64/le"></A><TT><STRONG>write-ub64/le</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>This family of functions writes an unsigned 16-bit, 32-bit, or

64-bit <EM>integer</EM> to <EM>stream</EM> in little-endian order.  <EM>stream</EM>

must have an element-type of <TT>(UNSIGNED-BYTE 8)</TT>.  The value written

is returned.</P><DIV CLASS="lisp-symbol"><A NAME="write-ub16/be"></A><TT><STRONG>write-ub16/be</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-ub32/be"></A><TT><STRONG>write-ub32/be</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-ub64/be"></A><TT><STRONG>write-ub64/be</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>As the above, only the value is read in big-endian order.</P><DIV CLASS="lisp-symbol"><A NAME="write-sb16/le"></A><TT><STRONG>write-sb16/le</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-sb32/le"></A><TT><STRONG>write-sb32/le</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-sb64/le"></A><TT><STRONG>write-sb64/le</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><DIV CLASS="lisp-symbol"><A NAME="write-sb16/be"></A><TT><STRONG>write-sb16/be</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-sb32/be"></A><TT><STRONG>write-sb32/be</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-sb64/be"></A><TT><STRONG>write-sb64/be</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>As the above, only the value is signed, rather than unsigned.</P></BODY></HTML>
 
 No newline at end of file

doc/nibbles-doc.txt

0 → 100644
+130 −0
Original line number Diff line number Diff line 
(:author "Nathan Froyd"

 :email "froydnj@gmail.com"

 :package "nibbles"

 :cl-package "NIBBLES"

 :version #.(asdf:component-version (asdf:find-system :nibbles))

 :homepage "http://www.method-combination.net/lisp/nibbles/"

 :download "http://www.method-combination.net/lisp/files/nibbles.tar.gz")



(:h1 ${package})



(:p ${package} " is a library for accessing multibyte integers from

octet arrays and streams.  While such accessors are straightforward to

write, " ${package} " aims to centralize such facilities and also

provide optimizations for them when appropriate.")



(:h2 "Installation")



(:p ${package} " can be downloaded at " (:url ${download} ${download})

".  The latest version is " ${version} ".")



(:p "It comes with an ASDF system definition, so " `(ASDF:OOS

'ASDF:LOAD-OP :NIBBLES)` " should be all that you need to get started.")



(:h2 "License")



(:p ${package} " is released under a MIT-like license; you can do pretty

much anything you want to with the code except claim that you wrote

it.")



(:h2 "Integer array accessors")



(:describe :accessor (nibbles:ub16ref/le value)

                     (nibbles:ub32ref/le value)

                     (nibbles:ub64ref/le value))



(:p "This family of functions accesses an unsigned 16-bit, 32-bit or

64-bit value stored in little-endian order starting at " 'index' " in "

'vector' ".  " 'vector' " must be a " `(VECTOR (UNSIGNED-BYTE 8))`

". These functions are SETFable.  For instance:")



(:pre "CL-USER> (nibbles:ub16ref/le (coerce #(42 53) '(vector (unsigned-byte 8))) 0)

13610

CL-USER> (format nil \"~X\" *)

\"352A\"")



(:describe :accessor (nibbles:ub16ref/be value)

                     (nibbles:ub32ref/be value)

                     (nibbles:ub64ref/be value))



(:p "As the above, only the value is accessed in big-endian order.  For instance:")



(:pre "CL-USER> (nibbles:ub16ref/be (coerce #(42 53) '(vector (unsigned-byte 8))) 0)

10805

CL-USER> (format nil \"~X\" *)

\"2A35\"")



(:describe :accessor (nibbles:sb16ref/le value)

                     (nibbles:sb32ref/le value)

                     (nibbles:sb64ref/le value))



(:describe :accessor (nibbles:sb16ref/be value)

                     (nibbles:sb32ref/be value)

                     (nibbles:sb64ref/be value))



(:p "As the above, only the value accessed is a signed value.  For instance:")



(:pre "CL-USER> (nibbles:sb16ref/be (coerce #(81 92) '(vector (unsigned-byte 8))) 0)

20828

CL-USER> (nibbles:sb16ref/be (coerce #(129 135) '(vector (unsigned-byte 8))) 0)

-32377

CL-USER> (format nil \"~X ~X\" ** *)

\"515C -7E79\"

CL-USER> (nibbles:sb16ref/le (coerce #(81 92) '(vector (unsigned-byte 8))) 0)

23633

CL-USER> (nibbles:sb16ref/le (coerce #(129 135) '(vector (unsigned-byte 8))) 0)

-30847

CL-USER> (format nil \"~X ~X\" ** *)

\"5C51 -787F\"")



(:h2 "Stream readers")



(:describe :function (nibbles:read-ub16/le value)

	   	     (nibbles:read-ub32/le value)

		     (nibbles:read-ub64/le value))



(:p "This family of functions reads an unsigned 16-bit, 32-bit, or

64-bit value from " 'stream' " in little-endian order.  " 'stream' "

must have an element-type of " `(UNSIGNED-BYTE 8)` ".")



(:describe :function (nibbles:read-ub16/be value)

	   	     (nibbles:read-ub32/be value)

		     (nibbles:read-ub64/be value))



(:p "As the above, only the value is read in big-endian order.")



(:describe :function (nibbles:read-sb16/le value)

	   	     (nibbles:read-sb32/le value)

		     (nibbles:read-sb64/le value))

(:describe :function (nibbles:read-sb16/be value)

	   	     (nibbles:read-sb32/be value)

		     (nibbles:read-sb64/be value))



(:p "As the above, only the value is signed, rather than unsigned.")



(:h2 "Stream writers")



(:describe :function (nibbles:write-ub16/le value)

	   	     (nibbles:write-ub32/le value)

		     (nibbles:write-ub64/le value))



(:p "This family of functions writes an unsigned 16-bit, 32-bit, or

64-bit " 'integer' " to " 'stream' " in little-endian order.  " 'stream' "

must have an element-type of " `(UNSIGNED-BYTE 8)` ".  The value written

is returned.")



(:describe :function (nibbles:write-ub16/be value)

	   	     (nibbles:write-ub32/be value)

		     (nibbles:write-ub64/be value))



(:p "As the above, only the value is read in big-endian order.")



(:describe :function (nibbles:write-sb16/le value)

	   	     (nibbles:write-sb32/le value)

		     (nibbles:write-sb64/le value))

(:describe :function (nibbles:write-sb16/be value)

	   	     (nibbles:write-sb32/be value)

		     (nibbles:write-sb64/be value))



(:p "As the above, only the value is signed, rather than unsigned.")

doc/style.css

0 → 100644
+77 −0
Original line number Diff line number Diff line 
body {

  margin: 1em 5% 1em 5%;

}



p {

  margin-top: 0.5em;

  margin-bottom: 0.5em;

}



pre {

  padding: 0;

  margin: 0;

}



h1, h2 {

  border-bottom: 2px solid #449977;

}



h1, h2, h3, h4, h5, h6 {

  font-family: sans-serif;

  line-height: 1.3;

}



a:link {

  color: #449977;

}



a:visited {

  color: purple;

}



a {

  text-decoration: none;

  padding: 1px 2px;

}



a:hover {

  text-decoration: none;

  padding: 1px;

  border: 1px solid #000000;

}



.lisp-symbol {

  margin-right: 10%;

  margin-top: 1.5em;

  margin-bottom: 1.5em;

  border: 1px solid #449977;

  background: #eeeeee;

  padding: 0.5em;

}



.note {

  margin-right: 10%;

  margin-top: 1.5em;

  margin-bottom: 1.5em;

}



td.content {

  padding: 0;

}



td.title {

  font-family: sans-serif;

  font-size: 1.1em;

  font-weight: bold;

  text-align: left;

  vertical-align: top;

  text-decoration: underline;

  padding-right: 0.5em;

  margin-top: 0.0em;

  margin-bottom: 0.5em;

}



.note td.content {

  padding-left: 0.5em;

  border-left: 2px solid #449977;

}

nibbles.asd

+12 −1
Original line number Diff line number Diff line
@@ -5,8 +5,14 @@ 


(cl:in-package :nibbles-system)



(defclass txt-file (asdf:doc-file) ())

(defclass css-file (asdf:doc-file) ())



(defmethod asdf:source-file-type ((c txt-file) (s asdf:module)) "txt")

(defmethod asdf:source-file-type ((c css-file) (s asdf:module)) "css")



(asdf:defsystem :nibbles

  :version "0.1"

  :version "0.9"

  :author "Nathan Froyd <froydnj@gmail.com>"

  :maintainer "Nathan Froyd <froydnj@gmail.com>"

  :description "A library for accessing octet-addressed blocks of data"
@@ -18,6 +24,11 @@ 
               (:file "vectors" :depends-on ("types")

                      :in-order-to ((asdf:compile-op (asdf:load-op "macro-utils"))))

               (:file "streams" :depends-on ("vectors"))

	       (:module "doc"

			:components

			((:html-file "index")

			 (:txt-file "nibbles-doc")

			 (:css-file "style")))

               (:module "sbcl-opt"

                        :depends-on ("package" "macro-utils")

                        :if-component-dep-fails :ignore