# Command line syntax

Commands are formatted in the following pattern:

```
chore [filters] [command] [modifications]
```

## Filters

A filter is information used to restrict the tasks a command applies to.
Filters may be any of:

- A `+project`, `@context`, or `key:value` pair: tasks which have the given
  tag.
- A key with a modifier:
	- `key.any:`: tasks which have the key, irrelevant of its value.
	- `key.none:`: tasks which lack a pair with the key.
	- `key.before:date:`: tasks with the key whose value ends before the
	  specified date's starts.
	- `key.after:date:`: tasks with the key whose value starts after the
	  specified date's ends.
	- `key.in:date:`: tasks with the key whose value either matches or is
	  contained within the specified date.
- `/regex/`: tasks which match the regular expression.
- `(P)`: tasks which have the specified priority.
- `(A-Z)`: tasks which have a priority within the specified range.
- `1`: tasks which occur on the specified line number.
- `1-3`: tasks which occur within the specified range of line numbers.
- `1,2,3`: tasks which have any of the listed line numbers.
- `all`: this matches all filters.  Its intended use is to override Chore's
  default filters.

### Inverted filters

All filters can be inverted by prefixing either a `-` or `!` to the filter.
For example, `-@work` will filter out all tasks that have the `@work` context
and `!/foo/` will filter out all tasks that match the regular expression
`/foo/`.

### Filter aliases

Users may configure aliases for filters by creating a directory at
`~/.chore/filter-aliases` which contains files whose name describes the alias
and contents contain newline-separated filters.  For example:

- `~/.chore/filter-aliases/waiting` may contain `wait.after:now`
- `~/.chore/filter-aliases/overdue` may contain `due.before:now`
- `~/.chore/filter-aliases/ready` may contain `scheduled.before:now`
- `~/.chore/filter-aliases/pending` may contain `+done`
- `~/.chore/filter-aliases/completed` may contain `-+done`

An example of an alias that describes multiple filters may be a file at
`~/.chore/filter-aliases/missed` which contains:

```
-+done
until.before:now
```

### Default filters

Chore can be configured to apply a list of filters by default by creating a
directory at `~/.chore/default-filters` which contains files that in turn
contain filters, no more than once per line.  For example

- `~/.chore/default-filters/hide-completed` may contain `-+done`
- `~/.chore/default-filters/hide-missed` may contain `-until.after:now`
- `~/.chore/default-filters/hide-waiting` may contain `-wait.before:now`
- `~/.chore/default-filters/hide` may contain `-+hide`

Such filters may be overridden on the command line:

- Any filter that operates on the same term as a default filter will disable
  the default filter.
	- For example, `wait.any:` overrides a default `-wait.before:now`.
	- For example, `+hide` overrides a default `-+hide`.
	- For example, `pri.any:` overrides a default `(A-M)`.
- Any regex filter overrides all default regex filters.
- Any line number filter overrides all default line number filters.
- The `all` filter, which disables all default filters.

The choice to make default-filters a directory rather than a file was primarily
to ease automation around creating and removing default filters; specifically,
around changing contexts.  For example, if someone works from home, a default
`@work` filter may exist during work hours, then be overwritten to `@home` on
nights and weekends.  A mobile device might detect it is in a grocery store via
GPS or wifi and set the default context to `@shopping`.

In practice, a user may be in multiple contexts at once.  For example, a user
may both be in a "@home" context and a "@dog" context when home with his or her
dog.  Chore does not have a way to directly express "or" filters, but it does
support negated filters; consequently De Morgan's law may be of use: users may
create filters which negate currently invalid contexts to effectively pass
multiple valid contexts.  For example, nights and weekends may have a default
`-@work` filter, and GPS or wifi may create a `-@home` when away from home.

## Modifications

A modification is information used by the `modify` command to change the
contents of tasks that pass the provided filters.

- `+project` or `@context: if the task lags the tag, add it.
- `key:value`: if the task lacks the key, add the pair.  If the task has the
  tag, update its value.
- `-+project`, `!+project`, `-@context`, or `!@context`, `-key:value`,
  `!key:value`: if the task has the tag, remove it.
- `-key:` or `!key:`: if the task has the key irrelevant of value, remove it.
- `>>text`: append text.  Following ambiguous fields are also appended.
- Otherwise, the modifiction is assumed to be new body text that completely
  overwrites the task body.  Following ambiguous fields are interpreted as
  additional new body content.

### Modification aliases

Users may configure aliases for modifications by creating a directory at
`~/.chore/modification-aliases` which contains files whose name describes the
alias and contents contain whitespace-separated modifications.  For example,
`~/.chore/modification-aliases/reopen` may contain `-+done -end:`, which would
then allow users to run:

```
chore 10 modify reopen
```

to modify a completed task on line 10 to be no longer considered completed.

## Commands

### Listing commands

These commands may not have any `modification`.

- `list`: lists tasks.  If Chore is run without any non-filter arguments this
  command is assumed by default.
- `projects`: lists all projects in use by at least one task.
- `contexts`: lists all contexts in use by at least one task.
- `keys`: lists all keys in use by at least one task.

### Non-listing commands

- `add`: Add a new task.  Entire modification text is treated as new task body,
  and an entry date is set automatically.
- `delete`: Delete a task.  No modification is allowed.
- `modify`: modifies tasks with the specified modifications.  At least one
  modification is required.
- `undo`: undo last add, remove, or modify command.

### Command aliases

Users may configure aliases for commands by creating a directory at
`~/.chore/command-aliases` which contains files whose name describes the alias
and contents contain whitespace-separated filters.  For example:

- `~/.chore/command-aliases/a` may contain `add`
- `~/.chore/command-aliases/proj` may contain `projects`
- `~/.chore/command-aliases/ctx` may contain `contexts`
- `~/.chore/command-aliases/mod` may contain `modify`
- `~/.chore/command-aliases/done` may contain `modify +done end:today`
- `~/.chore/command-aliases/prepend` may contain `modify <<`
- `~/.chore/command-aliases/append` may contain `modify >>`
- `~/.chore/command-aliases/note` may contain `modify >>|`

This can be used to set default modifications for a command.  For example,
during work hours a file at `~/.chore/command-aliases/add` may be created which
contains `add @work`, setting the `@work` context by default.  On nights and
weekends, this command alias may be deleted, after which `add` refrains from
setting any context.