# Filter

The **Filter** object lets you create a [textual filter](https://chaoses-ib.gitbook.io/directory-opus/manual/reference/textual_filters) of the type used by the **Find** tool and commands such as **Copy** to control recursive operations.

Use the [**dopusfactory**](https://chaoses-ib.gitbook.io/directory-opus/manual/reference/scripting_reference/scripting_objects/dopusfactory)**.Filter** method to create a new filter object. Once you have a **Filter** object you can:

* Use the [**item**](https://chaoses-ib.gitbook.io/directory-opus/manual/reference/scripting_reference/scripting_objects/item)**.MatchFilter** method to see if a file or folder matches the filter.
* Apply the filter to a command with the [**command**](https://chaoses-ib.gitbook.io/directory-opus/manual/reference/scripting_reference/scripting_objects/command)**.SetFilter** method.

| Property Name | Return Type                                                                                                                                           | Description                                                                                                           |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| lasterror     | *object:*[**filterparseerror**](https://chaoses-ib.gitbook.io/directory-opus/manual/reference/scripting_reference/scripting_objects/filterparseerror) | If *valid* returns **False** you can use this property to discover information about the error.                       |
| valid         | *bool*                                                                                                                                                | Returns **True** if the filter was created successfully (i.e. no errors were encountered in parsing the filter text). |

| Method Name | **Arguments**                                                                               | Return Type | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Add         | <p>\<string:clause><br>or \<object:<strong>Filter</strong>><br>\[\<string:conjunction>]</p> | *bool*      | <p>Adds a clause to the filter. If provided as a string, the clause will be parsed and the method returns <strong>True</strong> if parsing was successful. If parsing fails, use the <strong>lasterror</strong> property to find out why. Alternatively, you can add another <strong>Filter</strong> object.</p><p>The <em>clause</em> string must be a fully formed <a href="../../textual_filters">textual filter</a> clause. For example, <code>size match > 2 mb</code></p><p>The optional <em>conjunction</em> string lets you choose whether the clause is joined via <strong>and</strong> or <strong>or</strong>. If not specified, the default is <strong>and</strong>.</p> |
| Clear       | *none*                                                                                      | *none*      | Clears the contents of the filter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Set         | <p>\<string:clause><br>or \<object:<strong>Filter</strong>></p>                             | *bool*      | Initialises the filter with either a string or the contents of an existing **Filter** object. If provided as a string, the clause will be parsed and the method returns **True** if parsing was successful. If parsing fails, use the **lasterror** property to find out why.                                                                                                                                                                                                                                                                                                                                                                                                       |