mango 0.1.1 → 0.5.0.beta1

data/.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+.rvmrc
+.yardoc
+*.gem
+*.tmproj
+yardoc

data/.yardopts

@@ -0,0 +1,6 @@
+--output-dir ./yardoc
+--markup markdown
+-
+LICENSE
+doc/HISTORY.mdown
+doc/ROAD-MAP.mdown

data/README.mdown

@@ -2,65 +2,84 @@
 
 Image courtesy of [B.C. Tree Fruits LTD.](http://www.bctree.com/products/sourced/mango.php)
 
-Mango release 0.1.1 (June 15, 2010)
-===================================
+Mango release 0.5.0 (September 12, 2010)
+========================================
 
 Copyright (c) 2010 Ryan Sobol. Licensed under the MIT license.  Please see the {file:LICENSE} for more information.
 
-**Source Code**: [http://github.com/ryansobol/mango](http://github.com/ryansobol/mango)  
-**Bug Tracker**: [http://github.com/ryansobol/mango/issues](http://github.com/ryansobol/mango/issues)  
-**Wiki**: [http://wiki.github.com/ryansobol/mango](http://wiki.github.com/ryansobol/mango)  
+* **Source Code**: [http://github.com/ryansobol/mango](http://github.com/ryansobol/mango)
+* **Documentation**: [http://rubydoc.info/github/ryansobol/mango](http://rubydoc.info/github/ryansobol/mango)
+* **Bug Tracker**: [http://github.com/ryansobol/mango/issues](http://github.com/ryansobol/mango/issues)
+* **Wiki**: [http://wiki.github.com/ryansobol/mango](http://wiki.github.com/ryansobol/mango)
+
+**Mango respects [Semantic Versioning](http://semver.org/)!**
 
 WHAT'S NEW?
 -----------
 
-  * Reserved the 'mango' namespace on RubyGems.org!
+### New Features:
+
+  * Added the beginnings of a default theme titled "Smashing Mangos".
+  * Added `Mango::Rack::Debugger` to the middleware stack (Only loads in the `:development` rack environment).
+  * Added a `Mango::ContentPage` model to convert user-generated content into HTML.  Supports either [Haml](http://haml-lang.com/) or [Markdown](http://daringfireball.net/projects/markdown/syntax) formatted content.
+  * Refactored `Mango::Application` to utilize `Mango::ContentPage`.  Now views have access to a `@content_page` instance variable.
+  * Added `Mango::FlavoredMarkdown`, a subset of [GithubFlavoredMarkdown](http://github.github.com/github-flavored-markdown/), into the Markdown-to-HTML conversion.
+
+### Dependencies:
+
+  * Updated [Haml](http://haml-lang.com/) to 3.0.18
+  * Updated [YARD::Sinatra](http://github.com/rkh/yard-sinatra) to 0.5.0
+  * Added [BlueCloth](http://deveiate.org/projects/BlueCloth) 2.0.7 as a required dependency
 
 Please see {file:doc/HISTORY.mdown} for the historical overview of the project.
 
 SYNOPSIS
 --------
 
-**Mango is a dynamic blog engine for Ruby hackers who believe in minimalism.**
-
-Mango let's you use publish to the web using the tools you're already familiar with -- the file system and your trusty text editor.  With Mango, there is:
-
-  * No clunky administrator interface for managing content
-  * No unchangeable database requirements -- no database period!
-  * No know exploits  ;)
+**Mango is a dynamic, database-free, and open source website framework that is designed to make life easier for small teams of designers, developers, and content writers.**
 
 FEATURES
 --------
 
-  * Dynamically route HTTP requests to Haml content pages
-  * Route unknown pages to a customizable 404 page
-  * Wrap content pages within customizable Haml templates and layout
-  * Publish to any Rack-based application server (e.g. Phusion Passenger, thin, mongrel, webrick, etc.)
+  1. Easy to install:  Mango installs as a RubyGem and can generate a basic website structure in seconds.
+
+  2. Easy to publish: Supports many types of deployments like direct SFTP uploading and source control systems like Git, Mercurial, SVN, CSV, etc.
+
+  3. Easy to write:  Mango let's you publish to the web using the tools you're already familiar with -- the file system and your trusty text editor.  Mango supports a variety of formats include Markdown, HAML, HTML, SASS, CSS, and JavaScript.  These files are easier to create and revise then working with database records.  Say goodbye to clunky administrator interfaces for managing content!
+
+  4. Easy to deploy: There's no database to install, configure, and manage.
+
+  5. Easy to understand:  Mango is perfect for smalls teams of varying levels of coding expertise.  Why not take the simple route where everyone is on the same page?  Instead of struggling with complex platforms, which most CMS are, Mango is perfect for people who has no coding experience.
+
+  6. Easy on the wallet: It's free!
+
+  7. Easy to... SPEED:  A major advantage of a database-less website framework is speed.  Database queries slow down servers.  On a high traffic website, this has a dramatic effect on the speed of the site.  With minimal server side scripting and zero database queries, Mango is lightening fast.
 
 REQUIREMENTS
 ------------
 
 **Required dependencies**
 
-  * Ruby 1.9.1
-  * Rack 1.2.1
-  * Sinatra 1.0
-  * Haml 3.0.12
+  * [Ruby](http://www.ruby-lang.org/) 1.9.1
+  * [Rack](http://rack.rubyforge.org/) 1.2.1
+  * [Sinatra](http://www.sinatrarb.com/) 1.0
+  * [Haml](http://haml-lang.com/) 3.0.18
+  * [Sass](http://sass-lang.com/) 3.0.18 (bundled with Haml)
+  * [BlueCloth](http://deveiate.org/projects/BlueCloth) 2.0.7
 
 **Optional development dependencies**
 
-  * Rake 0.8.7 (bundled with Ruby 1.9.1)
-  * Rack::Test 0.5.4
-  * RSpec 1.3.0
-  * YARD 0.5.5
-  * BlueCloth 2.0.7
+  * [Rake](http://rake.rubyforge.org/) 0.8.7 (bundled with Ruby)
+  * [Rack::Test](http://github.com/brynary/rack-test) 0.5.4
+  * [RSpec](http://rspec.info/) 1.3.0
+  * [YARD](http://yardoc.org/) 0.5.8
+  * [YARD::Sinatra](http://github.com/rkh/yard-sinatra) 0.5.0
+  * [BlueCloth](http://deveiate.org/projects/BlueCloth) 2.0.7
 
 INSTALLING
 ----------
 
-    $ git clone git@github.com:ryansobol/mango.git
-    $ cd mango
-    $ bundle install
+    $ gem install mango
 
 USAGE
 -----
@@ -75,6 +94,11 @@ USAGE
     `-- themes
         `-- default
             |-- public
+            |   |-- images
+            |   |   `-- ripe-mango.jpg
+            |   `-- robots.txt
+            |-- styles
+            |   `-- screen.sass
             `-- views
                 |-- 404.haml
                 |-- layout.haml
@@ -84,6 +108,15 @@ USAGE
 
     $ rackup
 
+UNDER THE HOOD
+--------------
+
+  * Mango tries to route HTTP requests to static files first
+  * Then it tries to route HTTP requests to Markdown or Haml content pages or Sass style templates
+  * Finally, it routes unknown HTTP requests to a customizable 404 page
+  * Wraps content pages within a customizable Haml template and layout
+  * Supports any Rack-based application server (e.g. Phusion Passenger, thin, mongrel, webrick, etc.)
+
 MOTIVATION
 ----------
 

data/Rakefile

@@ -0,0 +1,62 @@
+# encoding: UTF-8
+require_relative "lib/mango"
+Mango::Dependencies.warn_at_exit
+
+###################################################################################################
+
+begin
+  require "spec/rake/spectask"
+  require "rack/test" # for Rack support
+  Spec::Rake::SpecTask.new(:spec)
+  task :default => :spec
+rescue LoadError => e
+  Mango::Dependencies.create_warning_for(e)
+end
+
+###################################################################################################
+
+begin
+  require "yard"
+  require "bluecloth" # for Markdown support
+  require "yard/sinatra" # for Sinatra support
+  YARD::Rake::YardocTask.new(:yard) do |t|
+    t.options += ["--title", "Mango #{Mango::VERSION} Documentation"]
+  end
+rescue LoadError => e
+  Mango::Dependencies.create_warning_for(e)
+end
+
+###################################################################################################
+
+namespace :gem do
+  desc "Builds a gem from the current project's Gem::Specification"
+  task :build do
+    system "gem build mango.gemspec"
+  end
+
+  desc "Removes the gem file for the current project"
+  task :clean do
+    jeweler { |gem_file| rm gem_file }
+  end
+
+  desc "Pushes the current gem to RubyGems.org"
+  task :push do
+    jeweler { |gem_file| system "gem push #{gem_file}"}
+  end
+
+  desc "Builds, pushes, and cleans a gem for the current project"
+  task :release do
+    Rake::Task["gem:build"].invoke
+    Rake::Task["gem:push"].invoke
+    Rake::Task["gem:clean"].invoke
+  end
+
+  def jeweler(&block)
+    file = "mango-#{Mango::VERSION}.gem"
+    if File.exists?(file)
+      yield file
+    else
+      puts "No gem file found - #{file}"
+    end
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.5.0.beta1

data/bin/mango

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+require_relative "../lib/mango/runner"
+Mango::Runner.start

data/doc/HISTORY.mdown

@@ -0,0 +1,71 @@
+Mango release 0.5.0 (September 12, 2010)
+========================================
+
+
+Mango release 0.4.0 (August 30, 2010)
+=====================================
+
+### New Features:
+
+  * Added the beginnings of a default theme titled "Smashing Mangos".
+  * Added `Mango::Rack::Debugger` to the middleware stack (Only loads in the `:development` rack environment).
+  * Added a `Mango::ContentPage` model to convert user-generated content into HTML.  Supports either [Haml](http://haml-lang.com/) or [Markdown](http://daringfireball.net/projects/markdown/syntax) formatted content.
+  * Refactored `Mango::Application` to utilize `Mango::ContentPage`.  Now views have access to a `@content_page` instance variable.
+  * Added `Mango::FlavoredMarkdown`, a subset of [GithubFlavoredMarkdown](http://github.github.com/github-flavored-markdown/), into the Markdown-to-HTML conversion.
+
+### Dependencies:
+
+  * Updated [Haml](http://haml-lang.com/) to 3.0.18
+  * Updated [YARD::Sinatra](http://github.com/rkh/yard-sinatra) to 0.5.0
+  * Added [BlueCloth](http://deveiate.org/projects/BlueCloth) 2.0.7 as a required dependency
+
+Mango release 0.3.0 (June 25, 2010)
+===================================
+
+### New Features:
+
+  * Added a route handler that renders [Sass](http://sass-lang.com/) templates to CSS!
+  * Refactored tests for better spec coverage of route handling
+  * Massive rewrite of internal documentation thanks to the [YARD::Sinatra (modified)](http://github.com/ryansobol/yard-sinatra)
+  * Uploaded developer documentation to [http://yardoc.org/docs/ryansobol-mango](http://yardoc.org/docs/ryansobol-mango)
+
+### Dependencies:
+
+  * Updated [Haml](http://haml-lang.com/) to 3.0.13
+  * Added [YARD::Sinatra](http://github.com/rkh/yard-sinatra) 0.4.0.1 [(modified)](http://github.com/ryansobol/yard-sinatra)
+
+### Bug fixes:
+
+  * Fixed Regex when parsing LoadError messages on missing development dependencies
+  * Fixed rspec gem name detection when requiring spec/rake/spectask in the Rakefile
+
+Mango release 0.2.1 (June 23, 2010)
+===================================
+
+  * Refactored the application to reduce its code size and increase its maintainability
+  * Improved the application's documentation and tests with additional HTTP routing examples
+
+Mango release 0.2.0 (June 19, 2010)
+===================================
+
+  * Mango tries to route HTTP requests to static files first
+  * Then it tries to route HTTP requests to Haml content pages
+  * Finally, it routes unknown HTTP requests to a customizable 404 page
+
+Mango release 0.1.1 (June 15, 2010)
+===================================
+
+  * Reserved the 'mango' namespace on RubyGems.org!
+
+Mango release 0.1.0 (June 15, 2010)
+===================================
+
+  * Mango tries to route HTTP requests to Haml content pages first
+  * Then it routes unknown HTTP requests to a customizable 404 page
+  * Wraps content pages within a customizable Haml template and layout
+  * Supports any Rack-based application server (e.g. Phusion Passenger, thin, mongrel, webrick, etc.)
+
+Mango unrelease 0.0.1 (June 12, 2010)
+=====================================
+
+  * First commit of the project

data/doc/ROAD-MAP.mdown

@@ -0,0 +1,10 @@
+Road-map of Potential Improvements
+==================================
+
+In no particular order of importance:
+
+Mango::Dependencies
+-------------------
+
+    * Compare, contrast, extend, and/or integrate with Bundler
+    * Promote the installation and use of RVM

data/lib/mango.rb

@@ -0,0 +1,7 @@
+# encoding: UTF-8
+require_relative "mango/dependencies" # ruby version guard
+require_relative "mango/version"
+require_relative "mango/rack/debugger"
+require_relative "mango/application"
+require_relative "mango/flavored_markdown"
+require_relative "mango/content_page"

data/lib/mango/application.rb

@@ -0,0 +1,334 @@
+# encoding: UTF-8
+require "sinatra/base"
+require "haml"
+require "sass"
+
+module Mango
+  # It's probably no surprise that `Mango::Application` is a modular **application controller**
+  # class, inheriting all of the magic and wonder of `Sinatra::Base`.  The primary responsibility
+  # of the class is to receive an HTTP request and send an HTML response by instructing the
+  # necessary models and/or views to perform actions based on that request.
+  #
+  # For **every HTTP request**, the application will first attempt to match the request URI path to
+  # a public file found within `settings.public` and send that file with a 200 response code.
+  #
+  # In addition to serving static assets, the application has two dynamic route handlers:
+  #
+  #   * Content page templates with `GET *`
+  #   * Style sheet templates with `GET /styles/*.css`
+  #
+  # and one error handler:
+  #
+  #   * 404 Page Not Found with `NOT_FOUND`
+  #
+  # # Serving public files found within `settings.public`
+  #
+  # ### Example requests routed to public files (with potential security holes)
+  #
+  #     |-- content
+  #     |   `-- override.haml
+  #     `-- themes
+  #         `-- default
+  #             |-- public
+  #             |   |-- images
+  #             |   |   |-- index.html
+  #             |   |   `-- ripe-mango.jpg
+  #             |   |-- override
+  #             |   `-- robots.txt
+  #             `-- security_hole.txt
+  #
+  #     GET /robots.txt            => 200 themes/default/public/robots.txt
+  #     GET /images/index.html     => 200 themes/default/public/images/index.html
+  #     GET /images/ripe-mango.jpg => 200 themes/default/public/images/ripe-mango.jpg
+  #     GET /override              => 200 themes/default/public/override
+  #     GET /images/               => 200 themes/default/public/images/index.html
+  #
+  #     GET /../security_hole.txt  => pass to NOT_FOUND error handler
+  #
+  # # Content page templates with `GET *`
+  #
+  # ### Example `GET *` requests routed to content pages (with potential security holes)
+  #
+  #     |-- content
+  #     |   |-- about
+  #     |   |   |-- index.haml
+  #     |   |   `-- us.haml
+  #     |   |-- index.haml
+  #     |   |-- override.haml
+  #     |   `-- turner+hooch.haml
+  #     `-- security_hole.haml
+  #
+  #     GET /                      => 200 content/index.haml
+  #     GET /index                 => 200 content/index.haml
+  #     GET /index?foo=bar         => 200 content/index.haml
+  #     GET /about/                => 200 content/about/index.haml
+  #     GET /about/index           => 200 content/about/index.haml
+  #     GET /about/us              => 200 content/about/us.haml
+  #     GET /turner%2Bhooch        => 200 content/turner+hooch.haml
+  #
+  #     GET /page_not_found        => pass to NOT_FOUND error handler
+  #     GET /../security_hole      => pass to NOT_FOUND error handler
+  #
+  # # Style sheet templates with `GET /styles/*.css`
+  #
+  # ### Example `GET /styles/*.css` requests routed to style sheets (with potential security holes)
+  #
+  #     `-- themes
+  #       `-- default
+  #           |-- public
+  #           |   |-- default.css
+  #           |   `-- styles
+  #           |       |-- override.css
+  #           |       |-- reset.css
+  #           |       `-- subfolder
+  #           |           `-- another.css
+  #           |-- security_hole.sass
+  #           `-- styles
+  #               |-- override.sass
+  #               |-- screen.sass
+  #               `-- subfolder
+  #                   `-- screen.sass
+  #
+  #     GET /styles/screen.css            => 200 themes/default/styles/screen.sass
+  #     GET /styles/subfolder/screen.css  => 200 themes/default/styles/subfolder/screen.sass
+  #
+  #     GET /styles/reset.css             => 200 themes/default/public/styles/reset.css
+  #     GET /styles/override.css          => 200 themes/default/public/styles/override.css
+  #     GET /default.css                  => 200 themes/default/public/default.css
+  #     GET /styles/subfolder/another.css => 200 themes/default/public/styles/subfolder/another.css
+  #
+  #     GET /styles/style_not_found.css  => pass to NOT_FOUND error handler
+  #     GET /screen.css                  => pass to NOT_FOUND error handler
+  #     GET /styles/../security_hole.css => pass to NOT_FOUND error handler
+  #
+  # # 404 Page Not Found with `NOT_FOUND`
+  #
+  # When a requested URI path cannot be matched with a public file or template file, the error
+  # handler renders the 404 template and sends it with a 404 response.
+  #
+  class Application < Sinatra::Base
+    set :root, Dir.getwd
+    set :theme, "default"
+    set :views, lambda { File.join(root, "themes", theme, "views") }
+    set :public, lambda { File.join(root, "themes", theme, "public") }
+    set :styles, lambda { File.join(root, "themes", theme, "styles") }
+    set :content, lambda { File.join(root, "content") }
+
+    # Renders the `404.haml` template found within `settings.views` and sends it with 404 HTTP
+    # response.
+    #
+    # The `404.haml` template is **not** wrapped within the `layout.haml` template when rendered,
+    # even if one exists within `settings.views`.
+    #
+    # For example:
+    #
+    #     |-- content
+    #     |   `-- index.haml
+    #     `-- themes
+    #         `-- default
+    #             `-- views
+    #                 `-- 404.haml
+    #
+    #     GET /page_not_found => 404 themes/default/views/404.haml
+    #
+    not_found do
+      haml :"404", :layout => false
+    end
+
+    # Attempts to render style sheet templates found within `settings.styles`
+    #
+    # First, the application attempts to match the URI path with a public CSS file stored in
+    # `settings.public`.  If a public CSS file is found, the handler will:
+    #
+    #   * Send the public CSS file with a 200 HTTP response code
+    #   * Halt execution
+    #
+    #  For example:
+    #
+    #     `-- themes
+    #         `-- default
+    #             `-- public
+    #                 `-- styles
+    #                     `-- reset.css
+    #
+    #     GET /styles/reset.css => 200 themes/default/public/styles/reset.css
+    #
+    # If no match is found, the route handler attempts to match the URI path with a style sheet
+    # template stored in `settings.styles`.  If a style sheet template is found, the handler will:
+    #
+    #   * Convert the style sheet template from Sass to CSS
+    #   * Send the converted style with a 200 HTTP response code
+    #   * Halt execution
+    #
+    # For example:
+    #
+    #     `-- themes
+    #         `-- default
+    #             `-- styles
+    #                 `-- screen.sass
+    #
+    #     GET /styles/screen.css => 200 themes/default/styles/screen.sass
+    #
+    # **It's intended that requests to public CSS files and requests to style sheet templates share
+    # the `/styles/` prefix.**
+    #
+    # Finally, if no matches are found, the route handler passes execution to the `NOT_FOUND` error
+    # handler.
+    #
+    get "/styles/*.css" do |uri_path|
+      render_style_sheet! uri_path
+      not_found
+    end
+
+    ###############################################################################################
+
+    private
+
+    # Given a URI path, attempts to render a style sheet, if it exists, and halt
+    #
+    # @param [String] uri_path
+    #
+    def render_style_sheet!(uri_path)
+      styles_match     = File.join(settings.styles, "*")
+      style_sheet_path = build_style_sheet_path(uri_path)
+
+      return unless File.fnmatch(styles_match, style_sheet_path)
+      return unless File.file?(style_sheet_path)
+
+      content_type "text/css"
+      halt sass(uri_path.to_sym, :views => settings.styles)
+    end
+
+    # Given a URI path, build a path to a potential style sheet
+    #
+    # @param [String] uri_path
+    # @param [String] format (defaults to `sass`)
+    # @return [String] The path to a potential style sheet
+    #
+    def build_style_sheet_path(uri_path, format = "sass")
+      File.expand_path("#{uri_path}.#{format}", settings.styles)
+    end
+
+    public
+
+    # Attempts to render content page templates found within `settings.content`
+    #
+    # First, the application attempts to match the URI path with a public file stored in
+    # `settings.public`.  If a public file is found, the handler will:
+    #
+    #   * Send the public file with a 200 HTTP response code
+    #   * Halt execution
+    #
+    # For example:
+    #
+    #     `-- themes
+    #         `-- default
+    #             `-- public
+    #                 `-- hello_word.html
+    #
+    #     GET /hello_word.html => 200 themes/default/public/hello_word.html
+    #
+    # If no match is found, the route handler attempts to match the URI path with a content page
+    # template stored in `settings.content`.  If a content page template is found, the handler will:
+    #
+    #   * Read the content page into memory and assign it to the `@content_page` instance variable
+    #   * Render the content page's view template file (see `Mango::ContentPages`)
+    #     * A `RuntimeError` is raised if the view template does not exist within `settings.views`
+    #   * Send the rendered page with a 200 HTTP response code and halt execution
+    #
+    # In addition, if a `layout.haml` template exists within `settings.views`, the page's view
+    # template is wrapped within this layout when rendered.
+    #
+    # For example:
+    #
+    #     |-- content
+    #     |   `-- index.haml
+    #     `-- themes
+    #         `-- default
+    #             `-- views
+    #                 |-- layout.haml
+    #                 `-- page.haml
+    #
+    #     GET /index => 200 content/index.haml +
+    #                       themes/default/views/page.haml +
+    #                       themes/default/views/layout.haml
+    #
+    # Finally, if no matches are found, the route handler passes execution to the `NOT_FOUND` error
+    # handler.
+    #
+    get "/*" do |uri_path|
+      render_index_file! uri_path
+      render_content_page! uri_path
+      not_found
+    end
+
+    ###############################################################################################
+
+    private
+
+    # Given a URI path, attempts to send an index.html file, if it exists, and halt
+    #
+    # @param [String] uri_path
+    #
+    def render_index_file!(uri_path)
+      return unless uri_path[-1] == "/"
+
+      index_match     = File.join(settings.public, "*")
+      index_file_path = build_index_file_path(uri_path)
+
+      return unless File.fnmatch(index_match, index_file_path)
+      return unless File.file?(index_file_path)
+
+      send_file index_file_path
+    end
+
+    # Given a URI path, build a path to a potential index.html file
+    #
+    # @param [String] uri_path
+    # @return [String] The path to a potential index.html file
+    #
+    def build_index_file_path(uri_path)
+      uri_path = File.join(uri_path, "index.html")
+      File.expand_path(uri_path, settings.public)
+    end
+
+    ###############################################################################################
+
+    private
+
+    # Given a URI path, attempts to render a content page, if it exists, and halt
+    #
+    # @param [String] uri_path
+    # @raise [RuntimeError] Raised when the content page's view template cannot be found
+    #
+    def render_content_page!(uri_path)
+      content_match     = File.join(settings.content, "*")
+      content_page_path = build_content_page_path(uri_path)
+      return unless File.fnmatch(content_match, content_page_path)
+
+      begin
+        @content_page = Mango::ContentPage.find_by_path(content_page_path)
+      rescue Mango::ContentPage::PageNotFound
+        return
+      end
+
+      begin
+        halt haml(@content_page.view)
+      rescue Errno::ENOENT
+        view_path = File.expand_path("#{@content_page.view}.haml", settings.views)
+        raise "Unable to find a view template file -- #{view_path}"
+      end
+    end
+
+    # Given a URI path, build a path to a potential content page
+    #
+    # @param [String] uri_path
+    # @return [String] The path to a potential content page
+    #
+    def build_content_page_path(uri_path)
+      uri_path += "index" if uri_path.empty? || uri_path[-1] == "/"
+      File.expand_path(uri_path, settings.content)
+    end
+
+  end
+end