BBAutoComplete Manual

This manual is also available in BBAutoComplete’s Help menu, as a PDF (277K), and as multi-page online help.


1   Introduction

BBAutoComplete adds word auto-completion to Affrus, BBEdit, Mailsmith, Microsoft Word, Script Debugger, Smile, Tex-Edit Plus, and TextWrangler. You type the start of a word, press a key, and BBAutoComplete types the letters to complete the word. If BBAutoComplete guessed wrong, you can keep pressing the key to cycle through other possible completions. Other auto-completion utilities need to be taught the abbreviations and expansions that you use; BBAutoComplete avoids this hassle by automatically looking for expansions in the program’s open documents. This means that it always suggests completions that are relevant to your current task.

BBAutoComplete is probably most useful for programmers, who need to remember and type long variable and method names, but it can also help with prose writing. It’s useful any time you need to type long words quickly and accurately.

BBEdit 9 and later have a built-in auto-completion feature, however BBAutoComplete is preferable in some ways:

2   Installing and Updating

2.1   Requirements

BBAutoComplete works with macOS 10.7 and later. BBAutoComplete works in the following programs:

If you know AppleScript, you can hook it up to other scriptable text editors. If you do, please send me your glue script, so that I can include it with the BBAutoComplete distribution.

2.2   Installing BBAutoComplete

  1. Drag the BBAutoComplete icon onto the Applications folder.
  2. Double-click the Applications folder to open it.
  3. Double-click the BBAutoComplete icon to launch it.
  4. Eject the BBAutoComplete-1.6 icon.
  5. Now follow the instructions in the Integration Scripts section.

2.3   Updating From a Previous Version

There are two ways to update to the latest version of BBAutoComplete:

Automatic Updating

  1. Launch your old version of BBAutoComplete.
  2. Normally, BBAutoComplete will automatically check for updates and detect that a new version is available. If you had turned that feature off:
    1. Choose Software Update… from the BBAutoComplete menu.
    2. Click the Check Now button.
  3. Click the Download & Install button and follow the on-screen instructions.
  4. Now follow the instructions in the Integration Scripts section.

Manual Updating

  1. Go to the BBAutoComplete Web site and click the Download button.
  2. Quit the BBAutoComplete application.
  3. Replace the old BBAutoComplete application file with the new one. That is, if BBAutoComplete is installed in the Applications folder, drag the new BBAutoComplete application icon into the Applications folder and click Replace when the Finder asks if you want to overwrite the old version. If you get an error saying that you do not have sufficient privileges, drag the old BBAutoComplete to the trash and empty it, and then drag the new one into the Applications folder.
  4. Launch BBAutoComplete.
  5. Now follow the instructions in the Integration Scripts section.

Reinstalling a Fresh Copy

If your copy of BBAutoComplete is damaged, you may need to download and install a fresh copy.

  • If you are able to launch BBAutoComplete, you can ask it to reinstall itself. To do this, follow the Automatic Updating instructions (above) but hold down the Option key when you click the Check Now button.
  • If BBAutoComplete won’t launch, follow the Manual Updating instructions (above).
  • If you’ve uninstalled BBAutoComplete, you can always get it back by going to the BBAutoComplete Web site and clicking the Download button.

2.4   Integration Scripts

BBAutoComplete includes AppleScripts that let you invoke it from inside other programs. To access these scripts, choose Show Scripts from the BBAutoComplete menu. Find the color corresponding to the application that you’re using, e.g. BBEdit 12.

These scripts need to be installed in particular locations so that they show up in the Scripts menus of the aforementioned programs.

The scripts go in the Scripts folder next to the Affrus application. To open this folder, you can choose About The Scripts Menu from Affrus’s Scripts menu, and then click the Open Scripts Folder button.

The scripts go in the folder ~/Library/Application Support/BBEdit/Scripts. You may need to set the trigger keys after installing the scripts.

The script goes in the folder ~/Library/Application Support/Mailsmith/Scripts.
Microsoft Word
Install FastScripts. Put the script in the folder ~/Library/Scripts/Applications/Word/ (creating that folder, if necessary). Then open FastScripts’s preferences and assign the script a keyboard shortcut. Another option is to use Spark instead of FastScripts. Do not use Word’s built-in Word Script Menu Items folder, since the script does not work properly when Word itself runs it.
Script Debugger
The scripts go in the Scripts folder next to the Script Debugger application.
Make sure that you have Smile installed and then run the Installer program in the Smile folder.
Tex-Edit Plus
The scripts go in the Scripts folder next to the Tex-Edit Plus application.
TextWrangler 2–4
The scripts go in the folder ~/Library/Application Support/TextWrangler/Scripts.
TextWrangler 1.5
The scripts go in the folder ~/Library/Application Support/TextWrangler Support/Scripts.

Launch and Quit Scripts

The Launch and Quit Scripts folder contains optional scripts that open BBAutoComplete when you open your editor and quit it when your editor quits.

The Launch BBAutoComplete script goes in BBEdit, Mailsmith, or TextWrangler’s Startup Items folder:

~/Library/Application Support/BBEdit/Startup Items
~/Library/Application Support/Mailsmith/Startup Items
~/Library/Application Support/TextWrangler/Startup Items

The Quit BBAutoComplete script goes in BBEdit, Mailsmith, or TextWrangler’s Shutdown Items folder:

~/Library/Application Support/BBEdit/Shutdown Items
~/Library/Application Support/Mailsmith/Shutdown Items
~/Library/Application Support/TextWrangler/Shutdown Items

It may be necessary for you to create the Startup Items and Shutdown Items folders.

You might find it inconvenient to use these scripts if you use more than one of the programs.

3   Using BBAutoComplete

To use BBAutoComplete, type the first few letters of a long word in one of the supported applications. Then invoke the BBAutoComplete AppleScript from the Scripts menu, or use a keyboard shortcut (Command-/ by default). BBAutoComplete will insert the letters to complete the word. If you aren’t happy with the completion BBAutoComplete chose, invoke the BBAutoComplete AppleScript again. You can do this repeatedly to cycle through possible completions.

The order in which BBAutoComplete suggests completions is deterministic. With a little practice you’ll be able to predict what BBAutoComplete will suggest, and how many completions you’ll need to cycle through to get the one you want. Here are the rules:

Note that this auto-completion algorithm is the same as dabbrev-expand (M-/) in GNU Emacs, except for being case-sensitive. (If you don’t know what Emacs is, stick with BBEdit.)

3.1   Changing the Trigger Key

BBEdit, Mailsmith, TextWrangler
Choose Scripts from the Palettes submenu of the Window menu. Click on BBAutoComplete in the palette that opens, and then click the Set Key… button.
Affrus, Script Debugger
Choose Show Scripts from the Palettes submenu of the Window menu. Click on BBAutoComplete in the palette that opens, and then choose Set Keystroke… from the down-pointing triangle menu opposite from the Edit button.
Microsoft Word, Smile, Tex-Edit Plus
You can change the key by modifying the letters at the end of the script file’s name. For the details of how this works, please consult the documentation for those applications.

3.2   Ignoring Background Windows

By default, BBAutoComplete looks for completions in all of front program’s open text windows. However, background windows containing lots of text will slow down BBAutoComplete. To make BBAutoComplete look for completions in only a single window, use the included BBAutoComplete (Front Only) script instead of the BBAutoComplete script.

3.3   Hiding the Dock Icon

To hide BBAutoComplete’s icon from the Dock and the Command-Tab application switcher, click the special link below:

BBAutoComplete will automatically remember these settings when you update to a new version.

4   Menus

4.1   The BBAutoComplete Menu

4.1.1   About BBAutoComplete

The About BBAutoComplete window shows the credits, as well as download and support information.

You can always download the latest version of BBAutoComplete from the BBAutoComplete Web site.

Questions about BBAutoComplete may be sent to We’re always looking to improve BBAutoComplete, so please feel free to send any feature requests to that address.

To make sure that you have the latest version of BBAutoComplete, you can use the Software Update… command.

4.1.2   Software Update…

Checking for Updates

Click the Check Now button, and BBAutoComplete will tell you whether a newer version is available for download. By default, BBAutoComplete will automatically check for new versions each time it is launched and once per day. You can disable this feature by unchecking the Check for updates automatically checkbox.


If a new version is available, BBAutoComplete will tell you what’s new in that version. Click Download to have BBAutoComplete download the .dmg file for the new version to your downloads folder. Click Download & Install to have it download the .dmg and then update the installed BBAutoComplete application to the new version. For more information, please see Updating From a Previous Version.

Installing a Fresh Copy

You can hold down the Option key when you click Check Now to make BBAutoComplete always download the latest version, even if your version is already up-to-date. This is an easy way to download and re-install a fresh copy of BBAutoComplete if your copy is damaged.


To check for a new version, BBAutoComplete contacts a Web server at over a secure connection. BBAutoComplete transmits the following information to the server: the name of the product (BBAutoComplete) and its version, the version of macOS, the kind of Mac and processor, whether BBAutoComplete has been purchased, and the name of the current language. This information is used to guide future development. No personal information is transmitted.

Mac App Store

If you purchased DropDMG or EagleFiler via the Mac App Store, the Software Update… menu command is not present, and updates are available via the App Store application.

5   Preferences

5.1   Find completions using spell checker

This option causes BBAutoComplete use macOS’s built-in spell checker to find additional completions for the text that you’ve typed, after you’ve cycled through all the completions available in the current window and other open documents. This is useful when the open documents don’t contain much text, and therefore aren’t very useful for suggesting completions. It can also be used to help type words that you aren’t quite sure how to spell. One reason to turn this option off would be if you often cycle through the whole list of completions and want to avoid cycling through a potentially long list of suggestions from the spell checker.

5.2   Use word cache

This option makes BBAutoComplete faster at suggesting completions, at the expense of using additional memory.

5.3   Extra word characters

Depending on the kind of words that you type, you may want to adjust BBAutoComplete’s list of word characters. The effects of doing this can be surprising. For example, if you add . (period) as a word character, and your document contains:


Then you will be able to complete:







On the other hand, if your document contains:


you would not be able to complete:




because BBAutoComplete will see the foo.method as a single word. When . is not a word character, the method is seen as a separate word, and so it can be used for completion.

If you work a lot with HTML, you could add these word characters:


and this will make it easier to complete tags.

6   Legal Stuff

Copyright and Trademarks

BBAutoComplete and this manual are copyright © 2002–2018 by C-Command Software, LLC. All rights reserved.

BBAutoComplete is a trademark of C-Command Software, LLC. Mac is a registered trademark of Apple Computer. All other products mentioned are trademarks of their respective owners.

End User License Agreement


License Grant

“You” means the person or company who is being licensed to use the Software or Documentation. “We,” “us” and “our” means C-Command Software, LLC.

We hereby grant you a nonexclusive license to use one copy of the Software on any single computer, or on multiple computers only used by a single person. The Software is “in use” on a computer when it is loaded into temporary memory (RAM) or installed into the permanent memory of a computer—for example, a hard disk or other storage device.


We remain the owner of all right, title and interest in the Software and related explanatory written materials (“Documentation”).

Archival or Backup Copies

You may copy the Software for backup and archival purposes, provided that the original and each copy is kept in your possession and that your installation and use of the Software does not exceed that allowed in the “License Grant” section above.

Things You May Not Do

The Software and Documentation are protected by United States copyright laws and international treaties. You must treat the Software and Documentation like any other copyrighted material—for example, a book. You may not:


You may transfer all your rights to use the Software and Documentation to another person or legal entity provided you transfer this Agreement, the Software and Documentation, including all copies, updates and prior versions to such person or entity and that you retain no copies, including copies stored on computer.

Limited Warranty

The software is provided “as is,” without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. No employee, agent, dealer or distributor of ours is authorized to modify this limited warranty, nor to make any additional warranties.

Term and Termination

This license agreement takes effect upon your use of the software and remains effective until terminated. You may terminate it at any time by destroying all copies of the Software and Documentation in your possession. It will also automatically terminate if you fail to comply with any term or condition of this license agreement. You agree on termination of this license to destroy all copies of the Software and Documentation in your possession.

General Provisions

  1. This written license agreement is the exclusive agreement between you and us concerning the Software and Documentation and supersedes any prior purchase order, communication, advertising or representation concerning the Software.
  2. This license agreement may be modified only by a writing signed by you and us.
  3. This license agreement is governed by the laws of the State of New Hampshire.
  4. You agree that the Software will not be shipped, transferred or exported into any country or used in any manner prohibited by the United States Export Administration Act or any other export laws, restrictions or regulations.


The following open-source components are used in BBAutoComplete:

7   Version History

1.6—September 4, 2018
  • BBAutoComplete now supports Dark Mode on macOS 10.14.
  • Added support for Hiding the Dock Icon.
  • Fixed a bug where BBEdit 12 would report an error if you invoked BBAutoComplete while a palette was open.
  • Improved the Extra word characters and Requirements sections of the manual.
  • The new Save Diagnostic Report… command in the Help menu provides an easier way of recording error logs and other information to send to technical support.
  • Made various code modernizations.
  • Renamed “Mac OS X” to “macOS” throughout the app and documentation.
  • Removed the embedded Growl framework, as it was not used.
  • The Software Update… feature and crash reporter now use HTTPS.
  • Documentation and Help menu links to now use https instead of http.
  • Worked around a badly worded OS certificate error when checking for a software update.
  • Improved the error reporting for the Software Update… command.
  • Added support for App Transport Security.
  • Fixed a bug where Software Update… would continue offering updates in the same session in which you had held down the Option key.
  • Increased the font size in the Software Update… window.
  • Added accessibility label in the Software Update window.
  • The Software Update… feature and crash reporter now use HTTPS.
  • Worked around a macOS bug that could cause a crash during Software Update….
  • The About, Software Update, and help windows now use the San Francisco font on Mac OS X 10.11.
  • The About BBAutoComplete window now uses the system language names.
  • Fixed the size of the distribution disk image window.
  • Worked around a Finder bug that could cause the disk image’s icons to be misaligned if the AppleShowAllFiles option was enabled.
  • The distribution disk image is now signed for Gatekeeper.
  • BBAutoComplete now requires macOS 10.7 or later. Versions of BBAutoComplete for macOS 10.6 and earlier are available.
1.5.5—November 19, 2014
  • Revised the instructions for Microsoft Word to recommend running the script using FastScripts because that seems to work around a bug in Word 2011.
  • Clarified the locations of script folders.
  • Modernized lots of code and removed old code that’s no longer needed for compatibility with legacy OS versions.
  • BBAutoComplete is better at repairing folder ownership and permissions.
  • Updated the Gatekeeper signature format.
  • The Software Update… feature is better at explaining what you can do if installation fails.
  • Improved error reporting when BBAutoComplete can’t connect to the update server.
  • Worked around a bug in Mac OS X 10.10 that could cause BBAutoComplete to freeze at launch.
  • Improved the error reporting.
  • Updated the disk image icon for Mac OS X 10.10.
  • The disk image is now optimized for Retina displays.
  • Adjusted the font sizes in the PDF manual.
  • Fixed a bug where the release notes in the Software Update… window were shown in the wrong font.
  • Fixed a bug were BBAutoComplete could crash if Microsoft Word returned invalid information about the selection.
  • BBAutoComplete now requires Mac OS X 10.6.8 or later. Versions of BBAutoComplete for Mac OS X 10.5 and earlier are available.
1.5.4—April 25, 2012
  • Added support for TextWrangler 4. Also, completion now works in TextWrangler search results browser windows.
  • BBAutoComplete now has an automatic keyboard shortcut in Microsoft Word 2011. (Previous versions of Word need FastScripts to assign a shortcut.)
  • BBAutoComplete now runs as 64-bit under Mac OS X 10.6 and later, which should make it launch faster.
  • BBAutoComplete is now code-signed using a Developer ID certificate for Gatekeeper.
  • Modernized the Software Update window and code.
  • Made various improvements to the documentation.
  • Updated the disk image and Apple Help layouts.
1.5.3—September 12, 2008
  • When using BBEdit 9, auto-completion now works in disk browser, project, and search results windows.
  • BBAutoComplete now requires Mac OS X 10.4 or later.
1.5.2—January 9, 2008
  • Fixed bug where BBAutoComplete was needlessly logging to the console.
  • The software updater is better at handling invalid downloads folders.
1.5.1—November 14, 2007
  • Fixed bug where the Apple Help didn’t work on Mac OS X 10.5.
  • Fixed bug where the Software Update… checker didn’t always re-check for new updates.
  • The Software Update… feature now checks whether the updated version can run on your installed version of Mac OS X.
  • Modernized the crash reporter code.
  • Fixed help book icon.
1.5—February 7, 2007
  • BBAutoComplete now requires Mac OS X 10.3 or later.
  • Now works with Microsoft Word.
  • Added Find completions using spell checker option. This is useful when the open documents don’t contain much text, and therefore aren’t very useful for suggesting completions. It can also be used to help type words that you aren’t quite sure how to spell.
  • Can now find completions in BBEdit and TextWrangler results browser windows.
  • Rewrote the Software Update… feature. When a new version is available, it can now show you the release notes. BBAutoComplete now downloads the new version itself, rather than relying on your browser. The Download & Install button will cause BBAutoComplete to auto-update itself to the latest version. Also, the software update checker now works behind HTTP proxies.
  • Added keyboard shortcut for Hide Others.
  • Improved compatibility with pre-release versions of Mac OS X 10.5.
  • Added Danish localization.
1.4.2—January 25, 2006
  • BBAutoComplete is now a universal binary.
  • Can now look for completions in the preview panes of BBEdit and TextWrangler disk browsers.
  • If Path Finder is running, the Show Scripts command reveals the scripts using it instead of the Finder.
  • The Software Update alert is now a sheet, so it won’t interfere with auto-completion.
  • Improved scaling of the icon.
1.4.1—February 7, 2005
  • Now supports TextWrangler 2.0’s documents drawer.
  • The Front Only Smile script now works with European keyboards.
  • Added example of changing the word characters.
1.4—January 10, 2005
  • Now works with Smile.
  • Fixed bug where BBAutoComplete sometimes didn’t realize that the front window’s text had changed, and so it returned the wrong completion.
1.3—September 21, 2004
  • Now works with Affrus.
  • In BBEdit 8, now supports shell worksheets and multiple documents in the same window.
  • The AppleScripts are now packaged inside the application; they can be accessed using the Show Scripts command in the BBAutoComplete menu.
  • Added software update checker and crash reporter.
  • Added Close All Windows and Minimize All Windows commands.
  • Now requires Mac OS X 10.2 or later.
1.2—August 13, 2003
  • Now works with Script Debugger, Tex-Edit Plus, and TextWrangler.
  • Added new icon.
  • Refined and updated the interface.
  • Added Apple Help.
  • Fixed bug in Mailsmith script.
  • The Quit script no longer cancels logout.
1.1.2—March 26, 2002
  • Now works with Mailsmith 1.5.
1.1.1—March 18, 2002
  • Removed profiling code, so no longer creates gmon.out files at root of the boot volume.
1.1—March 16, 2002
  • Parsing words is between 20 and 70 times faster than in 1.0.1 (for an 80KB window), with greater improvements on low-memory systems.
  • The new word cache further speeds processing.
  • BBAutoComplete can optionally ignore background BBEdit windows.
  • Includes an Open BBAutoComplete script for BBEdit’s Startup Items folder.
1.0.1—February 27, 2002
  • The Quit AppleScript is saved as an application now—so it works.
1.0—February 26, 2002
  • First public release.