Provided by: nmh_1.2-3_i386 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  double-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.