branch: scratch/hook-helpers commit ff95f4944f3d6d1a43aca141cb7fa36a9043704d Author: Ian Dunn <du...@gnu.org> Commit: Ian Dunn <du...@gnu.org>
Preparations to push to ELPA Updated copyright on all files. * hook-helpers.el (package header): Added requirements and bumped version to 1.1beta1 * hook-helpers.org: Renamed from README.org, updated copyright, and added installation section. --- .gitignore | 2 +- Makefile | 5 +++-- hook-helpers-tests.el | 5 +++-- hook-helpers.el | 21 +++++++++++++-------- README.org => hook-helpers.org | 37 ++++++++++++++++++++++++++++++------- 5 files changed, 50 insertions(+), 20 deletions(-) diff --git a/.gitignore b/.gitignore index ef39635..1af0c54 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,2 @@ *.elc -README.html \ No newline at end of file +hook-helpers.html \ No newline at end of file diff --git a/Makefile b/Makefile index 68d4062..9a91f34 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,7 @@ # This is part of Hook Helpers # -# Copyright (C) 2016 Ian Dunn. +# Copyright (C) 2016 Ian Dunn +# Copyright (C) 2017 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 @@ -40,7 +41,7 @@ hook-helpers-autoloads.el: clean: -rm -f *.elc -check: +check: compile @$(EMACS) \ -L "." \ --load "ert" \ diff --git a/hook-helpers-tests.el b/hook-helpers-tests.el index c5758e6..d3b446a 100644 --- a/hook-helpers-tests.el +++ b/hook-helpers-tests.el @@ -1,11 +1,12 @@ ;;; hook-helpers-tests.el --- Tests for hook helpers -;; Copyright (C) 2016,2017 Ian Dunn +;; Copyright (C) 2016 Ian Dunn +;; Copyright (C) 2017 Free Software Foundation, Inc. ;; Author: Ian Dunn <du...@gnu.org> ;; Keywords: development, hooks ;; URL: https://savannah.nongnu.org/projects/hook-helpers-el/ -;; Version: 1.0 +;; Version: 1.1 ;; 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 diff --git a/hook-helpers.el b/hook-helpers.el index dbc7bc0..9772049 100644 --- a/hook-helpers.el +++ b/hook-helpers.el @@ -1,13 +1,16 @@ -;;; hook-helpers.el --- Anonymous, modifiable hook functions +;;; hook-helpers.el --- Anonymous, modifiable hook functions -*- lexical-binding: t; -*- ;; Copyright (C) 2016 Ian Dunn +;; Copyright (C) 2017 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.1alpha1 +;; Version: 1.1beta1 ;; Created: 06 May 2016 -;; Modified: 21 May 2016 +;; Modified: 23 Apr 2017 ;; 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 @@ -27,12 +30,13 @@ ;; 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. +;; outside of the `add-hook' call, it looks messy. -;; The ‘define-hook-helper’ macro is a solution to this. Think of it as an -;; anaphoric ‘add-hook’, but one that can be called many times without risking -;; redundant hook functions. It gives a cleaner look and feel to Emacs -;; configuration files. +;; 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 `describe-function', but they +;; can be removed or modified as needed. ;;; Code: @@ -104,6 +108,7 @@ For each hook HOOK in the original: ;; Delete the helper from the hooks (cl-delete old-func (symbol-value hook) :test 'equal))))))) +;;;###autoload (defmacro create-hook-helper (id args &optional docstring &rest body) "Creates a new hook helper ID for the hooks in HOOKS. diff --git a/README.org b/hook-helpers.org similarity index 82% rename from README.org rename to hook-helpers.org index 2af2a8e..4a72ce1 100644 --- a/README.org +++ b/hook-helpers.org @@ -3,7 +3,8 @@ #+EMAIL: du...@gnu.org * Copying -Copyright (C) 2016-2017 Ian Dunn +Copyright (C) 2016 Ian Dunn +Copyright (C) 2017 Free Software Foundation, Inc. #+BEGIN_QUOTE This program is free software: you can redistribute it and/or modify @@ -34,15 +35,38 @@ 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. -Let's look at an example: +* Installation + +Hook Helpers requires Emacs 25.1 or later. + +To install hook helpers, you can 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): + +#+BEGIN_SRC emacs-lisp +(add-to-list 'load-path "/path/to/hook-helpers") +(load "/path/to/hook-helpers/hook-helpers-autoloads.el") +#+END_SRC + +* Examples +Let's look at some examples. + +Without using a hook helper, one must do the following: #+BEGIN_SRC emacs-lisp (defun my/after-init-hook () (set-scroll-bar-mode nil)) +(add-hook 'after-init-hook 'my/after-init-hook) #+END_SRC -You've got to remember to actually add this to the after-init-hook variable. -Alternatively, you can use a lambda function: +If you forget the ~add-hook~ call, then this doesn't do any good. Alternatively, +you can use a lambda function: #+BEGIN_SRC emacs-lisp (add-hook 'after-init-hook (lambda () (set-scroll-bar-mode nil))) @@ -53,7 +77,7 @@ 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. -Instead, hook-helpers can do the following: +With a hook helper, this is reduced to the following: #+BEGIN_SRC emacs-lisp (define-hook-helper after-init () @@ -62,8 +86,7 @@ Instead, hook-helpers can do the following: Which handles everything for you. -* Usage - +* 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.