diplodocus.org Git - nmh/blob - man/pick.man

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