Emacs text-categories package

When debugging code, it is not unusual to insert print statements and other temporary code in the program to locate the bugs. After locating all of them, it is impossible to undo or revert just the code used for debugging because it will revert the bug corrections too. This package defines a text category for inserted text. All text inserted belongs to text category “0” by default. It is possible to instruct the package to change the text category to any string. Everything inserted from that moment and after will belong to the new text category. A category can be deleted leaving only the characters belonging to all the other active categories or stored for later use. When saving the current buffer on a file, the default behaviour is to create a helper file containing the text categories of characters in the buffer. When enabling text categories in a buffer that has such a file in that directory, it loads the text categories (and the stored ones, see text-categories-store-restore) of characters from the file in stead of setting them to the default one.

Usage example

A very general usage example can be seen in this gif. Debug words represent the extra debugging code added to locate the bugs which we want to get rid of later. Since debug code is spread across all the program we cannot just revert the changes or use region undo with one move. But we wrote all debug code in text category 1 so we can delete it with one hotkey.

Package reference

Below there is a listing of the commands provided by this package and their purpose.

• text-categories: Toggles text categories (enabled-disabled) in the current buffer.
• text-categories-change: Changes the active category to a new one with any string as a name. Calling it when text-categories are not active causes them to activate.
• text-categories-delete: Deletes every character belonging to a category given by the user.
• text-categories-reset: Sets the category to be the default one. The package holds the default category in the variable text-categories-default and its default value is “0”. The user can change the value of this variable to have a different default category.
• text-categories-report: Prints the current active category and all the categories existing in the current buffer.
• text-categories-visualize: Shows the contents of the current buffer in a new buffer with each character highlighted according to its category.
• text-categories-change-region-category: Changes the category of each character in the selected region to the one the user inputs.
• text-categories-toggle-hidden: Toggles the visibility of characters belonging to a certain category.
• text-categories-store-restore: Asks for a category from the user. If characters of that category exist in the current buffer, it deletes them but stores their positions in memory. The user cannot change the category to be one that is stored from then on. If this function is called and the category given by the user is already stored, it restores it inserting all the caracters belonging to it to their original position. Note that this position will be updated according to the insertions and deletions the user makes while a category is stored. After a category is restored, the user can select it again as normal.
• text-categories-cycle-line: Changes the category of all characters in the current line to the next one in the text-categories-default-cycle list. If not all characters have the same category in the current line or their category doesn’t belong to the text-categories-default-cycle, the category selected is the first item of text-categories-default-cycle.

Below there is a listing of important variables that the user can customize in this package and their purpose.

• text-categories-default: Holds the default category. When enabling text categories in a buffer, this will be the category of all characters in the buffer.
• text-categories-file-prefix: Holds the prefix of the helper file created when killing a buffer with text categories enabled in it. When loading a file and the helper file exists in the same directory, text categories are enabled and loaded from the helper file. This is not the default behaviour but can be achieved by calling text-categories-enable-on-find-file after loading the package. In the default behaviour the categories saved in the helper file can be loaded simply by enabling typing categories after a file is opened in its buffer.
• text-categories-viz-prefix: The visualization buffer prefix.
• text-categories-default-cycle: List holding the categories to cycle through on a line when text-categories-cycle-line is called.
• text-categories-save: When this variable is t, killing the current buffer results in creating a helper file holding the categories assigned to characters at that time. This can be disabled by setting this variable to nil.
• text-categories-colorwheel: List of colors used in the visualization buffer. The visualization process will cycle through them for each category so if more categories than colors in this variable exist, some categories will have the same color.

The visualisation buffer

The visualisation buffer depicts the categories present in the original buffer. It has text-categories-viz-mode as its major mode and defines the following keybindings by default:

• n: Go to the next occurence (ignoring adjacent characters) of the same category as the one where the cursor is now.
• p: Go to the previous occurence (ignoring adjacent characters) of the same category as the one where the cursor is now.
• m: Mark all the adjacent to the point characters that have the same category as the one where the cursor is now.
• u: Update the category of the active region.
• RET: Go to the original buffer at the same point.

Installation

This package is available through MELPA.

It can be installed with M-x package-install text-categories.

And then requiring it with:

	(require 'text-categories)

An example of setting the keybindings:

	;; toggle text category mode
	(global-set-key (kbd "C-c t t") 'text-categories)
	;; change text category
	(global-set-key (kbd "C-c t c") 'text-categories-change)
	;; delete characters belonging to a text category
	(global-set-key (kbd "C-c t d") 'text-categories-delete)
	;; set the text category to the default one
	(global-set-key (kbd "C-c t r") 'text-categories-reset)
	;; report the current text category
	(global-set-key (kbd "C-c t p") 'text-categories-report)
	;; visualize categories in buffer
	(global-set-key (kbd "C-c t v") 'text-categories-visualize)
	;; change the category of the marked region
	(global-set-key (kbd "C-c t u") 'text-categories-change-region-category)
	;; toggle the visibility of a certain category
	(global-set-key (kbd "C-c t h") 'text-categories-toggle-hidden)
	;; store or restore a certain category
	(global-set-key (kbd "C-c t s") 'text-categories-store-restore)
	;; cycle the category of the current line
	(global-set-key (kbd "C-c t n") 'text-categories-cycle-line)

Or it can be set up using use-package:

	(use-package text-categories
		:ensure t ;; install it automatically if it doesn't exist
		:bind (
		 ;; toggle text category mode
		 ("C-c t t" . text-categories)
		 ;; change text category
		 ("C-c t c" . text-categories-change)
		 ;; delete characters belonging to a text category
		 ("C-c t d" . text-categories-delete)
		 ;; set the text category to the default one
		 ("C-c t r" . text-categories-reset)
		 ;; report the current text category
		 ("C-c t p" . text-categories-report)
		 ;; visualize categories in buffer
		 ("C-c t v" . text-categories-visualize)
		 ;; change the category of the marked region
		 ("C-c t u" . text-categories-change-region-category)
		 ;; toggle the visibility of a certain category
		 ("C-c t h" . text-categories-toggle-hidden)
		 ;; store or restore a certain category
		 ("C-c t s" . text-categories-store-restore)
		 ;; cycle the category of the current line
		 ("C-c t n" . text-categories-cycle-line)))

To enable text-categories automatically whenever a file is loaded that has a corresponding text-categories file call the function

	(text-categories-enable-on-find-file)

after the package is loaded.

If you don’t want text-categories to create the helper files for persistence, it can be disabled with:

	(setq text-categories-save nil)