Issue730

README.md

@@ -41,6 +41,9 @@ and on macOS we do not test LP solvers (yet).
 
 See [BUILD.md](BUILD.md).
 
+## Tab completion
+
+See [TABCOMPLETION.md](TABCOMPLETION.md).
 
 ## Contributors
 

TABCOMPLETION.md

@@ -0,0 +1,71 @@
+## Tab completion for Fast Downward
+
+We support tab completion for bash and zsh based on the python package [argcomplete](https://pypi.org/project/argcomplete/). For full support, use at least version 3.3 which can be installed via `pip`.
+
+```bash
+pip install "argcomplete>=3.3"
+```
+
+After the installation, tab completion has to be enabled in one of two ways.
+
+
+### Activating tab completion globally
+
+The global activation will enable tab completion for *all* Python files that support argcomplete (not only files related to Fast Downward). To activate the global tab completion execute the following command. Depending on your installation replace `activate-global-python-argcomplete` with `activate-global-python-argcomplete3`.
+
+```bash
+activate-global-python-argcomplete
+```
+
+
+### Activating tab completion locally
+
+In contrast to global activation, local activation only enables tab completion for files called `fast-downward.py`, `build.py`, or `translate.py`. However, activation is not limited to files that support argcomplete. This means that pressing tab on older version of Fast Downward files or unrelated files with the same name may have unintended side effects. For example, with older version of Fast Downward `build.py <TAB>` will start a build without printing the output.
+
+To activate the local tab completion, add the following commands to your `.bashrc` or `.zshrc`. Depending on your installation replace `register-python-argcomplete` with `register-python-argcomplete3`.
+
+```bash
+eval "$(register-python-argcomplete fast-downward.py)"
+eval "$(register-python-argcomplete build.py)"
+eval "$(register-python-argcomplete translate.py)"
+```
+
+### Activating tab completion for the search binary
+
+If you are working with the search binary `downward` directly, adding the following commands to your `.bashrc` or `.zshrc` will enable tab completion. This is only necessary if you are not using the driver script `fast-downward.py`.
+
+```bash
+function _downward_complete() {
+    local IFS=$'\013'
+    if [[ -n "${ZSH_VERSION-}" ]]; then
+        local DFS=":"
+        local completions
+        local COMP_CWORD=$((CURRENT - 1))
+        completions=( $( "${words[1]}" --bash-complete \
+                         "$IFS" "$DFS" "$CURSOR" "$BUFFER" "$COMP_CWORD" ${words[@]}))
+        if [[ $? == 0 ]]; then
+            _describe "${words[1]}" completions -o nosort
+        fi
+    else
+        local DFS=""
+        COMPREPLY=( $( "$1" --bash-complete \
+                    "$IFS" "$DFS" "$COMP_POINT" "$COMP_LINE" "$COMP_CWORD" ${COMP_WORDS[@]}))
+        if [[ $? != 0 ]]; then
+            unset COMPREPLY
+        fi
+    fi
+}
+
+if [[ -n "${ZSH_VERSION-}" ]]; then
+    compdef _downward_complete downward
+else
+    complete -o nosort -F _downward_complete downward
+fi
+```
+
+Restart your shell afterwards.
+
+
+### Limitations
+
+The search configuration following the `--search` option is not yet covered by tab completion. For example, `fast-downward.py problem.pddl --search "ast<TAB>"` will not suggest `astar`.

build.py

@@ -1,12 +1,24 @@
 #!/usr/bin/env python3
+# PYTHON_ARGCOMPLETE_OK
 
+import argparse
 import errno
 import os
+from pathlib import Path
 import subprocess
 import sys
 
 import build_configs
 
+try:
+    import argcomplete
+    HAS_ARGCOMPLETE = True
+except ImportError:
+    HAS_ARGCOMPLETE = False
+
+PROJECT_ROOT_PATH = Path(__file__).parent
+SRC_PATH = PROJECT_ROOT_PATH / "src"
+
 CONFIGS = {config: params for config, params in build_configs.__dict__.items()
            if not config.startswith("_")}
 DEFAULT_CONFIG_NAME = CONFIGS.pop("DEFAULT")
@@ -24,7 +36,27 @@
     # Number of available CPUs as a fall-back (may be None)
     NUM_CPUS = os.cpu_count()
 
-def print_usage():
+
+class RawHelpFormatter(argparse.HelpFormatter):
+    """Preserve newlines and spacing."""
+    def _fill_text(self, text, width, indent):
+        return "".join([indent + line for line in text.splitlines(True)])
+
+    def _format_args(self, action, default_metavar):
+        """Show explicit help for remaining args instead of "..."."""
+        if action.nargs == argparse.REMAINDER:
+            return "[BUILD ...] [CMAKE_OPTION ...]"
+        else:
+            return argparse.HelpFormatter._format_args(self, action, default_metavar)
+
+
+def parse_args():
+    description = """Build one or more predefined build configurations of Fast Downward. Each build
+uses CMake to compile the code. Build configurations differ in the parameters
+they pass to CMake. By default, the build uses all available cores if this
+number can be determined. Use the "-j" option for CMake to override this
+default behaviour.
+"""
     script_name = os.path.basename(__file__)
     configs = []
     for name, args in sorted(CONFIGS.items()):
@@ -34,56 +66,54 @@ def print_usage():
             name += " (default with --debug)"
         configs.append(name + "\n    " + " ".join(args))
     configs_string = "\n  ".join(configs)
-    cmake_name = os.path.basename(CMAKE)
-    generator_name = CMAKE_GENERATOR.lower()
-    default_config_name = DEFAULT_CONFIG_NAME
-    debug_config_name = DEBUG_CONFIG_NAME
-    print(f"""Usage: {script_name} [BUILD [BUILD ...]] [--all] [--debug] [MAKE_OPTIONS]
-
-Build one or more predefined build configurations of Fast Downward. Each build
-uses {cmake_name} to compile the code using {generator_name} . Build configurations
-differ in the parameters they pass to {cmake_name}. By default, the build uses all
-available cores if this number can be determined. Use the "-j" option for
-{cmake_name} to override this default behaviour.
-
-Build configurations
+    epilog = f"""build configurations:
   {configs_string}
 
---all         Alias to build all build configurations.
---debug       Alias to build the default debug build configuration.
---help        Print this message and exit.
-
-Make options
-  All other parameters are forwarded to the build step.
-
-Example usage:
-  ./{script_name}                     # build {default_config_name} in #cores threads
-  ./{script_name} -j4                 # build {default_config_name} in 4 threads
-  ./{script_name} debug               # build debug
-  ./{script_name} --debug             # build {debug_config_name}
-  ./{script_name} release debug       # build release and debug configs
-  ./{script_name} --all VERBOSE=true  # build all build configs with detailed logs
-""")
-
-
-def get_project_root_path():
-    import __main__
-    return os.path.dirname(__main__.__file__)
-
-
-def get_builds_path():
-    return os.path.join(get_project_root_path(), "builds")
-
-
-def get_src_path():
-    return os.path.join(get_project_root_path(), "src")
+example usage:
+  {script_name}                     # build {DEFAULT_CONFIG_NAME} with #cores parallel processes
+  {script_name} -j4                 # build {DEFAULT_CONFIG_NAME} with 4 parallel processes
+  {script_name} debug               # build debug
+  {script_name} --debug             # build {DEBUG_CONFIG_NAME}
+  {script_name} release debug       # build release and debug configs
+  {script_name} --all VERBOSE=true  # build all build configs with detailed logs
+"""
+
+    parser = argparse.ArgumentParser(
+        description=description, epilog=epilog, formatter_class=RawHelpFormatter)
+    parser.add_argument("--debug", action="store_true",
+                        help="alias to build the default debug build configuration")
+    parser.add_argument("--all", action="store_true",
+                        help="alias to build all build configurations")
+    remaining_args = parser.add_argument("arguments", nargs=argparse.REMAINDER,
+                        help="build configurations (see below) or build options")
+    remaining_args.completer = complete_arguments
+
+    if HAS_ARGCOMPLETE:
+        argcomplete.autocomplete(parser)
+
+    # With calls like 'build.py -j4' the parser would try to interpret '-j4' as
+    # an option and fail to parse. We use parse_known_args to parse everything
+    # we recognize and add everything else to the list of arguments.
+    args, unparsed_args = parser.parse_known_args()
+    args.arguments = unparsed_args + args.arguments
+
+    return args
+
+
+def complete_arguments(prefix, parsed_args, **kwargs):
+    # This will modify parsed_args in place. This is not a problem because the
+    # process will stop after generating suggestions for the tab completion.
+    split_args(parsed_args)
+    unused_configs = set(CONFIGS) - set(parsed_args.config_names)
+    return sorted([c for c in unused_configs if c.startswith(prefix)])
 
 
 def get_build_path(config_name):
-    return os.path.join(get_builds_path(), config_name)
+    return PROJECT_ROOT_PATH / "builds" / config_name
+
 
 def try_run(cmd):
-    print(f'Executing command "{" ".join(cmd)}"')
+    print(f"""Executing command '{" ".join(cmd)}'""")
     try:
         subprocess.check_call(cmd)
     except OSError as exc:
@@ -94,17 +124,18 @@ def try_run(cmd):
         else:
             raise
 
+
 def build(config_name, configure_parameters, build_parameters):
     print(f"Building configuration {config_name}.")
 
     build_path = get_build_path(config_name)
-    generator_cmd = [CMAKE, "-S", get_src_path(), "-B", build_path]
+    generator_cmd = [CMAKE, "-S", str(SRC_PATH), "-B", str(build_path)]
     if CMAKE_GENERATOR:
         generator_cmd += ["-G", CMAKE_GENERATOR]
     generator_cmd += configure_parameters
     try_run(generator_cmd)
 
-    build_cmd = [CMAKE, "--build", build_path]
+    build_cmd = [CMAKE, "--build", str(build_path)]
     if NUM_CPUS:
         build_cmd += ["-j", f"{NUM_CPUS}"]
     if build_parameters:
@@ -114,25 +145,27 @@ def build(config_name, configure_parameters, build_parameters):
     print(f"Built configuration {config_name} successfully.")
 
 
+def split_args(args):
+    args.config_names = []
+    args.build_parameters = []
+    for arg in args.arguments:
+        if arg in CONFIGS:
+            args.config_names.append(arg)
+        elif arg != "--":
+            args.build_parameters.append(arg)
+
+    if args.debug:
+        args.config_names.append(DEBUG_CONFIG_NAME)
+    if args.all:
+        args.config_names.extend(sorted(CONFIGS.keys()))
+
+
 def main():
-    config_names = []
-    build_parameters = []
-    for arg in sys.argv[1:]:
-        if arg == "--help" or arg == "-h":
-            print_usage()
-            sys.exit(0)
-        elif arg == "--debug":
-            config_names.append(DEBUG_CONFIG_NAME)
-        elif arg == "--all":
-            config_names.extend(sorted(CONFIGS.keys()))
-        elif arg in CONFIGS:
-            config_names.append(arg)
-        else:
-            build_parameters.append(arg)
-    if not config_names:
-        config_names.append(DEFAULT_CONFIG_NAME)
-    for config_name in config_names:
-        build(config_name, CONFIGS[config_name], build_parameters)
+    args = parse_args()
+    split_args(args)
+    for config_name in args.config_names or [DEFAULT_CONFIG_NAME]:
+        build(config_name, CONFIGS[config_name],
+              args.build_parameters)
 
 
 if __name__ == "__main__":