mango 0.5.4 → 0.6.0

data/lib/mango/content_page.rb

@@ -1,18 +1,15 @@
 # encoding: UTF-8
 
-require "bluecloth"
-require "haml"
+require "english"
 require "yaml"
 
 module Mango
   # `ContentPage` is a **model** class.  An instance of `ContentPage` is the representation of a
   # single content file.  The primary responsiblity of `ContentPage` is to manage the conversion of
-  # user-generated data into HTML.  It accomplishes this task by utilizing 3rd-party content
-  # engines, which convert easy-to-read, easy-to-write plain text and markup into structurally
-  # valid HTML.
+  # user-generated data into markup like HTML.  It accomplishes this task by utilizing a variety of
+  # content engines.
   #
-  # `ContentPage` instances have two primary components -- **a body** and some **attributes**.
-  # Each component is defined within a single content file.
+  # A `ContentPage` file contains **a body** and possibly **a header**.
   #
   # ### Example content file
   #
@@ -31,163 +28,140 @@ module Mango
   # Mangos aside, let's bring attention to a few important facets of this example and content files
   # in general.
   #
-  # 1. Content pages are stored as files on disk.  Here, the file name is `mango_poem.markdown`.
-  # 2. Attributes are defined first, embedded within triple-dashed ("---") dividers.
-  # 3. The body comes second, nestled comfortably below the attributes header.
-  # 4. Attributes are key-value pairs, defined with [YAML](http://www.yaml.org/) formatting.
-  # 5. The body, in this example, is plain-text.  Because of the file extension, it's interpretted
-  #    as Markdown.
+  # 1. A content page is stored as file on disk.  Here, the file name is `mango_poem.markdown`.
+  # 2. The header is defined first, embedded within triple-dashed ("---") dividers.
+  # 3. The body comes second, nestled comfortably below the header.
+  # 4. The header is composed of key-value attribute pairs in [YAML](http://www.yaml.org/) format.
+  # 5. The file's extension signals that the body should treated as Markdown.
   #
-  # ### The Body
-  #
-  # The body of a content file may be written using one of the following human-friendly formats:
-  #
-  #   * [Markdown](http://daringfireball.net/projects/markdown/syntax) extended with
-  #     `Mango::FlavoredMarkdown`
-  #   * [Haml](http://haml-lang.com/)
-  #
-  # The content file's extension determines the body's formatting.  For a complete list of content
-  # file formats and their extensions, see `Mango::ContentPage::CONTENT_ENGINES`
+  # ### The Header
   #
-  # `ContentPage` instances are expected to be passed along into the view template they define.
-  # Once in that scope, the instance can convert its body to HTML with the `#to_html` method:
+  # The header is composed of key-value attribute pairs in [YAML](http://www.yaml.org/) format.
   #
-  #     @content_page.to_html
+  # Each `ContentPage` instance is passed into their body and view templates as the `page` local
+  # variable.  For example, this is how to access the header attributes of a content page inside an
+  # ERB template:
   #
-  # ### The Attributes
+  #     <h1><%= page.title %></h1>
   #
-  # Attributes are key-value pairs, defined with [YAML](http://www.yaml.org/) formatting.
+  # ### The Body
   #
-  # All `ContentPage` instances have a `view` attribute, even if one is not explicitly declared in
-  # the content file.  This attribute is essential as it guides the `Mango::Application` to render
-  # the correct view template file.
+  # The body of a content file can be written in many human and designer friendly formats.  It's the
+  # content file's extension that determines the format, and therefore, the template engine used to
+  # convert the body into markup like HTML.  For a list of supported content page template engines,
+  # and their formats, see `Mango::ContentPage::TEMPLATE_ENGINES`.
   #
-  # When declaring an explicit view template, only the base file name is important. **It's assumed
-  # that all view templates are in Haml format.**  The default view template file name is defined
-  # by `Mango::ContentPage::DEFAULT["attributes"]`.
+  # Each `ContentPage` instance is passed into their body and view templates as the `page` local
+  # variable.  For example, this is how to access the raw data, unrendered body, and rendered
+  # content of a content page inside an ERB template:
   #
-  # Syntactic sugar has been added for accessing attribtues.  For example:
+  #     <p><%= page.data %></p>
+  #     <p><%= page.body %></p>
+  #     <p><%= page.content %></p>
   #
-  #     @content_page.attributes["title"]
+  # ### The View Attribute and Template
   #
-  # can be shortened to
+  # Each `ContentPage` instance has a `view` attribute, even if one is not explicitly declared in
+  # the content file.  This attribute is essential as it guides the `Mango::Application` to render
+  # the correct view template file.  The default view template file name is defined by
+  # `Mango::ContentPage::DEFAULT_ATTRIBUTES`.
   #
-  #     @content_page.title
+  # When declaring an explicit view template, the relative file name is required.  For example,
+  # given the following content page:
   #
-  # Again, `ContentPage` instances are expected to be passed along into the view template they
-  # define.  With a `@content_page` instance in scope, accessing attributes inside a Haml template
-  # works like this:
+  #     ---
+  #     view: blog.haml
+  #     ---
   #
-  #     %title
-  #       = @content_page.title
+  # The `Mango::Application` will attempt to render the content page within the `blog.haml` view
+  # template if it exists in the `Mango::Application.settings.views` directory.  The supported view
+  # template engines are defined by `Mango::Application::VIEW_TEMPLATE_ENGINES`.
   #
-  # @see Mango::FlavoredMarkdown
+  # @see FlavoredMarkdown
+  # @see Application::VIEW_TEMPLATE_ENGINES
   #
   class ContentPage
-    class PageNotFound < RuntimeError; end
+    # @see http://goo.gl/z2Zzk
+    class InvalidHeaderError < RuntimeError; end
 
-    # Known content formats and their associated file extensions
-    CONTENT_ENGINES = {
-      :markdown => ["md", "mdown", "markdown"],
-      :haml     => ["haml"]
+    # Supported content page template engines
+    TEMPLATE_ENGINES = {
+      Tilt::BlueClothTemplate => :markdown,
+      Tilt::HamlTemplate      => :haml,
+      Tilt::ERBTemplate       => :erb,
+      Tilt::LiquidTemplate    => :liquid
     }
 
-    # Default values for various accessors
-    DEFAULT = {
-      :attributes     => { "view" => :page },
-      :body           => "",
-      :content_engine => :markdown
+    # Default key-value attribute pairs
+    DEFAULT_ATTRIBUTES = {
+      "engine" => TEMPLATE_ENGINES.key(:markdown),
+      "view"   => "page.haml"
     }
 
-    # `String`
-    attr_reader :data
-    # `Hash`
+    # Contains the engine, data, body, content, view, and any header key-value pairs
+    # @return [Hash]
     attr_reader :attributes
-    # `String`
-    attr_reader :body
-    # `Symbol`
-    attr_reader :content_engine
+    alias :to_liquid :attributes
 
     # Creates a new instance by extracting the body and attributes from raw data.  Any extracted
     # components found are merged with their defaults.
     #
-    # @param [String] data
     # @param [Hash] options
-    # @option options [Symbol] :content_engine See `CONTENT_ENGINES` and `DEFAULT[:content_engine]`
+    # @option options [String] :data Contains a body and possibly a YAML header
+    # @option options [Symbol] :engine See `TEMPLATE_ENGINES` and `DEFAULT_ATTRIBUTES["engine"]`
+    # @raise [ArgumentError] Raised when registered content engine cannot be found
+    # @raise [InvalidHeaderError] Raised when YAML header is invalid
     #
-    def initialize(data, options = {})
-      @data           = data
-      @content_engine = options.delete(:content_engine) || DEFAULT[:content_engine]
+    def initialize(options = {})
+      data   = options[:data]   || ""
+      engine = options[:engine] || DEFAULT_ATTRIBUTES["engine"]
 
-      if self.data =~ /^(---\s*\n.*?\n?)^(---\s*$\n?)/m
-        @attributes = DEFAULT[:attributes].merge(YAML.load($1) || {})
-        @body       = self.data[($1.size + $2.size)..-1]
-      else
-        @attributes = DEFAULT[:attributes]
-        @body       = self.data || DEFAULT[:body]
+      unless TEMPLATE_ENGINES.include?(engine)
+        raise ArgumentError, "Cannot find registered content engine -- #{engine}"
       end
-    end
 
-    # Create a new instance by searching for and reading a content file from disk. Content files
-    # are searched consecutively until a page with known content extension is found.
-    #
-    # @param [String] path_without_extension
-    # @raise [PageNotFound] Raised when a content page cannot be found
-    # @return [ContentPage] A new instance is created and returned when found
-    #
-    def self.find_by_path(path_without_extension)
-      CONTENT_ENGINES.each_pair do |content_engine, extensions|
-        extensions.each do |extension|
-          path = "#{path_without_extension}.#{extension}"
-          return new(File.read(path), :content_engine => content_engine) if File.exist?(path)
+      @attributes = DEFAULT_ATTRIBUTES.dup
+
+      @attributes["body"] = if data =~ /^(---\s*\n.*?\n?)^(---\s*$\n?)/m
+        begin
+          header = YAML.load($1) || {}
+        rescue Exception => e
+          raise InvalidHeaderError, e.message
         end
-      end
 
-      raise PageNotFound, "Unable to find content page for path -- #{path_without_extension}"
-    end
+        begin
+          @attributes.merge!(header)
+        rescue
+          raise InvalidHeaderError, "Cannot parse header -- #{header.inspect}"
+        end
 
-    # Given a content engine, converts the body to HTML.
-    #
-    # @raise [RuntimeError] Raised when content engine is unknown
-    # @return [String] HTML from the conversion
-    #
-    def to_html
-      case content_engine
-      when :markdown
-        BlueCloth.new(Mango::FlavoredMarkdown.shake(body)).to_html
-      when :haml
-        Haml::Engine.new(body).to_html
+        $POSTMATCH
       else
-        raise "Unknown content engine -- #{content_engine}"
+        data
       end
-    end
 
-    # Returns just the view template's base file name.  It's assumed that all view templates are in
-    # Haml format.
-    #
-    # @example
-    #   @content_page.attributes["view"]  #=> "blog.haml"
-    #   @content_page.view                #=> :blog
-    #
-    # @return [Symbol] The view template's base file name.
-    #
-    def view
-      File.basename(attributes["view"].to_s, '.*').to_sym
+      FlavoredMarkdown.shake!(@attributes["body"]) if engine == TEMPLATE_ENGINES.key(:markdown)
+      @attributes.merge!("engine" => engine, "data" => data, "content" => nil)
+
+      @attributes["content"] = engine.new { @attributes["body"] }.render(nil, :page => self)
     end
 
+    private
+
     # Adds syntactic suger for reading attributes.
     #
     # @example
-    #   @content_page.title == @content_page.attributes["title"]
+    #   page.title == page.attributes["title"]
     #
     # @param [Symbol] method_name
+    # @param [Array] args
+    # @param [Proc] block
     # @raise [NoMethodError] Raised when there is no method name key in attributes
     # @return [Object] Value of the method name attribute
     #
-    def method_missing(method_name)
+    def method_missing(method_name, *args, &block)
       key = method_name.to_s
       attributes.has_key?(key) ? attributes[key] : super
     end
-
   end
 end

data/lib/mango/core_ext/string.rb

@@ -0,0 +1,16 @@
+# encoding: UTF-8
+
+# Extentions to the core `String` class
+#
+class String
+  # Convert a file name to a Sinatra-compliant template name
+  #
+  # @example
+  #   "blog.haml".templatize  #=> :blog
+  #
+  # @return [Symbol] A Sinatra-compliant template name
+  #
+  def templatize
+    File.basename(self, '.*').to_sym
+  end
+end

data/lib/mango/core_ext/uri.rb

@@ -0,0 +1,14 @@
+# encoding: UTF-8
+
+# Extentions to the core `URI` module
+#
+module URI
+  # Given a URI path, determine whether or no it looks like a directory path
+  #
+  # @param [String] uri_path
+  # @return [Boolean] `true` if the path is empty or has a trailing `/`, otherwise `false`
+  #
+  def self.directory?(uri_path)
+    uri_path.empty? || uri_path[-1] == "/"
+  end
+end

data/lib/mango/dependencies.rb

@@ -15,11 +15,11 @@ module Mango
   # developer-friendly warnings from rescued `LoadError` exceptions raised by missing
   # development RubyGem dependencies.
   #
-  # @example Simple usage with the YARD gem
+  # @example Simple usage with the rspec-core gem
   #   Mango::Dependencies.warn_at_exit
   #   begin
-  #     require "yard"
-  #     YARD::Rake::YardocTask.new(:yard)
+  #     require "rspec/core/rake_task"
+  #     RSpec::Core::RakeTask.new(:spec)
   #   rescue LoadError => e
   #     Mango::Dependencies.create_warning_for(e)
   #   end
@@ -27,12 +27,13 @@ module Mango
   # @see Mango::Dependencies.create_warning_for
   # @see Mango::Dependencies.warn_at_exit
   module Dependencies
+    # A short list of supported Ruby versions
     SUPPORTED_RUBY_VERSIONS = ["1.9.2"]
 
+    # Maps file names to gem name
     FILE_NAME_TO_GEM_NAME = {
       :"rack/test"            => :"rack-test",
       :"rspec/core/rake_task" => :"rspec-core",
-      :"yard/sinatra"         => :"yard-sinatra"
     }
 
     # Checks that the version of the current Ruby process matches the one of the

data/lib/mango/flavored_markdown.rb

@@ -78,5 +78,12 @@ module Mango
       text
     end
 
+    # Destructively replaces the value of `text` with a shake of `FlavoredMarkdown` text
+    #
+    # @param [String] text
+    # @see FlavoredMarkdown.shake
+    def self.shake!(text)
+      text.replace shake(text)
+    end
   end
 end

data/lib/mango/rack/debugger.rb

@@ -1,7 +1,21 @@
 # encoding: UTF-8
 module Mango
+  # TOOD: Remove namespace
+  #
   module Rack
+    # A Rack Middleware class that enables `ruby-debug` which allows the interception of `debugger`
+    # breakpoints.
+    #
+    # @see http://www.sinatrarb.com/intro#Rack%20Middleware
+    # @see http://railscasts.com/episodes/54-debugging-with-ruby-debug
+    #
     class Debugger
+      # Given a `Mango::Application`, enable `ruby-debug` when creating a new instance of `Debugger`.
+      #
+      # @param [Mango::Application] app
+      # @param [Kernel] kernel Useful for testing
+      # @param [String] ruby_version TODO: Remove parameter
+      #
       def initialize(app, kernel = Kernel, ruby_version = RUBY_VERSION)
         @app = app
         kernel.require "ruby-debug"
@@ -14,6 +28,12 @@ module Mango
         puts "=> With RubyGems, use 'gem install #{gem_name}' to install the library."
       end
 
+      # Given a Rack environment, simply invoke the `Mango::Application` with the environment
+      # and return the response without modification.
+      #
+      # @param [Hash] env
+      # @return [Array]
+      #
       def call(env)
         @app.call(env)
       end

data/lib/mango/runner.rb

@@ -2,6 +2,10 @@
 require "thor"
 
 module Mango
+  # `Mango::Runner` is a `Thor` class and is used in combination with the `bin/mango` executable.
+  #
+  # @see https://github.com/wycats/thor/wiki
+  #
   class Runner < Thor
     include Thor::Actions
 
@@ -10,91 +14,70 @@ module Mango
     source_root File.expand_path("templates", File.dirname(__FILE__))
 
     desc "create /path/to/your/app", "Creates a new Mango application at the specified path"
-    def create(destination)
-      self.destination_root = destination
+    # Creates a new Mango application at the specified path
+    # @param [String] path
+    def create(path)
+      self.destination_root = path
 
       copy_file(".gitignore")
       copy_file("config.ru")
       copy_file("Gemfile")
       copy_file("README.md")
 
-      build_content_path
-      build_themes_path
+      copy_content
+      copy_themes
     end
 
     ###############################################################################################
 
     protected
 
-    def build_content_path
-      content_root = File.join(self.destination_root, "content")
-      empty_directory(content_root)
-
-      copy_file("content/index.md")
+    def copy_content
+      copy_file("content/index.erb")
     end
 
-    def build_themes_path
-      themes_root = File.join(self.destination_root, "themes")
-      empty_directory(themes_root)
-
-      default_root = File.join(themes_root, "default")
-      empty_directory(default_root)
-
-      build_public_path default_root
-      build_styles_path default_root
-      build_views_path default_root
+    def copy_themes
+      copy_javascript_templates
+      copy_public_files
+      copy_stylesheet_templates
+      copy_view_templates
     end
 
     ###############################################################################################
 
-    protected
-
-    def build_public_path(destination)
-      public_root = File.join(destination, "public")
-      empty_directory(public_root)
-
+    def copy_public_files
       create_file("themes/default/public/favicon.ico")
       copy_file("themes/default/public/robots.txt")
 
-      build_public_images_path public_root
-      build_public_javascripts_path public_root
-      build_public_styles_path public_root
+      copy_image_files
+      copy_javascript_files
+      copy_stylesheet_files
     end
 
-    def build_public_images_path(destination)
-      public_images_root = File.join(destination, "images")
-      empty_directory(public_images_root)
-
+    def copy_image_files
       copy_file("themes/default/public/images/particles.gif")
     end
 
-    def build_public_javascripts_path(destination)
-      public_javascripts_root = File.join(destination, "javascripts")
-      empty_directory(public_javascripts_root)
-
+    def copy_javascript_files
       copy_file("themes/default/public/javascripts/fireworks.js")
-      copy_file("themes/default/public/javascripts/timer.js")
     end
 
-    def build_public_styles_path(destination)
-      public_styles_root = File.join(destination, "styles")
-      empty_directory(public_styles_root)
-
-      copy_file("themes/default/public/styles/fireworks.css")
-      copy_file("themes/default/public/styles/reset.css")
+    def copy_stylesheet_files
+      copy_file("themes/default/public/stylesheets/fireworks.css")
+      copy_file("themes/default/public/stylesheets/reset.css")
     end
 
-    def build_styles_path(destination)
-      styles_root = File.join(destination, "styles")
-      empty_directory(styles_root)
+    ###############################################################################################
 
-      copy_file("themes/default/styles/screen.sass")
+    def copy_javascript_templates
+      copy_file("themes/default/javascripts/timer.coffee")
     end
 
-    def build_views_path(destination)
-      views_root = File.join(destination, "views")
-      empty_directory(views_root)
+    def copy_stylesheet_templates
+      copy_file("themes/default/stylesheets/screen.sass")
+    end
 
+    def copy_view_templates
       copy_file("themes/default/views/404.haml")
       copy_file("themes/default/views/layout.haml")
       copy_file("themes/default/views/page.haml")