[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/sesman 4f52cccf26 013/100: Update readme
From: |
ELPA Syncer |
Subject: |
[nongnu] elpa/sesman 4f52cccf26 013/100: Update readme |
Date: |
Tue, 28 Dec 2021 14:05:58 -0500 (EST) |
branch: elpa/sesman
commit 4f52cccf264c7d8bc7321c0bba8045932c744296
Author: Vitalie Spinu <spinuvit@gmail.com>
Commit: Vitalie Spinu <spinuvit@gmail.com>
Update readme
---
README.md | 28 +++++++++++++++-------------
sesman.el | 19 +------------------
2 files changed, 16 insertions(+), 31 deletions(-)
diff --git a/README.md b/README.md
index f0ea76a9c4..21c4dd4122 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ This is a brief overview. Please see the code for more details.
Sesman provides facilities for session management and interactive session
association with current contexts. While "sessions" is a broad and
implementation specific concept, the primary target of `sesman` are Emacs based
IDEs ([CIDER][], [ESS][], [Geiser][], [Robe][], [SLIME][] etc.)
-For Emacs based IDEs, session is commonly composed of one or more physical
processes (sub-processes, sockets, websockets etc). For example in the current
implementation of [CIDER][] a session would be composed of one or more cider
connections (Clojre or ClojureScript). Each [CIDER][] connection consists of
user REPL buffer and two sub-processes, one for user eval communication and
another for tooling (completion, inspector etc).
+For Emacs based IDEs, session is commonly composed of one or more physical
processes (sub-processes, sockets, websockets etc). For example in the current
implementation of [CIDER][] a session would be composed of one or more sesman
connections (Clojre or ClojureScript). Each [CIDER][] connection consists of
user REPL buffer and two sub-processes, one for user eval communication and
another for tooling (completion, inspector etc).
### Concepts:
@@ -26,30 +26,32 @@ Consists of
- lifecycle management commands (`sesman-start`, `sesman-kill` and
`sesman-restart`), and
- association management commands (`sesman-link-with-buffer`,
`sesman-link-with-directory`, `sesman-link-with-project` and `sesman-unlink`).
-From the user's prospective the work-flow is simple. Start a session, either
with `sesman-start` (`C-c C-s C-s`) or some of the system specific commands
(`run-xyz`, `xyz-jack-in` etc). On startup each session is automatically
associated with the least specific context (commonly a project). In the most
common case the user has only one session open per project. In such case, no
ambiguity arises when a system retrieves the current session. If none or
multiple sessions are associated with c [...]
+From the user's prospective the work-flow is as follow. Start a session,
either with `sesman-start` (`C-c C-s C-s`) or some of the system specific
commands (`run-xyz`, `xyz-jack-in` etc). On startup each session is
automatically associated with the least specific context (commonly a project).
In the most common case the user has only one session open per project. In such
case, no ambiguity arises when a system retrieves the current session. If
multiple sessions are associated with the cu [...]
-Currently there is only one custom variable, `sesman-1-to-1-links`, which
lists context types for which `1-to-1` associations are desired (defaults to
`'(directory buffer)`. This means, that each time the user links a session with
a directory, any previous associations with that directory are lost. For
context types not in this list (e.g. `project`), 1-to-many associations are
allowed.
+By default links with projects and directories are many-to-many in the sense
that any session can be linked to multiple context and each context can be
associated with multiple sessions. Buffers instead are 1-to-many. One buffer
can be associated with only one session and a session can be associated with
multiple buffers. This behavior is controlled by a custom `sesman-1-to-1-links`.
### [System Interface][]
-Consists of several generics, of which only first two are strictly required:
+Consists of several generics, of which only first three are strictly required:
- `sesman-start-session`
- `sesman-kill-session`
- - `sesman-restart-session` - defaults to `sesman-start-session` +
`sesman-kill-session`
- - `sesman-more-relevant-p` - used for sorting sessions in "recency" order.
Defaults to sorting by session name.
- <!-- - `sesman-friendly-session-p` - used to define friendly sessions (e.g.
dependency projects). -->
+ - `sesman-restart-session`
+ - `sesman-session-info`
+ - `sesman-context-types`
+ - `sesman-more-relevant-p`
-Depending on the purpose at hand, sesman system can use several functions to
retrieve sessions (`sesman-ensure-linked-session`, `sesman-linked-sessions`,
`sesman-friendly-sessions` and `sesman-sessions`). Most important of these
being `sesman-ensure-linked-session` which should be used to ensure that at
least one session is linked to the current context. It returns the most
specific session given sesman associations already in place. In case of
ambiguity (or no sessions) the user is ask [...]
+Sesman also provides [a range of utility functions][system api] functions to
manipulate sessions, links and session components. Systems can register entire
sessions with `sesman-register` or add/remove objects one by one with
`sesman-add-object`/`sesman-remove-object`.
-Systems could directly use user level commands to manage sessions
(`sesman-start`, `sesman-kill`) or use legacy system specific initializer
(`run-xyz`, `xyz-jack-in` etc). In the latter case, systems should call
`sesman-register` to register their sessions with `sesman`.
+Systems should link [sesman map][] into their key-maps (ideally on `C-c C-s`)
and install sesman menu with `sesman-install-menu`.
-Systems should link [semsna map][] into their modes' key-maps (ideally on `C-c
C-s`, which is a good mnemonic, is free in CIDER and already does similar
things in ESS).
+<!-- , which is a good mnemonic and is already used in CIDER and ESS. -->
-[user interface]: https://github.com/vspinu/sesman/blob/master/sesman.el#L55
-[system interface]: https://github.com/vspinu/sesman/blob/master/sesman.el#L216
-[sesman map]: https://github.com/vspinu/sesman/blob/master/sesman.el#L168
+[user interface]: https://github.com/vspinu/sesman/blob/master/sesman.el#L242
+[sesman map]: https://github.com/vspinu/sesman/blob/master/sesman.el#L331
+[system interface]: https://github.com/vspinu/sesman/blob/master/sesman.el#L379
+[system api]: https://github.com/vspinu/sesman/blob/master/sesman.el#L411
[cider]: https://github.com/clojure-emacs/cider
[ess]: https://ess.r-project.org/
diff --git a/sesman.el b/sesman.el
index 6da6e32179..fd3a7c022f 100644
--- a/sesman.el
+++ b/sesman.el
@@ -407,26 +407,9 @@ provide a more meaningful ordering. If your system objects
are buffers you
can use `sesman-more-relevant-p' utility in this method."
(not (string-greaterp (car session1) (car session2))))
-;; (cl-defgeneric sesman-session-object-type (system)
-;; "Return type (a symbol) of the constituents of the session object.
-;; Depending on this type, sesman might provide additional
-;; functionality (e.g. a better default for
-;; `sesman-more-relevant-p'). Currently only 'buffer is understood."
-;; nil)
-
-;; (cl-defgeneric sesman-friendly-session-p (system session)
-;; "Non-nil if SYSTEM's SESSION is friendly to current context.
-;; A friendly session is the one for which it makes sense to create
-;; an association with current contexts. For example, if the user
-;; is within the project A which is required (dependent upon) from
-;; project B, then a session opened within project B is a friendly
-;; session for current context. By default, there all sessions are
-;; friendly sessions."
-;; ;; by default all are friendly sessions
-;; t)
-
;;; System API
+
(defun sesman-session (system session-name)
"Retrieve SYSTEM's session with SESSION-NAME from global hash."
(let ((system (or system (sesman--system))))
- [nongnu] branch elpa/sesman created (now e0f555f963), ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 6aa04521eb 012/100: Add badges, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 0f6eadfb1a 004/100: Idem, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman b27755c150 003/100: Major update before cider integration, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman e83fcfd939 002/100: Add readme, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 4f52cccf26 013/100: Update readme,
ELPA Syncer <=
- [nongnu] elpa/sesman fea061de16 007/100: Add sesman menu, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman a39f0e2c1b 015/100: Add commentary, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 13f7748b9f 017/100: Rename sesman-single-link-contexts -> sesman-single-link-context-types, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 0303d66f0e 019/100: Rename link accessors --link- -> --lnk- to avoid naming confusion, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 0f86bd3d34 021/100: Rename sesman-ensure-linked-session -> sesman-ensure-session, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 43b0c9ef2a 026/100: [Fix #4] Rename lingering sesman-ensure-linked-session, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman fb4d2784f3 025/100: Fix typo in README, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 16be56c643 032/100: Add a missing :package-version to a defcustom, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 4229e2128c 027/100: Replace a redundant let*, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 9ec1c330a6 034/100: Fix typo sesman-more-relevant-p -> sesman-more-recent-p, ELPA Syncer, 2021/12/28