Skip to content

Commit 8cae99d

Browse files
kopporkoppor
committed
Update search syntax description
1 parent 66925e4 commit 8cae99d

File tree

1 file changed

+72
-32
lines changed
  • en/finding-sorting-and-cleaning-entries

1 file changed

+72
-32
lines changed

‎en/finding-sorting-and-cleaning-entries/search.md‎

Lines changed: 72 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,6 @@ To make the cursor jump to the search field, you can:
1313

1414
To find the search history, you can right click in the search field. Only ten recent searches will be displayed in the sub-menu. You can find clear history button under your search history.
1515

16-
## Search settings
17-
18-
At the right of the search text field, 2 buttons allow for selecting some settings:
19-
20-
* Regular expressions
21-
* Whether or not the search query uses [regular expressions](search.md#regular-expressions).
22-
* Case sensitivity
23-
* Whether or not the search query is case sensitive.
24-
2516
## Simple search <a href="#simple-search" id="simple-search"></a>
2617

2718
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".
@@ -30,25 +21,30 @@ All entries that do not match are hidden, leaving for display the matching entri
3021

3122
To stop displaying the search results, just clear the search field, press Esc or click on the "Clear" (`X`) button.
3223

33-
## Search using regular expressions <a href="#regular-expressions" id="regular-expressions"></a>
24+
## Search within specific fields
3425

35-
{% hint style="warning" %}
36-
Make sure that the button "regular expressions" is activated
37-
{% endhint %}
26+
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 `==`.
3827

39-
### General syntax
28+
If a field is not given, all fields are searched and one can mix the selection:
29+
`video and year == 1932` will search for entries with any field containing `video` and the field `year` being exactly `1932`.
4030

41-
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).
31+
### Pseudo fields
4232

43-
#### Search within specific Fields
33+
JabRef defines the following pseudo fields:
4434

45-
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 `==`.
35+
| | | |
36+
| ---------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
37+
| **Pseudo field** | **Purpose** | **Example** |
38+
| `anyfield` / `any` | Search in any field | `anyfield contains fruit`: search for entries having one of its fields containing the word **fruit**. This is identical to just writing `apple`. It may be more useful as `anyfield matches apple`, where one field must be exactly `apple` for a match. |
39+
| `anykeyword` | Search among the keywords | `anykeyword matches apple`: search for entries which have the word **apple** among its keywords. However, as this also matches `pineapple`, it may be more useful in searches of the type `anykeyword matches apple`, which will not match `apples` or `pineapple` |
40+
| `key` | Search for citation keys | `citationkey == miller2005`: search for an entry whose citation key is **miller2005** |
41+
| `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**) |
4642

47-
#### Search for terms containing spaces
43+
## Search for terms containing spaces
4844

49-
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"`
45+
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"`
5046

51-
#### Search using parentheses, `and`, `or` and `not`
47+
## Search using parentheses, `and`, `or` and `not`
5248

5349
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:
5450

@@ -61,23 +57,67 @@ To search for entries with the title _or_ the keyword "image processing", type:
6157
| (X) | X, as a capturing group |
6258
| != | tests if the search term is _not_ contained in the field (equivalent to `not ... contains ...`) |
6359

64-
#### Regular Expression search and Field Types
60+
## Search settings
6561

66-
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`.
62+
At the right of the search text field, two buttons allow for selecting some settings:
6763

68-
### Pseudo fields
64+
* Regular expressions
65+
* Whether the search query uses [regular expressions](search.md#regular-expressions).
66+
* Case sensitivity
67+
* Whether the search query is case-sensitive.
6968

70-
JabRef defines the following pseudo fields:
69+
This applies to all "unfielded" search terms. Meaning: All search terms not specifying a field (e.g., `title`).
7170

72-
| | | |
73-
| ---------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
74-
| **Pseudo field** | **Purpose** | **Example** |
75-
| `anyfield` | Search in any field | `anyfield contains fruit`: search for entries having one of its fields containing the word **fruit**. This is identical to just writing `apple`. It may be more useful as `anyfield matches apple`, where one field must be exactly `apple` for a match. |
76-
| `anykeyword` | Search among the keywords | `anykeyword matches apple`: search for entries which have the word **apple** among its keywords. However, as this also matches `pineapple`, it may be more useful in searches of the type `anykeyword matches apple`, which will not match `apples` or `pineapple` |
77-
| `key` | Search for citation keys | `citationkey == miller2005`: search for an entry whose citation key is **miller2005** |
78-
| `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**) |
71+
## Modifiers for fields
72+
73+
JabRef offers operators for the fielded search.
74+
The general idea is to have `=` for contains search and `==` for exact matches.
75+
Then, the `!` can be used to force case-sensitive matching (when used at the end) and as negation, when used in front.
76+
Finally, the `~` sign is used to enable regular-expression-based search.
77+
78+
This leads to following operator combinations:
79+
80+
| Operator | Explanation |
81+
|----------|----------------------------------------|
82+
| `=` | Case insensitive contains |
83+
| `=!` | Case sensitive contains |
84+
| `==` | Exact match, case insensitive |
85+
| `==!` | Exact match, case sensitive |
86+
| `=~` | Regex check, case insensitive |
87+
| `=~!` | Regex check, case sensitive |
88+
| `!=` | Negated case insensitive contains |
89+
| `!=!` | Negated case sensitive contains |
90+
| `!==` | Negated exact match, case insensitive |
91+
| `!==!` | Negated exact match, case sensitive |
92+
| `!=~` | Negated regex check, case insensitive |
93+
| `!=~!` | Negated regex check, case sensitive |
94+
95+
Remember, the regex option has no effect on "field = value" expressions.
96+
To use regex with field names, the expression must have the form "field =~ value", which will apply the regular expression regardless of the ".*" regex option.
97+
To put it another way, using `field = myterm` explicitly disables regex while `field =~ myterm` explicitly enables it, _on this term only without affecting the rest of the search._ Note that the "abc" case-sensitive option follows the same principle.
7998

80-
### Advanced use of regular expressions <a href="#regular-expressions-advanced" id="regular-expressions-advanced"></a>
99+
The idea makes sense, because it allows regex and non-regex terms to coexist in the same search.
100+
101+
However, in practice this is totally unintuitive and not worth the trade-off. My suggestion for the maintainers is to keep "field =~ value" explicit (always apply regex syntax for this term) and make "field = value" apply standard or regex syntax, depending on the regex button/checkmark. In other words, `=` and `=~` should be treated as equivalent when the regex option is enabled.
102+
103+
Personally, I keep regex enabled all the time, so adding escape characters as needed has become second nature.
104+
105+
This is how the search currently works in the development version.
106+
107+
| Terms | Regex | Term 1 | Term 2 |
108+
|--------|--------|---------|---------|
109+
| `title =~ pa*ediatric AND 1.0` | Off | Matches "paediatric", "pediatric" | Matches "1.0" |
110+
| `title =~ pa*ediatric AND 1.0` | On |Matches "paediatric", "pediatric" | Matches "1.0", "1+0" "1/0", "1q0", ... |
111+
| `title = pa*ediatric AND 1.0` | Off | No match. Regex is disabled | "1.0" |
112+
| `title = pa*ediatric AND 1.0` | On | No match. Regex is disabled for this term |Matches "1.0", "1+0" "1/0", "1q0", ... |
113+
114+
## Search using regular expressions <a href="#regular-expressions" id="regular-expressions"></a>
115+
116+
{% hint style="warning" %}
117+
This has changed with JabRef v6
118+
{% endhint %}
119+
120+
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).
81121

82122
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/).
83123

0 commit comments

Comments
 (0)