etude_for_ruby 0.1.0 → 0.1.4

data/vendor/bundle/ruby/2.4.0/gems/yard-0.9.8/lib/yard/i18n/text.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+module YARD
+  module I18n
+    # Provides some convenient features for translating a text.
+    class Text
+      # Creates a text object that has translation related features for
+      # the input text.
+      #
+      # @param [#each_line] input a text to be translated.
+      # @option options [Boolean] :have_header (false) whether the
+      #   input text has header or not.
+      def initialize(input, options = {})
+        @input = input
+        @options = options
+      end
+
+      # Extracts translation target messages from +@input+.
+      #
+      # @yield [:attribute, name, value, line_no] the block that
+      #   recieves extracted an attribute in header. It may called many
+      #   times.
+      # @yieldparam [String] name the name of extracted attribute.
+      # @yieldparam [String] value the value of extracted attribute.
+      # @yieldparam [Integer] line_no the defined line number of extracted
+      #   attribute.
+      # @yield [:paragraph, text, start_line_no] the block that
+      #   recieves extracted a paragraph in body. Paragraph is a text
+      #   block separated by one or more empty lines. Empty line is a
+      #   line that contains only zero or more whitespaces. It may
+      #   called many times.
+      # @yieldparam [String] text the text of extracted paragraph.
+      # @yieldparam [Integer] start_line_no the start line number of
+      #   extracted paragraph.
+      # @return [void]
+      def extract_messages
+        parse do |part|
+          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 = String.new("")
+        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 = String.new("")
+        paragraph_start_line = 0
+        line_no = 0
+        in_header = @options[:have_header]
+
+        @input.each_line do |line|
+          line_no += 1
+          if in_header
+            case line
+            when /^#!\S+\s*$/
+              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
+              if line.strip.empty?
+                emit_empty_line_event(line, line_no, &block)
+                next
+              end
+            end
+            next if in_header
+          end
+
+          case line
+          when /^\s*$/
+            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 = String.new("")
+            end
+          else
+            paragraph_start_line = line_no if paragraph.empty?
+            paragraph << line
+          end
+        end
+
+        unless paragraph.empty?
+          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
+  end
+end

data/vendor/bundle/ruby/2.4.0/gems/yard-0.9.8/lib/yard/logging.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+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 unless level > INFO # 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
+      @progress_msg = nil
+    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)
+      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
+      @mutex.synchronize do
+        print("\e[2K\e[?25l\e[1m#{icon}#{msg}\e[0m\r")
+        @progress_msg = msg
+        @progress_indicator += 1
+        @progress_indicator %= PROGRESS_INDICATORS.size
+      end
+      Thread.new do
+        sleep(0.05)
+        progress(msg + ".", nil) if @progress_msg == msg
+      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 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 << 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)
+      old_level = level
+      self.level = new_level
+      yield
+    ensure
+      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/vendor/bundle/ruby/2.4.0/gems/yard-0.9.8/lib/yard/options.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+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
+      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.empty?
+        log.debug "Attempting to access unregistered key #{meth} on #{self.class}"
+        instance_variable_defined?("@#{meth}") ? instance_variable_get("@#{meth}") : nil
+      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_defined?("@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
+
+    def tap; yield(self); self end unless defined?(tap) # only for 1.8.6
+  end
+end