Class: Chef::Cookbook::Metadata

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

Overview

Chef::Cookbook::Metadata

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

Direct Known Subclasses

MinimalMetadata

Constant Summary collapse

NAME = 
'name'.freeze
DESCRIPTION = 
'description'.freeze
LONG_DESCRIPTION = 
'long_description'.freeze
MAINTAINER = 
'maintainer'.freeze
MAINTAINER_EMAIL = 
'maintainer_email'.freeze
LICENSE = 
'license'.freeze
PLATFORMS = 
'platforms'.freeze
DEPENDENCIES = 
'dependencies'.freeze
RECOMMENDATIONS = 
'recommendations'.freeze
SUGGESTIONS = 
'suggestions'.freeze
CONFLICTING = 
'conflicting'.freeze
PROVIDING = 
'providing'.freeze
REPLACING = 
'replacing'.freeze
ATTRIBUTES = 
'attributes'.freeze
GROUPINGS = 
'groupings'.freeze
RECIPES = 
'recipes'.freeze
VERSION = 
'version'.freeze
COMPARISON_FIELDS = 
[ :name, :description, :long_description, :maintainer,
:maintainer_email, :license, :platforms, :dependencies,
:recommendations, :suggestions, :conflicting, :providing,
:replacing, :attributes, :groupings, :recipes, :version]
VERSION_CONSTRAINTS = 
{:depends     => DEPENDENCIES,
:recommends  => RECOMMENDATIONS,
:suggests    => SUGGESTIONS,
:conflicts   => CONFLICTING,
:provides    => PROVIDING,
:replaces    => REPLACING }

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_COMPANY_NAME', maintainer_email = 'YOUR_EMAIL', license = 'none') ⇒ 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>



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/chef/cookbook/metadata.rb', line 94

def initialize(cookbook=nil, maintainer='YOUR_COMPANY_NAME', maintainer_email='YOUR_EMAIL', license='none')
  @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.



71
72
73
 
# File 'lib/chef/cookbook/metadata.rb', line 71

def attributes
  @attributes
end

#conflicting ⇒ Object (readonly)

Returns the value of attribute conflicting.



71
72
73
 
# File 'lib/chef/cookbook/metadata.rb', line 71

def conflicting
  @conflicting
end

#cookbook ⇒ Object (readonly)

Returns the value of attribute cookbook.



71
72
73
 
# File 'lib/chef/cookbook/metadata.rb', line 71

def cookbook
  @cookbook
end

#dependencies ⇒ Object (readonly)

Returns the value of attribute dependencies.



71
72
73
 
# File 'lib/chef/cookbook/metadata.rb', line 71

def dependencies
  @dependencies
end

#groupings ⇒ Object (readonly)

Returns the value of attribute groupings.



71
72
73
 
# File 'lib/chef/cookbook/metadata.rb', line 71

def groupings
  @groupings
end

#platforms ⇒ Object (readonly)

Returns the value of attribute platforms.



71
72
73
 
# File 'lib/chef/cookbook/metadata.rb', line 71

def platforms
  @platforms
end

#providing ⇒ Object (readonly)

Returns the value of attribute providing.



71
72
73
 
# File 'lib/chef/cookbook/metadata.rb', line 71

def providing
  @providing
end

#recipes ⇒ Object (readonly)

Returns the value of attribute recipes.



71
72
73
 
# File 'lib/chef/cookbook/metadata.rb', line 71

def recipes
  @recipes
end

#recommendations ⇒ Object (readonly)

Returns the value of attribute recommendations.



71
72
73
 
# File 'lib/chef/cookbook/metadata.rb', line 71

def recommendations
  @recommendations
end

#replacing ⇒ Object (readonly)

Returns the value of attribute replacing.



71
72
73
 
# File 'lib/chef/cookbook/metadata.rb', line 71

def replacing
  @replacing
end

#suggestions ⇒ Object (readonly)

Returns the value of attribute suggestions.



71
72
73
 
# File 'lib/chef/cookbook/metadata.rb', line 71

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



212
213
214
 
# File 'lib/chef/cookbook/metadata.rb', line 212

def version
  @version
end

Class Method Details

.from_hash(o) ⇒ Object 



449
450
451
452
453
 
# File 'lib/chef/cookbook/metadata.rb', line 449

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

.from_json(string) ⇒ Object 



476
477
478
479
 
# File 'lib/chef/cookbook/metadata.rb', line 476

def self.from_json(string)
  o = Chef::JSONCompat.from_json(string)
  self.from_hash(o)
end

.validate_json(json_str) ⇒ Object 



481
482
483
484
485
486
487
488
489
490
491
492
 
# File 'lib/chef/cookbook/metadata.rb', line 481

def self.validate_json(json_str)
  o = Chef::JSONCompat.from_json(json_str)
  metadata = new()
  VERSION_CONSTRAINTS.each do |method_name, hash_key|
    if constraints = o[hash_key]
     constraints.each do |cb_name, constraints|
       metadata.send(method_name, cb_name, *Array(constraints))
     end
    end
  end
  true
end

Instance Method Details

#==(other) ⇒ Object 



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

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

#attribute(name, options) ⇒ Object

Adds an attribute )hat 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



388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
 
# File 'lib/chef/cookbook/metadata.rb', line 388

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, *version_args) ⇒ Object

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

Parameters

cookbook<String>

The cookbook

version<String>

A version constraint of the form “OP VERSION”,

where OP is one of < <= = > >= ~> and VERSION has the form x.y.z or x.y.

Returns

versions<Array>

Returns the list of versions for the platform



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

def conflicts(cookbook, *version_args)
  version = new_args_format(:conflicts, cookbook, version_args)
  validate_version_constraint(:conflicts, cookbook, version)
  @conflicting[cookbook] = version
  @conflicting[cookbook]
end

#depends(cookbook, *version_args) ⇒ Object

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

Parameters

cookbook<String>

The cookbook

version<String>

A version constraint of the form “OP VERSION”,

where OP is one of < <= = > >= ~> and VERSION has the form x.y.z or x.y.

Returns

versions<Array>

Returns the list of versions for the platform



262
263
264
265
266
267
 
# File 'lib/chef/cookbook/metadata.rb', line 262

def depends(cookbook, *version_args)
  version = new_args_format(:depends, cookbook, version_args)
  validate_version_constraint(:depends, cookbook, version)
  @dependencies[cookbook] = version
  @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



181
182
183
184
185
186
187
 
# File 'lib/chef/cookbook/metadata.rb', line 181

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

#from_hash(o) ⇒ Object 



455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
 
# File 'lib/chef/cookbook/metadata.rb', line 455

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                 = handle_deprecated_constraints(o[DEPENDENCIES]) if o.has_key?(DEPENDENCIES)
  @recommendations              = handle_deprecated_constraints(o[RECOMMENDATIONS]) if o.has_key?(RECOMMENDATIONS)
  @suggestions                  = handle_deprecated_constraints(o[SUGGESTIONS]) if o.has_key?(SUGGESTIONS)
  @conflicting                  = handle_deprecated_constraints(o[CONFLICTING]) if o.has_key?(CONFLICTING)
  @providing                    = o[PROVIDING] if o.has_key?(PROVIDING)
  @replacing                    = handle_deprecated_constraints(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 



494
495
496
497
 
# File 'lib/chef/cookbook/metadata.rb', line 494

def from_json(string)
  o = Chef::JSONCompat.from_json(string)
  from_hash(o)
end

#grouping(name, options) ⇒ Object 



411
412
413
414
415
416
417
418
419
420
421
 
# File 'lib/chef/cookbook/metadata.rb', line 411

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



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

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



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

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.



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

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.



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

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.



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

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

#provides(cookbook, *version_args) ⇒ 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

version<String>

A version constraint of the form “OP VERSION”,

where OP is one of < <= = > >= ~> and VERSION has the form x.y.z or x.y.

Returns

versions<Array>

Returns the list of versions for the platform



334
335
336
337
338
339
 
# File 'lib/chef/cookbook/metadata.rb', line 334

def provides(cookbook, *version_args)
  version = new_args_format(:provides, cookbook, version_args)
  validate_version_constraint(:provides, cookbook, version)
  @providing[cookbook] = version
  @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



365
366
367
 
# File 'lib/chef/cookbook/metadata.rb', line 365

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

#recommends(cookbook, *version_args) ⇒ Object

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

Parameters

cookbook<String>

The cookbook

version<String>

A version constraint of the form “OP VERSION”,

where OP is one of < <= = > >= ~> and VERSION has the form x.y.z or x.y.

Returns

versions<Array>

Returns the list of versions for the platform



279
280
281
282
283
284
 
# File 'lib/chef/cookbook/metadata.rb', line 279

def recommends(cookbook, *version_args)
  version = new_args_format(:recommends, cookbook,  version_args)
  validate_version_constraint(:recommends, cookbook, version)
  @recommendations[cookbook] = version
  @recommendations[cookbook]
end

#replaces(cookbook, *version_args) ⇒ Object

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

Parameters

cookbook<String>

The cookbook we replace

version<String>

A version constraint of the form “OP VERSION”,

where OP is one of < <= = > >= ~> and VERSION has the form x.y.z or x.y.

Returns

versions<Array>

Returns the list of versions for the platform



350
351
352
353
354
355
 
# File 'lib/chef/cookbook/metadata.rb', line 350

def replaces(cookbook, *version_args)
  version = new_args_format(:replaces, cookbook, version_args)
  validate_version_constraint(:replaces, cookbook, version)
  @replacing[cookbook] = version
  @replacing[cookbook]
end

#suggests(cookbook, *version_args) ⇒ Object

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

Parameters

cookbook<String>

The cookbook

version<String>

A version constraint of the form “OP VERSION”,

where OP is one of < <= = > >= ~> and VERSION has the formx.y.z or x.y.

Returns

versions<Array>

Returns the list of versions for the platform



296
297
298
299
300
301
 
# File 'lib/chef/cookbook/metadata.rb', line 296

def suggests(cookbook, *version_args)
  version = new_args_format(:suggests, cookbook, version_args)
  validate_version_constraint(:suggests, cookbook, version)
  @suggestions[cookbook] = version
  @suggestions[cookbook]
end

#supports(platform, *version_args) ⇒ Object

Adds a supported platform, with version checking strings.

Parameters

platform<String>,<Symbol>

The platform (like :ubuntu or :mac_os_x)

version<String>

A version constraint of the form “OP VERSION”,

where OP is one of < <= = > >= ~> and VERSION has the form x.y.z or x.y.

Returns

versions<Array>

Returns the list of versions for the platform



245
246
247
248
249
250
 
# File 'lib/chef/cookbook/metadata.rb', line 245

def supports(platform, *version_args)
  version = new_args_format(:supports, platform, version_args)
  validate_version_constraint(:supports, platform, version)
  @platforms[platform] = version
  @platforms[platform]
end

#to_hash ⇒ Object 



423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
 
# File 'lib/chef/cookbook/metadata.rb', line 423

def to_hash
  {
    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
  }
end

#to_json(*a) ⇒ Object 



445
446
447
 
# File 'lib/chef/cookbook/metadata.rb', line 445

def to_json(*a)
  self.to_hash.to_json(*a)
end