git.marmaro.de Git - mmh/blob - man/pick.man

   1 .\"
   2 .\" %nmhwarning%
   3 .\"
   4 .TH PICK %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
   5 .SH NAME
   6 pick \- search for messages by content
   7 .SH SYNOPSIS
   8 .HP 5
   9 .na
  10 .B pick
  11 .RI [ +folder ]
  12 .RI [ msgs ]
  13 .RB [ \-and
  14 \&...]
  15 .RB [ \-or
  16 \&...]
  17 .RB [ \-not
  18 \&...]
  19 .RB [ \-lbrace
  20 \&...
  21 .BR \-rbrace ]
  22 .RB [ \-\|\-component
  23 .IR pattern ]
  24 .RB [ \-cc
  25 .IR pattern ]
  26 .RB [ \-date
  27 .IR pattern ]
  28 .RB [ \-from
  29 .IR pattern ]
  30 .RB [ \-search
  31 .IR pattern ]
  32 .RB [ \-subject
  33 .IR pattern ]
  34 .RB [ \-to
  35 .IR pattern ]
  36 .RB [ \-after
  37 .IR date ]
  38 .RB [ \-before
  39 .IR date ]
  40 .RB [ \-datefield
  41 .IR field ]
  42 .RB [ \-sequence
  43 .I name
  44 \&...]
  45 .RB [ \-public " | " \-nopublic ]
  46 .RB [ \-zero " | " \-nozero ]
  47 .RB [ \-list " | " \-nolist ]
  48 .RB [ \-version ]
  49 .RB [ \-help ]
  50 .PP
  51 typical usage:
  52 .PP
  53 .RS 5
  54 .nf
  55 scan\0`pick\0\-from\0jones`
  56 pick\0\-to\0holloway\0\-sequence\0select
  57 show\0`pick\0\-before\0friday`
  58 .fi
  59 .RE
  60 .ad
  61 .SH DESCRIPTION
  62 .B Pick
  63 searches within a folder for messages with the specified
  64 contents, and then identifies those messages.  Two types of search
  65 primitives are available: pattern matching and date constraint
  66 operations.
  67 .PP
  68 A modified
  69 .BR grep (1)
  70 is used to perform the matching, so the
  71 full regular expression (see
  72 .BR ed (1))
  73 facility is available
  74 within
  75 .IR pattern .
  76 With
  77 .BR \-search ,
  78 .I pattern
  79 is used directly, and with the others, the grep pattern constructed is:
  80 .PP
  81 .RS 5
  82 `component[ \\t]*:\&.*pattern'
  83 .RE
  84 .PP
  85 This means that the pattern specified for a
  86 .B \-search
  87 will be found
  88 everywhere in the message, including the header and the body, while
  89 the other pattern matching requests are limited to the single specified
  90 component.  The expression
  91 .PP
  92 .RS 5
  93 `\-\|\-component\ pattern'
  94 .RE
  95 .PP
  96 is a shorthand for specifying
  97 .PP
  98 .RS 5
  99 `\-search \*(lqcomponent[ \\t]*:\&.*pattern\*(rq\ '
 100 .RE
 101 .PP
 102 It is used to pick a component which is not one of \*(lqTo:\*(rq,
 103 \*(lqcc:\*(rq, \*(lqDate:\*(rq, \*(lqFrom:\*(rq, or \*(lqSubject:\*(rq.
 104 An example is
 105 .RB \*(lq "pick\0\-\|\-reply\-to\0pooh" \*(rq.
 106 .PP
 107 Pattern matching is performed on a per\-line basis.  Within the header
 108 of the message, each component is treated as one long line, but in the
 109 body, each line is separate.  Lower\-case letters in the search pattern
 110 will match either lower or upper case in the message, while upper case
 111 will match only upper case.
 112 .PP
 113 Note that since the
 114 .B \-date
 115 switch is a pattern matching operation (as
 116 described above), to find messages sent on a certain date the pattern
 117 string must match the text of the \*(lqDate:\*(rq field of the message.
 118 .PP
 119 Independent of any pattern matching operations requested, the switches
 120 .B \-after
 121 .I date
 122 or
 123 .B \-before
 124 .I date
 125 may also be used to introduce date/time
 126 constraints on all of the messages.  By default, the \*(lqDate:\*(rq
 127 field is consulted, but if another date yielding field (such as
 128 \*(lqBB\-Posted:\*(rq or \*(lqDelivery\-Date:\*(rq) should be used, the
 129 .B \-datefield
 130 .I field
 131 switch may be used.
 132 .PP
 133 With
 134 .B \-before
 135 and
 136 .BR \-after ,
 137 .B pick
 138 will actually parse the date
 139 fields in each of the messages specified in `msgs' and compare them
 140 to the date/time specified.  If
 141 .B \-after
 142 is given, then only those
 143 messages whose \*(lqDate:\*(rq field value is chronologically after the
 144 date specified will be considered.  The
 145 .B \-before
 146 switch specifies the
 147 complimentary action.
 148 .PP
 149 Both the
 150 .B \-after
 151 and
 152 .B \-before
 153 switches take legal 822\-style date
 154 specifications as arguments.
 155 .B Pick
 156 will default certain missing
 157 fields so that the entire date need not be specified.  These fields
 158 are (in order of defaulting): timezone, time and timezone, date, date
 159 and timezone.  All defaults are taken from the current date, time,
 160 and timezone.
 161 .PP
 162 In addition to 822\-style dates,
 163 .B pick
 164 will also recognize any of
 165 the days of the week (\*(lqsunday\*(rq, \*(lqmonday\*(rq, and so on),
 166 and the special dates \*(lqtoday\*(rq, \*(lqyesterday\*(rq (24 hours
 167 ago), and \*(lqtomorrow\*(rq (24 hours from now).  All days of the
 168 week are judged to refer to a day in the past (e.g., telling \fIpick\fR
 169 \*(lqsaturday\*(rq on a \*(lqtuesday\*(rq means \*(lqlast\ saturday\*(rq
 170 not \*(lqthis\ saturday\*(rq).
 171 .PP
 172 Finally, in addition to these special specifications,
 173 .B pick
 174 will
 175 also honor a specification of the form \*(lq\-dd\*(rq, which means
 176 \*(lqdd days ago\*(rq.
 177 .PP
 178 .B Pick
 179 supports complex boolean operations on the searching primitives
 180 with the
 181 .BR \-and ,
 182 .BR \-or ,
 183 .BR \-not ,
 184 and
 185 .B \-lbrace
 186 .B \&...
 187 .B \-rbrace
 188 switches.
 189 For example,
 190 .PP
 191 .RS 5
 192 .nf
 193 pick\0\-after\0yesterday\0\-and
 194      \-lbrace\0\-from\0freida\0\-or\0\-from\0fear\0\-rbrace
 195 .fi
 196 .RE
 197 .PP
 198 identifies messages recently sent by \*(lqfrieda\*(rq or \*(lqfear\*(rq.
 199 .PP
 200 The matching primitives take precedence over the
 201 .B \-not
 202 switch, which in turn takes precedence over
 203 .B \-and
 204 which in turn takes precedence
 205 over
 206 .BR \-or .
 207 To override the default precedence, the
 208 .B \-lbrace
 209 and
 210 .B \-rbrace
 211 switches are provided, which act just like opening and closing
 212 parentheses in logical expressions.
 213 .PP
 214 If no search criteria are given, all the messages specified on the
 215 command line are selected (this defaults to \*(lqall\*(rq).
 216 .PP
 217 Once the search has been performed, if the
 218 .B \-list
 219 switch is given, the
 220 message numbers of the selected messages are written to the standard
 221 output separated by newlines.  This is
 222 .B extremely
 223 useful for
 224 quickly generating arguments for other
 225 .B nmh
 226 programs by using the
 227 \*(lqbackquoting\*(rq syntax of the shell.  For example, the command
 228 .PP
 229 .RS 5
 230 scan\0`pick\0+todo\0\-after\0\*(lq31 Mar 83 0123 PST\*(rq`
 231 .RE
 232 .PP
 233 says to
 234 .B scan
 235 those messages in the indicated folder which meet the
 236 appropriate criterion.  Note that since
 237 .BR pick 's
 238 context changes
 239 are written out prior to
 240 .BR scan 's
 241 invocation, you need not give
 242 the folder argument to
 243 .B scan
 244 as well.
 245 .PP
 246 The
 247 .B \-sequence
 248 .I name
 249 switch may be given once for each sequence the user wishes to define.
 250 For each sequence named, that sequence will be defined to mean exactly
 251 those messages selected by
 252 .BR pick .
 253 For example,
 254 .PP
 255 .RS 5
 256 pick\0\-from\0frated\0\-seq\0fred
 257 .RE
 258 .PP
 259 defines a new message sequence for the current folder called
 260 \*(lqfred\*(rq which contains exactly those messages that were selected.
 261 .PP
 262 By default,
 263 .B pick
 264 will zero the sequence before adding it.  This
 265 action can be disabled with the
 266 .B \-nozero
 267 switch, which means that the
 268 messages selected by
 269 .B pick
 270 will be added to the sequence, if it
 271 already exists, and any messages already a part of that sequence will
 272 remain so.
 273 .PP
 274 The
 275 .B \-public
 276 and
 277 .B \-nopublic
 278 switches are used by
 279 .B pick
 280 in the
 281 same way
 282 .B mark
 283 uses them.
 284
 285 .SH FILES
 286 .fc ^ ~
 287 .nf
 288 .ta \w'%etcdir%/ExtraBigFileName  'u
 289 ^$HOME/\&.mh\(ruprofile~^The user profile
 290 .fi
 291
 292 .SH "PROFILE COMPONENTS"
 293 .fc ^ ~
 294 .nf
 295 .ta 2.4i
 296 .ta \w'ExtraBigProfileName  'u
 297 ^Path:~^To determine the user's nmh directory
 298 ^Current\-Folder:~^To find the default current folder
 299 .fi
 300
 301 .SH "SEE ALSO"
 302 mark(1)
 303
 304 .SH DEFAULTS
 305 .nf
 306 .RB ` +folder "' defaults to the current folder"
 307 .RB ` msgs "' defaults to all"
 308 .RB ` "\-datefield date" '
 309 .RB ` \-zero '
 310 .RB ` \-list "' is the default if no `\-sequence', `\-nolist' otherwise"
 311 .fi
 312
 313 .SH CONTEXT
 314 If a folder is given, it will become the current folder.
 315
 316 .SH HISTORY
 317 In previous versions of
 318 .BR MH ,
 319 the
 320 .B pick
 321 command would
 322 .BR show ,
 323 .BR scan ,
 324 or
 325 .B refile
 326 the selected messages.  This was rather
 327 \*(lqinverted logic\*(rq from the UNIX point of view, so
 328 .B pick
 329 was changed to define sequences and output those sequences.  Hence,
 330 .B pick
 331 can be used to generate the arguments for all other
 332 .B MH
 333 commands, instead of giving
 334 .B pick
 335 endless switches for invoking those commands
 336 itself.
 337 .PP
 338 Also, previous versions of
 339 .B pick
 340 balked if you didn't specify
 341 a search string or a date/time constraint.  The current version does
 342 not, and merely matches the messages you specify.  This lets you type
 343 something like:
 344 .PP
 345 .RS 5
 346 show\0`pick\0last:20\0\-seq\0fear`
 347 .RE
 348 .PP
 349 instead of typing
 350 .PP
 351 .RS 5
 352 .nf
 353 mark\0\-add\0\-nozero\0\-seq\0fear\0last:20
 354 show\0fear
 355 .fi
 356 .RE
 357 .PP
 358 Finally, timezones used to be ignored when comparing dates: they aren't
 359 any more.
 360
 361 .SH "HELPFUL HINTS"
 362 Use
 363 .RB \*(lq "pick sequence \-list" \*(rq
 364 to enumerate the messages in a sequence
 365 (such as for use by a shell script).
 366
 367 .SH BUGS
 368 The argument to the
 369 .B \-after
 370 and
 371 .B \-before
 372 switches must be interpreted
 373 as a single token by the shell that invokes
 374 .BR pick .
 375 Therefore, one
 376 must usually place the argument to this switch inside double\-quotes.
 377 Furthermore, any occurrence of
 378 .B \-datefield
 379 must occur prior to the
 380 .B \-after
 381 or
 382 .B \-before
 383 switch it applies to.
 384 .PP
 385 If
 386 .B pick
 387 is used in a back\-quoted operation, such as
 388 .PP
 389 .RS 5
 390 scan\0`pick\0\-from\0jones`
 391 .RE
 392 .PP
 393 and
 394 .B pick
 395 selects no messages (e.g., no messages are from
 396 \*(lqjones\*(rq), then the shell will still run the outer command (e.g.,
 397 .BR scan ).
 398 Since no messages were matched,
 399 .B pick
 400 produced
 401 no output, and the argument given to the outer command as a result of
 402 backquoting
 403 .B pick
 404 is empty.  In the case of
 405 .B nmh
 406 programs,
 407 the outer command now acts as if the default `msg' or `msgs' should be
 408 used (e.g., \*(lqall\*(rq in the case of
 409 .BR scan ).
 410 To prevent this
 411 unexpected behavior, if
 412 .B \-list
 413 was given, and if its standard output is not a tty, then
 414 .B pick
 415 outputs the illegal message number \*(lq0\*(rq
 416 when it fails.  This lets the outer command fail gracefully as well.
 417 .PP
 418 The pattern syntax \*(lq[l-r]\*(rq is not supported; each letter to be
 419 matched must be included within the square brackets.