https://github.com/rocktakey/rii
Reversible input interface for multiple input.
https://github.com/rocktakey/rii
Last synced: 3 months ago
JSON representation
Reversible input interface for multiple input.
- Host: GitHub
- URL: https://github.com/rocktakey/rii
- Owner: ROCKTAKEY
- License: gpl-3.0
- Created: 2021-03-05T09:30:27.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2021-03-17T14:46:50.000Z (over 4 years ago)
- Last Synced: 2025-03-20T16:39:38.547Z (3 months ago)
- Language: Emacs Lisp
- Homepage:
- Size: 27.3 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.org
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[[https://github.com/ROCKTAKEY/rii][https://img.shields.io/github/tag/ROCKTAKEY/rii.svg?style=flat-square]]
[[file:LICENSE][https://img.shields.io/github/license/ROCKTAKEY/rii.svg?style=flat-square]]
[[https://codecov.io/gh/ROCKTAKEY/rii?branch=master][https://img.shields.io/codecov/c/github/ROCKTAKEY/rii.svg?style=flat-square]]
[[https://github.com/ROCKTAKEY/rii/actions][https://img.shields.io/github/workflow/status/ROCKTAKEY/rii/CI/master.svg?style=flat-square]]
* Rii: Reversible Input Interface for Emacs
You can read multiple input from users. Users can go back backward input
through the buttons in the buffer.
#+begin_center
[[https://raw.githubusercontent.com/ROCKTAKEY/images/038c4569ee95c2e1bb977947d0e8c0487591e2c2/demo.gif]]
Fig. 1 Demo of =rii= (recorded with [[https://github.com/tarsius/keycast][keycast.el]])
#+end_center
#+begin_src emacs-lisp :tangle yes
(rii ((editor (completing-read "Favorite editor: " '("Emacs" "Vim" "VSCode")))
(fruit (intern (completing-read "Favorite fruit: " '(apple orange lemon)))))
(switch-to-buffer "*Welcome-to-Rii*")
(erase-buffer)
(insert "Welcome to Rii!\n\n"
"Your favorite editor is " editor "!\n"
"Your favorite fruit is " (pp fruit) "!\n"))
#+end_src
* How to Use?
You can just use macro =rii= for the purpose. Semantics is almost same as =let=,
but a little expanded. Buffer is shown to provide backward input.
#+begin_src emacs-lisp :tangle yes
(rii (
;; You can bind any object, such as string, and symbol.
(editor (completing-read "Favorite editor: " '("Emacs" "Vim" "VSCode")))
(fruit (intern (completing-read "Favorite fruit: " '(apple orange lemon))))
;; If you would like to display string in buffer instead of value,
;; use `rii-change-display-value'.
(str-list (let* ((list-list '(("star" . ("Sun" "Vega" "Antares" "Sirius"))
("planet" . ("Mercury" "Venus" "Earth" "Mars"))))
(key (completing-read "Which list do you use: " list-list))
(value (cdr (assoc key list-list))))
(rii-change-display-value
value ;Actual value
key))) ;Displayed string
;; If you want to change string of button, use list instead of symbol as car.
;; Cdr the car list is plist.
((sport ;Symbol bound by value
:display "Your favorite sports") ;String displayed on the buffer
(completing-read "Favorite sports: "
'("soccer" "baseball" "basketball" "skiing"))))
(switch-to-buffer "*Welcome-to-Rii*")
(erase-buffer)
(insert "Welcome to Rii!\n\n"
"Your favorite editor is " editor "!\n"
"Your favorite fruit is " (pp fruit) "!\n"
"Your favorite sport is " sport "!\n\n")
(dolist (x str-list)
(insert x ", "))
(insert "are very beautiful!\n"))
#+end_src
* Detail of =rii= macro
#+begin_src emacs-lisp :tangle yes
(rii ((VAR VALUE) ...)
BODY...)
#+end_src
** Basic structure
Basical smantics is same as =let=, except that =VAR= cannot be used instead of
=(VAR nil)= (because binding by =nil= is unecessary). Also constant or noninteractive
sexp can be also accepted as =VALUE=, but button is still displayed, so =let= is
recommended for that case.
#+begin_src emacs-lisp :tangle yes
(rii (
;;Input string
(str (read-string "Input some str: "))
;; Constant is accepted but not recommended
(x 1))
(message "%s / %d" str x))
#+end_src
** Change button string
If you want to change button string, use =((VAR :display "something") VALUE)=
instead of =(VAR VALUE)=, in first argument of =rii=. By default, string capitalized
=VAR= and repleced "-" with " " is used.
#+begin_src emacs-lisp :tangle yes
(rii (((str :display "My string") ;Button is shown as "My string" instead of "Str"
(read-string "Hit some str: "))
((num :display "My number") ;Button is shown as "My number" inttead of "Num"
(read-number "Hit number: ")))
(message "%s%d" str num))
#+end_src
** Change displayed string of each value
If you want to change string displayed after button instead of value returned by =VALUE=,
use =rii-change-display-value= or =rii-change-display-value-func=.
First argument is commonly value returned by =VALUE=.
On =rii-change-display-value=, second argument is string displayed instead of =VALUE=.
On =rii-change-display-value-func=, second argument is function which recieves
first argument and which returns displayed string.
#+begin_src emacs-lisp :tangle yes
(rii ((str1 (rii-change-display-value
(read-string "String1: ")
"xyz")) ;Always display "xyz"
(str2 (let ((s (read-string "String1: ")))
(rii-change-display-value
s ;Actually bound value
(concat "xyz" s)))) ;Prefixed by "xyz"
(num (rii-change-display-value-func
(read-number "Number: ") ;Actually bound value
(lambda (x) ;x is bound by read number
(make-string x ?a))))) ;display "a" X times.
(message "%s\n%s\n%d" str1 str2 num))
#+end_src
** Use custom variables prefixed by =rii-=
When symbol prefixed by "rii-" is used as =VAR=, the =(VAR VALUE)=
is regarded as special. While the other =VALUE= s are evaluated
sequencially, =VALUE= s of "rii-"-prefixed =VAR= are evaluated
earlier than any others. These =VAR= is bound buffer-locally
(not bound dynamically), so accessable only in the buffer.
#+begin_src emacs-lisp :tangle yes
(rii ((rii-buffer-name "*Welcome*") ;Like this
(str (read-string "str: ")))
(message str))
#+end_src
* Keybinding in buffer
| Key | Function | Description |
|----------------+-------------------------+-------------------------------|
| TAB | forward-button | Go to next button |
| backtab(S-TAB) | backward-button | Go to previous button |
| SPC | scroll-up-command | Scroll up the buffer |
| S-SPC | scroll-down-command | Scroll down the buffer |
| M-p | rii-previous-history | Load previous history |
| M-n | rii-next-history | Load next history |
| q | quit-window | Quit this buffer (not killed) |
| C-c C-k | rii-kill-current-buffer | Kill buffer |
| C-c C-c | rii-apply | Push apply button |
* Custom variables
All custom variables below can use as =VAR= in first argument of =rii=.
You can change default value by set variable globally.
** =rii-button-type=, =rii-button-apply-type=
Button type which is used to create input button or application button.
See document of =define-button-type=.
** =rii-buffer-name=
Buffer name used by =rii=.
** =rii-multiple-buffer=
Whether create multiple buffers when buffer named =rii-buffer-name=
is already exist. when the value is =non-nil= and when buffer named
=rii-buffer-name= is already exist, =rii= creates buffer named
=rii-buffer-name= + "" (N is serial number). When the value is =nil=,
ask whether kill the buffer or not.
** =rii-separator-after-button=
Separator string between section.
(section means pair of button and displayed value).
** =rii-separator-between-section=
Separator string between button and value.
** =rii-confirm-when-apply=
Whether confirm before apply or not.
** =rii-header-document=
Comment inserted on head of the buffer.
** =rii-ring-history-variable=
Variable which has history.
Set this on =rii= if you want to use isolated history.
** =rii-ring-history-size-default=
Default size of history saved in =rii-ring-history-variable=.
* License
This package is licensed by GPLv3. See [[file:LICENSE][LICENSE]].