From: Kirk Haines <khaines@...>
Date: 2002-06-12T05:41:53+09:00
Subject: Re: Modules and version determination

> Hi all,
>
> I'm curious as to what you all think about an internal 'version()'
> method for published modules.  I've seen a few threads out on Google,
> but no definitive consensus on the subject.
>
> In other words, should we always put a "version" method (or VERSION, or
> _version_, or whatever) within our modules as a class method?  If so,
> what syntax do people prefer?

I've got a module that I wrote called Meta that is used to define metadata
such as version numbers.  From it's minimal documentation:
-----
                      FILE NAME: $RCSfile: Meta.rb,v $

   REVISION:  $Revision:  1.5 $
   AUTHOR:  $Author: khaines $
   DATE MODIFIED:  $Date: 2002/01/19 08:09:13 $

                                   PURPOSE:

   Provides  a set of mixins that let one set version, modification date,
   and  other  similar sorts of module/class information in a way that is
   human readable and also software queryable.

                                   EXAMPLE:

Class Foo
  require "Meta"
  include Meta

  version .13
  author 'Jack Black'
  modification_date '17 Jan 2002'
  state 'stable'
  about <<-EABOUT
    Provides mixin methods that let one specify versioning and
    other descriptive information in a human readable and code
    queryable manner.
  EABOUT
  history <<-EHISTORY
    # $Log: Meta.rb,v $
    # Revision 1.5  2002/01/19 08:09:13  khaines
    # Removed the module declaration.  That's not really what this is.
    #
    # Revision 1.4  2002/01/17 07:17:34  khaines
    # Fixed a small typo.
    #
    # Revision 1.3  2002/01/17 05:41:00  khaines
    # Added the first swing at inlined documentation to the module.
    #
    # Revision 1.2  2002/01/14 07:54:47  khaines
    # Added some comments.
    #
  EHISTORY

-----

The code underlying it can _certainly_ be improved.  It was one of my
early forays into Ruby.  It provides the following facilities:

version()
  Takes a String that contains a version number.  If no argument, returns
  the last set version #.

  version '1.23.07b'
  myver = version() #myver contains "1.23.07b"


cvsVersion()
  Takes a version string as delivered by the Revision tag of CVS (RCS)
  and trims of the extraneous information, leaving just the version number.

  cvsVersion '$Revision:  1.5 $
  myver = version()  #myver contains "1.5"


modification_date()
  Sets or returns the last modification date of the module or class.
  Uses ParseDate::parsedate to make sense of any value passed to it, and
  returns a string containing the date, asctime() formatted.

  modification_date '17 Jul 2003 16:41:39'
  mod_date = modification_date();


author()
  Takes a string containing the author's name.  If called without an arg,
  returns the last set author's name.

  author 'Jack Black'
  myauthor = author() #Contains "Jack Black"


history()
  Takes a string describing the class or module history.  If called without
  and arg, returns the history as a string.


state()
  Sets or gets a string giving a simple description of the state of the
  class or module.


about()
  Sets or gets a string describing what the class or module is all about.



The idea was so that I could make my library of code software indexable
and queryable so that I could provide, for example, a web app that let one
browse high level information about the code corpus, then drill down tothe documentation within the file for more information.

If anyone is interested, I can put this module where you can download it.


Kirk Haines