mango 0.1.1 → 0.5.0.beta1

data/lib/mango/content_page.rb

@@ -0,0 +1,193 @@
+# encoding: UTF-8
+
+require "bluecloth"
+require "haml"
+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.
+  #
+  # `ContentPage` instances have two primary components -- **a body** and some **attributes**.
+  # Each component is defined within a single content file.
+  #
+  # ### Example content file
+  #
+  #     # mango_poem.markdown
+  #     ---
+  #     title: The Sin of Mango
+  #     categories:
+  #       - bad
+  #       - poetry
+  #     ---
+  #     Mango is like a drug.
+  #     You must have more and more and more of the Mango
+  #     until there is no Mango left.
+  #     Not even for 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.
+  #
+  # ### 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`
+  #
+  # `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:
+  #
+  #     @content_page.to_html
+  #
+  # ### The Attributes
+  #
+  # Attributes are key-value pairs, defined with [YAML](http://www.yaml.org/) formatting.
+  #
+  # 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.
+  #
+  # 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"]`.
+  #
+  # Syntactic sugar has been added for accessing attribtues.  For example:
+  #
+  #     @content_page.attributes["title"]
+  #
+  # can be shortened to
+  #
+  #     @content_page.title
+  #
+  # 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:
+  #
+  #     %title
+  #       = @content_page.title
+  #
+  # @see Mango::FlavoredMarkdown
+  #
+  class ContentPage
+    class PageNotFound < RuntimeError; end
+
+    # Known content formats and their associated file extensions
+    CONTENT_ENGINES = {
+      :markdown => ["md", "mdown", "markdown"],
+      :haml     => ["haml"]
+    }
+
+    # Default values for various accessors
+    DEFAULT = {
+      :attributes     => { "view" => :page },
+      :body           => "",
+      :content_engine => :markdown
+    }
+
+    # `String`
+    attr_reader :data
+    # `Hash`
+    attr_reader :attributes
+    # `String`
+    attr_reader :body
+    # `Symbol`
+    attr_reader :content_engine
+
+    # 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]`
+    #
+    def initialize(data, options = {})
+      @data           = data
+      @content_engine = options.delete(:content_engine) || DEFAULT[:content_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]
+      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)
+        end
+      end
+
+      raise PageNotFound, "Unable to find content page for path -- #{path_without_extension}"
+    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
+      else
+        raise "Unknown content engine -- #{content_engine}"
+      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_sym
+    end
+
+    # Adds syntactic suger for reading attributes.
+    #
+    # @example
+    #   @content_page.title == @content_page.attributes["title"]
+    #
+    # @param [Symbol] method_name
+    # @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)
+      key = method_name.to_s
+      attributes.has_key?(key) ? attributes[key] : super
+    end
+
+  end
+end

data/lib/mango/dependencies.rb

@@ -0,0 +1,125 @@
+# encoding: UTF-8
+
+module Mango
+  # `Mango::Dependencies` is a class-methods-only **singleton** class that performs both strict
+  # parse-time dependency checking and simple, elegant run-time dependency warning.
+  #
+  # My preferred mental model is to consider software library dependencies as a snapshot in time.
+  # I also make the assumption, sometimes incorrectly, that a newer version of a software library
+  # is not always a better version.
+  #
+  # `Mango::Dependencies` automatically enforces a strict parse-time check for the
+  # `REQUIRED_RUBY_VERSION` on both application and development processes for the `Mango` library.
+  # (i.e. `bin/mango`, `rake`, `spec`, etc)  Because of this, I've ensured this file is
+  # syntactically compatible with Ruby 1.8.6 or higher.
+  #
+  # Currently, `Mango` does **not** enforce strict parse-time version checking on `DEVELOPMENT_GEMS`.
+  # In the future, I would like to experiment with using RubyGems and the `Kernel#gem` method to
+  # this end.  For now, each developer is responsible for ensuring the correct versions of their
+  # necessary development gems are located in the `$LOAD_PATH` on their system.
+  #
+  # When a gem is required, but a `LoadError` is raised, and rescued, `Mango::Dependencies` can be
+  # incorporated into the process to warn a developer of missing development features.  Even with a
+  # few methods --  `.create_warning_for` and `.warn_at_exit` --  users are automatically warned, in
+  # this case at the moment of termination, about gems that could not found be in the `$LOAD_PATH`.
+  # Using `Mango::Dependencies` is **not** a mandatory inclusion for all gem requirements, merely a
+  # guide to help developers quickly see obstacles in their path.
+  #
+  # @example Simple usage with the YARD gem
+  #   begin
+  #     require "yard"
+  #     YARD::Rake::YardocTask.new(:yard)
+  #   rescue LoadError => e
+  #     Mango::Dependencies.create_warning_for(e)
+  #   end
+  #
+  # @see Mango::Dependencies.create_warning_for
+  # @see Mango::Dependencies.warn_at_exit
+  class Dependencies
+    # For now, starting with Ruby 1.9.1 but I would like to experiment with compatibility with Ruby >= 1.9.1 in the future.
+    REQUIRED_RUBY_VERSION = "1.9.1"
+
+    # bluecloth is a hidden yard dependency for markdown support
+    DEVELOPMENT_GEMS = {
+      :"rack-test"    => "0.5.4",
+      :rspec          => "1.3.0",
+      :yard           => "0.5.8",
+      :"yard-sinatra" => "0.5.0",
+      :bluecloth      => "2.0.7"
+    }
+
+    FILE_NAME_TO_GEM_NAME = {
+      :"rack/test"          => :"rack-test",
+      :"spec/rake/spectask" => :rspec,
+      :"yard/sinatra"       => :"yard-sinatra"
+    }
+
+    # Empties the warnings cache.  This method is called when the class is required.
+    def self.destroy_warnings
+      @@warnings_cache = []
+    end
+    destroy_warnings
+
+    # Creates and caches a warning from a `LoadError` exception.  Warnings are only created for
+    # known development gem dependencies.
+    #
+    # @param [LoadError] error A rescued exception
+    # @raise [RuntimeError] Raised when the `LoadError` argument is an unknown development gem.
+    def self.create_warning_for(error)
+      pattern = %r{no such file to load -- ([\w\-\\/]*)}
+      error.message.match(pattern) do |match_data|
+        file_name = match_data[1].to_sym
+        gem_name  = if DEVELOPMENT_GEMS.has_key?(file_name)
+          file_name
+        elsif FILE_NAME_TO_GEM_NAME.has_key?(file_name)
+          FILE_NAME_TO_GEM_NAME[file_name]
+        else
+          raise "Cannot create a dependency warning for unknown development gem -- #{file_name}"
+        end
+
+        @@warnings_cache << "#{gem_name} --version '#{DEVELOPMENT_GEMS[gem_name]}'"
+      end
+    end
+
+    # Displays a warning message to the user on the standard output channel if there are warnings
+    # to render.
+    #
+    # @example Sample warning message
+    #   The following development gem dependencies could not be found. Without them, some available development features are missing:
+    #   jeweler --version "1.4.0"
+    #   rspec --version "1.3.0"
+    #   yard --version "0.5.3"
+    #   bluecloth --version "2.0.7"
+    def self.render_warnings
+      unless @@warnings_cache.empty?
+        message = []
+        message << "The following development gem dependencies could not be found. Without them, some available development features are missing:"
+        message += @@warnings_cache
+        puts "\n" + message.join("\n")
+      end
+    end
+
+    # Attaches a call to `render_warnings` to `Kernel#at_exit`
+    def self.warn_at_exit
+      at_exit { render_warnings }
+    end
+
+    private
+
+    # Checks that the version of the current Ruby process matches the `REQUIRED_RUBY_VERSION`.
+    # This method is automatically invoked at the first time this class is required, ensuring the
+    # correct Ruby version at parse-time.
+    #
+    # @param [String] ruby_version Useful for automated specifications.  Defaults to `RUBY_VERSION`.
+    # @raise [SystemExit] Raised, with a message, when the process is using an incorrect version of Ruby.
+    def self.check_ruby_version(ruby_version = RUBY_VERSION)
+      unless ruby_version == REQUIRED_RUBY_VERSION
+        abort <<-ERROR
+This library requires Ruby #{REQUIRED_RUBY_VERSION}, but you're using #{ruby_version}.
+Please visit http://www.ruby-lang.org/ for installation instructions.
+        ERROR
+      end
+    end
+    check_ruby_version
+  end
+end

data/lib/mango/flavored_markdown.rb

@@ -0,0 +1,82 @@
+require "digest/md5"
+
+module Mango
+  # `Mango::FlavoredMarkdown` (MFM) is a subset of GithubFlavoredMarkdown (GFM).  MFM adds a touch
+  # seasoning to the standard Markdown (SM) syntax.
+  #
+  # ## Differences from standard Markdown
+  #
+  # ### Newlines
+  #
+  # The biggest difference that MFM introduces is in the handling of linebreaks. With SM you can
+  # hard wrap paragraphs of text and they will be combined into a single paragraph. I find this to
+  # be the cause of a huge number of unintentional formatting errors. MFM treats newlines in
+  # paragraph-like content as real line breaks, which is probably what you intended.
+  #
+  # The next paragraph contains two phrases separated by a single newline character:
+  #
+  #     Roses are red
+  #     Violets are blue
+  #
+  # becomes
+  #
+  # Roses are red  
+  # Violets are blue
+  #
+  # ### Multiple underscores in words
+  #
+  # It is not reasonable to italicize just part of a word, especially when you're dealing with code
+  # and names often appear with multiple underscores. Therefore, MFM ignores multiple underscores
+  # in words.
+  #
+  #     perform_complicated_task
+  #     do_this_and_do_that_and_another_thing
+  #
+  # becomes
+  #
+  # perform_complicated_task  
+  # do_this_and_do_that_and_another_thing
+  #
+  # @see http://github.github.com/github-flavored-markdown/
+  # @see http://daringfireball.net/projects/markdown/syntax
+  #
+  class FlavoredMarkdown
+    # For maximum flavor, add one shake of seasoning to markdown text **before** cooking with a
+    # Markdown engine.
+    #
+    # @example Cooking with BlueCloth
+    #
+    #   BlueCloth.new(Mango::FlavoredMarkdown.shake(text)).to_html
+    #
+    # @param [String] text
+    # @return [String] Seasoned text that is ready to cook!
+    #
+    def self.shake(text)
+      # Extract pre blocks
+      extractions = {}
+      text.gsub!(%r{<pre>.*?</pre>}m) do |match|
+        md5 = Digest::MD5.hexdigest(match)
+        extractions[md5] = match
+        "{gfm-extraction-#{md5}}"
+      end
+
+      # prevent foo_bar_baz from ending up with an italic word in the middle
+      text.gsub!(/(^(?! {4}|\t)\w+_\w+_\w[\w_]*)/) do |x|
+        x.gsub("_", '\_') if x.split('').sort.join[0..1] == "__"
+      end
+
+      # in very clear cases, let newlines become <br /> tags
+      text.gsub!(/^[\w\<][^\n]*\n+/) do |x|
+        x =~ /\n{2}/ ? x : (x.strip!; x << "  \n")
+      end
+
+      # Insert pre block extractions
+      text.gsub!(/\{gfm-extraction-([0-9a-f]{32})\}/) do
+        "\n\n" + extractions[$1]
+      end
+
+      text
+    end
+
+  end
+end

data/lib/mango/rack/debugger.rb

@@ -0,0 +1,22 @@
+# encoding: UTF-8
+module Mango
+  module Rack
+    class Debugger
+      def initialize(app, kernel = Kernel, ruby_version = RUBY_VERSION)
+        @app = app
+        kernel.require "ruby-debug"
+        ::Debugger.start
+        puts "=> Debugger enabled"
+      rescue LoadError
+        gem_name = (ruby_version >= "1.9" ? "ruby-debug19" : "ruby-debug")
+        puts "=> Debugger not enabled"
+        puts "=> The #{gem_name} library is required to run the server in debugging mode."
+        puts "=> With RubyGems, use 'gem install #{gem_name}' to install the library."
+      end
+
+      def call(env)
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/mango/runner.rb

@@ -0,0 +1,95 @@
+# encoding: UTF-8
+require "thor"
+
+module Mango
+  class Runner < Thor
+    include Thor::Actions
+
+    add_runtime_options!
+
+    source_root File.join(File.dirname(__FILE__), "templates")
+
+    desc "create /path/to/your/app",
+      "Creates a new Mango application with a default directory structure and configuration at the path you specify."
+    def create(destination)
+      self.destination_root = destination
+      copy_file("config.ru", File.join(self.destination_root, "config.ru"))
+      copy_file("Gemfile", File.join(self.destination_root, "Gemfile"))
+      copy_file("README.md", File.join(self.destination_root, "README.md"))
+
+      build_content_path
+      build_themes_path
+    end
+
+    ###############################################################################################
+
+    protected
+
+    def build_content_path
+      content_root = File.join(self.destination_root, "content")
+      empty_directory(content_root)
+      copy_file("content/index.md", File.join(content_root, "index.md"))
+    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
+    end
+
+    ###############################################################################################
+
+    protected
+
+    def build_public_path(destination)
+      public_root = File.join(destination, "public")
+      empty_directory(public_root)
+      create_file(File.join(public_root, "favicon.ico"))
+      copy_file("themes/default/public/robots.txt", File.join(public_root, "robots.txt"))
+
+      build_public_images_path public_root
+      build_public_javascripts_path public_root
+      build_public_styles_path public_root
+    end
+
+    def build_public_images_path(destination)
+      public_images_root = File.join(destination, "images")
+      empty_directory(public_images_root)
+      copy_file("themes/default/public/images/particles.gif", File.join(public_images_root, "particles.gif"))
+    end
+
+    def build_public_javascripts_path(destination)
+      public_javascripts_root = File.join(destination, "javascripts")
+      empty_directory(public_javascripts_root)
+      copy_file("themes/default/public/javascripts/fireworks.js", File.join(public_javascripts_root, "fireworks.js"))
+      copy_file("themes/default/public/javascripts/timer.js", File.join(public_javascripts_root, "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", File.join(public_styles_root, "fireworks.css"))
+      copy_file("themes/default/public/styles/reset.css", File.join(public_styles_root, "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", File.join(styles_root, "screen.sass"))
+    end
+
+    def build_views_path(destination)
+      views_root = File.join(destination, "views")
+      empty_directory(views_root)
+      copy_file("themes/default/views/404.haml", File.join(views_root, "404.haml"))
+      copy_file("themes/default/views/layout.haml", File.join(views_root, "layout.haml"))
+      copy_file("themes/default/views/page.haml", File.join(views_root, "page.haml"))
+    end
+  end
+end