Mercurial > p > roundup > code
comparison doc/user_guide.txt @ 8173:079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
Added doc that invalid filter expressions are silently ignored and a
fallback search is generated.
Added disabled test that uses incorrect filter expression examples
from this issue.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Mon, 02 Dec 2024 13:53:23 -0500 |
| parents | 6a58acc3f39f |
| children | cae1bbf2536b |
comparison
equal
deleted
inserted
replaced
| 8172:6a58acc3f39f | 8173:079958914ed7 |
|---|---|
| 447 | 447 |
| 448 Advanced Searching with Property Expressions | 448 Advanced Searching with Property Expressions |
| 449 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 449 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 450 | 450 |
| 451 You can create more advanced searches in your tracker by using Reverse | 451 You can create more advanced searches in your tracker by using Reverse |
| 452 Polish Notation (`RPN`_) to make property expressions. By default, when | 452 Polish Notation (`RPN`_) to make property expressions. By default, |
| 453 filtering by multiple items, the expression type is 'or'. For | 453 when filtering by multiple items, the expression type is 'or'. For |
| 454 instance, if you filter the property assignedto by adding the query | 454 instance, if you filter the property assignedto by adding the query |
| 455 string element "assignedto=2,3,40", it matches users "2 or 3 or | 455 string element ``assignedto=2,3,40``, it matches users numbered ``2 or |
| 456 40". In RPN, this would be written as "2, 3, or, 4, or". Roundup uses | 456 3 or 40``. In RPN, this would be written as ``2, 3, or, 4, |
| 457 negative numbers to represent operators. For example, using "-1" for a | 457 or``. Roundup uses negative numbers to represent operators. For |
| 458 single value (e.g. the assignedto Link property, but not the keyword | 458 example, using "-1" for a single value (e.g. the assignedto Link |
| 459 multivalued/MultiLink property) matches an issue where the property is | 459 property, but not the keyword multivalued/MultiLink property) matches |
| 460 'not set'. | 460 an issue where the property is 'not set'. |
| 461 | 461 |
| 462 The operators and their corresponding numbers are: | 462 The operators and their corresponding numbers are: |
| 463 | 463 |
| 464 * 'not' is represented by -2 | 464 * 'not' is represented by -2 |
| 465 * 'and' is represented by -3 | 465 * 'and' is represented by -3 |
| 466 * 'or' is represented by -4 | 466 * 'or' is represented by -4 |
| 467 | 467 |
| 468 So, "assignedto=2,3,40" is the same as | 468 So, ``assignedto=2,3,40`` is the same as |
| 469 "assignedto=2,3,-4,40,-4". While this example is the same as | 469 ``assignedto=2,3,-4,40,-4``. While this example is the same as |
| 470 "2,3,40", the expression "keyword=1,2,-3,-2" filters issues that don't | 470 ``2,3,40``, the expression ``keyword=1,2,-3,-2`` filters issues that |
| 471 have both keywords 1 and 2. | 471 don't have both keywords 1 and 2. |
| 472 | 472 |
| 473 Another example is: ``creator=3,-2,1,-2,-3``. This is the same as the | 473 Another example is: ``creator=3,-2,1,-2,-3``. This is the same as the |
| 474 expression: ``(not user3) and (not user1)``. Using the rules of logic, | 474 expression: ``(not user3) and (not user1)``. Using the rules of logic, |
| 475 this is the same as: ``not (user3 or user1)`` which is expressed in | 475 this is the same as: ``not (user3 or user1)`` which is expressed in |
| 476 RPN as ``creator=3,1,-4,-2``. Compare this to ``creator=3,1,-2`` which | 476 RPN as ``creator=3,1,-4,-2``. Compare this to ``creator=3,1,-2`` which |
| 477 returns issues created by user3 or any user other than user1. | 477 returns issues created by user3 or any user other than user1. |
| 478 | 478 |
| 479 Another example, useful when filtering issues, is: | 479 Another example, useful when filtering issues, is:: |
| 480 | 480 |
| 481 keyword=-1,-2,1,8,-3,-2,-3 | 481 keyword=-1,-2,1,8,-3,-2,-3 |
| 482 | 482 |
| 483 which returns issues that have one or more keywords set and the issue | 483 which returns issues that have one or more keywords set and the issue |
| 484 does not have keyword1 and keyword8 both set. In more standard infix | 484 does not have keyword1 and keyword8 both set. In more standard infix |
| 485 form: | 485 form:: |
| 486 | 486 |
| 487 not empty and not (keyword1 and keyword8) | 487 not empty and not (keyword1 and keyword8) |
| 488 | 488 |
| 489 Typing these expressions manually can be tiresome, so there's an | 489 Typing these expressions manually can be tiresome and tricky. On the |
| 490 expression editor on the search page. You can access it by clicking on | 490 search page, there's an expression editor. You can access it by |
| 491 the ``(expr)`` link, which makes creating these expressions a bit | 491 clicking on the ``(expr)`` link, which makes creating these |
| 492 easier. But at least you can use this info to understand the search | 492 expressions a bit easier. |
| 493 syntax in the URL. | 493 |
| 494 Note that errors in your expression (e.g. a missing operand) are | |
| 495 silently ignored and a fallback search is conducted. This is | |
| 496 `considered a bug <https://issues.roundup-tracker.org/issue2551374>`_ | |
| 497 and will hopefully be fixed in the future. But at least you can use | |
| 498 this info to understand the search syntax in the URL if you see | |
| 499 something strange. | |
| 494 | 500 |
| 495 Using the Classhelper | 501 Using the Classhelper |
| 496 --------------------- | 502 --------------------- |
| 497 | 503 |
| 498 The classhelper makes finding the id number or name for linked items | 504 The classhelper makes finding the id number or name for linked items |