Ruby の定番対話ツール pry 徹底攻略 | Live help system

概要

Ruby の定番対話ツール pry 徹底攻略
Live help system について

Live help system

pry の設計のひとつのゴールはセルフドキュメンテーションです。
そのためにも、 pry は REPL 内で利用する pry のほとんどすべての
ドキュメントを提供します。

Viewing a Pry method's documentation

Pry はただの Ruby のコードであり、ほとんどのドキュメントは
show-doc コマンドで参照可能です。

`show-doc` のドキュメントを取得する

[2] pry(main)> show-doc show-doc

From: /path/to/ruby/gems/2.1.0/gems/pry-0.10.1/lib/pry/commands/show_doc.rb
Number of lines: 15

Usage:   show-doc [OPTIONS] [METH]
Aliases: ?

Show the documentation for a method or class. Tries instance methods first and
then methods by default.

show-doc hi_method # docs for hi_method
show-doc Pry       # for Pry class
show-doc Pry -a    # for all definitions of Pry class (all monkey patches)

    -s, --super             Select the 'super' method. Can be repeated to traverse the ancestors
    -l, --line-numbers      Show line numbers
    -b, --base-one          Show line numbers but start numbering at 1 (useful for `amend-line` and `play` commands)
    -a, --all               Show all definitions and monkeypatches of the module/class
    -h, --help              Show this message.

show-doc の alias である、 `?` で `Pry#prompt` のドキュメントを取得する

[6] pry(main)> ? Pry#prompt

From: /path/to/ruby/gems/2.1.0/gems/pry-0.10.1/lib/pry/pry_instance.rb @ line 84:
Owner: Pry
Visibility: public
Signature: prompt()
Number of lines: 8

The current prompt.
This is the prompt at the top of the prompt stack.

example
   self.prompt = Pry::SIMPLE_PROMPT
   self.prompt # => Pry::SIMPLE_PROMPT

return [Array<Proc>] Current prompt.

Learning about Pry's configuration options

オプションのヘルプを確認

Live Help 機能は、 pry のオプション設定について覚えるのに便利です。（公式ドキュメント談）
しかし・・・

[21] pry("hoge"):2> ? Pry.config.editor
Error: No superclass found for #<Method: #<Pry::Config:0x3ff173dddb60 local_keys=['pry_debugger','pry_doc','has_pry_doc','hooks'] default=#<Pry::Config::Default:0x3ff173de70e8 local_keys=['gist','history'] default=nil>>.editor>
[23] pry("hoge"):2> _ex_.backtrace
=> ["(pry):6:in `__pry__'",
 "/path/to/ruby/gems/2.0.0/gems/pry-0.10.1/lib/pry/pry_instance.rb:355:in `eval'",
 "/path/to/ruby/gems/2.0.0/gems/pry-0.10.1/lib/pry/pry_instance.rb:355:in `evaluate_ruby'",
# 以下略

公式ドキュメントをそのまま試したらエラーになった。
※念のため Windows + Cygwin 環境と Ubuntu 環境の双方で確認したが同じ。

参考までにソースコードの表示も試したがダメ

[25] pry(main)> $ Pry.config.editor
Error: No superclass found for #<Method: #<Pry::Config:0x300359410 local_keys=['pry_byebug','pry_doc','has_pry_doc','hooks'] default=#<Pry::Config::Default:0x3003598c0 local_keys=['gist','history'] default=nil>>.editor>

代替手段を探す

以下で、ソースコードは表示できた

[58] pry("hoge"):1> $ _pry_.editor

From: /path/to/.rbenv/versions/2.1.0-rc1/lib/ruby/gems/2.1.0/gems/pry-0.10.1/lib/pry/config/convenience.rb @ line 21:
Owner: Pry
Visibility: public
Number of lines: 1

define_method(reader) { config.public_send(name) }

ドキュメントは・・・だめ

これって、公式ドキュメントを書いた当初はべた書き実装で、メソッドコメントが付いていたけど、
現在は define_method で動的定義しているからドキュメントがない、ってことだろうか？
Wiki の該当ページの最終更新日は 6 Feb 2013

[61] pry("hoge"):1> ? _pry_.editor
Error: No docs found for: _pry_.editor

バグではなく、ドキュメンテーションが追いついていない、といったところでしょうか？

とりあえず、今後記事化予定の

の内容が古くなければそちらでカバーできそうかな？

The help command (Pry command documentation)

Pry の command はメソッドではないため、他のメソッドのように簡単に show-doc で確認できません。
代わりに、 help command を利用します。

help で実行可能な全コマンドを表示します。
help <command name> で対象コマンドの詳細を表示します。

`help`

[9] pry(main)> help
Help
  help               Show a list of commands or information about a specific command.

Context
  cd                 Move into a new context (object or scope).
  find-method        Recursively search for a method within a class/module or the current namespace.
  ls                 Show the list of vars and methods in the current scope.
  pry-backtrace      Show the backtrace for the pry session.
  raise-up           Raise an exception out of the current pry instance.
  reset              Reset the repl to a clean state.
  watch              Watch the value of an expression and print a notification whenever it changes.
  whereami           Show code surrounding the current context.
  wtf?               Show the backtrace of the most recent exception.

Editing
  /^\s*!\s*$/        Clear the input buffer.
  amend-line         Amend a line of input in multi-line mode.
  edit               Invoke the default editor on a file.
  hist               Show and replay readline history.
  play               Playback a string variable, method, line, or file as input.
  show-input         Show the contents of the input buffer for the current multi-line expression.

Introspection
  ri                 View ri documentation.
  show-doc           Show the documentation for a method or class.
  show-source        Show the source for a method or class.
  stat               View method information and set _file_ and _dir_ locals.

Gems
[10] pry(main)> help
Help
  help               Show a list of commands or information about a specific command.

Context
  cd                 Move into a new context (object or scope).
  find-method        Recursively search for a method within a class/module or the current namespace.
  ls                 Show the list of vars and methods in the current scope.
  pry-backtrace      Show the backtrace for the pry session.
  raise-up           Raise an exception out of the current pry instance.
  reset              Reset the repl to a clean state.
  watch              Watch the value of an expression and print a notification whenever it changes.
  whereami           Show code surrounding the current context.
  wtf?               Show the backtrace of the most recent exception.

Editing
  /^\s*!\s*$/        Clear the input buffer.
  amend-line         Amend a line of input in multi-line mode.
  edit               Invoke the default editor on a file.
  hist               Show and replay readline history.
  play               Playback a string variable, method, line, or file as input.
  show-input         Show the contents of the input buffer for the current multi-line expression.

Introspection
  ri                 View ri documentation.
  show-doc           Show the documentation for a method or class.
  show-source        Show the source for a method or class.
  stat               View method information and set _file_ and _dir_ locals.

Gems
  gem-cd             Change working directory to specified gem's directory.
  gem-install        Install a gem and refresh the gem cache.
  gem-list           List and search installed gems.
  gem-open           Opens the working directory of the gem in your editor.

Commands
  import-set         Import a pry command set.
  install-command    Install a disabled command.

Aliases
  !!!                Alias for `exit-program`
  !!@                Alias for `exit-all`
  $                  Alias for `show-source`
  ?                  Alias for `show-doc`
  @                  Alias for `whereami`
  breakpoint         Alias for `break`
  breaks             Alias for `breakpoints`
  c                  Alias for `continue`
  clipit             Alias for `gist --clip`
  f                  Alias for `finish`
  file-mode          Alias for `shell-mode`
  history            Alias for `hist`
  n                  Alias for `next`
  quit               Alias for `exit`
  quit-program       Alias for `exit-program`
  reload-method      Alias for `reload-code`
  s                  Alias for `step`
  show-method        Alias for `show-source`

Input and output
  .<shell command>   All text following a '.' is forwarded to the shell.
  cat                Show code from a file, pry's input buffer, or the last exception.
  change-inspector   Change the current inspector proc.
  change-prompt      Change the current prompt.
  fix-indent         Correct the indentation for contents of the input buffer
  list-inspectors    List the inspector procs available for use.
  list-prompts       List the prompts available for use.
  save-file          Export to a file using content from the repl.
  shell-mode         Toggle shell mode. bring in pwd prompt and file completion.

Misc
  gist               Upload code, docs, history to https://gist.github.com/.
  pry-version        Show pry version.
  reload-code        Reload the source file that contains the specified code object.
  toggle-color       Toggle syntax highlighting.

Navigating pry
  !pry               Start a pry session on current self.
  disable-pry        Stops all future calls to pry and exits the current session.
  exit               Pop the previous binding.
  exit-all           End the current pry session.
  exit-program       End the current program.
  jump-to            Jump to a binding further up the stack.
  nesting            Show nesting information.
  switch-to          Start a new subsession on a binding in the current stack.

Prompts
  simple-prompt      Toggle the simple prompt.

Pry-byebug (v2.0.0)
  break              Set or edit a breakpoint.
  breakpoints        List defined breakpoints.
  continue           Continue program execution and end the pry session.
  finish             Execute until current stack frame returns.
  next               Execute the next line within the current stack frame.
  step               Step execution into the next line or method.

`help hist`

[12] pry(main)> help hist
Usage:   hist [--head|--tail]
         hist --all
         hist --head N
         hist --tail N
         hist --show START..END
         hist --grep PATTERN
         hist --clear
         hist --replay START..END
         hist --save [START..END] FILE
Aliases: history

Show and replay Readline history.

    -a, --all              Display all history
    -H, --head             Display the first N items
    -T, --tail             Display the last N items
    -s, --show             Show the given range of lines
    -G, --grep             Show lines matching the given pattern
    -c, --clear            Clear the current session's history
    -r, --replay           Replay a line or range of lines
        --save             Save history to a file
    -e, --exclude-pry      Exclude Pry commands from the history
    -n, --no-numbers       Omit line numbers
    -h, --help             Show this message.