nanoc3 3.2.4 → 3.3.0

data/lib/nanoc3/helpers/breadcrumbs.rb

@@ -1,40 +0,0 @@
-# encoding: utf-8
-
-module Nanoc3::Helpers
-
-  # Provides support for breadcrumbs, which allow the user to go up in the
-  # page hierarchy.
-  module Breadcrumbs
-
-    # Creates a breadcrumb trail leading from the current item to its parent,
-    # to its parent’s parent, etc, until the root item is reached. This
-    # function does not require that each intermediate item exist; for
-    # example, if there is no `/foo/` item, breadcrumbs for a `/foo/bar/` item
-    # will contain a `nil` element.
-    #
-    # @return [Array] The breadcrumbs, starting with the root item and ending
-    #   with the item itself
-    def breadcrumbs_trail
-      breadcrumbs_for_identifier(@item.identifier)
-    end
-
-    def item_with_identifier(identifier)
-      @identifier_cache ||= {}
-      @identifier_cache[identifier] ||= begin
-        @items.find { |i| i.identifier == identifier }
-      end
-    end
-
-    def breadcrumbs_for_identifier(identifier)
-      @breadcrumbs_cache ||= {}
-      @breadcrumbs_cache[identifier] ||= begin
-        head = (identifier == '/' ? [] :  breadcrumbs_for_identifier(identifier.sub(/[^\/]+\/$/, '')) )
-        tail = [ item_with_identifier(identifier) ]
-
-        head + tail
-      end
-    end
-
-  end
-
-end

data/lib/nanoc3/helpers/capturing.rb

@@ -1,138 +0,0 @@
-# encoding: utf-8
-
-module Nanoc3::Helpers
-
-  # Provides functionality for “capturing” content in one place and reusing
-  # this content elsewhere.
-  #
-  # For example, suppose you want the sidebar of your site to contain a short
-  # summary of the item. You could put the summary in the meta file, but
-  # that’s not possible when the summary contains eRuby. You could also put
-  # the sidebar inside the actual item, but that’s not very pretty. Instead,
-  # you write the summary on the item itself, but capture it, and print it in
-  # the sidebar layout.
-  #
-  # This helper has been tested with ERB and Haml. Other filters may not work
-  # correctly.
-  #
-  # @example Capturing content for a summary
-  #
-  #   <% content_for :summary do %>
-  #     <p>On this item, nanoc is introduced, blah blah.</p>
-  #   <% end %>
-  #
-  # @example Showing captured content in a sidebar
-  #
-  #   <div id="sidebar">
-  #     <h3>Summary</h3>
-  #     <%= content_for(@item, :summary) || '(no summary)' %>
-  #   </div>
-  #
-  # @example Showing captured content in a sidebar the old, deprecated way (do not use or I will become very angry)
-  #
-  #   <div id="sidebar">
-  #     <h3>Summary</h3>
-  #     <%= @item[:content_for_summary] || '(no summary)' %>
-  #   </div>
-  module Capturing
-
-    # @api private
-    class CapturesStore
-
-      require 'singleton'
-      include Singleton
-
-      def initialize
-        @store = {}
-      end
-
-      def []=(item, name, content)
-        @store[item.identifier] ||= {}
-        @store[item.identifier][name] = content
-      end
-
-      def [](item, name)
-        @store[item.identifier] ||= {}
-        @store[item.identifier][name]
-      end
-
-    end
-
-    # @overload content_for(name, &block)
-    #
-    #   Captures the content inside the block and stores it so that it can be
-    #   referenced later on. The same method, {#content_for}, is used for
-    #   getting the captured content as well as setting it. When capturing,
-    #   the content of the block itself will not be outputted.
-    #
-    #   For backwards compatibility, it is also possible to fetch the captured
-    #   content by getting the contents of the attribute named `content_for_`
-    #   followed by the given name. This way of accessing captures is
-    #   deprecated.
-    #
-    #   @param [Symbol, String] name The base name of the attribute into which
-    #     the content should be stored
-    #
-    #   @return [void]
-    #
-    # @overload content_for(item, name)
-    #
-    #   Fetches the capture with the given name from the given item and
-    #   returns it.
-    #
-    #   @param [Nanoc3::Item] item The item for which to get the capture
-    #
-    #   @param [Symbol, String] name The name of the capture to fetch
-    #
-    #   @return [String] The stored captured content
-    def content_for(*args, &block)
-      if block_given? # Set content
-        # Get args
-        if args.size != 1
-          raise ArgumentError, "expected 1 argument (the name " + 
-            "of the capture) but got #{args.size} instead"
-        end
-        name = args[0]
-
-        # Capture and store
-        content = capture(&block)
-        CapturesStore.instance[@item, name.to_sym] = content
-      else # Get content
-        # Get args
-        if args.size != 2
-          raise ArgumentError, "expected 2 arguments (the item " +
-            "and the name of the capture) but got #{args.size} instead"
-        end
-        item = args[0]
-        name = args[1]
-
-        # Get content
-        CapturesStore.instance[item, name.to_sym]
-      end
-    end
-
-    # Evaluates the given block and returns its contents. The contents of the
-    # block is not outputted.
-    #
-    # @return [String] The captured result
-    def capture(&block)
-      # Get erbout so far
-      erbout = eval('_erbout', block.binding)
-      erbout_length = erbout.length
-
-      # Execute block
-      block.call
-
-      # Get new piece of erbout
-      erbout_addition = erbout[erbout_length..-1]
-
-      # Remove addition
-      erbout[erbout_length..-1] = ''
-
-      # Done
-      erbout_addition
-    end
-
-  end
-
-end

data/lib/nanoc3/helpers/filtering.rb

@@ -1,50 +0,0 @@
-# encoding: utf-8
-
-module Nanoc3::Helpers
-
-  # Provides functionality for filtering parts of an item or a layout.
-  module Filtering
-
-    require 'nanoc3/helpers/capturing'
-    include Nanoc3::Helpers::Capturing
-
-    # Filters the content in the given block and outputs it. This function
-    # does not return anything; instead, the filtered contents is directly
-    # appended to the output buffer (`_erbout`).
-    #
-    # This function has been tested with ERB and Haml. Other filters may not
-    # work correctly.
-    #
-    # @example Running a filter on a part of an item or layout
-    #
-    #   <p>Lorem ipsum dolor sit amet...</p>
-    #   <% filter :rubypants do %>
-    #     <p>Consectetur adipisicing elit...</p>
-    #   <% end %>
-    #
-    # @param [Symbol] filter_name The name of the filter to run on the
-    #   contents of the block
-    #
-    # @param [Hash] argument Arguments to pass to the filter
-    #
-    # @return [void]
-    def filter(filter_name, arguments={}, &block)
-      # Capture block
-      data = capture(&block)
-
-      # Find filter
-      klass = Nanoc3::Filter.named(filter_name)
-      raise Nanoc3::Errors::UnknownFilter.new(filter_name) if klass.nil?
-      filter = klass.new(@item_rep.assigns)
-
-      # Filter captured data
-      filtered_data = filter.run(data, arguments)
-
-      # Append filtered data to buffer
-      buffer = eval('_erbout', block.binding)
-      buffer << filtered_data
-    end
-
-  end
-
-end

data/lib/nanoc3/helpers/html_escape.rb

@@ -1,55 +0,0 @@
-# encoding: utf-8
-
-module Nanoc3::Helpers
-
-  # Contains functionality for HTML-escaping strings.
-  module HTMLEscape
-
-    require 'nanoc3/helpers/capturing'
-    include Nanoc3::Helpers::Capturing
-
-    # Returns the HTML-escaped representation of the given string or the given
-    # block. Only `&`, `<`, `>` and `"` are escaped. When given a block, the
-    # contents of the block will be escaped and appended to the output buffer,
-    # `_erbout`.
-    #
-    # @example Escaping a string
-    #
-    #     h('<br>')
-    #     # => '&lt;br&gt;'
-    #
-    # @example Escaping with a block
-    #
-    #     <% h do %>
-    #       <h1>Hello <em>world</em>!</h1>
-    #     <% end %>
-    #     # The buffer will now contain “&lt;h1&gt;Hello &lt;em&gt;world&lt;/em&gt;!&lt;/h1&gt;”
-    #
-    # @param [String] string The string to escape
-    #
-    # @return [String] The escaped string
-    def html_escape(string=nil, &block)
-      if block_given?
-        # Capture and escape block
-        data = capture(&block)
-        escaped_data = html_escape(data)
-
-        # Append filtered data to buffer
-        buffer = eval('_erbout', block.binding)
-        buffer << escaped_data
-      elsif string
-        string.gsub('&', '&amp;').
-               gsub('<', '&lt;').
-               gsub('>', '&gt;').
-               gsub('"', '&quot;')
-      else
-        raise RuntimeError, "The #html_escape or #h function needs either a " \
-          "string or a block to HTML-escape, but neither a string nor a block was given"
-      end
-    end
-
-    alias h html_escape
-
-  end
-
-end

data/lib/nanoc3/helpers/link_to.rb

@@ -1,151 +0,0 @@
-# encoding: utf-8
-
-module Nanoc3::Helpers
-
-  # Contains functions for linking to items and item representations.
-  module LinkTo
-
-    require 'nanoc3/helpers/html_escape'
-    include Nanoc3::Helpers::HTMLEscape
-
-    # Creates a HTML link to the given path or item representation, and with
-    # the given text. All attributes of the `a` element, including the `href`
-    # attribute, will be HTML-escaped; the contents of the `a` element, which
-    # can contain markup, will not be HTML-escaped. The HTML-escaping is done
-    # using {Nanoc3::Helpers::HTMLEscape#html_escape}.
-    #
-    # @param [String] text The visible link text
-    #
-    # @param [String, Nanoc3::Item, Nanoc3::ItemRep] target The path/URL,
-    #   item or item representation that should be linked to
-    #
-    # @param [Hash] attributes A hash containing HTML attributes (e.g.
-    #   `rel`, `title`, …) that will be added to the link.
-    #
-    # @return [String] The link text
-    #
-    # @example Linking to a path
-    #
-    #   link_to('Blog', '/blog/')
-    #   # => '<a href="/blog/">Blog</a>'
-    #
-    # @example Linking to an item
-    #
-    #   about = @items.find { |i| i.identifier == '/about/' }
-    #   link_to('About Me', about)
-    #   # => '<a href="/about.html">About Me</a>'
-    #
-    # @example Linking to an item representation
-    #
-    #   about = @items.find { |i| i.identifier == '/about/' }
-    #   link_to('My vCard', about.rep(:vcard))
-    #   # => '<a href="/about.vcf">My vCard</a>'
-    #
-    # @example Linking with custom attributes
-    #
-    #   link_to('Blog', '/blog/', :title => 'My super cool blog')
-    #   # => '<a title="My super cool blog" href="/blog/">Blog</a>'
-    def link_to(text, target, attributes={})
-      # Find path
-      if target.is_a?(String)
-        path = target
-      else
-        path = target.path
-        raise RuntimeError, "Cannot create a link to #{target.inspect} because this target is not outputted (its routing rule returns nil)" if path.nil?
-      end
-
-      # Join attributes
-      attributes = attributes.inject('') do |memo, (key, value)|
-        memo + key.to_s + '="' + h(value) + '" '
-      end
-
-      # Create link
-      "<a #{attributes}href=\"#{h path}\">#{text}</a>"
-    end
-
-    # Creates a HTML link using {#link_to}, except when the linked item is
-    # the current one. In this case, a span element with class “active” and
-    # with the given text will be returned. The HTML-escaping rules for
-    # {#link_to} apply here as well.
-    #
-    # @param [String] text The visible link text
-    #
-    # @param [String, Nanoc3::Item, Nanoc3::ItemRep] target The path/URL,
-    #   item or item representation that should be linked to
-    #
-    # @param [Hash] attributes A hash containing HTML attributes (e.g.
-    #   `rel`, `title`, …) that will be added to the link.
-    #
-    # @return [String] The link text
-    #
-    # @example Linking to a different page
-    #
-    #   link_to_unless_current('Blog', '/blog/')
-    #   # => '<a href="/blog/">Blog</a>'
-    #
-    # @example Linking to the same page
-    #
-    #   link_to_unless_current('This Item', @item)
-    #   # => '<span class="active" title="You\'re here.">This Item</span>'
-    def link_to_unless_current(text, target, attributes={})
-      # Find path
-      path = target.is_a?(String) ? target : target.path
-
-      if @item_rep && @item_rep.path == path
-        # Create message
-        "<span class=\"active\" title=\"You're here.\">#{text}</span>"
-      else
-        link_to(text, target, attributes)
-      end
-    end
-
-    # Returns the relative path from the current item to the given path or
-    # item representation. The returned path will not be HTML-escaped.
-    #
-    # @param [String, Nanoc3::Item, Nanoc3::ItemRep] target The path/URL,
-    #   item or item representation to which the relative path should be
-    #   generated
-    #
-    # @return [String] The relative path to the target
-    #
-    # @example
-    #
-    #   # if the current item's path is /foo/bar/
-    #   relative_path_to('/foo/qux/')
-    #   # => '../qux/'
-    def relative_path_to(target)
-      require 'pathname'
-
-      # Find path
-      if target.is_a?(String)
-        path = target
-      else
-        path = target.path
-        raise RuntimeError, "Cannot get the relative path to #{target.inspect} because this target is not outputted (its routing rule returns nil)" if path.nil?
-      end
-
-      # Get source and destination paths
-      dst_path   = Pathname.new(path)
-      raise RuntimeError, "Cannot get the relative path to #{path} because the current item representation, #{@item_rep.inspect}, is not outputted (its routing rule returns nil)" if @item_rep.path.nil?
-      src_path   = Pathname.new(@item_rep.path)
-
-      # Calculate the relative path (method depends on whether destination is
-      # a directory or not).
-      if src_path.to_s[-1,1] != '/'
-        relative_path = dst_path.relative_path_from(src_path.dirname).to_s
-      else
-        relative_path = dst_path.relative_path_from(src_path).to_s
-      end
-
-      # Add trailing slash if necessary
-      if dst_path.to_s[-1,1] == '/'
-        relative_path << '/'
-      end
-
-      # Done
-      relative_path
-    end
-
-  end
-
-end

data/lib/nanoc3/helpers/rendering.rb

@@ -1,140 +0,0 @@
-# encoding: utf-8
-
-module Nanoc3::Helpers
-
-  # Provides functionality for rendering layouts as partials.
-  module Rendering
-
-    include Nanoc3::Helpers::Capturing
-
-    # Renders the given layout. The given layout will be run through the first
-    # matching layout rule.
-    #
-    # When this method is invoked _without_ a block, the return value will be
-    # the rendered layout (a string)  and `_erbout` will not be modified.
-    #
-    # When this method is invoked _with_ a block, an empty string will be
-    # returned and the rendered content will be appended to `_erbout`. In this
-    # case, the content of the block will be captured (using the
-    # {Nanoc3::Helpers::Capturing} helper) and this content will be made
-    # available with `yield`. In other words, a `yield` inside the partial
-    # will output the content of the block passed to the method.
-    #
-    # (For the curious: the reason why {#render} with a block has this
-    # behaviour of returning an empty string and modifying `_erbout` is
-    # because ERB does not support combining the `<%= ... %>` form with a
-    # method call that takes a block.)
-    #
-    # The assigns (`@item`, `@config`, …) will be available in the partial. It
-    # is also possible to pass custom assigns to the method; these assigns
-    # will be made available as instance variables inside the partial.
-    #
-    # @param [String] identifier The identifier of the layout that should be
-    #   rendered
-    #
-    # @param [Hash] other_assigns A hash containing extra assigns that will be
-    #   made available as instance variables in the partial
-    #
-    # @example Rendering a head and a foot partial around some text
-    #
-    #   <%= render 'head' %> - MIDDLE - <%= render 'foot' %>
-    #   # => "HEAD - MIDDLE - FOOT" 
-    #
-    # @example Rendering a head partial with a custom title
-    #
-    #   # The 'head' layout
-    #   <h1><%= @title %></h1>
-    #
-    #   # The item/layout where the partial is rendered
-    #   <%= render 'head', :title => 'Foo' %>
-    #   # => "<h1>Foo</h1>"
-    #
-    # @example Yielding inside a partial
-    #
-    #   # The 'box' partial
-    #   <div class="box">
-    #     <%= yield %>
-    #   </div>
-    #
-    #   # The item/layout where the partial is rendered
-    #   <% render 'box' do %>
-    #     I'm boxy! Luvz!
-    #   <% end %>
-    #
-    #   # Result
-    #   <div class="box">
-    #     I'm boxy! Luvz!
-    #   </div>
-    #
-    # @raise [Nanoc3::Errors::UnknownLayout] if the given layout does not
-    #   exist
-    #
-    # @raise [Nanoc3::Errors::CannotDetermineFilter] if there is no layout
-    #   rule for the given layout
-    #
-    # @raise [Nanoc3::Errors::UnknownFilter] if the layout rule for the given
-    #   layout specifies an unknown filter
-    #
-    # @return [String, nil] The rendered partial, or nil if this method was
-    #   invoked with a block
-    def render(identifier, other_assigns={}, &block)
-      # Find layout
-      layout = @site.layouts.find { |l| l.identifier == identifier.cleaned_identifier }
-      raise Nanoc3::Errors::UnknownLayout.new(identifier.cleaned_identifier) if layout.nil?
-
-      # Visit
-      Nanoc3::NotificationCenter.post(:visit_started, layout)
-      Nanoc3::NotificationCenter.post(:visit_ended,   layout)
-
-      # Capture content, if any
-      captured_content = block_given? ? capture(&block) : nil
-
-      # Get assigns
-      assigns = {
-        :content    => captured_content,
-        :item       => @item,
-        :item_rep   => @item_rep,
-        :items      => @items,
-        :layout     => layout,
-        :layouts    => @layouts,
-        :config     => @config,
-        :site       => @site
-      }.merge(other_assigns)
-
-      # Get filter name
-      filter_name, filter_args = @site.compiler.rules_collection.filter_for_layout(layout)
-      raise Nanoc3::Errors::CannotDetermineFilter.new(layout.identifier) if filter_name.nil?
-
-      # Get filter class
-      filter_class = Nanoc3::Filter.named(filter_name)
-      raise Nanoc3::Errors::UnknownFilter.new(filter_name) if filter_class.nil?
-
-      # Create filter
-      filter = filter_class.new(assigns)
-
-      begin
-        # Notify start
-        Nanoc3::NotificationCenter.post(:processing_started, layout)
-
-        # Layout
-        result = filter.run(layout.raw_content, filter_args)
-
-        # Append to erbout if we have a block
-        if block_given?
-          # Append result and return nothing
-          erbout = eval('_erbout', block.binding)
-          erbout << result
-          ''
-        else
-          # Return result
-          result
-        end
-      ensure
-        # Notify end
-        Nanoc3::NotificationCenter.post(:processing_ended, layout)
-      end
-    end
-
-  end
-
-end