webgen 0.5.17 → 1.0.0.beta1

data/lib/webgen/context/rendering.rb

@@ -0,0 +1,39 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/content_processor/blocks'
+
+module Webgen
+  class Context
+
+    # Provides methods for rendering page blocks.
+    module Rendering
+
+      # Render the named block and return the result.
+      #
+      # call-seq:
+      #   context.render_block(block_name)
+      #   context.render_block(:name => block_name, :option => value, ...)
+      #
+      # This method uses the functionality of Webgen::ContentProcessor::Blocks for doing the actual
+      # work, so you may also want to look at Webgen::ContentProcessor::Blocks.render_block. You can
+      # call this method in two ways:
+      #
+      # [#render_block(block_name)]
+      #   Renders the block named +block_name+ of the next node in the current node chain. This is
+      #   the version that most want to use since it is equivalent to the use of '<webgen:block
+      #   name="block_name" />'. It is also equivalent to '#render_block(:name => block_name)'.
+      #
+      # [#render_block(opts_hash)]
+      #   This version allows the same level of control over the output as the blocks content
+      #   processor. For a list of valid options have a look at the documentation of the
+      #   Webgen::ContentProcessor::Blocks.render_block method!
+      #
+      def render_block(name_or_hash)
+        name_or_hash = {:name => name_or_hash} if name_or_hash.kind_of?(String)
+        Webgen::ContentProcessor::Blocks.render_block(self, name_or_hash)
+      end
+
+    end
+
+  end
+end

data/lib/webgen/context/webgen_tags.rb

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+
+module Webgen
+  class Context
+
+    # Provides methods for using webgen tags.
+    module WebgenTags
+
+      # Returns the result of evaluating the webgen tag +name+ with the tag parameters +params+ and
+      # the +body+ in the current context.
+      #
+      # Have a look at Webgen::Tag for more information about webgen tags!
+      #
+      # This method is useful when you want to have the functionality of webgen tags available but you
+      # don't want to use the content processor for them. Or, for example, if the used markup language
+      # uses a similar markup as webgen tags do and therefore you can't use the normal webgen tags
+      # content processor.
+      def tag(name, params = {}, body = '')
+        website.ext.tag.call(name, params, body, self)
+      end
+
+    end
+
+  end
+end

data/lib/webgen/core_ext.rb

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/error'
+
+# Require the given library but handle a possible loading error more gracefully.
+#
+# The parameter +gem+ (which defaults to +library+) should be set to the Rubygem that provides the
+# library or to +nil+ if no such Rubygem exists.
+def webgen_require(library, gem = library)
+  require library
+rescue LoadError
+  raise Webgen::LoadError.new(library, self.class.name, nil, gem)
+end
+
+
+class Hash
+
+  # Return a new hash where all String keys are converted to Symbol keys.
+  def symbolize_keys
+    hash = dup
+    hash.keys.each {|k| hash[(k.to_sym rescue k)] = hash.delete(k)}
+    hash
+  end
+
+end

data/lib/webgen/destination.rb

@@ -0,0 +1,151 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/extension_manager'
+require 'webgen/error'
+
+module Webgen
+
+  # Namespace for all classes that are used to write content to a specific destination.
+  #
+  # == About
+  #
+  # This class is used to manage destination classes. A destination class is a class that writes
+  # content to a specific destination. For example, the FileSystem class uses the file system to
+  # write out the generated content to the file system.
+  #
+  # The #register method is used for registering new destination classes.
+  #
+  # Since there can only be one destination class per website instance, this manager class hides the
+  # implementation details and uses the configuration option "destination" to create a new object
+  # from the correct destination class. Use the #write, #read, #exists? and #delete methods on this
+  # manager class to perform the equivalent operations on the destination class.
+  #
+  # == Implementing a destination class
+  #
+  # A destination class must respond to the following five methods:
+  #
+  # [initialize(website, *args)]
+  #   The website instance is always provided as the first argument and the initialize method can
+  #   have any number of other parameters.
+  #
+  # [exists?(path)]
+  #   Return +true+ if the given path exists.
+  #
+  # [delete(path)]
+  #   Delete the given path.
+  #
+  # [write(path, data)]
+  #   Write the +data+ to the given +path+. If +path+ ends with a slash, a directory should be
+  #   created. The parameter +data+ is either a String with the content or a Webgen::Path object. If
+  #   it is the latter, use the Webgen::Path#io method for retrieving the IO object.
+  #
+  # [read(path, mode = 'rb')]
+  #   Return the content of the given path if it exists or raise an error otherwise. The parameter
+  #   +mode+ specifies the mode in which the path should be opened and defaults to reading in binary
+  #   mode.
+  #
+  #   It seems a bit odd that a destination object has to implement reading functionality. However,
+  #   consider the case where you want webgen to render a website programmatically and *use* the
+  #   generated data. In this case you need a way to get the content of the generated files!
+  #
+  # == Sample destination class
+  #
+  # Following is a simple destination class which stores the written content in a hash in memory:
+  #
+  #   class MemoryDestination
+  #
+  #     attr_reader :data
+  #
+  #     def initialize(website)
+  #       # the website object is not used in this destination class
+  #       @data = {}
+  #     end
+  #
+  #     def exists?(path)
+  #       @data.has_key?(path)
+  #     end
+  #
+  #     def delete(path)
+  #       @data.delete(path)
+  #     end
+  #
+  #     def write(path, data)
+  #       @data[path] = (data.kind_of?(String) ? data : data.data)
+  #     end
+  #
+  #     def read(path, mode = 'rb')
+  #       raise "No such path #{path}" unless @data[path] && path[-1] != ?/
+  #       @data[path]
+  #     end
+  #   end
+  #
+  #   website.ext.destination.register MemoryDestination, :name => 'memory'
+  #
+  class Destination
+
+    include Webgen::ExtensionManager
+
+    # Create a new Destination object that is associated with the given website.
+    def initialize(website)
+      super()
+      @website = website
+    end
+
+    # Register a destination class.
+    #
+    # The parameter +klass+ has to contain the name of the destination class or the class object
+    # itself. If the class is located under this namespace, only the class name without the
+    # hierarchy part is needed, otherwise the full class name including parent module/class names is
+    # needed.
+    #
+    # === Options:
+    #
+    # [:name] The name for the destination class. If not set, it defaults to the snake-case version
+    #         (i.e. FileSystem → file_system) of the class name (without the hierarchy part). It
+    #         should only contain letters.
+    #
+    # === Examples:
+    #
+    #   destination.register('FileSystem')   # registers Webgen::Destination::FileSystem
+    #
+    #   destination.register('::FileSystem') # registers FileSystem !!!
+    #
+    #   destination.register('MyModule::Doit', name: 'doit_now')
+    #
+    def register(klass, options={}, &block)
+      do_register(klass, options, false, &block)
+    end
+
+    # Return the instance of the configured destination class.
+    def instance
+      if !defined?(@instance)
+        name, *args = @website.config['destination']
+        @instance = extension(name).new(@website, *args)
+      end
+      @instance
+    end
+    private :instance
+
+    # Return +true+ if the given path exists.
+    def exists?(path)
+      instance.exists?(path)
+    end
+
+    # Delete the given +path+
+    def delete(path)
+      instance.delete(path)
+    end
+
+    # Write the +data+ (either a String or a Webgen::Path object) to the given +path+.
+    def write(path, data)
+      instance.write(path, data) if !@website.config['website.dry_run']
+    end
+
+    # Return the content of the given +path+ which is opened in +mode+.
+    def read(path, mode = 'rb')
+      instance.read(path, mode)
+    end
+
+  end
+
+end

data/lib/webgen/destination/file_system.rb

@@ -0,0 +1,62 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/destination'
+require 'fileutils'
+
+module Webgen
+  class Destination
+
+    # This class uses the file systems as output device. On initialization a root path is set and
+    # all other operations are taken relative to this root path.
+    class FileSystem
+
+      # The root path, ie. the path to which the root node gets rendered.
+      attr_reader :root
+
+      # Create a new FileSystem object with the given +root+ path. If +root+ is not absolute, it is
+      # taken relative to the website directory.
+      def initialize(website, root)
+        @root = File.absolute_path(root, website.directory)
+      end
+
+      # Return +true+ if the given path exists.
+      def exists?(path)
+        File.exists?(File.join(@root, path))
+      end
+
+      # Delete the given +path+
+      def delete(path)
+        dest = File.join(@root, path)
+        if File.directory?(dest)
+          FileUtils.rm_rf(dest)
+        else
+          FileUtils.rm(dest)
+        end
+      end
+
+      # Write the +data+ to the given +path+.
+      def write(path, data)
+        dest = File.join(@root, path)
+        FileUtils.makedirs(File.dirname(dest))
+        if path[-1] == ?/
+          FileUtils.makedirs(dest)
+        else
+          if data.kind_of?(String)
+            File.open(dest, 'wb') {|f| f.write(data) }
+          else
+            data.io('rb') do |source|
+              File.open(dest, 'wb') {|f| FileUtils.copy_stream(source, f) }
+            end
+          end
+        end
+      end
+
+      # Return the content of the given +path+ which is opened in +mode+.
+      def read(path, mode = 'rb')
+        File.open(File.join(@root, path), mode) {|f| f.read}
+      end
+
+    end
+
+  end
+end

data/lib/webgen/error.rb

@@ -2,51 +2,63 @@
 
 module Webgen
 
-  # Custom webgen error.
+  # This error class and its descendants are only used in webgen when user-visible errors need to be
+  # created. For example, when the format of the configuration is not valid. Use the built-in Ruby
+  # error classes for all other error situations!
   class Error < StandardError
 
-    # The name of the class where the error happened.
-    attr_reader :class_name
+    # The location where the error happened (this can be set to a file name, a class name, ...).
+    attr_accessor :location
 
-    # This is either the source path or the node alcn which is responsible for the error.
-    attr_accessor :alcn
+    # Contains the path name if the error is related to a specific source or destination path,
+    attr_accessor :path
 
-    # The plain error message.
-    attr_reader :plain_message
-
-    # Create a new Error using the provided values.
+    # Create a new Error object.
     #
     # If +msg_or_error+ is a String, it is treated as the error message. If it is an exception, the
-    # exception is wrapped.
-    def initialize(msg_or_error, class_name = nil, alcn = nil)
+    # exception is wrapped. The +location+ parameter can be used to further describe where the error
+    # happened and the +path+ parameter can be used to associate a source or destination path with
+    # the error.
+    def initialize(msg_or_error, location = nil, path = nil)
       if msg_or_error.kind_of?(String)
         super(msg_or_error)
-        @plain_message = msg_or_error
       else
         super(msg_or_error.message)
         set_backtrace(msg_or_error.backtrace)
-        @plain_message = msg_or_error.message
       end
-      @class_name, @alcn = class_name, (alcn.kind_of?(Node) ? alcn.to_s : alcn)
+      @location, @path = location, path.to_s
     end
 
-    def message # :nodoc:
-      msg = 'Error while working'
-      msg += (@alcn ? " on <#{@alcn}>" : '')
-      msg += " with #{@class_name}" if @class_name
-      msg + ":\n    " + plain_message
+    def message(wrapped_msg_only = false) # :nodoc:
+      return super().gsub(/\n/, "\n    ") if wrapped_msg_only
+      msg = 'Error'
+      msg << " at #{@location}" if @location
+      msg << (!@path.to_s.empty? ? " while working on <#{@path}>" : '')
+      msg << ":\n    " << super().gsub(/\n/, "\n    ")
+    end
+
+    # Return the error line by inspecting the backtrace of the given +error+ instance.
+    def self.error_line(error)
+      (error.is_a?(::SyntaxError) ? error.message : error.backtrace[0]).scan(/:(\d+)/).first.first.to_i rescue nil
+    end
+
+    # Return the file name where the error occured.
+    def self.error_file(error)
+      (error.is_a?(::SyntaxError) ? error.message : error.backtrace[0]).scan(/(?:^|\s)(.*?):(\d+)/).first.first
     end
 
   end
 
+
   # This error is raised when an error condition occurs during the creation of a node.
   class NodeCreationError < Error
 
     def message # :nodoc:
-      msg = 'Error while creating a node'
-      msg += (@alcn ? " from <#{@alcn}>" : '')
-      msg += " with #{@class_name}" if @class_name
-      msg + ":\n    " + plain_message
+      msg = 'Error'
+      msg << " at #{@location}" if @location
+      msg << ' while creating a node'
+      msg << (!@path.to_s.empty? ? " from <#{@path}>" : '')
+      msg << ":\n    " << super(true)
     end
 
   end
@@ -55,33 +67,31 @@ module Webgen
   # This error is raised when an error condition occurs during rendering of a node.
   class RenderError < Error
 
-    # The alcn of the file where the error happened. This can be different from #alcn (e.g. a page
+    # The path of the file where the error happened. This can be different from #path (e.g. a page
     # file is rendered but the error happens in a used template).
-    attr_accessor :error_alcn
+    attr_accessor :error_path
 
-    # The line number in the +error_alcn+ where the errror happened.
+    # The line number in the +error_path+ where the errror happened.
     attr_accessor :line
 
-    # Create a new RenderError using the provided values.
-    #
-    # If +msg_or_error+ is a String, it is treated as the error message. If it is an exception, the
-    # exception is wrapped.
-    def initialize(msg_or_error, class_name = nil, alcn = nil, error_alcn = nil, line = nil)
-      super(msg_or_error, class_name, alcn)
-      @error_alcn, @line = (error_alcn.kind_of?(Node) ? error_alcn.to_s : error_alcn), line
+    # Create a new RenderError.
+    def initialize(msg_or_error, location = nil, path = nil, error_path = nil, line = nil)
+      super(msg_or_error, location, path)
+      @error_path = error_path || (Exception === msg_or_error ? self.class.error_file(msg_or_error) : nil)
+      @line = line || (Exception === msg_or_error ? self.class.error_line(msg_or_error) : nil)
     end
 
     def message # :nodoc:
-      msg = 'Error '
-      if @error_alcn
-        msg += "in <#{@error_alcn}"
+      msg = 'Error'
+      msg << " at #{@location}" if @location
+      if @error_path
+        msg += " in <#{@error_path}"
         msg += ":~#{@line}" if @line
-        msg += "> "
+        msg += ">"
       end
-      msg += 'while rendering '
-      msg += (@alcn ? "<#{@alcn}>" : 'the website')
-      msg += " with #{@class_name}" if @class_name
-      msg + ":\n    " + plain_message
+      msg << ' while rendering'
+      msg << (!@path.to_s.empty? ? " <#{@path}>" : ' the website')
+      msg << ":\n    " << super(true)
     end
 
   end
@@ -96,18 +106,18 @@ module Webgen
     # The name of the Rubygem that provides the missing library.
     attr_reader :gem
 
-    # Create a new LoadError using the provided values.
+    # Create a new LoadError.
     #
     # If +library_or_error+ is a String, it is treated as the missing library name and an approriate
     # error message is created. If it is an exception, the exception is wrapped.
-    def initialize(library_or_error, class_name = nil, alcn = nil, gem = nil)
+    def initialize(library_or_error, location = nil, path = nil, gem = nil)
       if library_or_error.kind_of?(String)
         msg = "The needed library '#{library_or_error}' is missing."
-        msg += " You can install it via rubygems with 'gem install #{gem}'!" if gem
-        super(msg, class_name, alcn)
+        msg << " You can install it with rubygems by running 'gem install #{gem}'!" if gem
+        super(msg, location, path)
         @library = library_or_error
       else
-        super(library_or_error, class_name, alcn)
+        super(library_or_error, location, path)
         @library = nil
       end
       @gem = gem
@@ -122,11 +132,11 @@ module Webgen
     # The command that is missing.
     attr_reader :cmd
 
-    # Create a new CommandNotFoundError using the provided values.
+    # Create a new CommandNotFoundError.
     #
     # The parameter +cmd+ specifies the command that is missing.
-    def initialize(cmd, class_name = nil, alcn = nil)
-      super("The needed command '#{cmd}' is missing!", class_name, alcn)
+    def initialize(cmd, location = nil, path = nil)
+      super("The needed command '#{cmd}' is missing!", location, path)
       @cmd = cmd
     end