Suffix Slots

Here we document most of the slots that are only available for suffix objects. Some slots are shared by suffix and group objects, they are documented in Predicate Slots.

Also see Suffix Classes.

Slots of transient-child

This is the abstract superclass of transient-suffix and transient-group. In addition to the slots listed below, this class is also where the if* and inapt-if* slots (see Predicate Slots) and the level slot (see Enabling and Disabling Suffixes) are defined.

• parent The object for the parent group, if any.
• inactive If an :if* predicate of a suffix or group returns nil, then it is not displayed in the menu, but it has to remain in the internal object tree, in case that predicate later returns t, and the object therefore has to appear in the menu again. Likewise a group or suffix may be (potentially only temporarily) inactive due to its level. The inactive slot is set accordingly. Never set it yourself.

The following two slots are experimental. If they are set for a group, then they apply to all suffixes in that group, except for suffixes that themselves set the same slot to a non-nil value.

• advice A function used to advise the command. The advise is called using (apply advice command args), i.e., it behaves like an "around" advice.
• advice* A function used to advise the command. Unlike advice, this advises not only the command body but also its interactive spec. If both slots are non-nil, advice is used for the body and advice* is used for the interactive form. When advising the interactive spec, called using (funcall advice #'advice-eval-interactive-spec spec).

Slots of transient-suffix

• key is the key binding, a string in the format returned by describe-key and understood by kbd.

  That format is more permissive than the one accepted by key-valid-p. Being more permissive makes it possible, for example, to write the key binding, which toggles the -a command line argument, as "-a", instead of having to write "- a". Likewise additional spaces can be added, which is not removed when displaying the binding in the menu, which is useful for alignment purposes.

• command The command, a symbol.

• transient Whether to stay transient. See Transient State.

• format The format used to display the suffix in the menu buffer. It must contain the following %-placeholders:

  • %k For the key.
  • %d For the description.
  • %v For the infix value. Non-infix suffixes don’t have a value.

• description The description, either a string or a function, which is called with zero or one argument (the suffix object), and returns a string.

• face Face used for the description. In simple cases it is easier to use this instead of using a function as description and adding the styling there. face is appended using add-face-text-property.

• show-help A function used to display help for the suffix. If unspecified, the prefix controls how help is displayed for its suffixes. See also function transient-show-help.

• summary A short description to be displayed in addition to the text displayed in the menu itself. If this is nil, the first line of the documentation string is used instead. If non-nil, this must be a string or a function that returns a string or nil.

  This description is displayed as a tooltip, when hovering an element in the menu. If transient-enable-menu-navigation is verbose, it is also shown in the echo area, when navigating the menu.

  The generic function transient-get-summary is used to determine and format this description.

• definition A command, which is used if the body is omitted when defining a command using transient-define-suffix.

Slots of transient-infix

Some of these slots are only meaningful for some of the subclasses. They are defined here anyway to allow sharing certain methods.

• argument The long argument, e.g., --verbose.

• shortarg The short argument, e.g., -v.

• value The value. Should not be accessed directly.

• init-value Function that is responsible for setting the object’s value. If bound, then this is called with the object as the only argument. Usually this is not bound, in which case the object’s primary transient-init-value method is called instead.

• unsavable Whether the value of the suffix is not saved as part of the prefixes.

• multi-value For options, whether the option can have multiple values. If this is non-nil, then the values are read using completing-read-multiple by default and if you specify your own reader, then it should read the values using that function or similar.

  Supported non-nil values are:

  • Use rest for an option that can have multiple values. This is useful e.g., for an -- argument that indicates that all remaining arguments are files (such as git log -- file1 file2).

    In the list returned by transient-args such an option and its values are represented by a single list of the form (ARGUMENT . VALUES).

  • Use repeat for an option that can be specified multiple times.

    In the list returned by transient-args each instance of the option and its value appears separately in the usual from, for example: ("--another-argument" "--option=first" "--option=second").

  In both cases the option’s values have to be specified in the default value of a prefix using the same format as returned by transient-args, e.g., ("--other" "--o=1" "--o=2" ("--" "f1" "f2")).

• always-read For options, whether to read a value on every invocation. If this is nil, then options that have a value are simply unset and have to be invoked a second time to set a new value.

• allow-empty For options, whether the empty string is a valid value.

• history-key The key used to store the history. This defaults to the command name. This is useful when multiple infixes should share the same history because their values are of the same kind.

• reader The function used to read the value of an infix. Not used for switches. The function takes three arguments, PROMPT, INITIAL-INPUT and HISTORY, and must return a string.

• prompt The prompt used when reading the value, either a string or a function that takes the object as the only argument and which returns a prompt string.

• choices A list of valid values, or a function that returns such a list. The latter is not implemented for transient-switches, because I couldn’t think of a use-case. How exactly the choices are used varies depending on the class of the suffix.

Slots of transient-variable

• variable The variable.

Slots of transient-switches

• argument-format The display format. Must contain %s, one of the choices is substituted for that. E.g., --%s-order.
• argument-regexp The regexp used to match any one of the switches. E.g., \\(--\\(topo\\|author-date\\|date\\)-order\\).