Embrace Help

Name:	Embrace
Version:	1.3
Last update:	2020-01-06 09:26:34

This package creates a suite of keybindings and procs operating on the word under the cursor (or just preceding it --- see below for precise specification).
Click here to display the Features Preferences dialog and activate this package.

Introduction

The principal functions are to put the word into any kind of braces, quotes, or tags, or take it out of any kind of braces, quotes, or tags. Each keybinding toggles the braces, quotes, or tags. Other functions are similar to functions already found in Alpha: transform the word to uppercase, lowercase, titlecase, or mixedcase; find another occurrence of it (forwards or backwards), hilite it or delete it.
Which word? If there is a selection the operation applies to the whole selection (somewhat contrary to the main philosophy of the mechanism). The main situation addressed is when there is no selection: then the current word is defined to be the last previous word, counting the start of the word. (So if the cursor is in the middle of a word or at the end of a word, that word is current; if the cursor is at the beginning of a word, or anywhere among punctuation characters or whitespace, then the previous word is current.
All operations are bound to two-step key combinations consisting of Control-B (⌃B) followed by a single key. ('B' might be for 'braces', 'back', or 'balance'... however you want to remember it.)
NOTE: the letter B can be changed to any letter via the preference variable embrace::trigger which can be set in Alpha ↣ Preferences ↣ Package Preferences ↣ Other Packages. In the following instructions we assume the letter B is used.
So for example: Control-B P (⌃B P) means set parentheses around current word. (Except if there are already parentheses around the word: then they are instead removed.)
Click here to temporarily activate this package, and turn this window into a shell to experiment with the key bindings described below.

Key Bindings

All of these follow Control-B

P	parentheses	( )
A	angle brackets	< >
S	square brackets	[ ]
C	curly braces	{ }
Q	single quotes	' '
W	double quotes	" "
G	guillemets	« »
H	reverse guillemets	» «
J	single curly quotes	‘ ’
K	double curly quotes	“ ”
N	back quotes	` `

In latex mode, the quotes are inserted slightly differently, according to latex syntax, so you get for example ``this'' instead of "this".
The operations can also apply to more than one word: this works by pressing an infix key between the Control-B and the characteristic key: For example Control-B 4 P will put parentheses around the previous four words (unless these parentheses already exist, in which case they are removed). The infix keys allowed are 0,1,2,3,... 0 means the entire line. (1 is similar to absence of infix, but it means 'precisely one word, independent of any selection')
Finally there is one more special infix key 'R': for example Control-B R P will remove the innermost parentheses around the current word (even if these parentheses are a bit far away from the word).
All actions are single-stroke undo-able.

Other Operations

All of these are without toggle

L	lowercase
U	uppercase
T	titlecase (all words)
Y	capitalize (only first word)
M	mixedcase

Note that lowercase, uppercase, capitalize, and titlecase admit infix arguments, but mixedcase doesn't: it only operates on the current word.
(mixedcase is very useful in programming modes where you often name your variables and procedures with a happy mixture of lowercase and uppercase letters. If you have a mis-cased word then this operation corrects it! (it simply looks back and copies the casing from the previous occurrence of the variable, assumed to be correct...)

X	extrapolate

This tries to correct a mistyped word by looking around in the text for something similar. Similar means: either two adjacent letters are transposed, or one letter replaced by any other, or one letter added or deleted. For example, if the current word is lapm then possible matches are lamp, lap, lam, and typically only one of the matches will actually exist in the text, hence the usefullness of the mechanism. Note that extrapolate does not admit infix.

Z	zpellcheck
D	delete
F	find next occurrence of word
E	find previous occurrence of word
V	toggle dollar (value of a variable)
B	Show all embrace shortcuts
O	hilite (and select)

Z (spellcheck) does not currently admit infix.

Shortcomings

If at a given word you set two different braces you have to set the outermost braces first. Example: after the word foo if you invoke
```
Control-B P Control-B 2 S
```
then you end up with [word (foo]) --- hardly what you had in mind... You have to do
```
Control-B 2 S Control-B P
```
to achieve proper nesting of braces. Perhaps the programme ought to do a balance check inside the target, and refuse to operate on a target containing non-matched braces --- or better still: see if the braces can be matched by extending the target slightly...
Some of the good keybindings are already taken by exotic sorts of quotes...

Quick reminder

Pressing Control-B B (⌃B B) creates a Dipslay Bindings window with a short summary of all the embrace keybinding combinations.

Advanced users

You can find more information in embrace.tcl.

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 2002-2020, Joachim Kock.
All rights reserved.
The embrace package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Joachim Kock nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JOACHIM KOCK BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.