EndUser_SearchTool

End users notes: the search tool

pgn4web provides a search tool, either in the form of a search form on the web page (if the page includes this option) or of a popup search box invoked with the 's' shortcut key and/or the associated shortcut squares.

If the search is successful, the chessboard automatically loads the next matching game, otherwise the current game remains shown. The search is implemented as a javascript regular expression search against the text of the PGN data of each game.

For basic searches, this is equivalent to matching the search pattern string anywhere in the PGN data of each game, including header, moves and comments. For more complex searches, this is a regular expression search against the PGN data of each game, with following remarks:

• search is case insensitive
• the PGN data of each game is stripped to a single line before searching, so there's no need to worry about regular expressions not matching newlines

Key regular expressions summary

For more information look at the Wikipedia page on regular expressions.

For practical purposes, the following key regular expressions are very useful:

match any character:

.

match a sequence of zero or more of any characters:

.*

match a sequence of one or more of any characters:

.+

match a space character:

\s

match a sequence of zero or more space characters:

\s*

match either the string White or the string Black:

(White|Black)

match anything but the string "1/2-1/2":

(?!"1/2-1/2")

match the presence of both the "Event" and "Site" strings regardless of the order (this might be rather slow):

(?=.*Event)(?=.*Site)

match one letter (remember search is case insensitive):

[a-z]

match one char that is anything else than a letter (remember search is case insensitive):

[^a-z]

Please find below some examples, use the TWIC #944 page for practicing.

Searching for a generic text

The search pattern

Kramnik

will look for the string anywhere in the PGN data of each game, inlcuding header, moves and comments. Of course, usually Kramnik will appear as either the White or Black player header tag, but the search could match also the name Kramnik in the opening name or somewhere in the game comment.

Keep in mind the search is case insensitive and also fragments of words are matched.

In order to be sure to match only Kramnik and excluding Kramnikovsky, the search pattern could be

Kramnik[^a-z]+

This means Kramnik followed by one or more of a character that is not a lowercase letter ('[^a-z]+' as understood in regular expressions).

Searching for a specific header tag

To search for Kramnik as the White player, the search pattern could be

White\s*"Kramnik

This means searching for the text White followed by zero or more spaces ('\s*' as understood in regular expressions) then followed by quotes and then by Kramnik.

To search for Kramnik as either the White or the Black player, the search pattern could be

(White|Black)\s*"Kramnik

This means to look for either White or Black as the first word ('(White|Black)' as understood in regular expressions).

To search for all games not ending in a draw, the search pattern could be

Result(?!\s*"1/2-1/2")

This means to look for the text Result followed by zero or more spaces preceding anything but "1/2-1/2" ((?!\s*"1/2-1/2") as understood in regular expressions).

Searching for a combination of header tags

The PGN standard specifies that the seven mandatory header tags should appear in the following order: Event, Site, Date,

Round, White, Black, Result, then followed by any additional (optional and/or custom) header tags.

Taking advantage of the order of the header tags, to search for Kramnik-McShane games the search pattern could be

White\s*"Kramnik.*Black\s*"McShane

This means to look for Kramnik as White, followed by zero or more of any characters ('.*' as understood in regular expressions) then followed by McShane as Black.

More robust regular expressions searching for Kramnik-McShane games, regardless of the order of the PGN header tags, could be either of

(?=.*White\s*"Kramnik)(?=.*Black\s*"McShane)

(White\s*"Kramnik.*Black\s*"McShane)|(Black\s*"McShane.*White\s*"Kramnik)

The former is more compact, however more resource intensive and could require a relatively long execution time on certain browsers.

To search for games between those players regardless of colors, the search pattern could be

White\s*"(Kramnik|McShane).*Black\s*"(Kramnik|McShane)

Other header combinations are allowed. For instance, to search for all games at the 4th London Chess Classic ending with a win, the search pattern could be

Event\s*"4th London Chess Classic.*Result\s"(1-0|0-1)

The more robust options, searching for all games at the 4th London Chess Classic ending with a win regardless of the order of the PGN header tags, could be either of

(?=.*Event\s*"4th London Chess Classic)(?=.*Result\s"(1-0|0-1))

(Event\s*"4th London Chess Classic.*Result\s"(1-0|0-1))|(Result\s"(1-0|0-1).*Event\s*"4th London Chess Classic)

Warning: any well formed PGN file, like the one at the TWIC #944 page, should respect the header tag order, however pgn4web would still parse and display PGN data with header tags in the wrong order and this might affect your search results. If your search does not return the results you expect, please check the PGN data (using the shortcut square D8) and possibly use the more robust variant.

Some PGN files include ECO codes using the ECO header tag, like the one at the TWIC #944 page. If the ECO header tag is available, to search for all Alekhine defense games, the search pattern could be

ECO\s*"B0[2-5]

while to restrict that to wins for Black, the search pattern could be

Result\s*"0-1.*ECO\s*"B0[2-5]

Searching for specific moves

The search pattern will be matched against the moves portion of the PGN data as well.

Please note that the PGN standard specifies that the dot after the move number should be followed by a space, however many PGN files available have the actual move immediately after the dot following the move number.

To search for games starting with e4, the search pattern could be

\b1\.\s*e4

Please note this could also match a comment or a variation. Also note the element [^0-9] making sure we dont match the move e4 later in the game, such as on the 21st move.

To search for games in the open Tarrasch variation of the French, with Black recapturing in d5 with the Queen, the search pattern could be

\b1\.\s*e4\s*e6.*4\.\s*exd5\s*Qxd5

Please be aware that this search would fails if the game transposes to a French from a different start than e4 e6 and would also fail if there's any comment between e4 and e6 or between a3 and Ba5. Also unwanted games might be returned with unusual opening sequences including Nc3 and early exd5. Even if not completely accurate, this search patterns provides a decent way to look for those French Tarrasch games.

To search for open games 1. e4 e5 without 2. Nf3, the search pattern could be

\b1\.\s*e4\s*e5(?!\s*2\.\s*Nf3)