mplscorwin / defmaybe

maybe declare well documented variables

defmaybe - maybe declare well documented variables

I’ve largely abandoned this. I’ll likely drop the reop pretty soon. Open an issue or otherwise reach out if you want to talk about the thing I’ve been putting off instead of putting off improving this approach :)

Provides a drop in replacement to defvar (or defcustom) called **defvar-maybe**. By setting the buffer local variable ‘defmabe-defvar’ we can case eval-buffer, eval-region, etc. to implicitly reset all formally declared variables to their default bindings.

I use this package to define variables (whether customizable or not) including their full documentation strings and customization options inline while I write packages. As the package grows stable I’ve probably got it’s local maybedef-defvar variable set to ‘custom or t, meaning I want current to leave vars as currently set (or customized) as I re-eval the package or its parts.

To quickly reset vars within an open buffer:

(with-current-buffer "hacked-on-supporting-feature.el" 
  (let ((defmaybe-defvar nil))
    (eval-buffer)))

It may be straight forward to create a similar wrapper for function defining forms such as defun. This could support a “feature flags” like capability by introspecting for the availability of other features and creating alias instead when the given feature is present, meets requirements, etc.. It’s unlikely I’ll add this unless I end up needing it for something at which point I’ll go hunting for someone else’s solution first. If you’d really like to see that feature here, or if your interested in writing it, please open an issue and/or otherwise reach out.

Usage

This package provides a drop-in replacement for defvar or defcustom that substitutes ‘setq’ during “DEVEL”. Place the following lines into a package you are hacking on:

(require 'defmaybe)
(setq defmaybe-defvar nil) ;; nil=setq, t=defvar, 'custom=defcustom
(defvar-maybe 'my-var "val" "is documented" :group 'mine :type 'string)

The default for the buffer-local var defmaybe-defvar is t, meaning that customize options may appear in the source but defcustom won’t actually be called when evaluating the defvar-maybe statement or the buffer, nor when compiling.

A clean-up function is also provided:

;; later, at release-time, M-X eval-expression RET
(defmaybe-chdef 'defvar-maybe 'defcustom)

More generalized:

defmaybe-chdef(OLD-SYM NEW-SYM & optional MAX-ARGS)

The final argument, MAX-ARGS causes truncation of any additional arguments **and their removal from your source**. So please be careful and stuff.

Cutting a DEVEL version could be:

;; remove docstring and customize args
(defmaybe-chdef 'defvar-maybe 'setq 1)

It should also be possable to use defmaybe-chdef in conjunction with batch mode to support a packaging process that produces a version of your work without dependency on the module. I’ve left removing the require pragmatically as an exercise for the reader.

Concept notes

The following are my notes prior to initiating the project.

Feature flags

Map features to replacement functionality and information.

Swap variable definition forms

E.g. use defvar, defcustom or plain ‘ol setq.

Document everything

Rendered source need contain neither non-contributing documentation nor any dependency on defmaybe.

BUGS

Byte-compiler warning

I get byte-compilation warning about defmyabe-defvar not being defined as a function, which it isn’t and shouldn’t be. Thanks in advance for suggestions or patch.

These are items under consideration. Maybe I have notes or borked code somwhere about some of this. More than welcome to show me how it’s done :]

Feature flags as described elsewhere

Extract an ‘at-point’ version of chdef

chdef-remap(&rest (maybe-deffed-var . chdef-args))

Acknoledgements, Author Contact and Support

Thanks in advance for any issues you report; please use the issue tracker to request commit access and make suggestions as well as to report bugs.

Ever bit as much thanks to everyone on #Emacs@Freenode and the contributers to EmacsWiki for rather a great deal of kind assistance.

Contact the author by email (Corwin AT Bru DOT st) or find “Corwin” on Discord, here: https://discord.gg/gar8ns, or as “q[corwin]” on irc.freenode.net.