Source

TextButcher / README.rst

Full commit

TextButcher

TextButcher lets you define named search and replace operations and other actions. You can then apply those actions to all selected regions without having to type the patterns, etc. again.

Side effects

This package doesn't alter your Sublime Text settings or behavior in any way. It will only be activated by means of a keybinding you need to define.

TextButcher will create a file with the name regexes.txt under your Packages/User folder if it can't find it.

Getting started

Assign the command textButcher a keybinding (e. g. ctrl+f12) or open from the console by typing view.runCommand("textButcher").

Usage

You can define new actions in the file regexes.txt, typically located under Packages/User. There are a few predefined actions ready to use.

Main menu

>> EDIT ITEMS
Opens the user's regexes.txt file for editing.
<Any option>
Applies the action to every selected region.

How to define actions

Search and replace operations:

name    search_pattern  replace_with    options [comment]

Note: The options field is ignored, but you need to put a placeholder.

Example:

Transform a into e      a       e       XXX     This isn't terribly useful...

Set Sublime options:

Description here.       optionName      value   sublime:        Sets optionName to value

Example:

Description here.       drawWhiteSpace  all     sublime:        Show whitespace always

Extensibility

Filters

TextButcher lets you create text filters as simple python functions. Filters live in python modules somewhere TextButcher can find them (typically, the sublime.packagesPath() + "\\User").

External Commands

In addition to search and replace operations, "modelines" and filters, Text Butcher can interact with other external commands. Currently, it supports Powershell calls through the PowershellUtils package and UberSelection commands through the package of the same name.

Note: You will need to install these two packages separately if you want external commands to work.

Hooking Up Filters And External Commands

You tell Text Butcher which kind of command you want to run in the options field. Let's analyze filters first:

Turn selections to upper case.  myfilters       sels_to_upper   tbf     Does exactly that.

myfilters is the module containing sels_to_upper. sels_to_upper is a python function taking a View as argument. tbf instructs TextButcher to interpret this line as a filter.

This is how a sample filter file would look like:

from textbutcherlib.regionselectors import Sels
from textbutcherlib.textactions import Upper, Transpose
from textbutcherlib.textpipeline import Do

def sels_to_upper(view):
        Do(view, Sels(), Upper())

(Documentation on built-in region selectors, text actions, etc. not available.)

Now we'll take a look at Powershell commands:

curdir  "$pwd"          powershell:     Paste current dir into selection.
mydocs  [environment]::GetFolderPath([environment+specialfolder]::MyDocuments)          powershell:

The key here is to put powershell: in the options field. Only the SEARCH field is required. Note that in the examples above, the REPLACE WITH field is empty.

Lastly, here's how you issue UberSelection commands:

select contiguous       .,/^$/          uberselection:

This command selects all lines from the current one to the next empty line.