Provided by: mmh_0.4-1_amd64 bug

NAME

       pick - select messages by content scan - produce a one line per message scan listing

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]
            [-format formatfile] [-width columns] [-thread [+folder]messages|files] [-file
            mboxfilename] [-sequence name ...]  [-public | -nopublic] [-zero | -nozero] [-list |
            -nolist] [-Version] [-help]

       scan is equivalent to pick -format scan.default

       typical usage:

            scan -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.

       The default regex(7) is used to perform the  matching,  so  the  full  regular  expression
       facility  is  available  within pattern.  With -search, pattern is used directly, but only
       for the body of the Mail.  With the others, pick  compares  the  header  field  name  case
       insensitive and the tries to match the field body with the pattern.

       With  --componend  you can specify the exact header field name you are looking for.  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-header-field  basis. Within the header of the
       message, each field is treated as one long line, but in the body, each line  is  separate.
       The pattern will match any 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').  Further more, dates in a  simplified  ISO  8601/RFC  3339  style  (e.g.
       `YYYY-MM-DD'  or  `YYYY-MM-DD  hh:mm:ss')  are  accepted.   Finally,  in addition to these
       special specifications, pick will also honor a date  specification  of  the  form  `-ddd',
       which means `ddd days ago'.  For example,

            pick -after -30

       identifies the messages of the last thirty days.

       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 `a').

       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  mmh  programs  by  using  the
       `backquoting' syntax of the shell.  For example, the command

            show `pick +todo -after `31 Mar 83 0123 PST'`

       says  to show those messages in the indicated folder which meet the appropriate criterion.
       Note that since pick's context changes are written out prior  to  show's  invocation,  you
       need not give the folder argument to show 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.

       Scan and pick produces a one-line-per-message listing of the specified and selected folder
       or messages.  The default format is for pick is to  print  the  message  number  for  each
       message.   The default Scan line contains the message number (name), the date, the `From:'
       field and the `Subject' field.  The following example shows the default output of scan

            15+     10/05 crocker nned
            16-    10/05 crocker message id format
            18      10/06 brien   Re: Exit status from mkdir
            19      10/07*brien   `scan' listing format in mmh

       The `+' on message 15 indicates that it is the current message.  The  `-'  on  message  16
       indicates that it has been replied to, as indicated by a `Replied:' component (produced by
       the -annotate switch to the repl command).  The  `*'  on  message  19  indicates  that  no
       `Date:'  header  was  present.   The  time  of  last  modification of the message is given
       instead.  Scan actually reads each of the specified messages and parses  them  to  extract
       the  desired fields.  During parsing, appropriate error messages will be produced if there
       are format errors in any of the messages.

       By default, scan will decode RFC-2047 (MIME) encoding in these scan listings.   Scan  will
       only  decode  these fields if your terminal can natively display the character set used in
       the encoding.  You should set the MM_CHARSET environment variable to your native character
       set,  if  it  is  not  US-ASCII.   See  the  mh-profile(5) man page for details about this
       environment variable.

       The -file filename switch allows the user to obtain a scan listing of a maildrop  file  as
       produced  by  packf.   This  listing  includes  every  message in the file (you can't scan
       individual messages).

       The switch -width columns may be used to specify the width of the scan line.  The  default
       is to use the width of the terminal.

       The command:

            (scan | pr ; show a -showproc pr) | lpr

       produces  a  scan  listing  of  the current folder, followed by a formatted listing of all
       messages in the folder, one per page.  Omitting `-showproc pr' will cause the messages  to
       be concatenated, separated by a one-line header and two blank lines.

       To  override  the output format used by scan, the -form file switch is used.  This permits
       individual fields of the scan listing to be extracted with ease.  file is either the  name
       of  a  format  file or a format string directly, if prepended with an equal sign `='.  See
       mh-format(5) for the details.

       In addition to the standard mh-format(5)  escapes,  scan  also  recognizes  the  following
       additional component escapes:

            Escape      Returns Description
            dtimenow        date    the current date
            folder  string  the name of the current folder

       If  no date header is present in the message, the function escapes which operate on {date}
       will return values for the date of last modification of the  message  file  itself.   This
       feature  is handy for scanning a draft folder, as message drafts usually aren't allowed to
       have dates in them.

       scan will update the mmh context prior to starting the listing,  so  interrupting  a  long
       scan listing preserves the new context.  nmh purists hate this idea.

FILES

       $HOME/.mmh/profile         The user profile

PROFILE COMPONENTS

       Path:                To determine the user's mail storage
       Alternate-Mailboxes: To determine the user's mailboxes
       Current-Folder:      To find the default current folder

SEE ALSO

       mark(1)

DEFAULTS

       `+folder' defaults to the current folder
       `msgs' defaults to all messages
       `-datefield date'
       `-zero'
       `-list' is the default if no `-sequence', `-nolist' otherwise
       `-format pick.default' if the program is called with scan `scan.default' is used

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 l:20 -seq fear`

       instead of typing

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

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

       In  MH  ,  nmh and old mmh versions scan and pick where two different tools. So instand of
       typing

            scan -from philipp

       you had typed

            scan `pick -from philipp`

       With the default config the old style usage is still supported, so you can  write  scripts
       for both mmh and nmh.

HELPFUL HINTS

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

BUGS

       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 mmh 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.

       To account for this case when combining pick with regular  shell  tools,  filter  out  the
       message number `0'.  For example, do

            pick ... | fgrep -vx 0 | wc -l

       to count the number of messages picked.

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