- Add comments to doom-cli-context-parse.
- Simplify/inline code here and there.
- Remove sacrifice to appease byte-compiler.
Thanks to a346928 there's no need to appease the byte-compiler with this
eval-when-compile hackery.
Ref: a34692826f18
I've removed these CLI properties because they were either
unused (:deprecated and :since) or poorly implemented (:stub and
:obsolete). And I'd rather have fewer magical properties, and instead
delegate these roles to the defobsolete! and (new) defstub! macros.
Also, in the future, the help API will ascertain :since dynamically, so
it won't be very useful.
In summary:
- Use defstub! instead of :stub
- Use defobsolete! instead of :obsolete or :deprecated
- This removes the doom-cli-deprecated-error type (it's not really an
error to begin with).
- Removes :stub, :obsolete, :deprecated, and :since
BREAKING CHANGE: This renames the fn! macro to lambda! and fn!! to fn!.
I hadn't put much thought into their names when they were added, but now
that they're seeing more use, I've reconsidered.
The reasoning is (and I'll refer to them by their new names):
- If you're using fn!, you care more about the syntax's brevity, than if
you were using lambda!, so I wanted fn! to have the (even if slightly)
shorter name.
- lambda! decorates native lambda (with cl-function). Its old name
did not suggest that connection like other !-macros in Doom's library
do.
- Their old names implied the two macros were somehow related or that
one decorated the other. They aren't and don't.
So the doctor doesn't complain about pseudo packages, like revealjs,
which is not actually an Emacs package, we're just using straight.el to
install it for org-re-reveal.
- :before ci will try to load $REPOROOT/ci.el or $DOOMDIR/ci.el. It
finds $REPOROOT by calling `git`, but doesn't handle errors. Now it
does.
- Because &rest was in :before ci's argspec, :before ci * subcommands
would be inaccessible (not that any exist atm, though).
- Let the user know when it finds the project's ci.el.
If you type an unrecognized command, you get an "Error: unrecognized
command X" error, then a list of similar commands, followed by a
recommendation to check out 'doom help Y' or 'doom --help Y', where Y is
the nearest recognized parent command. E.g. 'doom ci blah' is an unknown
command, but 'doom ci' is known, therefore Y = 'doom ci'.
This fix ensures that Y is properly resolved.
Amend: 6c0b7e1530
Before:
$ doom help help
Usage: COMMAND [ARGS...]
TODO
TODO
After:
Usage: doom help [-g|--no-global] [--manpage] [--commands]
[--synopsis|--subcommands|--similar|--envvars|--postamble] [--]
COMMAND [ARGS...]
Show documentation for a Doom CLI command.
OPTIONS:
-g, --no-global
Hide global options.
--manpage
Generate in manpage format.
--commands
List all known commands.
--synopsis, --subcommands, --similar, --envvars, --postamble
Show only the specified sections..
Amend: 6c0b7e1530
Some packages (primarily vterm, evil-collection, and with-editor) end up
hanging their native compilation process. In vterm's case it's because
it invisibly prompts to compile its module then waits forever for user
input that'll never come. I haven't figured out why it happens for the
others though.
In any case, since the workaround is to simply kill these processes and
carry on, I added this timeout mechanism to do it for you (timing out
after 30s of no movement). A more elegant solution will have to wait
until the rewrite of our package manager.
Fix: #5592
- An improper autoload was preventing 'doom clean' from being
recognized.
- 'doom compile' hadn't been updated to reflect changes introduced
recently in 1402db5.
Amend: 6c0b7e1530
Ref: 1402db5129
To 'doom sync', 'doom upgrade', and 'doom build'. So users can decide
whether they want Doom 100%'ing their CPUs.
After 3.0, many of these commands will be merged, so a little code
duplication is fine for now.
When I added call! to the DSL, I forgot to update doom-cli-call calls.
This should quell these errors when running 'doom upgrade':
x There was an unexpected runtime error
Message: Wrong number of arguments
Details: (((cl-struct-doom-cli-context-tags cl-struct-doom-cli-option-...
Backtrace:
(doom-cli-call ("doom" "sync" "-u"))
(cond (packages\? (doom-cli-call sync-cmd) (doom-print (doom-print-...
Amend: 6c0b7e1530
BREAKING CHANGE: this changes Doom's CLI framework in subtle ways, which
is listed in greater detail below. If you've never extended Doom's CLI,
then this won't affect you, but otherwise it'd be recommended you read
on below.
This commit focuses on the CLI framework itself and backports some
foundational changes to its DSL and how it resolves command line
arguments to CLIs, validates input, displays documentation, and persists
state across sessions -- and more. This is done in preparation for the
final stretch towarding completing the CLI rewrite (see #4273).
This is also an effort to generalize Doom's CLI (both its framework and
bin/doom), to increase it versatility and make it a viable dev tool for
other Doom projects (on our Github org) and beyond.
However, there is a *lot* to cover so I'll try to be brief:
- Refactor: generalize Doom's CLI framework by moving all bin/doom
specific configuration/commands out of core-cli into bin/doom. This
makes it easier to use bin/doom as a project-agnostic development
tool (or for users to write their own).
- Refactor: change the namespace for CLI variables/functions from
doom-cli-X to doom-X.
- Fix: subcommands being mistaken as arguments. "doom make index" will
resolve to (defcli! (doom make index)) if it exists,
otherwise (defcli! (doom make)) with "index" as an argument. Before
this, it would resolve to the latter no matter what. &rest can
override this; with (defcli! (doom make) (&rest args)), (defcli! (doom
make index)) will never be invoked.
- Refactor!: redesign our output library (was core/autoload/output.el,
is now core/autoload/print.el), and how our CLI framework buffers and
logs output, and now merges logs across (exit! ...) restarts.
- Feat: add support for :before and :after pseudo commands. E.g.
(defcli! (:before doom help) () ...)
(defcli! (:after doom sync) () ...)
Caveat: unlike advice, only one of each can be defined per-command.
- Feat: option arguments now have rudimentary type validation (see
`doom-cli-option-arg-types`). E.g.
(defcli! (doom foo) ((foo ("--foo" num))) ...)
If NUM is not a numeric, it will throw a validation error.
Any type that isn't in `doom-cli-option-arg-types` will be treated as a
wildcard string type. `num` can also be replaced with a specification,
e.g. "HOST[:PORT]", and can be formatted by using symbol quotes:
"`HOST'[:`PORT']".
- Feat: it is no longer required that options *immediately* follow the command
that defines them (but it must be somewhere after it, not before). E.g.
With:
(defcli! (:before doom foo) ((foo ("--foo"))) ...)
(defcli! (doom foo baz) () ...)
Before:
FAIL: doom --foo foo baz
GOOD: doom foo --foo baz
FAIL: doom foo baz --foo
After:
FAIL: doom --foo foo baz
GOOD: doom foo --foo baz
GOOD: doom foo baz --foo
- Refactor: CLI session state is now kept in a doom-cli-context struct (which
can be bound to a CLI-local variable with &context in the arglist):
(defcli! (doom sync) (&context context)
(print! "Command: " (doom-cli-context-command context)))
These contexts are persisted across sessions (when restarted). This is
necessary to support seamless script restarting (i.e. execve
emulation) in post-3.0.
- Feat: Doom's CLI framework now understands "--". Everything after it will be
treated as regular arguments, instead of sub-commands or options.
- Refactor!: the semantics of &rest for CLIs has changed. It used to be "all
extra literal, non-option arguments". It now means *all* unprocessed
arguments, and its use will suppress "unrecognized option" errors, and
tells the framework not to process any further subcommands. Use &args
if you just want "all literal arguments following this command".
- Feat: add new auxiliary keywords for CLI arglists: &context, &multiple,
&flags, &args, &stdin, &whole, and &cli.
- &context SYM: binds the currently running context to SYM (a
`doom-cli-context` struct). Helpful for introspection or passing
along state when calling subcommands by hand (with `call!`).
- &stdin SYM: SYM will be bound to a string containing any input piped
into the running script, or nil if none. Use
`doom-cli-context-pipe-p` to detect whether the script has been
piped into or out of.
- &multiple OPTIONS...: allows all following OPTIONS to be repeated. E.g. "foo
-x a -x b -x c" will pass (list ("-x" . "a") ("-x" . "b") ("-x" .
"c")) as -x's value.
- &flags OPTIONS...: All options after "&flags" get an implicit --no-* switch
and cannot accept arguments. Will be set to :yes or :no depending on which flag is
provided, and nil if the flag isn't provided. Otherwise, a default
value can be specified in that options' arglist. E.g.
(defcli! (doom foo) (&flags (foo ("--foo" :no))) ...)
When called, this command sets FOO to :yes if --foo, :no if --no-foo, and
defaults to :no otherwise.
- &args SYM: this replaces what &rest used to be; it binds to SYM a
list of all unprocessed (non-option) arguments.
- &rest SYM: now binds SYM to a list of all unprocessed arguments, including
options. This also suppresses "unrecognized option" errors, but will render
any sub-commands inaccessible. E.g.
(defcli! (doom make) (&rest rest) ...)
;; These are now inaccessible!
(defcli! (doom make foo) (&rest rest) ...)
(defcli! (doom make bar) (&rest rest) ...)
- &cli SYM: binds SYM to the currently running `doom-cli` struct. Can also be
obtained via `(doom-cli-get (doom-cli-context-command context))`. Possibly
useful for introspection.
- feat: add defobsolete! macro for quickly defining obsolete commands.
- feat: add defalias! macro for quickly defining alias commands.
- feat: add defautoload! macro for defining an autoloaded command (won't
be loaded until it is called for).
- refactor!: rename defcligroup! to defgroup! for consistency.
- fix: CLIs will now recursively inherit plist properties from parent
defcli-group!'s (but will stack :prefix).
- refactor!: remove obsolete 'doom update':
- refactor!: further generalize 'doom ci'
- In an effort to generalize 'doom ci' (so other Doom--or
non-doom--projects can use it), all its subcommands have been
changed to operate on the current working directory's repo instead
of $EMACSDIR.
- Doom-specific CI configuration was moved to .github/ci.el.
- All 'doom ci' commands will now preload one of \$CURRENT_REPO_ROOT/ci.el or
\$DOOMDIR/ci.el before executing.
- refactor!: changed 'doom env'
- 'doom env {-c,--clear}' is now 'doom env {clear,c}'
- -r/--reject and -a/--allow may now be specified multiple times
- refactor!: rewrote CLI help framework and error handling to be more
sophisticated and detailed.
- feat: can now initiate $PAGER on output with (exit! :pager) (or use
:pager? to only invoke pager is output is longer than the terminal is
tall).
- refactor!: changed semantics+conventions for global bin/doom options
- Single-character global options are now uppercased, to distinguish them from
local options:
- -d (for debug mode) is now -D
- -y (to suppress prompts) is now -!
- -l (to load elisp) is now -L
- -h (short for --help) is now -?
- Replace --yes/-y switches with --force/-!
- -L/--load FILE: now silently ignores file errors.
- Add --strict-load FILE: does the same as -L/--load, but throws an error if
FILE does not exist/is unreadable.
- Add -E/--eval FORM: evaluates arbitrary lisp before commands are processed.
- -L/--load, --strict-load, and -E/--eval can now be used multiple times in
one command.
- Add --pager COMMAND to specify an explicit pager. Will also obey
$DOOMPAGER envvar. Does not obey $PAGER.
- Fix#3746: which was likely caused by the generated post-script overwriting
the old mid-execution. By salting the postscript filenames (with both an
overarching session ID and a step counter).
- Docs: document websites, environment variables, and exit codes in
'doom --help'
- Feat: add imenu support for def{cli,alias,obsolete}!
Ref: #4273Fix: #3746Fix: #3844
By default, 'doom ci deploy-hooks' would deploy Doom's git hooks in
$EMACSDIR (~/.emacs.d/.git/hooks). Now it deploys in the local repo its
run in. This is part of an effort to generalize Doom's CI for use
outside this repo.
Ref: 4bae9ffa47
Continues from 47d1b82 as part of an effort to generalize Doom's CI for
use outside this repo:
- 'doom ci ...' commands now:
- Run in the context of the local repo where they're run, rather than
from Doom's install directory ($EMACSDIR).
- Load the first of $REPO_ROOT/.github/ci.el, $DOOMDIR/cli.el, or
$DOOMDIR/cli.el, before executing CI commands. This allows for
per-project configuration, for example:
- https://github.com/doomemacs/doomemacs/blob/master/.github/ci.el
- https://github.com/doomemacs/themes/blob/master/.github/ci.el
(Details may change post-3.0)
- Scopeless commit types are now enforced in `doom-cli-commit-scopes`,
rather than `doom-cli-commit-rules`. This lets you specify exceptions,
like 0597466261.
- `doom-cli-commit-scopes` now supports sub-lists, as an easy way to
permit type-local scopes. E.g. To allow 'install' and 'faq' scopes
only for 'docs:' commits.
(add-to-list 'doom-cli-commit-scopes '(docs "install" "faq"))
These sublists accepts predicates too.
- Fixed the link to git conventions in the linter's failure/warning
output, to point to our Discourse post.
Ref: https://github.com/doomemacs/doomemacs/blob/master/.github/ci.el
Ref: https://github.com/doomemacs/themes/blob/master/.github/ci.el
Ref: 0597466261
Amend: 47d1b82382
When launching Doom via 'doom run', the child process inherits
bin/doom's environment. This change restricts this sub-environment to
the intended target: straight and its use of git.
Fix: #6320
I was discussing issues generating autoloads files from some packages
with someone on Discord, and they mentioned issues with
alphapapa/bufler.el, so I added doom-autoloads-excluded-files in
5d0f781062, and also added bufler to it by default. In hindsight, that
doesn't make much sense as a default when Doom and its modules don't
even install bufler (and even if they did, this shouldn't be done in
core).
Ref: 5d0f781062
So they don't interfere with straight in odd, unpredictable ways. If
you *really* know what you're doing, set DOOMGITCONFIG to the path of a
gitconfig file. This envvar may be renamed in the future, however.
Close: #5640
Co-authored-by: M. Yas. Davoodeh <Davoodeh@users.noreply.github.com>
- Simplify doom-info and doom/info.
- Remove doom/copy-buffer-contents (may be moved later, but atm not very
useful).
- Remove doom/am-i-secure (this will later be replaced with CLI
commands)
Reduce cases where native-comp procedures were executed in
non-native-comp contexts (somehow).
Also:
- Adds a NATIVECOMP constant for statically detecting the feature.
- Remove native-comp-* -> comp-* aliases (Emacs HEAD has long since
moved on from these).
- Add 'no-native-compile: t' to autoloads file.
The message simply test for the "not-a-version-yet" patch number and
displays an explanation to prepare users for raised error frequency and
having a backup version of Emacs if they do not want to deal with
issues.
