neapolitan 0.2.0 → 0.3.0

data/HISTORY.rdoc

@@ -1,8 +1,26 @@
 = RELEASE HISTORY
 
+== 0.3.0 / 2010-11-09
+
+This release entails a fairly major overhaul of the API. Primarily, the
+`Document` class has been removed, so the `Template` class now handles
+all cases.
+
+Changes:
+
+* Deprecate Document class, in favor of single Template class interface.
+* Deprecate Command class and move code to class method(s) of Neapolitan.
+* Add #select and #reject methods to Template class.
+
+
 == 0.2.0 / 2010-09-14
 
-Renamed project from "Chocolates" to "Neapolitan".
+This release renames project from "Chocolates" to "Neapolitan". It's also
+the first release that is mature enough for general use.
+
+Changes:
+
+* Renamed project from "chocolates" to "neapolitan".
 
 
 == 0.1.0 / 2008-10-25

data/LICENSE

@@ -1,23 +1,205 @@
-The MIT License
+.
 
-Copyright (c) 2009 Thomas Sawyer
+                             Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+   1. Definitions.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
 
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
 
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+.

data/README.rdoc

@@ -1,5 +1,7 @@
 = Neapolitan
 
+Copyright (c) 2010 Thomas Sawyer
+
 * home: http://rubyworks.github.com/neapolitan
 * code: http://github.com/rubyworks/neapolitan
 
@@ -20,7 +22,7 @@ you a whole box to pick from.
 
 == SYNOPSIS
 
-For now please see the Neapolitan website and API documentation.
+For now please see the Neapolitan website and online documentation.
 
 
 == HOW TO INSTALL

data/bin/neapolitan

@@ -1,3 +1,3 @@
 #!/usr/bin/env ruby
-require 'neapolitan/command'
-Neapolitan::Command.main(*ARGV)
+require 'neapolitan'
+Neapolitan.cli(*ARGV)

data/lib/neapolitan.rb

@@ -1,2 +1,424 @@
 require 'neapolitan/meta/data'
-require 'neapolitan/document'
+#require 'tilt'
+require 'malt'
+
+module Neapolitan
+
+  #
+  def self.load(source, options={})
+    Template.new(source, options)
+  end
+
+  #
+  def self.text(source, options={})
+    Template.new(source.to_s, options)
+  end
+
+  #
+  def self.file(fname, options={})
+    Template.new(File.new(fname), options)
+  end
+
+  #
+  class Template
+
+    # Template text.
+    attr :text
+
+    # File name of template, if given.
+    attr :file
+
+    # Templating format to apply "whole-clothe".
+    attr :stencil
+
+    # Default format(s) for undecorated parts.
+    # If not otherwise set the default is 'html'.
+    attr :default
+
+    # Common format(s) to be applied to all parts.
+    # These are applied at the end.
+    attr :common
+
+    # Rendering formats to disallow.
+    #attr :reject
+
+    # Header data, also known as <i>front matter</i>.
+    attr :header
+
+    #
+    def initialize(source, options={})
+      case source
+      when ::File
+        @file = source.path #name
+        @text = source.read
+        source.close
+      when ::IO
+        @text = source.read
+        @file = options[:file]
+        source.close
+      when ::String
+        @text = source
+        @file = options[:file]
+      when Hash
+        options = source
+        source  = nil
+        @file = options[:file]
+        @text = File.read(@file)
+      end
+
+      @stencil = options[:stencil]
+      @default = options[:default] || 'html'
+      @common  = options[:common]
+      #@reject  = options[:reject]
+
+      parse
+    end
+
+    #
+    def inspect
+      if file
+        "<#{self.class}: @file='#{file}'>"
+      else
+        "<#{self.class}: @text='#{text[0,10]}'>"
+      end
+    end
+
+    # Rejection formats.
+    #--
+    # TODO: filter common and default
+    #++
+    def reject(&block)
+      parts.each do |part|
+        part.formats.reject!(&block)
+      end
+    end
+
+    # Select formats.
+    #--
+    # TODO: filter common and default
+    #++
+    def select(&block)
+      parts.each do |part|
+        part.formats.select!(&block)
+      end
+    end
+
+    # Unrendered template parts.
+    def parts
+      @parts
+    end
+
+    #
+    def render(data={}, &block)
+      if !block
+        case data
+        when Hash
+          yld = data.delete('yield')
+          block = Proc.new{ yld } if yld
+        end
+        block = Proc.new{''} unless block
+      end
+
+      renders = parts.map{ |part| render_part(part, data, &block) }
+
+      Rendering.new(renders, header)
+    end
+
+    # :call-seq:
+    #   save(data={}, &block)
+    #   save(file, data={}, &block)
+    #
+    def save(*args, &block)
+      data = Hash===args.last ? args.pop : {}
+      path = args.first
+
+      rendering = render(data, &block)
+
+      path = path || rendering.header['output']
+      path = path || path.chomp(File.extname(file))
+
+      path = Dir.pwd unless path
+      if File.directory?(path)
+        file = File.join(path, file.chomp(File.extname(file)) + extension)
+      else
+        file = path
+      end
+
+      if $DRYRUN
+        $stderr << "[DRYRUN] write #{fname}"
+      else
+        File.open(file, 'w'){ |f| f << rendering.to_s }
+      end
+    end
+
+  private
+
+    #--
+    # TODO: Should a stencil be applied once to the entire document?
+    #++
+    def parse
+      @parts = []
+
+      sect = text.split(/^\-\-\-/)
+
+      if sect.size == 1
+        @header = {}
+        @parts << Part.new(sect[0]) #, *[@stencil, @default].compact.flatten)
+      else
+        sect.shift if sect.first.strip.empty?
+
+        head = sect.shift
+        head = YAML::load(head)
+        parse_header(head)
+
+        sect.each do |body|
+          index   = body.index("\n")
+          formats = body[0...index].strip
+          formats = formats.split(/\s+/) if String===formats
+          #formats = @default if formats.empty?
+          #formats.unshift(@stencil) if @stencil
+          text    = body[index+1..-1]
+          @parts << Part.new(text, *formats)
+        end
+      end
+    end
+
+    #
+    def parse_header(head)
+      @header  = head
+      @default = head.delete('default'){ @default }
+      @common  = head.delete('common'){ @common }
+    end
+
+    #
+    def render_part(part, data, &block)
+      formats = part.formats
+      formats = default if formats.empty?
+      formats = [formats, common].flatten.compact
+
+      #case reject
+      #when Array
+      #  formats = formats - reject.map{|r|r.to_s}
+      #when Proc
+      #  formats = formats.reject(&reject)
+      #end
+
+      formats = [stencil, *formats].compact
+
+      formats.inject(part.text) do |text, format|
+        factory.render(text, format, data, &block)
+      end
+    end
+
+    #
+    def factory
+      @factory ||= Factory.new
+    end
+
+  end
+
+  # A part is a section of a template. Templates can be segmented into
+  # parts using the '--- FORMAT' notation.
+  class Part
+    # Rendering formats (html, rdoc, markdown, textile, etc.)
+    attr :formats
+
+    # Body of text as given in the part.
+    attr :text
+
+    #
+    def initialize(text, *formats)
+      @text     = text
+      @formats  = formats
+    end
+  end
+
+  # Template Rendering
+  class Rendering
+    #
+    def initialize(renders, header)
+      @renders = renders
+      @summary = renders.first
+      @output  = renders.join("\n")
+      @header  = header
+    end
+
+    #
+    def to_s
+      @output
+    end
+
+    # Renderings of each part.
+    def to_a
+      @renders
+    end
+
+    # Summary is the rendering of the first part.
+    def summary
+      @summary
+    end
+
+    #
+    def header
+      @header
+    end
+  end
+
+  # Controls rendering to a variety of back-end templating
+  # and markup systems via Malt.
+  class Factory
+    #
+    attr :types
+
+    #
+    def initialize(options={})
+      @types = options[:types]
+    end
+
+    #
+    def render(text, format, data, &yld) 
+      case format
+      when /^coderay/
+        coderay(text, format)
+      when /^syntax/
+        syntax(text, format)
+      else
+        render_via_malt(text, format, data, &yld)
+      end
+    end
+
+    #
+    def render_via_malt(text, format, data, &yld)
+      doc = malt.text(text, :type=>format.to_sym)
+      doc.render(data, &yld)
+    end
+
+    #
+    def render_via_tilt(text, format, data, &yld)
+      if engine = Tilt[format]
+        case data
+        when Hash
+          scope = Object.new
+          table = data
+        when Binding
+          scope = data.eval('self')
+          table = {}
+        else # object scope
+          scope = data
+          table = {}
+        end
+        engine.new{text}.render(scope, table, &yld)
+      else
+        text
+      end
+    end
+
+    #
+    def malt
+      @malt ||= (
+        if types && !types.empty?
+          Malt::Machine.new(:types=>types)
+        else
+          Malt::Machine.new
+        end
+      )
+    end
+
+    def coderay(input, format)
+      require 'coderay'
+      format = format.split('.')[1] || :ruby #:plaintext
+      tokens = CodeRay.scan(input, format.to_sym) #:ruby
+      tokens.div()
+    end
+
+    #
+    def syntax(input, format)
+      require 'syntax/convertors/html'
+      format = format.split('.')[1] || 'ruby' #:plaintext
+      lines  = true
+      conv   = Syntax::Convertors::HTML.for_syntax(format)
+      conv.convert(input,lines)
+    end
+
+    #
+    #def render_stencil(stencil, text, attributes)
+    #  case stencil
+    #  when 'rhtml'
+    #    erb(text, attributes)
+    #  when 'liquid'
+    #    liquid(text, attributes)
+    #  else
+    #    text
+    #  end
+    #end
+
+    public
+
+    #
+    def self.render(text, format, data, &yld) 
+      new.render(text, format, data, &yld)
+    end
+
+  end
+
+  # Command line interface.
+  def self.cli(*argv)
+    options = {}
+
+    option_parser(options).parse!(argv)
+
+    if src = options[:source]
+      data = YAML.load(File.new(src))
+    else
+      data = {} #@source ||= YAML.load(STDIN.read)
+    end
+
+    files = argv
+
+    begin
+      files.each do |file|
+        template = Template.new(File.new(file))
+        if options[:output]
+          #template.save(data)
+        else
+          puts template.render(data)
+        end
+      end
+    rescue => e
+      $DEBUG ? raise(e) : puts(e.message)
+    end
+  end
+
+  #--
+  # TODO: Save to output.
+  #++
+  def self.option_parser(options)
+    require 'optparse'
+
+    OptionParser.new do |opt|
+      opt.banner = "neapolitan [file1 file2 ...]"
+      #opt.on("--output", "-o [PATH]", "save output to specified directory") do |path|
+      #  options[:output] = path
+      #end
+      opt.on("--source", "-s [FILE]", "data souce (YAML file)") do |file|
+        options[:source] = file
+      end
+      opt.on("--trace", "show extra operational information") do
+        $TRACE = true
+      end
+      opt.on("--dryrun", "-n", "don't actually write to disk") do
+        $DRYRUN = true
+      end
+      opt.on("--debug", "run in debug mode") do
+        $DEBUG   = true
+        $VERBOSE = true
+      end
+      opt.on_tail("--help", "display this help message") do
+        puts opt
+        exit
+      end
+    end
+
+  end
+
+end