Skip to content
John Mair edited this page Jul 10, 2011 · 14 revisions

Plugins

### Quick Menu:

Back to Main Menu

Overview

Pry can be extended by way of plugins. A plugin is very simple - it is just a gem that is automatically required when a Pry session starts.

### What is a plugin?

A valid Pry plugin is a gem that has the pry- prefix (such as the pry-doc gem). There must also be a pry-PLUGINNAME.rb file in the lib/ folder of the gem. The functionality provided by a plugin is typically implemented by way of the customization and command system APIs.

In the following example, assume we have created a gem called pry-sample that has the file pry-sample.rb in the lib/ folder.

Example: Contents of lib/pry-sample.rb

Pry.config.prompt = proc { "Sample Plugin Prompt> " }

From above, the pry-sample gem is a valid Pry plugin. Once it is installed it will be required automatically by Pry and the Pry prompt will be set to Sample Plugin Prompt>

Back to top

### Loading and suppression (all plugins)

If a Pry plugin is installed (i.e a gem with the pry- prefix) it will be loaded automatically when a session starts. As stated in the .pryrc section, plugins are loaded after the .pryrc file is loaded but before history is loaded; this means that plugin loading can be controlled in the .pryrc file; it also means that plugins can control the configuration of history.

As plugins are loaded automatically, suppression of plugin loading must be explicit:

Command line suppression

From the command-line all plugin loading can be suppressed using the --no-plugins switch:

Example: Suppress all plugin loading from command line

crow:~ john$ pry --no-plugins

Runtime suppression

If invoking Pry at runtime you can disable Plugin loading by using the Pry.config.should_load_plugins configuration option:

Example: Disable plugin loading at runtime

Pry.config.should_load_plugins = false

Back to top

### Loading and suppression (per plugin)

For finer grained control over plugins, individual plugin loading can be turned on and off.

Disabling a specific plugin

An individual plugin can be disabled (leaving other plugins enabled) by using the Pry.plugins API:

Example: Disable only the pry-doc plugin

Pry.plugins["doc"].disable!

Forcing activation of specific plugins

Alternatively, if you invoke the Pry executable with the --no-plugins switch you can still activate specific plugins.

Example:

Pry.plugins["doc"].activate!

All of the above applies equally when invoking Pry at runtime, simply put the relevants calls to the Pry.plugins API before you first invoke Pry.