class Pry::Indent - pry-0.10.1 Documentation

# class Pry::Indent

Pry::Indent is a class that can be used to indent a number of lines containing Ruby code similar as to how IRB does it (but better). The class works by tokenizing a string using CodeRay and then looping over those tokens. Based on the tokens in a line of code that line (or the next one) will be indented or un-indented by correctly.

### Constants

IGNORE_TOKENS

  Collection of token types that should be ignored. Without this list keywords such as “class” inside strings would cause the code to be indented incorrectly.

  :pre_constant and :preserved_constant are the CodeRay 0.9.8 and 1.0.0 classifications of “true”, “false”, and “nil”.

MIDWAY_TOKENS

  Collection of tokens that should appear dedented even though they don’t affect the surrounding code.

OPEN_TOKENS

  Hash containing all the tokens that should increase the indentation level. The keys of this hash are open tokens, the values the matching tokens that should prevent a line from being indented if they appear on the same line.

OPTIONAL_DO_TOKENS

  Which tokens can be followed by an optional “do” keyword.

SINGLELINE_TOKENS

  Which tokens can either be open tokens, or appear as modifiers on a single-line.

SPACES

  The amount of spaces to insert for each indent level.

STATEMENT_END_TOKENS

  Tokens that indicate the end of a statement (i.e. that, if they appear directly before an “if” indicates that that if applies to the same line, not the next line)

  :reserved and :keywords are the CodeRay 0.9.8 and 1.0.0 respectively classifications of “super”, “next”, “return”, etc.

### Attributes

indent_level[R]

@return [String] String containing the spaces to be inserted before the next line.

stack[R]

@return [Array<String>] The stack of open tokens.

### Public Class Methods

indent(str) click to toggle source

Clean the indentation of a fragment of ruby.

@param [String] str @return [String]

    # File lib/pry/indent.rb, line 80
    def self.indent(str)
      new.indent(str)
    end

nesting_at(str, line_number) click to toggle source

Get the module nesting at the given point in the given string.

NOTE If the line specified contains a method definition, then the nesting at the start of the method definition is used. Otherwise the nesting from the end of the line is used.

@param [String] str The ruby code to analyze @param [Fixnum] line_number The line number (starting from 1) @return [Array<String>]

    # File lib/pry/indent.rb, line 93
    def self.nesting_at(str, line_number)
      indent = new
      lines = str.split("\n")
      n = line_number - 1
      to_indent = lines[0...n] << (lines[n] || "").split("def").first(1)
      indent.indent(to_indent.join("\n") << "\n")
      indent.module_nesting
    end

new() click to toggle source

    # File lib/pry/indent.rb, line 102
    def initialize
      reset
    end

### Public Instance Methods

correct_indentation(prompt, code, overhang=0) click to toggle source

Return a string which, when printed, will rewrite the previous line with the correct indentation. Mostly useful for fixing ‘end’.

@param [String] prompt The user’s prompt @param [String] code The code the user just typed in. @param [Fixnum] overhang (0) The number of chars to erase afterwards (i.e.,

    the difference in length between the old line and the new one).

@return [String]

    # File lib/pry/indent.rb, line 385
    def correct_indentation(prompt, code, overhang=0)
      prompt = prompt.delete("\001\002")
      line_to_measure = Pry::Helpers::Text.strip_color(prompt) << code
      whitespace = ' ' * overhang

      _, cols = Terminal.screen_size

      cols = cols.to_i
      lines = (cols != 0 ? (line_to_measure.length / cols + 1) : 1).to_i

      if Pry::Helpers::BaseHelpers.windows_ansi?
        move_up   = "\e[#{lines}F"
        move_down = "\e[#{lines}E"
      else
        move_up   = "\e[#{lines}A\e[0G"
        move_down = "\e[#{lines}B\e[0G"
      end

      "#{move_up}#{prompt}#{colorize_code(code)}#{whitespace}#{move_down}"
    end

current_prefix() click to toggle source

Get the indentation for the start of the next line.

This is what’s used between the prompt and the cursor in pry.

@return String The correct number of spaces

    # File lib/pry/indent.rb, line 177
    def current_prefix
      in_string? ? '' : indent_level
    end

end_of_statement?(last_token, last_kind) click to toggle source

If the code just before an “if” or “while” token on a line looks like the end of a statement, then we want to treat that “if” as a singleline, not multiline statement.

    # File lib/pry/indent.rb, line 252
    def end_of_statement?(last_token, last_kind)
      (last_token =~ /^[)\]}\/]$/ || STATEMENT_END_TOKENS.include?(last_kind))
    end

in_string?() click to toggle source

Are we currently in the middle of a string literal.

This is used to determine whether to re-indent a given line, we mustn’t re-indent within string literals because to do so would actually change the value of the String!

@return Boolean

    # File lib/pry/indent.rb, line 263
    def in_string?
      !open_delimiters.empty?
    end

indent(input) click to toggle source

Indents a string and returns it. This string can either be a single line or multiple ones.

@example

    str = <<TXT
    class User
    attr_accessor :name
    end
    TXT

    # This would result in the following being displayed:
    #
    # class User
    #   attr_accessor :name
    # end
    #
    puts Pry::Indent.new.indent(str)

@param [String] input The input string to indent. @return [String] The indented version of `input`.

    # File lib/pry/indent.rb, line 139
    def indent(input)
      output = ''
      prefix = indent_level

      input.lines.each do |line|

        if in_string?
          tokens = tokenize("#{open_delimiters_line}\n#{line}")
          tokens = tokens.drop_while{ |token, type| !(String === token && token.include?("\n")) }
          previously_in_string = true
        else
          tokens = tokenize(line)
          previously_in_string = false
        end

        before, after = indentation_delta(tokens)

        before.times{ prefix.sub! SPACES, '' }
        new_prefix = prefix + SPACES * after

        line = prefix + line.lstrip unless previously_in_string

        output += line

        prefix = new_prefix
      end

      @indent_level = prefix

      return output
    end

indentation_delta(tokens) click to toggle source

Get the change in indentation indicated by the line.

By convention, you remove indent from the line containing end tokens, but add indent to the line after that which contains the start tokens.

This method returns a pair, where the first number is the number of closings on this line (i.e. the number of indents to remove before the line) and the second is the number of openings (i.e. the number of indents to add after this line)

@param [Array] tokens A list of tokens to scan. @return [Array]

    # File lib/pry/indent.rb, line 194
    def indentation_delta(tokens)

      # We need to keep track of whether we've seen a "for" on this line because
      # if the line ends with "do" then that "do" should be discounted (i.e. we're
      # only opening one level not two) To do this robustly we want to keep track
      # of the indent level at which we saw the for, so we can differentiate
      # between "for x in [1,2,3] do" and "for x in ([1,2,3].map do" properly
      seen_for_at = []

      # When deciding whether an "if" token is the start of a multiline statement,
      # or just the middle of a single-line if statement, we just look at the
      # preceding token, which is tracked here.
      last_token, last_kind = [nil, nil]

      # delta keeps track of the total difference from the start of each line after
      # the given token, 0 is just the level at which the current line started for
      # reference.
      remove_before, add_after = [0, 0]

      # If the list of tokens contains a matching closing token the line should
      # not be indented (and thus we should return true).
      tokens.each do |token, kind|
        is_singleline_if  = (SINGLELINE_TOKENS.include?(token)) && end_of_statement?(last_token, last_kind)
        is_optional_do = (token == "do" && seen_for_at.include?(add_after - 1))

        last_token, last_kind = token, kind unless kind == :space
        next if IGNORE_TOKENS.include?(kind)

        track_module_nesting(token, kind)

        seen_for_at << add_after if OPTIONAL_DO_TOKENS.include?(token)

        if kind == :delimiter
          track_delimiter(token)
        elsif OPEN_TOKENS.keys.include?(token) && !is_optional_do && !is_singleline_if
          @stack << token
          add_after += 1
        elsif token == OPEN_TOKENS[@stack.last]
          popped = @stack.pop
          track_module_nesting_end(popped)
          if add_after == 0
            remove_before += 1
          else
            add_after -= 1
          end
        elsif MIDWAY_TOKENS.include?(token)
          if add_after == 0
            remove_before += 1
            add_after += 1
          end
        end
      end

      return [remove_before, add_after]
    end

module_nesting() click to toggle source

Return a list of strings which can be used to re-construct the Module.nesting at the current point in the file.

Returns nil if the syntax of the file was not recognizable.

@return [Array<String>]

    # File lib/pry/indent.rb, line 369
    def module_nesting
      @module_nesting.map do |(kind, token)|
        raise UnparseableNestingError, @module_nesting.inspect if token.nil?

        "#{kind} #{token}"
      end
    end

open_delimiters() click to toggle source

All the open delimiters, in the order that they first appeared.

@return [String]

    # File lib/pry/indent.rb, line 303
    def open_delimiters
      @heredoc_queue + [@string_start].compact
    end

open_delimiters_line() click to toggle source

Return a string which restores the CodeRay string status to the correct value by opening HEREDOCs and strings.

@return String

    # File lib/pry/indent.rb, line 311
    def open_delimiters_line
      "puts #{open_delimiters.join(", ")}"
    end

reset() click to toggle source

reset internal state

    # File lib/pry/indent.rb, line 107
    def reset
      @stack = []
      @indent_level = ''
      @heredoc_queue = []
      @close_heredocs = {}
      @string_start = nil
      @awaiting_class = false
      @module_nesting = []
      self
    end

tokenize(string) click to toggle source

Given a string of Ruby code, use CodeRay to export the tokens.

@param [String] string The Ruby to lex @return [Array] An Array of pairs of [token_value, token_type]

    # File lib/pry/indent.rb, line 271
    def tokenize(string)
      tokens = CodeRay.scan(string, :ruby)
      tokens = tokens.tokens.each_slice(2) if tokens.respond_to?(:tokens) # Coderay 1.0.0
      tokens.to_a
    end

track_delimiter(token) click to toggle source

Update the internal state about what kind of strings are open.

Most of the complication here comes from the fact that HEREDOCs can be nested. For normal strings (which can’t be nested) we assume that CodeRay correctly pairs open-and-close delimiters so we don’t bother checking what they are.

@param [String] token The token (of type :delimiter)

    # File lib/pry/indent.rb, line 284
    def track_delimiter(token)
      case token
      when /^<<-(["'`]?)(.*)\1/
        @heredoc_queue << token
        @close_heredocs[token] = /^\s*$2/
      when @close_heredocs[@heredoc_queue.first]
        @heredoc_queue.shift
      else
        if @string_start
          @string_start = nil
        else
          @string_start = token
        end
      end
    end

track_module_nesting(token, kind) click to toggle source

Update the internal state relating to module nesting.

It’s responsible for adding to the @module_nesting array, which looks something like:

[“class”, “Foo”], [“module”, “Bar::Baz”], [“class <<”, “self”

  ]

A nil value in the @module_nesting array happens in two places: either when @awaiting_class is true and we’re still waiting for the string to fill that space, or when a parse was rejected.

At the moment this function is quite restricted about what formats it will parse, for example we disallow expressions after the class keyword. This could maybe be improved in the future.

@param [String] token a token from Coderay @param [Symbol] kind the kind of that token

    # File lib/pry/indent.rb, line 332
    def track_module_nesting(token, kind)
      if kind == :keyword && (token == "class" || token == "module")
        @module_nesting << [token, nil]
        @awaiting_class = true
      elsif @awaiting_class
        if kind == :operator && token == "<<" && @module_nesting.last[0] == "class"
          @module_nesting.last[0] = "class <<"
          @awaiting_class = true
        elsif kind == :class && token =~ /\A(self|[A-Z:][A-Za-z0-9_:]*)\z/
          @module_nesting.last[1] = token if kind == :class
          @awaiting_class = false
        else
          # leave @module_nesting[-1]
          @awaiting_class = false
        end
      end
    end

track_module_nesting_end(token, kind=:keyword) click to toggle source

Update the internal state relating to module nesting on ‘end’.

If the current ‘end’ pairs up with a class or a module then we should pop an array off of @module_nesting

@param [String] token a token from Coderay @param [Symbol] kind the kind of that token

    # File lib/pry/indent.rb, line 357
    def track_module_nesting_end(token, kind=:keyword)
      if kind == :keyword && (token == "class" || token == "module")
        @module_nesting.pop
      end
    end