core/library/structures/version_record.h

   1 #ifndef VERSION_STRUCTURE_GROUP
   2 #define VERSION_STRUCTURE_GROUP
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : version & version_record                                          *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 1996-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 /*! @file version_record.h
  19   Note that this header is tuned for forward declaration of the version
  20   and version_record objects; this is a better approach than including this
  21   somewhat heavy header file in other header files.
  22 */
  23
  24 #include "string_array.h"
  25
  26 #include <basis/astring.h>
  27 #include <basis/contracts.h>
  28
  29 namespace structures {
  30
  31 //! Holds a file's version identifier.
  32 /*!
  33   The version structures can be used in any of our components because
  34   they're not platform specific.  They maintain information about a file
  35   that is part of the released product.
  36 */
  37
  38 class version : public virtual basis::packable, public virtual basis::orderable
  39 {
  40 public:
  41   version();  //!< constructs a blank version.
  42
  43   version(const structures::string_array &version_info);
  44     //!< constructs a version from a list of strings that form the components.
  45     /*!< note that if a component is an empty string, it is changed to be a
  46     zero ("0"). */
  47
  48   version(const basis::astring &formatted_string);
  49     //!< the version components will be parsed from the "formatted_string".
  50     /*!< the version component separator is the period ('.') or the comma (',')
  51     character. */
  52
  53   version(int major, int minor, int rev = 0, int build = 0);
  54     //!< constructs a win32 style version structure from the information.
  55
  56   version(const version &to_copy);
  57     //!< constructs a copy of "to_copy".
  58
  59   virtual ~version();
  60
  61   version &operator =(const version &to_copy);
  62     //!< assigns this to the "to_copy".
  63
  64   DEFINE_CLASS_NAME("version");
  65
  66   virtual basis::astring text_form() const;
  67
  68   bool equal_to(const equalizable &to_test) const;
  69     //!< compares two versions for exact equality.
  70     /*!< to perform a check of win32 build compatibility, use the
  71     compatible() method. */
  72
  73   bool less_than(const orderable &to_test) const;
  74     //!< reports if this version is less than "to_test".
  75     /*!< supplies the other operator needed for the full set of comparisons
  76     (besides equality).  the basis namespace provides templates for the rest
  77     of the comparison operators in <basis/functions.h>. */
  78
  79   int components() const;
  80     //!< reports the number of components that make up this version.
  81
  82   basis::astring get_component(int index) const;
  83     //!< returns the component at the specified index.
  84     /*!< note that if an entry is an empty string, then a string with zero
  85     in it is returned ("0"). */
  86
  87   void set_component(int index, const basis::astring &to_set);
  88     //!< sets the component at "index" to "to_set".
  89     /*!< an empty string for "to_set" is turned into a zero. */
  90
  91   enum version_places { MAJOR, MINOR, REVISION, BUILD };
  92     //!< these are names for the first four components of the version.
  93     /*!< there may be more components than four on some platforms. */
  94
  95   enum version_style { DOTS, COMMAS, DETAILED };
  96     //!< different ways that a version object can be displayed.
  97     /*!< DOTS is in the form "1.2.3.4"
  98     COMMAS is in the form "1, 2, 3, 4"
  99     DETAILED is in the form "major 1, minor 2, ..."
 100     */
 101
 102   basis::astring flex_text_form(version_style style = DOTS, int including = -1) const;
 103     //!< returns a textual form of the version number.
 104     /*!< the place passed in "including" specifies how much of the version
 105     to print, where a negative number means all components.  for example, if
 106     "including" is MINOR, then only the first two components (major and minor
 107     components) are printed. */
 108
 109   static version from_text(const basis::astring &to_convert);
 110     //!< returns a version structure parsed from "to_convert".
 111
 112   virtual int packed_size() const;
 113   virtual void pack(basis::byte_array &target) const;
 114   virtual bool unpack(basis::byte_array &source);
 115
 116   //////////////
 117
 118   // the following methods mainly help on win32 platforms, where the version
 119   // components are always simple short integers.  there are only ever four
 120   // of these.  if one adheres to that same scheme on other platforms, then
 121   // these functions may be helpful.  otherwise, with the mixed alphanumeric
 122   // versions one sees on unix, these are not so great.
 123
 124   int v_major() const;
 125     //!< major version number.
 126     /*!< major & minor are the most significant values for a numerical version.
 127     these are the familiar numbers often quoted for software products, like
 128     "jubware version 8.2". */
 129   int v_minor() const;
 130     //!< minor version number.
 131   int v_revision() const;
 132     //!< revision level.
 133     /*!< in the hoople code and the clam system, this number is changed for
 134     every new build.  when two versions of a file are the same in major,
 135     minor and revision numbers, then they are said to be compatible.  for
 136     those using this version scheme, it asserts that dll compatibility has not
 137     been broken if one swaps those two files in an installation.  after the
 138     swap, any components that are dependent on the dll must all link properly
 139     against the replacement file.  when in doubt, increment the version number.
 140     some folks automatically increment the revision level every week. */
 141   int v_build() const;
 142     //!< build number.
 143     /*!< this number is not considered important when comparing file
 144     compatibility.  the compatible() method always returns true if two files
 145     differ only in the "build" number (rather than major, minor or revision).
 146     this allows patches to be created with a newer (larger) build number, but
 147     still link fine with existing dlls.  since the file is distinguished by
 148     more than just its time stamp, it allows changes to an installation to be
 149     tracked very precisely.  some folks keep a catalog of patched components
 150     for each software release and index the patch details by the different
 151     build numbers. */
 152
 153   bool compatible(const version &that) const;
 154     //!< returns true if this is compatible with "that" version on win32.
 155     /*!< that means that all version components are the same except for the
 156     last one, the build number.  we allow the build numbers to fluctuate so
 157     that patched components can be installed without causing version
 158     complaints. */
 159
 160   bool bogus() const;
 161     //!< returns true if the version held here is clearly bogus.
 162     /*!< this means that all four numbers are zero. */
 163
 164 //////////////
 165
 166   static void *__global_module_handle();
 167     //!< a static resource required to identify the actual win32 module that this lives in.
 168     /*!< this handle is stored statically when the libraries are started up.  it records
 169     the handle of the module they belong to for later use in checking versions. */
 170
 171 //hmmm: storage here is still missing!
 172
 173 private:
 174   structures::string_array *_components;  //!< our list of version components.
 175 };
 176
 177 //////////////
 178
 179 //! Holds all information about a file's versioning.
 180 /*! Not all of these fields are meaningful on every platform. */
 181
 182 class version_record : public virtual basis::root_object
 183 {
 184 public:
 185   virtual ~version_record();
 186
 187   DEFINE_CLASS_NAME("version_record");
 188
 189   basis::astring text_form() const;
 190     // returns a view of the fields in this record.
 191
 192   // these describe a particular file:
 193   basis::astring description;  // the purpose of this file.
 194   version file_version;  // the version number for this file.
 195   basis::astring internal_name;  // the internal name of the file.
 196   basis::astring original_name;  // name of file before possible renamings.
 197
 198   // these describe the project that the file belongs to:
 199   basis::astring product_name;  // the product this file belongs to.
 200   version product_version;  // the version of the product.
 201
 202   // these describe the creators of the file:
 203   basis::astring company_name;  // name of the company that created the file.
 204
 205   // legal matters:
 206   basis::astring copyright;  // copyright info for this file.
 207   basis::astring trademarks;  // trademarks related to the file.
 208
 209   // extra pieces not stored in record (yet).
 210   basis::astring web_address;  // the location of the company on the web.
 211 };
 212
 213 //////////////
 214
 215 } //namespace.
 216
 217 #endif
 218