mirror of
https://github.com/sstent/sublime-text-3.git
synced 2026-02-06 12:32:21 +00:00
backing up sublime settings
This commit is contained in:
398
Packages/SublimeREPL/doc/index.rst
Normal file
398
Packages/SublimeREPL/doc/index.rst
Normal file
@@ -0,0 +1,398 @@
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
SublimeREPL
|
||||
===========
|
||||
|
||||
SublimeREPL is a plugin for Sublime Text 2 that lets you run interactive
|
||||
interpreters of several languages within a normal editor tab. It also allows
|
||||
connecting to a running remote interpreter (e.g. Clojure/Lein) though a telnet
|
||||
port.
|
||||
|
||||
SublimeREPL has a built-in support for command history and transferring code
|
||||
from open buffers to the interpreters for evaluation, enabling interactive
|
||||
programming.
|
||||
|
||||
.. note::
|
||||
This documentation is work in progress. Details on language integrations are
|
||||
sorely missing. Please contribute!
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
Download `Package Control`__, select Install Package and pick SublimeREPL from the list of
|
||||
available packages. You should have Package Control anyway.
|
||||
|
||||
__ http://wbond.net/sublime_packages/package_control
|
||||
|
||||
|
||||
Quick Start
|
||||
-----------
|
||||
|
||||
SublimeREPL adds itself as a submenu in Tools. You can choose any one of the
|
||||
preconfigured REPLs and if it's available in your SYSTEM PATH [#]_, it will
|
||||
be launched immediately.
|
||||
|
||||
.. image:: _static/menu.png
|
||||
|
||||
Second and more user friendly way to launch any given REPL is through Command
|
||||
Palette. Bring up Command Palette and type "repl". You will be presented with
|
||||
all preconfigured REPLs. Running REPL through Command Palette has exactly the
|
||||
same result as picking it from *Tools > SublimeREPL* menu.
|
||||
|
||||
.. image:: _static/palette.png
|
||||
|
||||
.. [#] One of the most frequently reported errors is SublimeREPL not being able
|
||||
to find interpreter executable, even if it's visible in your shell. There are several way to fix this problem that we'll discuss in FAQ.
|
||||
|
||||
You may now use a source buffer to either evaluate text from the buffer in
|
||||
the REPL or copy text over to the REPL without evaluation. For this to work,
|
||||
ensure that the language syntax definition for your source buffer matches
|
||||
the REPL.
|
||||
|
||||
Keyboard shortcuts
|
||||
------------------
|
||||
|
||||
The default shortcuts shipped with SublimeREPL are listed below. If you are
|
||||
accustomed to another REPL keymap, or if you intend to work in REPL a lot
|
||||
(lispers pay attention!) you may want to rebind the keys more to your liking.
|
||||
|
||||
REPL keys
|
||||
^^^^^^^^^
|
||||
|
||||
.. NOTE::
|
||||
The list below omits the trivial text editing keybindings (e.g. left, right
|
||||
etc). They are nevertheless configurable in keymap files.
|
||||
|
||||
+---------------+---------------+----------------+----------------------------------+-------------------------------------------------+
|
||||
| Linux | OS X | Windows | Command used | Meaning |
|
||||
+===============+===============+================+==================================+=================================================+
|
||||
| Up | Up | Up | repl_view_previous | Walk back to previous input, with autocomplete |
|
||||
+---------------+---------------+----------------+----------------------------------+-------------------------------------------------+
|
||||
| Alt+p | Ctrl+p | Alt+p | repl_view_previous | Walk back to previous input, no autocomplete |
|
||||
+---------------+---------------+----------------+----------------------------------+-------------------------------------------------+
|
||||
| Down | Down | Down | repl_view_next | Walk back to next input, with autocomplete |
|
||||
+---------------+---------------+----------------+----------------------------------+-------------------------------------------------+
|
||||
| Alt+n | Ctrl+n | Alt+n | repl_view_next | Walk back to next input, no autocomplete |
|
||||
+---------------+---------------+----------------+----------------------------------+-------------------------------------------------+
|
||||
| Enter | Enter | Enter | repl_enter | Send current line to REPL |
|
||||
+---------------+---------------+----------------+----------------------------------+-------------------------------------------------+
|
||||
| Esc | Esc | Esc | repl_escape | Clear REPL input |
|
||||
+---------------+---------------+----------------+----------------------------------+-------------------------------------------------+
|
||||
| Ctrl+l | Ctrl+l | Shift+Ctrl+c | repl_clear | Clear REPL screen |
|
||||
+---------------+---------------+----------------+----------------------------------+-------------------------------------------------+
|
||||
| Shift+Ctrl+c | Shift+Ctrl+c | *Unsupported* | subprocess_repl_send_signal | Send SIGINT to REPL |
|
||||
+---------------+---------------+----------------+----------------------------------+-------------------------------------------------+
|
||||
|
||||
Source buffer keys
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. important::
|
||||
The keybindings here use Ctrl+, as a prefix (C-, in emacs notation), meaning press Ctrl, press comma, release both. Pressing the
|
||||
prefix combination and then the letter will immediately send the target text into the REPL and *evaluate* it as if you pressed enter.
|
||||
If you want to prevent evaluation and send the text for *editing* in the REPL, press Shift with the prefix combination.
|
||||
|
||||
.. note::
|
||||
Default source buffer keys are identical on all platforms.
|
||||
|
||||
+---------------+--------------------------------------------------------------------------------------------------------------------+
|
||||
| Key | Meaning |
|
||||
+===============+====================================================================================================================+
|
||||
| Ctrl+, b | Send the current "block" to REPL. Currently Clojure-only. |
|
||||
+---------------+--------------------------------------------------------------------------------------------------------------------+
|
||||
| Ctrl+, s | Send the selection to REPL |
|
||||
+---------------+--------------------------------------------------------------------------------------------------------------------+
|
||||
| Ctrl+, f | Send the current file to REPL |
|
||||
+---------------+--------------------------------------------------------------------------------------------------------------------+
|
||||
| Ctrl+, l | Send the current line to REPL |
|
||||
+---------------+--------------------------------------------------------------------------------------------------------------------+
|
||||
|
||||
Language specific information
|
||||
-----------------------------
|
||||
|
||||
SublimeREPL's integration with a specific language includes language-specific
|
||||
main menu and palette options for REPL startup, keymaps, and special REPL
|
||||
extensions unique to the target language. An integration may contain several
|
||||
different REPL modes which are based on different underlying classes.
|
||||
|
||||
Clojure
|
||||
^^^^^^^
|
||||
|
||||
The Clojure integration supports Leiningen projects.
|
||||
You must install Leiningen to use Clojure integration.
|
||||
|
||||
If your Leiningen installation is not system-global, you may need to tweak
|
||||
SublimeREPL configuration (via Preferences > Package Settings > SublimeREPL >
|
||||
Settings - User) so that we can find your lein binary::
|
||||
|
||||
"default_extend_env": {"PATH": "{PATH}:/home/myusername/bin"}
|
||||
|
||||
To start a REPL subprocess with Leiningen project environment, open your `project.clj`
|
||||
and, while it is the current file, use the menu or the command palette to start the REPL.
|
||||
|
||||
* In subprocess REPL mode, the REPL is launched as a subprocess of the editor.
|
||||
This is the mode you should use right now.
|
||||
* The telnet mode no longer works because of the changes in Leiningen and nrepl.
|
||||
|
||||
The source buffer "send block" command (Ctrl+, b) deserves a special mention.
|
||||
Performing this command while the cursor is within the body of a definition
|
||||
will select this (current, top-level) definition and send it to the REPL for
|
||||
evaluation. This means that the latest version of the function you're
|
||||
currently working on will be installed in the live environment so that you
|
||||
can immediately start playing with it in the REPL. This is similar to [slime
|
||||
-]eval-defun in emacs.
|
||||
|
||||
Additional keybindings are available for Clojure:
|
||||
|
||||
+---------------+--------------------------------------------------------------------------------------------------------------------+
|
||||
| Key | Meaning |
|
||||
+===============+====================================================================================================================+
|
||||
| Ctrl+F12 c s | Launch a subprocess Clojure REPL |
|
||||
+---------------+--------------------------------------------------------------------------------------------------------------------+
|
||||
| Ctrl+F12 c t | Connect to a running Clojure REPL |
|
||||
+---------------+--------------------------------------------------------------------------------------------------------------------+
|
||||
|
||||
Python
|
||||
^^^^^^
|
||||
|
||||
Both stock Python and Execnet integrations support virtualenv. Various ways to work with Python, including PDB and IPython, are supported.
|
||||
|
||||
Documentation contributions from a Python specialist are welcome.
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
The default SublimeREPL configuration documents all available configuration settings.
|
||||
|
||||
Frequently Asked Questions
|
||||
--------------------------
|
||||
|
||||
**SublimeREPL can't launch the REPL process - OSError(2, 'No such file or directory'), how do I fix that?**
|
||||
|
||||
Sublime is unable to locate the binary that is needed to launch your REPL in the search paths available to it. This is
|
||||
because the subprocess REPLs are launched, as, well, subprocesses of Sublime environment, which may be different from
|
||||
your interactive environment, especially if your REPL is installed in a directory that is not in a system-wide path (e.g
|
||||
`/usr/local/bin` or '/home/myusername` on Linux, `My Documents` on Windows etc)
|
||||
|
||||
If the binary is not in your system path and you can't or won't change that, tweak SublimeREPL configuration::
|
||||
|
||||
{
|
||||
...
|
||||
"default_extend_env": {"PATH": "{PATH}:/home/myusername/bin"}
|
||||
...
|
||||
}
|
||||
|
||||
**I'd like an interactive REPL for Foo and it is not supported, what do?**
|
||||
|
||||
Chances are, you only need a minimal amount of work to add an integration, and necessary steps are described
|
||||
here briefly.
|
||||
|
||||
If you already have an interactive shell for Foo, you can use the subprocess
|
||||
REPL. For an example, see PHP or Lua integration in `config/PHP`.
|
||||
|
||||
If Foo provides an interactive environment over TCP, you can use the telnet
|
||||
REPL. For an example, see MozRepl integration
|
||||
|
||||
Supported languages
|
||||
-------------------
|
||||
|
||||
SublimeREPL currently ships with support for the following languages:
|
||||
|
||||
* Clisp
|
||||
* Clojure
|
||||
* CoffeeScript
|
||||
* Elixir
|
||||
* Execnet Python
|
||||
* Erlang
|
||||
* F#
|
||||
* Groovy
|
||||
* Haskell
|
||||
* Lua
|
||||
* Matlab
|
||||
* MozRepl
|
||||
* NodeJS
|
||||
* Octave
|
||||
* Perl
|
||||
* PHP interactive mode
|
||||
* PowerShell
|
||||
* Python
|
||||
* R
|
||||
* Racket
|
||||
* Ruby
|
||||
* Scala
|
||||
* Scheme
|
||||
* Shell (Windows, Linux and OS X)
|
||||
* SML
|
||||
* Sublime internal REPL (?)
|
||||
* Tower (CoffeeScript)
|
||||
|
||||
Structure of SublimeREPL
|
||||
------------------------
|
||||
|
||||
.. NOTE::
|
||||
If this is your first time dealing with Sublime plugins, you may find it a bit too magical. Basically,
|
||||
Sublime automatically scans plugin directories loads configuration files and plugin code without manual
|
||||
intervention, and reloads them dynamically as soon as they change. The entry points to a plugin's code are its commands,
|
||||
which are Python objects that extend Sublime's standard command class. Sublime calls them when needed. There
|
||||
is no initialization entry point or a "plugin loaded" callback or somesuch.
|
||||
|
||||
Basics of language integration: configuration and launch commands
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A language integration in SublimeREPL consists of configuration files and,
|
||||
where needed, Python code. The configuration consists of:
|
||||
|
||||
* Menu configuration files which specify the actual REPL object configuration
|
||||
* Command palette `configuration files <http://docs.sublimetext.info/en/latest/reference/command_palette.html>`_
|
||||
* Optional `keybinding configuration files <http://docs.sublimetext.info/en/latest/reference/key_bindings.html>`_
|
||||
|
||||
REPLs are started by SublimeREPL command `repl_open`. The command and its
|
||||
arguments is usually specified in the menu configuration file, and the other
|
||||
places refer to that configuration item by file name and ID using the
|
||||
`run_existing_window_command` command.
|
||||
|
||||
Simple language integrations use an existing REPL class (see below) without
|
||||
modification. For these integrations, no additional Python code is needed.
|
||||
They use one of the standard REPL classes as the base, as documented below. In
|
||||
most cases, this will be the subprocess based REPL class. An example of such
|
||||
an integration is Lua.
|
||||
|
||||
The menu configuration file `config/Lua/Menu.sublime-menu` contains::
|
||||
|
||||
[
|
||||
{
|
||||
"id": "tools",
|
||||
"children":
|
||||
[{
|
||||
"caption": "SublimeREPL",
|
||||
"mnemonic": "r",
|
||||
"id": "SublimeREPL",
|
||||
"children":
|
||||
[
|
||||
{"command": "repl_open",
|
||||
"caption": "Lua",
|
||||
"id": "repl_lua",
|
||||
"mnemonic": "l",
|
||||
"args": {
|
||||
"type": "subprocess",
|
||||
"encoding": "utf8",
|
||||
"cmd": ["lua", "-i"],
|
||||
"cwd": "$file_path",
|
||||
"external_id": "lua",
|
||||
"syntax": "Packages/Lua/Lua.tmLanguage"
|
||||
}
|
||||
}
|
||||
]
|
||||
}]
|
||||
}
|
||||
]
|
||||
|
||||
This adds a "Lua" menu item to "Tools > SublimeREPL" which creates a Lua REPL
|
||||
via SublimeREPL command `repl_open`. The important part to take note of here
|
||||
is the `id` attribute (`repl_lua`). This is the ID by which the command
|
||||
palette configuration file refers to Lua REPL configuration.
|
||||
|
||||
As you can see, the main way to launch a new REPL is the SublimeREPL command
|
||||
`repl_open` (class :class:`ReplOpenCommand`). The menu configuration file (see
|
||||
above) specifies the arguments for the command that are used to locate the
|
||||
desired REPL class and the settings for it so that it can be spawned.
|
||||
|
||||
The command configuration file `config/Lua/Default.sublime-commands` looks like this::
|
||||
|
||||
[
|
||||
{
|
||||
"caption": "SublimeREPL: Lua",
|
||||
"command": "run_existing_window_command", "args":
|
||||
{
|
||||
/* Note that both these arguments are used to identify the file above and
|
||||
load the REPL configuration from it
|
||||
*/
|
||||
"id": "repl_lua",
|
||||
"file": "config/Lua/Main.sublime-menu"
|
||||
}
|
||||
}
|
||||
]
|
||||
|
||||
It is obvious that the REPL configuration is concentrated in the menu files,
|
||||
and the palette configuration only refers to those by ID and file name. The
|
||||
latter is achieved by the command `run_existing_window_command` (class
|
||||
:class:`RunExistingWindowCommandCommand`)
|
||||
|
||||
This command is a wrapper that is used in the *command palette* configuration.
|
||||
Its function is to execute another command. It takes an ID of a configuration
|
||||
item and the name of a file where the configuration is stored, and scans the
|
||||
available Sublime configuration folders for the file and within the file for
|
||||
the configuration item until one is found. This allows the command palette
|
||||
configuration to specify a reference to the REPL configuration command instead
|
||||
of replicating it. For this reason, actual REPL configuration is *concentrated
|
||||
in the menu files*.
|
||||
|
||||
|
||||
REPL classes
|
||||
^^^^^^^^^^^^
|
||||
|
||||
All REPL instances are descendants of :class:`Repl`. New integrations can
|
||||
either provide their own class, or use one of the base classes that ship with
|
||||
SublimeREPL:
|
||||
|
||||
* Class :class:`SubprocessRepl` for subprocess-based REPLs. The process
|
||||
running in the REPL is a subprocess of the editor. The input and output of
|
||||
the process is connected to the output and the input of the REPL
|
||||
|
||||
* Class :class:`TelnetRepl`. The process runs outside of the editor,
|
||||
presumably having been spawned externally, and the REPL connects to it over
|
||||
TCP via Python `telnetlib`.
|
||||
|
||||
There are three integrations that provide their own classes:
|
||||
|
||||
* Class :class:`PowershellRepl`. This is only used by PowerShell integration.
|
||||
* Class :class:`ExecnetRepl`. This is only used by Execnet Python integration
|
||||
* Class :class:`SublimePythonRepl`. A REPL over SublimeText's internal Python interpreter.
|
||||
|
||||
All these can be found in the plugin's `repl/` subdirectory.
|
||||
|
||||
A REPL class is expected to provide a standard interface for SublimeREPL integration:
|
||||
|
||||
.. py:method:: read_bytes()
|
||||
|
||||
Read and return some bytes from REPL's incoming stream, blocking as
|
||||
necessary. :class:`ReplManager` will set up a separate thread with a
|
||||
:class:`ReplReader` pump that keeps polling this method.
|
||||
|
||||
.. py:method:: write_bytes(bytes)
|
||||
|
||||
Write some bytes to REPL's outgoing stream. User input in the REPL view's
|
||||
command line will be delivered here.
|
||||
|
||||
REPL initialization sequence
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* User interaction causes the execution of `repl_open` command. Its arguments are usually taken
|
||||
from a menu configuration file.
|
||||
* The open() method of ReplManager is called, where a Repl instance and a ReplView instance get created
|
||||
* Within the ReplView constructor, the read and write loops get started. The REPL is now alive.
|
||||
|
||||
REPL manager
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Class :class:`ReplManager` is responsible for managing REPL instances
|
||||
(subclasses of :class:`Repl`). It initializes new REPLs by:
|
||||
|
||||
* Creating REPL instances
|
||||
* Providing an instance of the Sublime view associated with the REPL by reusing an existing one, or creating a new one
|
||||
* Creating and remembering a named :class:`ReplView` instance that couples between the two.
|
||||
|
||||
REPL views
|
||||
^^^^^^^^^^
|
||||
|
||||
A :class:`ReplView` instance is a coupling between a REPL instance and a
|
||||
Sublime view. Its main responsibility is to create Sublime views and maintain
|
||||
the loops that read from, and write to, the REPL.
|
||||
|
||||
* The incoming data *from* the REPL is read in a separate thread using
|
||||
:class:`ReplReader`, because read operations are assumed to be blocking
|
||||
* The outgoing data is written into the REPL by ReplView's method
|
||||
py:method:`update_view_loop`. This method is called by ReplView's constructor
|
||||
at the very end and, as long as the associated REPL object is alive, will reschedule
|
||||
itself with Sublime's py:method:`set_timeout`.
|
||||
|
||||
Reference in New Issue
Block a user