README.md

Welcome to Emacs Pro Essentials (formerly Sublemacspo)

We are huge fans of Emacs and Sublime Text. Our motivation for this project has been to bring the right amount of the Emacs experience to Sublime, while also recognizing that Sublime has some excellent ideas of its own. We appreciate the careful thought the Emacs creator put into such basic things as cursor motion, kill and mark rings, incremental search, etc. However, Sublime brings with it an extremely powerful multi-cursor concept and others which are worth embracing as well. Here we have produced a careful implementation of Emacs semantics and enhanced them with modern Sublime concepts where possible and appropriate.

Key Features Overview

• Navigation and Kill Commands for Characters/Words/Lines/S-Expressions with Multi-cursor Support
• Universal, Numeric, and Negative Argument Handling
• Kill Ring with Multi-cursor and Sublime Quick Panel Support
• Mark Ring with Multi-cursor Support
• Incremental Search with History (regular and regex supported) and Multi-cursor Features
• Frame (Window) and Window (Window Pane) Commands
• Switch to Buffer (View), Kill the Oldest Buffers, and Pinned Tabs Commands
• Change Case Commands (upper/lower/title/camelCase/under_score supported)
• Zap/Jump to Char and String with Multi-cursor Support
• Rectangle and Text/Point Register Commands (not Multi-cursor aware yet)
• All Buffers (Views) Auto Complete

The hope is that when you fire up this plugin, your fingers will find many of the key bindings and associated behavior completely familiar. We've implemented the universal argument concept (ctrl+u and meta-Digit), and made all the character, word, line and s-expression commands behave very close to the original Emacs. The ctrl+k command is identical to Emacs in almost every way, except it now includes a powerful multi-cursor implementation that makes sense. Incremental search also is very familiar, except it has additional features for keeping or skipping matches along the way, so that when you're done the "kept matches" are available as multi-cursors for further editing.

Everything else is still Sublime and all that that implies: silky smooth performance, great built-in automatic function tagging, great single-file/multi-language support, and so on.

See below for details.

Installation

To install Emacs Pro Essentials you have to install [Package Control] (http://wbond.net/sublime_packages/package_control) as an automatic package manager for Sublime Text. Now, you can easily install Emacs Pro Essentials and your installation will never be outdated. After you install Package Control, hit [CMD]-Shift P on Mac or [Ctrl]-Shift P on Windows\Linux to open up the command palette and type install. Now select Package Control: Install Package. This will load all packages from the remote repository and you can select Emacs Pro Essentials from the drop-down list.

Sublime Text 2 and 3 Support

The main development for Emacs Pro Essentials is now Sublime Text 3 only. There is still the branch using the earlier codebase for ST2 but it honestly doesn't have most of the features mentioned.

https://github.com/sublime-emacs/sublemacspro/tree/st2

Features and Key Bindings

The following features have largely been implemented from scratch and are only supported with Sublime Text 3. For the bindings below, meta is the alt key on Windows/Linux or the option key on the Mac. super is the Command key on the Mac.

Emacs-style Universal, Numeric, and Negative Argument Handling

• ctrl+u: Emacs universal argument command (so 4^n where n is the number of times ctrl+u has been pressed) E.g., ctrl+u ctrl+u ctrl+f means go forward 16 characters.
• meta+0 ... meta+9: Emacs numeric arguments - you provide a prefix using the numeric arguments before a command to run it that many times. E.g., meta+2 meta+3 ctrl+f means go forward 23 characters.
• meta+-: Emacs negative argument command - reverses the direction of the command. E.g., meta+- meta+2 meta+3 ctrl+f means go backward 23 characters.

Emacs-style Kill Ring with Multi-cursor Support and Sublime Quick Panel Selection

• Commands that utilize the kill ring
  • ctrl+w and meta+w: Kill (cut) and copy onto the kill ring.
  • ctrl+y: Yank (Paste) from the last entry put into the kill ring.
  • meta+y and shift+meta+y: Yank-pop forward and backward from the kill ring, and requires a yank command before running either one as with Emacs.
  • ctrl+k: Kill to the end of line.
    • Mimics emacs almost exactly, killing lines and adding into the kill ring. With a numeric argument, delete that many lines (which is different from typing ctrl+k that many times). Zero and negative numeric arguments also behave as expected.
  • ctrl+meta+k: Delete S-Expression and place onto the kill ring.
    • Can pass in a direction argument set to -1 to delete backward.
  • meta+d and meta+backspace: Kill word forward and backward and add to the kill ring.
  • ctrl+x ctrl+y: Displays a Sublime quick panel menu of all the kills and allows you to choose which one to yank. If you supply a numeric argument, that means yank all the cursors into new cursors. (See below)
• Kill ring implementation details
  • 64 entries by default, but settable with sbp_kill_ring_size setting in the sublemacspro .sublime-settings file.
  • Consecutive kill commands (meta+d,ctrl+k, etc.) are appended to the same entry on the kill ring so they can be yanked back as once.
  • The yank command will pull from the system clipboard if it finds it is not the same as the current kill-ring entry. This means you can go into a different application and copy something there. Then, paste it into Sublime using ctrl+y.
  • Anything you kill in Sublime will be placed on the clipboard for other apps to access. If a kill ring entry has multiple cursors, just the first cursor is placed on the clipboard.
• Multi-cursor support
  • If you had multiple cursors while appending to the kill ring, the kill entry will contain and remember those separate cursors. If you try to yank multiple cursors, it will work as expected if you still have the same number of cursors. If you have more cursors than your kill, the kill will be repeated until you have enough. If you have fewer cursors than your kill, it will use just as many as it needs.
  • If you know you want to yank all the cursors, there's a new command which will automatically create the number of cursors you need for the kill ring entry just before it performs the yank. This is useful if you currently have just 1 cursor but want back all the data from a previous multi-cursor kill command. This new command is called Yank All Cursors. Furthermore, when you supply a numeric argument to the ctrl+x ctrl+y command, it will let you choose which item to yank all cursors for. And now the choose command shows you which entries have more than one cursor.

Emacs-style Mark Ring with Multi-cursor Support

• Commands that utilize the mark ring
  • ctrl+space: Push a new mark onto the mark ring
  • ctrl+x ctrl+x: Switch point and mark
  • ctrl+space ctrl+space: Push a new mark and activate the mark, which means highlight it as a selection. It will stay highlighted until ctrl+g is pressed or certain commands are executed.
  • ctrl+u ctrl+x ctrl+x: Toggles the current state of the mark to see the current mark selection region. This will highlight the current mark region (activate the mark) if it isn't highlighted or remove the highlighting (deactivate the mark) if it is highlighted.
    • Suggested additional binding for this: {"keys": ["ctrl+m"], "command": "sbp_swap_point_and_mark", "args": {"toggle_active_mark_mode": true}},
  • ctrl+u ctrl+space: This moves point to where the current mark is, but then rotates the mark ring so that the NEW current mark is the previous one on the ring. This allows you to move back through the mark history. Some marks are multi-cursors and they will be handled in exactly the same way.
• Mark ring implementation details
  • ctrl+y sets the mark automatically as it does (and must for meta+y to work properly) in emacs.
  • Commands like meta+< and meta+> also set the mark automatically.
  • If you use the mouse to make a selection, it will set the mark at the beginning of your selection point will be at the end, thus your emacs region and selection will be the same.
• Multi-cursor support
  • You can set the mark with multiple cursors and pop off the mark ring to marks with multiple cursors. Furthermore, you can kill and copy using those cursors, and then yank them later as well.
  • All the above commands for manipulating the mark ring (and kill ring) will continue to work with multiple cursors.

Emacs-style Incremental Search with History (regular and regex supported)

• Commands to initiate a search
  • ctrl+s and ctrl+r: Initiate a forward or backward search.
  • ctrl+u ctrl+s and ctrl+u ctrl+r: Initiate a forward or backward regex search.
  • ctrl+s ctrl+s and ctrl+r ctrl+r: Initiate a forward or backward search using the same search string as the last search.
    • This can be used with a regex search as well.
• Commands during an incremental search
  • ctrl+s: Move to next match.
  • ctrl+r: Move to previous match.
  • meta+d: Keep current match as a future cursor and move to next.
  • ctrl+w: The characters in front of your cursor are appended to your search string.
  • meta+a: Keep all remaining matches from your current position to the end of the file (or beginning if you're doing a reverse search). Kept matches are are saved as future cursors when isearch is done.
    • Pressing a second meta+a will wraparound, selecting all the matches in the whole file.
  • backspace: Move backward in the search history (undo).
    • Will undo any of the above commands moving backwards in the commands run during the search one at a time. For example, it will go back to a previous match, delete a character from your search string, or remove the last kept match.
    • When undoing a ctrl+w append from cursor command, the entire set of characters are removed at once. However, if you use shift+backspace instead, it will remove just one character at a time.
  • ctrl+g: If your search is currently failing, takes you back to the last point your search was succeeding. When your search is succeeding, the search is aborted and you go back to the start.
  • up: Access previous history in the search history.
  • down: Access next history in the search history.
  • enter: End your search with all the kept items as multi-cursors.
• Incremental search implementation details
  • If you type any uppercase characters in your search, the search automatically becomes case-sensitive.
  • You can end your search by typing any regular emacs commands as well, e.g., ctrl+a, meta+f, ctrl+l, meta+<, meta+>, ctrl+f, ctrl+n, etc.... The kept items will be intact as multi-cursors.
  • When you complete (as opposed to abort) a search, your mark is set to where you started the search from.
  • I-search has support for remembering previous searches. You can access previous searches with the up and down arrow keys after you initiate a search.
• Find and Replace
  • meta+r: Not implemented in Emacs Pro Essentials so this brings up the default find and replace of sublime text.
• Increased Efficiencies
  • If you use alt for the meta binding, then setting alt+s to move to next match and alt+r to move to previous match with alt+d already set to keep match can make moving through iSearch quicker when selecting matches.
  • Example binding for alt+r is below (for alt+s set forward to true: {"keys": ["alt+r"], "command": "sbp_inc_search", "args": {"cmd": "next", "keep": false, "forward": false}, "context": [ {"key": "i_search_active"}, {"key": "panel_has_focus"} ] },

Emacs Frame (Window), Window (Window Pane), and Buffer (View) Commands

• Frame (Window) Commands
  • ctrl+x 5 2: Open a new frame (Window).
  • ctrl+x 5 0: Close the current frame (Window).
• Window Pane Commands
  • ctrl+x 1: Remove all other window panes except this one
  • ctrl+x 2: Split window pane vertically
  • ctrl+x 3: Split window pane horizontally
  • ctrl+x d: Delete current window pane
  • ctrl+x o: Go to next window pane.
  • ctrl+x n: Go to next window pane.
  • ctrl+x p: Go to previous window pane.
  • super+shift+[: Go to previous tab in this window pane (wraps around at edges).
  • super+shift+]: Go to next tab in this window pane (wraps around at edges).
  • ctrl+x ^ or ctrl+shift+i: Make selected window pane taller.
  • ctrl+x - or ctrl+shift+k: Make selected window pane wider.
  • ctrl+x } or ctrl+shift+j: Make selected window pane narrower.
  • ctrl+x { or ctrl+shift+l: Make selected window pane shorter.
    • Resize window pane commands accept universal, numeric, and negative arguments so meta+5 ctrl+x ^ will make the selected window taller by 5 times.
• View Commands
  • ctrl+x k: Delete current view from this window pane.
  • ctrl+x K: Delete most stale n views, that is, the views that haven't been touched in the longest time (supports numeric argument input).
    • n is set by default to 5. This can be changed by overriding the binding in your user bindings file by changing the argument n_windows. If the value is null or not specified, the numeric argument will be used to determine how many to close. The default binding is: {"keys": ["ctrl+x", "K"], "command": "sbp_close_stale_views", "args": {"n_windows": 5}}
  • ctrl+x P: Pin tab. A pinned tab will never be automatically closed by the ctrl+x K command. A small pin icon (by default) will appear in the status area, settable the sbp_pinned_tab_status_text variable.
  • ctrl+x b: Go to next view (keeps scrolling through all the views (tabs to the right in each window pane) and ignores window pane boundaries going into the next pane when it reaches the last view on the right).
  • ctrl+x right: Go to next view (set to the same command as ctrl+x b above).
  • ctrl+x left: Go to previous view (keeps scrolling through all the views (tabs to the left in each window pane) and ignores window pane boundaries going into the next pane when it reaches the last view on the left).

Switch to View (Buffer)

• Commands
  • ctrl+x ctrl+b: Switch to a view (buffer) using the quick panel for selection.
• Implementation Details
  • Sorted by last used time and skips past the current view in the quick panel to the second most recent view.
  • Optional arguments with the default values are completion_components=2 and display_components=1.
    • The default configuration displays the view's file name and parent directory (the last 2 components of the file path) on the top line and just the last component of the file name on the second line. The completion is performed on the first line. If you set the value of display_components to 0, the second line will be omitted entirely.
  • If creating your own key bindings has optional argument current_group_only, default is false, but when set to true will only use the current window pane for the switch to view.

Go to File or Symbol

• ctrl+x ctrl+f: Go to file in a quick panel as implemented by Sublime.
• ctrl+meta+g: Go to symbol in the quick panel as implemented by Sublime.

Change Case Commands

• meta+c, meta+l, meta+u: capitalize, lower case, upper case words using the sbp_change_case command. They support emacs-style numeric arguments, including negative arguments which means "do it to the previous N words".
  • Accepts two arguments direction (1 is forward and -1 is backward) and mode (can be title, upper, or lower).
• ctrl+x ctrl+u and ctrl+x ctrl+l: upper case and lower case the highlighted region/s or the emacs region/s if nothing is highlighted.
  • This use the same sbp_change_case command as above with the use_region argument set to true, therefor, no direction argument is needed.
• ctrl+x ctrl+meta+c, ctrl+x ctrl+meta+u: Convert from Underscores to camelCase and vice versa. They operate on highlighted region/s or emacs region/s as ctrl+x ctrl+u above and use the same sbp_change_case command setting the mode to camel or underscore.

Zap/Jump to Char and String

• Zap and Jump Commands
  • meta+z: Zap-to-char, delete from current point to the next occurrence of a character and includes deleting the character.
  • shift+meta+z zap-up-to-char, delete from current point up to but not including the next occurrence of a character.
  • ctrl+x z zap-to-string, delete from current point until next occurrence of the string and includes deleting the string.
  • ctrl+x Z zap-up-to-string, delete from current point up to but not including the next occurrence of the string.
  • ctrl+x j c jump-to-char, move past the next occurrence of a character.
  • ctrl+x j C jump-up-to-char, move up to the next occurrence of a character.
  • ctrl+x j s jump-to-string, move past next occurrence of a string.
  • ctrl+x j S jump-up-to-string, move up to the next occurrence of a string.
• Implementation Details
  • The char jump and zap commands have an optional argument include_char that is set to true by default.
  • The string jump and zap commands have an optional argument include_string that is set to true by default.

Rectangle and Text/Point Register Commands (not Multi-cursor aware)

• Text and Point Register Commands
  • C-x r s [register]: Store the current emacs region or highlighted region into the register.
  • C-x r i [register]: Insert the selected register at the current cursor position.
  • C-x r space [register]: Store the current point into a register.
  • C-x r j [register]: Jump to the stored point in the selected register.
  • [register] can be set as 'a-z/0-9/A-Z'.
  • C-x r r: Choose a text register to insert from the sublime quick panel menu.
  • C-x r p: Choose a point register to jump to from the sublime quick panel menu.
• Rectangle Commands
  • C-x r t: Rectangular cut (as in emacs).
  • C-x r d: Rectangular insert (as in emacs).

Emacs Navigation Commands

• Word Level
  • meta+f and meta+b: Forward and backward words with the same exact behavior of emacs in terms of how you move.
  • ctrl+meta+f and ctrl+meta+b: Forward and backward movement over s-expressions. It works for skipping over identifiers, strings, parentheses, braces, square brackets, etc...
    • DEPENDENCY NOTE: S-expression checks if Bracket Highlighter is installed, which enables it to perform much better movement over s-expressions that are language dependent.
    • If Bracket Highlighter isn't installed, the s-expression falls back to default movement over the modifiers in sbp_sexpr_separators setting in the sublemacspro .sublime-settings file, but this performs much worse than the updated implementation.
• Line Level
  • ctrl+n: Move down a line.
  • ctrl+p: Move up a line.
  • ctrl+a: Go to beginning of line (ignores wrapped lines always goes to very beginning).
  • meta+m: Go back to the indentation at the beginning of the line (same as ctrl+a except moves back to the indentation instead of the very start of the line).
  • ctrl+e: Go to end of line (ignores wrapped lines always goes to very end).
  • meta+a: Go back to soft beginning of the line (doesn't ignore wrapped lines).
• Paragraph Level
  • ctrl+meta+] and ctrl+meta+[: Navigate forward and backward paragraphs.
• Page Level
  • meta+, and meta+.: Move to beginning and end of the current window view, respectively.
    • This command allows an optional argument always_push_mark which by default is set to true and will push the mark before going to the beginning or end of the current window view.
  • ctrl+v: Page down.
  • meta+v: Page up.
  • ctrl+l: Center current line in view.
    • Used with numeric arguments, put the current line at the Nth line in the view (E.g. meta+5 ctrl+l moves the current line to the 5th line in the view.
• File Level
  • meta+< and meta+>: Move to beginning and end of file, respectively.
  • meta+g also bound to ctrl+x g: Goto line via numeric argument or via quick panel entry if entered without a numeric argument.
    • Numeric argument e.g., meta+4 meta+3 meta+5 meta+g goes to line 435.

All View Auto Complete

• Similar to All Autocomplete plugin but fixed two issues with that plugin: the limit of 20 views to search and completions not being found due to errors in some syntax definitions.
• Disabled by default.
• Enable by setting sbp_use_internal_complete_all_buffers to true in the sublemacspro.sublime-settings file.

Miscellaneous Commands

• Undo/Redo
  • ctrl+backslash: Undo.
  • ctrl+_: Undo.
  • ctrl+x u: Undo.
  • ctrl+shift+/: Redo.
  • ctrl+shift+backslash: Redo.
• Save
  • ctrl+x, ctrl+s: Save this file.
  • ctrl+x, ctrl+m: Save all files.
  • ctrl+x, s: Save all files.
  • ctrl+x, ctrl+w: Prompt for writing a new file to disk (Save As...).
• Selection
  • ctrl+x h: Select All (works like emacs: setting a mark at the bottom and going to the top of the file)
• Deletion
  • ctrl+d: Right delete.
  • backspace: Left delete.
• Wrap Lines
  • meta+j: Wrap lines using sublime built in function to 100 characters.
• Indent/Unindent
  • ctrl+c, >: Indent.
  • ctrl+c, <: Unindent.
  • meta+i: Insert tab character at cursor ("\t").
• Macros
  • ctrl+x, (: Toggle macro recording.
  • ctrl+x, ): Toggle macro recording.
  • ctrl+x, e: Execute recorded macro.
• Exit
  • ctrl+x, ctrl+c: Save this file.
• Shift Indentation of Regions
  • meta+]: Shift active mark region or current highlighted region to the right one indentation.
  • meta+[: Shift active mark region or current highlighted region to the left one indentation.
• White Space Removal
  • meta+backslash: Delete white space around point (supports numeric arguments). If keep_spaces is > 0, it will leave at that many spaces instead of deleting all the white space. If a numeric argument is supplied, it overrides the keep_spaces argument.
  • ctrl+x ctrl+o: Delete blank lines around point.
• Auto Complete
  • meta+/: Brings up Sublime's Auto Complete window.
  • meta+h: Brings up Sublime's Auto Complete window.
• Find and Replace
  • meta+r: Not implemented so brings up default find and replace of sublime.

Important Settings File Options

Kill Ring Size

• Settable by sbp_kill_ring_size.

Use Alt Bindings (as well as meta+ for digits) or Super (Command on Mac) Bindings

• Default is sbp_use_alt_bindings set to true and sbp_use_super_bindings to false.
  • If you prefer to use super bindings then swap these or if you prefer to have both super and alt bindings then set both to true.
• To insert digits as their normal characters instead of using Emacs-style numeric arguments, change sbp_alt+digit_inserts to true.

Trim Trailing White Space and Ensure New Line at End of File

• Optional settings that if set to true in the sublemacspro.sublime-settings will occur on saving a file.

All View Auto Complete

• Set sbp_use_internal_complete_all_buffers to true.

Known Bugs/Issues

• If you're running an incremental search and you invoke another command that opens the overlay, such as "Goto Anything..." or "Command Palette...", the search can get into a weird state and interfere with the overlay. To deal with that, we override the default key bindings for those commands and handle them properly. If you have your own bindings for those commands, you should copy these examples:

  {"keys": ["super+shift+p"], "command": "sbp_inc_search_escape",
      "args": {"next_cmd": "show_overlay", "next_args": {"overlay": "command_palette"}},
      "context": [ {"key": "i_search_active"}, {"key": "panel_has_focus"} ]
  },
  {"keys": ["super+t"], "command": "sbp_inc_search_escape",
      "args": {"next_cmd": "show_overlay", "next_args": {"overlay": "goto", "show_files": true}},
      "context": [ {"key": "i_search_active"}, {"key": "panel_has_focus"} ]
  },

Future

We will try to extend this more and more to provide more features from Emacs to Sublime Text, and make this a fast and beautiful Emacs replacement.

Possible Future Package Additions

• Supplying a numeric argument to ctrl+d and Backspace should append to the kill ring.
• Turn the last n marks into multiple cursors.
• Switch to view works across windows (frames) and not just within a single window.
• Make the registers work with multi-cursors.
• Emacs marking of textual objects
• Quick Panel selection to scroll through the mark ring and pop a previous mark like choose and yank command for the kill ring.

Authors and Contributors

2012-2017 Jonathan Payne (@canoeberry), Jeff Spencer (@excetara2), Martin Grund (@grundprinzip), Brian M. Clapper (@bmc)

• @dustym - focus groups
• @phildopus - for goto-open-file
• @aflc - toggle comment improvements
• @jinschoi - ST3 bugfix
• @mcdonc - inspiration for more Emacs key bindings