mccq 1.0.2
Minecraft command query program. Inspired by the in-game help command, with added features like multiple version support and expandable regex search.
License: MIT
Requires Python: >=3.6
Keywords: minecraft command query help utility

# Minecraft Command Query
Minecraft command query program. Inspired by the in-game help command, with added features like multiple version support and expandable regex search.

[![package-badge]](https://pypi.python.org/pypi/mccq/)
[![version-badge]](https://pypi.python.org/pypi/mccq/)

## Installation
Requires Python 3.6+, recommended with [virtualenv](https://virtualenv.pypa.io/en/stable/) or the like. Just install with `pip`:

```
pip install mccq
```

## Database setup
MCCQ requires access to generated server files (namely `commands.json`), and so is compatible with [Minecraft snapshot 18w01a](https://minecraft.net/en-us/article/minecraft-snapshot-18w01a) and up.

Each version directory must remain as generated by the server, and all version directories should be in the same root database directory:

```
database_root/
  18w01a/
    generated/
      reports/
        commands.json
  18w02a/
    generated/
      reports/
        commands.json
```

These files can be loaded either from the local filesystem or [the internet](https://github.com/Arcensoth/mcdata).

## Basic usage
Enter the CLI (command line interface) by providing it a default version `-s` to query and a database location `-d` where version directories are located:
```bash
python -m mccq -s 18w01a -d "https://raw.githubusercontent.com/Arcensoth/mcdata"
```

Start with a basic command:
```bash
> say
```

This produces some output:
```bash
# 18w01a
say <message>
```
Which will generally outline all possible variations of the command for the specified version(s).

Try something a little more involved:
```bash
> effect
# 18w01a
effect clear|give ...
```
The command is rolled out until a choice can be made, which saves on vertical space and is often more readable than assigning a separate line to each possibility.

## Program options
Various flags and options can be written **before the command query** to augment behaviour.

Normally several subcommands/arguments are condensed to one line, but `-e` can be used to forcibly expand the command:
```bash
> -e effect
# 18w01a
effect clear <targets>
effect clear <targets> <effect>
effect give <targets> <effect>
effect give <targets> <effect> <seconds>
effect give <targets> <effect> <seconds> <amplifier>
effect give <targets> <effect> <seconds> <amplifier> <hideParticles>
```
Be warned that this can cause a large amount of output for commands with many subcommands/arguments.

Search for specific subcommands/arguments:
```bash
> tag targets add
# 18w01a
tag <targets> add <name>
```
Notice how arguments are shown between `<>` but can be searched by name just like subcommands.

Speaking of arguments, use `-t` to render their types:
```bash
> -t tag targets add
# 18w01a
tag <targets: entity> add <name: string>
```

Use `-v VERSION` to query a particular version:
```bash
> -v 18w02a execute
# 18w02a
execute align|anchored|as|at|facing|if|in|positioned|rotated|run|store|unless ...
```

Repeat `-v VERSION` to query several versions at once:
```bash
> -v 18w01a -v 18w02a execute
# 18w01a
execute align|as|at|if|offset|run|store|unless ...
# 18w02a
execute align|anchored|as|at|facing|if|in|positioned|rotated|run|store|unless ...
```

For more precise control than `-e` can offer, provide `-c CAPACITY` to define a threshold for expansion:
```bash
> -c 5 time set
# 18w01a
time set day
time set midnight
time set night
time set noon
time set <time>
> -c 4 time set
# 18w01a
time set day|midnight|night|noon|<time>
```
This allows a command to expand so long as the total number of subcommands/arguments it contains does not exceed the given threshold.

## Dynamic search
Each whitespace-separated search term of the provided query is treated as a regex pattern:
```bash
> execute a.*
# 18w01a
execute align <axes> -> execute
execute as <targets> -> execute
execute at <targets> -> execute
```

And so any combination of subcommands/arguments can be flexibly queried:
```bash
> t.* targets
# 18w01a
tag <targets> add <name>
tag <targets> list
tag <targets> remove <name>
teleport <targets> <destination>|<location> ...
tellraw <targets> <message>
title <targets> actionbar|clear|reset|subtitle|times|title ...
```

Search terms are case-insensitive:
```bash
> gamerule .*mob.*
# 18w01a
gamerule doMobLoot
gamerule doMobLoot <value>
gamerule doMobSpawning
gamerule doMobSpawning <value>
gamerule mobGriefing
gamerule mobGriefing <value>
```

Special case: a single `.` is treated as a wildcard and will match any term:
```bash
> clone . . . masked
# 18w01a
clone <begin> <end> <destination> masked
clone <begin> <end> <destination> masked force|move|normal
```
Which is a convenient way of quickly diving into the command.

[package-badge]: https://img.shields.io/pypi/v/mccq.svg
[version-badge]: https://img.shields.io/pypi/pyversions/mccq.svg