5.3 Input/Options Specification

Input and option specifications are used in all of the main entities of p-search. They are used to define what data a particular component needs. A input/option specification is an alist where the car element is the argument symbol, and the cdr is the transient specification. p-search being driven by transient, transient infix is needed for each argument type, in order for the system to know how to read and display such arguments.

The following is a list of the available transient infixes to choose from. The specification part is of the form (infix-item &key kwargs). Each type can take the arguments :key, :description, :default-value, and :instruction-string.

p-search-infix-toggle

A on/off toggle. It’s value will be non-nil when on and nil if off.

p-search-infix-choices

Prompt the user for a selection out of a list of possible choices. In addition to the standard arguments, the argument :choices should also be provided, which should be a list of possible choices or a function to call to get a list of possible choices.

p-search-infix-date

A date with time. This infix uses org-mode’s org-read-date function to get the user’s selected date. The value of this will be a string in the form ‘%Y-%m-%d %H:%m’.

p-search-infix-number

A number. This infix uses the read-number function obtain the selected number.

p-search-infix-string

A simple string.

p-search-infix-regexp

A regular expression string.

p-search-infix-directory

A directory. This infix uses the read-directory-name function to read a user’s selected directory.

p-search-infix-memory

An amount of memory. This uses a specialized reader that can understand the various units of memory (e.g. KB, KiB).

The :key parameter should be the string of the transient key to press. The :description parameter is the human-readable name of the item that will show up on various UI components. The :default-value should be the default value that the parameter takes, or a function with no arguments that returns it. If a default value is provided on an input, the user will not be prompted for the value. The :instruction-string parameter is a string that will show up when prompting a user for the item, which should give more detailed instructions about what the field does or what is expected.

The following are some examples of input/options specs:

;;; example 1
  '((n-commits . (p-search-infix-number
                   :key "n"
                   :description "Last N Commits to Consider"
                   :default-value 20)))

;;; example 2
  `((time-scale . (p-search-infix-choices
                    :key "t"
                    :description "Time Scale"
                    :instruction-string
                    "The scale of time where you expecct the most differentiation to happen.
E.g. For \"yesterday vs three days ago vs 10 days ago\" choose :days.
     For \"This year vs last year vs three years ago\" choose :years."
                    :choices ,(mapcar #'car p-search--time-scales)
                    :default-value :months))
     (target-date . (p-search-infix-date
                     :key "d"
                     :description "Target Date"
                     :default-value ,(format-time-string "%Y-%m-%d %H:%m"))))

;;; example 3
   `((base-directory . (p-search-infix-directory
                        :key "d"
                        :description "Directories"
                        :default-value (lambda () default-directory)))
     (filename-regexp . (p-search-infix-regexp
                         :key "f"
                         :description "Filename Pattern"
                         :default-value ".*"))
     (search-tool . (p-search-infix-choices
                     :key "t"
                     :description "Search Tool"
                     :choices (:grep :rg :ag)
                     :default-value ,(or p-search-default-search-tool :grep))))