texas 0.1.6 → 0.1.7

data/lib/texas/output_helper.rb

@@ -0,0 +1,58 @@
+module Texas
+  # The OutputHelper module provides helper methods to output information
+  # to STDOUT.
+  module OutputHelper
+
+    # Puts the given arguments
+    #
+    def trace(*args)
+      puts *args
+    end
+
+    # Traces the result of the given block if Texas is running in verbose mode
+    #
+    # Example:
+    #   verbose { "Debug information: " + some_expensive_lookup.to_s }
+    #
+    def verbose(&block)
+      if Texas.verbose
+        trace block.()
+      end
+    end
+
+    # Traces the result of the given block if warnings are enabled
+    #
+    # Example:
+    #   warning { "This might cause problems: " + something.to_s }
+    #
+    def warning(&block)
+      if Texas.warnings
+        trace TraceInfo.new("WARNING", block.().to_s, :yellow)
+      end
+    end
+
+    class TraceInfo
+      COL_LENGTH = 20
+
+      def initialize(left, right, color = nil)
+        @left, @right, @color = left, right, color
+      end
+
+      def left
+        l = (@left.to_s + " ").rjust(COL_LENGTH)
+        l = l.__send__(@color) if @color
+        l.bold
+      end
+
+      def right
+        r = @right.to_s
+        r = r.__send__(@color) if @color
+        r
+      end
+
+      def to_s
+        left + right
+      end
+    end
+  end
+end

data/lib/texas/runner.rb

@@ -1,76 +1,57 @@
-def verbose(&block)
-  if Texas.verbose
-    value = block.()
-    if value.is_a?(String)
-      puts value
-    else
-      pp value
-    end
-  end
-end
-
-def warning(&block)
-  if Texas.warnings
-    value = block.()
-    if value.is_a?(String)
-      puts "[WARNING]".yellow + " #{value}"
-    else
-      pp value
-    end
-  end
-end
-
 module Texas
+  # An instance of Texas::Runner is used to run a build process.
+  #
   class Runner
+    include Texas::OutputHelper
+
+    # Returns the instance of the performed task. 
+    # Normally a Texas::Build::Base derived object.
+    #
     attr_reader :task_instance
 
-    def initialize(force_options = nil)
-      @options = if force_options.nil?
-        Texas::OptionParser.new(ARGV).parse
-      else
-        opts = Texas::OptionParser.new([]).parse
-        force_options.each { |k, v| opts.send("#{k}=", v) }
-        opts
-      end
+    # Initializes the Runner with an array or hash of options.
+    #
+    # Example:
+    #   Texas::Runner.new(%w(-w --no-color))
+    #   Texas::Runner.new(:warnings => true, :colors => false)
+    #
+    def initialize(args = nil)
+      @options = options_from_args args
       extend_string_class
       Texas.verbose = @options.verbose
       Texas.warnings = @options.warnings
       load_local_libs if @options.load_local_libs
+      verbose { TraceInfo.new(:starting, task_class, :magenta) }
       @task_instance = task_class.new(@options)
       run
     end
-    
-    # Display the error message that caused the exception.
-    #
-    def display_error_message(ex)
-      puts "#{@options.task} aborted!"
-      puts ex.message
-      if @options.backtrace
-        puts ex.backtrace
-      else
-        puts "(See full trace with --backtrace)"
-      end
-    end
 
-    # Extends String with Term::ANSIColor if options demand it.
+    # Extends String with Term::ANSIColor.
     #
     def extend_string_class
-      mod = @options.colors ? Term::ANSIColor : Term::NoColor
-      String.send :include, mod
+      String.send(:include, Term::ANSIColor)
+      Term::ANSIColor::coloring = @options.colors
     end
 
     # Load lib/init.rb if present in current project.
     #
     def load_local_libs
       init_file = File.join(@options.work_dir, "lib", "init.rb")
-      require init_file if File.exist?(init_file)
+      load init_file if File.exist?(init_file)
+    end
+
+    def options_from_args(args)
+      if args.is_a?(Hash)
+        opts = Texas::OptionParser.new([]).parse
+        args.each { |k, v| opts.send("#{k}=", v) }
+        opts
+      else
+        Texas::OptionParser.new(args).parse
+      end
     end
 
     def run
-      @task_instance.run
-    rescue Exception => ex
-      display_error_message ex
-      exit 1
+      Build.run_with_nice_errors(@task_instance) { exit 1 }
     end
 
     # Returns the class for the given task.
@@ -88,7 +69,7 @@ module Texas
       begin
         eval("::Texas::Task::#{class_name}")
       rescue
-        puts "Failed to fallback for Texas::Task::#{class_name}"
+        trace "Failed to fallback for Texas::Task::#{class_name}"
         exit
       end
     end

data/lib/texas/task/base.rb

@@ -1,6 +1,7 @@
 module Texas
   module Task
     class Base
+      include Texas::OutputHelper
       attr_accessor :options
 
       def initialize(_options, _build = nil)

data/lib/texas/task/new_project.rb

@@ -18,7 +18,7 @@ module Texas
           if Dir[File.join(dest_dir, "*")].empty?
             FileUtils.rm_r dest_dir
           else
-            warn "texas: directory is not empty: #{dest_dir}"
+            trace "texas: directory is not empty: #{dest_dir}"
             exit 1
           end
         end

data/lib/texas/task/watch.rb

@@ -8,32 +8,43 @@ module Texas
       end
 
       def run
-        self.class.run_options = options
+        self.class.run_options = options.to_h.merge(:task => :build)
         dirs = Task::Watch.directories_to_watch
         Listen.to(*dirs) do |modified, added, removed|
           Task::Watch.rebuild
         end
       end
 
-      def self.directories_to_watch
-        arr = []
-        arr << "tex"      if Dir.exists?("tex")
-        arr << "contents" if Dir.exists?("contents")
-        arr << "figures"  if Dir.exists?("figures")
-        arr << Texas.texas_dir
-        arr
-      end
+      class << self
+        include Texas::OutputHelper
 
-      def self.rebuild
-        started_at = Time.now.to_i
-        Build::Final.new(run_options).run
-        finished_at = Time.now.to_i
-        puts (finished_at - started_at).to_s + " seconds to rebuild"
-      rescue Exception => e
-        puts @build.current_template.filename
-        puts "[ERROR] while building \n#{e}"
-      end
+        # Returns the directories watched by default.
+        #
+        def default_directories
+          [Texas.contents_subdir_name, "lib/", Texas.texas_dir]
+        end
 
+        # Returns the directories watched, which can be extended.
+        #
+        # Example:
+        #   Texas::Task::Watch.directories << "images/"
+        #   
+        def directories
+          @@directories ||= default_directories
+        end
+
+        def directories_to_watch
+          directories.uniq
+        end
+
+        def rebuild
+          started_at = Time.now.to_i
+          Texas::Runner.new(run_options)
+          finished_at = Time.now.to_i
+          time = finished_at - started_at
+          trace TraceInfo.new(:rebuild, "in #{time} seconds", :green)
+        end 
+      end
     end
   end
 end

data/lib/texas/template.rb

@@ -1,7 +1,11 @@
 module Texas
   module Template
     class << self
-      attr_accessor :handlers, :known_extensions
+      # Returns a map of file extensions to handlers
+      attr_accessor :handlers
+
+      # Returns all known template extensions
+      attr_accessor :known_extensions
 
       # Returns a template handler for the given filename
       #
@@ -49,7 +53,7 @@ module Texas
       #
       # Example:
       #   Template.create("some_file.tex.erb", build)
-      #   # => #<Template::Runner::TeX ...>
+      #   # => #<Texas::Template::Runner::TeX ...>
       #
       def create(filename, build)
         handler(filename).new(filename, build)

data/lib/texas/template/helper/base.rb

@@ -19,10 +19,26 @@ module Texas
         # Returns a subdir with the current template's basename
         #
         # Example:
-        # In /example/introduction.tex.erb this method 
-        # returns "/example/introduction" if that directory exists
-        # and nil if it doesn't.
+        #   # Given the following contents directory:
+        #   #
+        #   # contents/
+        #   #   section-1/
+        #   #     subsection-1-1.tex.erb
+        #   #   contents.tex.erb
+        #   #   section-1.tex-erb
+        #   #   section-2.tex-erb
+        #   #
         #
+        #   # section-1.tex.erb
+        #
+        #   <%= path_with_templates_basename %>
+        #   # => "section-1"
+        #   
+        #   # section-2.tex.erb
+        #
+        #   <%= path_with_templates_basename %>
+        #   # => nil
+        #   
         def path_with_templates_basename
           subdir = Template.basename @output_filename
           File.directory?(subdir) ? subdir : nil
@@ -42,11 +58,8 @@ module Texas
         #
         def find_template_file(parts, possible_exts = [], possible_paths = default_search_paths)
           possible_paths.each do |base|
-            ([""] + possible_exts).each do |ext|
-              path = parts.clone.map(&:to_s).map(&:dup)
-              path.unshift base.to_s
-              path.last << ".#{ext}" unless ext.empty?
-              filename = File.join(*path)
+            (possible_exts + [""]).each do |ext|
+              filename = filename_for_find(parts, base, ext)
               return filename if File.exist?(filename) && !File.directory?(filename)
             end
           end
@@ -63,14 +76,35 @@ module Texas
           end
         end
 
+        def filename_for_find(parts, base, ext = nil)
+          path = [parts].flatten.map(&:to_s).map(&:dup)
+          path.unshift base.to_s
+          path.last << ".#{ext}" unless ext.empty?
+          File.join(*path)
+        end
+
         # Renders a partial with the given locals.
         #
+        # Example:
+        #   <%= partial :some_partial, :some_value => 42 %>
+        #   
         def partial(name, locals = {})
           render("_#{name}", locals)
         end
 
         # Renders one or more templates with the given locals.
         #
+        # Example:
+        #   <%= render :template => "some_template" %>
+        #   
+        #   # or by shorthand:
+        #   
+        #   <%= render :some_template %>
+        #
+        #   # or render multiple templates with a single call:
+        #   
+        #   <%= render %w(some_template some_other_template) %>
+        #
         def render(options, locals = {})
           if [String, Symbol].include?(options.class)
             options = {:templates => [options]}
@@ -94,12 +128,30 @@ module Texas
 
         # Returns all extensions the Template::Runner can handle.
         #
+        # Example:
+        #   template_extensions
+        #   # => ["tex", "tex.erb", "md", "md.erb"]
+        #   
         def template_extensions
           Texas::Template.known_extensions
         end
 
         # Returns all templates in the current template's path matching the given glob
         #
+        # Example:
+        #   # Given the following contents directory:
+        #   #
+        #   # contents/
+        #   #   _some_partial.tex.erb
+        #   #   contents.tex.erb
+        #   #   other_latex.tex
+        #   #   other_markdown.md.erb
+        #   #   some_template.tex.erb
+        #   #
+        #
+        #   templates_by_glob("*.tex.erb")
+        #   # => ["_some_partial", "contents", "other_markdown", "some_template"]
+        #   
         def templates_by_glob(glob = "*") 
           files = Dir[File.join(__path__, glob)]
           templates = files.map do |f| 
@@ -107,7 +159,6 @@ module Texas
           end
           templates.uniq.sort
         end
-
       end
     end
   end

data/lib/texas/template/helper/tex.rb

@@ -50,12 +50,10 @@ module Texas
           template.write
         end
 
-        private
-
         # Returns a path relative to the build_path
         #
         # Example:
-        #   input_path("/home/rene/github/sample_project/tmp/build/contents.tex.erb")
+        #   relative_template_filename("/home/rene/github/sample_project/tmp/build/contents.tex.erb")
         #   # => "contents.tex.erb"
         #
         def relative_template_filename(path, possible_exts = Template.known_extensions)
@@ -66,7 +64,7 @@ module Texas
         # Returns a path relative to the build_path and strips the template extension
         #
         # Example:
-        #   input_path("/home/rene/github/sample_project/tmp/build/contents.tex.erb")
+        #   relative_template_basename("/home/rene/github/sample_project/tmp/build/contents.tex.erb")
         #   # => "contents"
         #
         def relative_template_basename(path)

data/lib/texas/template/runner.rb

@@ -6,8 +6,5 @@ module Texas
 end
 
 require_relative 'runner/base'
-
-all_rbs = Dir[ File.join( File.dirname(__FILE__), "runner", "*.rb" ) ]
-all_rbs.each do |t|
-  require t
-end
+require_relative 'runner/tex'
+require_relative 'runner/md'

data/lib/texas/template/runner/base.rb

@@ -1,13 +1,23 @@
-require 'texas/template/helper/base'
-require 'texas/template/helper/info'
+require_relative '../helper/base'
+require_relative '../helper/info'
 require 'erb'
 
 module Texas
+  # Runs and renders a template.
+  #
   class Template::Runner::Base
+    include Texas::OutputHelper
     include Texas::Template::Helper::Base
     include Texas::Template::Helper::Info
 
-    attr_accessor :build, :content, :filename
+    # Returns the build object
+    attr_accessor :build
+
+    # Returns the original content of the template
+    attr_accessor :content
+
+    # Returns the location of the template (in the build directory)
+    attr_accessor :filename
 
     def initialize(_filename, _build)
       self.filename = _filename
@@ -16,25 +26,48 @@ module Texas
       @output_filename = filename.gsub(/(\.erb)$/, '')
     end
 
-    # TODO: Use Forwardable
-    def root; build.root; end
-
+    # Shorthand to the build's __path__.
+    #
     def build_path
       build.__path__
     end
 
+    # Returns this template's path.
+    #
     def __path__
       File.dirname filename
     end
     
+    # Shorthand to the build's config's document object.
+    # Can be used inside templates to display config information.
+    #
+    # Example: 
+    #   <%= document.title %>
+    #
     def document
-      build.document_struct
+      build.config.document
     end
 
+    # Shorthand to the build's store object.
+    # Can be used inside templates to store information.
+    #
     def store
       build.store
     end
 
+    # Shorthand to the template's locals object.
+    # Can be used inside templates.
+    #
+    # Example:
+    #   # some_template.tex.erb
+    #
+    #   Value: <%= o.some_value %>
+    #
+    #   # contents.tex.erb
+    #
+    #   <%= render :some_template, :some_value => 42
+    #
+    #   # => "Value: 42"
     def o
       @locals
     end
@@ -43,17 +76,21 @@ module Texas
       @erbout << str
     end
 
+    # Renders the template into a String.
+    #
     def __render__(locals = {})
       @locals = OpenStruct.new(locals)
       ERB.new(@content, nil, nil, "@erbout").result(binding)
     rescue TemplateError => ex
       raise ex
-    rescue Exception => ex
+    rescue StandardError => ex
       raise TemplateError.new(self, ex.message, ex)
     end
 
+    # Runs the template with the given local variables.
+    #
     def __run__(locals = {})
-      verbose { "[T] #{filename.gsub(build_path, '')}".dark }
+      verbose { TraceInfo.new(:template, filename.gsub(build_path, ''), :dark) }
 
       old_current_template = build.current_template
       build.current_template = self
@@ -62,9 +99,20 @@ module Texas
       @output
     end
 
-    def after_write; end
-    def after_render(str); str; end
+    # Called after write.
+    #
+    def after_write
+    end
+
+    # Called after __render__.
+    # Can be overriden to modify the rendered contents of the template.
+    #
+    def after_render(str)
+      str
+    end
 
+    # Runs the template and writes it to disk afterwards.
+    #
     def write
       __run__
       File.open(@output_filename, 'w') {|f| f.write(@output) }