poise 2.0.0

data/Rakefile

@@ -0,0 +1,17 @@
+#
+# Copyright 2013-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.
+#
+
+require 'poise_boiler/rakefile'

data/lib/poise.rb

@@ -0,0 +1,71 @@
+#
+# Copyright 2013-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.
+#
+
+require 'chef/provider'
+require 'chef/resource'
+
+require 'poise/utils/resource_provider_mixin'
+
+
+module Poise
+  include Poise::Utils::ResourceProviderMixin
+  autoload :Helpers, 'poise/helpers'
+  autoload :Provider, 'poise/provider'
+  autoload :Resource, 'poise/resource'
+  autoload :Subcontext, 'poise/subcontext'
+  autoload :Utils, 'poise/utils'
+  autoload :VERSION, 'poise/version'
+end
+
+# Callable form to allow passing in options:
+#   include Poise(ParentResource)
+#   include Poise(parent: ParentResource)
+#   include Poise(container: true)
+def Poise(options={})
+  # Allow passing a class as a shortcut
+  if options.is_a?(Class)
+    options = {parent: options}
+  end
+
+  # Create a new anonymous module
+  mod = Module.new
+
+  # Fake the name.
+  mod.define_singleton_method(:name) do
+    super() || 'Poise'
+  end
+
+  mod.define_singleton_method(:included) do |klass|
+    super(klass)
+    # Pull in the main helper to cover most of the needed logic.
+    klass.class_exec { include Poise }
+    # Set the defined_in values as needed.
+    klass.poise_defined!(caller)
+    # Resource-specific options.
+    if klass < Chef::Resource
+      klass.poise_subresource(options[:parent], options[:parent_optional], options[:parent_auto]) if options[:parent]
+      klass.poise_subresource_container(options[:container_namespace]) if options[:container]
+      klass.poise_fused if options[:fused]
+      klass.poise_inversion(options[:inversion_options_resource]) if options[:inversion]
+    end
+    # Provider-specific options.
+    if klass < Chef::Provider
+      klass.poise_inversion(options[:inversion], options[:inversion_attribute]) if options[:inversion]
+    end
+  end
+
+  mod
+end

data/lib/poise/error.rb

@@ -0,0 +1,24 @@
+#
+# 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.
+#
+
+
+module Poise
+  # Base exception class for Poise errors.
+  #
+  # @since 2.0.0
+  class Error < Exception
+  end
+end

data/lib/poise/helpers.rb

@@ -0,0 +1,33 @@
+#
+# 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.
+#
+
+
+module Poise
+  module Helpers
+    autoload :ChefspecMatchers, 'poise/helpers/chefspec_matchers'
+    autoload :DefinedIn, 'poise/helpers/defined_in'
+    autoload :Fused, 'poise/helpers/fused'
+    autoload :IncludeRecipe, 'poise/helpers/include_recipe'
+    autoload :Inversion, 'poise/helpers/inversion'
+    autoload :LazyDefault, 'poise/helpers/lazy_default'
+    autoload :LWRPPolyfill, 'poise/helpers/lwrp_polyfill'
+    autoload :NotifyingBlock, 'poise/helpers/notifying_block'
+    autoload :OptionCollector, 'poise/helpers/option_collector'
+    autoload :ResourceName, 'poise/helpers/resource_name'
+    autoload :Subresources, 'poise/helpers/subresources'
+    autoload :TemplateContent, 'poise/helpers/template_content'
+  end
+end

data/lib/poise/helpers/chefspec_matchers.rb

@@ -0,0 +1,92 @@
+#
+# Copyright 2013-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.
+#
+
+begin
+  require 'chefspec'
+  require 'rspec/expectations'
+rescue LoadError
+  # Don't panic! We will no-op later on if these aren't available.
+end
+
+require 'poise/helpers/lwrp_polyfill'
+require 'poise/helpers/resource_name'
+
+
+module Poise
+  module Helpers
+    # A resource mixin to register ChefSpec matchers for a resource
+    # automatically.
+    #
+    # If you are using the provides() form for naming resources, ensure that is
+    # set before declaring actions.
+    #
+    # @since 2.0.0
+    # @example Define a class
+    #   class Chef::Resource::MyResource < Chef::Resource
+    #     include Poise::Helpers::ChefspecMatchers
+    #     actions(:run)
+    #   end
+    # @example Use a matcher
+    #   expect(chef_run).to run_my_resource('...')
+    module ChefspecMatchers
+      include Poise::Helpers::LWRPPolyfill::Resource
+      include Poise::Helpers::ResourceName
+
+      # Create a matcher for a given resource type and action. This is
+      # idempotent so if a matcher already exists, it will not be recreated.
+      #
+      # @api private
+      def self.create_matcher(resource, action)
+        # Check that we have everything we need.
+        return unless defined?(ChefSpec) && defined?(RSpec::Matchers) && resource
+        method = :"#{action}_#{resource}"
+        return if RSpec::Matchers.method_defined?(method)
+        RSpec::Matchers.send(:define_method, method) do |resource_name|
+          ChefSpec::Matchers::ResourceMatcher.new(resource, action, resource_name)
+        end
+      end
+
+      # @!classmethods
+      module ClassMethods
+        # Create a resource-level matcher for this resource.
+        #
+        # @see Resource::ResourceName.provides
+        def provides(name)
+          ChefSpec.define_matcher(name) if defined?(ChefSpec)
+          super
+        end
+
+        # Create matchers for all declared actions.
+        #
+        # @see Resource::LWRPPolyfill.actions
+        def actions(*names)
+          super.tap do |actions|
+            actions.each do |action|
+              ChefspecMatchers.create_matcher(resource_name, action)
+            end
+          end
+        end
+
+        def included(klass)
+          super
+          klass.extend ClassMethods
+        end
+      end
+
+      extend ClassMethods
+    end
+  end
+end

data/lib/poise/helpers/defined_in.rb

@@ -0,0 +1,111 @@
+#
+# 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.
+#
+
+require 'poise/error'
+require 'poise/utils'
+
+
+module Poise
+  module Helpers
+    # A mixin to track where a resource or provider was defined. This can
+    # provide either the filename of the class or the cookbook it was defined in.
+    #
+    # @since 2.0.0
+    # @example
+    #   class MyProvider < Chef::provider
+    #     include Poise::Helpers::DefinedIn
+    #
+    #     def action_create
+    #       template '...' do
+    #         # ...
+    #         cookbook new_resource.poise_defined_in
+    #       end
+    #     end
+    #   end
+    module DefinedIn
+      # Wrapper for {.poise_defined_in_cookbook} to pass the run context for you.
+      #
+      # @see .poise_defined_in_cookbook
+      # @param file [String, nil] Optional file path to check instead of the path
+      #   this class was defined in.
+      # @return [String]
+      def poise_defined_in_cookbook(file=nil)
+        self.class.poise_defined_in_cookbook(run_context, file)
+      end
+
+      # @!classmethods
+      module ClassMethods
+        # The file this class or module was defined in, or nil if it isn't found.
+        #
+        # @return [String]
+        def poise_defined_in
+          raise Poise::Error.new("Unable to determine location of #{self.name}") unless @poise_defined_in
+          @poise_defined_in
+        end
+
+        # The cookbook this class or module was defined in. Can pass a file to
+        # check that instead.
+        #
+        # @param run_context [Chef::RunContext] Run context to check cookbooks in.
+        # @param file [String, nil] Optional file path to check instead of the
+        #   path this class was defined in.
+        # @return [String]
+        def poise_defined_in_cookbook(run_context, file=nil)
+          file ||= poise_defined_in
+          Chef::Log.debug("[#{self.name}] Checking cookbook name for #{file}")
+          Poise::Utils.find_cookbook_name(run_context, file).tap do |cookbook|
+            Chef::Log.debug("[#{self.name}] found cookbook #{cookbook.inspect}")
+          end
+        end
+
+        # Record that the class/module was defined. Called automatically by Ruby
+        # for all normal cases.
+        #
+        # @param caller_array [Array<String>] A strack trace returned by #caller.
+        # @return [void]
+        def poise_defined!(caller_array)
+          # Only try to set this once.
+          return if @poise_defined_in
+          # Path to ignore, assumes Halite transformation which I'm not thrilled
+          # about.
+          poise_libraries = File.expand_path('../..', __FILE__)
+          # Parse out just the filenames.
+          caller_array = caller_array.map {|line| line.split(/:/, 2).first }
+          # Find the first non-poise line.
+          caller_path = caller_array.find do |line|
+            !line.start_with?(poise_libraries)
+          end
+          Chef::Log.debug("[#{self.name}] Recording poise_defined_in as #{caller_path}")
+          @poise_defined_in = caller_path
+        end
+
+        # @api private
+        def inherited(klass)
+          super
+          klass.poise_defined!(caller)
+        end
+
+        def included(klass)
+          super
+          klass.extend(ClassMethods)
+          klass.poise_defined!(caller)
+        end
+      end
+
+      extend ClassMethods
+    end
+  end
+end

data/lib/poise/helpers/fused.rb

@@ -0,0 +1,127 @@
+#
+# Copyright 2013-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.
+#
+
+require 'chef/provider'
+
+
+module Poise
+  module Helpers
+    # Resource mixin to create "fused" resources where the resource and provider
+    # are implemented in the same class.
+    #
+    # @since 2.0.0
+    # @example
+    #   class Chef::Resource::MyResource < Chef::Resource
+    #     include Poise(fused: true)
+    #     attribute(:path, kind_of: String)
+    #     attribute(:message, kind_of: String)
+    #     action(:run) do
+    #       file new_resource.path do
+    #         content new_resource.message
+    #       end
+    #     end
+    #   end
+    module Fused
+      # Hack is_a? so that the DSL will consider this a Provider for the
+      # purposes of attaching enclosing_provider.
+      #
+      # @api private
+      # @param klass [Class]
+      # @return [Boolean]
+      def is_a?(klass)
+        if klass == Chef::Provider
+          # Lies, damn lies, and Ruby code.
+          true
+        else
+          super
+        end
+      end
+
+      # Hack provider_for_action so that the resource is also the provider.
+      #
+      # @api private
+      # @param action [Symbol]
+      # @return [Chef::Provider]
+      def provider_for_action(action)
+        provider(self.class.fused_provider_class) unless provider
+        super
+      end
+
+      # @!classmethods
+      module ClassMethods
+        # Define a provider action. The block should contain the usual provider
+        # code.
+        #
+        # @param name [Symbol] Name of the action.
+        # @param block [Proc] Action implementation.
+        # @example
+        #   action(:run) do
+        #     file '/temp' do
+        #       user 'root'
+        #       content 'temp'
+        #     end
+        #   end
+        def action(name, &block)
+          fused_actions[name.to_sym] = block
+          # Make sure this action is allowed, also sets the default if first.
+          if respond_to?(:actions)
+            actions(name.to_sym)
+          end
+        end
+
+        # Storage accessor for fused action blocks. Maps action name to proc.
+        #
+        # @api private
+        # @return [Hash<Symbol, Proc>]
+        def fused_actions
+          (@fused_actions ||= {})
+        end
+
+        # Create a provider class for the fused actions in this resource.
+        # Inherits from the fused provider class of the resource's superclass if
+        # present.
+        #
+        # @api private
+        # @return [Class]
+        def fused_provider_class
+          @fused_provider_class ||= begin
+            provider_superclass = begin
+              self.superclass.fused_provider_class
+            rescue NoMethodError
+              Chef::Provider
+            end
+            actions = fused_actions
+            class_name = self.name
+            Class.new(provider_superclass) do
+              include Poise
+              define_singleton_method(:name) { class_name + ' (fused)' }
+              actions.each do |action, block|
+                define_method(:"action_#{action}", &block)
+              end
+            end
+          end
+        end
+
+        def included(klass)
+          super
+          klass.extend(ClassMethods)
+        end
+      end
+
+      extend ClassMethods
+    end
+  end
+end