nanoc3 3.1.0a2 → 3.1.0a3

data/lib/nanoc3/extra/validators/links.rb

@@ -0,0 +1,242 @@
+# encoding: utf-8
+
+module Nanoc3::Extra::Validators
+
+  # A validator that verifies that all links (`<a href="…">…</a>`) point to a
+  # location that exists.
+  class Links
+
+    # @param [String] dir The directory that will be searched for HTML files
+    # to validate
+    #
+    # @param [Array<String>] index_filenames An array of index filenames that
+    # will be appended to URLs by web servers if a directory is requested
+    # instead of a file
+    #
+    # @option params [Boolean] :internal (false) True if internal links should
+    # be checked; false if they should not
+    #
+    # @option params [Boolean] :external (false) True if external links should
+    # be checked; false if they should not
+    def initialize(dir, index_filenames, params={})
+      @dir              = dir
+      @index_filenames  = index_filenames
+      @include_internal = params.has_key?(:internal) && params[:internal]
+      @include_external = params.has_key?(:external) && params[:external]
+    end
+
+    # Starts the validator. The results will be printed to stdout.
+    #
+    # @return [void]
+    def run
+      require 'nokogiri'
+
+      @delegate = self
+      links = all_broken_hrefs
+      if links.empty?
+        puts "No broken links found!"
+      else
+        links.each_pair do |href, origins|
+          puts "Broken link: #{href} -- referenced from:"
+          origins.each do |origin|
+            puts "    #{origin}"
+          end
+          puts
+        end
+      end
+    end
+
+  private
+
+    def all_broken_hrefs
+      broken_hrefs = {}
+
+      internal_hrefs = {}
+      external_hrefs = {}
+
+      # Split into internal and external hrefs
+      all_hrefs_per_filename.each_pair do |filename, hrefs|
+        hrefs.each do |href|
+          if is_external_href?(href)
+            external_hrefs[href] ||= []
+            external_hrefs[href] << filename
+          else
+            internal_hrefs[href] ||= []
+            internal_hrefs[href] << filename
+          end
+        end
+      end
+
+      # Validate hrefs
+      validate_internal_hrefs(internal_hrefs, broken_hrefs) if @include_internal
+      validate_external_hrefs(external_hrefs, broken_hrefs) if @include_external
+
+      # Done
+      broken_hrefs
+    end
+
+    def all_files
+      Dir[@dir + '/**/*.html']
+    end
+
+    def all_hrefs_per_filename
+      hrefs = {}
+      all_files.each do |filename|
+        hrefs[filename] ||= all_hrefs_in_file(filename)
+      end
+      hrefs
+    end
+
+    def all_hrefs_in_file(filename)
+      doc = Nokogiri::HTML(::File.read(filename))
+      doc.css('a').map { |l| l[:href] }.compact
+    end
+
+    def is_external_href?(href)
+      !!(href =~ %r{^[a-z\-]+:})
+    end
+
+    def is_valid_internal_href?(href, origin)
+      # Skip hrefs that point to self
+      # FIXME this is ugly and won’t always be correct
+      return true if href == '.'
+
+      # Remove target
+      path = href.sub(/#.*$/, '')
+      return true if path.empty?
+
+      # Make absolute
+      if path[0, 1] == '/'
+        path = @dir + path
+      else
+        path = ::File.expand_path(path, ::File.dirname(origin))
+      end
+
+      # Check whether file exists
+      return true if File.file?(path)
+
+      # Check whether directory with index file exists
+      return true if File.directory?(path) && @index_filenames.any? { |fn| File.file?(File.join(path, fn)) }
+
+      # Nope :(
+      return false
+    end
+
+    def is_valid_external_href?(href)
+      require 'net/http'
+      require 'uri'
+
+      # Parse
+      uri = URI.parse(href)
+
+      # Skip non-HTTP URLs
+      return true if uri.scheme != 'http'
+
+      # Get status
+      status = fetch_http_status_for(uri)
+      is_valid = (status && status >= 200 && status <= 299)
+
+      # Notify
+      @delegate.send(:external_href_validated, href, is_valid)
+
+      # Done
+      is_valid
+    end
+
+    def validate_internal_hrefs(hrefs, broken_hrefs)
+      hrefs.each_pair do |href, filenames|
+        filenames.each do |filename|
+          if !is_valid_internal_href?(href, filename)
+            broken_hrefs[href] = filenames
+          end
+        end
+      end
+    end
+
+    class EachPairEnumerator
+
+      def initialize(hash)
+        @hash             = hash
+        @unprocessed_keys = @hash.keys.dup
+        @mutex            = Mutex.new
+      end
+
+      def next_pair
+        @mutex.synchronize do
+          key = @unprocessed_keys.shift
+          return (key ? [ key, @hash[key] ] : nil)
+        end
+      end
+
+    end
+
+    def validate_external_hrefs(hrefs, broken_hrefs)
+      @mutex = Mutex.new
+
+      enum = EachPairEnumerator.new(hrefs)
+
+      threads = []
+      10.times do
+        threads << Thread.new do
+          loop do
+            # Get next pair
+            pair = enum.next_pair
+            break if pair.nil?
+            href, filenames = pair[0], pair[1]
+
+            # Validate
+            if !is_valid_external_href?(href)
+              @mutex.synchronize do
+                broken_hrefs[href] = filenames
+              end
+            end
+          end
+        end
+      end
+      threads.each { |t| t.join }
+    end
+
+    def fetch_http_status_for(url, params={})
+      5.times do |i|
+        begin
+          res = request_url_once(url)
+
+          if res.code =~ /^3..$/
+            url = URI.parse(res['location'])
+            return nil if i == 5
+          else
+            return res.code.to_i
+          end
+        rescue
+          nil
+        end
+      end
+    end
+
+    def request_url_once(url)
+      path = (url.path.nil? || url.path.empty? ? '/' : url.path)
+      req = Net::HTTP::Head.new(path)
+      res = Net::HTTP.start(url.host, url.port) { |h| h.request(req) }
+      res
+    end
+
+    def external_href_validated(href, is_valid)
+      texts = {
+        true  => 'ok',
+        false => ' ERROR '
+      }
+
+      colors = {
+        true     => "\e[32m",
+        false    => "\e[41m\e[37m",
+        :off     => "\033[0m"
+      }
+
+      @mutex.synchronize do
+        puts href + ': ' + colors[is_valid] + texts[is_valid] + colors[:off]
+      end
+    end
+
+  end
+
+end

data/lib/nanoc3/extra/validators/w3c.rb

@@ -2,55 +2,79 @@
 
 module Nanoc3::Extra::Validators
 
-  # Nanoc3::Extra::Validators::W3C is a validator that uses the W3C web
-  # service to validate HTML and CSS files.
+  # A validator that uses the W3C web service to validate HTML and CSS files.
   class W3C
 
-    def initialize(site, type)
-      @site = site
-      @type = type
+    # @param [String] dir The directory that will be searched for HTML and/or
+    # CSS files to validate
+    #
+    # @param [Array<Symbol>] types A list of types to check. Allowed types are
+    # `:html` and `:css`.
+    def initialize(dir, types)
+      @dir   = dir
+      @types = types
     end
 
+    # Starts the validator. The results will be printed to stdout.
+    #
+    # @return [void]
     def run
       # Load validator
       require 'w3c_validators'
 
-      # Make sure config is loaded
-      @site.load_data
-
       # Find all files
-      files = extensions.map { |extension| Dir["#{@site.config[:output_dir]}/**/*.#{extension}"] }.flatten
+      filenames = []
+      extensions = types_to_extensions(@types)
+      extensions.each { |extension| filenames.concat(Dir[@dir + '/**/*.' + extension]) }
 
       # Validate each file
-      files.each do |file|
-        validation_started(file)
-        results = validator.validate_file(file)
-        validation_ended(file, results.errors)
+      filenames.each do |filename|
+        validation_started(filename)
+
+        extension = File.extname(filename)[1..-1]
+        results = validator_for(extension).validate_file(filename)
+
+        validation_ended(filename, results.errors)
       end
     end
 
   private
 
-    def extensions
-      case @type
-      when :html
-        [ 'html', 'htm' ]
-      when :css
-        [ 'css' ]
+    # Returns all extensions for the given types
+    def types_to_extensions(types)
+      extensions = []
+      types.each { |type| extensions.concat(type_to_extensions(type)) }
+      extensions
+    end
+
+    # Returns all extensions for the given type
+    def type_to_extensions(type)
+      case type
+        when :html
+          [ 'html', 'htm' ]
+        when :css
+          [ 'css' ]
+        else
+          raise RuntimeError, "unknown type: #{type}"
       end
     end
 
-    def validator_class
-      case @type
-      when :html
+    # Returns the validator class for the given extension
+    def validator_class_for(extension)
+      case extension
+      when 'html', 'htm'
         ::W3CValidators::MarkupValidator
-      when :css
+      when 'css'
         ::W3CValidators::CSSValidator
+      else
+        raise RuntimeError, "unknown extension: #{extension}"
       end
     end
 
-    def validator
-      @validator ||= validator_class.new
+    # Returns the validator for the given extension
+    def validator_for(extension)
+      @validators ||= {}
+      @validators[extension] ||= validator_class_for(extension).new
     end
 
     def validation_started(file)

data/lib/nanoc3/extra/validators.rb

@@ -2,10 +2,10 @@
 
 module Nanoc3::Extra
 
-  # Nanoc3::Extra::Validators is the name for all validators.
   module Validators
 
-    autoload 'W3C', 'nanoc3/extra/validators/w3c'
+    autoload 'W3C',   'nanoc3/extra/validators/w3c'
+    autoload 'Links', 'nanoc3/extra/validators/links'
 
   end
 

data/lib/nanoc3/extra/vcs.rb

@@ -8,7 +8,7 @@ module Nanoc3::Extra
   # the disk.
   #
   # @abstract Subclass and override {#add}, {#remove} and {#move} to implement
-  #   a custom VCS.
+  # a custom VCS.
   class VCS
 
     extend Nanoc3::PluginRegistry::PluginMethods

data/lib/nanoc3/extra.rb

@@ -5,13 +5,16 @@ module Nanoc3::Extra
   autoload 'AutoCompiler',      'nanoc3/extra/auto_compiler'
   autoload 'CHiCk',             'nanoc3/extra/chick'
   autoload 'Deployers',         'nanoc3/extra/deployers'
-  autoload 'FileProxy',         'nanoc3/extra/file_proxy'
   autoload 'Validators',        'nanoc3/extra/validators'
 
   # Deprecated; use {Nanoc3::Context} instead
   # TODO [in nanoc 4.0] remove me
   Context = ::Nanoc3::Context
 
+  # Deprecated
+  # TODO [in nanoc 4.0] remove me
+  autoload 'FileProxy',         'nanoc3/extra/file_proxy'
+
 end
 
 require 'nanoc3/extra/core_ext'

data/lib/nanoc3/helpers/blogging.rb

@@ -10,13 +10,16 @@ module Nanoc3::Helpers
   #
   # * `kind` — Set to `"article"`
   #
-  # * `created_at` — The article’s publication timestamp. This timestamp can
-  #   be in any format parseable by `Time.parse`.
+  # * `created_at` — The article’s publication timestamp
   #
   # Some functions in this blogging helper, such as the {#atom_feed} function,
   # require additional attributes to be set; these attributes are described in
   # the documentation for these functions.
   #
+  # All “time” item attributes, site configuration attributes or method
+  # parameters can either be a `Time` instance or a string in any format
+  # parseable by `Time.parse`.
+  #
   # The two main functions are {#sorted_articles} and {#atom_feed}.
   module Blogging
 
@@ -35,7 +38,10 @@ module Nanoc3::Helpers
     # @return [Array] A sorted array containing all articles
     def sorted_articles
       require 'time'
-      articles.sort_by { |a| t = a[:created_at] ; t.is_a?(String) ? Time.parse(t) : t }.reverse
+      articles.sort_by do |a|
+        time = a[:created_at]
+        time.is_a?(String) ? Time.parse(time) : time
+      end.reverse
     end
 
     # Returns a string representing the atom feed containing recent articles,
@@ -58,10 +64,9 @@ module Nanoc3::Helpers
     #   non-outputted items in a feed; such items could have their custom feed
     #   path set to the blog path instead, for example.
     #
-    # The feed will also include dates on which the articles were updated.
-    # These are generated automatically; the way this happens depends on the
-    # used data source (the filesystem data source checks the file mtimes, for
-    # instance).
+    # * `updated_at` — The time when the article was last modified. If this
+    #   attribute is not present, the `created_at` attribute will be used as
+    #   the time when the article was last modified.
     #
     # The site configuration will need to have the following attributes:
     #
@@ -69,7 +74,10 @@ module Nanoc3::Helpers
     #   example, if the site is at “http://example.com/”, the `base_url`
     #   would be “http://example.com”.
     #
-    # The feed item will need to have the following attributes:
+    # The feed item will need to know about the feed title, the feed author
+    # name, and the URI corresponding to the author. These can be specified
+    # using parameters, as attributes in the feed item, or in the site
+    # configuration.   
     #
     # * `title` — The title of the feed, which is usually also the title of
     #   the blog.
@@ -107,19 +115,28 @@ module Nanoc3::Helpers
     #   <%= atom_feed :limit => 5 %>
     #
     # @option params [Number] :limit (5) The maximum number of articles to
-    #   show
+    # show
     #
     # @option params [Array] :articles (sorted_articles) A list of articles to
-    #   include in the feed
+    # include in the feed
     #
     # @option params [Proc] :content_proc (->{ |article|
-    #   article.compiled_content(:snapshot => :pre) }) A proc that returns the
-    #   content of the given article, which is passed as a parameter. This
-    #   function may not return nil.
+    # article.compiled_content(:snapshot => :pre) }) A proc that returns the
+    # content of the given article, which is passed as a parameter. This
+    # function may not return nil.
     #
     # @option params [proc] :excerpt_proc (->{ |article| article[:excerpt] })
-    #   A proc that returns the excerpt of the given article, passed as a
-    #   parameter. This function should return nil if there is no excerpt.
+    # A proc that returns the excerpt of the given article, passed as a
+    # parameter. This function should return nil if there is no excerpt.
+    #
+    # @option params [String] :title The feed’s title, if it is not given in
+    # the item attributes.
+    #
+    # @option params [String] :author_name The name of the feed’s author, if
+    # it is not given in the item attributes.
+    #
+    # @option params [String] :author_uri The URI of the feed’s author, if it
+    # is not given in the item attributes.
     #
     # @return [String] The generated feed content
     def atom_feed(params={})
@@ -138,14 +155,17 @@ module Nanoc3::Helpers
       end
 
       # Check feed item attributes
-      if @item[:title].nil?
-        raise RuntimeError.new('Cannot build Atom feed: feed item has no title')
+      title = params[:title] || @item[:title] || @site.config[:title]
+      if title.nil?
+        raise RuntimeError.new('Cannot build Atom feed: no title in params, item or site config')
       end
-      if @item[:author_name].nil?
-        raise RuntimeError.new('Cannot build Atom feed: feed item has no author_name')
+      author_name = params[:author_name] || @item[:author_name] || @site.config[:author_name]
+      if author_name.nil?
+        raise RuntimeError.new('Cannot build Atom feed: no author_name in params, item or site config')
       end
-      if @item[:author_uri].nil?
-        raise RuntimeError.new('Cannot build Atom feed: feed item has no author_uri')
+      author_uri = params[:author_uri] || @item[:author_uri] || @site.config[:author_uri]
+      if author_uri.nil?
+        raise RuntimeError.new('Cannot build Atom feed: no author_uri in params, item or site config')
       end
 
       # Check article attributes
@@ -157,7 +177,10 @@ module Nanoc3::Helpers
       end
 
       # Get sorted relevant articles
-      sorted_relevant_articles = relevant_articles.sort_by { |a| Time.parse(a[:created_at]) }.reverse.first(limit)
+      sorted_relevant_articles = relevant_articles.sort_by do |a|
+        time = a[:created_at]
+        time.is_a?(String) ? Time.parse(time) : time
+      end.reverse.first(limit)
 
       # Get most recent article
       last_article = sorted_relevant_articles.first
@@ -173,10 +196,11 @@ module Nanoc3::Helpers
 
         # Add primary attributes
         xml.id      root_url
-        xml.title   @item[:title]
+        xml.title   title
 
         # Add date
-        xml.updated Time.parse(last_article[:created_at]).to_iso8601_time
+        time = last_article[:created_at]
+        xml.updated((time.is_a?(String) ? Time.parse(time) : time).to_iso8601_time)
 
         # Add links
         xml.link(:rel => 'alternate', :href => root_url)
@@ -184,8 +208,8 @@ module Nanoc3::Helpers
 
         # Add author information
         xml.author do
-          xml.name  @item[:author_name]
-          xml.uri   @item[:author_uri]
+          xml.name  author_name
+          xml.uri   author_uri
         end
 
         # Add articles
@@ -200,8 +224,10 @@ module Nanoc3::Helpers
             xml.title     a[:title], :type => 'html'
 
             # Add dates
-            xml.published Time.parse(a[:created_at]).to_iso8601_time
-            xml.updated   a.mtime.to_iso8601_time
+            create_time = a[:created_at]
+            update_time = a[:updated_at] || a[:created_at]
+            xml.published ((create_time.is_a?(String) ? Time.parse(create_time) : create_time).to_iso8601_time)
+            xml.updated   ((update_time.is_a?(String) ? Time.parse(update_time) : update_time).to_iso8601_time)
 
             # Add link
             xml.link(:rel => 'alternate', :href => url)
@@ -263,7 +289,9 @@ module Nanoc3::Helpers
       require 'time'
 
       hostname, base_dir = %r{^.+?://([^/]+)(.*)$}.match(@site.config[:base_url])[1..2]
-      formatted_date     = Time.parse(item[:created_at]).to_iso8601_date
+
+      time = item[:created_at]
+      formatted_date = (time.is_a?(String) ? Time.parse(time) : time).to_iso8601_date
 
       'tag:' + hostname + ',' + formatted_date + ':' + base_dir + (item.path || item.identifier)
     end

data/lib/nanoc3/helpers/breadcrumbs.rb

@@ -13,7 +13,7 @@ module Nanoc3::Helpers
     # will contain a `nil` element.
     #
     # @return [Array] The breadcrumbs, starting with the root item and ending
-    #   with the item itself
+    # with the item itself
     def breadcrumbs_trail
       trail = []
       current_identifier = @item.identifier

data/lib/nanoc3/helpers/capturing.rb

@@ -13,11 +13,13 @@ module Nanoc3::Helpers
   # the sidebar layout.
   #
   # @example Capturing content into a `content_for_summary` attribute
+  #
   #   <% 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>
   #     <%= @item[:content_for_summary] || '(no summary)' %>
@@ -28,8 +30,8 @@ module Nanoc3::Helpers
     # attribute named `content_for_` followed by the given name. The
     # content of the block itself will not be outputted.
     #
-    # @param [Symbol, String] The base name of the attribute into which
-    #   the content should be stored
+    # @param [Symbol, String] The base name of the attribute into which the
+    # content should be stored
     #
     # @return [void]
     def content_for(name, &block)

data/lib/nanoc3/helpers/filtering.rb

@@ -16,13 +16,14 @@ module Nanoc3::Helpers
     # 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
+    # contents of the block
     #
     # @param [Hash] argument Arguments to pass to the filter
     #