zen 0.2.8 → 0.3b

data/lib/zen/plugin.rb

@@ -1,182 +0,0 @@
-require __DIR__('error/plugin_error')
-require __DIR__('plugin/base')
-
-#:nodoc:
-module Zen
-  ##
-  # Plugins in Zen are quite similar to packages except for a few differences.
-  # The biggest difference is that plugins won't update any Ramaze root
-  # directories or language directories. This means that they can't have
-  # controllers, models and so on. Plugins are useful for supporting multiple
-  # markup formats (Markdown, Textile, etc) and other small tasks such as
-  # replacing Email addresses and so on.
-  #
-  # ## Creating Plugins
-  #
-  # Creating a plugin happens in two steps. First you'll create your class and
-  # then you'll register it so that it can be used by the system. A plugin has
-  # a very simple layout, it's just a class with two methods: initialize and
-  # call. The most basic skeleton of a plugin looks like the following:
-  #
-  #     class MyPlugin
-  #       def initialize
-  #
-  #       end
-  #
-  #       def call
-  #
-  #       end
-  #     end
-  #
-  # When a plugin is called all specified arguments are sent to the construct
-  # method so if your plugin requires a number of arguments be sure to store
-  # them. An example of this looks like the following:
-  #
-  #     class MyPlugin
-  #       def initialize(name)
-  #         @name = name
-  #       end
-  #
-  #       def call
-  #
-  #       end
-  #     end
-  #
-  # The call method is supposed to return some data. Say we want to capitalize
-  # a given name we'd modify the skeleton so that it looks like the following:
-  #
-  #     class MyPlugin
-  #       def initialize(name)
-  #         @name = name
-  #       end
-  #
-  #       def call
-  #         return @name.upcase
-  #       end
-  #     end
-  #
-  # ## Registering Plugins
-  #
-  # Now that the plugin is created it's time to tell Zen it actually is a plugin
-  # and not some random class that doesn't belong somewhere. This can be done
-  # by calling Zen::Plugin.add and specifying a block with the details of the
-  # plugin. Example:
-  #
-  #     Zen::Plugin.add do |plugin|
-  #       plugin.name   = :my_plugin
-  #       plugin.author = 'Your name goes in here'
-  #       plugin.about  = 'A simple plugin that capitalizes a given string/name'
-  #       plugin.plugin = MyPlugin
-  #     end
-  #
-  # The name and plugin setter are the most important. Names should always match
-  # the regular expression /[a-z0-9_\-]+/. This is done to ensure names are
-  # consistent and easy to remember. It's also used for calling plugins and
-  # making sure there are no duplicates.
-  #
-  # The second important part is the plugin setting. This setter takes the class
-  # constant of the plugin that was created earlier on. There's no need to call
-  # new(), this will be done by Zen whenever the plugin is actually used.
-  #
-  # ## Executing Plugins
-  #
-  # Executing plugins is very easy and can be done by using the global method
-  # plugin():
-  #
-  #     plugin(:my_plugin, 'yorick') # => "YORICK"
-  #
-  # The first argument is the name of the plugin to call, all following
-  # arguments will be sent to the plugin's construct method.
-  #
-  # @author Yorick Peterse
-  # @since  0.2.4
-  #
-  module Plugin
-    ##
-    # Hash containing all registered plugins. The keys are the names of the
-    # plugins and the values are instances of Zen::Plugin::Base.
-    #
-    # @author Yorick Peterse
-    # @since  0.2.5
-    #
-    Registered = {}
-
-    ##
-    # Adds a new plugin with the given details.
-    #
-    # @author Yorick Peterse
-    # @since  0.2.4
-    # @raise  [Zen::PluginError] Error raised whenever the plugin already exists
-    # or is missing a certain setter.
-    #
-    def self.add
-      plugin = Zen::Plugin::Base.new
-
-      yield plugin
-
-      # Validate the plugin
-      plugin.validate
-      plugin.name = plugin.name.to_sym
-
-      Registered[plugin.name] = plugin
-    end
-
-    ##
-    # Returns a plugin for the given name.
-    #
-    # @example
-    #  Zen::Plugin[:markup]
-    #
-    # @author Yorick Peterse
-    # @since  0.2.4
-    # @param  [String] name The name of the plugin to retrieve.
-    # @raise  Zen::PluginError Error that's raised when no plugins have been
-    # added yet or the specified plugin doesn't exist.
-    # @return [Struct] Instance of the plugin.
-    #
-    def self.[](name)
-      name = name.to_sym if name.class != Symbol
-
-      if !Registered[name]
-        raise(Zen::PluginError, "The plugin #{name} doesn't exist.")
-      end
-
-      return Registered[name]
-    end
-
-    ##
-    # @author Yorick Peterse
-    # @since  0.2.8
-    # @see    Zen::Plugin::SingletonMethods#plugin
-    #
-    def self.plugin(name, *data, &block)
-      if name.class != Symbol
-        name = name.to_sym
-      end
-
-      return ::Zen::Plugin[name].plugin.new(*data, &block).call
-    end
-
-    #:nodoc:
-    module SingletonMethods
-      ##
-      # Retrieves the given plugin and executes it. All specified parameters
-      # will be sent to the plugin as well.
-      #
-      # @example
-      #  plugin(:settings, :get, :language)
-      #
-      # @author Yorick Peterse
-      # @since  0.2.5
-      # @param  [String/Symbol] name The name of the plugin to call.
-      # @param  [Array] data Any data to pass to the plugin's action (a lambda).
-      # @param  [Proc] block A block that should be passed to the plugin instead
-      # of this method.
-      # @return [Mixed]
-      #
-      def plugin(name, *data, &block)
-        ::Zen::Plugin.plugin(name, *data, &block)
-      end
-    end # SingletonMethods
-  end # Plugin
-end # Zen

data/lib/zen/plugin/base.rb

@@ -1,46 +0,0 @@
-#:nodoc:
-module Zen
-  #:nodoc:
-  module Plugin
-    ##
-    # Base class used to store the data about plugins such as the name, plugin class, etc.
-    #
-    # @author Yorick Peterse
-    # @since  0.2.5
-    #
-    class Base
-      include ::Zen::Validation
-
-      # The name of the plugin
-      attr_accessor :name
-
-      # The author of the plugin
-      attr_accessor :author
-
-      # A small description of the plugin
-      attr_accessor :about
-
-      # The URL to the plugin's website
-      attr_accessor :url
-
-      # The class of the plugin
-      attr_accessor :plugin
-
-      ##
-      # Validates all the attributes.
-      #
-      # @author Yorick Peterse
-      # @since  0.2.5
-      #
-      def validate
-        validates_presence([:name, :author, :about, :plugin])
-        validates_format(:name, /[a-z0-9_\-]+/)
-
-        # Check if the theme doesn't exist
-        if ::Zen::Plugin::Registered.key?(name.to_sym)
-          raise(::Zen::ValidationError, "The plugin #{name} already exists.")
-        end
-      end
-    end
-  end
-end

data/lib/zen/plugin/helper.rb

@@ -1,47 +0,0 @@
-#:nodoc:
-module Zen
-  #:nodoc:
-  module Plugin
-    ##
-    # Module containing various methods that can be used for developing plugins.
-    #
-    # @author Yorick Peterse
-    # @since  0.2.5
-    #
-    module Helper
-
-      ##
-      # Method that can be used to validate the class of a given variable. If the class
-      # isn't included in the whitelist an error will be triggered explaining the error.
-      #
-      # @example
-      #  username = 10
-      #  validate_type(username, :username, [String]) # => TypeError: "\"username\" can only
-      #  be an instance of String but got Integer."
-      #
-      # @author Yorick Peterse
-      # @since  0.2.5
-      # @param  [Mixed] variable The variable to validate.
-      # @param  [Symbol/String] name The name of the variable to validate.
-      # @param  [Array] whitelist Whitelist of the allowed classes.
-      # @raise  TypeError Raised whenever the variable's class wasn't allowed.
-      #
-      def validate_type(variable, name, whitelist)
-        if whitelist.class != Array
-          whitelist = [whitelist]
-        end
-
-        name    = name.to_s
-        classes = whitelist.join(' or ').to_s
-
-        if !whitelist.include?(variable.class)
-          raise(
-            TypeError, 
-            "\"#{name}\" can only be an instance of #{classes} but got #{variable.class}"
-          )
-        end
-      end
-
-    end
-  end
-end

data/lib/zen/plugin/markup/lib/markup.rb

@@ -1,14 +0,0 @@
-# Load our language packs
-Zen::Language.options.paths.push(__DIR__('markup'))
-Zen::Language.load('markup')
-
-# Load the actual plugin
-require __DIR__('markup/markup')
-
-# Describe the plugin
-Zen::Plugin.add do |plugin|
-  plugin.name    = 'markup'
-  plugin.author  = 'Yorick Peterse'
-  plugin.about   = 'Plugin used for converting various markup formats to HTML.'
-  plugin.plugin  = Zen::Plugin::Markup
-end

data/lib/zen/plugin/markup/lib/markup/language/en/markup.yml

@@ -1,6 +0,0 @@
----
-engines:
-  html     : 'HTML'
-  markdown : 'Markdown'
-  textile  : 'Textile'
-  plain    : 'Plain text'

data/lib/zen/plugin/markup/lib/markup/markup.rb

@@ -1,165 +0,0 @@
-#:nodoc
-module Zen
-  #:nodoc
-  module Plugin
-    ##
-    # The Markup plugin is used to convert the given markup using the specified
-    # engine.  Out of the box this plugin is capable of doing the following:
-    #
-    # * Markdown -> HTML
-    # * Textile -> HTML
-    # * HTML -> Plain text (escapes HTML)
-    # * Regular HTML
-    #
-    # When using Markdown you'll have to make sure RDiscount is loaded, for
-    # Textile this should be RedCloth.
-    #
-    # ## Usage
-    #
-    # Using this plugin can be done as following::
-    #
-    #     plugin(:markup, :markdown, "hello **world**")
-    #
-    # ## Adding Engines
-    #
-    # In order to add a custom markdown engine (e.g. RDoc) you'll have to update
-    # Zen::Plugin::Markup::Engines so that it includes the name and human
-    # readable name of the engine you wish to use. This can be done as
-    # following:
-    #
-    #     Zen::Plugin::Markup::Engines[:rdoc] => 'RDoc'
-    #
-    # Once this is done you'll need to define a method that matches the key
-    # you've just added. In this case it will be named "rdoc":
-    #
-    #     module Zen
-    #       module Plugin
-    #         class Markup
-    #           def rdoc(markup)
-    #             # Do something with the markup in the variable "markup"
-    #           end
-    #         end
-    #       end
-    #     end
-    #
-    # Once this has been done you're able to convert RDoc markup to HTML using
-    # this plugin.
-    #
-    # @author Yorick Peterse
-    # @since  0.2.5
-    #
-    class Markup
-      include Ramaze::Helper::CGI
-
-      # Load the language pack in the class method scope rather than the
-      # instance's scope
-      class << self
-        include Zen::Language
-      end
-
-      ##
-      # Hash containing the keys of the engines to use and their human friendly
-      # names (used in the backend). Note that the keys of this hash should be
-      # strings.
-      #
-      # @author Yorick Peterse
-      # @since  0.2.5
-      #
-      Engines = {
-        'markdown' => lang('markup.engines.markdown'),
-        'textile'  => lang('markup.engines.textile'),
-        'plain'    => lang('markup.engines.plain'),
-        'html'     => lang('markup.engines.html')
-      }
-
-      ##
-      # Creates a new instance of the markup plugin and validates all the given
-      # parameters.
-      #
-      # @author Yorick Peterse
-      # @since  0.2.5
-      # @param  [Symbol] engine The markup engine to use (e.g. :markdown).
-      # @param  [String] markup The markup to convert to HTML or something else.
-      #
-      def initialize(engine = 'markdown', markup = '')
-        @engine, @markup = engine.to_s, markup
-
-        # Validate the given engine
-        if !Engines.keys.include?(@engine)
-          raise(
-            ArgumentError,
-            "The markup engine \"#{@engine}\" is invalid."
-          )
-        end
-
-        # Does the engine have a matching method?
-        if !respond_to?(@engine)
-          raise(
-            NoMethodError,
-            "The engine \"#{@engine}\" has no matching method."
-          )
-        end
-      end
-
-      ##
-      # Converts the markup into HTML or plain text.
-      #
-      # @author Yorick Peterse
-      # @since  0.2.5
-      # @return [String] The converted markup.
-      #
-      def call
-        return send(@engine, @markup)
-      end
-
-      ##
-      # Converts the Markdown markup to HTML using RDiscount.
-      #
-      # @author Yorick Peterse
-      # @since  0.2.5
-      # @param  [String] markup The Markdown string to convert to HTML.
-      # @return [String] The HTML returned by RDiscount.
-      #
-      def markdown(markup)
-        return RDiscount.new(markup).to_html
-      end
-
-      ##
-      # Converts Textile to HTML using RedCloth.
-      #
-      # @author Yorick Peterse
-      # @since  0.2.5
-      # @param  [String] markup The Textile markup to convert to HTML.
-      # @return [String] The HTML returned by RedCloth.
-      #
-      def textile(markup)
-        return RedCloth.new(markup).to_html
-      end
-
-      ##
-      # Escapes all HTML using Ramaze::Helper::CGI.
-      #
-      # @author Yorick Peterse
-      # @since  0.2.5
-      # @param  [String] markup The markup in which all HTML tags should be
-      # escaped.
-      # @return [String] String containing the escaped HTML.
-      #
-      def plain(markup)
-        return h(markup)
-      end
-
-      ##
-      # Ignores the markup and just returns it.
-      #
-      # @author Yorick Peterse
-      # @since  0.2.5
-      # @param  [String] markup The markup to return.
-      # @return [String] String containing our markup.
-      #
-      def html(markup)
-        return markup
-      end
-    end # Markup
-  end # Plugin
-end # Zen