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,44 @@
+## 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, 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)"
+
+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.

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__":