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.
A on/off toggle. It’s value will be non-nil when on and nil if off.
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.
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’.
A number. This infix uses the read-number function obtain the selected number.
A simple string.
A regular expression string.
A directory. This infix uses the read-directory-name function to read a user’s selected directory.
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))))