• Fix (make-int-serializer) to be big-endian 2′s complement
• Add :symbol and :keyword serializers
• Add (make-vector-serializer)
• Add (make-key-slot-serializer) and (make-key-accessor-serializer)
• Add (define-serializing-funcall)

Obtaining

• The USerial home page: http://nklein.com/software/unet/userial/
• The tarball: userial_0.8.2011.06.02.tar.gz
• The signature: userial_0.8.2011.06.02.tar.gz.asc
• The main git repository: http://git.nklein.com/lisp/libs/userial.git/
• Browsable git mirror: https://github.com/nklein/userial
• Issue reporting: https://github.com/nklein/userial/issues

Obtaining

Getting the USerial library:

• The home page: http://nklein.com/software/unet/userial/
• The tar-ball: userial_0.7.2011.05.24.tar.gz
• The GPG signature for the tar-ball: userial_0.7.2011.05.24.tar.gz.asc
• The main git repository: http://git.nklein.com/lisp/libs/userial.git
• A browsable mirror of the git repository: http://github.com/nklein/userial

Differences

The differences between this version and earlier versions of this library include:

• Use of ContextL layered functions instead of CLOS methods
• Elimination of :buffer parameter in favor of using the *buffer* special variable
• Cleaning up macros which no longer required the :buffer parameter
• Serializers for arbitrarily large integers and unsigned integers
• Serializer for raw sequence of bytes
• New make-list-serializer macro

By using ContextL layered functions, one has the ability to define a serializer and/or unserializer in a particular ContextL layer. This can be used to create new versions of the serializer without losing the ability to use the older version when required.

In the process, I have created macros to assist in creating completely custom serializers. This both streamlines their definition and should allow any future modifications to the USerial library to fly under the radar. Code that before looked like this:

(defmethod serialize ((key (eql :foo)) (value foo-struct)
                      &key (buffer userial:*buffer*) &allow-other-keys)
  ... some code ...
  buffer)
 
(defmethod unserialize ((key (eql :foo))
                        &key (buffer userial:*buffer*) &allow-other-keys)
  (values (progn ... some code ...)
          buffer))

Should now look like this:

(define-serializer (:foo (value foo-struct))
  ... some code ...)
 
(define-unserializer (:foo)
  ... some code ...)

And, when you find you need to add a new version of your :foo serializer but you don’t want to lose the old one, you can add:

(contextl:deflayer new-version)
 
(define-serializer (:foo (value foo-struct) :layer new-version)
  ... some new code ...)

Without the :buffer parameter everywhere, code that used to look like this:

(serialize* (:string aa :uint8 bb) :buffer buf)
(buffer-rewind :buffer buf)
(unserialize-slots* (:string name :uint8 age) object :buffer buf)

Should now look like this:

(with-buffer buf
  (serialize* :string aa :uint8 bb)
  (buffer-rewind)
  (unserialize-slots* object :string name :uint age))

There are now :int and :uint serializers that encode arbitrarily large integers and unsigned integers, respectively. There is also a serializer that copies a sequence of bytes as is without any prefix or suffix. To unserialize, you either have to provide a buffer of the appropriate length with the :output parameter or provide appropriate :start and :end keywords.

(serialize :raw-bytes uchar-array &key (start 0)
                                       (end (length uchar-array)))
(unserialize :raw-bytes &key output
                             (start 0)
                             (end (length output)))

And, if you have a serialize/unserialize pair for type :foo you can use the make-list-serializer macro to create a serialize/unserialize pair for a list of items that can be serialized with the :foo serializer.

(make-list-serializer :list-of-uint8 :uint8)
(serialize :list-of-int8 '(0 1 1 2 3 5 8 13 21 34 55 89))

At the USerial home page, you can find more complete documentation.

Obtaining

Getting the USerial library:

• The home page: http://nklein.com/software/unet/userial/
• The tar-ball: userial_0.7.2011.05.24.tar.gz
• The GPG signature for the tar-ball: userial_0.7.2011.05.24.tar.gz.asc
• The main git repository: http://git.nklein.com/lisp/libs/userial.git
• A browsable mirror of the git repository: http://github.com/nklein/userial

Differences

The differences between this version and earlier versions of this library include:

• Use of ContextL layered functions instead of CLOS methods
• Elimination of :buffer parameter in favor of using the *buffer* special variable
• Cleaning up macros which no longer required the :buffer parameter
• Serializers for arbitrarily large integers and unsigned integers
• Serializer for raw sequence of bytes
• New make-list-serializer macro

By using ContextL layered functions, one has the ability to define a serializer and/or unserializer in a particular ContextL layer. This can be used to create new versions of the serializer without losing the ability to use the older version when required.

In the process, I have created macros to assist in creating completely custom serializers. This both streamlines their definition and should allow any future modifications to the USerial library to fly under the radar. Code that before looked like this:

(defmethod serialize ((key (eql :foo)) (value foo-struct)
                      &key (buffer userial:*buffer*) &allow-other-keys)
  ... some code ...
  buffer)
 
(defmethod unserialize ((key (eql :foo))
                        &key (buffer userial:*buffer*) &allow-other-keys)
  (values (progn ... some code ...)
          buffer))

Should now look like this:

(define-serializer (:foo (value foo-struct))
  ... some code ...)
 
(define-unserializer (:foo)
  ... some code ...)

And, when you find you need to add a new version of your :foo serializer but you don’t want to lose the old one, you can add:

(contextl:deflayer new-version)
 
(define-serializer (:foo (value foo-struct) :layer new-version)
  ... some new code ...)

Without the :buffer parameter everywhere, code that used to look like this:

(serialize* (:string aa :uint8 bb) :buffer buf)
(buffer-rewind :buffer buf)
(unserialize-slots* (:string name :uint8 age) object :buffer buf)

Should now look like this:

(with-buffer buf
  (serialize* :string aa :uint8 bb)
  (buffer-rewind)
  (unserialize-slots* object :string name :uint age))

There are now :int and :uint serializers that encode arbitrarily large integers and unsigned integers, respectively. There is also a serializer that copies a sequence of bytes as is without any prefix or suffix. To unserialize, you either have to provide a buffer of the appropriate length with the :output parameter or provide appropriate :start and :end keywords.

(serialize :raw-bytes uchar-array &key (start 0)
                                       (end (length uchar-array)))
(unserialize :raw-bytes &key output
                             (start 0)
                             (end (length output)))

And, if you have a serialize/unserialize pair for type :foo you can use the make-list-serializer macro to create a serialize/unserialize pair for a list of items that can be serialized with the :foo serializer.

(make-list-serializer :list-of-uint8 :uint8)
(serialize :list-of-int8 '(0 1 1 2 3 5 8 13 21 34 55 89))

At the USerial home page, you can find more complete documentation.

Edit: After re-reading some of the ContextL papers, I believe that I am actually just going to use ContextL as it’s a much more flexible superset of this library. I will probably still keep this library published as an example of a non-trivial, but glarkable, method combination.

I am releasing a new library that allows one to dispatch generic methods based on the value of a global parameter.

There are situations where one might like to dispatch a method on some information other than the required parameters of the method. For many situations, it is sufficient to switch between those methods based on some external parameter. The method-versions library allows one to do just that.

Obtaining

• The home page: http://nklein.com/software/method-versions/
• The tar-ball: method-versions_0.1.2011.05.18.tar.gz
• The GPG signature for the tar-ball: method-versions_0.1.2011.05.18.tar.gz.asc
• The main git repository: http://git.nklein.com/lisp/libs/method-versions.git
• A browsable mirror of the git repository: http://github.com/nklein/method-versions

Internationalization Example

In this example, we do a silly form of internationalization. To that end, we will use English as the default language and define some other languages.

 (method-versions:define-method-version latin)
 (method-versions:define-method-version pig-latin)
 (method-versions:define-method-version french latin)
 (method-versions:define-method-version spanish latin)

We will prepare a language parameter and a welcome method that is versioned on the language.

 (declaim (special *language*))
 (defparameter *language* nil)
 
 (defgeneric welcome ()
   (:method-combination method-versions:method-version-method-combination
                        *language*))

And, we define welcome methods for the various languages (accidentally forgetting spanish).

 (defmethod welcome () :welcome)
 (defmethod welcome :latin     () :velkominum)
 (defmethod welcome :pig-latin () :elcomeway)
 (defmethod welcome :french    () :bonjour)

Then, we will try each of the languages in turn.

 (mapcar #'(lambda (ll)
             (let ((*language* ll))
               (welcome)))
         '(nil :latin :pig-latin :french :spanish))
 => (:welcome :velkominum :elcomeway :bonjour :velkominum)

(make-list-serializer :list-of-integers :uint32)
 
(with-buffer (make-buffer)
  (serialize :list-of-integers '(1 2 3 4 5 6 7))
  (buffer-rewind)
  (reduce #'+ (unserialize :list-of-integers))) => 28

Here is the latest:

• Code userial_0.6.2011.05.12.tar.gz, and
• Signature userial_0.6.2011.05.12.tar.gz.asc

This release extends the (make-slot-serializer ...) and (make-accessor-serializer ...) so that you can pass an existing instance into the unserializers with the :object parameter rather than having the factory form allocate a new instance.

This release also provides ways to serialize and unserialize from slots and accessors in other code to allow even greater flexibility:

(serialize-accessors* (:string person-name
                       :uint8  person-age
                       :string person-hair-color)
     *person-instance* :buffer buffer)
 
(unserialize-slots* (:string name
                     :uint8  age
                     :string hair-color)
     *person-instance* :buffer buffer)

The serialize-slots* and unserialize-accessors* macros are also available.

Here is the latest:

• Code userial_0.5.2011.04.21.tar.gz, and
• Signature userial_0.5.2011.04.21.tar.gz.asc

Edit: Special thanks to Elliott Slaughter. The above improvements came out of recommendations from him.

(serialize-log :log-category :uint32 uint-to-log :string "string to log" ...)

Here is the latest tarball: userial_0.4.2011.04.11.tar.gz and its signature: userial_0.4.2011.04.11.tar.gz.asc.

• Here is the new tarball: fft_1.4.2011.03.24.tar.gz
• and its GPG signature: fft_1.4.2011.03.24.tar.gz.asc

Thank you!

In an intervening and unannounced release, I added serializers for slots and accessors.

In this release, I have also really fleshed out the documentation and examples.

For instructions on obtaining and using the USerial library, please refer to the USerial library web page.

Edit: This had been v0.3.2011.03.04, but I made a minor update to add MIT License and correct a few glitches in the docs. Now, it’s v0.3.2011.03.05.

If you have any expertise in Spanish, French, German, or Japanese, I’d appreciate any feedback you can give me about the words I chose in those languages. Would they be the word one would think of when shown the picture? Thanks, in advance.