Provided by: nmh_1.5-release-5_amd64 bug

NAME

       pick - search for messages by content

SYNOPSIS

       pick [+folder] [msgs] [-and ...]  [-or ...]  [-not ...]  [-lbrace ...  -rbrace]
            [--component pattern] [-cc pattern] [-date pattern] [-from pattern] [-search pattern]
            [-subject pattern] [-to pattern] [-after date] [-before date] [-datefield field]
            [-sequence name ...]  [-public | -nopublic] [-zero | -nozero] [-list | -nolist]
            [-version] [-help]

       typical usage:

            scan `pick -from jones`
            pick -to holloway -sequence select
            show `pick -before friday`

DESCRIPTION

       Pick  searches  within  a  folder  for  messages  with  the  specified  contents, and then
       identifies those messages.  Two types of search primitives are available: pattern matching
       and date constraint operations.

       A  modified  grep(1)  is used to perform the matching, so the full regular expression (see
       ed(1)) facility is available within pattern.  With -search, pattern is used directly,  and
       with the others, the grep pattern constructed is:

            `component[ \t]*:.*pattern'

       This  means  that  the  pattern  specified  for  a -search will be found everywhere in the
       message, including the header and the body, while the other pattern matching requests  are
       limited to the single specified component.  The expression

            `--component pattern'

       is a shorthand for specifying

            `-search “component[ \t]*:.*pattern” '

       It  is  used  to  pick  a component which is not one of “To:”, “cc:”, “Date:”, “From:”, or
       “Subject:”.  An example is “pick --reply-to pooh”.

       Pattern matching is performed on a per-line basis.  Within the header of the message, each
       component is treated as one long line, but in the body, each line is separate.  Lower-case
       letters in the search pattern will match either lower or upper case in the message,  while
       upper case will match only upper case.

       Note  that since the -date switch is a pattern matching operation (as described above), to
       find messages sent on a certain date the pattern string must match the text of the “Date:”
       field of the message.

       Independent  of  any  pattern  matching  operations requested, the switches -after date or
       -before date may also be used to introduce date/time constraints on all of  the  messages.
       By  default,  the  “Date:” field is consulted, but if another date yielding field (such as
       “BB-Posted:” or “Delivery-Date:”) should be used, the -datefield field switch may be used.

       With -before and -after, pick will actually parse the date fields in each of the  messages
       specified in `msgs' and compare them to the date/time specified.  If -after is given, then
       only those messages whose “Date:” field value is chronologically after the date  specified
       will be considered.  The -before switch specifies the complimentary action.

       Both  the  -after  and  -before  switches  take  legal  822-style  date  specifications as
       arguments.  Pick will default certain missing fields so that the entire date need  not  be
       specified.   These fields are (in order of defaulting): timezone, time and timezone, date,
       date and timezone.  All defaults are taken from the current date, time, and timezone.

       In addition to 822-style dates, pick will also recognize any  of  the  days  of  the  week
       (“sunday”,  “monday”,  and  so  on),  and the special dates “today”, “yesterday” (24 hours
       ago), and “tomorrow” (24 hours from now).  All days of the week are judged to refer  to  a
       day  in  the  past (e.g., telling pick “saturday” on a “tuesday” means “last saturday” not
       “this saturday”).

       Finally, in addition to these special specifications, pick will also honor a specification
       of the form “-dd”, which means “dd days ago”.

       Pick  supports  complex boolean operations on the searching primitives with the -and, -or,
       -not, and -lbrace ...  -rbrace switches.  For example,

            pick -after yesterday -and
                 -lbrace -from freida -or -from fear -rbrace

       identifies messages recently sent by “frieda” or “fear”.

       The matching primitives take  precedence  over  the  -not  switch,  which  in  turn  takes
       precedence  over  -and  which  in turn takes precedence over -or.  To override the default
       precedence, the -lbrace and -rbrace switches are provided, which act just like opening and
       closing parentheses in logical expressions.

       If  no  search  criteria  are  given,  all  the messages specified on the command line are
       selected (this defaults to “all”).

       Once the search has been performed, if the -list switch is given, the message  numbers  of
       the  selected  messages are written to the standard output separated by newlines.  This is
       extremely useful for quickly generating arguments for other  nmh  programs  by  using  the
       “backquoting” syntax of the shell.  For example, the command

            scan `pick +todo -after “31 Mar 83 0123 PST”`

       says  to scan those messages in the indicated folder which meet the appropriate criterion.
       Note that since pick's context changes are written out prior  to  scan's  invocation,  you
       need not give the folder argument to scan as well.

       The  -sequence  name switch may be given once for each sequence the user wishes to define.
       For each sequence named, that sequence will be defined  to  mean  exactly  those  messages
       selected by pick.  For example,

            pick -from frated -seq fred

       defines a new message sequence for the current folder called “fred” which contains exactly
       those messages that were selected.

       By default, pick will zero the sequence before adding it.  This  action  can  be  disabled
       with  the  -nozero switch, which means that the messages selected by pick will be added to
       the sequence, if it already exists, and any messages already a part of that sequence  will
       remain so.

       The -public and -nopublic switches are used by pick in the same way mark uses them.

FILES

       $HOME/.mh_profile          The user profile

PROFILE COMPONENTS

       Path:                To determine the user's nmh directory
       Current-Folder:      To find the default current folder

SEE ALSO

       mark(1)

DEFAULTS

       `+folder' defaults to the current folder
       `msgs' defaults to all
       `-datefield date'
       `-zero'
       `-list' is the default if no `-sequence', `-nolist' otherwise

CONTEXT

       If a folder is given, it will become the current folder.

HISTORY

       In  previous  versions  of  MH,  the pick command would show, scan, or refile the selected
       messages.  This was rather “inverted logic” from the UNIX  point  of  view,  so  pick  was
       changed  to  define  sequences  and  output  those  sequences.  Hence, pick can be used to
       generate the arguments for all other MH commands, instead of giving pick endless  switches
       for invoking those commands itself.

       Also,  previous  versions  of  pick  balked  if  you  didn't  specify a search string or a
       date/time constraint.  The current version does not, and merely matches the  messages  you
       specify.  This lets you type something like:

            show `pick last:20 -seq fear`

       instead of typing

            mark -add -nozero -seq fear last:20
            show fear

       Finally, timezones used to be ignored when comparing dates: they aren't any more.

HELPFUL HINTS

       Use  “pick  sequence  -list” to enumerate the messages in a sequence (such as for use by a
       shell script).

BUGS

       The argument to the -after and -before switches must be interpreted as a single  token  by
       the  shell  that  invokes  pick.   Therefore,  one must usually place the argument to this
       switch inside quotes.  Furthermore, any occurrence of -datefield must occur prior  to  the
       -after or -before switch it applies to.

       If pick is used in a back-quoted operation, such as

            scan `pick -from jones`

       and  pick  selects  no  messages (e.g., no messages are from “jones”), then the shell will
       still run the outer command (e.g., scan).  Since no messages were matched,  pick  produced
       no  output, and the argument given to the outer command as a result of backquoting pick is
       empty.  In the case of nmh programs, the outer command now acts as if the default `msg' or
       `msgs'  should  be  used  (e.g.,  “all”  in the case of scan).  To prevent this unexpected
       behavior, if -list was given, and if its standard output is not a tty, then  pick  outputs
       the illegal message number “0” when it fails.  This lets the outer command fail gracefully
       as well.

       The pattern syntax “[l-r]” is not supported; each letter to be matched  must  be  included
       within the square brackets.