The method-versions Reference Manual

Table of Contents

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

The method-versions Reference Manual

This is the method-versions Reference Manual, version 0.1.2011.5.18, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:16:23 2018 GMT+0.


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

1 Introduction

;; Copyright (c) 2011 nklein software ;; MIT License. See included LICENSE.txt file for licensing details.

method-versions v0.1.2011.05.18

Patrick Stein pat@nklein.com

Obtaining

Overview

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.

For more complicated situations where one also wants to turn on and off slots within classes, one might prefer ContextL. For situations where one wants to dispatch a method based on predicates on the arguments, one might prefer Filtered Functions.

Protocol Example

The method-versions library provides a method-combination one can use to create multiple versions of a method and switch which one is invoked through a special variable.

For example, suppose you were working on a protocol for a simple client-server application. You may have methods like this:

(defmethod send-cmd ((cmd login-cmd))
  (send-string (login-name cmd))
  (send-string (login-password cmd)))

(defmethod recv-cmd ((cmd login-cmd))
  (setf (login-name cmd) (recv-string))
  (setf (login-password cmd) (recv-string)))

After a few months of beta-testing, you want to extend the login command to include a geographic location. If you just update your send-cmd and recv-cmd methods for the login-cmd, then you will have to jump through all kinds of hoops to make sure that you can handle receiving a login command from users with the new send-cmd in their binary and users with the old send-cmd in their binary.

You can use the method-versions library to create a version of your server that can handle both versions in a sane manner.

First, you define a version for the new variant of your protocol.

(method-versions:define-method-version :v1.0)

Note: The define-method-version accepts an optional second parameter which specifies the parent version. So, for future expansion, one could end up with the following:

(method-versions:define-method-version :v1.0)
(method-versions:define-method-version :v1.1 v1.0)
(method-versions:define-method-version :v1.2 v1.1)
(method-versions:define-method-version :v2.0 v1.2)
(method-versions:define-method-version :v1.1-bugfix-1 v1.1)

After you have established your versions, you define a special variable which will track which version of your methods you would like to use during any given invocation and declare your generic method to use the method-versions-method-combination with your tracking variable.

(declaim (special *protocol-version*))
(defparameter *protocol-version* :v1.0)

(defgeneric send-cmd (cmd)
  (:method-combination method-versions:method-versions-method-combination
                       *protocol-version*))

(defgeneric recv-cmd (cmd)
  (:method-combination method-versions:method-versions-method-combination
                       *protocol-version*))

Next, you declare your default versions as before and declare your :v1.0 versions using the version as a method qualifier. (For brevity, we only show the recv-cmd here, but the recv-cmd is similar.)

(defmethod recv-cmd ((cmd login-cmd))
  (setf (login-name cmd) (recv-string))
  (setf (login-password cmd) (recv-string)))

(defmethod recv-cmd :v1.0 ((cmd login-cmd))
  (setf (login-name cmd) (recv-string))
  (setf (login-password cmd) (recv-string))
  (setf (login-nickname cmd) (recv-string)))

Now, if you want to receive a message coming in from a client who is using the original version, you would ensure *protocol-version* is set to nil and then invoke the recv-cmd method.

(let ((*protocol-version* nil))
  (recv-cmd cmd))

For clients who are using the new version, you would set the *protocol-version* appropriately and then invoke the recv-cmd method.

(let ((*protocol-version* :v1.0))
  (recv-cmd cmd))

Of course, you will have to know which version of the protocol the client is sending. We recommend that you assume the client is using the default version and add a message to your connection establishment phase where the client tells the server what version the client is using.

(defmethod send-cmd ((cmd version-cmd))
  (send-string (package-name (symbol-package *protocol-version*)))
  (send-string (symbol-name *protocol-version*)))

Then, use that version when receiving subsequent commands from that client.

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)

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

2 Systems

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


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

2.1 method-versions

Author

Patrick Stein <pat@nklein.com>

License

MIT

Description

method-versions: package for creating versioned methods

Version

0.1.2011.5.18

Source

method-versions.asd (file)

Components

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

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 files   [Contents][Index]

3.1.1 method-versions.asd

Location

method-versions.asd

Systems

method-versions (system)


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

3.1.2 method-versions/package.lisp

Parent

method-versions (system)

Location

package.lisp

Packages

method-versions


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

3.1.3 method-versions/method-versions.lisp

Dependency

package.lisp (file)

Parent

method-versions (system)

Location

method-versions.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 method-versions

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: define-method-version NAME &optional SUPER
Package

method-versions

Source

method-versions.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Method combinations

Long Method Combination: method-version-method-combination ()
Package

method-versions

Source

method-versions.lisp (file)


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

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: find-matching-version AA BB
Package

method-versions

Source

method-versions.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Generic functions

Generic Function: version-precedence VERSION
Package

method-versions

Source

method-versions.lisp (file)

Methods
Method: version-precedence (VERSION (eql nil))

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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   M  
Index Entry  Section

F
File, Lisp, method-versions.asd: The method-versions<dot>asd file
File, Lisp, method-versions/method-versions.lisp: The method-versions/method-versions<dot>lisp file
File, Lisp, method-versions/package.lisp: The method-versions/package<dot>lisp file

L
Lisp File, method-versions.asd: The method-versions<dot>asd file
Lisp File, method-versions/method-versions.lisp: The method-versions/method-versions<dot>lisp file
Lisp File, method-versions/package.lisp: The method-versions/package<dot>lisp file

M
method-versions.asd: The method-versions<dot>asd file
method-versions/method-versions.lisp: The method-versions/method-versions<dot>lisp file
method-versions/package.lisp: The method-versions/package<dot>lisp file

Jump to:   F   L   M  

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

A.2 Functions

Jump to:   D   F   G   M   V  
Index Entry  Section

D
define-method-version: Exported macros

F
find-matching-version: Internal functions
Function, find-matching-version: Internal functions

G
Generic Function, version-precedence: Internal generic functions

M
Macro, define-method-version: Exported macros
Method, version-precedence: Internal generic functions

V
version-precedence: Internal generic functions
version-precedence: Internal generic functions

Jump to:   D   F   G   M   V  

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

A.3 Variables


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

A.4 Data types

Jump to:   L   M   P   S  
Index Entry  Section

L
Long Method Combination, method-version-method-combination: Exported method combinations

M
Method Combination, Long, method-version-method-combination: Exported method combinations
method-version-method-combination: Exported method combinations
method-versions: The method-versions system
method-versions: The method-versions package

P
Package, method-versions: The method-versions package

S
System, method-versions: The method-versions system

Jump to:   L   M   P   S