[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/cider ee7bdbd034 1/3: Introduce `cider-log-show` function
|
From: |
ELPA Syncer |
|
Subject: |
[nongnu] elpa/cider ee7bdbd034 1/3: Introduce `cider-log-show` function (#3602) |
|
Date: |
Tue, 2 Jan 2024 15:59:19 -0500 (EST) |
branch: elpa/cider
commit ee7bdbd034abfbd89cc52cb0725b2fdd76fb45e3
Author: vemv <vemv@users.noreply.github.com>
Commit: GitHub <noreply@github.com>
Introduce `cider-log-show` function (#3602)
* Introduce `cider-log-show` function
* Prefer logview-mode unconditionally, and warn when it's absent
This way, users will know logview-mode exists.
There's still fallback, and optionality.
---
cider-log.el | 68 ++++++++++--
cider-mode.el | 1 +
.../assets/images/cider-log-transient-mode.png | Bin 0 -> 21987 bytes
doc/modules/ROOT/pages/debugging/logging.adoc | 117 ++++++++++++++++-----
4 files changed, 153 insertions(+), 33 deletions(-)
diff --git a/cider-log.el b/cider-log.el
index 62b9034283..4e7a8d626d 100644
--- a/cider-log.el
+++ b/cider-log.el
@@ -37,7 +37,12 @@
(require 'transient)
(defcustom cider-log-framework-name nil
- "The name of the current log framework."
+ "The name of the default log framework.
+
+You may want to set this in .dir-locals.el,
+for a more streamlined setup.
+
+Example value: \"Logback\"."
:group 'cider
:package-version '(cider . "1.8.0")
:safe #'stringp
@@ -85,13 +90,20 @@
:safe #'integerp
:type 'integer)
-(defcustom cider-log-use-logview (fboundp 'logview-mode)
- "Whether to use `logview-mode' or not."
+(defcustom cider-log-use-logview t
+ "Whether to use `logview-mode'.
+
+It will not be used if the package hasn't been installed."
:group 'cider
:package-version '(cider . "1.8.0")
:safe #'booleanp
:type 'boolean)
+(defun cider-log-use-logview ()
+ "Whether to use `logview-mode'."
+ (and (fboundp 'logview-mode)
+ cider-log-use-logview))
+
(defvar logview-mode-map)
(declare-function logview--guess-submode "logview" () t)
(declare-function logview-initialized-p "logview" () t)
@@ -556,6 +568,8 @@ The KEYS are used to lookup the values and are joined by
SEPARATOR."
(when-let (appender (cider-log-appender-reload framework appender))
(cider-log-appender-consumer appender consumer)))
+(declare-function cider-log-mode "cider-log")
+
(defun cider-log--consumer-add (framework appender consumer buffer)
"Add the CONSUMER to the APPENDER of FRAMEWORK and write events to BUFFER."
(cider-request:log-add-consumer
@@ -567,7 +581,14 @@ The KEYS are used to lookup the values and are joined by
SEPARATOR."
(setq-local cider-log-framework framework)
(setq-local cider-log-appender appender)
(setq cider-log-consumer cider/log-add-consumer)
- (switch-to-buffer buffer)))
+ (switch-to-buffer buffer)
+ (when (and cider-log-use-logview
+ (not (fboundp 'logview-mode)))
+ (message "[CIDER Log Mode] Please install the Logview
package for best results.")
+ (cider--display-interactive-eval-result "Please install the
Logview package for best results."
+ 'error
+ (point)
+
'cider-error-overlay-face))))
((member "cider/log-event" status)
(let* ((consumer (nrepl-dict "id" cider/log-consumer))
(buffers (cider-log-consumer-buffers consumer)))
@@ -580,7 +601,8 @@ The KEYS are used to lookup the values and are joined by
SEPARATOR."
(seq-doseq (buffer buffers)
(with-current-buffer buffer
(cider-log--insert-events buffer (list cider/log-event))
- (when (and cider-log-use-logview (not
(logview-initialized-p)))
+ (when (and (cider-log-use-logview)
+ (not (logview-initialized-p)))
(let ((framework cider-log-framework)
(appender cider-log-appender)
(consumer cider-log-consumer))
@@ -812,7 +834,9 @@ The KEYS are used to lookup the values and are joined by
SEPARATOR."
(defvar cider-log-mode-map
(let ((map (make-sparse-keymap))
- (parent (if cider-log-use-logview logview-mode-map special-mode-map)))
+ (parent (if (cider-log-use-logview)
+ logview-mode-map
+ special-mode-map)))
(set-keymap-parent map parent)
(define-key map (kbd "C-c M-l a") #'cider-log-appender)
(define-key map (kbd "C-c M-l c") #'cider-log-consumer)
@@ -849,7 +873,7 @@ the CIDER Inspector and the CIDER stacktrace mode.
\\{cider-log-mode-map}")
-(if cider-log-use-logview
+(if (cider-log-use-logview)
(define-derived-mode cider-log-mode logview-mode "Cider Log"
cider-log--mode-doc
(cider-log--setup-mode))
(define-derived-mode cider-log-mode special-mode "Cider Log"
cider-log--mode-doc
@@ -1154,12 +1178,17 @@ the CIDER Inspector and the CIDER stacktrace mode.
(let ((inhibit-read-only t))
(erase-buffer)))))
+(defun cider-log--switch-to-buffer (buffer)
+ "Switch to the Cider log event BUFFER."
+ (when (get-buffer-create buffer)
+ (switch-to-buffer-other-window buffer)
+ (get-buffer buffer)))
+
(transient-define-suffix cider-log-switch-to-buffer (buffer)
"Switch to the Cider log event BUFFER."
:description "Switch to the log event buffer"
(interactive (list cider-log-buffer))
- (when (get-buffer-create buffer)
- (switch-to-buffer-other-window buffer)))
+ (cider-log--switch-to-buffer buffer))
(transient-define-suffix cider-log--do-search-events (framework appender
filters)
"Search the log events of FRAMEWORK and APPENDER which match FILTERS."
@@ -1385,6 +1414,27 @@ the CIDER Inspector and the CIDER stacktrace mode.
(cider-log--ensure-initialized framework appender)
(transient-setup 'cider-log-event))
+;;;###autoload
+(defun cider-log-show ()
+ "Ensures the *cider-log* buffer is visible,
+setting up a framework, appender and consumer if necessary.
+
+Honors the `cider-log-framework-name' customization variable.
+
+This function is offered as an alternative to workflows
+based on `transient-mode'."
+ (interactive)
+ (cider-current-repl nil 'ensure)
+ (let ((framework (cider-log--framework))
+ (appender (cider-log--appender))
+ (new-default-directory (buffer-local-value 'default-directory
(current-buffer))))
+ (with-current-buffer (cider-log--switch-to-buffer cider-log-buffer)
+ (setq-local default-directory new-default-directory) ;; for Sesman
+ (cider-log--ensure-initialized framework appender)
+ (unless cider-log-consumer
+ (apply #'cider-log--ensure-initialized
(cider-log--consumer-interactive-list))
+ (call-interactively 'cider-log--do-add-consumer)))))
+
;; Main Transient Menu
;;;###autoload (autoload 'cider-log "cider-log" "Show the Cider log menu." t)
diff --git a/cider-mode.el b/cider-mode.el
index 15024f96ce..235ce6c5c7 100644
--- a/cider-mode.el
+++ b/cider-mode.el
@@ -537,6 +537,7 @@ higher precedence."
(define-key map (kbd "C-c M-l a") #'cider-log-appender)
(define-key map (kbd "C-c M-l c") #'cider-log-consumer)
(define-key map (kbd "C-c M-l e") #'cider-log-event)
+ (define-key map (kbd "C-c M-l s") #'cider-log-show)
(define-key map (kbd "C-c M-l f") #'cider-log-framework)
(define-key map (kbd "C-c M-l i") #'cider-log-info)
(define-key map (kbd "C-c M-l l") #'cider-log)
diff --git a/doc/modules/ROOT/assets/images/cider-log-transient-mode.png
b/doc/modules/ROOT/assets/images/cider-log-transient-mode.png
new file mode 100644
index 0000000000..549f15db79
Binary files /dev/null and
b/doc/modules/ROOT/assets/images/cider-log-transient-mode.png differ
diff --git a/doc/modules/ROOT/pages/debugging/logging.adoc
b/doc/modules/ROOT/pages/debugging/logging.adoc
index cd30b0e105..3ee4436088 100644
--- a/doc/modules/ROOT/pages/debugging/logging.adoc
+++ b/doc/modules/ROOT/pages/debugging/logging.adoc
@@ -3,7 +3,7 @@
CIDER Log Mode allows you to capture, debug, inspect and view log
events emitted by Java logging frameworks. The captured log events can
-be searched, streamed to the client, pretty printed and are integrated
+be searched, streamed to the client, pretty-printed, and are integrated
with the CIDER link:inspector.html[Inspector] and
link:../usage/dealing_with_errors.html[Stacktrace Mode]. Here is a
screenshot of CIDER Log Mode in action.
@@ -20,12 +20,12 @@ logging related actions.
== Features
-- Browse Javadocs and website of log framework.
+- Browse Javadocs and website of the given log framework.
- Search log events and show them in buffers.
-- link:../usage/pretty_printing.html[Pretty Print] log events.
-- Show log events in the CIDER link:inspector.html[Inspector]
-- Show log event exceptions in the CIDER
link:../usage/dealing_with_errors.html[Stacktrace Mode]
-- Integration with https://github.com/doublep/logview[logview]
+- link:../usage/pretty_printing.html[Pretty-print] log events.
+- Show log events in the CIDER link:inspector.html[Inspector].
+- Show log event exceptions in the CIDER
link:../usage/dealing_with_errors.html[Stacktrace Mode].
+- Integration with https://github.com/doublep/logview[logview].
== Dependencies
@@ -33,13 +33,73 @@ https://github.com/doublep/logview[Logview] is an optional
dependency
of CIDER Log Mode. We recommend using it, since it is responsible for
coloring the log events and it provides other useful features, such as
syntax highlighting, filtering and more. It is used automatically when
-available and its use can be customized via `cider-log-use-logview`.
+available, and its use can be customized via `cider-log-use-logview`.
-== Usage
+== `transient-mode`
-To use CIDER Log Mode, type kbd:[C-c M-l l] or kbd:[M-x cider-log] in
-any buffer that has a CIDER https://github.com/vspinu/sesman[Sesman]
-session attached to it. The first time you run the command, it will
+It's worth pointing out that most features and workflows of Cider Log Mode are
based on https://github.com/magit/transient[transient-mode].
+
+A transient menu is the following widget:
+
+image::cider-log-transient-mode.png[CIDER Log transient menu]
+
+Its usage is mostly self-describing, since each command has its keybinding
attached to the description.
+
+== Getting started
+
+To use CIDER Log Mode, there two main ways to get started:
+
+* `M-x cider-log-event`, which uses transient-mode and will not immediately
show the logs (you should use transient-mode to show the `+*cider-log*+` buffer)
+* `M-x cider-log-show` is a newer function that intends to be an "all-in-one"
command, intended for a streamlined experience, which can be useful to get
started, or for casual usage.
+** It doesn't use transient-mode - it aims to do everything in one step
+** It immediately shows the `+*cider-log*+` buffer
+
+NOTE: any of these commands will only succeed in
+a buffer that has a CIDER repl (https://github.com/vspinu/sesman[Sesman]
+session) attached to it.
+
+=== Via `cider-log-show`
+
+By using `M-x cider-log-show`, all setup and rendering will be performed for
you in a single step that doesn't pop up a `transient-mode` menu:
+
+* A framework will be set up, automatically
+** You may be prompted for a framework
+** You can prevent the prompt by customizing `cider-log-framework-name` (best
done in `dir-locals.el`)
+* A log appender and a log consumer will be setup, automatically
+* The `+*cider-log*+` buffer will be rendered.
+
+All these steps are idempotent, so it's safe to run `M-x cider-log-show` more
than once.
+
+You can refine the setup afterwards (e.g. configuring filtering) by running
`M-x cider-log`.
+
+=== Via `cider-log-event`
+
+The intended workflow for this function is as follows:
+
+* Run `M-x cider-log-event`
+* A framework will be set up, automatically
+** You may be prompted for a framework
+** You can prevent the prompt by customizing `cider-log-framework-name` (best
done in `dir-locals.el`)
+* A log appender and a log consumer will be setup, automatically
+* The `+*cider-log*+` buffer will _not_ be rendered
+** For it to be rendered, press `s` (`Search log events`) within the
transient-mode menu.
+
+NOTE: The `+*cider-log*+` buffer might initially be empty, and you may
+see a `No log events found` message. This is because nothing has been
+logged between adding the appender and searching for events. So, now
+would be a good time to run some code that triggers a log event for
+the selected framework.
+
+== Advanced usage
+
+`cider-log` is a function that can serve both to set up logging from scratch,
+or for tweaking an existing setup (e.g. add filtering to a consumer).
+
+It's considered a lower-level approach.
+
+=== Setup via `cider-log`
+
+Type kbd:[C-c M-l l] or kbd:[M-x cider-log]. The first time you run the
command, it will
prompt you to select a log framework to use, and then attach a log
appender to the root logger of the selected framework. After the log
appender has been attached, the `cider-log` command will show a
@@ -47,26 +107,30 @@
https://www.gnu.org/software/emacs/manual/html_mono/transient.html[Transient]
menu, from which you can take further actions, like managing the log
framework, appenders, consumers and events.
-To view log events and stream them to your client, type kbd:[es]
+You should add a log appender and a log consumer at this point - else no log
entries will be possibly shown
+(which is why `cider-log` is considered a lower-level workflow).
+
+After that, to view log events and stream them to your client, type kbd:[es]
(Search log events) followed by kbd:[s]. This will open the
`+*cider-log*+` buffer showing any log events captured thus far. It will
also add a log consumer to this buffer, which receives newly-arriving
log events.
-NOTE: The `+*cider-log*+` buffer might initially be empty, and you may
-see a `No log events found` message. This is because nothing has been
-logged between adding the appender and searching for events. So, now
-would be a good time to run some code that triggers a log event for
-the selected framework.
-
=== Keybindings
|===
| Command | Keyboard shortcut | Description
+| `cider-log-event`
+| kbd:[C-c M-l e]
+| Show the menu to manage log events via a transient-mode menu. This is one of
the two main entrypoints to get started.
+
+| `cider-log-show`
+| kbd:[C-c M-l s]
+| Immediately shows the logs, without a transient-mode menu. This is one of
the two main entrypoints to get started.
| `cider-log`
| kbd:[C-c M-l l]
-| Show the CIDER log menu.
+| Show the CIDER log menu. Please note that this is considered advanced usage.
| `cider-log-framework`
| kbd:[C-c M-l f]
@@ -79,16 +143,12 @@ the selected framework.
| `cider-log-consumer`
| kbd:[C-c M-l c]
| Show the menu to manage consumers listening to log events.
-
-| `cider-log-event`
-| kbd:[C-c M-l e]
-| Show the menu to manage log events.
|===
== Log framework
CIDER Log Mode supports log frameworks that allow reconfiguration at
-run time. More specifically the framework should support attaching log
+runtime. More specifically the framework should support attaching log
appenders to loggers, in order to capture events.
At the moment the following log frameworks are supported:
@@ -103,6 +163,15 @@
https://stackoverflow.com/a/17842174/12711900[difficulties] with
configuration changes made at runtime, which are wiped out by the
Log4j2 reconfiguration mechanism.
+Timbre support is WIP as well.
+
+TIP: If your logging framework of choice is not currently supported by CIDER
Log Mode,
+you can opt to use Clojure's official `tools.logging` façade in your project,
such that you can locally,
+unobstrusively tell it to use a supported framework (like Logback) instead of
your project's default one.
+Note that `tools.logging`'s choice of logging backend implementation can be
controlled with the
+`-Dclojure.tools.logging.factory` Java system property, which can be cleanly
customized locally via Lein profiles,
+or Clojure CLI aliases.
+
=== Keybindings
|===