diff --git a/modules/mol/base/doc/query.rst b/modules/mol/base/doc/query.rst index 6cf82e2c44df6b821db9bc9b6021c7903ff974b5..16e9a3a02ec090145aab816ecd0f016be70e7996 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 d855703c3e55f3e366bbda51b8c6dc79e309e114..4ab52ac98dfafc0cface61822bcfb143c224bbcc 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 -