Class: Chef::Cookbook::Metadata

Inherits:
Object
  • Object
show all
Includes:
Mixin::CheckHelper, Mixin::FromFile, Mixin::ParamsValidate
Defined in:
lib/chef/cookbook/metadata.rb,
lib/chef/cookbook/metadata/version.rb

Overview

Chef::Cookbook::Metadata

Chef::Cookbook::Metadata provides a convenient DSL for declaring metadata about Chef Cookbooks.

Defined Under Namespace

Classes: Version

Constant Summary collapse

COMPARISON_FIELDS = 
[ :name, :description, :long_description, :maintainer,
:maintainer_email, :license, :platforms, :dependencies,
:recommendations, :suggestions, :conflicting, :providing,
:replacing, :attributes, :groupings, :recipes, :version]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Mixin::FromFile

#class_from_file, #from_file

Methods included from Mixin::ParamsValidate

#set_or_return, #validate

Methods included from Mixin::CheckHelper

#set_if_args

Constructor Details

#initialize(cookbook = nil, maintainer = 'Your Name', maintainer_email = '[email protected]', license = 'Apache v2.0') ⇒ Metadata

Builds a new Chef::Cookbook::Metadata object.

Parameters

cookbook<String>

An optional cookbook object

maintainer<String>

An optional maintainer

maintainer_email<String>

An optional maintainer email

license<String>::An optional license. Default is Apache v2.0

Returns

metadata<Chef::Cookbook::Metadata>



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/chef/cookbook/metadata.rb', line 65

def initialize(cookbook=nil, maintainer='Your Name', maintainer_email='[email protected]', license='Apache v2.0')
  @cookbook = cookbook
  @name = cookbook ? cookbook.name : "" 
  @long_description = ""
  self.maintainer(maintainer)
  self.maintainer_email(maintainer_email)
  self.license(license)
  self.description('A fabulous new cookbook')
  @platforms = Mash.new
  @dependencies = Mash.new
  @recommendations = Mash.new
  @suggestions = Mash.new
  @conflicting = Mash.new
  @providing = Mash.new
  @replacing = Mash.new
  @attributes = Mash.new
  @groupings = Mash.new
  @recipes = Mash.new
  @version = Version.new "0.0.0"
  if cookbook
    @recipes = cookbook.fully_qualified_recipe_names.inject({}) do |r, e| 
      e = self.name if e =~ /::default$/ 
      r[e] = ""
      self.provides e
      r
    end
  end
end

Instance Attribute Details

#attributes ⇒ Object (readonly)

Returns the value of attribute attributes.



42
43
44
 
# File 'lib/chef/cookbook/metadata.rb', line 42

def attributes
  @attributes
end

#conflicting ⇒ Object (readonly)

Returns the value of attribute conflicting.



42
43
44
 
# File 'lib/chef/cookbook/metadata.rb', line 42

def conflicting
  @conflicting
end

#cookbook ⇒ Object (readonly)

Returns the value of attribute cookbook.



42
43
44
 
# File 'lib/chef/cookbook/metadata.rb', line 42

def cookbook
  @cookbook
end

#dependencies ⇒ Object (readonly)

Returns the value of attribute dependencies.



42
43
44
 
# File 'lib/chef/cookbook/metadata.rb', line 42

def dependencies
  @dependencies
end

#groupings ⇒ Object (readonly)

Returns the value of attribute groupings.



42
43
44
 
# File 'lib/chef/cookbook/metadata.rb', line 42

def groupings
  @groupings
end

#platforms ⇒ Object (readonly)

Returns the value of attribute platforms.



42
43
44
 
# File 'lib/chef/cookbook/metadata.rb', line 42

def platforms
  @platforms
end

#providing ⇒ Object (readonly)

Returns the value of attribute providing.



42
43
44
 
# File 'lib/chef/cookbook/metadata.rb', line 42

def providing
  @providing
end

#recipes ⇒ Object (readonly)

Returns the value of attribute recipes.



42
43
44
 
# File 'lib/chef/cookbook/metadata.rb', line 42

def recipes
  @recipes
end

#recommendations ⇒ Object (readonly)

Returns the value of attribute recommendations.



42
43
44
 
# File 'lib/chef/cookbook/metadata.rb', line 42

def recommendations
  @recommendations
end

#replacing ⇒ Object (readonly)

Returns the value of attribute replacing.



42
43
44
 
# File 'lib/chef/cookbook/metadata.rb', line 42

def replacing
  @replacing
end

#suggestions ⇒ Object (readonly)

Returns the value of attribute suggestions.



42
43
44
 
# File 'lib/chef/cookbook/metadata.rb', line 42

def suggestions
  @suggestions
end

#version(arg = nil) ⇒ Object (readonly)

Sets the current cookbook version, or returns it. Can be two or three digits, seperated by dots. ie: ‘2.1’, ‘1.5.4’ or ‘0.9’.

Parameters

version<String>

The curent version, as a string

Returns

version<String>

Returns the current version



183
184
185
 
# File 'lib/chef/cookbook/metadata.rb', line 183

def version
  @version
end

Class Method Details

.from_hash(o) ⇒ Object 



405
406
407
408
409
 
# File 'lib/chef/cookbook/metadata.rb', line 405

def self.from_hash(o)
  cm = self.new() 
  cm.from_hash(o)
  cm
end

.from_json(string) ⇒ Object 



432
433
434
435
 
# File 'lib/chef/cookbook/metadata.rb', line 432

def self.from_json(string)
  o = JSON.parse(string)
  self.from_hash(o)
end

Instance Method Details

#==(other) ⇒ Object 



94
95
96
97
98
 
# File 'lib/chef/cookbook/metadata.rb', line 94

def ==(other)
  COMPARISON_FIELDS.inject(true) do |equal_so_far, field|
    equal_so_far && other.respond_to?(field) && (other.send(field) == send(field))
  end
end

#_check_version_expression(version_string) ⇒ Object 



374
375
376
377
378
379
380
 
# File 'lib/chef/cookbook/metadata.rb', line 374

def _check_version_expression(version_string)
  if version_string =~ /^(>>|>=|=|<=|<<) (.+)$/
    [ $1, $2 ]
  else
    raise ArgumentError, "Version expression #{version_string} is invalid!"
  end
end

#attribute(name, options) ⇒ Object

Adds an attribute that a user needs to configure for this cookbook. Takes a name (with the / notation for a nested attribute), followed by any of these options

display_name<String>:: What a UI should show for this attribute
description<String>:: A hint as to what this attr is for
choice<Array>:: An array of choices to present to the user.
calculated<Boolean>:: If true, the default value is calculated by the recipe and cannot be displayed.
type<String>:: "string" or "array" - default is "string"  ("hash" is supported for backwards compatibility)
required<String>:: Whether this attr is 'required', 'recommended' or 'optional' - default 'optional' (true/false values also supported for backwards compatibility)
recipes<Array>:: An array of recipes which need this attr set.
default<String>,<Array>,<Hash>:: The default value

Parameters

name<String>

The name of the attribute (‘foo’, or ‘apache2/log_dir’)

options<Hash>

The description of the options

Returns

options<Hash>

Returns the current options hash



339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
 
# File 'lib/chef/cookbook/metadata.rb', line 339

def attribute(name, options)
  validate(
    options,
    {
      :display_name => { :kind_of => String },
      :description => { :kind_of => String },
      :choice => { :kind_of => [ Array ], :default => [] },
      :calculated => { :equal_to => [ true, false ], :default => false },
      :type => { :equal_to => [ "string", "array", "hash", "symbol" ], :default => "string" },
      :required => { :equal_to => [ "required", "recommended", "optional", true, false ], :default => "optional" },
      :recipes => { :kind_of => [ Array ], :default => [] },
      :default => { :kind_of => [ String, Array, Hash ] }
    }
  )
  options[:required] = remap_required_attribute(options[:required]) unless options[:required].nil?
  validate_string_array(options[:choice])
  validate_calculated_default_rule(options)
  validate_choice_default_rule(options)

  @attributes[name] = options 
  @attributes[name]
end

#conflicts(cookbook, *versions) ⇒ Object

Adds a conflict for another cookbook, with version checking strings.

Parameters

cookbook<String>

The cookbook

*versions<String>

A list of versions matching << <= = >= >> followed by a version.

Returns

versions<Array>

Returns the list of versions for the platform



270
271
272
273
274
 
# File 'lib/chef/cookbook/metadata.rb', line 270

def conflicts(cookbook, *versions)
  versions.each { |v| _check_version_expression(v) }
  @conflicting[cookbook] = versions
  @conflicting[cookbook] 
end

#depends(cookbook, *versions) ⇒ Object

Adds a dependency on another cookbook, with version checking strings.

Parameters

cookbook<String>

The cookbook

*versions<String>

A list of versions matching << <= = >= >> followed by a version.

Returns

versions<Array>

Returns the list of versions for the platform



228
229
230
231
232
 
# File 'lib/chef/cookbook/metadata.rb', line 228

def depends(cookbook, *versions)
  versions.each { |v| _check_version_expression(v) }
  @dependencies[cookbook] = versions
  @dependencies[cookbook]
end

#description(arg = nil) ⇒ Object

Sets the current description, or returns it. Should be short - one line only!

Parameters

description<String>

The new description

Returns

description<String>

Returns the description



152
153
154
155
156
157
158
 
# File 'lib/chef/cookbook/metadata.rb', line 152

def description(arg=nil)
  set_or_return(
    :description,
    arg,
    :kind_of => [ String ]
  )
end

#from_hash(o) ⇒ Object 



411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
 
# File 'lib/chef/cookbook/metadata.rb', line 411

def from_hash(o)
  @name                         = o['name'] if o.has_key?('name')
  @description                  = o['description'] if o.has_key?('description')
  @long_description             = o['long_description'] if o.has_key?('long_description')
  @maintainer                   = o['maintainer'] if o.has_key?('maintainer')
  @maintainer_email             = o['maintainer_email'] if o.has_key?('maintainer_email')
  @license                      = o['license'] if o.has_key?('license')
  @platforms                    = o['platforms'] if o.has_key?('platforms')
  @dependencies                 = o['dependencies'] if o.has_key?('dependencies')
  @recommendations              = o['recommendations'] if o.has_key?('recommendations')
  @suggestions                  = o['suggestions'] if o.has_key?('suggestions')
  @conflicting                  = o['conflicting'] if o.has_key?('conflicting')
  @providing                    = o['providing'] if o.has_key?('providing')
  @replacing                    = o['replacing'] if o.has_key?('replacing')
  @attributes                   = o['attributes'] if o.has_key?('attributes')
  @groupings                    = o['groupings'] if o.has_key?('groupings')
  @recipes                      = o['recipes'] if o.has_key?('recipes')
  @version                      = o['version'] if o.has_key?('version')
  self
end

#from_json(string) ⇒ Object 



437
438
439
440
 
# File 'lib/chef/cookbook/metadata.rb', line 437

def from_json(string)
  o = JSON.parse(string)
  from_hash(o)
end

#grouping(name, options) ⇒ Object 



362
363
364
365
366
367
368
369
370
371
372
 
# File 'lib/chef/cookbook/metadata.rb', line 362

def grouping(name, options)
  validate(
    options,
    {
      :title => { :kind_of => String },
      :description => { :kind_of => String }
    }
  )
  @groupings[name] = options 
  @groupings[name]
end

#license(arg = nil) ⇒ Object

Sets the current license, or returns it.

Parameters

license<String>

The current license.

Returns

license<String>

Returns the current license



137
138
139
140
141
142
143
 
# File 'lib/chef/cookbook/metadata.rb', line 137

def license(arg=nil)
  set_or_return(
    :license,
    arg,
    :kind_of => [ String ]
  )
end

#long_description(arg = nil) ⇒ Object

Sets the current long description, or returns it. Might come from a README, say.

Parameters

long_description<String>

The new long description

Returns

long_description<String>

Returns the long description



167
168
169
170
171
172
173
 
# File 'lib/chef/cookbook/metadata.rb', line 167

def long_description(arg=nil)
  set_or_return(
    :long_description,
    arg,
    :kind_of => [ String ]
  )
end

#maintainer(arg = nil) ⇒ Object

Sets the cookbooks maintainer, or returns it.

Parameters

maintainer<String>

The maintainers name

Returns

maintainer<String>

Returns the current maintainer.



107
108
109
110
111
112
113
 
# File 'lib/chef/cookbook/metadata.rb', line 107

def maintainer(arg=nil)
  set_or_return(
    :maintainer,
    arg,
    :kind_of => [ String ]
  )
end

#maintainer_email(arg = nil) ⇒ Object

Sets the maintainers email address, or returns it.

Parameters

maintainer_email<String>

The maintainers email address

Returns

maintainer_email<String>

Returns the current maintainer email.



122
123
124
125
126
127
128
 
# File 'lib/chef/cookbook/metadata.rb', line 122

def maintainer_email(arg=nil)
  set_or_return(
    :maintainer_email,
    arg,
    :kind_of => [ String ]
  )
end

#name(arg = nil) ⇒ Object

Sets the name of the cookbook, or returns it.

Parameters

name<String>

The curent cookbook name.

Returns

name<String>

Returns the current cookbook name.



198
199
200
201
202
203
204
 
# File 'lib/chef/cookbook/metadata.rb', line 198

def name(arg=nil)
  set_or_return(
    :name,
    arg,
    :kind_of => [ String ]
  )
end

#provides(cookbook, *versions) ⇒ Object

Adds a recipe, definition, or resource provided by this cookbook.

Recipes are specified as normal Definitions are followed by (), and can include :params for prototyping Resources are the stringified version (service)

Parameters

recipe, definition, resource<String>

The thing we provide

*versions<String>

A list of versions matching << <= = >= >> followed by a version.

Returns

versions<Array>

Returns the list of versions for the platform



288
289
290
291
292
 
# File 'lib/chef/cookbook/metadata.rb', line 288

def provides(cookbook, *versions)
  versions.each { |v| _check_version_expression(v) }
  @providing[cookbook] = versions
  @providing[cookbook] 
end

#recipe(name, description) ⇒ Object

Adds a description for a recipe.

Parameters

recipe<String>

The recipe

description<String>

The description of the recipe

Returns

description<String>

Returns the current description



316
317
318
 
# File 'lib/chef/cookbook/metadata.rb', line 316

def recipe(name, description)
  @recipes[name] = description 
end

#recommends(cookbook, *versions) ⇒ Object

Adds a recommendation for another cookbook, with version checking strings.

Parameters

cookbook<String>

The cookbook

*versions<String>

A list of versions matching << <= = >= >> followed by a version.

Returns

versions<Array>

Returns the list of versions for the platform



242
243
244
245
246
 
# File 'lib/chef/cookbook/metadata.rb', line 242

def recommends(cookbook, *versions)
  versions.each { |v| _check_version_expression(v) }
  @recommendations[cookbook] = versions
  @recommendations[cookbook]
end

#replaces(cookbook, *versions) ⇒ Object

Adds a cookbook that is replaced by this one, with version checking strings.

Parameters

cookbook<String>

The cookbook we replace

*versions<String>

A list of versions matching << <= = >= >> followed by a version.

Returns

versions<Array>

Returns the list of versions for the platform



302
303
304
305
306
 
# File 'lib/chef/cookbook/metadata.rb', line 302

def replaces(cookbook, *versions)
  versions.each { |v| _check_version_expression(v) }
  @replacing[cookbook] = versions
  @replacing[cookbook] 
end

#suggests(cookbook, *versions) ⇒ Object

Adds a suggestion for another cookbook, with version checking strings.

Parameters

cookbook<String>

The cookbook

*versions<String>

A list of versions matching << <= = >= >> followed by a version.

Returns

versions<Array>

Returns the list of versions for the platform



256
257
258
259
260
 
# File 'lib/chef/cookbook/metadata.rb', line 256

def suggests(cookbook, *versions)
  versions.each { |v| _check_version_expression(v) }
  @suggestions[cookbook] = versions
  @suggestions[cookbook] 
end

#supports(platform, *versions) ⇒ Object

Adds a supported platform, with version checking strings.

Parameters

platform<String>,<Symbol>

The platform (like :ubuntu or :mac_os_x)

*versions<String>

A list of versions matching << <= = >= >> followed by a version.

Returns

versions<Array>

Returns the list of versions for the platform



214
215
216
217
218
 
# File 'lib/chef/cookbook/metadata.rb', line 214

def supports(platform, *versions)
  versions.each { |v| _check_version_expression(v) }
  @platforms[platform] = versions
  @platforms[platform]
end

#to_json(*a) ⇒ Object 



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
 
# File 'lib/chef/cookbook/metadata.rb', line 382

def to_json(*a)
  result = {
    :name             => self.name,
    :description      => self.description,
    :long_description => self.long_description,
    :maintainer       => self.maintainer,
    :maintainer_email => self.maintainer_email,
    :license          => self.license,
    :platforms        => self.platforms,
    :dependencies     => self.dependencies,
    :recommendations  => self.recommendations,
    :suggestions      => self.suggestions,
    :conflicting      => self.conflicting,
    :providing        => self.providing,
    :replacing        => self.replacing,
    :attributes       => self.attributes,
    :groupings        => self.groupings,
    :recipes          => self.recipes,
    :version          => self.version
  }
  result.to_json(*a)
end