diff --git a/README.org b/README.org index bdfcd01..3528f3f 100644 --- a/README.org +++ b/README.org @@ -125,7 +125,7 @@ ((string-match "^(\\_<\\(nth\\)\\_>" str) (cons (cons (match-beginning 1) (match-end 1)) - ;; This function permutate arguments on lisp. + ;; This function permutate arguments on Lisp. (grugru-utils-lisp-exchange-args (replace-match "aref" nil nil str 1) '(2 1)))) diff --git a/grugru.el b/grugru.el index fc97bc1..915ae67 100644 --- a/grugru.el +++ b/grugru.el @@ -24,293 +24,594 @@ ;;; Commentary: -;;; 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 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. -;;;; Examples -;; -;; ;; Define grugru on major-mode. -;; (grugru-define-on-major-mode 'c-mode 'symbol '("unsigned" "signed")) -;; (grugru-define-on-major-mode 'c-mode 'word '("get" "set")) -;; ;; Now, you can toggle unsigned <=> signed and get <=> set -;; ;; by running the command grugru in c-mode. -;; -;; ;; You can pass a list of symbol major-mode instead of one. -;; (grugru-define-on-major-mode '(java-mode c++-mode) 'word '("get" "set")) -;; -;; ;; Define grugru on current major-mode. -;; ;; Same as (grugru-define-on-major-mode major-mode 'symbol '("red" "green" "yellow")) -;; ;; This should be run in some hook or function, -;; ;; because major-mode is not confirmed if in init.el. -;; (add-hook 'c-mode-common-hook -;; (lambda () -;; (grugru-define-on-local-major-mode 'symbol '("red" "green" "yellow")))) -;; -;; ;; Define grugru on local. Should be defined in some hook or function, -;; ;; because it is saved buffer local. -;; (add-hook 'text-mode-hook -;; (lambda () -;; (grugru-define-local 'word '("is" "was")) -;; (grugru-define-local 'word '("I" "my" "me" "mine")))) -;; -;; ;; Define grugru globally. This is applied in all buffers. -;; (grugru-define-global 'symbol '("yes" "no")) -;; -;; ;; You can use function instead of list of strings. -;; (grugru-define-on-major-mode -;; 'c-mode 'symbol -;; (lambda (arg) -;; (cond -;; ((string-match "a\\(.*\\)b" arg) -;; (concat "b" (match-string 1 arg) "c")) -;; ((string-match "b\\(.*\\)c" arg) -;; (concat "a" (match-string 1 arg) "b"))))) -;; -;; ;; You can also write like: -;; (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"))) -;; -;; -;; ;; You can define function which rotate pre-specified texts. -;; ;; For example, three-state can rotate only 2 tuples, -;; ;; ("water" "ice" "vapor") and ("solid" "liquid" "gas"), -;; ;; not any other tuples defined by grugru-define-global and so on. -;; (grugru-define-function three-state () -;; "Docstring. This is optional." -;; (symbol . ("water" "ice" "vapor")) -;; (symbol . ("solid" "liquid" "gas"))) -;; ;; If you want to find the functions defined by `grugru-define-function' -;; ;; with `describe-function', execute this: -;; (grugru-find-function-integration-mode +1) -;; -;;; Interactive Functions -;;;; ~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. -;;;; ~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~. -;;;; ~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~. -;; You can assign completing function to ~grugru-completing-function~. -;;; Functions Defining grugru -;;;; ~(grugru-define-global GETTER STRINGS-OR-GENERATOR)~ -;; Define global grugru with GETTER and STRINGS-OR-GENERATOR. -;; -;; 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. -;; 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-GENERATOR 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")) -;; -;;;; ~(grugru-define-on-major-mode MAJOR GETTER STRINGS-OR-GENERATOR)~ -;; Define major-mode local grugru with GETTER and STRINGS-OR-GENERATOR. -;; -;; 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")) -;; -;;;; ~(grugru-define-local GETTER STRINGS-OR-GENERATOR)~ -;; Define buffer-local grugru with GETTER and STRINGS-OR-GENERATOR. -;; -;; 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-GENERATOR to a function). -;; On interactive usage, by default, GETTER is the length of car of STRINGS-OR-GENERATOR, -;; and STRINGS-OR-GENERATOR is a list which has 2 elements, constructed interactively. -;; With prefix argument, you can select GETTER and length of STRINGS-OR-GENERATOR. -;; Default GETTER is set by ~grugru-local-interactively-default-getter~. -;; -;;;; ~(grugru-define-multiple &rest CLAUSES)~ -;; This function define multiple grugru. -;; -;; Each ~CLAUSE~ is: -;; - ~(GETTER . STRINGS-OR-GENERATOR)~: means ~(grugru-define-global GETTER STRINGS-OR-GENERATOR)~. -;; - ~(MAJOR (GETTER . STRINGS-OR-GENERATOR)...)~: means ~(grugru-define-on-major-mode MAJOR GETTER STRINGS-OR-GENERATOR)...~. -;; - 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"))) -;; -;;;; ~(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-GENERATOR)~, -;; 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")) -;; -;;; leaf-keyword ~:grugru~ -;; You can use ~:grugru~ keyword on [[https://github.com/conao3/leaf.el][leaf.el]], if you use [[https://github.com/conao3/leaf-keywords.el][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 -;; (symbol "nil" "t") -;; (emacs-lisp-mode -;; (word "add" "remove"))) -;; -;;; Custom Variables -;;;; ~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. -;; -;;;; ~grugru-edit-save-file~ -;; The name of file saved the information by ~grugru-edit~. -;; Default value is "~/.emacs.d/.grugru". -;; -;;;; ~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) -;; -;; -;;;; ~grugru-select-function-generate-number~ -;; This variable have how many strings are generated from function -;; in ~STRINGS-OR-GENERATOR~, on ~grugru-select~. -;; -;;;; ~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. -;;; License -;; This package is licensed by GPLv3. See [[file:LICENSE][LICENSE]]. +;; 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] ;;; Code: