From f18b8faad930892a8018afb95eb049ac4776c9c3 Mon Sep 17 00:00:00 2001 From: ThiloteE <73715071+ThiloteE@users.noreply.github.com> Date: Mon, 5 Sep 2022 15:32:01 +0200 Subject: [PATCH 1/3] Rewrite of Regular Expression Search 1. Rephrases "General Syntax" 2. Adds `owner != ^[a-zA-Z]{3}$` returns empy and non-three-letter owners 3. Rephrases Searching for strings with double quotation marks (") 4. Adds Greedy quantifiers 5. Adds Reluctant quantifiers 6. Adds Possessive quantifiers --- .../search.md | 96 +++++++++++++++---- 1 file changed, 77 insertions(+), 19 deletions(-) diff --git a/en/finding-sorting-and-cleaning-entries/search.md b/en/finding-sorting-and-cleaning-entries/search.md index 7b5396129..d53cfbc07 100644 --- a/en/finding-sorting-and-cleaning-entries/search.md +++ b/en/finding-sorting-and-cleaning-entries/search.md @@ -18,7 +18,7 @@ At the right of the search text field, 2 buttons allow for selecting some settin * Case sensitivity * Whether or not the search query is case sensitive. -## Simple search +## Simple search In a normal search, the program searches your library for all occurrences of the words in your search string, once you entered it. Only entries containing all words will be considered matches. To search for sequences of words, enclose the sequences in double-quotes. For instance, the query **progress "marine aquaculture"** will match entries containing both the word "progress" and the phrase "marine aquaculture". @@ -26,27 +26,43 @@ All entries that do not match are hidden, leaving for display the matching entri To stop displaying the search results, just clear the search field, press Esc or click on the "Clear" (`X`) button. -## Search using regular expressions +## Search using regular expressions {% hint style="warning" %} Make sure that the button "regular expressions" is activated {% endhint %} + + ### General syntax -In order to search specific fields only and/or include logical operators in the search expression, a special syntax is available in which these can be specified. E.g. to search for entries whose an author contains **miller**, enter: +In order to only search for content within specific fields and/or to include logical operators in the search expression, a special syntax is available in which these can be specified. Both the field specification and the search term support [regular expressions](search.md#regular-expressions). + +#### Search within specific Fields: + + To search for entries whose author contains **miller**, enter: `author = miller`. The `=` sign is actually a shorthand for `contains`. Searching for an exact match is possible using `matches` or `==`. -`author = miller` +#### Search for terms containing spaces: -Both the field specification and the search term support [regular expressions](search.md#regular-expressions). If the search term contains spaces, enclose it in quotes. Do _not_ use spaces in the field specification! E.g. to search for entries about image processing, type: + If the search term contains spaces, enclose it in quotes. Do _not_ use spaces in the field specification! E.g to search for entries with the title "image processing", type: `title = "image processing"` -`title|keywords = "image processing"` +#### Search using parentheses, `and`, `or` and `not`: -You can use `and`, `or`, `not`, and parentheses as intuitively expected: +To search for entries with the title *or* the keyword "image processing", type: `title|keywords = "image processing"`. To search for entries *without* the title or the keyword "image processing", type: `title|keywords != "image processing"` It is also possible to chain search expressions. In general, you can use `and`, `or`, `not`, and parentheses as intuitively expected: + + `(author = miller or title|keywords = "image processing") and not author = brown and != author = blue` -`(author = miller or title|keywords = "image processing") and not author = brown` + Logical Operator / Symbol | Explanation + |:---|:---| + XY | X followed by Y + X\|Y | Either X or Y + (X) | X, as a capturing group + | != | tests if the search term is _not_ contained in the field (equivalent to `not ... contains ...`)| + -The `=` sign is actually a shorthand for `contains`. Searching for an exact match is possible using `matches` or `==`. Using `!=` tests if the search term is _not_ contained in the field (equivalent to `not ... contains ...`). The selection of field types to search (required, optional, all) is always overruled by the field specification in the search expression. If a field is not given, all fields are searched. For example, `video and year == 1932` will search for entries with any field containing `video` and the field `year` being exactly `1932`. +#### Regular Expression search and Field Types: + +The selection of field types to search (required, optional, all) is always overruled by the field specification in the search expression. If a field is not given, all fields are searched. For example, `video and year == 1932` will search for entries with any field containing `video` and the field `year` being exactly `1932`. ### Pseudo fields @@ -60,9 +76,10 @@ JabRef defines the following pseudo fields: | `key` | Search for citation keys | `citationkey == miller2005`: search for an entry whose citation key is **miller2005** | | `entrytype` | Search for entries of a certain type | `entrytype = thesis`: search entries whose type (as displayed in the `entrytype` column) contains the word **thesis** (which would be **phdthesis** and **mastersthesis**) | -### Advanced use of regular expressions +### Advanced use of regular expressions + -Regular expressions (regex for short) define a language for specifying the text to be matched, for example when searching. JabRef uses regular expressions as defined in Java. For extensive information, please, look at the [Java documentation](https://docs.oracle.com/en/java/javase/16/docs/api/java.base/java/util/regex/Pattern.html) and at the [Java tutorial](https://docs.oracle.com/javase/tutorial/essential/regex/). +Regular expressions (RegEx for short) define a language for representing patterns matching text, for example when searching. There are different types of RegEx languages. JabRef uses regular expressions as defined in Java. For extensive advanced information about Java's RegEx patterns, please have a look at the [Java documentation](https://docs.oracle.com/en/java/javase/16/docs/api/java.base/java/util/regex/Pattern.html) and at the [Java tutorial](https://docs.oracle.com/javase/tutorial/essential/regex/). #### Regular expressions and casing @@ -72,15 +89,22 @@ If casing is important to your search, activate the case-sensitive button. #### Searching for entries with an empty or missing field -* `.` means any character -* `+` means one or more times +* `.` means: any character +* `+` means: one or more times `author != .+` returns entries with empty or no author field. +* `^` means: the beginning of a line +* `[a-zA-Z]` means: a through z or A through Z, inclusive (range) +* `$` means: the end of a line +* `X{n}` means: X, exactly n times + +`owner != ^[a-zA-Z]{3}$` returns empy and non-three-letter owners + #### Searching for a given word -* `\b` means word boundary -* `\B` means not a word boundary +* `\b` means: word boundary +* `\B` means: not a word boundary `keywords = \buv\b` matches _uv_ but not _lluvia_ (it does match _uv-b_ however) @@ -92,8 +116,8 @@ If casing is important to your search, activate the case-sensitive button. #### Searching with optional spelling -* `?` means none or one copy of the preceding character. -* `{n,m}` means at least _n_, but not more than _m_ copies of the preceding character. +* `?` means: none or one copy of the preceding character. +* `{n,m}` means: at least _n_, but not more than _m_ copies of the preceding character. * `[ ]` defines a character class `title =neighbou?r` matches _neighbour_ and _neighbor_, and also _neighbours_ and _neighbors_, and _neighbouring_ and _neighboring_, etc. @@ -122,6 +146,40 @@ It means that to search for a string including a backslash, two consecutive back The character `"` has a special meaning: it is used to group words into phrases for exact matches. So, if you search for a string that includes a double quotation, the double quotation character has to be replaced with the hexadecimal character 22 in ASCII table `\x22`. -Hence, to search for `{\"o}quist` as an author, you must input `author = \{\\\x22o\}quist`, with regular expressions enabled (Note: the `{`, `_` and the `}` are escaped with a backslash; see above). +Neither a simple backslash `\"`, nor a double backslash `\\"` will work as an escape for `"`. Neither `author = {\"o}quist` with regular expression disabled, nor `author = \{\\\"O\}quist` with regular expression enabled, will find anything, even if the name `{\"o}quist` exists in the library. + +Hence, to search for `{\"o}quist` as an author, you must input `author = \{\\\x22o\}quist`, with regular expressions enabled (Note: the `\`, `{`, `_` and the `}` are escaped with a backslash; see above). + + +#### Greedy quantifiers + +Quantifier | Explanation +|:---|:---| +X? | X, once or not at all +X* | X, zero or more times +X+ | X, one or more times +X{n} | X, exactly n times +X{n,} | X, at least n times +X{n,m}| X, at least n but not more than m times + +#### Reluctant quantifiers + +Quantifier | Explanation +|:---|:---| +X?? | X, once or not at all +X*? | X, zero or more times +X+? | X, one or more times +X{n}? | X, exactly n times +X{n,}? | X, at least n times +X{n,m}? | X, at least n but not more than m times + +#### Possessive quantifiers -Indeed, `\"` does not work as an escape for `"`. Hence, neither `author = {\"o}quist` with regular expression disabled, nor `author = \{\\\"O\}quist` with regular expression enabled, will find anything even if the name `{\"o}quist` exists in the library. +Quantifier | Explanation +|:---|:---| +X?+ | X, once or not at all +X*+ | X, zero or more times +X++ | X, one or more times +X{n}+ | X, exactly n times +X{n,}+ | X, at least n times +X{n,m}+ | X, at least n but not more than m times From ad445aeea2f1737cb77611e93a1acf7996f118e9 Mon Sep 17 00:00:00 2001 From: ThiloteE <73715071+ThiloteE@users.noreply.github.com> Date: Mon, 5 Sep 2022 21:00:47 +0200 Subject: [PATCH 2/3] Fix spelling of empty --- en/finding-sorting-and-cleaning-entries/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/finding-sorting-and-cleaning-entries/search.md b/en/finding-sorting-and-cleaning-entries/search.md index d53cfbc07..c5c0eae80 100644 --- a/en/finding-sorting-and-cleaning-entries/search.md +++ b/en/finding-sorting-and-cleaning-entries/search.md @@ -99,7 +99,7 @@ If casing is important to your search, activate the case-sensitive button. * `$` means: the end of a line * `X{n}` means: X, exactly n times -`owner != ^[a-zA-Z]{3}$` returns empy and non-three-letter owners +`owner != ^[a-zA-Z]{3}$` returns empty and non-three-letter owners #### Searching for a given word From b9ee2822e1136eb3c573a87b7f91a558560e7e09 Mon Sep 17 00:00:00 2001 From: Christoph Date: Mon, 5 Sep 2022 21:43:18 +0200 Subject: [PATCH 3/3] lint --- .../search.md | 55 +++++++++---------- 1 file changed, 25 insertions(+), 30 deletions(-) diff --git a/en/finding-sorting-and-cleaning-entries/search.md b/en/finding-sorting-and-cleaning-entries/search.md index c5c0eae80..6d4a57d19 100644 --- a/en/finding-sorting-and-cleaning-entries/search.md +++ b/en/finding-sorting-and-cleaning-entries/search.md @@ -32,35 +32,32 @@ To stop displaying the search results, just clear the search field, press Esc or Make sure that the button "regular expressions" is activated {% endhint %} - - ### General syntax In order to only search for content within specific fields and/or to include logical operators in the search expression, a special syntax is available in which these can be specified. Both the field specification and the search term support [regular expressions](search.md#regular-expressions). -#### Search within specific Fields: +#### Search within specific Fields To search for entries whose author contains **miller**, enter: `author = miller`. The `=` sign is actually a shorthand for `contains`. Searching for an exact match is possible using `matches` or `==`. -#### Search for terms containing spaces: +#### Search for terms containing spaces If the search term contains spaces, enclose it in quotes. Do _not_ use spaces in the field specification! E.g to search for entries with the title "image processing", type: `title = "image processing"` -#### Search using parentheses, `and`, `or` and `not`: +#### Search using parentheses, `and`, `or` and `not` -To search for entries with the title *or* the keyword "image processing", type: `title|keywords = "image processing"`. To search for entries *without* the title or the keyword "image processing", type: `title|keywords != "image processing"` It is also possible to chain search expressions. In general, you can use `and`, `or`, `not`, and parentheses as intuitively expected: +To search for entries with the title _or_ the keyword "image processing", type: `title|keywords = "image processing"`. To search for entries _without_ the title or the keyword "image processing", type: `title|keywords != "image processing"` It is also possible to chain search expressions. In general, you can use `and`, `or`, `not`, and parentheses as intuitively expected: `(author = miller or title|keywords = "image processing") and not author = brown and != author = blue` Logical Operator / Symbol | Explanation |:---|:---| - XY | X followed by Y - X\|Y | Either X or Y - (X) | X, as a capturing group + XY | X followed by Y + X\|Y | Either X or Y + (X) | X, as a capturing group | != | tests if the search term is _not_ contained in the field (equivalent to `not ... contains ...`)| - -#### Regular Expression search and Field Types: +#### Regular Expression search and Field Types The selection of field types to search (required, optional, all) is always overruled by the field specification in the search expression. If a field is not given, all fields are searched. For example, `video and year == 1932` will search for entries with any field containing `video` and the field `year` being exactly `1932`. @@ -78,7 +75,6 @@ JabRef defines the following pseudo fields: ### Advanced use of regular expressions - Regular expressions (RegEx for short) define a language for representing patterns matching text, for example when searching. There are different types of RegEx languages. JabRef uses regular expressions as defined in Java. For extensive advanced information about Java's RegEx patterns, please have a look at the [Java documentation](https://docs.oracle.com/en/java/javase/16/docs/api/java.base/java/util/regex/Pattern.html) and at the [Java tutorial](https://docs.oracle.com/javase/tutorial/essential/regex/). #### Regular expressions and casing @@ -99,7 +95,7 @@ If casing is important to your search, activate the case-sensitive button. * `$` means: the end of a line * `X{n}` means: X, exactly n times -`owner != ^[a-zA-Z]{3}$` returns empty and non-three-letter owners +`owner != ^[a-zA-Z]{3}$` returns empty and non-three-letter owners #### Searching for a given word @@ -150,36 +146,35 @@ Neither a simple backslash `\"`, nor a double backslash `\\"` will work as an es Hence, to search for `{\"o}quist` as an author, you must input `author = \{\\\x22o\}quist`, with regular expressions enabled (Note: the `\`, `{`, `_` and the `}` are escaped with a backslash; see above). - #### Greedy quantifiers Quantifier | Explanation |:---|:---| X? | X, once or not at all -X* | X, zero or more times +X* | X, zero or more times X+ | X, one or more times -X{n} | X, exactly n times -X{n,} | X, at least n times -X{n,m}| X, at least n but not more than m times +X{n} | X, exactly n times +X{n,} | X, at least n times +X{n,m}| X, at least n but not more than m times #### Reluctant quantifiers Quantifier | Explanation |:---|:---| -X?? | X, once or not at all -X*? | X, zero or more times -X+? | X, one or more times -X{n}? | X, exactly n times -X{n,}? | X, at least n times -X{n,m}? | X, at least n but not more than m times +X?? | X, once or not at all +X*? | X, zero or more times +X+? | X, one or more times +X{n}? | X, exactly n times +X{n,}? | X, at least n times +X{n,m}? | X, at least n but not more than m times #### Possessive quantifiers Quantifier | Explanation |:---|:---| -X?+ | X, once or not at all -X*+ | X, zero or more times -X++ | X, one or more times -X{n}+ | X, exactly n times -X{n,}+ | X, at least n times -X{n,m}+ | X, at least n but not more than m times +X?+ | X, once or not at all +X*+ | X, zero or more times +X++ | X, one or more times +X{n}+ | X, exactly n times +X{n,}+ | X, at least n times +X{n,m}+ | X, at least n but not more than m times