Class: Inventory

Inherits:
Object
  • Object
show all
Defined in:
lib/inventory-1.0.rb,
lib/inventory-1.0/version.rb

Overview

An Inventory keeps track of your Ruby project’s version and its content. It also allows you to #load your project’s source files in a simple manner and track its #dependencies. Add-ons, such as [Inventory-Rake](disu.se/software/inventory-rake/) and [Inventory-Rake-Tasks-YARD](disu.se/software/inventory-rake-tasks-yard), can also use this information to great effect.

The basic usage pattern is to set your project’s Version constant to an instance of this class, where you set the version information and override the relevant methods with the information relevant to your project. For example, almost all project will want to override the #package_libs method with a method that returns an Array of the files relevant to it.

Quite a few methods have definitions that you’ll want to extend, for example, #dependencies, in which case you simply call super and add your additions to its result.

The naming convention of methods is that any method named “X_files” will return an Array of complete paths to files of kind X inside the project, while any method named “X” will return an Array of paths relative to the sub-directory that the method is named after. For example, “lib_files”returns an Array of complete paths to files under the “lib” directory ([lib/foo-1.0.rb, …]), while “libs” returns an Array of paths relative to the “lib” directory ([foo-1.0.rb]).

See Dependencies for more information on managing dependencies.

See Extension for more information on adding extensions.

Examples:

Creating an Inventory

require 'inventory-1.0'

class Foo
  Version = Inventory.new(1, 2, 0){
    authors{
      author 'A. U. Thor', '[email protected]'
    }

    homepage 'http://example.org/'

    licenses{
      license 'LGPLv3+',
              'GNU Lesser General Public License, version 3 or later',
              'http://www.gnu.org/licenses/'
    }

    def dependencies
      super + Dependencies.new{
        development 'inventory-rake', 1, 3, 0
        runtime 'bar', 1, 6, 0
      }
    end

    def package_libs
      %w'a.rb
         b.rb
         b/c.rb'
    end
  }
end

Defined Under Namespace

Modules: Dependency Classes: Author, Authors, Dependencies, Extension, License, Licenses

Constant Summary collapse

Version = 
Inventory.new(1, 5, 2){
  def authors
    Authors.new{
      author 'Nikolai Weibull', '[email protected]'
    }
  end

  def homepage
    'http://disu.se/software/inventory/'
  end

  def licenses
    Licenses.new{
      license 'LGPLv3+',
              'GNU Lesser General Public License, version 3 or later',
              'http://www.gnu.org/licenses/'
    }
  end

  def dependencies
    Dependencies.new{
      development 'inventory-rake', 1, 6, 0
      development 'inventory-rake-tasks-yard', 1, 4, 0
      development 'lookout', 3, 0, 0
      development 'lookout-rake', 3, 1, 0
      development 'yard', 0, 8, 7
      development 'yard-heuristics', 1, 2, 0
    }
  end

  def package_libs
    %w[author.rb
       authors.rb
       dependency.rb
       dependencies.rb
       dependencies/development.rb
       dependencies/optional.rb
       dependencies/runtime.rb
       extension.rb
       license.rb
       licenses.rb]
  end
}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(major, minor, patch, path = (m = /\A(.*):\d+(?::in .*)?\z/.match(caller.first) and m[1])) ⇒ Inventory

Sets up an inventory for version MAJOR.MINOR.PATCH for a library whose ‘lib/PACKAGE/version.rb` is at PATH. Any block will be #instance_exec’d.

Parameters:

  • major (String)
  • minor (String)
  • patch (String)
  • path (String) (defaults to: (m = /\A(.*):\d+(?::in .*)?\z/.match(caller.first) and m[1]))

Raises:

  • (ArgumentError) —

    If PATH’s default value can’t be calculated

  • (ArgumentError) —

    If PATH isn’t of the form ‘lib/PACKAGE/version.rb`



73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/inventory-1.0.rb', line 73

def initialize(major, minor, patch,
               path = (m = /\A(.*):\d+(?::in .*)?\z/.match(caller.first) and m[1]))
  @major, @minor, @patch = major, minor, patch
  raise ArgumentError, 'default value of path argument could not be calculated' unless path
  @path = path
  @srcdir, _, @package_path = File.dirname(File.expand_path(path)).rpartition('/lib/')
  @package = @package_path.sub(/-#{Regexp.escape(major.to_s)}\.0\z/, '').gsub('/', '-')
  @package_require = package == package_path.gsub('/', '-') ? '%s-%d.0' % [package_path, major] : package_path
  raise ArgumentError,
    'path is not of the form PATH/lib/PACKAGE/version.rb: %s' % path if
      @srcdir.empty?
  instance_exec(&Proc.new) if block_given?
end

Instance Attribute Details

#major ⇒ Integer (readonly)

Returns The major version atom of the package.

Returns:

  • (Integer) —

    The major version atom of the package



273
274
275
 
# File 'lib/inventory-1.0.rb', line 273

def major
  @major
end

#minor ⇒ Integer (readonly)

Returns The minor version atom of the package.

Returns:

  • (Integer) —

    The minor version atom of the package



276
277
278
 
# File 'lib/inventory-1.0.rb', line 276

def minor
  @minor
end

#package ⇒ String (readonly)

Returns The name of the package, as derived from the #package_path.

Returns:

  • (String) —

    The name of the package, as derived from the #package_path



89
90
91
 
# File 'lib/inventory-1.0.rb', line 89

def package
  @package
end

#package_path ⇒ String (readonly)

Returns The root sub-directory under the “lib” directory of the package of the package.

Returns:

  • (String) —

    The root sub-directory under the “lib” directory of the package of the package



289
290
291
 
# File 'lib/inventory-1.0.rb', line 289

def package_path
  @package_path
end

#package_require ⇒ String (readonly)

Returns The feature to require for the package.

Returns:

  • (String) —

    The feature to require for the package



292
293
294
 
# File 'lib/inventory-1.0.rb', line 292

def package_require
  @package_require
end

#patch ⇒ Integer (readonly)

Returns The patch version atom of the package.

Returns:

  • (Integer) —

    The patch version atom of the package



279
280
281
 
# File 'lib/inventory-1.0.rb', line 279

def patch
  @patch
end

#path ⇒ String (readonly)

Returns The path to the file containing the inventory.

Returns:

  • (String) —

    The path to the file containing the inventory



282
283
284
 
# File 'lib/inventory-1.0.rb', line 282

def path
  @path
end

#srcdir ⇒ String (readonly)

Returns The top-level path of the package.

Returns:

  • (String) —

    The top-level path of the package



285
286
287
 
# File 'lib/inventory-1.0.rb', line 285

def srcdir
  @srcdir
end

Instance Method Details

#additional_files ⇒ Array<String>

Returns Any additional files included in the package, the default being README and Rakefile.

Returns:

  • (Array<String>) —

    Any additional files included in the package, the default being README and Rakefile



244
245
246
247
248
249
 
# File 'lib/inventory-1.0.rb', line 244

def additional_files
  %w'
    README
    Rakefile
  '
end

#additional_libs ⇒ Array<String>

Returns Any additional library files, the default being ‘#package_path-#major.0.rb` and `#package_path/version.rb`.

Returns:



196
197
198
 
# File 'lib/inventory-1.0.rb', line 196

def additional_libs
  [package_require, File.join(package_path, 'version')].map{ |e| '%s.rb' % e }
end

#additional_unit_tests ⇒ Array<String>

Returns Any additional unit tests, the default being empty.

Returns:

  • (Array<String>) —

    Any additional unit tests, the default being empty



220
221
222
 
# File 'lib/inventory-1.0.rb', line 220

def additional_unit_tests
  []
end

#all_libs ⇒ Array<String>

Returns All library files, that is, #libs + #additional_libs.

Returns:



202
203
204
 
# File 'lib/inventory-1.0.rb', line 202

def all_libs
  libs + additional_libs
end

#all_unit_tests ⇒ Array<String>

Returns All unit tests, that is #unit_tests + #additional_unit_tests.

Returns:



226
227
228
 
# File 'lib/inventory-1.0.rb', line 226

def all_unit_tests
  unit_tests + additional_unit_tests
end

#authors {|?| ... } ⇒ Authors

Sets, when given a block, the authors of the project, otherwise returns them. The block will be #instance_exec’d inside a new Authors object, allowing you to add one or more authors.

Yields:

  • (?)

Returns:

Raises:

  • (RuntimeError) —

    If no block has been given and no authors have previously been set



122
123
124
125
126
 
# File 'lib/inventory-1.0.rb', line 122

def authors
  @authors = Authors.new(&Proc.new) if block_given?
  raise 'no authors defined in inventory of %s' % self if not defined? @authors or @authors.count == 0
  @authors
end

#dependencies ⇒ Dependencies

Note:

The default list of dependencies is an optional dependency on the inventory package itself.

Returns The dependencies of the package.

Returns:



157
158
159
160
161
 
# File 'lib/inventory-1.0.rb', line 157

def dependencies
  Dependencies.new{
    optional 'inventory', Version.major, Version.minor, Version.patch
  }
end

#extensions ⇒ Array<Extension>

Returns The extensions included in the package, the default being empty.

Returns:

  • (Array<Extension>) —

    The extensions included in the package, the default being empty



177
178
179
 
# File 'lib/inventory-1.0.rb', line 177

def extensions
  []
end

#files ⇒ Array<String>

Returns All files included in the package, that is #lib_files + #test_files + #additional_files + all files from #extensions.

Returns:



254
255
256
 
# File 'lib/inventory-1.0.rb', line 254

def files
  lib_files + test_files + additional_files + extensions.map(&:files).flatten
end

#homepage(value = nil) ⇒ String

Sets the project homepage to VALUE, or returns it, if VALUE is nil.

Parameters:

  • value (String) (defaults to: nil)

Returns:

  • (String)

Raises:

  • (RuntimeError) —

    If VALUE is nil and no homepage has previously been set



134
135
136
137
138
 
# File 'lib/inventory-1.0.rb', line 134

def homepage(value = nil)
  return @homepage = value if value
  raise 'no homepage set in inventory of %s' % self if not defined? @homepage
  @homepage
end

#inspect ⇒ Object 



268
269
270
 
# File 'lib/inventory-1.0.rb', line 268

def inspect
  '#<%s: %s %s>' % [self.class, package, self]
end

#lib_directories ⇒ Object 



96
97
98
 
# File 'lib/inventory-1.0.rb', line 96

def lib_directories
  %w[lib]
end

#lib_files ⇒ Array<String>

Returns The complete paths of all library files inside the package.

Returns:



208
209
210
 
# File 'lib/inventory-1.0.rb', line 208

def lib_files
  all_libs.map{ |e| 'lib/%s' % e }
end

#libs ⇒ Array<String>

Returns The library files to load when #loading, the default being #package_libs inside a directory with the same name as #package_require.

Returns:



190
191
192
 
# File 'lib/inventory-1.0.rb', line 190

def libs
  package_libs.map{ |e| '%s/%s' % [package_path, e] }
end

#licenses {|?| ... } ⇒ Licenses

Sets, when given a block, the licenses of the project, otherwise returns them. The block will be #instance_exec’d inside a new Licenses object, allowing you to add one or more licenses.

Yields:

  • (?)

Returns:

Raises:

  • (RuntimeError) —

    If no block has been given and no licenses have previously been set



148
149
150
151
152
 
# File 'lib/inventory-1.0.rb', line 148

def licenses
  @licenses = Licenses.new(&Proc.new) if block_given?
  raise 'no licenses defined in inventory of %s' % self if not defined? @licenses or @licenses.count == 0
  @licenses
end

#load ⇒ self

Requires all #requires, requires all #dependencies, and loads all #loads.

Returns:

  • (self) 


104
105
106
107
108
109
110
111
112
113
 
# File 'lib/inventory-1.0.rb', line 104

def load
  requires.each do |requirement|
    require requirement
  end
  dependencies.require
  loads.each do |load|
    Kernel.load File.expand_path('lib/%s' % load, srcdir)
  end
  self
end

#loads ⇒ Array<String>

Returns The files to load when #loading, the default being #libs.

Returns:

  • (Array<String>) —

    The files to load when #loading, the default being #libs



171
172
173
 
# File 'lib/inventory-1.0.rb', line 171

def loads
  libs
end

#package_libs ⇒ Array<String>

Returns The library files belonging to the package that will be loaded when #loading, the default being empty.

Returns:

  • (Array<String>) —

    The library files belonging to the package that will be loaded when #loading, the default being empty



183
184
185
 
# File 'lib/inventory-1.0.rb', line 183

def package_libs
  []
end

#requires ⇒ Array<String>

Returns The files to require when #loading, the default being empty.

Returns:

  • (Array<String>) —

    The files to require when #loading, the default being empty



165
166
167
 
# File 'lib/inventory-1.0.rb', line 165

def requires
  []
end

#test_files ⇒ Array<String>

Returns All test files included in the package, the default being #unit_test_files.

Returns:

  • (Array<String>) —

    All test files included in the package, the default being #unit_test_files



238
239
240
 
# File 'lib/inventory-1.0.rb', line 238

def test_files
  unit_test_files
end

#to_a ⇒ Array<String>

Returns Whatever #files returns.

Returns:

  • (Array<String>) —

    Whatever #files returns



259
260
261
 
# File 'lib/inventory-1.0.rb', line 259

def to_a
  files
end

#to_s ⇒ String

Returns The version atoms formatted as #major.#minor.#patch.

Returns:



264
265
266
 
# File 'lib/inventory-1.0.rb', line 264

def to_s
  '%d.%d.%d' % [major, minor, patch]
end

#unit_test_files ⇒ Array<String>

Returns The complete paths of all unit test files inside the package.

Returns:

  • (Array<String>) —

    The complete paths of all unit test files inside the package



232
233
234
 
# File 'lib/inventory-1.0.rb', line 232

def unit_test_files
  all_unit_tests.map{ |e| 'test/unit/%s' % e }
end

#unit_tests ⇒ Array<String>

Returns The unit tests included in the package, the default being #all_libs, meaning that there’s one unit test for each library file.

Returns:

  • (Array<String>) —

    The unit tests included in the package, the default being #all_libs, meaning that there’s one unit test for each library file



215
216
217
 
# File 'lib/inventory-1.0.rb', line 215

def unit_tests
  all_libs
end

#version_require ⇒ Object 



91
92
93
94
 
# File 'lib/inventory-1.0.rb', line 91

def version_require
  warn '%s#%s is deprecated and there’s no replacement' % [self.class, __method__]
  File.join(package_path, 'version')
end