yard 0.8.1 → 0.8.2

data/lib/yard/docstring_parser.rb

@@ -29,25 +29,25 @@ module YARD
   class DocstringParser
     # @return [String] the parsed text portion of the docstring,
     #   with tags removed.
-    attr_reader :text
+    attr_accessor :text
 
     # @return [String] the complete input string to the parser.
-    attr_reader :raw_text
+    attr_accessor :raw_text
 
     # @return [Array<Tag>] the list of meta-data tags identified
     #   by the parser
-    attr_reader :tags
+    attr_accessor :tags
 
     # @return [Array<Directive>] a list of directives identified
     #   by the parser. This list will not be passed on to the
     #   Docstring object.
-    attr_reader :directives
+    attr_accessor :directives
 
     # @return [OpenStruct] any arbitrary state to be passed between
     #   tags during parsing. Mainly used by directives to coordinate
     #   behaviour (so that directives can be aware of other directives
     #   used in a docstring).
-    attr_reader :state
+    attr_accessor :state
 
     # @return [CodeObjects::Base, nil] the object associated with
     #   the docstring being parsed. May be nil if the docstring is
@@ -177,7 +177,7 @@ module YARD
 
     # Creates a tag from the {Tags::DefaultFactory tag factory}.
     #
-    # To add an already created tag object, use {#add_tag}
+    # To add an already created tag object, append it to {#tags}.
     #
     # @param [String] tag_name the tag name
     # @param [String] tag_buf the text attached to the tag with newlines removed.
@@ -264,7 +264,7 @@ module YARD
       self.after_parse_callbacks << block
     end
 
-    # @return [Array<Proc>] the {#after_parse} callback proc objects
+    # @return [Array<Proc>] the {after_parse} callback proc objects
     def self.after_parse_callbacks
       @after_parse_callbacks ||= []
     end

data/lib/yard/globals.rb

@@ -4,9 +4,9 @@
 #
 # @see YARD::CodeObjects::Proxy
 # @see YARD::Registry.resolve
-def P(namespace, name = nil)
+def P(namespace, name = nil, type = nil)
   namespace, name = nil, namespace if name.nil?
-  YARD::Registry.resolve(namespace, name, false, true)
+  YARD::Registry.resolve(namespace, name, false, true, type)
 end
 
 # The global {YARD::Logger} instance

data/lib/yard/handlers/base.rb

@@ -356,12 +356,13 @@ module YARD
         opts = {
           :namespace => namespace,
           :scope => :instance,
-          :owner => owner || namespace
+          :owner => owner || namespace,
+          :visibility => nil
         }.update(opts)
 
         ns, vis, sc, oo = namespace, visibility, scope, owner
         self.namespace = opts[:namespace]
-        self.visibility = :public
+        self.visibility = opts[:visibility] || :public
         self.scope = opts[:scope]
         self.owner = opts[:owner]
 

data/lib/yard/handlers/c/handler_methods.rb

@@ -61,6 +61,7 @@ module YARD
 
         def handle_alias(var_name, new_name, old_name)
           namespace = namespace_for_variable(var_name)
+          return if namespace.nil?
           new_meth, old_meth = new_name.to_sym, old_name.to_sym
           old_obj = namespace.child(:name => old_meth, :scope => :instance)
           new_obj = register MethodObject.new(namespace, new_meth, :instance) do |o|

data/lib/yard/handlers/c/init_handler.rb

@@ -1,15 +1,17 @@
 # Handles the Init_Libname() method
 class YARD::Handlers::C::InitHandler < YARD::Handlers::C::Base
-  MATCH = %r{\A\s*(?:static\s+)?void\s+[Ii]nit_(\w+)\s*}
+  MATCH = %r{\A\s*(?:static\s+)?void\s+(?:[Ii]nit_)?(\w+)\s*}
   handles MATCH
   statement_class ToplevelStatement
 
   process do
     parse_block
-    ns = namespace_for_variable(statement.declaration[MATCH, 1])
-    if ns.is_a?(YARD::CodeObjects::NamespaceObject) && ns.docstring.blank?
-      if statement.comments
-        register_docstring(ns, statement.comments.source, statement)
+    if decl = statement.declaration[MATCH, 1]
+      ns = namespace_for_variable(decl)
+      if ns.is_a?(YARD::CodeObjects::NamespaceObject) && ns.docstring.blank?
+        if statement.comments
+          register_docstring(ns, statement.comments.source, statement)
+        end
       end
     end
   end

data/lib/yard/handlers/c/override_comment_handler.rb

@@ -16,7 +16,15 @@ class YARD::Handlers::C::OverrideCommentHandler < YARD::Handlers::C::Base
       when :module
         obj = YARD::CodeObjects::ModuleObject.new(:root, name)
       end
-      register_docstring(obj, statement.source, statement) if obj
+      register(obj)
     end
   end
+
+  def register_docstring(object, docstring = statement.source, stmt = statement)
+    super
+  end
+
+  def register_file_info(object, file = parser.file, line = statement.line, comments = statement.comments)
+    super
+  end
 end

data/lib/yard/handlers/ruby/class_condition_handler.rb

@@ -75,10 +75,12 @@ class YARD::Handlers::Ruby::ClassConditionHandler < YARD::Handlers::Ruby::Base
   end
 
   def parse_then_block
-    parse_block(statement.then_block)
+    parse_block(statement.then_block, :visibility => visibility)
   end
 
   def parse_else_block
-    parse_block(statement.else_block) if statement.else_block
+    if statement.else_block
+      parse_block(statement.else_block, :visibility => visibility)
+    end
   end
 end

data/lib/yard/handlers/ruby/legacy/class_condition_handler.rb

@@ -65,7 +65,7 @@ class YARD::Handlers::Ruby::Legacy::ClassConditionHandler < YARD::Handlers::Ruby
 
   # @since 0.5.5
   def parse_then_block
-    parse_block
+    parse_block(:visibility => visibility)
   end
 
   # @since 0.5.5
@@ -74,7 +74,9 @@ class YARD::Handlers::Ruby::Legacy::ClassConditionHandler < YARD::Handlers::Ruby
     stmtlist = YARD::Parser::Ruby::Legacy::StatementList
     stmtlist.new(statement.block).each do |stmt|
       if TkELSE === stmt.tokens.first
-        parser.process(stmtlist.new(stmt.block))
+        push_state(:visibility => visibility) do
+          parser.process(stmtlist.new(stmt.block))
+        end
       end
     end
   end

data/lib/yard/handlers/ruby/legacy/mixin_handler.rb

@@ -27,13 +27,11 @@ class YARD::Handlers::Ruby::Legacy::MixinHandler < YARD::Handlers::Ruby::Legacy:
       raise YARD::Parser::UndocumentableError
     end
 
-    obj = Proxy.new(namespace, mixmatch)
-
-    case obj
-    when Proxy
-      obj.type = :module
+    case obj = Proxy.new(namespace, mixmatch)
     when ConstantObject # If a constant is included, use its value as the real object
-      obj = Proxy.new(namespace, obj.value)
+      obj = Proxy.new(namespace, obj.value, :module)
+    else
+      obj = Proxy.new(namespace, mixmatch, :module)
     end
 
     namespace.mixins(scope).unshift(obj) unless namespace.mixins(scope).include?(obj)

data/lib/yard/handlers/ruby/mixin_handler.rb

@@ -25,10 +25,10 @@ class YARD::Handlers::Ruby::MixinHandler < YARD::Handlers::Ruby::Base
     raise YARD::Parser::UndocumentableError if mixin.first.type == :ident
 
     case obj = Proxy.new(namespace, mixin.source)
-    when Proxy
-      obj.type = :module
     when ConstantObject # If a constant is included, use its value as the real object
-      obj = Proxy.new(namespace, obj.value)
+      obj = Proxy.new(namespace, obj.value, :module)
+    else
+      obj = Proxy.new(namespace, mixin.source, :module)
     end
 
     namespace.mixins(scope).unshift(obj) unless namespace.mixins(scope).include?(obj)

data/lib/yard/handlers/ruby/visibility_handler.rb

@@ -9,7 +9,7 @@ class YARD::Handlers::Ruby::VisibilityHandler < YARD::Handlers::Ruby::Base
     return if (ident = statement.jump(:ident)) == statement
     case statement.type
     when :var_ref, :vcall
-      self.visibility = ident.first
+      self.visibility = ident.first.to_sym
     when :fcall, :command
       statement[1].traverse do |node|
         case node.type

data/lib/yard/i18n/locale.rb

@@ -0,0 +1,50 @@
+require "gettext/tools/poparser"
+require "gettext/runtime/mofile"
+
+module YARD
+  module I18n
+    # +Locale+ is a unit of translation. It has {#name} and a set of
+    # messages.
+    #
+    # @since 0.8.2
+    class Locale
+      # @return [String] the name of the locale. It used IETF language
+      #   tag format +[language[_territory][.codeset][@modifier]]+.
+      # @see http://tools.ietf.org/rfc/bcp/bcp47.txt
+      #   BCP 47 - Tags for Identifying Languages
+      attr_reader :name
+
+      # Creates a locale for +name+ locale.
+      #
+      # @param [String] name the locale name.
+      def initialize(name)
+        @name = name
+        @messages = {}
+      end
+
+      # Loads translation messages from +locale_directory+/{#name}.po.
+      #
+      # @param [String] locale_directory the directory path that has
+      #   {#name}.po.
+      # @return [Boolean] +true+ if PO file exists, +false+ otherwise.
+      def load(locale_directory)
+        po_file = File.join(locale_directory, "#{@name}.po")
+        return false unless File.exist?(po_file)
+
+        parser = GetText::PoParser.new
+        parser.report_warning = false
+        data = GetText::MoFile.new
+        parser.parse_file(po_file, data)
+        @messages.merge!(data)
+        true
+      end
+
+      # @param [String] message the translation target message.
+      # @return [String] translated message. If tarnslation isn't
+      #   registered, the +message+ is returned.
+      def translate(message)
+        @messages[message] || message
+      end
+    end
+  end
+end

data/lib/yard/i18n/text.rb

@@ -32,6 +32,48 @@ module YARD
       #   extracted paragraph.
       # @return [void]
       def extract_messages
+        parse do |part|
+          line_no = part[:line_no]
+          case part[:type]
+          when :markup, :empty_line
+            # ignore
+          when :attribute
+            yield(:attribute, part[:name], part[:value], part[:line_no])
+          when :paragraph
+            yield(:paragraph, part[:paragraph], part[:line_no])
+          end
+        end
+      end
+
+      # Translates into +locale+.
+      #
+      # @param [Locale] locale the translation target locale.
+      # @return [String] translated text.
+      def translate(locale)
+        translated_text = ""
+        parse do |part|
+          case part[:type]
+          when :markup
+            translated_text << part[:line]
+          when :attribute
+            prefix = "#{part[:prefix]}#{part[:name]}#{part[:infix]}"
+            value = locale.translate(part[:value])
+            suffix = part[:suffix]
+            translated_text << "#{prefix}#{value}#{suffix}"
+          when :paragraph
+            translated_text << locale.translate(part[:paragraph])
+          when :empty_line
+            translated_text << part[:line]
+          else
+            raise "should not reach here: unexpected type: #{type}"
+          end
+        end
+        translated_text
+      end
+
+      private
+
+      def parse(&block)
         paragraph = ""
         paragraph_start_line = 0
         line_no = 0
@@ -42,29 +84,88 @@ module YARD
           if in_header
             case line
             when /^#!\S+\s*$/
-              in_header = false unless line_no == 1
-            when /^\s*#\s*@(\S+)\s*(.+?)\s*$/
-              name, value = $1, $2
-              yield(:attribute, name, value, line_no)
+              if line_no == 1
+                emit_markup_event(line, line_no, &block)
+              else
+                in_header = false
+              end
+            when /^(\s*#\s*@)(\S+)(\s*)(.+?)(\s*)$/
+              emit_attribute_event(Regexp.last_match, line_no, &block)
             else
               in_header = false
-              next if line.chomp.empty?
+              if line.strip.empty?
+                emit_empty_line_event(line, line_no, &block)
+                next
+              end
             end
             next if in_header
           end
 
           case line
           when /^\s*$/
-            next if paragraph.empty?
-            yield(:paragraph, paragraph.rstrip, paragraph_start_line)
-            paragraph = ""
+            if paragraph.empty?
+              emit_empty_line_event(line, line_no, &block)
+            else
+              paragraph << line
+              emit_paragraph_event(paragraph, paragraph_start_line, line_no,
+                                   &block)
+              paragraph = ""
+            end
           else
             paragraph_start_line = line_no if paragraph.empty?
             paragraph << line
           end
         end
+
         unless paragraph.empty?
-          yield(:paragraph, paragraph.rstrip, paragraph_start_line)
+          emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
+        end
+      end
+
+      def emit_markup_event(line, line_no)
+        part = {
+          :type => :markup,
+          :line => line,
+          :line_no => line_no,
+        }
+        yield(part)
+      end
+
+      def emit_attribute_event(match_data, line_no)
+        part = {
+          :type => :attribute,
+          :prefix => match_data[1],
+          :name => match_data[2],
+          :infix => match_data[3],
+          :value => match_data[4],
+          :suffix => match_data[5],
+          :line_no => line_no,
+        }
+        yield(part)
+      end
+
+      def emit_empty_line_event(line, line_no)
+        part = {
+          :type => :empty_line,
+          :line => line,
+          :line_no => line_no,
+        }
+        yield(part)
+      end
+
+      def emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
+        paragraph_part = {
+          :type => :paragraph,
+          :line_no => paragraph_start_line,
+        }
+        match_data = /(\s*)\z/.match(paragraph)
+        if match_data
+          paragraph_part[:paragraph] = match_data.pre_match
+          yield(paragraph_part)
+          emit_empty_line_event(match_data[1], line_no, &block)
+        else
+          paragraph_part[:paragraph] = paragraph
+          yield(paragraph_part)
         end
       end
     end

data/lib/yard/logging.rb

@@ -1,24 +1,50 @@
 require 'logger'
+require 'thread'
 
 module YARD
   # Handles console logging for info, warnings and errors.
   # Uses the stdlib Logger class in Ruby for all the backend logic.
   class Logger < ::Logger
-    attr_writer :show_backtraces
+    # The list of characters displayed beside the progress bar to indicate
+    # "movement".
+    # @since 0.8.2
+    PROGRESS_INDICATORS = ["\u230C", "\u230D", "\u230E", "\u230F"]
+
+    # @return [IO] the IO object being logged to
+    # @since 0.8.2
+    attr_accessor :io
+
+    # @return [Boolean] whether backtraces should be shown (by default
+    #   this is on).
     def show_backtraces; @show_backtraces || level == DEBUG end
+    attr_writer :show_backtraces
+
+    # @return [Boolean] whether progress indicators should be shown when
+    #   logging CLIs (by default this is off).
+    def show_progress
+      return false if RUBY18 # threading is too ineffective for progress support
+      return false unless io.tty? # no TTY support on IO
+      return false if level > WARN # no progress in verbose/debug modes
+      @show_progress
+    end
+    attr_writer :show_progress
 
     # The logger instance
     # @return [Logger] the logger instance
-    def self.instance(pipe = STDERR)
+    def self.instance(pipe = STDOUT)
       @logger ||= new(pipe)
     end
 
     # Creates a new logger
-    def initialize(*args)
-      super
+    def initialize(pipe, *args)
+      super(pipe, *args)
+      self.io = pipe
       self.show_backtraces = true
+      self.show_progress = false
       self.level = WARN
       self.formatter = method(:format_log)
+      @progress_indicator = 0
+      @mutex = Mutex.new
     end
 
     # Changes the debug level to DEBUG if $DEBUG is set
@@ -28,15 +54,80 @@ module YARD
       super
     end
 
+    # Captures the duration of a block of code for benchmark analysis. Also
+    # calls {#progress} on the message to display it to the user.
+    #
+    # @todo Implement capture storage for reporting of benchmarks
+    # @param [String] msg the message to display
+    # @param [Symbol, nil] nontty_log the level to log as if the output
+    #   stream is not a TTY. Use +nil+ for no alternate logging.
+    # @yield a block of arbitrary code to benchmark
+    # @return [void]
+    def capture(msg, nontty_log = :debug, &block)
+      progress(msg, nontty_log)
+      yield
+    ensure
+      clear_progress
+    end
+
+    # Displays a progress indicator for a given message. This progress report
+    # is only displayed on TTY displays, otherwise the message is passed to
+    # the +nontty_log+ level.
+    #
+    # @param [String] msg the message to log
+    # @param [Symbol, nil] nontty_log the level to log as if the output
+    #   stream is not a TTY. Use +nil+ for no alternate logging.
+    # @return [void]
+    # @since 0.8.2
+    def progress(msg, nontty_log = :debug)
+      send(nontty_log, msg) if nontty_log
+      return unless show_progress
+      icon = ""
+      if defined?(::Encoding)
+        icon = PROGRESS_INDICATORS[@progress_indicator] + " "
+      end
+      self << "\e[2K\e[?25l\e[1m#{icon}#{msg}\e[0m\r"
+      @mutex.synchronize do
+        @progress_msg = msg
+        @progress_indicator += 1
+        @progress_indicator %= PROGRESS_INDICATORS.size
+      end
+      Thread.new do
+        sleep(0.05)
+        @mutex.synchronize do
+          progress(msg + ".", nil) if @progress_msg == msg
+        end
+      end
+    end
+
+    # Clears the progress indicator in the TTY display.
+    # @return [void]
+    # @since 0.8.2
+    def clear_progress
+      return unless show_progress
+      self << "\e[?25h\e[2K"
+      @progress_msg = nil
+    end
+
+    # Displays an unformatted line to the logger output stream. Similar to
+    # the +#<<+ method, but adds a newline.
+    # @param [String] msg the message to display
+    # @return [void]
+    # @since 0.8.2
+    def puts(msg)
+      self << "#{msg}\n"
+    end
+
     # Prints the backtrace +exc+ to the logger as error data.
     #
     # @param [Array<String>] exc the backtrace list
+    # @param [Symbol] level_meth the level to log backtrace at
     # @return [void]
-    def backtrace(exc)
+    def backtrace(exc, level_meth = :error)
       return unless show_backtraces
-      error "#{exc.class.class_name}: #{exc.message}"
-      error "Stack trace:" +
-        exc.backtrace[0..5].map {|x| "\n\t#{x}" }.join + "\n"
+      send(level_meth, "#{exc.class.class_name}: #{exc.message}")
+      send(level_meth, "Stack trace:" +
+        exc.backtrace[0..5].map {|x| "\n\t#{x}" }.join + "\n")
     end
 
     # Warns that the Ruby environment does not support continuations. Applies