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))))