docjs 0.1

data/lib/parser/exceptions.rb

@@ -0,0 +1,6 @@
+module Parser
+
+  class NotValidTokenline < Exception
+  end
+
+end

data/lib/parser/meta_container.rb

@@ -0,0 +1,20 @@
+# ../data.img#1772248:1
+module Parser
+
+  # is included by {CodeObject::Base} and {Parser::Comment}
+  module MetaContainer
+  
+    attr_reader :filepath, :source, :line_start
+  
+    def add_meta_data(filepath, source, line_start)
+      @filepath, @source, @line_start = filepath, source, line_start+1 # counting from 1
+    end
+    
+    def clone_meta(other)
+      @filepath, @source, @line_start = other.filepath, other.source, other.line_start
+    end
+  
+  end
+
+end
+

data/lib/parser/parser.rb

@@ -0,0 +1,269 @@
+# ../data.img#1869414:2
+require 'strscan'
+require_relative 'comment_parser'
+
+#
+# ![Parser Overview](../uml/Parser.svg)
+#
+#
+module Parser
+
+  NO_BR = /((?!\n)\s)/
+  ALL = /./m
+  
+  # Multiline Comments
+  M_START = /\/\*+/
+  
+  # End of multiline comment with all leading whitespaces (no breaks)
+  M_END = /#{NO_BR}*\*+\//
+  
+  # Singleline Comments
+  S_START = /\/\//
+  S_END = /\n/
+
+  
+  LINE_START = /(#{NO_BR})*\*+#{NO_BR}?/
+  LINE_END = /\n/
+  EMPTY_LINE = /^\s*$/
+    
+  # CAUTION: \s can contain breaks "\n"
+  TOKENLINE_START = /\s*@/
+  TOKENLINE = /
+    #{TOKENLINE_START}
+      (?<name>\w+)
+      (?:#{NO_BR}?(?<content>#{ALL}+)|$)
+    /x
+    
+  # String delimiter
+  S_STRING = /'/
+  D_STRING = /"/
+  
+  REGEXP_START = /\/[^\/]/
+  REGEXP_END = /\//
+  
+  NON_COMMENT_PATTERNS = {
+    S_STRING     => S_STRING,
+    D_STRING     => D_STRING,
+    REGEXP_START => REGEXP_END  
+  } 
+  
+  NON_CODE_PATTERNS = {    
+    M_START      => M_END,
+    S_START      => S_END,
+    S_STRING     => S_STRING,
+    D_STRING     => D_STRING,
+    REGEXP_START => REGEXP_END    
+  } 
+   
+  class Parser
+  
+    attr_reader :filepath, :offset
+  
+    # A new StringScanner instance will be used to {#parse parse} the given
+    # `input`.
+    #
+    # @param [String] input
+    def initialize(input, args = {})
+      
+      raise Exception, "Expected input to be a String, got #{input.class}" unless input.is_a? String
+      
+      # Default Values
+      @filepath = args[:filepath]  || "No File specified"
+      @offset   = args[:offset]    || -1 # we are adding 1 later
+      
+      
+      # clean input and convert windows linebreaks to normal ones
+      @to_parse = input.gsub(/\r\n/, "\n")
+      @scanner = StringScanner.new @to_parse
+      @comments = []
+    end  
+    
+    
+    # Recursivly parses the {#initialize given input} and thereby ignores
+    # strings.
+    # @todo Rewrite to use skip_intelligent_until
+    # @return [Array<Parser::Comment>] the parsed comment-stream
+    def parse()
+      @scanner.skip /\s/
+      @scanner.skip_until /#{M_START}|#{S_START}|#{NON_COMMENT_PATTERNS.keys.join('|')}|$/
+      
+      found = @scanner.matched
+      
+      if found.match M_START
+        parse_comment_until(M_END)
+        
+      elsif found.match S_START
+        parse_comment_until(S_END)
+        
+      else
+        matched_pattern = NON_COMMENT_PATTERNS.detect do |start_pattern, end_pattern|    
+          found.match start_pattern
+        end       
+        @scanner.skip_escaping_until matched_pattern.last unless matched_pattern.nil?    
+      end
+      
+      if @scanner.eos?
+        return @comments
+      else
+        parse
+      end
+    end
+    
+    def self.parse_file(path)
+      stream = File.read path
+      Parser.new(stream, :filepath => path).parse
+    end
+    
+    protected
+    
+    def parse_comment_until(ending)
+      content = @scanner.scan_until_ahead ending      
+      comment = CommentParser.new(content).parse unless content.nil?  
+           
+      # only proceed, if it is a tokenized comment
+      return parse unless comment.has_tokens?  
+      
+      # search scope for that comment
+      @scanner.skip /\n/
+      scope = @scanner.save_scanned { find_scope } 
+              
+      code_line = @to_parse.line_of(scope.min) + @offset + 1
+      source = @to_parse[scope]     
+      
+      # Add Metadata
+      comment.add_meta_data @filepath, source, code_line   
+      
+      # Save Comment
+      @comments << comment
+      
+      comment.add_children Parser.new(source, :filepath => @filepath, :offset => code_line-1).parse      
+    end    
+    
+    def find_scope(scope_stack = [], ignore_line_end = false)
+
+      if ignore_line_end    
+        return if scope_stack.empty?      
+        @scanner.skip /\s/
+      end
+      
+      # adding |$ only if we don't ignore line_ends (which is most of the time)
+      @scanner.intelligent_skip_until /\{|\(|\}|\)#{'|$' unless ignore_line_end}/
+      
+      match = @scanner.matched
+      
+      case match
+      when '{'
+        find_scope(scope_stack << '}', ignore_line_end)
+        
+      when '('          
+        find_scope(scope_stack << ')', ignore_line_end)
+        
+      when '}', ')'
+        if(scope_stack.last == match)
+          scope_stack.pop
+          find_scope(scope_stack, ignore_line_end)
+        else
+          # currently just ignore non matching closing pairs
+          puts "I'm ignoring #{match} at #{@scanner.pos} of #{@filepath}"
+        end      
+      else
+        
+        if ignore_line_end
+          if not @scanner.eos?
+            find_scope(scope_stack, ignore_line_end)
+            
+          elsif not scope_stack.empty?
+            raise "Unmatched Scope-Stack: #{scope_stack}"
+          end
+        
+        else        
+          find_scope(scope_stack, true)  unless scope_stack.empty?
+        end
+      end 
+    end    
+        
+  end
+  
+end
+
+# We have to extend StringScanner a little bit to fit our needs.
+#
+# @see Parser::Parser
+# @see Parser::CommentParser
+class StringScanner  
+  
+  # returns the string until `pattern` matches, then consums `pattern`
+  #
+  # @example
+  #   scanner = StringScanner.new("hello     world")
+  #   scanner.scan_until_ahead(/\s+/) #=> "hello"
+  #   scanner.pos #=> 5
+  #
+  # @param [Regexp] pattern the pattern to scan until
+  # @return [String] the String before `pattern`
+  def scan_until_ahead(pattern)
+    content = self.scan_until /(?=(#{pattern}))/
+    self.skip pattern
+    return content
+  end
+  
+  # will stop to scan at the specified pattern or at eos and returns the
+  # consumed string.
+  # 
+  # @param [Regexp] pattern the pattern to scan for
+  # @return [String] the String before `pattern`
+  def scan_until_or_end(pattern)
+    self.scan_until(pattern) or self.scan_until(/$/)
+  end
+  
+  # skips content within comments, strings and regularexpressions
+  def intelligent_skip_until(pattern)
+
+    self.skip_escaping_until(/#{pattern}|#{Parser::NON_CODE_PATTERNS.keys.join('|')}/)
+
+    found = self.matched
+    
+    raise end_of_string_error(pattern) if self.matched.nil?
+    
+    return if found.match pattern
+    
+    Parser::NON_CODE_PATTERNS.each do |start_pattern, end_pattern|    
+      if found.match start_pattern
+        self.skip_escaping_until end_pattern
+        return self.intelligent_skip_until pattern
+      end    
+    end
+  end
+  
+  def save_scanned
+    pos_start = self.pos #- 1 # fixes missing first char
+    yield
+    pos_end = self.pos
+    Range.new(pos_start, pos_end)
+  end
+  
+  def skip_escaping_until(pattern) 
+       
+    self.skip_until(/\\|#{pattern}/)
+    
+    raise end_of_string_error(pattern) if self.matched.nil?
+
+    if self.matched.match /\\/
+      self.getch
+      skip_escaping_until(pattern)
+    end    
+  end
+  
+  protected
+  
+  def end_of_string_error(pattern)
+    Error.new "Unexpected end of String, expected: #{pattern.inspect} in \"#{self.string}\" at pos:#{self.pos}"
+  end  
+
+end
+
+class String
+  def line_of(pos)
+    self[0..pos].count "\n"
+  end
+end

data/lib/processor.rb

@@ -0,0 +1,123 @@
+require 'rdiscount'
+require_relative 'dom/dom'
+require_relative 'tasks/render_task'
+require_relative 'document/document'
+
+module Processor
+  
+  RenderTask = Struct.new :name, :description, :block
+  @@render_tasks = {}
+    
+  # Accessor Method for RenderTasks
+  def self.render_tasks
+    @@render_tasks
+  end
+  
+  # @group Combined Stages
+  
+  def self.process_and_render
+    process_files_to_dom
+    perform_all_tasks
+  end
+  
+  def self.process_files_to_dom(files = nil)
+    process_comments parse_files(files)
+  end 
+  
+  # @group Stage #1 - FileProcessor
+  
+  # Parsing Files and creating comment stream
+  def self.parse_files(files = nil)
+    files ||= Configs.files
+        
+    return if files.nil?    
+
+    files = [files] unless files.is_a? Array
+    comments = []
+    
+    files.each do |file|  
+      Logger.info "Processing file #{file}"      
+      comments += Parser::Parser.parse_file(file)
+    end
+    
+    return comments
+  end  
+  
+  # @group Stage #2 - CommentProcessor
+  
+  # Processing comment-stream and convert to {CodeObject CodeObjects}
+  # This stage also adds the CodeObjects to Dom.
+  def self.process_comments(comments)
+    
+    comments = [comments] unless comments.is_a? Array
+    
+    comments.each do |comment|    
+      code_object = comment.to_code_object            # convert to code_object
+      Logger.debug "Adding to Dom: #{code_object}"
+      Dom.add_node(code_object.path, code_object)     # add to dom
+    end
+  end
+  
+  
+  # @group Stage #3 - TemplateProcessor  
+  
+  # just some notes
+  
+  # command line:
+  #     $~ jsdoc render_tasks
+  #     Registered Rendertasks:
+  #     - typed:     renders objects type-dependant
+  #     - overview:  renders an overview
+  #     - files:     converts specified markdown files and renders them
+  #  
+  def self.perform_all_tasks
+    perform_tasks @@render_tasks.keys
+  end
+  
+  def self.perform_tasks(tasks)
+  
+    tasks = [tasks] unless tasks.is_a? Array
+    
+    tasks.each do |task|
+      task = task.to_sym
+      raise Exception, "No render-task registered with name '#{task}'" unless @@render_tasks.has_key? task
+      
+      Logger.debug "Rendering task '#{task}'"
+      @@render_tasks[task].new.perform
+    end
+  end 
+  
+  # @group Stage #4 - Document Processor
+    
+  def self.prepare_documents
+    # underscores will be replaced with whitespaces as title
+    Configs.docs.each do |doc|
+    
+      doc_path = File.expand_path(doc, Configs.wdir)    
+      Logger.debug "Working with Document #{doc_path}"
+      
+      contents = File.read(doc_path)
+      
+      # Those documents get registered in a special {Dom::Node} Dom.docs
+      document = Document::Document.new(doc_path, contents)
+      Dom.docs.add_node(document.path, document)
+      
+      # The docs can be accessed via Dom later on
+    end
+  end
+  
+  
+  
+  # @group RenderTask-Setup
+  
+  def self.register_render_task(name, klass)
+    @@render_tasks[name.to_sym] = klass 
+  end
+
+  def self.unregister_render_task(name)
+    @@render_tasks.delete(name.to_sym)
+  end   
+  
+  
+  
+end

data/lib/renderer.rb

@@ -0,0 +1,108 @@
+# ../data.img#1783836:1
+require 'erb'
+require 'fileutils'
+
+class Renderer
+
+  def initialize(default_path, layout)
+    @_path = default_path
+    @_layout = layout
+  end
+
+  # Teilweise aus rails...
+  # @todo better error-handling with partial and layout context information!!!
+  def render(opt = nil, extra_options = {})
+
+    if opt.nil?
+      opt = { :layout => @_layout }
+
+    elsif opt.is_a?(String) || opt.is_a?(Symbol)
+      extra_options[:template] = opt
+      extra_options[:layout] ||= @_layout
+      opt = extra_options
+
+    elsif !opt.is_a?(Hash)
+      extra_options[:partial] = opt
+      opt = extra_options
+    end
+
+    if opt[:partial]
+    
+      # add underscore to last element of foo/bar/baz
+      parts = opt[:partial].split('/')
+      parts[-1] = "_"+parts.last        
+      
+      begin
+        template_file = File.read path_to_template(parts.join('/'))
+      rescue Exception
+        raise "Could not find Partial '#{opt[:partial]}'"
+      end
+      if opt[:collection]
+
+        partial_name = opt[:partial].split('/').last
+
+        opt[:collection].map { |item|
+          define_singleton_method(partial_name) { item }
+          ERB.new(template_file).result(binding)
+        }.join "\n"
+      else
+
+        # If there are locals we have to save our instance binding, otherwise we will store our
+        # newly created local-variables in the blockcontext of each_pair
+        # values has to be defined explicitly to be overridden by the block and still available inside of eval
+        if opt[:locals]
+          value = nil
+          instance_context = binding
+          opt[:locals].each_pair do |local, value|
+            Logger.warn("Please change your partial-name or local binding, because #{local} is already set in this context.") if respond_to? local
+            define_singleton_method(local) { value }
+          end
+        end
+
+        ERB.new(template_file).result(binding)
+      end
+    else
+      # bind @current_path correctly to use in helpers and views
+      if opt[:to_file]
+        # Make absolute
+        opt[:to_file] = File.expand_path(opt[:to_file], Configs.output)        
+        @current_path = File.dirname opt[:to_file]
+      else
+        @current_path ||= Configs.output
+      end
+
+      # render 'view_name', :option1 => 1, :option2 => 2
+      view = ERB.new(File.read path_to_template opt[:template]).result(binding)
+      
+      # then render with layout
+      if opt[:layout]
+        layout = File.read path_to_template opt[:layout]
+        view = render_in_layout(layout) { view }
+      end
+
+      # Render to file, if desired
+      if opt[:to_file]
+        # create directories recursive
+        FileUtils.mkpath File.dirname opt[:to_file]
+
+        File.open(opt[:to_file], "w+") do |f|
+          f.write view
+        end
+      else        
+        return view
+      end
+    end
+ 
+  end
+
+  protected
+
+  def render_in_layout(layout, &view)
+    ERB.new(layout).result(binding)
+  end
+
+  def path_to_template(file)
+    File.expand_path "#{file}.html.erb", @_path
+  end
+
+end