nanoc-core 4.11.12 → 4.11.13

data/lib/nanoc/core/feature.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Nanoc
+  module Core
+    # @example Defining a feature and checking its enabledness
+    #
+    #     Nanoc::Core::Feature.define('environments', version: '4.3')
+    #     Nanoc::Core::Feature.enabled?(Nanoc::Core::Feature::ENVIRONMENTS)
+    #
+    module Feature
+      # Defines a new feature with the given name, experimental in the given
+      # version. The feature will be made available as a constant with the same
+      # name, in uppercase, on the Nanoc::Core::Feature module.
+      #
+      # @example Defining Nanoc::Core::Feature::ENVIRONMENTS
+      #
+      #     Nanoc::Core::Feature.define('environments', version: '4.3')
+      #
+      # @param name The name of the feature
+      #
+      # @param version The minor version in which the feature is considered
+      #   experimental.
+      #
+      # @return [void]
+      def self.define(name, version:)
+        repo[name] = version
+        const_set(name.upcase, name)
+      end
+
+      # Undefines the feature with the given name. For testing purposes only.
+      #
+      # @param name The name of the feature
+      #
+      # @return [void]
+      #
+      # @private
+      def self.undefine(name)
+        repo.delete(name)
+        remove_const(name.upcase)
+      end
+
+      # @param [String] feature_name
+      #
+      # @return [Boolean] Whether or not the feature with the given name is enabled
+      def self.enabled?(feature_name)
+        enabled_features.include?(feature_name) ||
+          enabled_features.include?('all')
+      end
+
+      # @api private
+      def self.enable(feature_name)
+        raise ArgumentError, 'no block given' unless block_given?
+
+        if enabled?(feature_name)
+          yield
+        else
+          begin
+            enabled_features << feature_name
+            yield
+          ensure
+            enabled_features.delete(feature_name)
+          end
+        end
+      end
+
+      # @api private
+      def self.reset_caches
+        @enabled_features = nil
+      end
+
+      # @api private
+      def self.enabled_features
+        @enabled_features ||= Set.new(ENV.fetch('NANOC_FEATURES', '').split(','))
+      end
+
+      # @api private
+      def self.repo
+        @repo ||= {}
+      end
+
+      # @return [Enumerable<String>] Names of features that still exist, but
+      #   should not be considered as experimental in the current version of
+      #   Nanoc.
+      def self.all_outdated
+        repo.keys.reject do |name|
+          version = repo[name]
+          Nanoc::VERSION.start_with?(version)
+        end
+      end
+    end
+  end
+end

data/lib/nanoc/core/filter.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+module Nanoc
+  module Core
+    # Nanoc::Core::Filter is responsible for filtering items. It is the superclass
+    # for all textual filters.
+    #
+    # A filter instance should only be used once. Filters should not be reused
+    # since they store state.
+    #
+    # When creating a filter with a hash containing assigned variables, those
+    # variables will be made available in the `@assigns` instance variable and
+    # the {#assigns} method. The assigns itself will also be available as
+    # instance variables and instance methods.
+    #
+    # @example Accessing assigns in different ways
+    #
+    #   filter = SomeFilter.new({ :foo => 'bar' })
+    #   filter.instance_eval { @assigns[:foo] }
+    #     # => 'bar'
+    #   filter.instance_eval { assigns[:foo] }
+    #     # => 'bar'
+    #   filter.instance_eval { @foo }
+    #     # => 'bar'
+    #   filter.instance_eval { foo }
+    #     # => 'bar'
+    #
+    # @abstract Subclass and override {#run} to implement a custom filter.
+    class Filter < Nanoc::Core::Context
+      extend DDPlugin::Plugin
+
+      include Nanoc::Core::ContractsSupport
+
+      # @api private
+      TMP_BINARY_ITEMS_DIR = 'binary_items'
+
+      class UnknownFilterError < Nanoc::Core::Error
+        include Nanoc::Core::ContractsSupport
+
+        contract C::Or[String, Symbol] => self
+        def initialize(filter_name)
+          super("The requested filter, “#{filter_name}”, does not exist.")
+        end
+      end
+
+      class OutputNotWrittenError < Nanoc::Core::Error
+        include Nanoc::Core::ContractsSupport
+
+        contract C::Or[String, Symbol], String => self
+        def initialize(filter_name, output_filename)
+          super("The #{filter_name.inspect} filter did not write anything to the required output file, #{output_filename}.")
+        end
+      end
+
+      class FilterReturnedNilError < Nanoc::Core::Error
+        include Nanoc::Core::ContractsSupport
+
+        contract C::Or[String, Symbol] => self
+        def initialize(filter_name)
+          super("The #{filter_name.inspect} filter returned nil, but is required to return a String.")
+        end
+      end
+
+      class << self
+        def define(ident, &block)
+          filter_class = Class.new(::Nanoc::Core::Filter) { identifier(ident) }
+          filter_class.send(:define_method, :run) do |content, params = {}|
+            instance_exec(content, params, &block)
+          end
+        end
+
+        def named!(name)
+          klass = named(name)
+          raise UnknownFilterError.new(name) if klass.nil?
+
+          klass
+        end
+
+        # Sets the new type for the filter. The type can be `:binary` (default)
+        # or `:text`. The given argument can either be a symbol indicating both
+        # “from” and “to” types, or a hash where the only key is the “from” type
+        # and the only value is the “to” type.
+        #
+        # @example Specifying a text-to-text filter
+        #
+        #     type :text
+        #
+        # @example Specifying a text-to-binary filter
+        #
+        #     type :text => :binary
+        #
+        # @param [Symbol, Hash] arg The new type of this filter
+        #
+        # @return [void]
+        def type(arg)
+          if arg.is_a?(Hash)
+            @from = arg.keys[0]
+            @to = arg.values[0]
+          else
+            @from = arg
+            @to = arg
+          end
+        end
+
+        # @return [Boolean] True if this filter can be applied to binary item
+        #   representations, false otherwise
+        #
+        # @api private
+        def from_binary?
+          (@from || :text) == :binary
+        end
+
+        # @return [Boolean] True if this filter results in a binary item
+        #   representation, false otherwise
+        #
+        # @api private
+        def to_binary?
+          (@to || :text) == :binary
+        end
+
+        # @api private
+        def to_text?
+          (@to || :text) == :text
+        end
+
+        # @return [Boolean]
+        #
+        # @api private
+        def always_outdated?
+          @always_outdated || false
+        end
+
+        # Marks this filter as always causing the item rep to be outdated. This is useful for filters
+        # that cannot do dependency tracking properly.
+        #
+        # @return [void]
+        def always_outdated
+          @always_outdated = true
+        end
+
+        # @overload requires(*requires)
+        #   Sets the required libraries for this filter.
+        #   @param [Array<String>] requires A list of library names that are required
+        #   @return [void]
+        # @overload requires
+        #   Returns the required libraries for this filter.
+        #   @return [Enumerable<String>] This filter’s list of library names that are required
+        def requires(*requires)
+          if requires.any?
+            @requires = requires
+          else
+            @requires || []
+          end
+        end
+
+        # Requires the filter’s required library if necessary.
+        #
+        # @return [void]
+        #
+        # @api private
+        def setup
+          @setup ||= begin
+            requires.each { |r| require r }
+            true
+          end
+        end
+      end
+
+      # Creates a new filter that has access to the given assigns.
+      #
+      # @param [Hash] hash A hash containing variables that should be made
+      #   available during filtering.
+      #
+      # @api private
+      def initialize(hash = {})
+        @assigns = hash
+        super
+      end
+
+      # Sets up the filter and runs the filter. This method passes its arguments
+      # to {#run} unchanged and returns the return value from {#run}.
+      #
+      # @see #run
+      #
+      # @api private
+      def setup_and_run(*args)
+        self.class.setup
+        run(*args).tap { |res| verify(res) }
+      end
+
+      # Runs the filter on the given content or filename.
+      #
+      # @abstract
+      #
+      # @param [String] content_or_filename The unprocessed content that should
+      #   be filtered (if the item is a textual item) or the path to the file
+      #   that should be filtered (if the item is a binary item)
+      #
+      # @param [Hash] params A hash containing parameters. Filter subclasses can
+      #   use these parameters to allow modifying the filter's behaviour.
+      #
+      # @return [String, void] If the filter output binary content, the return
+      #   value is undefined; if the filter outputs textual content, the return
+      #   value will be the filtered content.
+      def run(content_or_filename, params = {}) # rubocop:disable Lint/UnusedMethodArgument
+        raise NotImplementedError.new('Nanoc::Core::Filter subclasses must implement #run')
+      end
+
+      def verify(res)
+        if self.class.to_binary?
+          unless File.file?(output_filename)
+            raise Nanoc::Core::Filter::OutputNotWrittenError.new(self.class.identifier, output_filename)
+          end
+        elsif self.class.to_text?
+          unless res
+            raise Nanoc::Core::Filter::FilterReturnedNilError.new(self.class.identifier)
+          end
+        end
+      end
+
+      contract C::None => String
+      # Returns a filename that is used to write data to. This method is only
+      #   used on binary items. When running a binary filter on a file, the
+      #   resulting file must end up in the location returned by this method.
+      #
+      # The returned filename will be absolute, so it is safe to change to
+      #   another directory inside the filter.
+      #
+      # @return [String] The output filename
+      def output_filename
+        @output_filename ||=
+          Nanoc::Core::TempFilenameFactory.instance.create(TMP_BINARY_ITEMS_DIR)
+      end
+
+      contract C::None => String
+      # Returns the filename associated with the item that is being filtered.
+      #   It is in the format `item <identifier> (rep <name>)`.
+      #
+      # @return [String] The filename
+      #
+      # @api private
+      def filename
+        if @layout
+          "layout #{@layout.identifier}"
+        elsif @item
+          "item #{@item.identifier} (rep #{@item_rep.name})"
+        else
+          '?'
+        end
+      end
+
+      # @api private
+      def on_main_fiber(&block)
+        Fiber.yield(block)
+      end
+
+      contract C::ArrayOf[C::Named['Nanoc::Core::BasicItemView']] => C::Any
+      # Creates a dependency from the item that is currently being filtered onto
+      # the given collection of items. In other words, require the given items
+      # to be compiled first before this items is processed.
+      #
+      # @return [void]
+      def depend_on(items)
+        items.flat_map(&:reps).flat_map(&:raw_path)
+        items.each(&:raw_filename)
+      end
+    end
+  end
+end

data/lib/nanoc/core/identifiable_collection_view.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Nanoc
+  module Core
+    class IdentifiableCollectionView < ::Nanoc::Core::View
+      include Enumerable
+
+      NOTHING = Object.new
+
+      # @api private
+      def initialize(objects, context)
+        super(context)
+        @objects = objects
+      end
+
+      # @api private
+      def _unwrap
+        @objects
+      end
+
+      # @abstract
+      #
+      # @api private
+      def view_class
+        raise NotImplementedError
+      end
+
+      # Calls the given block once for each object, passing that object as a parameter.
+      #
+      # @yieldparam [#identifier] object
+      #
+      # @yieldreturn [void]
+      #
+      # @return [self]
+      def each
+        @context.dependency_tracker.bounce(_unwrap, raw_content: true)
+        @objects.each { |i| yield view_class.new(i, @context) }
+        self
+      end
+
+      # @return [Integer]
+      def size
+        @context.dependency_tracker.bounce(_unwrap, raw_content: true)
+        @objects.size
+      end
+
+      # Finds all objects whose identifier matches the given argument.
+      #
+      # @param [String, Regex] arg
+      #
+      # @return [Enumerable]
+      def find_all(arg = NOTHING, &block)
+        if NOTHING.equal?(arg)
+          @context.dependency_tracker.bounce(_unwrap, raw_content: true)
+          return @objects.map { |i| view_class.new(i, @context) }.select(&block)
+        end
+
+        prop_attribute =
+          case arg
+          when String, Nanoc::Core::Identifier
+            [arg.to_s]
+          when Regexp
+            [arg]
+          else
+            true
+          end
+
+        @context.dependency_tracker.bounce(_unwrap, raw_content: prop_attribute)
+        @objects.find_all(arg).map { |i| view_class.new(i, @context) }
+      end
+
+      # @overload [](string)
+      #
+      #   Finds the object whose identifier matches the given string.
+      #
+      #   If the glob syntax is enabled, the string can be a glob, in which case
+      #   this method finds the first object that matches the given glob.
+      #
+      #   @param [String] string
+      #
+      #   @return [nil] if no object matches the string
+      #
+      #   @return [#identifier] if an object was found
+      #
+      # @overload [](regex)
+      #
+      #   Finds the object whose identifier matches the given regular expression.
+      #
+      #   @param [Regex] regex
+      #
+      #   @return [nil] if no object matches the regex
+      #
+      #   @return [#identifier] if an object was found
+      def [](arg)
+        prop_attribute =
+          case arg
+          when String, Nanoc::Core::Identifier
+            [arg.to_s]
+          when Regexp
+            [arg]
+          else
+            true
+          end
+
+        @context.dependency_tracker.bounce(_unwrap, raw_content: prop_attribute)
+        res = @objects[arg]
+        res && view_class.new(res, @context)
+      end
+    end
+  end
+end