branch: elpa/casual
commit 6befedaaa5b20bc205fb478ed6c94992c6b08fc0
Merge: fdef969ecf c6f5f5dd8b
Author: Charles Choi <[email protected]>
Commit: GitHub <[email protected]>
Merge pull request #4 from
kickingvegas/merge-development-to-main-20241018_192837
Merge development to main 20241018_192837
---
README.org | 105 +++++++++++++++++++++----
docs/agenda.org | 101 ++++++++++++++++++++++++
docs/bookmarks.org | 93 ++++++++++++++++++++++
docs/calc.org | 84 ++++++++++++++++++++
docs/developer.org | 38 ++++-----
docs/dired.org | 152 ++++++++++++++++++++++++++++++++++++
docs/editkit.org | 182 +++++++++++++++++++++++++++++++++++++++++++
docs/info.org | 73 +++++++++++++++++
docs/isearch.org | 79 +++++++++++++++++++
docs/re-builder.org | 89 +++++++++++++++++++++
lisp/casual-agenda.el | 1 -
lisp/casual-bookmarks.el | 1 -
lisp/casual-calc-labels.el | 1 +
lisp/casual-calc.el | 3 +-
lisp/casual-dired.el | 1 -
lisp/casual-editkit-utils.el | 54 ++++++++++---
lisp/casual-editkit.el | 8 +-
lisp/casual-ibuffer.el | 1 -
lisp/casual-info.el | 1 -
lisp/casual-isearch.el | 1 -
lisp/casual-lib.el | 6 +-
lisp/casual-re-builder.el | 1 -
lisp/casual.el | 137 +++++++++++++++++++++++++++++++-
scripts/read-version.sh | 2 +-
tests/test-casual-editkit.el | 4 +-
25 files changed, 1148 insertions(+), 70 deletions(-)
diff --git a/README.org b/README.org
index 2730317d59..79320d02ba 100644
--- a/README.org
+++ b/README.org
@@ -1,40 +1,104 @@
* Casual
-A collection of opinionated
[[https://github.com/magit/transient][Transient]]-based user interfaces for
Emacs.
+A collection of opinionated
[[https://github.com/magit/transient][Transient]]-based keyboard-driven user
interfaces for various built-in Emacs modes.
-*THIS PROJECT IS WIP.*
+Casual is organized into different user interface (UI) libraries tuned for
different modes. Different user interfaces for the following modes are
supported:
+
+** [[file:docs/agenda.org][Agenda]] (Elisp library: ~casual-agenda~)
+ An interface for Org Agenda to help you plan your day.
+
+ [[file:docs/agenda.org][file:docs/images/casual-agenda-screenshot.png]]
+
+** [[file:docs/bookmarks.org][Bookmarks]] (Elisp library: ~casual-bookmarks~)
+ An interface for editing your bookmark collection.
+
+ [[file:docs/bookmarks.org][file:docs/images/casual-bookmarks-screenshot.png]]
+
+** [[file:docs/calc.org][Calc]] (Elisp library: ~casual-calc~)
+ An interface for Emacs Calc, an embarrasingly feature-rich calculator.
+
+ [[file:docs/calc.org][file:docs/images/casual-calc-tmenu.png]]
+
+** [[file:docs/dired.org][Dired]] (Elisp library: ~casual-dired~)
+ An interface for the venerable file manager Dired.
+
+ [[file:docs/dired.org][file:docs/images/casual-dired-screenshot.png]]
+
+** [[file:docs/editkit.org][EditKit]] (Elisp library: ~casual-editkit~)
+ A cornucopia of interfaces for the different editing features (e.g. marking,
copying, killing, duplicating, transforming, deleting) of Emacs. Included are
interfaces for rectangle, register, macro, and project commands.
+
+
[[file:docs/editkit.org][file:docs/images/casual-editkit-main-screenshot.png]]
+
+** [[file:docs/info.org][Info]] (Elisp library: casual-info)
+ An interface for the Info documentation system.
+
+ [[file:docs/info.org][file:docs/images/casual-info-screenshot.png]]
+
+** [[file:docs/isearch.org][I-Search]] (Elisp library: ~casual-isearch~)
+ An interface for the many commands supported by I-Search.
+
+ [[file:docs/isearch.org][file:docs/images/casual-isearch-tmenu.png]]
+
+** [[file:docs/re-builder.org][Re-Builder]] (Elisp library:
~casual-re-builder~)
+ An interface for the Emacs regular expression tool.
+
+
[[file:docs/re-builder.org][file:docs/images/casual-re-builder-screenshot.png]]
+
+Users can choose any or all of the user interfaces made available by Casual at
their pleasure.
-Looking for Casual Calc? Go to https://github.com/kickingvegas/casual-calc
* Motivation
-Emacs has many commands that are easy to forget if not used frequently. Menus
are a user interface (UI) affordance that offers discoverability and
recognition that can lower its learning curve. While menus are commonly
associated with mouse-driven UI, the inclusion of Transient in Emacs core
allows for building a keyboard-driven menu UI. Casual endeavors to offer this
as many Emacs users prefer keyboard-driven workflows.
+Emacs has many commands that are easy to forget if not used frequently. Menus
are a user interface (UI) affordance that offers discoverability and
recognition. While menus are commonly associated with mouse-driven UI, the
inclusion of Transient in Emacs core allows for building a keyboard-driven menu
UI. Transient menus are appealing to users who prefer keyboard-driven workflows.
+
+That said, Casual has no aims to be a mutually exclusive user interface. All
existing user interfaces to commands (keybinding, mini-buffer prompt, mouse
menus) are still available to the user.
** Goals
-- To provide a keyboard-driven menu UI toolkit for common Emacs editing
commands.
-- To provide casual access to the above commands.
+- To provide a keyboard-driven menu UI toolkit for common Emacs commands.
+- To allow for casual discovery and use of infrequently used Emacs commands.
+- To be a frequently used interface to the modes Casual does support.
** Non-Goals
-- Full coverage of all Emacs editing commands. Casual is not intended to be a
power user tool nor is it intended to be a replacement for mouse-driven menus.
-- Strict adherence to Emacs editing command naming. While Casual is *mostly*
in alignment with Emacs command naming, there are cases where it will make an
opinionated change if the name is deemed too vague or idiomatic.
+- Full coverage of all Emacs commands. Casual is not intended to be a power
user tool nor is it intended to be a replacement for mouse-driven menus. Casual
has no intent to exhaustively cover all modes available in Emacs with
keyboard-driven menus.
+- Strict adherence to Emacs command naming. While Casual is *mostly* in
alignment with Emacs command naming, there are cases where it will make an
opinionated change if the name is deemed too vague or idiomatic.
+- No intention is made by Casual to help on-board users to the existing
default bindings of a mode, nor to cater to users who already know them. That
said, many existing default Emacs bindings are replicated in Casual. Such
correspondence should be considered incidental.
- UX Stability (for now). Given that Casual is early in its life-cycle, expect
changes to its user experience in terms of menu hierarchy and keybinding
choices in future releases.
+
+Editorially, all design decisions for Casual are ultimately the opinion of
Charles Y. Choi. People comfortable with this are invited to use Casual at
their discretion.
* Requirements
Casual requires usage of
- Emacs ≥ 29.1
-- Magit ≥ 4.0.0
-- Casual Lib ≥ 1.1.0
Casual has been verified with the following configuration.
- Emacs 29.4 (macOS 14.5, Ubuntu Linux 22.04.4 LTS)
-* Asks
-As Casual is new, we are looking for early adopters! Your
[[https://github.com/kickingvegas/casual-symbol-overlay/discussions][feedback]]
is welcome as it will likely impact Casual's evolution, particularly with
regards to UI.
-
* Install
+Standard installation of the ~casual~ package is via MELPA distribution.
+
+Configuration of a particular Casual user interface is performed per mode. Go
to the *Install* section for a mode of interest below for guidance on its
configuration.
+
+- [[file:docs/agenda.org::*Install][Agenda]]
+- [[file:docs/bookmarks.org::*Install][Bookmarks]]
+- [[file:docs/calc.org::*Install][Calc]]
+- [[file:docs/dired.org::*Install][Dired]]
+- [[file:docs/editkit.org::*Install][EditKit]]
+- [[file:docs/info.org::*Install][Info]]
+- [[file:docs/isearch.org::*Install][I-Search]]
+- [[file:docs/re-builder.org::*Install][Re-Builder]]
+
+** Upgrading to Casual 2.x
+If you have installed any Casual package that is version 1.x, you should
immediately run the following command upon installation of ~casual~.
+
+~M-x~ ~casual-upgrade-base-to-version-2~
+
+This command will uninstall any Casual v1.x packages that have been superseded
by this package.
** A Note on Package Dependencies
-Casual requires Casual Lib which in turn requires a recent installation of
Transient 0.6.0+ from either
[[https://elpa.gnu.org/packages/transient.html][ELPA]] or
[[https://melpa.org/#/transient][MELPA]]. As an older version of Transient is
built-in to the Emacs release, the package manager ~package.el~ will /not/
update this package unless the customizable variable
~package-install-upgrade-built-in~ is set to ~t~. Set this variable and proceed
with installing Casual. Alternately invoking [...]
+Casual requires a recent installation of Transient 0.6.0+ from either
[[https://elpa.gnu.org/packages/transient.html][ELPA]] or
[[https://melpa.org/#/transient][MELPA]]. If your version of Emacs is ≤ 30 but
also includes Transient as a built-in package, you will need to set the
customizable variable ~package-install-upgrade-built-in~ to ~t~ to enable
updating it via ~package.el~. Set this variable and proceed with installing
Casual. Alternately invoking ~package-install~ with a prefix [...]
-As Transient is closely tied to Magit, installing the latest version of Magit
(via [[https://elpa.nongnu.org/nongnu/magit.html][non-GNU ELPA]] or
[[https://melpa.org/#/magit][MELPA]]) before installing Casual can also pick up
the latest version of Transient.
+If you already have the latest version of Magit installed (via
[[https://elpa.nongnu.org/nongnu/magit.html][non-GNU ELPA]] or
[[https://melpa.org/#/magit][MELPA]]), you can bypass the above instruction as
Magit already includes the Transient package as a dependency.
+
+* Asks
+As Casual is new, we are looking for early adopters! Your
[[https://github.com/kickingvegas/casual/discussions][feedback]] is welcome as
it will likely impact Casual's evolution, particularly with regards to UI.
* Common Menu Actions
Casual is built using Transient menus and as such adopts its default behavior.
@@ -60,8 +124,15 @@ If you enjoy using Casual, consider making a modest
financial contribution to he
[[https://www.buymeacoffee.com/kickingvegas][file:docs/images/default-yellow.png]]
* See Also
-Casual is part of a suite of user interfaces for different Emacs packages
called [[https://github.com/kickingvegas/casual-suite][Casual Suite]].
+While the package ~casual~ focuses on user interfaces for built-in Emacs
modes, there are other third party packages which receive the “Casual”
treatment. Two such packages are:
+
+- [[https://github.com/kickingvegas/casual-avy][Casual Avy]] (Elisp package:
~casual-avy~)
+ - An interface for the highly capable Avy navigation package.
+- [[https://github.com/kickingvegas/casual-symbol-overlay][Casual Symbol
Overlay]] (Elisp package: ~casual-symbol-overlay~)
+ - An interface for the Symbol Overlay package.
+
+Users interested in getting all current and future Casual interfaces for both
built-in and third party packages should install
[[https://github.com/kickingvegas/casual-suite][Casual Suite]], which includes
all of the above packages including ~casual~.
* Acknowledgments
-A heartfelt thanks to all the contributors to Emacs,
[[https://github.com/magit/transient][Transient]], Org Mode, and Magit. This
package would not be possible without your efforts.
+A heartfelt thanks to all the contributors to
[[https://github.com/magit/transient][Transient]], [[https://magit.vc][Magit]],
[[https://orgmode.org][Org Mode]], and
[[https://www.gnu.org/software/emacs/][Emacs]]. This package would not be
possible without your efforts.
diff --git a/docs/agenda.org b/docs/agenda.org
new file mode 100644
index 0000000000..016ac86363
--- /dev/null
+++ b/docs/agenda.org
@@ -0,0 +1,101 @@
+[[../README.org][❮ Back to Casual]]
+
+* Casual Agenda
+An opinionated [[https://github.com/magit/transient][Transient]]-based user
interface for [[https://orgmode.org/manual/Agenda-Views.html][Org Agenda]], a
feature of Emacs [[https://orgmode.org/features.html][Org mode]] to help plan
your day.
+
+[[file:images/casual-agenda-screenshot.png]]
+
+
+* Install
+Add these lines to your Emacs initialization file with your binding of
preference.
+#+begin_src elisp :lexical no
+ (keymap-set org-agenda-mode-map "C-o" #'casual-agenda-tmenu)
+#+end_src
+
+If you use ~use-package~, here is the recipe for installing it.
+#+begin_src elisp :lexical no
+ (use-package casual-agenda
+ :ensure nil
+ :bind (:map
+ org-agenda-mode-map
+ ("C-o" . casual-agenda-tmenu))
+ :after (org-agenda))
+#+end_src
+
+
+** Configuration
+Use these bindings to configure Org Agenda to be consistent with bindings used
by Casual Agenda. This is optional.
+
+#+begin_src elisp :lexical no
+ ; bindings to make jumping consistent between Org Agenda and Casual Agenda
+ (keymap-set org-agenda-mode-map "M-j" #'org-agenda-clock-goto) ; optional
+ (keymap-set org-agenda-mode-map "J" #'bookmark-jump) ; optional
+#+end_src
+
+If you use ~use-package~, modify your configuration as follows:
+#+begin_src elisp :lexical no
+ (use-package casual-agenda
+ :ensure nil
+ :bind (:map
+ org-agenda-mode-map
+ ("C-o" . casual-agenda-tmenu)
+ ("M-j" . org-agenda-clock-goto) ; optional
+ ("J" . bookmark-jump))) ; optional
+#+end_src
+
+
+* Usage
+
+The main menu is divided into five sections:
+
+- *Agenda* - Modify the view duration (day, week, year)
+- *Filter* - Filter displayed headlines with different criteria
+- *Actions* - Perform an activity on a headline, create/capture a headline or
even generate a different agenda view.
+- *Navigation* - move the point to where you want it to be.
+- *Utils* - Set a timer, get almanac info.
+
+** Unicode Symbol Support
+By enabling “(u) Use Unicode Symbols” from the Settings menu, Casual Agenda
will use Unicode symbols as appropriate in its menus.
+
+[[file:images/casual-agenda-unicode-screenshot.png]]
+
+
+** Operating on Headlines
+
+Use the /Operations/ menu to alter attributes about it such as TODO state,
scheduling, tags, and priority. To use it, move the point to the line of a
heading you wish to change and from the main menu select "(o) Operations". The
following menu will be displayed.
+
+[[file:images/casual-agenda-operations-screenshot.png]]
+
+** Marking Headlines
+
+User the /Mark/ menu to mark different headlines and perform a bulk action on
them. From the main menu, select "(m) Mark" to display the following menu:
+
+[[file:images/casual-agenda-mark-screenshot.png]]
+
+
+** Changing Modes and Settings
+
+Agenda views have different display modes and behavior that can be modified
from the /Settings/ menu. From the main menu, select "(,) Settings" to display
the following menu:
+
+[[file:images/casual-agenda-settings-screenshot.png]]
+
+
+** Almanac
+Get sunrise/sunset times, lunar cycle dates, and holidays with respect to a
date via the /Almanac/ menu. From the main menu, select "(l) Almanac" to
display the following menu.
+
+[[file:images/casual-agenda-almanac-screenshot.png]]
+
+
+* Sponsorship
+If you enjoy using Casual Agenda, consider making a modest financial
contribution to help support its development and maintenance.
+
+[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
+
+* See Also
+- [[file:bookmarks.org][Bookmarks]]
+- [[file:calc.org][Calc]]
+- [[file:dired.org][Dired]]
+- [[file:editkit.org][EditKit (numerous editing commands)]]
+- [[file:info.org][Info]]
+- [[file:isearch.org][I-Search]]
+- [[file:re-builder.org][Re-Builder]]
diff --git a/docs/bookmarks.org b/docs/bookmarks.org
new file mode 100644
index 0000000000..70c2739d6b
--- /dev/null
+++ b/docs/bookmarks.org
@@ -0,0 +1,93 @@
+[[../README.org][❮ Back to Casual]]
+
+* Casual Bookmarks
+An opinionated [[https://github.com/magit/transient][Transient]]-based user
interface for the Emacs
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Bookmarks.html][Bookmark]]
list.
+
+[[file:images/casual-bookmarks-screenshot.png]]
+
+* Install
+If installed via MELPA then add these lines to your Emacs initialization file
with your binding of preference.
+#+begin_src elisp :lexical no
+ (require 'casual-bookmarks) ;; optional
+ (keymap-set bookmark-bmenu-mode-map "C-o" #'casual-bookmarks-tmenu)
+#+end_src
+
+If you use ~use-package~, here is the recipe for installing and configuring it.
+#+begin_src elisp :lexical no
+ (use-package bookmark
+ :ensure nil
+ :defer t)
+ (use-package casual-bookmarks
+ :ensure t
+ :bind (:map bookmark-bmenu-mode-map
+ ("C-o" . casual-bookmarks-tmenu)
+ ("S" . casual-bookmarks-sortby-tmenu)
+ ("J" . bookmark-jump))
+ :after (bookmark))
+#+end_src
+
+** Configuration
+Use these keybindings to configure bookmark list to be consistent with
keybindings used by Casual Bookmarks.
+
+#+begin_src elisp :lexical no
+ (keymap-set bookmark-bmenu-mode-map "J" #'bookmark-jump)
+#+end_src
+
+Casual Bookmarks also includes the keymap ~casual-bookmarks-main-menu~ which
inserts a /Bookmarks/ menu into the main menu bar as shown below.
+
+[[file:images/bookmarks-main-menu.png]]
+
+To enable this, add the following configuration to your initialization file.
+
+#+begin_src elisp :lexical no
+ (require 'casual-bookmarks)
+ (easy-menu-add-item global-map '(menu-bar)
+ casual-bookmarks-main-menu
+ "Tools")
+#+end_src
+
+While not necessary, having the current bookmark highlighted is convenient.
Enable ~hl-line-mode~ for the bookmark list as shown below.
+
+#+begin_src elisp :lexical no
+ (require 'hl-line)
+ (add-hook 'bookmark-bmenu-mode-hook #'hl-line-mode)
+#+end_src
+
+Finally, customize the variable ~bookmark-save-flag~ to the value ~1~ to
ensure that your bookmark changes are always saved.
+
+The above guidance largely extends the work done in the blog post
[[http://yummymelon.com/devnull/using-bookmarks-in-emacs-like-you-do-in-web-browsers.html][Using
Bookmarks in Emacs like you do in Web Browsers]].
+
+* Usage
+
+** Unicode Symbol Support
+[[file:images/casual-bookmarks-unicode-screenshot.png]]
+
+By enabling “Use Unicode Symbols” from the Settings menu, Casual Bookmarks
will use Unicode symbols as appropriate in its menus. The following mapping is
shown in the table below:
+
+| Name | Plain | Unicode |
+|----------------------+-----------+---------|
+| :previous | Previous | ↑ |
+| :next | Next | ↓ |
+| :jump | Jump | 🚀 |
+| :beginning-of-buffer | Beginning | ⤒ |
+| :end-of-buffer | End | ⤓ |
+| :backward | Backward | ← |
+| :forward | Forward | → |
+| :narrow | Narrow | →← |
+| :widen | Widen | ←→ |
+
+* Sponsorship
+If you enjoy using Casual Bookmarks, consider making a modest financial
contribution to help support its development and maintenance.
+
+[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
+
+* See Also
+- [[file:agenda.org][Agenda]]
+- [[file:calc.org][Calc]]
+- [[file:dired.org][Dired]]
+- [[file:editkit.org][EditKit (numerous editing commands)]]
+- [[file:info.org][Info]]
+- [[file:isearch.org][I-Search]]
+- [[file:re-builder.org][Re-Builder]]
+
+
diff --git a/docs/calc.org b/docs/calc.org
new file mode 100644
index 0000000000..bb6f35271a
--- /dev/null
+++ b/docs/calc.org
@@ -0,0 +1,84 @@
+[[../README.org][❮ Back to Casual]]
+
+* Casual Calc
+An opinionated [[https://github.com/magit/transient][Transient]]-based user
interface to support the casual usage of Emacs
[[https://www.gnu.org/software/emacs/manual/html_mono/calc.html][Calc]].
+
+[[file:images/casual-calc-tmenu.png]]
+
+* Install
+Casual Calc is available on [[https://melpa.org/#/casual-calc][MELPA]].
+
+If installed via ~list-packages~ then add this line to your Emacs
initialization file.
+#+begin_src elisp :lexical no
+ (require 'casual-calc) ;; optional
+ (keymap-set calc-mode-map "C-o" #'casual-calc-tmenu)
+ (keymap-set calc-alg-map "C-o" #'casual-calc-tmenu)
+#+end_src
+
+If you use ~use-package~, here is the recipe for installing it.
+#+begin_src elisp :lexical no
+ (use-package calc
+ :defer t)
+
+ (use-package casual-calc
+ :ensure nil
+ :bind (:map
+ calc-mode-map
+ ("C-o" . casual-calc-tmenu)
+ :map
+ calc-alg-map
+ ("C-o" . casual-calc-tmenu))
+ :after (calc))
+#+end_src
+
+** A Note on Package Dependencies
+Casual Calc requires Casual Lib which in turn requires a recent installation
of Transient 0.6.0+ from either
[[https://elpa.gnu.org/packages/transient.html][ELPA]] or
[[https://melpa.org/#/transient][MELPA]]. As an older version of Transient is
built-in to the Emacs release, the package manager ~package.el~ will /not/
update this package unless the customizable variable
~package-install-upgrade-built-in~ is set to ~t~. Set this variable and proceed
with installing Casual Calc. Alternatel [...]
+
+As Transient is closely tied to Magit, installing the latest version of Magit
(via [[https://elpa.nongnu.org/nongnu/magit.html][non-GNU ELPA]] or
[[https://melpa.org/#/magit][MELPA]]) before installing Casual Calc can also
pick up the latest version of Transient.
+
+
+* Usage
+1. Invoke ~M-x calc~ to launch Calc.
+2. When the point is in the Calc window, invoke ~C-o~ (or a binding of your
choosing) to launch the Casual Calc interface.
+
+Once raised, the Casual Calc interface can be dismissed via:
+- ~C-g~ to dismiss the current menu.
+- ~C-q~ to dismiss the interface completely.
+
+For nearly all menus, algebraic entry via the ' binding is available, as well
as basic calculator operations (addition, subtraction, multiplication,
division) and stack operations (pop, enter).
+
+* Calc Basics
+It helps to know some basics about Calc.
+
+- Calc is a stack-based calculator that supports both RPN and algebraic style
entry.
+ - By default it uses RPN entry, but this can be changed to algebraic.
+- Stack based operations are always RPN-style.
+- Undo has the keybinding ~U~, redo is ~D~.
+- The top of the stack is referred to as ~1:~
+- Calc vectors are punctuated with ~[~ and ~]~ (e.g. ~[2 3]~) Matrix values
are represented as vectors within a vector. For example, ~[[1 0] [0 1]]~ is a
square diagonal matrix.
+- Calc vector indexes are 1-offset.
+- Intervals
+ - Inclusive intervals are represented as [𝑛..𝑚], where 𝑛 < 𝑚.
+ - Exclusive intervals are represented as (𝑛..𝑚), where 𝑛 < 𝑚.
+ - Any combination of lower and upper bounds set to be inclusive or exclusive
is supported.
+- Complex numbers are entered as (𝑟, 𝑖), where 𝑟 is the real part and 𝑖 is the
imaginary.
+- Radix numbers are entered as 𝑏#𝑛 where 𝑏 is the base value and 𝑛 is the
number. For example entering ~2#0101~ will put ~5~ on the stack.
+- H:M:S values are default entered as ℎ@ 𝑚" 𝑠'.
+- Org-mode active timestamps can be entered into Calc.
+- The top of the stack (1:) can be edited by pressing the ~`~ key.
+- Entering a single quote (') will prompt you for an algebraic entry.
+
+* Sponsorship
+If you enjoy using Casual Calc, consider making a modest financial
contribution to help support its development and maintenance.
+
+[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
+
+
+* See Also
+- [[file:agenda.org][Agenda]]
+- [[file:bookmarks.org][Bookmarks]]
+- [[file:dired.org][Dired]]
+- [[file:editkit.org][EditKit (numerous editing commands)]]
+- [[file:info.org][Info]]
+- [[file:isearch.org][I-Search]]
+- [[file:re-builder.org][Re-Builder]]
diff --git a/docs/developer.org b/docs/developer.org
index fabb3a2303..55f7a80856 100644
--- a/docs/developer.org
+++ b/docs/developer.org
@@ -1,10 +1,10 @@
-* Casual EditKit Development
-Casual EditKit is an open source project and as such is always open for
contributors to its development.
+* Casual Development
+Casual is an open source project and as such is always open for contributors
to its development.
This document provides guidance on how to contribute to its development from a
programming perspective.
* Development Environment
-Casual EditKit is developed primarily using a GNU toolchain. GNU tools
required are:
+Casual is developed primarily using a GNU toolchain. GNU tools required are:
- make
- awk
@@ -13,39 +13,33 @@ Casual EditKit is developed primarily using a GNU
toolchain. GNU tools required
Also needed is the Python [[https://pypi.org/project/semver/][semver]] module.
This will require an installation of Python 3.x, ideally at 3.9 or higher.
-For source code management, Casual EditKit uses ~git~.
-
-Given a clone of this repository, ensure that the directory holding
~casual-editkit.el~ is in your ~info-path~. Add the following lines to your
Emacs initialization file.
-
-#+begin_src elisp :lexical no
- (require 'casual-editkit) ;; optional
- (keymap-global-set "C-o" #'casual-editkit-main-tmenu)
-#+end_src
+For source code management, Casual uses ~git~.
+Given a clone of this repository, ensure that the directory holding
~casual.el~ is in your ~info-path~.
* Branches
-For Casual EditKit development, there are two git branches of note:
+For Casual development, there are two git branches of note:
-- [[https://github.com/kickingvegas/casual-editkit/tree/main][main]] for
releases to the general public.
--
[[https://github.com/kickingvegas/casual-editkit/tree/development][development]]
for staging of stable pre-release functionality.
+- [[https://github.com/kickingvegas/casual/tree/main][main]] for releases to
the general public.
+- [[https://github.com/kickingvegas/casual/tree/development][development]] for
staging of stable pre-release functionality.
Planned changes for the next release are done on feature branches that are
merged via pull request into ~development~. Upon QA of ~development~, those
changes are merged to ~main~ for release to the general public.
* Test Regression
-Running the Casual EditKit test regression suite is done via Makefile. In the
top-level directory of Casual EditKit, run this from the command line.
+Running the Casual test regression suite is done via Makefile. In the
top-level directory of Casual, run this from the command line.
#+begin_src text
$ make tests
#+end_src
-Casual EditKit uses the
[[https://www.gnu.org/software/emacs/manual/html_node/ert/][ERT]] framework to
compose and manage tests.
+Casual uses the
[[https://www.gnu.org/software/emacs/manual/html_node/ert/][ERT]] framework to
compose and manage tests.
One can run a test for a single file by using a "phony" target with a suffix
of ~.elt~ in the ~lisp/~ directory containing all the source files.
-For example, in the ~lisp/~ directory, run this command to exercise all tests
for functions in ~casual-editkit-version.el~.
+For example, in the ~lisp/~ directory, run this command to exercise all tests
for functions in ~casual-version.el~.
#+begin_src test
- $ make casual-editkit-version.elt
+ $ make casual-version.elt
#+end_src
@@ -53,21 +47,21 @@ For example, in the ~lisp/~ directory, run this command to
exercise all tests fo
Before you submit a pull request (PR):
-- If it is a *new* feature, please propose an
[[https://github.com/kickingvegas/casual-editkit/issues][enhancement issue]]
instead.
+- If it is a *new* feature, please propose an
[[https://github.com/kickingvegas/casual/issues][enhancement issue]] instead.
- Your enhancement issue should be in the form of a products requirement
document (PRD).
- PRs without an approved PRD associated with it will be summarily rejected.
- Contributing to code development for a PRD requires advance approval from
the maintainer. PRs submitted outside of this flow will be rejected.
- PRs must pass the test regression suite.
- New behavior introduced in a PR should have unit tests associated with it.
- - Typically this entails exercising all items in a Transient menu. Look at
usage of ~casualt-suffix-testbench-runner~ in
[[https://github.com/kickingvegas/casual-lib/blob/main/tests/casual-lib-test-utils.el][casual-lib-test-utils.el]]
to see how this is done.
+ - Typically this entails exercising all items in a Transient menu. Look at
usage of ~casualt-suffix-testbench-runner~ in ~casual-lib-test-utils.el~ to see
how this is done.
- PRs must be made against the ~development~ branch on GitHub.
- If the pull request is made against ~main~ but can be re-targeted to
~development~, it will be reviewed.
- A pull request with merge conflicts to ~development~ will be summarily
rejected.
-All of the above is intended to ensure that Casual EditKit releases are of
high quality.
+All of the above is intended to ensure that Casual releases are of high
quality.
* UX Guidelines
- Menus must not exceed 80 characters in length.
- - Rationale: Casual EditKit follows suit with current Elisp format to
conform to the line width of an ADM-3A terminal.
+ - Rationale: Casual follows suit with current Elisp format to conform to the
line width of an ADM-3A terminal.
diff --git a/docs/dired.org b/docs/dired.org
new file mode 100644
index 0000000000..38107336d5
--- /dev/null
+++ b/docs/dired.org
@@ -0,0 +1,152 @@
+[[../README.org][❮ Back to Casual]]
+
+* Casual Dired
+An opinionated [[https://github.com/magit/transient][Transient]]-based user
interface for the Emacs file manager
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Dired.html][Dired]].
+
+[[file:images/casual-dired-screenshot.png]]
+
+* Install
+If installed via MELPA then add these lines to your Emacs initialization file
with your binding of preference.
+#+begin_src elisp :lexical no
+ (require 'casual-dired)
+ (keymap-set dired-mode-map "C-o" #'casual-dired-tmenu)
+ (keymap-set dired-mode-map "s" #'casual-dired-sort-by-tmenu) ; optional
+ (keymap-set dired-mode-map "/" #'casual-dired-search-replace-tmenu) ;
optional
+#+end_src
+
+If you use ~use-package~, here is the recipe for installing it.
+#+begin_src elisp :lexical no
+ (use-package casual-dired
+ :ensure t
+ :bind (:map dired-mode-map
+ ("C-o" . #'casual-dired-tmenu)
+ ("s" . #'casual-dired-sort-by-tmenu)
+ ("/" . #'casual-dired-search-replace-tmenu)))
+#+end_src
+
+In addition to binding the main menu ~casual-dired-tmenu~, the user can also
bind the sort-by menu ~casual-dired-sort-by-tmenu~ and the search & replace
menu ~casual-dired-search-replace-tmenu~.
+
+Included is a standard keymap for Dired sorting commands
(~casual-dired-sort-menu~) which can be included in a context menu for a
mouse-driven workflow. An example of this is shown below:
+
+#+begin_src elisp :lexical no
+ (require 'casual-dired)
+
+ (defun casual-dired-context-menu-addons (menu click)
+ "Customize context MENU with CLICK event."
+ (easy-menu-add-item menu nil casual-dired-sort-menu)
+ menu)
+
+ (add-hook 'context-menu-functions #'casual-dired-context-menu-addons)
+ (add-hook 'dired-mode-hook 'context-menu-mode)
+#+end_src
+
+For users running on Microsoft Windows, use
[[https://www.gnu.org/software/emacs/manual/html_node/efaq-w32/Dired-ls.html][this
guidance]] to configure GNU ~ls~ for running with Dired.
+
+** A Note on Package Dependencies
+Casual Dired requires Casual Lib which in turn requires a recent installation
of Transient 0.6.0+ from either
[[https://elpa.gnu.org/packages/transient.html][ELPA]] or
[[https://melpa.org/#/transient][MELPA]]. As an older version of Transient is
built-in to the Emacs release, the package manager ~package.el~ will /not/
update this package unless the customizable variable
~package-install-upgrade-built-in~ is set to ~t~. Set this variable and proceed
with installing Casual Dired. Alternat [...]
+
+As Transient is closely tied to Magit, installing the latest version of Magit
(via [[https://elpa.nongnu.org/nongnu/magit.html][non-GNU ELPA]] or
[[https://melpa.org/#/magit][MELPA]]) before installing Casual Dired can also
pick up the latest version of Transient.
+
+
+* Usage
+1. Invoke ~M-x dired~ to launch Dired.
+2. When the point is in the Dired window, invoke ~C-o~ (or a binding of your
choosing) to launch the Casual Dired menu.
+
+** Enhanced Sorting
+Casual Dired offers enhanced sorting capabilities through GNU ~ls~. Use this
to sort your Dired buffer to preference. Filter dot files (.*) by disabling the
~--all~ option is available here.
+
+[[file:images/casual-dired-sort-by-screenshot.png]]
+
+With the *Sort By* menu raised, one can save the switch settings for future
use via the binding ~C-x C-s~ (~transient-save~). Note this is a global setting
and will apply to all future calls to the *Sort By* menu.
+
+** Search & Replace
+Search and replace in multiple marked files using the ~/~ /Search & Replace/
menu item. This will raise a menu of Dired commands that will work on marked
files.
+
+[[file:images/casual-dired-search-replace.png]]
+
+While most Dired commands use Emacs-style
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Regular-Expressions.html][regular
expression syntax]], there are two commands that instead take instead
*grep*-style syntax:
+
+- (~g~) Find regex… (~dired-do-find-regexp~)
+- (~G~) Find regex and replace… (~dired-do-find-regexp-and-replace~)
+
+The *grep*-style syntax is dependent on the ~grep~ implementation that is
installed and used by Emacs.
+
+** Bulk Dired Operations
+Casual Dired organizes a number of Dired commands that work on a set of marked
files. These commands are presented in the *Utils* menu.
+
+[[file:images/casual-dired-utils-screenshot.png]]
+
+* Configuration
+
+As Dired has been around for a long time, the different ways of configuring it
are myriad. Described below is a configuration used by the author that is
consistent with the bindings used in Casual Dired.
+
+** Initialization
+
+#+begin_src elisp :lexical no
+ (require 'dired)
+ (require 'dired-x)
+ (require 'wdired)
+ (require 'hl-line)
+ (require 'mouse)
+ (require 'image-dired)
+ (require 'image-dired-dired)
+ (require 'casual-dired)
+
+ (keymap-set dired-mode-map "C-o" #'casual-dired-tmenu)
+ (keymap-set dired-mode-map "s" #'casual-dired-sort-by-tmenu)
+ (keymap-set dired-mode-map "/" #'casual-dired-search-replace-tmenu)
+
+ (add-hook 'dired-mode-hook 'hl-line-mode)
+ (add-hook 'dired-mode-hook 'context-menu-mode)
+ (add-hook 'dired-mode-hook 'dired-async-mode)
+ (add-hook
+ 'dired-mode-hook
+ (lambda ()
+ (setq-local mouse-1-click-follows-link 'double)))
+
+ (keymap-set dired-mode-map "M-o" #'dired-omit-mode)
+ (keymap-set dired-mode-map "E" #'wdired-change-to-wdired-mode)
+ (keymap-set dired-mode-map "M-n" #'dired-next-dirline)
+ (keymap-set dired-mode-map "M-p" #'dired-prev-dirline)
+ (keymap-set dired-mode-map "]" #'dired-next-subdir)
+ (keymap-set dired-mode-map "[" #'dired-prev-subdir)
+ (keymap-set dired-mode-map "A-M-<mouse-1>" #'browse-url-of-dired-file)
+ (keymap-set dired-mode-map "<backtab>" #'dired-prev-subdir)
+ (keymap-set dired-mode-map "TAB" #'dired-next-subdir)
+ (keymap-set dired-mode-map "M-j" #'dired-goto-subdir)
+ (keymap-set dired-mode-map ";" #'image-dired-dired-toggle-marked-thumbs)
+
+ (keymap-set image-dired-thumbnail-mode-map "n" #'image-dired-display-next)
+ (keymap-set image-dired-thumbnail-mode-map "p"
#'image-dired-display-previous)
+#+end_src
+
+** Variables
+
+Casual Dired offers a settings menu to customize a set of commonly used Dired
variables. Use this to customize your Dired behavior to taste.
+
+[[file:images/casual-dired-settings-screenshot.png]]
+
+If you have GNU ~ls~ installed and configured, use the ~l~ key to set the
variable ~dired-use-ls-dired~ to ~t~ ("Use GNU ‘ls’ with --dired"). Otherwise
this should be disabled.
+
+** Unicode Symbol Support
+
+By enabling “Use Unicode Symbols” from the Settings menu, Casual Dired will
use Unicode symbols as appropriate in its menus. An example is shown below.
+
+[[file:images/casual-dired-screenshot-unicode.png]]
+
+To ensure proper layout and spacing, your default typeface should be
fixed-width or monospace and *must* support the Unicode symbols used.
+
+* Sponsorship
+If you enjoy using Casual Dired, consider making a modest financial
contribution to help support its development and maintenance.
+
+[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
+
+
+* See Also
+- [[file:agenda.org][Agenda]]
+- [[file:bookmarks.org][Bookmarks]]
+- [[file:calc.org][Calc]]
+- [[file:editkit.org][EditKit (numerous editing commands)]]
+- [[file:info.org][Info]]
+- [[file:isearch.org][I-Search]]
+- [[file:re-builder.org][Re-Builder]]
diff --git a/docs/editkit.org b/docs/editkit.org
new file mode 100644
index 0000000000..a3a3975c01
--- /dev/null
+++ b/docs/editkit.org
@@ -0,0 +1,182 @@
+[[../README.org][❮ Back to Casual]]
+
+* Casual EditKit
+An opinionated [[https://github.com/magit/transient][Transient]]-based user
interface library for Emacs editing commands.
+
+[[file:images/casual-editkit-main-screenshot.png]]
+
+Casual EditKit endeavors to surface the many different editing commands
offered by Emacs via Transient menus. Included in this library are menus for:
+
+- Register commands
+- Rectangle commands
+- Editing commands for words, sentences, paragraphs, and balanced expressions
(sexps), and functions (defuns).
+ - Marking
+ - Copying
+ - Killing
+ - Moving
+ - Transposing
+ - Transforming
+ - Deleting
+ - Sorting
+- Window management
+ - Creating
+ - Moving
+ - Deleting
+- Search & Replace commands
+- Open commands
+- Project commands
+- Bookmark commands
+- Emoji & Symbol Insertion (including smart quotes)
+- Tool commands
+- Macro commands
+
+A main menu (~casual-editkit-main-tmenu~) demonstrating all of the above is
provided as a reference model. This reference model can be used as is. More
motivated users can use the reference model as a template to build their own
customized menus.
+
+* Motivation
+Emacs has many commands that are easy to forget if not used frequently. Menus
are a user interface (UI) affordance that offers discoverability and
recognition that can lower its learning curve. While menus are commonly
associated with mouse-driven UI, the inclusion of Transient in Emacs core
allows for building a keyboard-driven menu UI. Casual EditKit endeavors to
offer this as many Emacs users prefer keyboard-driven workflows.
+
+** Goals
+- To provide a keyboard-driven menu UI toolkit for common Emacs editing
commands.
+- To provide casual access to the above commands.
+
+** Non-Goals
+- Full coverage of all Emacs editing commands. Casual EditKit is not intended
to be a power user tool nor is it intended to be a replacement for mouse-driven
menus.
+- Strict adherence to Emacs editing command naming. While Casual EditKit is
*mostly* in alignment with Emacs command naming, there are cases where it will
make an opinionated change if the name is deemed too vague or idiomatic.
+- UX Stability (for now). Given that Casual EditKit is early in its
life-cycle, expect changes to its user experience in terms of menu hierarchy
and keybinding choices in future releases.
+
+* Install
+Typical installation of Casual EditKit is via MELPA. A reference menu
(~casual-editkit-main-tmenu~) illustrating nearly all the different menus
offered by Casual EditKit is provided. This menu can be used “as-is” with your
binding of preference. For consistency with other Casual Packages, the binding
~C-o~ is used in the example below. Other candidate bindings include ~M-o~ and
~F10~. To facilitate default access to this menu, the configuration below sets
this binding to be global which [...]
+
+#+begin_src elisp :lexical no
+ (require 'casual-editkit) ;; optional
+ (keymap-global-set "C-o" #'casual-editkit-main-tmenu)
+#+end_src
+
+If you use ~use-package~, here is the recipe for installing and configuring it.
+#+begin_src elisp :lexical no
+ (use-package casual-editkit
+ :ensure nil
+ :bind (("C-o" . casual-editkit-main-tmenu)))
+#+end_src
+
+For motivated users desiring a bespoke solution, it is recommended that they
use Casual EditKit as a library of menus to build their own workflows.
+
+* Library Overview
+
+** Register commands (~casual-editkit-registers-tmenu~)
+Register commands for saving and recalling text, point, window configuration,
and keyboard macros are supported here.
+
+[[file:images/casual-editkit-registers-screenshot.png]]
+
+** Rectangle commands (~casual-editkit-rectangle-tmenu~)
+This menu offers all the rectangle commands. It is packaged as a sub-menu of
~casual-editkit-edit-tmenu~.
+
+[[file:images/casual-editkit-rectangle-screenshot.png]]
+
+** Edit commands (~casual-editkit-edit-tmenu~)
+This menu contains commands and sub-menus related to editing text.
+
+[[file:images/casual-editkit-edit-screenshot.png]]
+
+Depending on the buffer mode, text can be operated on with different
granularity as words, sentences, paragraphs, balanced expressions, functions
(defuns). The following sub-menus illustrate what operations can be done on the
different text granularity.
+
+*** Mark (~casual-editkit-mark-tmenu~)
+Text can be marked with different granularity with this menu. Note that
marking functions (Defun) is only supported for modes derived from ~prog-mode~.
+
+[[file:images/casual-editkit-mark-screenshot.png]]
+
+*** Copy (~casual-editkit-copy-tmenu~)
+Text can be copied with different granularity with this menu.
+[[file:images/casual-editkit-copy-screenshot.png]]
+
+*** Kill (Cut) (~casual-editkit-kill-tmenu~)
+Text can be cut (killed) with different granularity with this menu.
+[[file:images/casual-editkit-kill-screenshot.png]]
+
+*** Move (~casual-editkit-move-tmenu~)
+Text can be moved forwards or backwards with different granularity with this
menu. Note that selecting a granularity will raise another menu to allow
selection of direction (forward, backward) the text is to be moved. To enable
repeat operation, that menu is persisted and must be dismissed either with
either ~C-q~ (dismiss all) or ~C-g~ (dismiss to previous menu).
+[[file:images/casual-editkit-move-screenshot.png]]
+
+*** Transpose (~casual-editkit-transpose-tmenu~)
+Text can be transposed with different granularity with this menu.
+
+[[file:images/casual-editkit-transpose-screenshot.png]]
+
+*** Transform (~casual-editkit-transform-tmenu~)
+Text can be transformed with different granularity with this menu. Supported
transformations are capitalization, lower and upper casing of text.
+
+[[file:images/casual-editkit-transform-screenshot.png]]
+
+*** Delete (~casual-editkit-delete-tmenu~)
+Operations involving text deletion are included in this menu, including
joining lines and zapping to a character.
+
+[[file:images/casual-editkit-delete-screenshot.png]]
+
+*** Sort (~casual-editkit-sort-tmenu~)
+Sorting operations on different sections of text are supported, as well as
support for sorting off a field. Press ~?~ or ~C-h~ to get help for a specific
command.
+
+[[file:images/casual-editkit-sort-screenshot.png]]
+
+** Window management (~casual-editkit-window-tmenu~)
+This menu provides support for different Emacs window management commands.
Note that in Emacs, /window/ is defined
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Basic-Windows.html#:~:text=A%20window%20is%20an%20area,view%20several%20buffers%20at%20once.][differently]]
than its usage in contemporary graphical user interfaces.
+[[file:images/casual-editkit-window-screenshot.png]]
+
+If the variable ~casual-lib-use-unicode~ is set to ~t~, then Unicode symbols
are used in the labels.
+
+[[file:images/casual-editkit-window-unicode-screenshot.png]]
+
+*** Deletion (~casual-editkit-window-delete-tmenu~)
+This menu provides support for deleting windows.
+[[file:images/casual-editkit-window-delete-screenshot.png]]
+
+** Search & Replace commands (~casual-editkit-search-tmenu~)
+Operations related to search and replace are captured by this menu. Note that
this menu uses Transient prefix arguments (~--backward~ and ~--regexp~). This
is because some commands have variants involving direction and whether to
search using a regexp. Commands that support direction will by default operate
forward of the current point if ~--backward~ is not enabled.
+
+[[file:images/casual-editkit-search-screenshot.png]]
+
+** Open commands (~casual-editkit-open-tmenu~)
+Commands related to opening a file (either for writing or read-only) are
supported here. The *Project* sub-menu is also offered here.
+
+[[file:images/casual-editkit-open-screenshot.png]]
+
+** Project commands (~casual-editkit-project-tmenu~)
+Project-related commands are listed in this menu.
+
+[[file:images/casual-editkit-project-screenshot.png]]
+
+** Bookmark commands (~casual-editkit-bookmarks-tmenu~)
+Commands edit, add, or jump to a bookmark are captured in this menu.
+
+[[file:images/casual-editkit-bookmarks-screenshot.png]]
+
+** Emoji & Symbol Insertion (~casual-editkit-emoji-symbol-tmenu~)
+
+Insert emoji and symbol characters with this menu. Smart quotes are also
supported by this menu and can be applied to a text region.
+
+[[file:images/casual-editkit-emoji-symbols-screenshot.png]]
+
+** Tool commands (~casual-editkit-tools-tmenu~)
+This menu holds an assorted collection of different tools/utilities provided
by Emacs. Motivated users can use this Transient prefix as starting point to
create a menu customized to their needs.
+
+[[file:images/casual-editkit-tools-screenshot.png]]
+
+** Macro (~casual-editkit-macro-tmenu~)
+Commands for managing macros are provided for by this menu. Note that macro
creation commands are /not/ supported as they are tightly-bound to keybindings.
+
+[[file:images/casual-editkit-macro-screenshot.png]]
+
+
+* Sponsorship
+If you enjoy using Casual EditKit, consider making a modest financial
contribution to help support its development and maintenance.
+
+[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
+
+* See Also
+- [[file:agenda.org][Org Agenda]]
+- [[file:bookmarks.org][Bookmarks]]
+- [[file:calc.org][Calc]]
+- [[file:dired.org][Dired]]
+- [[file:info.org][Info]]
+- [[file:isearch.org][I-Search]]
+- [[file:re-builder.org][Re-Builder]]
+
diff --git a/docs/info.org b/docs/info.org
new file mode 100644
index 0000000000..75a73b8a36
--- /dev/null
+++ b/docs/info.org
@@ -0,0 +1,73 @@
+[[../README.org][❮ Back to Casual]]
+
+* Casual Info
+An opinionated [[https://github.com/magit/transient][Transient]]-based user
interface for the Emacs
[[https://www.gnu.org/software/emacs/manual/html_node/info/][Info]] reader.
+
+[[file:images/casual-info-screenshot.png]]
+
+* Install
+If installed via MELPA then add these lines to your Emacs initialization file
with your binding of preference.
+#+begin_src elisp :lexical no
+ (require 'casual-info) ;; optional
+ (keymap-set Info-mode-map "C-o" #'casual-info-tmenu)
+#+end_src
+
+If you use ~use-package~, here is the recipe for installing it.
+#+begin_src elisp :lexical no
+ (use-package casual-info
+ :ensure t
+ :bind (:map Info-mode-map ("C-o" . 'casual-info-tmenu)))
+#+end_src
+
+** A Note on Package Dependencies
+Casual Info requires Casual Lib which in turn requires a recent installation
of Transient 0.6.0+ from either
[[https://elpa.gnu.org/packages/transient.html][ELPA]] or
[[https://melpa.org/#/transient][MELPA]]. As an older version of Transient is
built-in to the Emacs release, the package manager ~package.el~ will /not/
update this package unless the customizable variable
~package-install-upgrade-built-in~ is set to ~t~. Set this variable and proceed
with installing Casual Info. Alternatel [...]
+
+As Transient is closely tied to Magit, installing the latest version of Magit
(via [[https://elpa.nongnu.org/nongnu/magit.html][non-GNU ELPA]] or
[[https://melpa.org/#/magit][MELPA]]) before installing Casual Info can also
pick up the latest version of Transient.
+
+** Customization
+While not required, adding this configuration to your Emacs initialization
file will synchronize keybindings between Casual Info and the Info reader. A
nice visual improvement is to use ~hl-line-mode~ to highlight the line where
the cursor is at. Enabling ~scroll-lock-mode~ will enable scrolling the buffer
for content that is larger than its window size with the navigation keys.
+
+#+begin_src elisp :lexical no
+ ;; # Info
+ ;; Use web-browser history navigation bindings
+ (keymap-set Info-mode-map "M-[" #'Info-history-back)
+ (keymap-set Info-mode-map "M-]" #'Info-history-forward)
+ ;; Bind p and n to paragraph navigation
+ (keymap-set Info-mode-map "p" #'casual-info-browse-backward-paragraph)
+ (keymap-set Info-mode-map "n" #'casual-info-browse-forward-paragraph)
+ ;; Bind h and l to navigate to previous and next nodes
+ ;; Bind j and k to navigate to next and previous references
+ (keymap-set Info-mode-map "h" #'Info-prev)
+ (keymap-set Info-mode-map "j" #'Info-next-reference)
+ (keymap-set Info-mode-map "k" #'Info-prev-reference)
+ (keymap-set Info-mode-map "l" #'Info-next)
+ ;; Bind / to search
+ (keymap-set Info-mode-map "/" #'Info-search)
+ ;; Set Bookmark
+ (keymap-set Info-mode-map "B" #'bookmark-set)
+
+ (add-hook 'Info-mode-hook #'hl-line-mode)
+ (add-hook 'Info-mode-hook #'scroll-lock-mode)
+#+end_src
+
+
+* Usage
+1. Invoke ~M-x info~ to launch the Info reader.
+2. When the point is in the Info window, invoke ~C-o~ (or a binding of your
choosing) to launch the Casual Info menu.
+
+** Unicode Symbol Support
+By enabling “Use Unicode Symbols” from the Settings menu, Casual Info will use
Unicode symbols as appropriate in its menus.
+
+* Sponsorship
+If you enjoy using Casual Info, consider making a modest financial
contribution to help support its development and maintenance.
+
+[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
+
+* See Also
+- [[file:agenda.org][Agenda]]
+- [[file:bookmarks.org][Bookmarks]]
+- [[file:calc.org][Calc]]
+- [[file:dired.org][Dired]]
+- [[file:editkit.org][EditKit (numerous editing commands)]]
+- [[file:isearch.org][I-Search]]
+- [[file:re-builder.org][Re-Builder]]
diff --git a/docs/isearch.org b/docs/isearch.org
new file mode 100644
index 0000000000..5e30a01ae7
--- /dev/null
+++ b/docs/isearch.org
@@ -0,0 +1,79 @@
+[[../README.org][❮ Back to Casual]]
+
+* Casual I-Search
+
+This package contains a [[https://github.com/magit/transient][Transient]] menu
for I-Search. When in basic I-Search mode, this menu can be raised by pressing
the ~C-o~ key. A menu of different isearch commands will be offered as shown
below:
+
+[[file:images/casual-isearch-tmenu.png]]
+
+* Install
+Use the following lines to install casual-isearch-tmenu.
+#+begin_src elisp :lexical yes
+ (require 'casual-isearch)
+ (keymap-set isearch-mode-map "C-o" #'casual-isearch-tmenu)
+#+end_src
+
+Alternately install with ~use-package~ using the following initialization:
+#+begin_src elisp :lexical no
+ (use-package casual-isearch
+ :ensure t
+ :bind (:map isearch-mode-map ("C-o" . casual-isearch-tmenu)))
+#+end_src
+
+The keybinding to ~casual-isearch-tmenu~ can be changed to user preference.
+
+
+
+* Menu Commands
+The following I-Search commands are grouped as follows in the Transient menu
~casual-isearch-tmenu~. Keys associated with each command are shown enclosed in
parentheses.
+
+** Edit Search String
+- ~isearch-edit-string~ (~e~)
+- ~isearch-yank-word-or-char~ (~w~)
+- ~isearch-yank-symbol-or-char~ (~s~)
+- ~isearch-yank-line~ (~l~)
+- ~isearch-yank-kill~ (~y~)
+- ~isearch-forward-thing-at-point~ (~t~)
+** Replace
+- ~isearch-query-replace~ (~r~)
+- ~isearch-query-replace-regexp~ (~x~)
+** Toggle
+- ~isearch-toggle-regexp~ (~X~)
+- ~isearch-toggle-symbol~ (~S~)
+- ~isearch-toggle-word~ (~W~)
+- ~isearch-toggle-case-fold~ (~F~)
+- ~isearch-toggle-lax-whitespace~ (~L~)
+** Misc
+- ~isearch-occur~ (~o~)
+- ~isearch-highlight-regexp~ (~h~)
+- ~isearch-highlight-lines-matching-regexp~ (~H~)
+- ~unhighlight-regexp~ (~u~)
+** Navigation
+- ~isearch-repeat-forward~ (~n~)
+- ~isearch-repeat-backward~ (~p~)
+
+** Exit
+To exit search, press the ~RET~ key. This will leave the point at the last
successful search item.
+
+
+* Usage
+When in search mode (typically via the keybinding ~C-s~ or ~C-r~), pressing
the keybinding ~C-o~ (or binding of your preference) will raise the Transient
menu ~casual-isearch-tmenu~. Once raised, only the /I-Search/ commands in the
*Replace* and *Misc* sections will automatically dismiss the menu when
selected. All other /I-Search/ commands will /not/ dismiss the menu.
+
+Note that editing the search text via ~isearch-edit-string~ will enter a
recursive editing mode that is normally exited when pressing the return (~RET~)
key.
+
+Use ~C-g~ to dismiss this Transient menu.
+
+* Sponsorship
+If you enjoy using Casual I-Search, consider making a modest financial
contribution to help support its development and maintenance.
+
+[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
+
+
+* See Also
+- [[file:agenda.org][Agenda]]
+- [[file:bookmarks.org][Bookmarks]]
+- [[file:calc.org][Calc]]
+- [[file:dired.org][Dired]]
+- [[file:editkit.org][EditKit (numerous editing commands)]]
+- [[file:info.org][Info]]
+- [[file:re-builder.org][Re-Builder]]
diff --git a/docs/re-builder.org b/docs/re-builder.org
new file mode 100644
index 0000000000..c9f1de35a8
--- /dev/null
+++ b/docs/re-builder.org
@@ -0,0 +1,89 @@
+[[../README.org][❮ Back to Casual]]
+
+* Casual RE-Builder
+An opinionated [[https://github.com/magit/transient][Transient]]-based user
interface for
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Regular-Expressions.html][RE-Builder]],
a tool for building Emacs regular expressions (regexps).
+
+[[file:images/casual-re-builder-screenshot.png]]
+
+* Install
+If installed via [[https://melpa.org/#/casual-re-builder][MELPA]] then add
these lines to your Emacs initialization file with your binding of preference.
+#+begin_src elisp :lexical no
+ (require 'casual-re-builder) ;; optional
+ (keymap-set reb-mode-map "C-o" #'casual-re-builder-tmenu)
+ (keymap-set reb-lisp-mode-map "C-o" #'casual-re-builder-tmenu)
+#+end_src
+
+If you use ~use-package~, here is the recipe for installing and configuring
it.
+#+begin_src elisp :lexical no
+ (use-package re-builder
+ :defer t)
+
+ (use-package casual-re-builder
+ :ensure t
+ :bind (:map
+ reb-mode-map ("C-o" . casual-re-builder-tmenu)
+ :map
+ reb-lisp-mode-map ("C-o" . casual-re-builder-tmenu))
+ :after (re-builder))
+#+end_src
+
+** A Note on Package Dependencies
+Casual RE-Builder requires Casual Lib which in turn requires a recent
installation of Transient 0.6.0+ from either
[[https://elpa.gnu.org/packages/transient.html][ELPA]] or
[[https://melpa.org/#/transient][MELPA]]. As an older version of Transient is
built-in to the Emacs release, the package manager ~package.el~ will /not/
update this package unless the customizable variable
~package-install-upgrade-built-in~ is set to ~t~. Set this variable and proceed
with installing Casual RE-Builder [...]
+
+As Transient is closely tied to Magit, installing the latest version of Magit
(via [[https://elpa.nongnu.org/nongnu/magit.html][non-GNU ELPA]] or
[[https://melpa.org/#/magit][MELPA]]) before installing Casual RE-Builder can
also pick up the latest version of Transient.
+
+* Usage
+
+** Basic Usage
+When the command ~re-builder~ is invoked, a buffer named "✳︎RE-Builder✳︎" is
created. Activate Casual RE-Builder with the binding ~C-o~ (or one of your
preference).
+
+At the top of the menu shows the title "RE-Builder" with the target buffer
enclosed in parenthesis. The regexp pattern will be applied to the target
buffer. The target buffer can be changed with the /(b) Target buffer/ menu item.
+
+Emacs supports three different regexp syntax: 1) read, 2) string, 3) Rx. Use
the /(x) Syntax/ menu item to alter it. The current syntax is shown in
parenthesis.
+
+If multiple sub-expressions are in the regexp pattern, then they can be
observed via the /(s) Subexp mode/ menu item.
+
+If the regexp pattern entered in the "✳︎RE-Builder✳︎" finds multiple matches,
a match can be navigated to via the /(p) Previous/ and /(n) Next/ menu items.
+
+** Exporting the Regexp Pattern
+Once a desired regexp pattern is defined, there are two menu items that can be
used to export (copy) it to the kill-ring for further use.
+
+- /(w) Interactive/ will copy the regexp to the kill-ring so that it can be
yanked in an interactive command that requires a regexp (e.g.
~query-replace-regexp~).
+ - This can only be used when the regexp syntax is set to ~string~.
+ - ❗️When yanking (typically ~C-y~) a regexp into an interactive prompt, you
/must/ have the point/focus in the minibuffer prompt (typically via mouse).
Otherwise the desired content can be altered with extra escaping.
+- /(c) Code/ will copy the regexp to the kill-ring so that it can be yanked
into a Elisp code that requires a regexp argument.
+- /(g) Interactive grep/ will copy the regexp so that it can be used with
command that take a GNU grep regex argument.
+ - Example commands that do this are ~dired-do-find-regexp~ and
~dired-do-find-regexp-and-replace~.
+ - This command presumes that you have GNU grep installed and configured for
use by Emacs.
+ - ❗️At current this is an experimental feature. The regexp exported from
RE-Builder may not work. If so please report an
[[https://github.com/kickingvegas/casual-re-builder/issues][issue]] describing
the desired regexp and the target text.
+ - This can only be used when the regexp syntax is set to ~string~.
+
+** Regexp Syntax Help
+The menu item /(i)/ will invoke the Info page for regexp syntax with respect
to the current syntax type.
+
+** Quitting RE-Builder
+Select /(q) Quit/ to exit the RE-Builder tool.
+
+** Unicode Symbol Support
+By enabling “Use Unicode Symbols” from the Settings menu, Casual RE-Builder
will use Unicode symbols as appropriate in its menus. The following mapping is
shown in the table below:
+
+| Name | Plain | Unicode |
+|-----------+----------+---------|
+| :previous | Previous | ↑ |
+| :next | Next | ↓ |
+
+* Sponsorship
+If you enjoy using Casual RE-Builder, consider making a modest financial
contribution to help support its development and maintenance.
+
+[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
+
+* See Also
+- [[file:agenda.org][Agenda]]
+- [[file:bookmarks.org][Bookmarks]]
+- [[file:calc.org][Calc]]
+- [[file:dired.org][Dired]]
+- [[file:editkit.org][EditKit (numerous editing commands)]]
+- [[file:info.org][Info]]
+- [[file:isearch.org][I-Search]]
+
+
diff --git a/lisp/casual-agenda.el b/lisp/casual-agenda.el
index 81f163edad..a6ee79c10c 100644
--- a/lisp/casual-agenda.el
+++ b/lisp/casual-agenda.el
@@ -3,7 +3,6 @@
;; Copyright (C) 2024 Charles Choi
;; Author: Charles Choi <[email protected]>
-;; URL: https://github.com/kickingvegas/casual-agenda
;; Keywords: tools
;; This program is free software; you can redistribute it and/or modify
diff --git a/lisp/casual-bookmarks.el b/lisp/casual-bookmarks.el
index 444c86024c..428ba48f98 100644
--- a/lisp/casual-bookmarks.el
+++ b/lisp/casual-bookmarks.el
@@ -3,7 +3,6 @@
;; Copyright (C) 2024 Charles Choi
;; Author: Charles Choi <[email protected]>
-;; URL: https://github.com/kickingvegas/casual-bookmarks
;; Keywords: tools
;; This program is free software; you can redistribute it and/or modify
diff --git a/lisp/casual-calc-labels.el b/lisp/casual-calc-labels.el
index 466817e133..9b6a322fc1 100644
--- a/lisp/casual-calc-labels.el
+++ b/lisp/casual-calc-labels.el
@@ -25,6 +25,7 @@
;;; Code:
(require 'calc)
(require 'calc-math)
+(require 'casual-calc-utils)
;; !!! While not a label function, it is called from modules that call labels.
(defun casual-calc-open-settings-file ()
diff --git a/lisp/casual-calc.el b/lisp/casual-calc.el
index 31ceddf921..c504481add 100644
--- a/lisp/casual-calc.el
+++ b/lisp/casual-calc.el
@@ -1,9 +1,8 @@
-;;; casual-calc.el --- Transient UI for Calc -*- lexical-binding:
t; -*-
+;;; casual-calc.el --- Transient UI for Calc -*- lexical-binding: t; -*-
;; Copyright (C) 2024 Charles Choi
;; Author: Charles Choi <[email protected]>
-;; URL: https://github.com/kickingvegas/casual-calc
;; Keywords: tools
;; This program is free software; you can redistribute it and/or modify
diff --git a/lisp/casual-dired.el b/lisp/casual-dired.el
index b6e9f9a993..ed3a26f884 100644
--- a/lisp/casual-dired.el
+++ b/lisp/casual-dired.el
@@ -3,7 +3,6 @@
;; Copyright (C) 2024 Charles Choi
;; Author: Charles Choi <[email protected]>
-;; URL: https://github.com/kickingvegas/casual-dired
;; Keywords: tools
;; This program is free software; you can redistribute it and/or modify
diff --git a/lisp/casual-editkit-utils.el b/lisp/casual-editkit-utils.el
index 3d59fad00f..4cb1286c35 100644
--- a/lisp/casual-editkit-utils.el
+++ b/lisp/casual-editkit-utils.el
@@ -27,10 +27,6 @@
(require 'org-agenda)
(require 'recentf)
(require 'simple)
-(require 'magit-status)
-(require 'magit-files)
-(require 'symbol-overlay)
-(require 'transpose-frame)
(require 'casual-lib)
(require 'casual-editkit-constants)
@@ -61,17 +57,50 @@
"Predicate for `buffer-read-only'."
(if buffer-read-only t nil))
+(defun casual-editkit-package-symbol-overlay-installed-p ()
+ "Predicate to test if package `symbol-overlay' is installed."
+ (package-installed-p 'symbol-overlay))
+
+(defun casual-editkit-package-magit-installed-p ()
+ "Predicate to test if package `magit' is installed."
+ (package-installed-p 'magit))
+
+(defun casual-editkit-package-transpose-frame-installed-p ()
+ "Predicate to test if package `transpose-frame' is installed."
+ (package-installed-p 'transpose-frame))
+
+(defun casual-editkit-transpose-frame ()
+ "Dynamically dispatch command call to `transpose-frame'."
+ (interactive)
+ (if (fboundp 'transpose-frame)
+ (call-interactively #'transpose-frame) ; autoloaded
+ (message "%s not installed. Unable to call %s"
+ (symbol-name 'transpose-frame)
+ (symbol-name 'transpose-frame))))
+
+(defun casual-editkit-symbol-overlay-put ()
+ "Dynamically dispatch command call to `symbol-overlay'."
+ (interactive)
+ (if (fboundp 'symbol-overlay-put)
+ (call-interactively #'symbol-overlay-put) ; autoloaded
+ (message "%s not installed. Unable to call %s"
+ (symbol-name 'symbol-overlay)
+ (symbol-name 'symbol-overlay-put))))
+
(defun casual-editkit-select-magit-command ()
- "Select appropriate Magit command given context."
+ "Dynamically dispatch appropriate Magit command call given context."
(interactive)
(if (casual-editkit-version-controlled-p)
(cond
- ((derived-mode-p 'dired-mode) (funcall-interactively #'magit-status))
- ((or (derived-mode-p 'prog-mode)
- (derived-mode-p 'text-mode))
- (funcall-interactively #'magit-file-dispatch))
- (t (funcall-interactively #'magit-status)))
-
+ ((derived-mode-p 'dired-mode)
+ (if (fboundp 'magit-status)
+ (funcall-interactively #'magit-status)))
+ ((or (derived-mode-p 'prog-mode) (derived-mode-p 'text-mode))
+ (if (fboundp 'magit-file-dispatch)
+ (funcall-interactively #'magit-file-dispatch)))
+ (t
+ (if (fboundp 'magit-status)
+ (funcall-interactively #'magit-status))))
(message "Not a version controlled buffer.")))
(defun casual-editkit-select-magit-command-description ()
@@ -440,7 +469,8 @@ Commands pertaining to window management operations can be
accessed here."
:description (lambda () (casual-editkit-unicode-get
:split-window-horizontally)))]
["Misc"
- ("t" "Transpose" transpose-frame)
+ ("t" "Transpose" casual-editkit-transpose-frame
+ :if casual-editkit-package-transpose-frame-installed-p)
;; ("T" "Toggle Tab Bar" mac-toggle-tab-bar
;; :if casual-editkit-window-system-mac-p)
;;("J" "Jump to Window…" ace-select-window)
diff --git a/lisp/casual-editkit.el b/lisp/casual-editkit.el
index 076772daee..be3537ee85 100644
--- a/lisp/casual-editkit.el
+++ b/lisp/casual-editkit.el
@@ -3,7 +3,6 @@
;; Copyright (C) 2024 Charles Choi
;; Author: Charles Choi <[email protected]>
-;; URL: https://github.com/kickingvegas/casual-editkit
;; Keywords: tools, wp
;; This program is free software; you can redistribute it and/or modify
@@ -90,8 +89,11 @@ user-customized menu."
("C" "Compile…" compile)
("g" "Magit Status" casual-editkit-select-magit-command
:description casual-editkit-select-magit-command-description
- :if casual-editkit-version-controlled-p)
- ("h" "Highlight Symbol" symbol-overlay-put)]]
+ :if (lambda ()
+ (and (casual-editkit-package-magit-installed-p)
+ (casual-editkit-version-controlled-p))))
+ ("h" "Highlight Symbol" casual-editkit-symbol-overlay-put
+ :if casual-editkit-package-symbol-overlay-installed-p)]]
[[;;"Bookmarks"
("B" "Bookmarks›" casual-editkit-bookmarks-tmenu)
diff --git a/lisp/casual-ibuffer.el b/lisp/casual-ibuffer.el
index 38c9994a30..15131a3d6f 100644
--- a/lisp/casual-ibuffer.el
+++ b/lisp/casual-ibuffer.el
@@ -3,7 +3,6 @@
;; Copyright (C) 2024 Charles Choi
;; Author: Charles Choi <[email protected]>
-;; URL: https://github.com/kickingvegas/casual-ibuffer
;; Keywords: tools
;; This program is free software; you can redistribute it and/or modify
diff --git a/lisp/casual-info.el b/lisp/casual-info.el
index 6cc42c7eff..67bcdebd1c 100644
--- a/lisp/casual-info.el
+++ b/lisp/casual-info.el
@@ -3,7 +3,6 @@
;; Copyright (C) 2024 Charles Choi
;; Author: Charles Choi <[email protected]>
-;; URL: https://github.com/kickingvegas/casual-info
;; Keywords: tools
;; This program is free software; you can redistribute it and/or modify
diff --git a/lisp/casual-isearch.el b/lisp/casual-isearch.el
index 0d8485fb3b..9045ec442b 100644
--- a/lisp/casual-isearch.el
+++ b/lisp/casual-isearch.el
@@ -3,7 +3,6 @@
;; Copyright (C) 2023-2024 Charles Choi
;; Author: Charles Choi <[email protected]>
-;; URL: https://github.com/kickingvegas/casual-isearch
;; Keywords: wp
;; This program is free software; you can redistribute it and/or modify
diff --git a/lisp/casual-lib.el b/lisp/casual-lib.el
index 0696d7d6d9..99fec4bbe7 100644
--- a/lisp/casual-lib.el
+++ b/lisp/casual-lib.el
@@ -3,7 +3,6 @@
;; Copyright (C) 2024 Charles Choi
;; Author: Charles Choi <[email protected]>
-;; URL: https://github.com/kickingvegas/casual-lib
;; Keywords: tools
;; This program is free software; you can redistribute it and/or modify
@@ -32,6 +31,9 @@
;;; Code:
(require 'transient)
+(defgroup casual nil
+ "Settings for Casual user interfaces."
+ :group 'convenience)
(defcustom casual-lib-hide-navigation nil
"If non-nil then hide navigation controls.
@@ -80,7 +82,7 @@ plain ASCII-range string."
;; Predicates
(defun casual-lib-display-line-numbers-mode-p ()
"Predicate to test if `display-line-numbers-mode' is enabled."
- (if display-line-numbers t nil))
+ (bound-and-true-p display-line-numbers))
(defun casual-lib-buffer-writeable-p ()
"Predicate to test if buffer is writeable."
diff --git a/lisp/casual-re-builder.el b/lisp/casual-re-builder.el
index b506b96bec..41c53bd178 100644
--- a/lisp/casual-re-builder.el
+++ b/lisp/casual-re-builder.el
@@ -3,7 +3,6 @@
;; Copyright (C) 2024 Charles Choi
;; Author: Charles Choi <[email protected]>
-;; URL: https://github.com/kickingvegas/casual-re-builder
;; Keywords: tools
;; This program is free software; you can redistribute it and/or modify
diff --git a/lisp/casual.el b/lisp/casual.el
index 3c0139cc2d..1fb8e12816 100644
--- a/lisp/casual.el
+++ b/lisp/casual.el
@@ -5,8 +5,8 @@
;; Author: Charles Choi <[email protected]>
;; URL: https://github.com/kickingvegas/casual
;; Keywords: tools, wp
-;; Version: 0.1.0
-;; Package-Requires: ((emacs "29.1") (transient "0.6.0") (org "9.7.1"))
+;; Version: 1.1.1-rc.1
+;; Package-Requires: ((emacs "29.1") (transient "0.6.0"))
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
@@ -23,11 +23,142 @@
;;; Commentary:
-;; Casual EditKit is a Transient user interface toolkit for Emacs editing.
+;; Casual is a collection of opinionated Transient-based keyboard driven user
+;; interfaces for various built-in modes.
;; INSTALLATION
+;; Casual is organized into different user interface (UI) libraries tuned for
+;; different modes. Different user interfaces for the following modes are
+;; supported:
+
+;; - Agenda (Elisp library: `casual-agenda')
+;; An interface for Org Agenda to help you plan your day.
+;; URL `https://github.com/kickingvegas/casual/docs/agenda.org'
+
+;; - Bookmarks (Elisp library: `casual-bookmarks')
+;; An interface for editing your bookmark collection.
+;; URL `https://github.com/kickingvegas/casual/docs/bookmarks.org'
+
+;; - Calc (Elisp library: `casual-calc')
+;; An interface for Emacs Calc, an embarrasingly feature-rich calculator.
+;; URL `https://github.com/kickingvegas/casual/docs/calc.org'
+
+;; - Dired (Elisp library: `casual-dired')
+;; An interface for the venerable file manager Dired.
+;; URL `https://github.com/kickingvegas/casual/docs/dired.org'
+
+;; - EditKit (Elisp library: `casual-editkit')
+;; A cornucopia of interfaces for the different editing features (e.g.
+;; marking, copying, killing, duplicating, transforming, deleting) of Emacs.
+;; Included are interfaces for rectangle, register, macro, and project
+;; commands.
+;; URL `https://github.com/kickingvegas/casual/docs/editkit.org'
+
+;; - Info (Elisp library: `casual-info')
+;; An interface for the Info documentation system.
+;; URL: `https://github.com/kickingvegas/casual/docs/info.org'
+
+;; - I-Search (Elisp library: `casual-isearch')
+;; An interface for the many commands supported by I-Search.
+;; URL: `https://github.com/kickingvegas/casual/docs/isearch.org'
+
+;; - Re-Builder (Elisp library: `casual-re-builder')
+;; An interface for the Emacs regular expression tool.
+;; URL: `https://github.com/kickingvegas/casual/docs/re-builder.org'
+
+;; Users can choose any or all of the user interfaces made available by Casual
+;; at their pleasure.
+
+;; UPGRADING to Casual 2.x
+
+;; If you have installed any Casual package that is version 1.x, you should
+;; immediately run the following command upon installation of casual.
+
+;; M-x casual-upgrade-base-to-version-2
+
+;; This command will uninstall any Casual v1.x packages that have been
+;; superseded by this package.
+
;;; Code:
(require 'casual-lib)
+
+(defun casual-upgrade-base-to-version-2 (enable)
+ "Upgrade base Casual packages to version 2 if ENABLE is t.
+
+Use this command to migrate your current Casual version 1.x
+packages to the consolidated organization of version 2.x.
+
+This will delete the following packages:
+
+casual-agenda, casual-bookmarks, casual-calc, casual-dired,
+casual-editkit, casual-ibuffer, casual-info, casual-isearch,
+casual-re-builder, casual-lib.
+
+Note that the package casual-lib will not be deleted if any of the packages
+casual-suite, casual-avy, or casual-symbol-overlay is installed."
+ (interactive
+ (list (y-or-n-p "Upgrade Casual to version 2?")))
+
+ (when enable
+ (let ((pkglist (list
+ 'casual-agenda
+ 'casual-bookmarks
+ 'casual-calc
+ 'casual-dired
+ 'casual-editkit
+ 'casual-ibuffer
+ 'casual-info
+ 'casual-isearch
+ 'casual-re-builder)))
+ (mapc (lambda (pkg)
+ (when (package-installed-p pkg)
+ (display-warning
+ :warning
+ (format
+ "Casual 2.0 Migration: Deleting obsolete package %s"
+ (symbol-name pkg)))
+ (package-delete (package-get-descriptor pkg) t)
+ (package-refresh-contents)))
+ pkglist))
+
+ (let* ((pkglist (list
+ 'casual-suite
+ 'casual-avy
+ 'casual-symbol-overlay))
+ (test (seq-reduce (lambda (a b) (or a b))
+ (mapcar #'package-installed-p pkglist)
+ nil)))
+ ;; TODO: add this logic to upgrade existing 3rd party packages when they
are ready.
+ ;; (mapc (lambda (pkg)
+ ;; (when (package-installed-p pkg)
+ ;; (display-warning
+ ;; :warning
+ ;; (format
+ ;; "Casual 2.0 Migration: Upgrading package %s"
+ ;; (symbol-name pkg)))
+ ;; (package-upgrade pkg)))
+ ;; pkglist)
+
+ ;; TODO: change logic to delete casual-lib when 3rd party packages are
updated.
+ (when (and (not test) (package-installed-p 'casual-lib))
+ (display-warning
+ :warning
+ (format
+ "Casual 2.0 Migration: Deleting obsolete package %s"
+ (symbol-name 'casual-lib)))
+ (package-delete (package-get-descriptor 'casual-lib) t)
+ (package-refresh-contents)))))
+
+(defun casual-get-package-version (pkg)
+ "Get package version of symbol PKG."
+ (let* ((pkg-name (symbol-name pkg))
+ (pkg-buf (find-library pkg-name))
+ (buflist (list pkg-name)))
+ (with-current-buffer pkg-buf
+ (push (package-get-version) buflist))
+ (kill-buffer pkg-buf)
+ (string-join (reverse buflist) "-")))
+
(provide 'casual)
;;; casual.el ends here
diff --git a/scripts/read-version.sh b/scripts/read-version.sh
index f58f0ce36d..ded2cf2b41 100755
--- a/scripts/read-version.sh
+++ b/scripts/read-version.sh
@@ -15,4 +15,4 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <https://www.gnu.org/licenses/>.
-grep 'Version: ' $1 | awk '{print $3}'
+awk '/Version: / {print $3}' $1
diff --git a/tests/test-casual-editkit.el b/tests/test-casual-editkit.el
index d32f9b1e92..a25a96d937 100644
--- a/tests/test-casual-editkit.el
+++ b/tests/test-casual-editkit.el
@@ -32,6 +32,8 @@
(let ((tmpfile "casual-editkit-main-tmenu.txt"))
(casualt-editkit-setup tmpfile)
(cl-letf (((symbol-function #'casual-editkit-version-controlled-p) (lambda
() t))
+ ((symbol-function
#'casual-editkit-package-symbol-overlay-installed-p) (lambda () t))
+ ((symbol-function #'casual-editkit-package-magit-installed-p)
(lambda () t))
(casualt-mock #'find-file)
(casualt-mock #'dired-jump-other-window)
(casualt-mock #'ibuffer)
@@ -73,7 +75,7 @@
(:binding "a" :command org-agenda)
(:binding "C" :command compile)
(:binding "g" :command casual-editkit-select-magit-command)
- (:binding "h" :command symbol-overlay-put)
+ (:binding "h" :command casual-editkit-symbol-overlay-put)
(:binding "B" :command casual-editkit-bookmarks-tmenu)
(:binding "J" :command bookmark-jump)
![https://www.buymeacoffee.com/kickingvegas][file:docs/images/default-yellow.png](https://www.buymeacoffee.com/kickingvegas][file:docs/images/default-yellow.png){kind=link}
![https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png](https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png){kind=link}