Debian Codegraph @

doc/boxes.el

raw
1 ;;; boxes.el --- ASCII boxes unlimited! -*- lexical-binding: t -*-
2
3 ;; Copyright (C) 1999, 2001, 2006 Jason L. Shiffer
4
5 ;; Author: Jason L. Shiffer <[email protected]>
6 ;; Maintainer: Jason L. Shiffer <[email protected]>
7 ;; Version: 0.0
8 ;; Package-Requires: ((emacs "24.3"))
9 ;; Keywords: extensions
10 ;; URL: https://boxes.thomasjensen.com
11 ;; Created: 1999-10-30
12 ;; Others:
13 ;; Vijay Lakshminarayanan: support for choosing boxes comment by current buffer mode.
14 ;; Mike Woolley: Customise and packaging support.
15
16 ;; boxes - Command line filter to draw/remove ASCII boxes around text
17 ;; Copyright (c) 1999-2024 Thomas Jensen and the boxes contributors
18 ;;
19 ;; This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
20 ;; License, version 3, as published by the Free Software Foundation.
21 ;; This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
22 ;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
23 ;; details.
24 ;; You should have received a copy of the GNU General Public License along with this program.
25 ;; If not, see <https://www.gnu.org/licenses/>.
26
27 ;;; Commentary:
28
29 ;; This program provides an interface to the boxes application which can be found at
30 ;; https://boxes.thomasjensen.com/
31
32 ;; To use this, add the following lines to your startup file:
33 ;;
34 ;; (global-set-key "\C-cb" 'boxes-command-on-region)
35 ;; (global-set-key "\C-cq" 'boxes-create)
36 ;; (global-set-key "\C-cr" 'boxes-remove)
37 ;;
38 ;; If you didn't install the package version then you will also need to put this file somewhere in your load path and
39 ;; add these lines to your startup file:
40 ;;
41 ;; (autoload 'boxes-command-on-region "boxes" nil t)
42 ;; (autoload 'boxes-remove "boxes" nil t)
43 ;; (autoload 'boxes-create "boxes" nil t)
44 ;;
45 ;; If `use-package' is installed you can automatically install the boxes binary and elisp package with:
46 ;;
47 ;; (use-package boxes
48 ;; :ensure t
49 ;; :ensure-system-package boxes
50 ;; :bind (("C-c b" . boxes-command-on-region)
51 ;; ("C-c q" . boxes-create)
52 ;; ("C-c r" . boxes-remove)))
53
54 ;;; Code:
55
56 (defgroup boxes nil
57 "ASCII boxes unlimited!"
58 :prefix "boxes-"
59 :group 'convenience)
60
61 (defcustom boxes-command "boxes"
62 "The boxes command."
63 :type 'string
64 :group 'boxes)
65
66 (defcustom boxes-args ""
67 "Additional arguments to the boxes command."
68 :type 'string
69 :group 'boxes)
70
71 (defcustom boxes-known-modes
72 '((c-mode . "c-cmt2") (c++-mode . "c-cmt2") (java-mode . "java-cmt")
73 (html-mode . "html-cmt") (sh-mode . "pound-cmt") (perl-mode . "pound-cmt")
74 (python-mode . "pound-cmt") (ruby-mode . "pound-cmt")
75 (emacs-lisp-mode . "lisp-cmt") (lisp-mode . "lisp-cmt"))
76 "Default box type based on the major mode of the buffer."
77 :type '(alist :key-type symbol :value-type string)
78 :group 'boxes)
79
80 (defconst boxes-minimum-version "2.1.0"
81 "Minimum required version of `boxes' to support querying the available box types.")
82
83 (defvar boxes-history nil
84 "Boxes types history.")
85
86 (defvar-local boxes-default-type nil
87 "The default type of box.")
88
89 (defvar boxes-types-list nil
90 "List of types available to the current boxes implementation, nil if not set yet.")
91
92 (defun boxes-types ()
93 "Return the list of types available to the current boxes implementation.
94 Signal error if a supported version of `boxes' is not available."
95 (condition-case nil
96 (or boxes-types-list
97 (setq boxes-types-list
98 (let ((types (process-lines boxes-command "-q" "(all)")))
99 (mapcar (lambda(type) (replace-regexp-in-string " *\(alias\) *$" "" type))
100 types))))
101 (error (error "Please install Boxes %s or later" boxes-minimum-version))))
102
103 (defun boxes-default-type (mode)
104 "Get the default box type for the given buffer major MODE."
105 (or (cdr (assoc mode boxes-known-modes)) "c-cmt2"))
106
107 ;;;###autoload
108 (defun boxes-create ()
109 "Automagicly create a new box around the region based on the default type."
110 (interactive "*")
111 (boxes-command-on-region (region-beginning) (region-end) boxes-default-type))
112
113 ;;;###autoload
114 (defun boxes-remove ()
115 "Automagicly remove a new box around the region based on the default type."
116 (interactive "*")
117 (boxes-command-on-region (region-beginning) (region-end) boxes-default-type 1))
118
119 ;;;###autoload
120 (defun boxes-command-on-region (start end type &optional remove)
121 "Create or Remove boxes from a region.
122
123 To create a box select a region, hit \\[boxes-command-on-region]
124 & enter a box type. Box type selection uses tab completion on
125 the supported types.
126
127 To remove a box simply prefix a 1 to the call, eg M-1
128 \\[boxes-command-on-region] will remove a box from a region.
129
130 Note that interactive use requires `boxes' >= 2.1.0 to support
131 querying the supported types.
132
133 When calling from Lisp, supply the region START & END and the box
134 TYPE to create a box. Specifying a non-nil value for REMOVE,
135 removes the box."
136 (interactive (let ((string
137 (completing-read (format "Box type (%s): " boxes-default-type)
138 (boxes-types) nil t nil 'boxes-history boxes-default-type)))
139 (list (region-beginning) (region-end)
140 string
141 current-prefix-arg)))
142 (when (or (null type) (string= type ""))
143 (setq type (boxes-default-type major-mode)))
144 (setq boxes-default-type type)
145 (let ((command-string
146 (concat boxes-command
147 (if remove
148 (concat boxes-args " -r "))
149 (if type
150 (concat boxes-args " -d " type)))))
151 (shell-command-on-region start end command-string nil 1)))
152
153 (provide 'boxes)
154 ;;; boxes.el ends here