docjs 0.1

data/lib/helper/helper.rb

@@ -0,0 +1,120 @@
+# ../data.img#1800236:1
+require 'pathname'
+require 'rdiscount'
+
+require_relative 'linker'
+
+# The Helpers are 'mixed' into your {Tasks::RenderTask} and therefore can be used in all 
+# template-views.
+# If you are searching for a method and don't know, where it may be implemented i suggest the 
+# following inheritence chain as your search-strategy:
+#
+#     Helper::IncludedHelpers → Tasks::YourTask → Tasks::RenderTask → Renderer
+#
+# Somewhere at that chain you will find your desired function.
+module Helper
+
+  # The Helper-methods in this module are globally used one and should not depend on the template
+  # you are using. You will find many html-helpers around here.
+  module Helper
+ 
+    include Linker
+    
+    def tag(sym, content = "", attrs = {})
+   
+      # @todo FIXME
+      if block_given?
+        _erbout << "<#{sym.to_s} #{attributize(content)}>"        
+        content = yield
+        _erbout << "</#{sym.to_s}>"
+      else
+        "<#{sym.to_s} #{attributize(attrs)}>#{content}</#{sym.to_s}>"        
+      end     
+    end    
+    
+    def truncate(string, num = 150)
+      if string.length > num
+        string[0..num] + " &hellip;"
+      else
+        string
+      end
+    end
+    
+    def style(*args)
+      html = ""
+      args.each do |path|
+        html += tag :link, "", :rel => 'stylesheet', :href => to_relative('css/'+path+'.css')
+      end
+      return html
+    end
+    
+    def script(*args)
+      html = ""
+      args.each do |path|
+        html += tag :script, "", :src => to_relative('js/'+path+'.js')
+      end
+      return html
+    end
+    
+    def code(source)    
+      # find minimal intendation
+      intendation = source.lines.map {|line| line.match(/(^\s+)/) && line.match(/(^\s+)/).captures.first.size || 0 }.min
+      
+      # @todo there has to be a better way for that      
+      tag :code, source.lines.map { |line| line[intendation .. line.size] }.join(""), :class => 'block'
+    end
+    
+    def to_html(markdown_text, *markdown_opts)
+      replace_links RDiscount.new(markdown_text, *markdown_opts).to_html
+    end
+    
+    def toc(markdown_text)
+      RDiscount.new(markdown_text, :generate_toc).toc_content
+    end
+    
+    def to_relative(path)
+    
+      path = Pathname.new(path)
+      base = Pathname.new(@current_path)
+      
+      # for example /home/jsdoc/css/style.css
+      # current: /home/jsdoc/output/Foo/Bar.html
+      if not path.absolute?
+        # resolve to Configs.output
+        path = Pathname.new(Configs.output) + path
+      end     
+      
+      Logger.debug "Relative path '#{path}' from '#{base}'"
+      path.relative_path_from(base).to_s
+    end
+    
+    def render_tokens(opts = {})
+    
+      code_object = opts[:of] or raise Exception.new("Parameter :of (CodeObject) required")
+      area        = opts[:in] or raise Exception.new("Parameter :in (Area) required")
+    
+      rendered = ""
+    
+      token_groups = code_object.tokens.values.each do |tokens|        
+           
+        # tokens is an array of Token::Token
+        if not tokens.empty? and tokens.first.area == area
+        
+          template = tokens.first.template.to_s
+          
+          # overwriting default template with specified option[:template] if existant
+          template = opts[:template].to_s if opts[:template] and template == 'default'
+        
+          rendered += render :partial => "tokens/#{template}", :locals => { :tokens => tokens }
+        end
+      end            
+      
+      rendered
+    end
+    
+    def attributize(hash)
+      hash.map{|k,v| "#{k}=\"#{v}\""}.join ' '
+    end
+    
+  end
+end

data/lib/helper/linker.rb

@@ -0,0 +1,130 @@
+module Helper
+
+  # This Helper contains all needed functionality to link to an object, on-page-element or some
+  # other urls
+  module Linker
+  
+    FILE = /^file\:(\S+)/
+    EXTERNAL = /^((?:http|ftp|https|ssh):\/\/\S+)/
+    MAIL = /^(mailto\:\S+)/
+    HASH = /^#\S*/
+    DOCUMENTATION = /^doc\:([^\s#]+)(#\S+)?/
+
+    # @note link_to - first argument can be
+    #   "file:some/path/to_a.file"
+    #   "Code.object.path"
+    #   ".relative.code_object.path"
+    #   "http://external.address.com"
+    #   instance_of_code_object
+    #
+    def link_to(target, text = nil, args = {})
+           
+      Logger.debug "Trying to link #{target}"
+      
+      link = if target.is_a? Document::Document
+        
+        text = target.name if text.nil?     
+        to_relative path_to target        
+      
+      elsif target.is_a? CodeObject::Base
+      
+        if text.nil? and target.parent == context and context != Dom.root
+          text = ".#{target.name}"
+          text += "()" if target.is_a? CodeObject::Function
+        elsif text.nil?
+          text = target.qualified_name
+        end
+      
+        to_relative path_to target
+        
+      elsif target.match EXTERNAL or target.match MAIL or target.match HASH
+        target
+        
+      elsif target.match FILE
+        to_relative target.match(FILE).captures.first
+        
+      elsif target.match DOCUMENTATION
+        Logger.debug target + " matched DOCUMENTATION"
+      
+        doc_name, hash = target.match(DOCUMENTATION).captures
+        obj = Dom.docs.find doc_name        
+        text ||= obj.name
+
+        # find relative path to our object and reattach hash to path
+        to_relative(path_to obj) + (hash || "") unless obj.nil?        
+        
+      else        
+        # use context dependent resolving functionality as specified in {Tasks::RenderTask}
+        obj = resolve target
+        to_relative path_to obj unless obj.nil?  
+      end
+        
+      text ||= target 
+      
+      if link.nil?
+        Logger.warn "Could not resolve link to '#{target}'"
+        return text 
+      end
+     
+      tag :a, text, :href => link      
+    end
+    
+    def relative_link(path, text)
+      tag :a, text, :href => to_relative(path)
+    end
+    
+    # Returns the relative path (from dom) to this node
+    # The Node can be either a {CodeObject::Base CodeObject} or a {Document::Document Document}.
+    # 
+    # @param [CodeObject::Base, Document::Document] object
+    #
+    # @example 
+    #   Dom[:Foo][:bar].file_path #=> Foo/bar
+    #   
+    def path_to(object, args = {})
+
+      return "" if object.nil? 
+      format = args[:format] || :html      
+      path = object.parents.push(object).map{|p| p.name}.join('/') + ".#{format.to_s}"
+    
+      # object can be either a CodeObject or a Document
+      # maybe source this one out later on in Configs.some_path
+      if object.is_a? CodeObject::Base
+        "api/" + path
+      elsif object.is_a? Document::Document
+        "docs/" + path
+      else
+        Logger.warn "Could not resolve link to '#{object}'"
+        object.to_s
+      end   
+    end
+
+    # (see https://github.com/lsegal/yard/blob/master/lib/yard/templates/helpers/html_helper.rb)
+    def replace_links(text)
+      code_tags = 0
+      text.gsub(/<(\/)?(pre|code|tt)|(\\)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W<]|.+<\/|$)/m) do |str|
+        closed, tag, escape, name, title, match = $1, $2, $3, $4, $5, $&
+        if tag
+          code_tags += (closed ? -1 : 1)
+          next str
+        end
+        next str unless code_tags == 0
+
+        next(match[1..-1]) if escape
+
+        next(match) if name[0,1] == '|'
+        
+        link_to(name, title)
+      end
+    end
+    
+    def link_on_page(object)
+      if object.is_a? CodeObject::Function
+         link_to "#method-#{object.name}", ".#{object.name}()"
+      else
+        link_to "#object-#{object.name}", ".#{object.name}"
+      end
+    end
+  end
+  
+end

data/lib/logger.rb

@@ -0,0 +1,49 @@
+require 'thor/base'
+
+# The logger is using colorizing-functionality from Thor's shell
+module Logger
+  
+  LogLevel = Struct.new :numeric, :prefix, :color
+  
+  LEVEL = {
+    :debug  => LogLevel.new(0,  "DEBUG ", :white),
+    :info   => LogLevel.new(1,  "INFO  ", :blue),
+    :warn   => LogLevel.new(2,  "WARN  ", :yellow),
+    :error  => LogLevel.new(3,  "ERROR ", :red),
+    :system => LogLevel.new(10, "",       :black)
+  }
+   
+  def self.setup(args = {})
+
+    @@shell = Thor::Base.shell.new
+    @@logfile = args[:file] 
+    @@level   = LEVEL[args[:level] || :info]
+    
+    # write start sequence
+    log LEVEL[:info], ["\n\n== #{Time.now} #{'='*50}"]
+  end
+
+  def self.method_missing(name, *args)
+    level = LEVEL[name.to_sym]    
+    raise NoMethodError.new(name.to_s) if level.nil?
+    
+    log(level, args)
+  end
+  
+  protected
+  
+  def self.log(level, msg)
+    return if level.numeric < @@level.numeric
+    
+    msg = msg.join "\n"
+    
+    unless @@logfile.nil?      
+      File.open(@@logfile, "a") do |f|
+        f.write "#{level.prefix} #{msg}\n"
+      end
+    end
+    
+    @@shell.say @@shell.set_color(level.prefix, level.color, true) +  msg
+  end
+
+end

data/lib/parser/comment.rb

@@ -0,0 +1,69 @@
+# ../data.img#1781829:1
+require_relative 'meta_container'
+require_relative '../code_object/converter'
+
+module Parser
+
+  # Together with {Parser::Coment} it acts as an **Interface** between {Parser} 
+  # and {CodeObject}. Parser::Comment creates instances of Tokenline, which are
+  # then analysed by {Token::Container#process_token} 
+  #
+  # @see Parser::Comment
+  # @see Parser::CommentParser
+  Tokenline = Struct.new :token, :content
+  
+  # Comment contains all **tokenlines** and **doclines**, which are created by the
+  # {Parser::Parser parser}. The tokenlines are stored as {Tokenline}. Because
+  # of this Comment and Tokenline act as **Interface** for {CodeObject::Base}.
+  #
+  # The tokens will further be processed by {Token::Container}, which 
+  # is mixed in to CodeObject::Base).
+  #
+  # @example creating of an comment
+  #   c = Parser::Comment.new "the original string of the comment, with all tokens and doclines"
+  #   c.add_tokenline :param "[String] first_parameter this is the description for param1"
+  #   c.add_docline "Some documentation of the comment"
+  #
+  # @example access of comment-data
+  #   c.tokenlines.first.token #=> :param
+  #   c.tokenlines.first.content #=> "[String] first_parameter this is the description for param1"
+  #   c.doclines #=> ["Some documentation of the comment"]
+  class Comment   
+    
+    include MetaContainer
+    include CodeObject::Converter
+    
+    attr_reader :tokenlines, :doclines, :children
+    
+    def initialize(comment_text = "")
+      @original_comment = comment_text
+      
+      @tokenlines, @doclines, @children = [], [], []
+    end
+    
+    # @param [String, Symbol] tokenname
+    # @param [String] content
+    def add_tokenline(tokenname, content = "")
+      @tokenlines << Tokenline.new(tokenname.to_sym, content)
+    end
+    
+    # @param [String] docline
+    def add_docline(docline)
+      @doclines << docline
+    end
+    
+    # @param [Array<Comment>] comments
+    def add_children(comments)
+      @children += comments
+    end
+    
+    def has_tokens?
+      not @tokenlines.empty?
+    end    
+    
+    def to_s
+      "#<Parser::Comment tokenlines=#{@tokenlines.length} doclines=#{@doclines.length}>"
+    end
+    
+  end
+end

data/lib/parser/comment_parser.rb

@@ -0,0 +1,90 @@
+# ../data.img#1799299:1
+require_relative 'comment'
+require_relative 'exceptions'
+
+module Parser
+  class CommentParser < StringScanner    
+
+    def initialize(input)
+      super(input)
+      @comment = Comment.new(input)
+    end
+
+    # All lines, that start with a `@-symbol` will be processed as tokenline
+    # if the next line after a token starts with two spaces, it will be 
+    # interpreted as continuation of the preceding token.
+    #
+    # @example multiline token
+    #   @multiline_token this is a multi_line token, it won't
+    #     stop if i intend the next line with two spaces, like "  "
+    #
+    # All other lines are interpreted as doclines
+    #
+    # @return [Parser::Comment] Creates an instance of {Parser::Comment} and
+    #   attaches all find doc- and tokenlines to it.
+    def parse
+      # we don't want the linebreak of the comment start in our first docline
+      # i.e. ignore '/**\n' 
+      self.skip LINE_END
+      
+      while not eos? do
+        parse_comment_line
+      end
+      return @comment
+    end
+    
+    protected
+    
+    # skips leading spaces with asterisk aka {Parser::LINE_START LINE_START}
+    # then checks for {Parser::TOKENLINE_START @-symbol} to parse a token
+    def parse_comment_line
+      self.skip LINE_START
+      
+      if self.check TOKENLINE_START
+        tokenline = parse_token        
+        matches = tokenline.match(TOKENLINE)
+        
+        raise NotValidTokenline.new("Not valid:'#{tokenline}'") if matches.nil?
+        
+        name, content = matches.captures
+        @comment.add_tokenline(name, content)
+      else
+        @comment.add_docline parse_doc
+      end
+    end
+    
+    # Parses tokens, if the line begins with an @
+    #     @token_one some other text etc.
+    #
+    # The parser does the following to detect multiline tokens like:
+    #     @token_two some text, and some more
+    #       and even some more.
+    #
+    #   1. Scan til the first linebreak (or end of string, if it reaches it first)
+    #   2. Check if next line starts with two spaces, skip them
+    #   3. Parse recursivly til the next line does not start with two spaces
+    #
+    # @see StringScanner.scan_until_ahead to see another example
+    #   of the positive lookahead
+    def parse_token
+    
+      # scan until the first linebreak, but don't include it in the `content`
+      # content = self.scan_until_or_end(/(?=(#{LINE_END}))/)
+      # so just skip it
+      # self.skip LINE_END
+      content = self.scan_until_or_end LINE_END
+      
+      # skip the first two spaces and parse line recursivly
+      unless self.skip(/#{LINE_START}#{NO_BR}{2}/).nil?
+        content + parse_token
+      else
+        content
+      end
+    end
+    
+    def parse_doc
+      self.scan_until_or_end(LINE_END)
+    end
+    
+  end
+end