branch: master commit f058606a3b86d9a810d0c5da051d701e2248d0f1 Merge: 28863f3 7c6c2bf Author: Ian Dunn <du...@gnu.org> Commit: Ian Dunn <du...@gnu.org>
Merge commit '7c6c2bf1b6eab973e61ff3cacfac47183279a898' --- packages/hook-helpers/.gitignore | 3 +- packages/hook-helpers/hook-helpers.el | 16 +- packages/hook-helpers/hook-helpers.info | 283 ++++++++++++++++++++++++++++++++ packages/hook-helpers/hook-helpers.org | 50 +++++- 4 files changed, 339 insertions(+), 13 deletions(-) diff --git a/packages/hook-helpers/.gitignore b/packages/hook-helpers/.gitignore index 1af0c54..bf6ec2f 100644 --- a/packages/hook-helpers/.gitignore +++ b/packages/hook-helpers/.gitignore @@ -1,2 +1,3 @@ *.elc -hook-helpers.html \ No newline at end of file +hook-helpers.html +hook-helpers.texi \ No newline at end of file diff --git a/packages/hook-helpers/hook-helpers.el b/packages/hook-helpers/hook-helpers.el index 82a8667..00bce04 100644 --- a/packages/hook-helpers/hook-helpers.el +++ b/packages/hook-helpers/hook-helpers.el @@ -1,15 +1,15 @@ ;;; hook-helpers.el --- Anonymous, modifiable hook functions -*- lexical-binding: t; -*- -;; Copyright (C) 2016-2017 Free Software Foundation, Inc. +;; Copyright (C) 2016-2018 Free Software Foundation, Inc. ;; Author: Ian Dunn <du...@gnu.org> ;; Maintainer: Ian Dunn <du...@gnu.org> ;; Keywords: development, hooks ;; Package-Requires: ((emacs "25.1")) ;; URL: https://savannah.nongnu.org/projects/hook-helpers-el/ -;; Version: 1.1 +;; Version: 1.1.1 ;; Created: 06 May 2016 -;; Modified: 23 Apr 2017 +;; Modified: 11 Feb 2018 ;; 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 @@ -39,7 +39,11 @@ ;;; Code: -(require 'subr-x) +(eval-when-compile (require 'subr-x)) + +;; Compatibility for Emacs < 26.1 +(unless (fboundp 'when-let*) + (defalias 'when-let* 'when-let)) (defvar hkhlp--helpers-map nil "Map of IDs to helpers.") @@ -101,7 +105,7 @@ For each hook HOOK in the original: ((not hook-val) nil) ((member hook new-hooks) ;; Update the helper in hooks - (when-let ((elt (cl-position old-func hook-val :test 'equal))) + (when-let* ((elt (cl-position old-func hook-val :test 'equal))) (setf (nth elt hook-val) new-func))) (t ;; Delete the helper from the hooks @@ -138,7 +142,7 @@ See `hkhlp-normalize-hook-spec' for an explanation of HOOKS. :source-file source-file :hooks (mapcar 'car normalized-hooks)))) ;; Update an old helper - (when-let ((old-helper (alist-get id-sym hkhlp--helpers-map))) + (when-let* ((old-helper (alist-get id-sym hkhlp--helpers-map))) (hkhlp-update-helper old-helper helper)) (setf (alist-get id-sym hkhlp--helpers-map) helper) ;; Add to the new hook-spec diff --git a/packages/hook-helpers/hook-helpers.info b/packages/hook-helpers/hook-helpers.info new file mode 100644 index 0000000..5cf10ce --- /dev/null +++ b/packages/hook-helpers/hook-helpers.info @@ -0,0 +1,283 @@ +This is hook-helpers.info, produced by makeinfo version 6.5 from +hook-helpers.texi. + +INFO-DIR-SECTION Emacs +START-INFO-DIR-ENTRY +* Hook Helpers: (hook-helpers). Anonymous, modifiable hook functions. +END-INFO-DIR-ENTRY + + +File: hook-helpers.info, Node: Top, Next: Copying, Up: (dir) + +Hook Helpers +************ + +* Menu: + +* Copying:: +* Introduction:: +* Installation:: +* Examples:: +* In-Depth Usage:: +* Changelog:: + +— The Detailed Node Listing — + +In-Depth Usage + +* Adding and Removing Helpers:: +* Seeing all the Available Helpers:: + +Changelog + +* 1.1.1: 111. +* 1.1: 11. +* 1.0: 10. + + + +File: hook-helpers.info, Node: Copying, Next: Introduction, Prev: Top, Up: Top + +Copying +******* + +Copyright (C) 2016-2018 Free Software Foundation, Inc. + + 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 the Free Software Foundation, either version 3 of the + License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + <http://www.gnu.org/licenses/>. + + +File: hook-helpers.info, Node: Introduction, Next: Installation, Prev: Copying, Up: Top + +Introduction +************ + +Savannah Project (https://savannah.nongnu.org/projects/hook-helpers-el/) + + Often times, I see people define a function to be used once in a +hook. If they don’t do this, then it will be an anonymous function. If +the anonymous function is modified, then the function can’t be removed. +With a function outside of the ‘add-hook’ call, it looks messy. + + Hook Helpers are a solution to this. A “hook helper” is an +anonymous, modifiable function created for the sole purpose of being +attached to a hook. This combines the two commonly used methods +mentioned above. The functions don’t exist, so they don’t get in the +way of ‘C-h f’, but they can be removed or modified as needed. + + +File: hook-helpers.info, Node: Installation, Next: Examples, Prev: Introduction, Up: Top + +Installation +************ + +Hook Helpers requires Emacs 25.1 or later. + + The easiest way to install hook helpers is using GNU ELPA: + + M-x package-install RET hook-helpers RET + + No more setup is required to start using hook helpers. + + You can also clone from the git repo: + + git clone https://git.savannah.gnu.org/git/hook-helpers-el hook-helpers + make -C hook-helpers compile autoloads + + Then you’ll need to add the following to your .emacs file (or +equivalent): + + (add-to-list 'load-path "/path/to/hook-helpers") + (load "/path/to/hook-helpers/hook-helpers-autoloads.el") + + +File: hook-helpers.info, Node: Examples, Next: In-Depth Usage, Prev: Installation, Up: Top + +Examples +******** + +Let’s look at some examples. + + Without using a hook helper, one must do the following: + + (defun my/after-init-hook () + (set-scroll-bar-mode nil)) + (add-hook 'after-init-hook 'my/after-init-hook) + + If you forget the ‘add-hook’ call, then this doesn’t do any good. +Alternatively, you can use a lambda function: + + (add-hook 'after-init-hook (lambda () (set-scroll-bar-mode nil))) + + But then if you want to modify the function, it’s permanently stuck +on the after-init-hook variable, and you have to deal with it. It’s not +a problem for after-init-hook, which is used once, but would be a +problem for a mode hook, like text-mode-hook. + + With a hook helper, this is reduced to the following: + + (define-hook-helper after-init () + (set-scroll-bar-mode nil)) + + Which handles everything for you. + + +File: hook-helpers.info, Node: In-Depth Usage, Next: Changelog, Prev: Examples, Up: Top + +In-Depth Usage +************** + +There are two macros in hook helpers: ‘define-hook-helper’ and +‘create-hook-helper’. + + The former is a basic case; it creates and adds a helper for a single +hook. Most hooks have the -hook suffix, so we take advantage of that +here for a little less typing. In order to add a helper to a +non-standard hook, use the ‘:suffix’ argument: + + (define-hook-helper my () + :suffix function + :append t + (message "Hello!")) + + We also introduce the ‘:append’ keyword above, which does exactly +what it sounds like. + + There’s one more keyword for ‘define-hook-helper’: ‘:name’. This +specifies an additional name for the new helper. Without this, its +helper ID is just the name of the hook; with a ‘:name’, its ID is +HOOK-NAME/NAME. + + The work horse of hook helpers is ‘create-hook-helper’. This is the +generic case, capable of adding itself to any number of hooks: + + (create-hook-helper new-helper () + :hooks (hook-1-hook + (hook-2-hook . t) + hook-3-function) + (message "Look at all that we can do!")) + + This creates a new hook helper called “new-helper”, and adds it to +‘hook-1-hook’, ‘hook-2-hook’, and ‘hook-3-function’, appending to the +latter. + + The ‘:hooks’ keyword can have the following form: + + • A single hook + • A cons cell (HOOK . APPEND) + • A list containing a mixture of the above two forms + + This is called a “hook spec”. + +* Menu: + +* Adding and Removing Helpers:: +* Seeing all the Available Helpers:: + + +File: hook-helpers.info, Node: Adding and Removing Helpers, Next: Seeing all the Available Helpers, Up: In-Depth Usage + +Adding and Removing Helpers +=========================== + +To add or remove helpers, the functions add-hook-helper and +remove-hook-helper are provided. + + (add-hook-helper 'test-helper '(hook-the-first hook-the-second)) + (remove-hook-helper 'test-helper 'hook-the-second) + + As you can see, each of them takes the same arguments: a symbol +denoting the helper to add or remove, and a quoted hook spec. + + Any hook helper created using ‘define-hook-helper’ can be removed as +well: + + (define-hook-helper my () + :name ours + (message "Hello!")) + + (remove-hook-helper 'my-hook/ours 'my-hook) + + +File: hook-helpers.info, Node: Seeing all the Available Helpers, Prev: Adding and Removing Helpers, Up: In-Depth Usage + +Seeing all the Available Helpers +================================ + +Seeing lambda functions in your hooks can be confusing. While we don’t +have a solution for that, we do have ‘describe-hook-helpers’, an +interactive function that creates a pretty buffer containing all the +defined hook helpers, grouped by the hooks to which they are attached. + + +File: hook-helpers.info, Node: Changelog, Prev: In-Depth Usage, Up: Top + +Changelog +********* + +* Menu: + +* 1.1.1: 111. +* 1.1: 11. +* 1.0: 10. + + +File: hook-helpers.info, Node: 111, Next: 11, Up: Changelog + +1.1.1 +===== + + • Fixed some usage warnings + • Added more examples of removing hook helpers + • Added documentation about installing from GNU ELPA + • Added changelog section to the documentation + + +File: hook-helpers.info, Node: 11, Next: 10, Prev: 111, Up: Changelog + +1.1 +=== + + • Updated to new design + + +File: hook-helpers.info, Node: 10, Prev: 11, Up: Changelog + +1.0 +=== + + • Initial release + + + +Tag Table: +Node: Top219 +Node: Copying585 +Node: Introduction1411 +Node: Installation2236 +Node: Examples2934 +Node: In-Depth Usage3890 +Node: Adding and Removing Helpers5572 +Node: Seeing all the Available Helpers6315 +Node: Changelog6791 +Node: 1116936 +Node: 117211 +Node: 107327 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/packages/hook-helpers/hook-helpers.org b/packages/hook-helpers/hook-helpers.org index 4a72ce1..ebeaeb2 100644 --- a/packages/hook-helpers/hook-helpers.org +++ b/packages/hook-helpers/hook-helpers.org @@ -1,10 +1,20 @@ #+TITLE: Hook Helpers #+AUTHOR: Ian Dunn #+EMAIL: du...@gnu.org +#+DATE: {{{modification-time}}} + +#+STARTUP: overview +#+STARTUP: indent +#+TODO: FIXME | FIXED +#+OPTIONS: toc:2 num:nil timestamp:nil \n:nil |:t ':t email:t +#+OPTIONS: *:t <:t d:nil todo:nil pri:nil tags:not-in-toc -:nil + +#+TEXINFO_DIR_CATEGORY: Emacs +#+TEXINFO_DIR_TITLE: Hook Helpers: (hook-helpers) +#+TEXINFO_DIR_DESC: Anonymous, modifiable hook functions * Copying -Copyright (C) 2016 Ian Dunn -Copyright (C) 2017 Free Software Foundation, Inc. +Copyright (C) 2016-2018 Free Software Foundation, Inc. #+BEGIN_QUOTE This program is free software: you can redistribute it and/or modify @@ -39,15 +49,22 @@ modified as needed. Hook Helpers requires Emacs 25.1 or later. -To install hook helpers, you can clone from the git repo: +The easiest way to install hook helpers is using GNU ELPA: + +#+begin_example +M-x package-install RET hook-helpers RET +#+end_example + +No more setup is required to start using hook helpers. + +You can also clone from the git repo: #+BEGIN_SRC shell git clone https://git.savannah.gnu.org/git/hook-helpers-el hook-helpers make -C hook-helpers compile autoloads #+END_SRC -After that, setup is easy. Just add the following to your .emacs file (or -equivalent): +Then you'll need to add the following to your .emacs file (or equivalent): #+BEGIN_SRC emacs-lisp (add-to-list 'load-path "/path/to/hook-helpers") @@ -90,7 +107,7 @@ Which handles everything for you. There are two macros in hook helpers: ~define-hook-helper~ and ~create-hook-helper~. The former is a basic case; it creates and adds a helper for a single hook. -Most hooks have the -hook suffix, so we take advantage of that here for a little +Most hooks have the "-hook" suffix, so we take advantage of that here for a little less typing. In order to add a helper to a non-standard hook, use the ~:suffix~ argument: @@ -142,9 +159,30 @@ are provided. As you can see, each of them takes the same arguments: a symbol denoting the helper to add or remove, and a quoted hook spec. +Any hook helper created using ~define-hook-helper~ can be removed as well: + +#+begin_src emacs-lisp +(define-hook-helper my () + :name ours + (message "Hello!")) + +(remove-hook-helper 'my-hook/ours 'my-hook) +#+end_src + ** Seeing all the Available Helpers Seeing lambda functions in your hooks can be confusing. While we don't have a solution for that, we do have ~describe-hook-helpers~, an interactive function that creates a pretty buffer containing all the defined hook helpers, grouped by the hooks to which they are attached. + +* Changelog +** 1.1.1 +- Fixed some usage warnings +- Added more examples of removing hook helpers +- Added documentation about installing from GNU ELPA +- Added changelog section to the documentation +** 1.1 +- Updated to new design +** 1.0 +- Initial release