From ec09274bb3dfca8a90921001458b22c337c6f504 Mon Sep 17 00:00:00 2001
From: Gerardo Tauriello <gerardo.tauriello@unibas.ch>
Date: Tue, 9 Jul 2019 18:01:30 +0200
Subject: [PATCH] SCHWED-4246: Documented mol.QueryQuoteName function.
---
modules/mol/base/doc/query.rst | 29 +++++++++++++++++++++++++----
modules/mol/base/src/query.hh | 7 +++----
2 files changed, 28 insertions(+), 8 deletions(-)
diff --git a/modules/mol/base/doc/query.rst b/modules/mol/base/doc/query.rst
index 6cf82e2c4..16e9a3a02 100644
--- a/modules/mol/base/doc/query.rst
+++ b/modules/mol/base/doc/query.rst
@@ -48,13 +48,15 @@ Both the selection statements that have been used so far take strings as their a
n_term = model.Select('rnum<=20')
If you want to supply arguments with special characters they need to be put in
-quotation marks. For instance, this is needed to select the chain named "_" or
-for any chain name conatining ".", " " or ",". Hence, chain "_" can be selected
-with:
+quotation marks (' or "). For instance, this is needed for any chain name
+containing spaces as in:
.. code-block:: python
- model.Select('cname="_"')
+ model.Select('cname=" "')
+
+Almost any name can be quoted with :meth:`QueryQuoteName`.
+
Combining predicates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -305,3 +307,22 @@ In the following, the interface of the query class is described. In general, you
* ``NO_BONDS`` - do not include any bonds (by default bonds are included)
* ``MATCH_RESIDUES`` - include all atoms of a residue if any of its atoms is
selected (by default only selected atoms are included)
+
+.. method:: QueryQuoteName(name)
+
+ Adds appropriate quotation marks to use *name* in a :class:`Query`. For
+ instance the following code snippet would generate a query string selecting
+ all chains from a list of chain names:
+
+ .. code-block:: python
+
+ query = "cname=" + ','.join(mol.QueryQuoteName(name) for name in names)
+
+ Note that there is some limited support of wild card symbols (* and ?) which
+ may have undesired effects in a query such as the code above.
+
+ :param name: Name to put in quotation marks
+ :type name: :class:`str`
+ :rtype: :class:`str`
+ :raises: :exc:`~exceptions.Exception` if *name* cannot be used in queries.
+ This happens if *name* includes both ' and " or if it ends with \\.
diff --git a/modules/mol/base/src/query.hh b/modules/mol/base/src/query.hh
index d855703c3..4ab52ac98 100644
--- a/modules/mol/base/src/query.hh
+++ b/modules/mol/base/src/query.hh
@@ -124,14 +124,14 @@ inline String DLLEXPORT_OST_MOL QueryQuoteName(const String& name) {
char quote = '\'';
if (name.find('\'') != String::npos) {
if (name.find('"') != String::npos) {
- throw Error("Cannot quote chain name " + name + " because it contains '"
- " and \" in its name.");
+ throw Error("Cannot quote chain name " + name + " because it contains "
+ "both ' and \" in its name.");
}
quote = '"';
}
// check problematic \ at end (escapes quotation mark and breaks logic)
if (name[name.length() - 1] == '\\') {
- throw Error("Cannot quote chain name " + name + "because it ends in \\.");
+ throw Error("Cannot quote chain name " + name + " because it ends in \\.");
}
return quote + name + quote;
}
@@ -139,4 +139,3 @@ inline String DLLEXPORT_OST_MOL QueryQuoteName(const String& name) {
}} // ns
#endif
-
--
GitLab