The filter Command

The filter command is used to manage filter objects. Filter objects are a convenient method to quickly access subsets of objects, for example subsets of atoms or bonds with specific properties.

A filter basically consists of the name of a property which is used as foundation for the comparison. It also defines a comparison operator and one or more comparison values. Objects whose property values of the filter property pass the test are passed on to further processing.

The filter command has the following subcommands:

filter create

filter create filtername ?attribute value?...
filter create filtername dict

Create a new filter. In case the filter already exists, this is the same as filter set . A default filter without any other configured attributes does nothing and lets everything pass. The supported attributes and values are explained in the paragraph on the filter set command.

The return value is the filter name or reference.

filter defined

filter defined filtername

A boolean check whether the filter is available. In case it is not yet in memory, an attempt is made to auto-load or auto-instantiate it. For a command variant without auto-loading, see filter exists .

filter exists

filter exists filtername

A boolean test whether the filter is current defined and loaded. No attempt is made to auto-load it. For a command with auto-loading, see filter defined .

filter delete

filter delete ?filtername?..

Delete zero or more filters. Note that it is possible to delete built-in filters. An attempt to delete a non-exiting filter raises an error. The return value of this command is the number of deleted filters.

filter get

filter get filtername attribute

Query an attribute from a filter definition. The supported attributes are detailed in the paragraph on the filter set subcommand.

If the specified filter is not yet loaded, an attempt to auto-load a definition file is made.

filter list

filter list ?pattern?

Get a list of all currently loaded filters, including the built-in filter definitions. If desired, a string match pattern can be supplied to filter the reported set.

filter load

filter load filtername
filter load all

Attempt to explicitly load a filter via the auto-loader mechanism. If the filter is already in memory, the command has no effect. In case auto-loading fails, an error results. The return value is the filter table slot index the filter is loaded into for Tcl , or a filter reference for Python .

The second form of the command scans the currently set filter search path and loads all accessible filters which are not yet in memory. Filters which are already active in the running application are not unloaded, and only a single instance of each I/O filter, even if present under various alias names in the filter directories, is loaded. This form of the command does not return a value.

filter query

filter query keyword ?objectclass? ?mode? ?casesensitivity?

Search the internal filter database by matching the keyword against a standard set of filter attributes, such as name, description, keywords, category, comment and UUID s. Only the current memory database is checked, no auto-loading or repository checks are performed.

By default all filter definitions are matched. The object class argument (such as atom ) can be used to limit the search to filters using a property of a specific property class. Providing an empty argument is the same as omitting the argument.

The optional mode argument changes the string comparison mode. The default is equal , other possibilities are substring , left (match beginning of string), right (match end of string), like (as the SQL operator), glob or regexp .

The final argument can be case (case-sensitive matching) or nocase (case-insensitive comparison, this is the default).

The return value is a list of the names or references of the matched filters.

filter read

filter read filename/dirname
filter read all

Read a filter definition file with one or more filter definitions, a directory containing such definition files, or the filter definition files contained in all accessible directories found in the filter auto-load path. In case a filter is already defined in the current interpreter, its definition is overwritten by what is found in the input file.

The return value is a list of two elements. The first element is the total number of filter definitions read from the file. The second element is the name ( Tcl ) or reference ( Python ) of the first filter read.

filter readblob

filter readblob datablob

Read a filter definition from an in-memory XML blob. This blob can only contain a single filter definition. In the Python case, the data blob can be either a Unicode string, or a byte array.

The return value is the name ( Tcl ) or reference ( Python ) of the newly read filter definition.

filter ref


Python -only method to get a reference of the filter, which allows terser attribute retrieval commands and other operations.

filter set

filter set filtername ?attribute value?...
filter set filtername dict
f.attribute = value
f[attribute] = value

Set one or more filter attributes. Some of the attributes listed below are read-only. They are included here because the filter get subcommand refers to this section. The following attributes are supported:

The standard mathematical operator notation >, >=,== etc. may also be used to identify the operator.

filter create alphac property A_RESIDUE(atomtag) value “CA” operator =

If the filter argument is not yet loaded, an attempt to auto-load the definition file is made.

filter string

filter string filtername

Encode the filter as XML blob and return the blob as result. The blob format is the same as output by the filter write command.

filter subcommands

filter subcommands

Get a list of all supported subcommands of the filter command in this particular application.

filter write

filter write filtername ?filename?

Write the current definition of the filter to a file in XML format. The file can be loaded into future script interpreters explicitly (see filter read command) or implicitly via the filter definition auto-load mechanism. If no file name is given, the name of the file is automatically constructed from the filter name in lower case and the suffix .fil. In addition to normal file names, the magic names stdout and stderr may be used, as well as already opened Tcl or Python socket and file handles, plus pipes indicated by a file name which starts with “|”. Writing to Tcl channels is not supported on the MS Windows platform.

The command returns the (possibly auto-generated) file name.

It is possible and sometimes useful to write out built-in filter definitions.