Table of Contents _________________ 1. Grugru: Rotate text at point. 2. How to Use? .. 1. Examples 3. Interactive Functions .. 1. `grugru' .. 2. `grugru-select' .. 3. `grugru-edit' 4. Functions Defining grugru .. 1. `(grugru-define-global GETTER STRINGS-OR-FUNCTION)' .. 2. `(grugru-define-on-major-mode MAJOR GETTER STRINGS-OR-FUNCTION)' .. 3. `(grugru-define-local GETTER STRINGS-OR-FUNCTION)' .. 4. `(grugru-define-multiple &rest CLAUSES)' .. 5. `(grugru-define-function NAME () &optional DOCSTRING &rest BODY)' 5. Utilities to define grugru .. 1. `(grugru-utils-lisp-exchange-args LIST-STRING PERMUTATION)' ..... 1. Usage 6. Custom Variables .. 1. `grugru-getter-alist' .. 2. `grugru-edit-save-file' .. 3. `grugru-completing-function' .. 4. `grugru-select-function-generate-number' .. 5. `grugru-local-interactively-default-getter' .. 6. `grugru-point-after-rotate' .. 7. `grugru-indent-after-rotate' .. 8. `grugru-strings-metagenerator' 7. leaf-keyword `:grugru' 8. License [https://img.shields.io/github/tag/ROCKTAKEY/grugru.svg?style=flat-square] [https://img.shields.io/github/license/ROCKTAKEY/grugru.svg?style=flat-square] [https://img.shields.io/github/actions/workflow/status/ROCKTAKEY/grugru/CI.yml.svg?style=flat-square] [https://img.shields.io/codecov/c/github/ROCKTAKEY/grugru/master.svg?style=flat-square] [file:https://melpa.org/packages/grugru-badge.svg] [https://img.shields.io/github/tag/ROCKTAKEY/grugru.svg?style=flat-square] [https://img.shields.io/github/license/ROCKTAKEY/grugru.svg?style=flat-square] [https://img.shields.io/github/actions/workflow/status/ROCKTAKEY/grugru/CI.yml.svg?style=flat-square] [https://img.shields.io/codecov/c/github/ROCKTAKEY/grugru/master.svg?style=flat-square] [file:https://melpa.org/packages/grugru-badge.svg] 1 Grugru: Rotate text at point. =============================== With this package, you can rotate things at point. Fig. 1 demo on `emacs-lisp-mode' Fig. 2 demo on `c++-mode' Fig. 3 Use `grugru-define-local' interactively 2 How to Use? ============= You can interactively use the function `grugru'. This function rotate the thing at point if assigned. You can assign rotated things with `grugru-define-on-major-mode', `grugru-define-on-local-major-mode', and `grugru-define-local'. If you use `grugru', you should assign `grugru' to 1 stroke key like `C-;', or `M-g'. ,---- | (global-set-key (kbd "C-;") #'grugru) ; Or other key. `---- If you want use default grugru, eval `grugru-default-setup'. In the other words, add to your init.el: ,---- | (grugru-default-setup) `---- If you want `grugru' to highlight gurgruable thing, add to your init.el: ,---- | (grugru-highlight-mode) `---- If you want to change default action at point, you can use `grugru-edit', with which you can edit grugrus at point interactively. The change edited by this function is saved in `grugru-edit-save-file', and loaded by run `grugru-edit-load'. So to load the change, you can write on init.el after `(grugru-default-setup)': ,---- | (grugru-edit-load) `---- If you want to use ivy or ido as completing-read, set `grugru-edit-completing-function'. Or, you can use `grugru-redefine-\*' or `grugru-remove-\*' for non-interactive editing of default setup. 2.1 Examples ~~~~~~~~~~~~ ,---- | 1 ;; Define grugru on major-mode. | 2 (grugru-define-on-major-mode 'c-mode 'symbol '("unsigned" "signed")) | 3 (grugru-define-on-major-mode 'c-mode 'word '("get" "set")) | 4 ;; Now, you can toggle unsigned <=> signed and get <=> set | 5 ;; by running the command grugru in c-mode. | 6 | 7 ;; You can pass a list of symbol major-mode instead of one. | 8 (grugru-define-on-major-mode '(java-mode c++-mode) 'word '("get" "set")) | 9 | 10 ;; Define grugru on current major-mode. | 11 ;; Same as (grugru-define-on-major-mode major-mode 'symbol '("red" "green" "yellow")) | 12 ;; This should be run in some hook or function, | 13 ;; because major-mode is not confirmed if in init.el. | 14 (add-hook 'c-mode-common-hook | 15 (lambda () | 16 (grugru-define-on-local-major-mode 'symbol '("red" "green" "yellow")))) | 17 | 18 ;; Define grugru on local. Should be defined in some hook or function, | 19 ;; because it is saved buffer local. | 20 (add-hook 'text-mode-hook | 21 (lambda () | 22 (grugru-define-local 'word '("is" "was")) | 23 (grugru-define-local 'word '("I" "my" "me" "mine")))) | 24 | 25 ;; Define grugru globally. This is applied in all buffers. | 26 (grugru-define-global 'symbol '("yes" "no")) | 27 | 28 ;; Define grugru keeping case: | 29 (grugru-define-global 'symbol (grugru-metagenerator-keep-case '("yes" "no"))) | 30 | 31 ;; If you want grugru to define grugru defaultly keeping case: | 32 (customize-set-variable 'grugru-strings-metagenerator #'grugru-metagenerator-simple) | 33 | 34 ;; You can use function instead of list of strings. | 35 (grugru-define-on-major-mode | 36 'c-mode 'symbol | 37 ;; Optional argument `rev' is flag for backward rotation. | 38 ;; If the second argument `rev' is ignoreable (for example, rotate two strings), | 39 ;; you can just use the function receiving only 1 argument. | 40 (lambda (arg &optional rev) | 41 (if rev | 42 ;; backward | 43 (cond | 44 ((string-match "a\\(.*\\)b" arg) | 45 ;; Rotate axyzb to cxyzd | 46 (concat "c" (match-string 1 arg) "d")) | 47 ((string-match "b\\(.*\\)c" arg) | 48 ;; Rotate bxyzc to axyzb | 49 (concat "a" (match-string 1 arg) "b")) | 50 ((string-match "c\\(.*\\)d" arg) | 51 ;; Rotate cxyzd to bxyzc | 52 (concat "b" (match-string 1 arg) "c"))) | 53 ;; forward | 54 (cond | 55 ((string-match "a\\(.*\\)b" arg) | 56 ;; Rotate axyzb to bxyzc | 57 (concat "b" (match-string 1 arg) "c")) | 58 ((string-match "b\\(.*\\)c" arg) | 59 ;; Rotate bxyzc to cxyzd | 60 (concat "c" (match-string 1 arg) "d")) | 61 ((string-match "c\\(.*\\)d" arg) | 62 ;; Rotate cxyzd to axyzb | 63 (concat "a" (match-string 1 arg) "b")))))) | 64 | 65 ;; You can indicate which position is valid to grugru in strings. | 66 ;; The function can return not only string but also cons cell (BOUNDS . STRING). | 67 ;; BOUNDS is a list of cons cell (BEG . END), which is pair of numbers indicating | 68 ;; range valid to rotate. | 69 (defun grugru-default@emacs-lisp+nth!aref (str) | 70 "Return STR exchanged `nth' and `aref' with argument permutation." | 71 (cond | 72 ((string-match "^(\\_<\\(nth\\)\\_>" str) | 73 (cons | 74 (cons (match-beginning 1) (match-end 1)) | 75 ;; This function permutate arguments on Lisp. | 76 (grugru-utils-lisp-exchange-args | 77 (replace-match "aref" nil nil str 1) | 78 '(2 1)))) | 79 ((string-match "^(\\_<\\(aref\\)\\_>" str) | 80 (cons | 81 (cons (match-beginning 1) (match-end 1)) | 82 (grugru-utils-lisp-exchange-args | 83 (replace-match "nth" nil nil str 1) | 84 '(2 1)))))) | 85 | 86 ;; You can also write like: | 87 (grugru-define-multiple | 88 (fundamental-mode | 89 . ((word . ("aaa" "bbb" "ccc")) | 90 ;; (symbol "xxx" "yyy" "zzz") is same as below. | 91 ;; You can use both. | 92 (symbol . ("xxx" "yyy" "zzz")) | 93 (word . ("abc" "def" "ghi")))) | 94 (word . ("aaaa" "bbbb" "cccc")) | 95 (symbol . ("xxxx" "yyyyy" "zzzzz")) | 96 (word . ("abcd" "defd" "ghid"))) | 97 ;; or | 98 (grugru-define-multiple | 99 (fundamental-mode | 100 (word "aaa" "bbb" "ccc") | 101 (symbol "xxx" "yyy" "zzz") | 102 (word "abc" "def" "ghi")) | 103 (word "aaaa" "bbbb" "cccc") | 104 (symbol "xxxx" "yyyyy" "zzzzz") | 105 (word "abcd" "defd" "ghid")) | 106 | 107 ;; Above two examples are both expanded to: | 108 (progn | 109 (progn | 110 (grugru-define-on-major-mode 'fundamental-mode 'word '("aaa" "bbb" "ccc")) | 111 (grugru-define-on-major-mode 'fundamental-mode 'symbol '("xxx" "yyy" "zzz")) | 112 (grugru-define-on-major-mode 'fundamental-mode 'word '("abc" "def" "ghi"))) | 113 (grugru-define-global 'word '("aaaa" "bbbb" "cccc")) | 114 (grugru-define-global 'symbol '("xxxx" "yyyyy" "zzzzz")) | 115 (grugru-define-global 'word '("abcd" "defd" "ghid"))) | 116 | 117 | 118 ;; You can define function which rotate pre-specified texts. | 119 ;; For example, three-state can rotate only 2 tuples, | 120 ;; ("water" "ice" "vapor") and ("solid" "liquid" "gas"), | 121 ;; not any other tuples defined by grugru-define-global and so on. | 122 (grugru-define-function three-state () | 123 "Docstring. This is optional." | 124 (symbol . ("water" "ice" "vapor")) | 125 (symbol . ("solid" "liquid" "gas"))) | 126 ;; If you want to find the functions defined by `grugru-define-function' | 127 ;; with `describe-function', execute this: | 128 (grugru-find-function-integration-mode +1) `---- 3 Interactive Functions ======================= 3.1 `grugru' ~~~~~~~~~~~~ This function rotates text at point. Rotated text is defined by `grugru-define-*' functions. If prefix argument is passed, repeatedly executed. Negative prefix arguments means backward rotation. Also, `grugru-backward' can be used for backward rotation. 3.2 `grugru-select' ~~~~~~~~~~~~~~~~~~~ This function replace text at point. You can select grugru and string replaced to. You can assign completing function to `grugru-completing-function'. 3.3 `grugru-edit' ~~~~~~~~~~~~~~~~~ This function edits grugru at point defined by default. First, select grugru from grugrus available at point. Then, edit the list in minibuffer. The change is saved to file `grugru-edit-save-file' if it is not `local' one. You can assign completing function to `grugru-completing-function'. 4 Functions Defining grugru =========================== 4.1 `(grugru-define-global GETTER STRINGS-OR-FUNCTION)' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Define global grugru with GETTER and STRINGS-OR-FUNCTION. GETTER is a function, or a symbol which is alias defined in `grugru-getter-alist'. GETTER also can be positive or negative number, which means the number of characters after point. By default, symbol, word, char is available. If it is a function, it should return cons cell `(begin . end)' which express things at point, and with no argument. STRINGS-OR-FUNCTION is list of string or function. List of string: If it includes string gotten by GETTER, the things gotten by GETTER is replaced to next string. Function: It is passed things gotten by GETTER, and should return string to replace the things to. You can use like: ,---- | ;; Replace "yes" at point, to "no". | ;; Or replace "no" at point, to "yes". | (grugru-define-global 'symbol '("yes" "no")) `---- 4.2 `(grugru-define-on-major-mode MAJOR GETTER STRINGS-OR-FUNCTION)' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Define major-mode local grugru with GETTER and STRINGS-OR-FUNCTION. Same as `grugru-define-global', but grugru defined with this is applied only in buffer on MAJOR major-mode. MAJOR can be list of major-modes. ,---- | ;; Replace "yes" at point, to "no", or replace "no" at point, to "yes", | ;; only in lisp-interaction-mode. | (grugru-define-on-major-mode lisp-interaction-mode 'symbol '("yes" "no")) `---- 4.3 `(grugru-define-local GETTER STRINGS-OR-FUNCTION)' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Define buffer-local grugru with GETTER and STRINGS-OR-FUNCTION. Same as `grugru-define-global', but grugru defined with this is applied only in buffer where eval this expression. ,---- | ;; This should be used in hook or others. | ;; Because this definition is buffer-local. | (add-hook 'text-mode-hook | (lambda () | (grugru-define-local 'word '("is" "was")) | (grugru-define-local 'word '("I" "my" "me" "mine")))) `---- Also, you can run it interactively (though cannot set STRINGS-OR-FUNCTION to a function). On interactive usage, by default, GETTER is the length of car of STRINGS-OR-FUNCTION, and STRINGS-OR-FUNCTION is a list which has 2 elements, constructed interactively. With prefix argument, you can select GETTER and length of STRINGS-OR-FUNCTION. Default GETTER is set by `grugru-local-interactively-default-getter'. 4.4 `(grugru-define-multiple &rest CLAUSES)' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This function define multiple grugru. Each `CLAUSE' is: - `(GETTER . STRINGS-OR-FUNCTION)': means `(grugru-define-global GETTER STRINGS-OR-FUNCTION)'. - `(MAJOR (GETTER . STRINGS-OR-FUNCTION)...)': means `(grugru-define-on-major-mode MAJOR GETTER STRINGS-OR-FUNCTION)...'. - List of above. ,---- | (grugru-define-multiple | (fundamental-mode | . ((word . ("aaa" "bbb" "ccc")) | ;; (symbol "xxx" "yyy" "zzz") is same as below. | ;; You can use both. | (symbol . ("xxx" "yyy" "zzz")) | (word . ("abc" "def" "ghi")))) | (word . ("aaaa" "bbbb" "cccc")) | (symbol . ("xxxx" "yyyyy" "zzzzz")) | (word . ("abcd" "defd" "ghid"))) | ;; or | (grugru-define-multiple | (fundamental-mode | (word "aaa" "bbb" "ccc") | (symbol "xxx" "yyy" "zzz") | (word "abc" "def" "ghi")) | (word "aaaa" "bbbb" "cccc") | (symbol "xxxx" "yyyyy" "zzzzz") | (word "abcd" "defd" "ghid")) | | ;; Above two examples are both expanded to: | (progn | (progn | (grugru-define-on-major-mode 'fundamental-mode 'word '("aaa" "bbb" "ccc")) | (grugru-define-on-major-mode 'fundamental-mode 'symbol '("xxx" "yyy" "zzz")) | (grugru-define-on-major-mode 'fundamental-mode 'word '("abc" "def" "ghi"))) | (grugru-define-global 'word '("aaaa" "bbbb" "cccc")) | (grugru-define-global 'symbol '("xxxx" "yyyyy" "zzzzz")) | (grugru-define-global 'word '("abcd" "defd" "ghid"))) `---- 4.5 `(grugru-define-function NAME () &optional DOCSTRING &rest BODY)' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Define function which can roate only grugru defined by BODY. Each element of BODY is `(GETTER . STRINGS-OR-FUNCTION)', which meaning is same as `grugru-define-*' functions. ,---- | ;; The function `three-state' rotate like "water"=>"ice"=>"vapor"=>"water", | ;; or "solid"=>"liquid"=>"gas"=>"solid". | (grugru-define-function three-state () | "Docstring. This is optional." | (symbol . ("water" "ice" "vapor")) | (symbol . ("solid" "liquid" "gas"))) | | ;; This sentense do NOT affect to the function `three-state'. | (grugru-define-global 'symbol '("yes" "no")) `---- 5 Utilities to define grugru ============================ 5.1 `(grugru-utils-lisp-exchange-args LIST-STRING PERMUTATION)' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Permute argument of sexp read from `LIST-STRING' according to `PERMUTATION'. For example, `(grugru-utils-lisp-exchange-args \"(nth 1 '(x y z))\" '(2 1))' returns `(nth '(x y z) 1)'. Newlines and whitespaces are also kept. This function is defined for user to define the function for grugru which rotate not only fuction's name but also arguments' order. 5.1.1 Usage ----------- ,---- | (defun grugru-rotate-nth-aref (str) | (cond | ((string-match "^(\\(\\_\\)" str) ;match to "(nth" | (grugru-utils-lisp-exchange-args | (replace-match "aref" nil nil str 1) ;replace function's name to "aref" | '(2 1))) ;exchange arguments' order | ((string-match "^(\\(\\_\\)" str) ;match to "(aref" | (grugru-utils-lisp-exchange-args | (replace-match "nth" nil nil str 1) ;replace function's name to "nth" | '(2 1))))) ;exchange arguments' order | (grugru-define-on-major-mode | 'emacs-lisp-mode | 'list | #'grugru-rotate-nth-aref) | | ;; Then, | (nth 3 '(foo bar)) | ;; is rotated to: | (aref '(foo bar) 3) `---- 6 Custom Variables ================== 6.1 `grugru-getter-alist' ~~~~~~~~~~~~~~~~~~~~~~~~~ Alist of getter. Each key (car) of element is a symbol, which is regarded as `GETTER'. Each value (cdr) of element is a function or sexp. It should return things at point. 6.2 `grugru-edit-save-file' ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The name of file saved the information by `grugru-edit'. Default value is "~/.emacs.d/.grugru". 6.3 `grugru-completing-function' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Completing function. Default value is `completing-read'. If you would like to use ivy or ido, write: ,---- | ;; For ivy: | (setq grugru-completing-function #'ivy-completing-read) | ;; For ido: | (setq grugru-completing-function #'ido-completing-read) `---- 6.4 `grugru-select-function-generate-number' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This variable have how many strings are generated from function in `STRINGS-OR-FUNCTION', on `grugru-select'. 6.5 `grugru-local-interactively-default-getter' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Indicate default getter on interactive usage of `grugru-define-local'. 0 means If 0, gets number from first string, otherwise it should be symbol in `grugru-getter-alist' or a function which gets things at point. 6.6 `grugru-point-after-rotate' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Where the point is after rotation by `grugru'. - `as-is' means keeping first position. - `beginning' means beginning of rotated things. - `end' means end of rotated things. 6.7 `grugru-indent-after-rotate' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Indent rotated text after `grugru' or not. Indent happens only if text after rotation has a newline. ,---- | (grugru-define-local 'list '("(abc def)" "(ghi\njkl)")) | ;; If `grugru-indent-after-rotate' is nil, | (abc def) | ;; is rotated to: | (ghi | jkl) | | ;; If `grugru-indent-after-rotate' is t, | (abc def) | ;; is rotated to: | (ghi | jkl) `---- 6.8 `grugru-strings-metagenerator' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Function which generates default generator from strings on `grugru-define-*'. The function should recieve `STRINGS', list of string, as one argument, and return function. Returned function should recieve one or two argument(s), string `STRING' as first one, boolean `REVERSE' as second one. STRING means current string. Returned function (generator) returns string next to STRING. If REVERSE is non-nil, it returns previous one instead. 7 leaf-keyword `:grugru' ======================== You can use `:grugru' keyword on [leaf.el], if you use [leaf-keywords.el]. By default, `leaf--name' is used as major-mode. Or you can write major-mode obviously. ,---- | (leaf lisp-mode | :grugru | (symbol "nil" "t") | (emacs-lisp-mode | (word "add" "remove")) | ...) | ;; The section of `:grugru' means: | (grugru-define-multiple | (lisp-mode | (symbol "nil" "t")) | (emacs-lisp-mode | (word "add" "remove"))) `---- [leaf.el] [leaf-keywords.el] 8 License ========= This package is licensed by GPLv3. See [LICENSE]. [LICENSE]