6.1 Comparison With Prefix Keys and Prefix Arguments

While transient commands were inspired by regular prefix keys and prefix arguments, they are also quite different and much more complex.

The following diagrams illustrate some of the differences.

Regular Prefix Commands

See (elisp)Prefix Keys.

                                  ,--> command1 --> (c)
                                  |
(c)-(+)-> prefix command or key --+--> command2 --> (c)
                                  |
                                  `--> command3 --> (c)

Regular Prefix Arguments

See (elisp)Prefix Command Arguments.

        ,----------------------------------,
        |                                  |
        v                                  |
(c)-(+)---> prefix argument command --(c)-(+)-> any command --> (c)
               |                                        ^        |
               |                                        |        |
               `-- sets or changes --, ,-- maybe used --'        |
                                     | |                         |
                                     v |                         |
                          prefix argument state                  |
                                      ^                          |
                                      |                          |
                                      `-------- discards --------'

Transients

(∩`-´)⊃━☆゚.*・。゚

This diagram ignores the infix value and external state:

(c)
 |        ,- {stay} ------<-,-<------------<-,-<---,
(+)       |                 |                |     |
 |        |                 |                |     |
 |        |   ,--> infix1 --|                |     |
 |        |   |             |                |     |
 |        |   |--> infix2 --|                |     |
 v        v   |             |                |     |
 prefix -(c)-(+)-> infix3 --'                ^     |
              |                              |     |
              |---------------> suffix1 -->--|     |
              |                              |     |
              |---------------> suffix2 ----{1}------> {exit} --> (c)
              |                                    |
              |---------------> suffix3 -------------> {exit} --> (c)
              |                                    |
              `--> any command --{2}-> {warn} -->--|
                                  |                |
                                  |--> {noop} -->--|
                                  |                |
                                  |--> {call} -->--'
                                  |
                                  `------------------> {exit} --> (c)

This diagram takes the infix value into account to an extend, while still ignoring external state:

(c)
 |        ,- {stay} ------<-,-<------------<-,-<---,
(+)       |                 |                |     |
 |        |                 |                |     |
 |        |   ,--> infix1 --|                |     |
 |        |   |    |        |                |     |
 |        |   ,--> infix2 --|                |     |
 v        v   |    |        |                |     |
 prefix -(c)-(+)-> infix3 --'                |     |
              |    |                         ^     |
              |    |                         |     |
              |---------------> suffix1 -->--|     |
              |    |             ^           |     |
              |    |             |           |     |
              |---------------> suffix2 ----{1}------> {exit} --> (c)
              |    |             ^                 |     |
              |    |             |                 |     v
              |    |             |                 |     |
              |---------------> suffix3 -------------> {exit} --> (c)
              |    |             ^                 |     |
              | sets             |                 |     v
              |    |             maybe             |     |
              |    |             used              |     |
              |    |             |                 |     |
              |    |     infix --'                 |     |
              |    `---> value                     |     |
              |           ^                        |     |
              |           |                        |     |
              |       hides                        |     |
              |           |                        |     |
              |           `--------------------------<---|
              |                                    |     |
              `--> any command --{2}-> {warn} -->--|     |
                                  |                |     |
                                  |--> {noop} -->--|     |
                                  |                |     |
                                  |--> {call} -->--'     ^
                                  |                      |
                                  `------------------> {exit} --> (c)

This diagram provides more information about the infix value and also takes external state into account.

                                       ,----sets--- "anything"
                                       |
                                       v
                      ,---------> external
                      |           state
                      |            | |
                      |  initialized |                      ☉‿⚆
                   sets         from |
                      |            | maybe
                      | ,----------' used
                      | |            |
(c)                   | |            v
 |        ,- {stay} --|---<-,-<------|-----<-,-<---,
(+)       |           | |   |        |       |     |
 |        |           | v   |        |       |     |
 |        |   ,--> infix1 --|        |       |     |
 |        |   |       | |   |        |       |     |
 |        |   |       | v   |        |       |     |
 |        |   ,--> infix2 --|        |       |     |
 |        |   |    | ^      |        |       |     |
 v        v   |    | |      |        |       |     |
 prefix -(c)-(+)-> infix3 --'        |       |     |
              |    | ^               |       ^     |
              |    | |               v       |     |
              |---------------> suffix1 -->--|     |
              |    | |            ^  |       |     |
              |    | |            |  v       |     |
              |---------------> suffix2 ----{1}------> {exit} --> (c)
              |    | |            ^  |             |     |
              |    | |            |  |             |     v
              |    | |            |  v             |     |
              |---------------> suffix3 -------------> {exit} --> (c)
              |    | |            ^                |     |
              | sets |            |                |     v
              |    | initialized  maybe            |     |
              |    | from         used             |     |
              |    | |            |                |     |
              |    | `-- infix ---'                |     |
              |    `---> value -----------------------------> persistent
              |           ^ ^                      |     |    across
              |           | |                      |     |    invocations -,
              |       hides |                      |     |                 |
              |           | `----------------------------------------------'
              |           |                        |     |
              |           `--------------------------<---|
              |                                    |     |
              `--> any command --{2}-> {warn} -->--|     |
                                  |                |     |
                                  |--> {noop} -->--|     |
                                  |                |     |
                                  |--> {call} -->--'     ^
                                  |                      |
                                  `------------------> {exit} --> (c)

Despite already being rather complex, even the last diagram leaves out many details. Most importantly it implies that the decision whether to remain transient is made later than it actually is made (for the most part a function on pre-command-hook is responsible). But such implementation details are of little relevance to users and are covered elsewhere.