poise 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 139be873d0ca15732ed1e63cda3c64fb5f66df07
-  data.tar.gz: 5c320b061767f73716e12d14cd4435d2ac454ade
+  metadata.gz: a493c9d1d4c7f307cfa38c39d5e9de3d7242c3b6
+  data.tar.gz: 6b700222a7634a9e301b55dc3be8a41d61a15e04
 SHA512:
-  metadata.gz: 3cad8094aa339ae2da67533a14be99ad2ad855f7f9e1896540db99a23a129c714e1cc906e89fa1c46be36a417bc5dfa4b24cf7882d51cfe73b881d1bfb98dabf
-  data.tar.gz: c924334c534a43fc017a2b2437479ff8b1e73460485df2559ebceb750178ec204219a6075185c2194a214b75cf061aeb7f9e714cee8845ee47a6e678fda28915
+  metadata.gz: 3d90977a6a46d00298dddf93479023d27364aa73049e89ef97c4671af27847b695de39ac5af04e962d449818f5fd556ec4cbf168ac5f275c88d35e91c711f722
+  data.tar.gz: 81c4de3bb755d2d8c5c2f7e6837eea4f16fab1c942b6d60d6ac611fb8f0867c3ec07153c58156402f00331b4b38e0e3671d9fce3207ec408f737b6a5efa25ff6

data/.travis.yml

@@ -22,4 +22,5 @@ gemfile:
 - test/gemfiles/chef-12.0.gemfile
 - test/gemfiles/chef-12.1.gemfile
 - test/gemfiles/chef-12.2.gemfile
+- test/gemfiles/chef-12.3.gemfile
 - test/gemfiles/master.gemfile

data/Berksfile.lock

@@ -5,6 +5,6 @@ DEPENDENCIES
     path: test/cookbooks/poise_test
 
 GRAPH
-  poise (2.0.0)
+  poise (2.0.2)
   poise_test (0.0.0)
     poise (>= 0.0.0)

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v2.1.0
+
+* Compatibility with Chef 12.4.
+* Add `#property` as an alias for `#attribute` in resources. This provides
+  forward compatibility with future versions of Chef.
+* Freeze default resource attribute values. **This may break your code**,
+  however this is not a major release because any code broken by this change
+  was itself already a bug.
+
 ## v2.0.1
 
 * Make the ChefspecHelpers helper a no-op if chefspec is not already loaded.

data/README.md

@@ -21,35 +21,51 @@ the resource, which is in turn based on the class name. This means that the file
 An example of a simple shell to start from:
 
 ```ruby
-class Chef
-  class Resource::MyApp < Resource
-    include Poise
+require 'poise'
+require 'chef/resource'
+require 'chef/provider'
 
+module MyApp
+  class Resource < Chef::Resource
+    include Poise
+    provides(:my_app)
     actions(:enable)
 
     attribute(:path, kind_of: String)
-    ... # Other attribute definitions
+    # Other attribute definitions.
   end
 
-  class Provider::MyApp < Provider
+  class Provider < Chef::Provider
     include Poise
+    provides(:my_app)
 
     def action_enable
-      converge_by("enable resource #{new_resource.name}") do
-        notifying_block do
-          ... # Normal Chef recipe code goes here
-        end
+      notifying_block do
+        ... # Normal Chef recipe code goes here
       end
     end
   end
 end
 ```
 
-Starting from the top, first we declare the resource class, which inherits from
-`Chef::Resource`. This is similar to the `resources/` file in an LWRP, and a similar DSL can be used. In order to load the helpers into the class, we
-include the `Poise` mixin. Then we use the familiar DSL, though with a few additions we'll cover later.
-
-Then we declare the provider class, again similar to the `providers/` file in an LWRP. We include the `Poise` mixin again to get access to all the helpers. Rather than use the `action :enable do ... end` DSL from LWRPs, we just define the action method directly, and use the `converge_by` method to provide a description of what the action does. The implementation of action comes from a block of recipe code wrapped with `notifying_block` to capture changes in much the same way as `use_inline_resources`, see below for more information about all the features of `notifying_block`.
+Starting from the top, first we require the libraries we will be using. Then we
+create a module to hold our resource and provider. If your cookbook declares
+multiple resources and/or providers, you might want additional nesting here.
+Then we declare the resource class, which inherits from `Chef::Resource`. This
+is similar to the `resources/` file in an LWRP, and a similar DSL can be used.
+We then include the `Poise` mixin to load our helpers, and then call
+`provides(:my_app)` to tell Chef this class will implement the `my_app`
+resource. Then we use the familiar DSL, though with a few additions we'll cover
+later.
+
+Then we declare the provider class, again similar to the `providers/` file in an
+LWRP. We include the `Poise` mixin again to get access to all the helpers and
+call `provides()` to tell Chef what provider this is. Rather than use the
+`action :enable do ... end` DSL from LWRPs, we just define the action method
+directly. The implementation of action comes from a block of recipe code
+wrapped with `notifying_block` to capture changes in much the same way as
+`use_inline_resources`, see below for more information about all the features of
+`notifying_block`.
 
 We can then use this resource like any other Chef resource:
 
@@ -177,6 +193,16 @@ end
 
 This will be converted to `{key1: 'value1', key2: 'value2'}`. You can also pass a Hash to an option collector attribute just as you would with a normal attribute.
 
+## Upgrading from Poise 1.x
+
+The biggest change when upgrading from Poise 1.0 is that the mixin is no longer
+loaded automatically. You must add `require 'poise'` to your code is you want to
+load it, as you would with normal Ruby code outside of Chef. It is also highly
+recommended to add `provides(:name)` calls to your resources and providers, this
+will be required in Chef 13 and will display a deprecation warning if you do
+not. This also means you can move your code out of the `Chef` module namespace
+and instead declare it in your own namespace. An example of this is shown above.
+
 ## Sponsors
 
 The Poise test server infrastructure is generously sponsored by [Rackspace](https://rackspace.com/). Thanks Rackspace!

data/lib/poise/helpers/lazy_default.rb

@@ -14,6 +14,8 @@
 # limitations under the License.
 #
 
+require 'chef/version'
+
 
 module Poise
   module Helpers
@@ -29,11 +31,21 @@ module Poise
     #     attribute(:path, default: lazy { name + '_temp' })
     #   end
     module LazyDefault
+      # Check if this version of Chef already supports lazy defaults. This is
+      # true for Chef 12.5+.
+      #
+      # @since 2.0.3
+      # @api private
+      # @return [Boolean]
+      def self.needs_polyfill?
+        @needs_polyfill ||= Gem::Requirement.new('< 12.5.pre').satisfied_by?(Gem::Version.new(Chef::VERSION))
+      end
+
       # Override the default set_or_return to support lazy evaluation of the
       # default value. This only actually matters when it is called from a class
       # level context via #attributes.
       def set_or_return(symbol, arg, validation)
-        if validation && validation[:default].is_a?(Chef::DelayedEvaluator)
+        if LazyDefault.needs_polyfill? && validation && validation[:default].is_a?(Chef::DelayedEvaluator)
           validation = validation.dup
           validation[:default] = instance_eval(&validation[:default])
         end

data/lib/poise/helpers/lwrp_polyfill.rb

@@ -14,6 +14,8 @@
 # limitations under the License.
 #
 
+require 'chef/resource'
+
 require 'poise/utils/resource_provider_mixin'
 
 
@@ -30,35 +32,83 @@ module Poise
       module Resource
         def initialize(*args)
           super
-          # Try to not stomp on stuff if already set in a parent
+          # Try to not stomp on stuff if already set in a parent.
           @action = self.class.default_action if @action == :nothing
           (@allowed_actions << self.class.actions).flatten!.uniq!
         end
 
-        # @!classmethods
         module ClassMethods
+          # @overload default_action()
+          #   Get the default action for this resource class. If no explicit
+          #   default is set, the first action in the list will be used.
+          #   @see #actions
+          #   @return [Symbol]
+          # @overload default_action(name)
+          #   Set the default action for this resource class. If this action is
+          #   not already allowed, it will be added.
+          #   @note It is idiomatic to use {#actions} instead, with the first
+          #     action specified being the default.
+          #   @param name [Symbol] Name of the action.
+          #   @return [Symbol]
+          #   @example
+          #     class MyApp < Chef::Resource
+          #       include Poise
+          #       default_action(:install)
+          #     end
           def default_action(name=nil)
             if name
               @default_action = name
               actions(name)
             end
-            @default_action || ( respond_to?(:superclass) && superclass.respond_to?(:default_action) && superclass.default_action ) || actions.first || :nothing
+            @default_action || ( respond_to?(:superclass) && superclass != Chef::Resource && superclass.respond_to?(:default_action) && superclass.default_action ) || actions.first || :nothing
           end
 
+          # @overload actions()
+          #   Get all actions allowed for this resource class. This includes
+          #   any actions allowed on parent classes.
+          #   @return [Array<Symbol>]
+          # @overload actions(*names)
+          #   Set actions as allowed for this resource class. These must
+          #   correspond with action methods in the provider class(es).
+          #   @param names [Array<Symbol>] One or more actions to set.
+          #   @return [Array<Symbol>]
+          #   @example
+          #     class MyApp < Chef::Resource
+          #       include Poise
+          #       actions(:install, :uninstall)
+          #     end
           def actions(*names)
-            @actions ||= ( respond_to?(:superclass) && superclass.respond_to?(:actions) ? superclass.actions.dup : [] )
+            @actions ||= ( respond_to?(:superclass) && superclass.respond_to?(:actions) && superclass.actions.dup ) || ( respond_to?(:superclass) && superclass != Chef::Resource && superclass.respond_to?(:allowed_actions) && superclass.allowed_actions.dup ) || []
             (@actions << names).flatten!.uniq!
             @actions
           end
 
-          def attribute(name, opts)
-            # Ruby 1.8 can go to hell
+          # Create a resource property (née attribute) on this resource class.
+          # This follows the same usage as the helper of the same name in Chef
+          # LWRPs.
+          #
+          # @param name [Symbol] Name of the property.
+          # @param opts [Hash<Symbol, Object>] Validation options and flags.
+          # @return [void]
+          # @example
+          #   class MyApp < Chef::Resource
+          #     include Poise
+          #     attribute(:path, name_attribute: true)
+          #     attribute(:port, kind_of: Integer, default: 8080)
+          #   end
+          def attribute(name, opts={})
+            # Freeze the default value. This is done upstream too in Chef 12.5+.
+            opts[:default].freeze if opts && opts[:default]
+            # Ruby 1.8 can go to hell.
             define_method(name) do |arg=nil, &block|
-              arg = block if arg.nil? # Try to allow passing either
+              arg = block if arg.nil? # Try to allow passing either.
               set_or_return(name, arg, opts)
             end
           end
 
+          # For forward compat with Chef 12.5+.
+          alias_method :property, :attribute
+
           def included(klass)
             super
             klass.extend(ClassMethods)

data/lib/poise/helpers/resource_name.rb

@@ -72,7 +72,9 @@ module Poise
         # @param auto [Boolean] Try to auto-detect based on class name.
         # @return [Symbol]
         def resource_name(auto=true)
-          return @provides_name if @provides_name
+          # In 12.4+ we need to proxy through the super class for setting.
+          return super(auto) if defined?(super) && (auto.is_a?(Symbol) || auto.is_a?(String))
+          return @provides_name unless auto
           @provides_name || if name && name.start_with?('Chef::Resource')
             Chef::Mixin::ConvertToClassName.convert_to_snake_case(name, 'Chef::Resource').to_sym
           elsif name

data/lib/poise/helpers/subresources/default_containers.rb

@@ -65,6 +65,8 @@ module Poise
         # @param run_context [Chef::RunContext] Context of the current run.
         # @return [Array<Chef::Resource>]
         def self.containers(run_context)
+          # For test cases where nil gets used sometimes.
+          return [] unless run_context && run_context.node && run_context.node.run_state
           run_context.node.run_state[:poise_default_containers] ||= []
         end
       end

data/lib/poise/resource.rb

@@ -34,7 +34,7 @@ module Poise
   module Resource
     include Poise::Helpers::ChefspecMatchers
     include Poise::Helpers::DefinedIn
-    include Poise::Helpers::LazyDefault
+    include Poise::Helpers::LazyDefault if Poise::Helpers::LazyDefault.needs_polyfill?
     include Poise::Helpers::LWRPPolyfill
     include Poise::Helpers::OptionCollector
     include Poise::Helpers::ResourceName

data/lib/poise/version.rb

@@ -16,5 +16,5 @@
 
 
 module Poise
-  VERSION = '2.0.1'
+  VERSION = '2.1.0'
 end

data/test/gemfiles/chef-12.3.gemfile

@@ -0,0 +1,19 @@
+#
+# Copyright 2015, Noah Kantrowitz
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+eval_gemfile File.expand_path('../../../Gemfile', __FILE__)
+
+gem 'chef', '~> 12.3.0'

data/test/spec/helpers/lazy_default_spec.rb

@@ -39,7 +39,7 @@ describe Poise::Helpers::LazyDefault do
     end
 
     it { is_expected.to run_poise_test('test').with(value: 'value') }
-  end
+  end # /context with an explicit value
 
   context 'in a subclass' do
     resource(:poise_sub, parent: :poise_test)
@@ -49,7 +49,7 @@ describe Poise::Helpers::LazyDefault do
     end
 
     it { is_expected.to run_poise_test('test').with(value: 'test_lazy') }
-  end
+  end # /context in a subclass
 
   context 'with an external global' do
     resource(:poise_test) do
@@ -70,5 +70,21 @@ describe Poise::Helpers::LazyDefault do
       LAZY_DEFAULT_GLOBAL[0] = 42
       is_expected.to run_poise_test('test').with(value: 0)
     end
-  end
+  end # /context with an external global
+
+  context 'with a mutable value' do
+    resource(:poise_test) do
+      include Poise::Helpers::LWRPPolyfill
+      include described_class
+      attribute(:value, default: lazy { [] })
+    end
+    recipe do
+      poise_test 'test' do
+        value << 1
+        value << 2
+      end
+    end
+
+    it { is_expected.to run_poise_test('test').with(value: [1, 2]) }
+  end # /context with a mutable value
 end

data/test/spec/helpers/lwrp_polyfill_spec.rb

@@ -23,38 +23,36 @@ describe Poise::Helpers::LWRPPolyfill do
         include described_class
         attribute(:boolean, equal_to: [true, false])
       end
-
       provider(:poise_test)
-
-      context 'with default value' do
-        recipe do
-          poise_test 'nil'
-        end
-
-        it { is_expected.to run_poise_test('nil').with(boolean: nil) }
+      recipe do
+        poise_test 'test'
       end
 
-      context 'with true value' do
+      context 'with no value' do
+        it { is_expected.to run_poise_test('test').with(boolean: nil) }
+      end # /context with no value
+
+      context 'with a true value' do
         recipe do
-          poise_test 'true' do
+          poise_test 'test' do
             boolean true
           end
         end
 
-        it { is_expected.to run_poise_test('true').with(boolean: true) }
-      end
+        it { is_expected.to run_poise_test('test').with(boolean: true) }
+      end # /context with a true value
 
-      context 'with false value' do
+      context 'with a false value' do
         recipe do
-          poise_test 'false' do
+          poise_test 'test' do
             boolean false
           end
         end
 
-        it { is_expected.to run_poise_test('false').with(boolean: false) }
-      end
+        it { is_expected.to run_poise_test('test').with(boolean: false) }
+      end # /context with a false value
 
-      context 'with string value' do
+      context 'with a string value' do
         recipe do
           poise_test 'true' do
             boolean 'boom'
@@ -62,7 +60,36 @@ describe Poise::Helpers::LWRPPolyfill do
         end
 
         it { expect { subject }.to raise_error Chef::Exceptions::ValidationFailed }
-      end
+      end # /context with a string value
+
+      context 'with a default value' do
+        resource(:poise_test) do
+          include described_class
+          attribute(:value, default: 'default value')
+        end
+
+        it { is_expected.to run_poise_test('test').with(value: 'default value') }
+      end # /context with a default value
+
+      context 'with a mutable default value' do
+        resource(:poise_test) do
+          include described_class
+          attribute(:value, default: [])
+        end
+
+        it { is_expected.to run_poise_test('test').with(value: []) }
+        it { expect(chef_run.poise_test('test').value).to be_frozen }
+
+        context 'and trying to change it' do
+          recipe do
+            poise_test 'test' do
+              value << 1
+            end
+          end
+
+          it { expect { chef_run }.to raise_error RuntimeError }
+        end # /context and trying to change it
+      end # /context with a mutable default value
     end # /describe #attribute
 
     describe '#default_action' do
@@ -93,7 +120,7 @@ describe Poise::Helpers::LWRPPolyfill do
         end
 
         it { is_expected.to be_nil }
-      end
+      end # /context with a direct Provider subclass
 
       context 'with an intermediary class' do
         provider(:poise_parent, auto: false) do
@@ -106,8 +133,8 @@ describe Poise::Helpers::LWRPPolyfill do
         end
 
         it { is_expected.to eq 'helper' }
-      end
-    end
+      end # /context with an intermediary class
+    end # /describe load_current_resource override
 
     describe 'Chef::DSL::Recipe include' do
       resource(:poise_test)
@@ -123,6 +150,6 @@ describe Poise::Helpers::LWRPPolyfill do
       end
 
       it { is_expected.to run_ruby_block('test') }
-    end
+    end # /describe Chef::DSL::Recipe include
   end # /describe Poise::Helpers::LWRPPolyfill::Provider
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: poise
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Noah Kantrowitz
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-29 00:00:00.000000000 Z
+date: 2015-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: halite
@@ -100,6 +100,7 @@ files:
 - test/gemfiles/chef-12.0.gemfile
 - test/gemfiles/chef-12.1.gemfile
 - test/gemfiles/chef-12.2.gemfile
+- test/gemfiles/chef-12.3.gemfile
 - test/gemfiles/chef-12.gemfile
 - test/gemfiles/master.gemfile
 - test/integration/default/serverspec/default_spec.rb
@@ -145,7 +146,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Helpers for writing extensible Chef cookbooks.
@@ -162,6 +163,7 @@ test_files:
 - test/gemfiles/chef-12.0.gemfile
 - test/gemfiles/chef-12.1.gemfile
 - test/gemfiles/chef-12.2.gemfile
+- test/gemfiles/chef-12.3.gemfile
 - test/gemfiles/chef-12.gemfile
 - test/gemfiles/master.gemfile
 - test/integration/default/serverspec/default_spec.rb