deg-yard 0.8.7.1

data/lib/yard/logging.rb

@@ -0,0 +1,190 @@
+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
+    # 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
+    def io; @logdev end
+    def io=(pipe) @logdev = pipe end
+
+    # @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 YARD.ruby18? # threading is too ineffective for progress support
+      return false if YARD.windows? # windows has poor ANSI 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 = STDOUT)
+      @logger ||= new(pipe)
+    end
+
+    # Creates a new logger
+    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
+    # and writes a debugging message.
+    def debug(*args)
+      self.level = DEBUG if $DEBUG
+      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
+      print("\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
+      print_no_newline("\e[?25h\e[2K")
+      @progress_msg = nil
+    end
+
+    # Displays an unformatted line to the logger output stream, adding
+    # a newline.
+    # @param [String] msg the message to display
+    # @return [void]
+    # @since 0.8.2
+    def puts(msg = '')
+      print("#{msg}\n")
+    end
+
+    alias_method :print_no_newline, :<<
+    private :print_no_newline
+
+    # Displays an unformatted line to the logger output stream.
+    # @param [String] msg the message to display
+    # @return [void]
+    # @since 0.8.2
+    def print(msg = '')
+      clear_line
+      print_no_newline(msg)
+    end
+    alias_method :<<, :print
+
+    # 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, level_meth = :error)
+      return unless show_backtraces
+      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
+    # to JRuby, Rubinius and MacRuby. This warning will only display once
+    # per Ruby process.
+    #
+    # @deprecated Continuations are no longer needed by YARD 0.8.0+.
+    # @return [void]
+    def warn_no_continuations
+    end
+
+    # Sets the logger level for the duration of the block
+    #
+    # @example
+    #   log.enter_level(Logger::ERROR) do
+    #     YARD.parse_string "def x; end"
+    #   end
+    # @param [Fixnum] new_level the logger level for the duration of the block.
+    #   values can be found in Ruby's Logger class.
+    # @yield the block with the logger temporarily set to +new_level+
+    def enter_level(new_level = level, &block)
+      old_level, self.level = level, new_level
+      yield
+      self.level = old_level
+    end
+
+    private
+
+    # Override this internal Logger method to clear line
+    def add(*args)
+      clear_line
+      super(*args)
+    end
+
+    def clear_line
+      return unless @progress_msg
+      print_no_newline("\e[2K\r")
+    end
+
+    # Log format (from Logger implementation). Used by Logger internally
+    def format_log(sev, time, prog, msg)
+      "[#{sev.downcase}]: #{msg}\n"
+    end
+  end
+end

data/lib/yard/options.rb

@@ -0,0 +1,216 @@
+module YARD
+  # Generalized options class for passing around large amounts of options between objects.
+  #
+  # The options class exists for better visibility and documentability of options being
+  # passed through to other objects. Because YARD has parser and template architectures
+  # that are heavily reliant on options, it is necessary to make these option keys easily
+  # visible and understood by developers. Since the options class is more than just a
+  # basic Hash, the subclass can provide aliasing and convenience methods to simplify
+  # option property access, and, if needed, support backward-compatibility for deprecated
+  # key names.
+  #
+  # == Hash and OpenStruct-like Access
+  #
+  # Although the options class allows for Hash-like access (<tt>opts[:key]</tt>), the recommended
+  # mechanism for accessing an option key will be via standard method calls on attributes
+  #
+  # The options class can also act as an open ended key value storage structure (like a
+  # Hash or OpenStruct), and allows for setting and getting of unregistered option keys.
+  # This methodology is not recommended, however, and is only supported for backward
+  # compatibility inside YARD. Whenever possible, developers should define all keys used
+  # by an options class.
+  #
+  # == Declaring Default Values
+  #
+  # Note that the options class can contain default value definitions for certain options,
+  # but to initialize these defaults, {#reset_defaults} must be called manually after
+  # initialization; the options object is always created empty until defaults are applied.
+  #
+  # @abstract Subclasses should define (and document) custom attributes that are expected
+  #   to be made available as option keys.
+  # @example Defining an Options class with custom option keys
+  #   class TemplateOptions < YARD::Options
+  #     # @return [Symbol] the output format to generate templates in
+  #     attr_accessor :format
+  #
+  #     # @return [Symbol] the template to use when generating output
+  #     attr_accessor :template
+  #   end
+  # @example Initializing default option values
+  #   class TemplateOptions < YARD::Options
+  #     def reset_defaults
+  #       super
+  #       self.format = :html
+  #       self.template = :default
+  #       self.highlight = true
+  #       # ...
+  #     end
+  #   end
+  # @example Using +default_attr+ to create default attributes
+  #   class TemplateOptions < YARD::Options
+  #     default_attr :format, :html
+  #     default_attr :template, :default
+  #     default_attr :highlight, true
+  #   end
+  # @example Deprecating an option while still supporting it
+  #   class TemplateOptions < YARD::Options
+  #     # @return [Boolean] if syntax highlighting should be performed on code blocks.
+  #     #   Defaults to true.
+  #     attr_accessor :highlight
+  #
+  #     # @deprecated Use {#highlight} instead.
+  #     # @return [Boolean] if no syntax highlighting should be performs on code blocks.
+  #     #   Defaults to false.
+  #     attr_accessor :no_highlight
+  #     def no_highlight=(value) @highlight = !value end
+  #     def no_highlight; !highlight end
+  #   end
+  class Options
+    # @!macro [attach] yard.default_attr
+    #   @!attribute $1
+    # Defines an attribute named +key+ and sets a default value for it
+    #
+    # @example Defining a default option key
+    #   default_attr :name, 'Default Name'
+    #   default_attr :time, lambda { Time.now }
+    # @param [Symbol] key the option key name
+    # @param [Object, Proc] default the default object value. If the default
+    #   value is a proc, it is executed upon initialization.
+    def self.default_attr(key, default)
+      (@defaults ||= {})[key] = default
+      attr_accessor(key)
+    end
+
+    # Delegates calls with Hash syntax to actual method with key name
+    #
+    # @example Calling on an option key with Hash syntax
+    #   options[:format] # equivalent to: options.format
+    # @param [Symbol, String] key the option name to access
+    # @return the value of the option named +key+
+    def [](key) send(key) end
+
+    # Delegates setter calls with Hash syntax to the attribute setter with the key name
+    #
+    # @example Setting an option with Hash syntax
+    #   options[:format] = :html # equivalent to: options.format = :html
+    # @param [Symbol, String] key the optin to set
+    # @param [Object] value the value to set for the option
+    # @return [Object] the value being set
+    def []=(key, value) send("#{key}=", value) end
+
+    # Updates values from an options hash or options object on this object.
+    # All keys passed should be key names defined by attributes on the class.
+    #
+    # @example Updating a set of options on an Options object
+    #   opts.update(:template => :guide, :type => :fulldoc)
+    # @param [Hash, Options] opts
+    # @return [self]
+    def update(opts)
+      opts = opts.to_hash if Options === opts
+      opts.each do |key, value|
+        self[key] = value
+      end
+      self
+    end
+
+    # Creates a new options object and sets options hash or object value
+    # onto that object.
+    #
+    # @param [Options, Hash] opts
+    # @return [Options] the newly created options object
+    # @see #update
+    def merge(opts)
+      dup.update(opts)
+    end
+
+    # @return [Hash] Converts options object to an options hash. All keys
+    #   will be symbolized.
+    def to_hash
+      opts = {}
+      instance_variables.each do |ivar|
+        name = ivar.to_s.sub(/^@/, '')
+        opts[name.to_sym] = send(name)
+      end
+      opts
+    end
+
+    # Yields over every option key and value
+    # @yield [key, value] every option key and value
+    # @yieldparam [Symbol] key the option key
+    # @yieldparam [Object] value the option value
+    # @return [void]
+    def each(&block)
+      instance_variables.each do |ivar|
+        name = ivar.to_s.sub(/^@/, '')
+        yield(name.to_sym, send(name))
+      end
+    end
+
+    # Inspects the object
+    def inspect
+      "<#{self.class}: #{to_hash.inspect}>"
+    end
+
+    # @return [Boolean] whether another Options object equals the
+    #   keys and values of this options object
+    def ==(other)
+      case other
+      when Options; to_hash == other.to_hash
+      when Hash; to_hash == other
+      else false
+      end
+    end
+
+    # Handles setting and accessing of unregistered keys similar
+    # to an OpenStruct object.
+    #
+    # @note It is not recommended to set and access unregistered keys on
+    #   an Options object. Instead, register the attribute before using it.
+    def method_missing(meth, *args, &block)
+      if meth.to_s =~ /^(.+)=$/
+        log.debug "Attempting to set unregistered key #{$1} on #{self.class}"
+        instance_variable_set("@#{$1}", args.first)
+      elsif args.size == 0
+        log.debug "Attempting to access unregistered key #{meth} on #{self.class}"
+        instance_variable_get("@#{meth}")
+      else
+        super
+      end
+    end
+
+    # Resets all values to their defaults.
+    #
+    # @abstract Subclasses should override this method to perform custom
+    #   value initialization if not using {default_attr}. Be sure to call
+    #   +super+ so that default initialization can take place.
+    # @return [void]
+    def reset_defaults
+      names_set = {}
+      self.class.ancestors.each do |klass| # look at all ancestors
+        defaults = klass.instance_variable_get("@defaults")
+        next unless defaults
+        defaults.each do |key, value|
+          next if names_set[key]
+          names_set[key] = true
+          self[key] = Proc === value ? value.call : value
+        end
+      end
+    end
+
+    # Deletes an option value for +key+
+    #
+    # @param [Symbol, String] key the key to delete a value for
+    # @return [Object] the value that was deleted
+    def delete(key)
+      val = self[key]
+      if instance_variable_defined?("@#{key}")
+        remove_instance_variable("@#{key}")
+      end
+      val
+    end
+
+    unless defined? tap() # only for 1.8.6
+      def tap(&block) yield(self); self end
+    end
+  end
+end

data/lib/yard/parser/base.rb

@@ -0,0 +1,56 @@
+module YARD
+  module Parser
+    # Represents the abstract base parser class that parses source code in
+    # a specific way. A parser should implement {#parse}, {#tokenize} and
+    # {#enumerator}.
+    #
+    # == Registering a Custom Parser
+    # To register a parser, see {SourceParser.register_parser_type}
+    #
+    # @abstract
+    # @see #parse
+    # @see #tokenize
+    # @see #enumerator
+    # @since 0.5.6
+    class Base
+      # Convenience method to create a new parser and {#parse}
+      def self.parse(source, filename = nil)
+        new(source, filename).parse
+      end
+
+      # This default constructor does nothing. The subclass is responsible for
+      # storing the source contents and filename if they are required.
+      # @param [String] source the source contents
+      # @param [String] filename the name of the file if from disk
+      def initialize(source, filename)
+        raise NotImplementedError, "invalid parser implementation"
+      end
+
+      # This method should be implemented to parse the source and return itself.
+      # @abstract
+      # @return [Base] this method should return itself
+      def parse
+        raise NotImplementedError, "#{self.class} must implement #parse"
+      end
+
+      # This method should be implemented to tokenize given source
+      # @abstract
+      # @return [Array] a list/tree of lexical tokens
+      def tokenize
+        raise NotImplementedError, "#{self.class} does not support tokenization"
+      end
+
+      # This method should be implemented to return a list of semantic tokens
+      # representing the source code to be post-processed. Otherwise the method
+      # should return nil.
+      #
+      # @abstract
+      # @return [Array] a list of semantic tokens representing the source code
+      #   to be post-processed
+      # @return [nil] if no post-processing should be done
+      def enumerator
+        nil
+      end
+    end
+  end
+end

data/lib/yard/parser/c/c_parser.rb

@@ -0,0 +1,231 @@
+module YARD
+  module Parser
+    module C
+      class CParser < Base
+        def initialize(source, file = '(stdin)')
+          @file = file
+          @namespaces = {}
+          @content = source
+          @index = 0
+          @line = 1
+          @state = nil
+          @newline = true
+          @statements = []
+          @last_comment = nil
+          @last_statement = nil
+        end
+
+        def parse
+          parse_toplevel
+          enumerator
+        end
+
+        def enumerator
+          @statements
+        end
+
+        def tokenize
+          raise NotImplementedError, "no tokenization support for C/C++ files"
+        end
+
+        private
+
+        def parse_toplevel
+          advance_loop do
+            case char
+            when /['"]/; consume_quote(char)
+            when '#'; consume_directive
+            when '/'; consume_comment
+            when /\s/; consume_whitespace
+            else consume_toplevel_statement
+            end
+          end
+        end
+
+        def consume_quote(type = '"')
+          advance
+          advance_loop do
+            case char
+            when "\n"; advance; nextline
+            when '\\'; advance(2)
+            when type; advance; return
+            else advance
+            end
+          end
+        end
+
+        def consume_directive
+          return(advance) unless @newline
+          @last_comment = nil
+          @last_statement = nil
+          advance_loop do
+            if char == '\\' && nextchar =~ /[\r\n]/
+              advance_loop { advance; break(nextline) if char == "\n" }
+            elsif char == "\n"
+              return
+            end
+            advance
+          end
+        end
+
+        def consume_toplevel_statement
+          @newline = false
+          start = @index
+          line = @line
+          decl = consume_until(/[{;]/)
+          return nil if decl =~ /\A\s*\Z/
+          statement = ToplevelStatement.new(nil, @file, line)
+          @statements << statement
+          attach_comment(statement)
+          stmts = nil
+          if prevchar == '{'
+            stmts = consume_body_statements
+            if decl =~ /\A(typedef|enum|class|#{struct}|union)/
+              consume_until(';')
+            end
+          end
+          statement.source = @content[start..@index]
+          statement.block = stmts
+          statement.declaration = decl
+        end
+
+        def consume_body_statements
+          stmts = []
+          brace_level = 1
+          while true
+            strip_non_statement_data
+            start, line = @index, @line
+            consume_until(/[{};]/)
+            brace_level += 1 if prevchar == '{'
+            brace_level -= 1 if prevchar == '}'
+
+            break if prevchar.empty? || (brace_level <= 0 && prevchar == '}')
+            end_chr = @index
+            end_chr -= 1 if prevchar == '}'
+            src = @content[start...@index]
+            if src && src !~ /\A\s*\Z|\A\}\Z/
+              stmt = BodyStatement.new(src, @file, line)
+              attach_comment(stmt)
+              stmts << stmt
+            end
+          end
+          stmts
+        end
+
+        def strip_non_statement_data
+          start = @index
+          begin
+            start = @index
+            case char
+            when /\s/; consume_whitespace
+            when '#';  consume_directive
+            when '/';  consume_comment
+            end
+          end until start == @index
+        end
+
+        def consume_whitespace
+          advance_loop { nextline if char == "\n"; break if char =~ /\S/; advance }
+        end
+
+        def consume_comment(add_comment = true)
+          return(advance) unless nextchar == '*' || nextchar == '/'
+          line = @line
+          type = nextchar == '*' ? :multi : :line
+          advance(2)
+          comment = ""
+          advance_loop do
+            comment << char
+            if type == :multi
+              nextline if char == "\n"
+              if char(2) == '*/'
+                if add_comment
+                  comment << '/'
+                  stmt = Comment.new(comment, @file, line)
+                  stmt.type = type
+                  attach_comment(stmt)
+                  @statements << stmt
+                end
+                return advance(2)
+              end
+            elsif char == "\n"
+              if add_comment
+                stmt = Comment.new(comment[0...-1], @file, line)
+                stmt.type = type
+                attach_comment(stmt)
+                @statements << stmt
+              end
+              return
+            end
+            advance
+          end
+        end
+
+        def consume_until(end_char, bracket_level = 0, brace_level = 0, add_comment = true)
+          end_char = /#{end_char}/ if end_char.is_a?(String)
+          start = @index
+          advance_loop do
+            chr = char
+            case chr
+            when /\s/; consume_whitespace
+            when /['"]/; consume_quote(char)
+            when '#'; consume_directive
+            when '/'; consume_comment(add_comment)
+            when '{'; advance; brace_level += 1
+            when '}'; advance; brace_level -= 1
+            when '('; advance; bracket_level += 1
+            when ')'; advance; bracket_level -= 1
+            else advance
+            end
+            @newline = false if chr !~ /\s/
+
+            if chr =~ end_char && (chr == '{' || chr == '(')
+              break
+            elsif chr =~ end_char && bracket_level <= 0 && brace_level <= 0
+              break
+            end
+          end
+          return @content[start...@index]
+        end
+
+        def attach_comment(statement)
+          if Comment === statement
+            if @last_statement && @last_statement.line == statement.line
+              @last_statement.comments = statement
+              statement.statement = @last_statement
+            end
+            @last_comment = statement
+            @last_statement = nil
+          else
+            if @last_comment
+              statement.comments = @last_comment
+              @last_comment.statement = statement
+            end
+            @last_statement = statement
+            @last_comment = nil
+          end
+        end
+
+        def advance(num = 1) @index += num end
+        def back(num = 1) @index -= num end
+
+        def advance_loop(&block)
+          while @index <= @content.size; yield end
+        end
+
+        def nextline
+          @line += 1
+          @newline = true
+        end
+
+        def char(num = 1) @content[@index, num] end
+        def prevchar(num = 1) @content[@index - 1, num] end
+        def nextchar(num = 1) @content[@index + 1, num] end
+
+        def struct
+          /struct\s[:alnum:]+\s\{/
+        end
+      end
+    end
+  end
+end