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-1.0/) and [Inventory-Rake-Tasks-YARD](disu.se/software/inventory-rake-tasks-yard-1.0/), 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, 3){
  def authors
    Authors.new{
      author 'Nikolai Weibull', '[email protected]'
    }
  end

  def homepage
    'http://disu.se/software/inventory-1.0/'
  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



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

def major
  @major
end

#minor ⇒ Integer (readonly)

Returns The minor version atom of the package.

Returns:

  • (Integer) —

    The minor version atom of the package



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

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



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

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



295
296
297
 
# File 'lib/inventory-1.0.rb', line 295

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



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

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



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

def path
  @path
end

#srcdir ⇒ String (readonly)

Returns The top-level path of the package.

Returns:

  • (String) —

    The top-level path of the package



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

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



247
248
249
250
251
252
 
# File 'lib/inventory-1.0.rb', line 247

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:



199
200
201
 
# File 'lib/inventory-1.0.rb', line 199

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



223
224
225
 
# File 'lib/inventory-1.0.rb', line 223

def additional_unit_tests
  []
end

#all_libs ⇒ Array<String>

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

Returns:



205
206
207
 
# File 'lib/inventory-1.0.rb', line 205

def all_libs
  libs + additional_libs
end

#all_unit_tests ⇒ Array<String>

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

Returns:



229
230
231
 
# File 'lib/inventory-1.0.rb', line 229

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
127
 
# 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 %s' % [package, 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:



160
161
162
163
164
 
# File 'lib/inventory-1.0.rb', line 160

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



180
181
182
 
# File 'lib/inventory-1.0.rb', line 180

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:



257
258
259
 
# File 'lib/inventory-1.0.rb', line 257

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



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

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

#inspect ⇒ Object 



271
272
273
 
# File 'lib/inventory-1.0.rb', line 271

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:



211
212
213
 
# File 'lib/inventory-1.0.rb', line 211

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:



193
194
195
 
# File 'lib/inventory-1.0.rb', line 193

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



150
151
152
153
154
155
 
# File 'lib/inventory-1.0.rb', line 150

def licenses
  @licenses = Licenses.new(&Proc.new) if block_given?
  raise 'no licenses defined in inventory of %s %s' % [package, 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



174
175
176
 
# File 'lib/inventory-1.0.rb', line 174

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



186
187
188
 
# File 'lib/inventory-1.0.rb', line 186

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



168
169
170
 
# File 'lib/inventory-1.0.rb', line 168

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



241
242
243
 
# File 'lib/inventory-1.0.rb', line 241

def test_files
  unit_test_files
end

#to_a ⇒ Array<String>

Returns Whatever #files returns.

Returns:

  • (Array<String>) —

    Whatever #files returns



262
263
264
 
# File 'lib/inventory-1.0.rb', line 262

def to_a
  files
end

#to_s ⇒ String

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

Returns:



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

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



235
236
237
 
# File 'lib/inventory-1.0.rb', line 235

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



218
219
220
 
# File 'lib/inventory-1.0.rb', line 218

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