E-Mail Search Engine

The Computational Chemistry Archives can be searched by sending a search query to the address chemistry-search@ccl.net. A list of files which satisfy your query will be sent back to you via e-mail. This is an experimental service; please send your comments and ideas to the author, Jan K. Labanowski at jkl@ccl.net.

The following document describes the format of the search query. The format, while not simple, allows for precise and elaborate search queries. Please take the time to read these instructions before using the e-mail searcher.

A search query consists of a number of lines of text. The first line consists of a single number. The number corresponds to the number of text patterns you wish to search for. Note that if you only wish to search for one text pattern, you may omit this line provided that you also omit the logical relation (see below.)

Following the first line is a list of regular expressions. There should be exactly one regular expression per line; the number of regular expressions (and thus, the number of lines) should be equal to the number in the first line. The format of regular expressions is described below. (Those familiar with Perl already know the format for regular expressions.)

Following the list of regular expressions is a single line containing a logical relation. The logical relation determines which combination of regular expressions constitute a match. For example, you may wish to find all files which mention carbon and oxygen, or MOPAC or MindTool, or hydrogen and helium but not argon. Logical expressions allow this sort of "pick and choose" behavior. Note that if there is only one regular expression, you may omit the logical relation. The format of logical relations is also described below.

A search query with only one regular expression would look like this:

  regular expression

  n
  regular expression 1
  regular expression 2
    .
    .
    .
  regular expression n
  logical relation

*Return to top of page*

2. Regular Expressions

A regular expression is a string of characters which tells the searcher which string (or strings) you are looking for. The following explains the format of regular expressions in detail. If you are familiar with Perl, you already know the syntax. If you are familiar with Unix, you should know that there are subtle differences between Perl's regular expressions and Unix' regular expressions.

Delimiters

A regular expression always starts and ends with a character, called the delimiter, which does not appear anywhere else in the expression. The delimiter is included because the searcher removes trailing spaces at the end of a line. Without the delimiters, there would be no way to distinguish between significant and insignificant spaces. Only the characters inside the delimiters are considered part of the regular expression.

Here are some examples of legal regular expressions:

  /legal/

("/" is the delimiter)

  .legal.

("." is the delimiter)

  blegal b

("b" is the delimiter; note that the space after the "l" is considered part of the regular expression)

Here are some illegal regular expressions:

  /illegal

(The first and last character are not the same)

  /ill/egal/

(The delimiter appears inside the regular expression)

*Return to top of page*

Simple Regular Expressions

In its simplest form, a regular expression is just a word or phrase to search for. For example,

  /gauss/

  /carbon/

Finds any file with the string "carbon" in its name, or which mentions carbon (or carbonization or hydrocarbons or carbon-based life forms) in the file contents.

  .hydro.

Finds any file with the string "hydro" in its name or contents. Files named "hydro", "hydrogen" or "hydrodynamics" are found, as well as files containing the words "hydroplane" or "hydroelectric".

  boxyb

Finds any file with the string "oxy" in the file name or contents. This could be used to find files on oxygen, boxy houses or oxymorons.

  >top ten>

Note that spaces may be part of the regular expression. The above expression could be used to find top ten lists. (Note that they would also find articles on how to stop tension.)

*Return to top of page*

Metacharacters

Some characters have a special meaning to the searcher. These characters are called metacharacters. Although they may seem confusing at first, they add a great deal of flexibility and convenience to the searcher.

The period (.) is a commonly used metacharacter. It matches exactly one character, regardless of what the character is. For example, the regular expression:

  /2,.-Dimethylbutane/

But what if you wanted to search for a string containing a period? For example, suppose we wished to search for references to pi. The following regular expression would not work:

  /3.14/     (THIS IS WRONG!)

To get around this, we introduce a second metacharacter, the backslash (\). The backslash can be used to indicate that the character immediately to its right is to be taken literally. Thus, to search for the string "3.14", we would use:

  /3\.14/    (This will work.)

(Unfortunately, the backslash is used for other things besides quoting metacharacters. Many "normal" characters take on special meanings when preceded by a backslash. The rule of thumb is, quoting a metacharacter turns it into a normal character, and quoting a normal character may turn it into a metacharacter.)

Let's look at some more common metacharacters. We consider first the question mark (?). The question mark indicates that the character immediately preceding it should be matched either zero times or one time. Thus

  /m?ethane/

  /comm?a/

Another metacharacter is the star (*). This indicates that the character immediately to its left may be repeated any number of times, including zero. Thus

  /ab*c/

The plus (+) metacharacter indicates that the character immediately preceding it may be repeated one or more times. It is just like the star metacharacter, except it doesn't match the null string. Thus

  /ab+c/

Metacharacters may be combined. A common combination includes the period and star metacharacters, with the star immediately following the period. This is used to match an arbitrary string of any length, including the null string. For example:

  /cyclo.*ane/

If you wanted to search for articles on cyclodecane and cyclohexane, but didn't want to match articles about how cyclones drive one insane, you could string together three periods, as follows:

  /cyclo...ane/

Here are some more examples. These involve the backslash. Note that the placement of the backslash is important.

  /a\.*z/

Matches any string starting with "a", followed by a series of periods (including the "series" of length zero), and terminated by "z". Thus, "az", "a.z", "a..z", "a...z" and so forth are all matched.

  /a.\*z/

(Note that the backslash and period are reversed in this regular expression.)

Matches any string starting with an "a", followed by one arbitrary character, and terminated with "*z". Thus, "ag*z", "a5*z" and "a@*z" are all matched. Only strings of length four, where the first character is "a", the third "*", and the fourth "z", are matched.

  /a\++z/

Matches any string starting with "a", followed by a series of plus signs, and terminated by "z". There must be at least one plus sign between the "a" and the "z". Thus, "az" is not matched, but "a+z", "a++z", "a+++z", etc. will be matched.

  /a\+\+z/

Matches only the string "a++z".

  /a+\+z/

Matches any string starting with a series of "a"'s, followed by a single plus sign and ending with a "z". There must be at least one "a" at the start of the string. Thus "a+z", "aa+z", "aaa+z" and so on will match, but "+z" will not.

  /a.?e/

Matches "ace", "ale", "axe" and any other three-character string beginning with "a" and ending with "e"; will also match "ae".

  /a\.?e/

Matches "ae" and "a.e". No other string is matched.

  /a.\?e/

Matches any four-character string starting with "a" and ending with "?e". Thus, "ad?e", "a1?e" and "a%?e" will all be matched.

  /a\.\?e/

Matches only "a.?e" and nothing else.

  /2,\d-Dimethylbutane/

  /1\.\d\d\d\d\d/

  /a\d+z/

The letter "d" in the string "\d" must be lower-case. This is because there is another metacharacter, the non-digit metacharacter, which uses the uppercase "D". The non-digit metacharacter looks like "\D" and matches any character except a digit. Thus,

  /a\Dz/

  /\D+/

Notice that in changing the "d" from lower-case to upper-case, we have reversed the meaning of the digit metacharacter. This holds true for most other metacharacters of the format backslash-letter.

There are three other metacharacters in the backslash-letter format. The first is the word metacharacter, which matches exactly one letter, one number, or the underscore character (_). It is written as "\w". It's opposite, "\W", matches any one character except a letter, a number or the underscore. Thus,

  /a\wz/

  /a\Wz/

The whitespace metacharacter matches exactly one character of whitespace. (Whitespace is defined as spaces, tabs, newlines, or any character which would not use ink if printed on a printer.) The whitespace metacharacter looks like this: "\s". It's opposite, which matches any character that is not whitespace, looks like this: "\S". Thus,

  /a\sz/

  /a\Sz/

  /\bcomput/

  /\Bcomput/

Note that the underscore (_) is considered a "word" character. Thus,

  /super\bcomputer/

There is one other metacharacter starting with a backslash, the octal metacharacter. The octal metacharacter looks like this: "\nnn", where "n" is a number from zero to seven. This is used for specifying control characters that have no typed equivalent. For example,

  /\007/

There are three other metacharacters that may be of use. The first is the braces metacharacter. This metacharacter follows a normal character and contains two numbers separated by a comma (,) and surrounded by braces ({}). It is like the star metacharacter, except the length of the string it matches must be within the minimum and maximum length specified by the two numbers in braces. Thus,

  /ab{3,5}c/

  /.{3,5}pentane/

The alternative metacharacter is represented by a vertical bar (|). It indicates an either/or behavior by separating two or more possible choices. For example:

  /isopentane|cyclopentane/

  /\s[cmt]an\s/

  /2,[23]-dimethylbutane/

  /a[a-d]z/

  /textfile0[3-5]/

If you wish to include a dash within brackets as one of the characters to match, instead of to denote a range, put the dash immediately before the right bracket. Thus:

  /a[1234-]z/

  /a[1-4-]z/

The bracket metacharacter can also be inverted by placing a caret (^) immediately after the left bracket. Thus,

  /textfile0[^02468]/

  /\W[^f-h]ood\W/

Note that within brackets, ordinary quoting rules do not apply and other metacharacters are not available. The only characters that can be quoted in brackets are "[", "]", and "\". Thus,

  /[\[\\\]]abc/

<Return to top of page>

Forbidden Characters

Because of the way the searcher works, the following metacharacters should not be used, even though they are valid Perl metacharacters. They are:

^ (allowed within brackets)

$ (allowed within brackets)

\n

\r

\t

\f

\b

( ) (allowed within brackets. Note that if you wish to search for parentheses within text outside of brackets, you should quote the parentheses.)

\1, \2 ... \9

\B

:

!

Here are some other things you should know about regular expressions.

1. To the searcher, the file's contents appears as a single long line of text where words are separated by spaces. New lines and tabs are converted to spaces, multiple spaces are compacted into a single space, and hyphenated words at the end of the line are joined. (Note that this applies only to the file's contents, not to the file's name.)

2. The search is case insensitive; thus

     /mopac/

   and

     /Mopac/

   and

     /MOPAC/

   all search for the same set of strings. Each will match "mopac", "MOPAC", "Mopac", "mopaC", "MoPaC", "mOpAc" and so forth. Thus you need not worry about capitalization. (Note, however, that metacharacter must still have the proper case. This is especially important for metacharacters whose case determines whether their meaning is reversed or not.)

3. All files have their name searched, but only textfiles have their contents searched.

4. When searching archived messages, each message is searched as though it were a separate file.

5. A very few computers and gateways do not handle the backslash character properly; they may cause the backslash to disappear as the search query is sent from your computer to ours. To help get around this, two substitutes for the backslash are provided. They are the tilde (~) and the backtick (`). They function identically to the backslash. Note that, like the backslash, they must be quoted if you wish for the searcher to take them literally.

6. You cannot search for the backslash (\), the tilde (~) or the backtick (`), nor can you use them as delimiters.

7. Outside of the brackets metacharacter, you must quote parentheses, brackets and braces to get the searcher to take them literally.

8. You can precede a regular expression with a search scope identifier. The format is:

   x:/regular expression/

   where x is either "F", "T" or "B". "F" instructs the searcher to only search filenames for matches to this regular expression. "T" instructs the searcher to only search a file's contents for matches to this regular expression. "B" indicates that the searcher should search both.

   For instance,

     F:/text/

   will match any file with the string "text" in its name. Likewise,

     T:/mopac/

   will match any file mentioning "mopac" in the contents. It will not match a file named "mopac". Finally,

     B:/carbon/

   will match any file mentioning "carbon" in its name or contents. Note that if no search scope identifier is included, "B:" is assumed.

3. Logical Relations

Once the regular expressions have been specified, you need to specify a logical relation between them. This relation determines how matches with the regular expression determine whether or not the file itself matches. For example, you might want to see all files referring to hydrogen and carbon, or those which mention methane or ethane, or those which refer to cyclopentane or neopentane but not both, or that do not refer to uranium. There are three logical operators:

AND

The AND operator can be represented by the word "AND", or by a single ampersand (&), or by a pair of ampersands (&&). It returns a match only if the expression to its left is true, and the expression to the right is true.

OR

The OR operator can be represented by the word "OR", or by a single vertical bar (|), or by a pair of veritcal bars (||). It returns a match only if the expression to its left is true, or the expression to the right is true.

NOT

The NOT operator can be represented by the word "NOT", or by a single exclamation point (!). It negates the value of the expression to its right.

Here are some simple examples of search queries with logical expressions. Note that the numbers in the logical relation show which regular expression is meant. "1" refers to the first regular expression, "2" to the second, and so on.

  2
  /\bcarbon\b/
  /\bhydrogen\b/
  1 OR 2

  2
  /\bpentane\b/
  /\bpropane\b/
  1 && 2

  1
  /\bmethane\b/
  !1

Here are some more complicated examples.

  3
  /\bcarbon\b/
  /\bhydrogen\b/
  /\boxygen\b/
  1 AND 2 OR NOT 3

  3
  /\bcarbon\b/
  /\bhydrogen\b/
  /\boxygen\b/
  (1 AND 2) OR (NOT 3)

  3
  /\bcarbon\b/
  /\bhydrogen\b/
  /\boxygen\b/
  1 AND (2 OR NOT 3)

*Return to top of page*

4. Examples

Here are some examples of typical search queries. Please study them to gain a better understanding of how the searcher works.

Example 1

Suppose you wish to find files which mention "AMBER". You might use a query that looks like this:

  1
  /amber/
  1

  /amber/

  /AMBER/

  /AmbeR/

  /Amber/

   / amber /

    /\bamber\b/

    /\bamber[^a-z]/

As this examples shows, it is important to analyze all possible combinations which will match your regular expression. You do not want to get too many unrelated files, but you want to be sure that you get all the files which relate to the topic of your search.

*Return to top of page*

Example 2

Suppose you want to search for the information on MM2, MM3, MM2P or MMP2. You can search the archives by giving the following query:

  4
  /MM2/
  /MM3/
  /MM2P/
  /MMP2/
  1 | 2 | 3 | 4

   1
   /MM2|MM3|MM2P|MMP2/
   1

   /MM2|MM3|MM2P|MMP2/

  1
  /\bMM[23]\b|\bMMP2\b|\bMM2P\b/
  1

  /\bMM[23]\b|\bMMP2\b|\bMM2P\b/

B:  /\bMM[23]\b|\bMMP2\b|\bMM2P\b/

*Return to top of page*

Example 3

  /basis\sset/

  /basis set/

Note that this example is not equivalent to the query:

  2
  /basis/
  /set/
  1 & 2

Actually, none of the above queries are good if you really want to find all the references about basis sets. People frequently say "basis" or "set"; sometimes they say "basis functions" or "contracted gaussians", and so on. You would need a more elaborate expression to be confident that you had found most of the references to this topic. It might look like:

  /basis|set|gaussians|contracted|6-31G\*|631G\*|gaussian exponent|/

  2
  /basis|set|gaussians| contracted |6-31G\*|631G\*|gaussian exponent|/
  /\bDZP\b|\bTZP\b|\bDZ\b|\bTZ\b|gaussian function|STO-?\dG|\+G\*/
  1 | 2

*Return to top of page*

Example 4

Suppose you want to search for files which talk about MNDO and d-orbitals. Here is an example of the query which could be used for this purpose:

  2
  /\bMNDO[^a-z]/
  /\bd[^a-z]|\bd[_\s-]*orbital|\bd[_\s-]function/
  1 & 2

  3
  /\bMNDO\b/
  /\bd[_\s-]/
  /\borbital|\bfunction/
  1 & 2 & 3

*Return to top of page*

Example 5

  3
  T: /\bMOPAC[^a-z]|/\bAMPAC[^a-z]|\bAM1\b|\bPM3\b|\bMNDO\b|\bMINDO/
  T: /\bCHARGE/
  T: /\bHYDROGEN[\s_-]?BOND[si\s.,;]|\bH[\s_-]?BOND[si\s.,;]/
  1 AND (2 OR 3)

Note that all the regular expressions given above request searching for the text of the file only, not its name.

The logical relation simply says: "Match all files which mention MOPAC or AMPAC or AM1 or PM3 or MNDO or MINDO and which also say something about charges or hydrogen bonds".

*Return to top of page*

1. Prepare your search query as described above and look at it for a few minutes. Writing a good query is not easy, but it can save you time in the long run.
2. Once you have composed your query, send it to chemistry-search@ccl.net
3. Wait at least four hours for an answer. The wait time depends how many searches are pending.

5. Using Search From Within Mailserv

When using the Mailserv program, you can perform searches of the current directory and all subdirectories by first CD-ing to the appropriate directory and then issuing the following command:

  SEARCH
  n
  /regular expression 1/
  /regular expression 2/
  .
  .
  .
  /regular expression n/
  logical relation

  SEARCH
  /regular expression/

*Return to top of page*

This helpfile was originally written by Jan K. Labanowski. It was revamped and converted to HTML by Alan Chalker. Plaintext copies of the original helpfile and the revised helpfile are both available.

       Return to the CCL homepage      |      Information on this page