thewoolleyman-webgen 0.5.8.20090419

data/doc/webgen_page_format.page

@@ -0,0 +1,129 @@
+---
+title: Webgen Page Format
+---
+## Webgen Page Format
+
+The Webgen Page Format is a custom format designed primarily for page and template files. It
+consists of an optional meta information block and one or more blocks of data; it is very simple and
+easy to use.
+
+## Structure
+
+A file using the Webgen Page Format consists of one or more blocks which are the smallest units
+recognized. Blocks are separated from each other through a line containing three dashes. This is
+illustrated in the following examples which are all valid files in WebPage Format:
+
+Example 1:
+
+    Here is a block!
+
+Example 2:
+
+    This is one block of the file
+    ---
+    This is another block.
+
+Example 3:
+
+    Block 1
+    --- name:block2
+    Block 2
+    --- name:block3
+    Block 3...
+
+If you want to use three dashes in a block but you don't want to end the block, you have to escape
+them with a backslash character, like this:
+
+    Block 1
+    \---
+    still Block 1
+    --- name:block2
+    Block 2
+
+All of the above examples show one kind of block, the content block. However, there may also be
+another type of block: the meta information block. Following is a short description of both kinds,
+starting with the meta information block.
+
+
+### Meta Information Block
+
+Each file in Webgen Page Format can have zero or one meta information blocks. This block is
+specified at the beginning of the file. To tell the parser that the first block is the meta
+information block and not a content block, you have to start the file with three dashes:
+
+    ---
+    title: The title set by Meta info
+    ---
+    This is the content of the file
+
+The above defines a meta information block and a content block. The meta information block has to be
+in YAML format and should contain key-value pairs of meta information. [YAML](http://www.yaml.org)
+is a simple markup language designed for ease of use and although you define structured data with
+it, it feels like just writing a plain text document.
+
+
+### Content Blocks
+
+A content block is used to provide content in a specific format. Each file in Webgen Page Format
+needs to have at least one content block which may be empty. However, it can have as many content
+blocks as necessary. This functionality can be used, for example, to provide the main content of an
+HTML page in one block and sidebar content in another one.
+
+Each content block needs to have a unique name and additional options can also be set. The name
+uniquely identifies a content block and is used to access it. The only option used by webgen is the
+`pipeline` option which specifies the processing pipeline for the block. The processing pipeline is
+used for rendering the block by using the specified content processors in the specified order. There
+are many different content processors available - have a look at the [extensions page]({relocatable:
+extensions.html}) for an overview.
+
+webgen extensions that use files in Webgen Page Format may specify defaults for the name and the
+options of a block but these defaults can be overwritten. You can use one of two ways to do this:
+
+* you either specify the name and additional options of the block on the starting line with the
+  three dashes
+
+* or you use the special meta information `block` to define the names and options of one or all
+  blocks.
+
+The following example uses the first technique to override the name and/or the `pipeline` option:
+
+    1. content block of the file
+    --- name:sidebar pipeline:maruku,tags
+    2. content block of the file
+    --- name:other
+    3. content block of the file
+
+The first block has no identifieres set (there is no line with three dashes and the identifieres).
+Therefore the default value for the name is used: `content`. The second block is named `sidebar` and
+uses the processing pipeline `maruku,tags`. As you can see, the name of a block as well as
+additional options are specified by stating the key (e.g. `name` or `pipeline`) followed by a colon
+and the value. Multiple options are separated via one or more spaces. The value of a block option is
+parsed with YAML. For example, when specifying `use_something:true` the value `true` is
+automatically converted from the string `true` to the boolean `true`.
+
+> Only the first block gets the default name of `content`. The second and following blocks have
+> numbered names like `block2`, `block3` and so on.
+{.information}
+
+You can also set the name and additional options of the content blocks by using the special `blocks`
+meta information. It is a hash using the index of a block (or the special value `default`) as key
+and the options as values. The above example can therefore also be written like this:
+
+    ---
+    blocks: \{2: {name: sidebar, pipeline: maruku,tags}, 3: {name: other}}
+    ---
+    1. content block of the file
+    ---
+    2. content block of the file
+    ---
+    3. content block of the file
+
+When selecting a value for the name of a block or an option, the following precedence is used (from
+low to high):
+
+* global defaults set via the `default` key of the meta information `blocks`
+* block defaults set via the meta information `blocks`
+* the `--- line` options
+
+As stated above, the "option" `name` is special insofar that when it is not set, an automatic name
+gets generated.

data/lib/webgen/blackboard.rb

@@ -0,0 +1,78 @@
+# -*- encoding: utf-8 -*-
+
+module Webgen
+
+  # A blackboard object provides two features for inter-object communication:
+  #
+  # * *services*: An object can add a service to the blackboard which can be called by any other
+  #   object by just specifing the service name. Therefore it is easy to change the underlying
+  #   implementation of the service and there are no hard dependencies on specific class or method
+  #   names.
+  #
+  # * *listeners*: Objects may register themselves for specific messsage names and get notified when
+  #   such a message gets dispatched.
+  #
+  # For a list of all available services and messages have a look at the main Webgen documentation
+  # page.
+  class Blackboard
+
+    # Create a new Blackboard object.
+    def initialize
+      @listener = {}
+      @services = {}
+    end
+
+    # Add the +callable_object+ or the given block as listener for the messages +msg_names+ (one
+    # message name or an array of message names).
+    def add_listener(msg_names = nil, callable_object = nil, &block)
+      callable_object = callable_object || block
+      if !callable_object.nil?
+        raise ArgumentError, "The listener needs to respond to 'call'" unless callable_object.respond_to?(:call)
+        [msg_names].flatten.compact.each {|name| (@listener[name] ||= []) << callable_object}
+      else
+        raise ArgumentError, "You have to provide a callback object or a block"
+      end
+    end
+
+    # Remove the given object from the dispatcher queues of the message names specified in
+    # +msg_names+.
+    def del_listener(msg_names, callable_object)
+      [msg_names].flatten.each {|name| @listener[name].delete(callable_object) if @listener[name]}
+    end
+
+    # Dispatch the message +msg_name+ to all listeners for this message, passing the given
+    # arguments.
+    def dispatch_msg(msg_name, *args)
+      return unless @listener[msg_name]
+      @listener[msg_name].each {|obj| obj.call(*args)}
+    end
+
+    # Add a service named +service_name+ provided by the +callable_object+ or a block to the
+    # blackboard.
+    def add_service(service_name, callable_object = nil, &block)
+      callable_object = callable_object || block
+      if @services.has_key?(service_name)
+        raise "The service name '#{service_name}' is already taken"
+      else
+        raise ArgumentError, "An object providing a service needs to respond to 'call'" unless callable_object.respond_to?(:call)
+        @services[service_name] = callable_object
+      end
+    end
+
+    # Delete the service +service_name+.
+    def del_service(service_name)
+      @services.delete(service_name)
+    end
+
+    # Invoke the service called +service_name+ with the given arguments.
+    def invoke(service_name, *args, &block)
+      if @services.has_key?(service_name)
+        @services[service_name].call(*args, &block)
+      else
+        raise ArgumentError, "No such service named '#{service_name}' available"
+      end
+    end
+
+  end
+
+end

data/lib/webgen/cache.rb

@@ -0,0 +1,87 @@
+# -*- encoding: utf-8 -*-
+
+require 'set'
+require 'facets/kernel/constant'
+
+module Webgen
+
+  # A cache object provides access to various caches to speed up rendering of a website:
+  #
+  # [permanent] The permanent cache should be used for data that should be available between webgen
+  #             runs.
+  #
+  # [volatile] The volatile cache is used for data that can easily be regenerated but might be
+  #            expensive to do so. This cache is not stored between webgen runs.
+  #
+  # [standard] The standard cache saves data between webgen runs and returns the cached data (not
+  #            the newly set data) if it is available. This is useful, for example, to store file
+  #            modifcation times and check if a file has been changed between runs.
+  #
+  # The standard cache should be accessed through the <tt>[]</tt> method which returns the correct
+  # value and the <tt>[]=</tt> method should be used for setting the new value. However, if you
+  # really need to access a particular value of the old or new standard cache, you can use the
+  # accessors +old_data+ and +new_data+.
+  class Cache
+
+    # The permanent cache hash.
+    attr_reader :permanent
+
+    # The volatile cache hash.
+    attr_reader :volatile
+
+    # The cache data stored in the previous webgen run.
+    attr_reader :old_data
+
+    # The cache data stored in the current webgen run.
+    attr_reader :new_data
+
+    # Create a new cache object.
+    def initialize()
+      @old_data = {}
+      @new_data = {}
+      @volatile = {}
+      @permanent = {:classes => []}
+    end
+
+    # Return the cached data (or, if it is not available, the new data) identified by +key+ from the
+    # standard cache.
+    def [](key)
+      if @old_data.has_key?(key)
+        @old_data[key]
+      else
+        @new_data[key]
+      end
+    end
+
+    # Store +value+ identified by +key+ in the standard cache.
+    def []=(key, value)
+      @new_data[key] = value
+    end
+
+    # Restore the caches from +data+ and recreate all cached instances (see #instance).
+    def restore(data)
+      @old_data, @permanent = *data
+      @permanent[:classes].each {|klass| instance(klass)}
+    end
+
+    # Return all caches that should be available between webgen runs.
+    def dump
+      [@old_data.merge(@new_data), @permanent]
+    end
+
+    # Reset the volatile cache.
+    def reset_volatile_cache
+      @volatile = {:classes => @volatile[:classes]}
+    end
+
+    # Return the unique instance of the class +name+. This method should be used when it is
+    # essential that webgen uses only one object of a class or when an object should automatically
+    # be recreated upon cache restoration (see #restore).
+    def instance(name)
+      @permanent[:classes] << name unless @permanent[:classes].include?(name)
+      (@volatile[:classes] ||= {})[name] ||= constant(name).new
+    end
+
+  end
+
+end

data/lib/webgen/cli.rb

@@ -0,0 +1,124 @@
+# -*- encoding: utf-8 -*-
+
+require 'cmdparse'
+require 'webgen/website'
+require 'webgen/version'
+
+module Webgen
+
+  # Namespace for all classes that act as CLI commands.
+  #
+  # == Implementing a CLI command
+  #
+  # Each CLI command class needs to be put into this module and has to end with +Command+, otherwise
+  # it is not used. A CLI command is an extension that can be invoked from the webgen command and
+  # thus needs to be derived from CmdParse::Command. For detailed information on this class and the
+  # whole cmdparse package have a look at http://cmdparse.rubyforge.org!
+  #
+  # == Sample CLI command
+  #
+  # Here is a sample CLI command extension:
+  #
+  #   require 'webgen/cli'
+  #
+  #   class Webgen::CLI::SampleCommand < CmdParse::Command
+  #
+  #     def initialize
+  #       super('sample', false)
+  #       self.short_desc = "This sample command just outputs its parameters"
+  #       self.description = Utils.format("Uses the global verbosity level and outputs additional " +
+  #         "information when the level is set to verbose!")
+  #       @username = nil
+  #       self.options = CmdParse::OptionParserWrapper.new do |opts|
+  #         opts.separator "Options:"
+  #         opts.on('-u', '--user USER', String,
+  #           'Specify an additional user name to output') {|@username|}
+  #       end
+  #     end
+  #
+  #     def execute(args)
+  #       if args.length == 0
+  #         raise OptionParser::MissingArgument.new('ARG1 [ARG2 ...]')
+  #       else
+  #         puts "Command line arguments:"
+  #         args.each {|arg| puts arg}
+  #         if commandparser.verbosity == :verbose
+  #           puts "Yeah, some additional information is always cool!"
+  #         end
+  #         puts "The entered username: #{@username}" if @username
+  #       end
+  #     end
+  #
+  #   end
+  #
+  # Note the use of Utils.format in the initialize method so that the long text gets wrapped
+  # correctly! The Utils class provides some other useful methods, too!
+  #
+  # For information about which attributes are available on the webgen command parser instance have
+  # a look at Webgen::CLI::CommandParser!
+  module CLI
+
+    autoload :RunCommand, 'webgen/cli/run_command'
+    autoload :CreateCommand, 'webgen/cli/create_command'
+    autoload :WebguiCommand, 'webgen/cli/webgui_command'
+    autoload :ApplyCommand, 'webgen/cli/apply_command'
+
+    autoload :Utils, 'webgen/cli/utils'
+
+
+    # This is the command parser class used for handling the webgen command line interface. After
+    # creating an instance, the inherited #parse method can be used for parsing the command line
+    # arguments and executing the requested command.
+    class CommandParser < CmdParse::CommandParser
+
+      # The website directory. Default: the current working directory.
+      attr_reader :directory
+
+      # The verbosity level. Default: <tt>:normal</tt>
+      attr_reader :verbosity
+
+      # The log level. Default: <tt>Logger::WARN</tt>
+      attr_reader :log_level
+
+      # Create a new CommandParser class. The default webgen website (if not specified via the
+      # <tt>-d</tt> option) is taken from the environment variable +WEBGEN_WEBSITE+ or, if it is not
+      # set or empty, the current working directory.
+      def initialize # :nodoc:
+        super(true)
+        @directory = (ENV['WEBGEN_WEBSITE'].to_s.empty? ? Dir.pwd : ENV['WEBGEN_WEBSITE'])
+        @verbosity = :normal
+        @log_level = ::Logger::WARN
+        @log_filter = nil
+
+        self.program_name = "webgen"
+        self.program_version = Webgen::VERSION
+        self.options = CmdParse::OptionParserWrapper.new do |opts|
+          opts.separator "Global options:"
+          opts.on("--directory DIR", "-d", String, "The website directory (default: the current directory)") {|p| @directory = p}
+          opts.on("--verbose", "-v", "Print more output") { @verbosity = :verbose }
+          opts.on("--quiet", "-q", "No output") { @verbosity = :quiet }
+          opts.on("--log-level LEVEL", "-l", Integer, "The logging level (0..debug, 3..error)") {|p| @log_level = p}
+          opts.on("--log-filter", "-f", Regexp, 'Filter for logging events') {|p| @log_filter = p}
+        end
+        self.add_command(CmdParse::HelpCommand.new)
+        self.add_command(CmdParse::VersionCommand.new)
+        Webgen::CLI.constants.select {|c| c =~ /.+Command$/ }.each do |c|
+          self.add_command(Webgen::CLI.const_get(c).new, (c.to_s == 'RunCommand' ? true : false))
+        end
+      end
+
+      # Utility method for sub-commands to create the correct Webgen::Website object.
+      def create_website
+        website = Webgen::Website.new(@directory) do |config|
+          config['logger.mask'] = @log_filter
+        end
+        website.logger.level = @log_level
+        website.logger.verbosity = @verbosity
+        website
+      end
+
+    end
+
+  end
+
+end

data/lib/webgen/cli/apply_command.rb

@@ -0,0 +1,64 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/cli'
+require 'webgen/websitemanager'
+
+module Webgen::CLI
+
+  # The CLI command for applying a style to a webgen website.
+  class ApplyCommand < CmdParse::Command
+
+    def initialize #:nodoc:
+      super('apply', false)
+      @force = false
+
+      self.short_desc = 'Apply a website style to an existing webgen website'
+      self.options = CmdParse::OptionParserWrapper.new do |opts|
+        opts.separator "Options:"
+        opts.on('-f', '--[no-]force', 'Specifies whether files should be overwritten (default: no)') do |val|
+          @force = val
+        end
+        opts.separator ""
+        opts.separator "Arguments:"
+        opts.separator opts.summary_indent + "STYLE: the style the should be applied to the website"
+      end
+    end
+
+    def usage # :nodoc:
+      "Usage: #{commandparser.program_name} [global options] apply [options] STYLE"
+    end
+
+    def show_help # :nodoc:
+      super
+      wm = Webgen::WebsiteManager.new(commandparser.directory)
+
+      puts
+      puts "Available styles:"
+      puts Utils.headline('Styles')
+      wm.styles.sort.each {|name, entry| Utils.hash_output(name, entry.instance_eval { @table }) }
+    end
+
+    # Apply the style specified in <tt>args[0]</tt> to the webgen website.
+    def execute(args)
+      wm = Webgen::WebsiteManager.new(commandparser.directory)
+      if !File.directory?(commandparser.directory)
+        puts "You need to specify a valid webgen website directory!"
+      elsif args.length == 0
+        raise OptionParser::MissingArgument.new('STYLE')
+      elsif !wm.styles.has_key?(args[0])
+        raise OptionParser::InvalidArgument.new("#{args[0]} is not a valid style")
+      else
+        puts "The following files in the website directory will be created or overwritten:"
+        puts wm.styles[args[0]].paths.to_a.sort.join("\n")
+        continue = @force
+        if !continue
+          print "Procede? (yes/no): "
+          continue = ($stdin.readline =~ /y(es)?/)
+        end
+        wm.apply_style(args[0]) if continue
+      end
+    end
+
+  end
+
+end