Skip to content

Commit 66edab0

Browse files
committed
Merge branch 'main' into fix-ppaged-missing-pager
# Conflicts: # CHANGELOG.md
2 parents 7b3c582 + ff372de commit 66edab0

8 files changed

Lines changed: 659 additions & 43 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,21 @@
33
- Bug Fixes
44
- Fixed file path completion for names containing square brackets, including bracketed working
55
directories and home directories.
6+
- Fixed `get_exes_in_path()` and shell command completion when executable names or `PATH`
7+
directories contain square brackets.
8+
- File path completion, shell command completion, and `get_exes_in_path()` now match `*` and `?`
9+
literally instead of returning nothing when the text being completed contains one, so names
10+
containing those characters can be completed.
11+
- Tab completion now adds quotes when a match has a character which is special to a shell, such
12+
as `*`, `?`, `(`, `&`, or `$`, if what is being completed is passed to one. That is the case
13+
for the arguments of the `shell` command and for everything after a pipe. Everywhere else,
14+
only a match with a space is quoted, as before. See the
15+
[Special Characters in Paths](docs/features/completion.md#special-characters-in-paths)
16+
documentation for details.
17+
- `get_exes_in_path()`, `find_editor()`, and shell command completion no longer skip `PATH`
18+
entries which are symbolic links to directories.
19+
- `find_editor()` now finds the `edit` editor on Windows. It was the preferred default editor
20+
there but could never be found because it was searched for without its `.exe` extension.
621
- `ppaged()` now prints its output when the configured pager program cannot be run, for example
722
where `less` is not installed. Previously only the shell's error was shown and the output was
823
lost. A pager command which could not be run is not tried again while the application is

‎cmd2/cmd2.py‎

Lines changed: 43 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2424,6 +2424,10 @@ def path_complete(
24242424
) -> Completions:
24252425
"""Perform completion of local file system paths.
24262426
2427+
Apart from a leading ``~``, which refers to a user's home directory, every character in ``text`` is
2428+
matched literally. Glob characters like ``*``, ``?``, and ``[`` are not expanded, and they are not
2429+
escaped in the results.
2430+
24272431
:param text: the string prefix we are attempting to match (all matches must begin with it)
24282432
:param line: the current input line with leading whitespace removed
24292433
:param begidx: the beginning index of the prefix text
@@ -2438,25 +2442,19 @@ def path_complete(
24382442
if endidx == len(line) or (endidx < len(line) and line[endidx] != os.path.sep):
24392443
add_trailing_sep_if_dir = True
24402444

2441-
# Used to replace cwd in the final results
2445+
# Used to replace CWD in the final results
24422446
cwd = os.getcwd()
24432447
cwd_added = False
24442448

24452449
# Used to replace expanded user path in final result
24462450
orig_tilde_path = ""
24472451
expanded_tilde_path = ""
24482452

2449-
# If the search text is blank, then search in the CWD for *
2453+
# If the search text is blank, then complete all entries in the CWD
24502454
if not text:
24512455
search_str = os.path.join(os.getcwd(), "")
24522456
cwd_added = True
24532457
else:
2454-
# Purposely don't match any path containing wildcards
2455-
wildcards = ["*", "?"]
2456-
for wildcard in wildcards:
2457-
if wildcard in text:
2458-
return Completions()
2459-
24602458
# Start the search string
24612459
search_str = text
24622460

@@ -2475,7 +2473,7 @@ def path_complete(
24752473
orig_tilde_path = text[:sep_index]
24762474
expanded_tilde_path = os.path.expanduser(orig_tilde_path)
24772475

2478-
# If the search text does not have a directory, then use the cwd
2476+
# If the search text does not have a directory, then use the CWD
24792477
elif not os.path.dirname(text):
24802478
search_str = os.path.join(os.getcwd(), search_str)
24812479
cwd_added = True
@@ -2504,7 +2502,7 @@ def path_complete(
25042502
matches[index] += os.path.sep
25052503
display_matches[index] += os.path.sep
25062504

2507-
# Remove cwd if it was added to match the text prompt-toolkit expects
2505+
# Remove CWD if it was added to match the text prompt-toolkit expects
25082506
if cwd_added:
25092507
to_replace = cwd if cwd == os.path.sep else cwd + os.path.sep
25102508
matches = [cur_path.replace(to_replace, "", 1) for cur_path in matches]
@@ -2540,7 +2538,7 @@ def shell_cmd_complete(
25402538
if not complete_blank and not text:
25412539
return Completions()
25422540

2543-
# If there are no path characters in the search text, then do shell command completion in the user's path
2541+
# If the search text is a bare command name (no '~' or path separator), complete executables from PATH
25442542
if not text.startswith("~") and os.path.sep not in text:
25452543
items = [CompletionItem(exe) for exe in utils.get_exes_in_path(text)]
25462544
return Completions(items=items)
@@ -2575,6 +2573,9 @@ def _redirect_complete(self, text: str, line: str, begidx: int, endidx: int, com
25752573
# True when command line contains any redirection tokens
25762574
has_redirection = False
25772575

2576+
# True when the first redirection token is a pipe, which means everything after it is passed to a shell
2577+
piped_to_shell = False
2578+
25782579
# Keep track of state while examining tokens
25792580
in_pipe = False
25802581
in_file_redir = False
@@ -2585,6 +2586,8 @@ def _redirect_complete(self, text: str, line: str, begidx: int, endidx: int, com
25852586
for cur_token in raw_tokens:
25862587
# Process redirection tokens
25872588
if cur_token in constants.REDIRECTION_TOKENS:
2589+
if not has_redirection:
2590+
piped_to_shell = cur_token == constants.REDIRECTION_PIPE
25882591
has_redirection = True
25892592

25902593
# Check if we are at a pipe
@@ -2617,11 +2620,10 @@ def _redirect_complete(self, text: str, line: str, begidx: int, endidx: int, com
26172620

26182621
prior_token = cur_token
26192622

2620-
if do_shell_completion:
2621-
return self.shell_cmd_complete(text, line, begidx, endidx)
2622-
2623-
if do_path_completion:
2624-
return self.path_complete(text, line, begidx, endidx)
2623+
if do_shell_completion or do_path_completion:
2624+
completer = self.shell_cmd_complete if do_shell_completion else self.path_complete
2625+
completions = completer(text, line, begidx, endidx)
2626+
return self._for_shell(completions) if piped_to_shell else completions
26252627

26262628
# If there were redirection strings anywhere on the command line, then we
26272629
# are no longer completing for the current command
@@ -2768,7 +2770,13 @@ def _perform_completion(
27682770
if not completion_token_quote:
27692771
matches = completions.to_strings()
27702772

2771-
if any(" " in match for match in matches):
2773+
# Matches which are being passed to a shell need quotes if any of them has a character special to it
2774+
if completions._quote_for_shell:
2775+
_quote_char = utils._shell_quote_char(matches)
2776+
_add_opening_quote = bool(_quote_char)
2777+
2778+
# Everything else only needs quotes to keep a match with a space as a single token
2779+
elif any(" " in match for match in matches):
27722780
_add_opening_quote = True
27732781

27742782
# Determine best quote (single vs double) based on text content
@@ -5075,13 +5083,29 @@ def do_set(self, args: argparse.Namespace) -> None:
50755083
@classmethod
50765084
def _build_shell_parser(cls) -> Cmd2ArgumentParser:
50775085
shell_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description="Execute a command as if at the OS prompt.")
5078-
shell_parser.add_argument("command", help="the command to run", completer=cls.shell_cmd_complete)
5086+
shell_parser.add_argument("command", help="the command to run", completer=cls._complete_shell_command)
50795087
shell_parser.add_argument(
5080-
"command_args", nargs=argparse.REMAINDER, help="arguments to pass to command", completer=cls.path_complete
5088+
"command_args", nargs=argparse.REMAINDER, help="arguments to pass to command", completer=cls._complete_shell_arg
50815089
)
50825090

50835091
return shell_parser
50845092

5093+
@staticmethod
5094+
def _for_shell(completions: Completions) -> Completions:
5095+
"""Mark completions as being for part of the command line which is passed to a shell.
5096+
5097+
This is what gets them quoted when one of them has a character which is special to that shell.
5098+
"""
5099+
return dataclasses.replace(completions, _quote_for_shell=True)
5100+
5101+
def _complete_shell_command(self, text: str, line: str, begidx: int, endidx: int) -> Completions:
5102+
"""Complete the command which do_shell passes to a shell."""
5103+
return self._for_shell(self.shell_cmd_complete(text, line, begidx, endidx))
5104+
5105+
def _complete_shell_arg(self, text: str, line: str, begidx: int, endidx: int) -> Completions:
5106+
"""Complete an argument of the command which do_shell passes to a shell."""
5107+
return self._for_shell(self.path_complete(text, line, begidx, endidx))
5108+
50855109
# Preserve quotes since we are passing these strings to the shell
50865110
@with_argparser(_build_shell_parser, preserve_quotes=True)
50875111
def do_shell(self, args: argparse.Namespace) -> None:

‎cmd2/completion.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -305,3 +305,7 @@ class Completions(CompletionResultsBase):
305305

306306
# The quote character to use if adding an opening or closing quote to the matches.
307307
_quote_char: str = ""
308+
309+
# Whether the matches are for part of the command line which is passed to a shell. If they are,
310+
# then quotes are also added when a match has a character which is special to that shell.
311+
_quote_for_shell: bool = field(default=False, compare=False)

‎cmd2/utils.py‎

Lines changed: 54 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
Generator,
1818
Iterable,
1919
MutableSequence,
20+
Sequence,
2021
)
2122
from difflib import SequenceMatcher
2223
from typing import (
@@ -323,6 +324,36 @@ def expand_user_in_tokens(tokens: MutableSequence[str]) -> None:
323324
tokens[index] = expand_user(tokens[index])
324325

325326

327+
# Matches a character which is special to a POSIX shell. A '[' counts even when no ']' follows it since
328+
# some shells, like zsh, reject that as a bad pattern. A '#' and a '=' only count at the start of a word.
329+
_POSIX_SPECIAL_RE = re.compile(r"""[ \t"';|<>&()*?\[{}$`\\]|^[#=]""")
330+
331+
# Matches a character which cmd.exe documents as requiring quotes. A '~' is left out because it is not
332+
# special to cmd.exe itself, and quoting it would quote every path below a home directory.
333+
_WINDOWS_SPECIAL_RE = re.compile(r"""[ \t&()\[\]{}^=;!'+,`]""")
334+
335+
336+
def _shell_quote_char(matches: Sequence[str]) -> str:
337+
"""Return the quote character which completions being passed to a shell need to be wrapped in.
338+
339+
:param matches: the completions being offered for part of a command line which is passed to a shell
340+
:return: the quote character to use, or an empty string if none of the matches need quotes
341+
"""
342+
if sys.platform.startswith("win"):
343+
# cmd.exe only treats double quotes as quotes, and a Windows file name can't contain one
344+
return '"' if any(_WINDOWS_SPECIAL_RE.search(match) for match in matches) else ""
345+
346+
if not any(_POSIX_SPECIAL_RE.search(match) for match in matches):
347+
return ""
348+
349+
# A quote character within a match has to be quoted with the other quote character
350+
if any("'" in match for match in matches):
351+
return '"'
352+
353+
# Only use single quotes when a shell would still expand something within double quotes
354+
return "'" if any(char in match for match in matches for char in '"$`\\') else '"'
355+
356+
326357
def _quote_shell_arg(arg: str) -> str:
327358
"""Quote a string so the OS shell treats it as one literal argument.
328359
@@ -345,6 +376,21 @@ def _quote_shell_arg(arg: str) -> str:
345376
return shlex.quote(arg)
346377

347378

379+
def _get_path_dirs() -> set[str]:
380+
"""Return the directories listed in the PATH environment variable.
381+
382+
The entries are returned as they are written. Resolving them would avoid searching a directory twice
383+
when it is listed under two names, but doing so can raise an exception for an entry which can't be reached.
384+
385+
An empty entry is kept because a POSIX shell searches the current working directory for one. A PATH which
386+
is set to an empty string is a single empty entry, so it is not the same as a PATH which is not set.
387+
388+
:return: the directories, which is an empty set if PATH is not set
389+
"""
390+
env_path = os.getenv("PATH")
391+
return set() if env_path is None else set(env_path.split(os.path.pathsep))
392+
393+
348394
def find_editor() -> str | None:
349395
"""Set cmd2.Cmd.DEFAULT_EDITOR. If EDITOR env variable is set, that will be used.
350396
@@ -354,15 +400,12 @@ def find_editor() -> str | None:
354400
editor = os.environ.get("EDITOR")
355401
if not editor:
356402
if sys.platform[:3] == "win":
357-
editors = ["edit", "code.cmd", "notepad++.exe", "notepad.exe"]
403+
editors = ["edit.exe", "code.cmd", "notepad++.exe", "notepad.exe"]
358404
else:
359405
editors = ["vim", "vi", "emacs", "nano", "pico", "joe", "code", "subl", "gedit", "kate"]
360406

361-
# Get a list of every directory in the PATH environment variable and ignore symbolic links
362-
env_path = os.getenv("PATH")
363-
paths = [] if env_path is None else [p for p in env_path.split(os.path.pathsep) if not os.path.islink(p)]
364-
365-
for possible_editor, path in itertools.product(editors, paths):
407+
# Use the most preferred editor which is in any of the PATH directories
408+
for possible_editor, path in itertools.product(editors, _get_path_dirs()):
366409
editor_path = os.path.join(path, possible_editor)
367410
if os.path.isfile(editor_path) and os.access(editor_path, os.X_OK):
368411
if sys.platform[:3] == "win":
@@ -408,26 +451,19 @@ def files_from_glob_patterns(patterns: Iterable[str], access: int = os.F_OK) ->
408451
def get_exes_in_path(starts_with: str) -> list[str]:
409452
"""Return names of executables in a user's path.
410453
454+
Every character in ``starts_with`` is matched literally. Glob characters like ``*``, ``?``, and ``[``
455+
are not expanded.
456+
411457
:param starts_with: what the exes should start with. leave blank for all exes in path.
412458
:return: a list of matching exe names
413459
"""
414-
# Purposely don't match any executable containing wildcards
415-
wildcards = ["*", "?"]
416-
for wildcard in wildcards:
417-
if wildcard in starts_with:
418-
return []
419-
420-
# Get a list of every directory in the PATH environment variable and ignore symbolic links
421-
env_path = os.getenv("PATH")
422-
paths = [] if env_path is None else [p for p in env_path.split(os.path.pathsep) if not os.path.islink(p)]
423-
424460
# Use a set to store exe names since there can be duplicates
425461
exes_set = set()
426462

427463
# Find every executable file in the user's path that matches the pattern
428-
for path in paths:
464+
for path in _get_path_dirs():
429465
full_path = os.path.join(path, starts_with)
430-
matches = files_from_glob_pattern(full_path + "*", access=os.X_OK)
466+
matches = files_from_glob_pattern(glob.escape(full_path) + "*", access=os.X_OK)
431467

432468
for match in matches:
433469
exes_set.add(os.path.basename(match))

‎docs/features/completion.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,52 @@ line of code similar to the following to your class which inherits from `cmd2.Cm
3333
complete_bar = functools.partialmethod(cmd2.Cmd.path_complete, path_filter=os.path.isdir)
3434
```
3535

36+
## Special Characters in Paths
37+
38+
Path and shell command completion match the text being completed literally. Glob characters such as
39+
`*`, `?`, and `[` are never expanded, so a file named `my*file.txt` or `notes[2026].txt` completes
40+
like any other. The one exception is a leading `~`, which refers to a user's home directory as it
41+
does in a shell.
42+
43+
Completion results are literal names too. `cmd2` does not escape them, because most commands use a
44+
path directly in Python, where the literal name is exactly what is wanted. The only thing `cmd2`
45+
adds is quotes around a match which contains a space, so it stays a single argument.
46+
47+
### Paths Passed to a Shell
48+
49+
There are two places where `cmd2` knows that what is being completed will be passed to a shell: the
50+
arguments of the [shell](./builtin_commands.md#shell) command, including its `!` shortcut, and
51+
everything after a [pipe](./redirection.md). There `cmd2` also adds quotes when a match has a
52+
character which is special to that shell, so the shell does not interpret it. For example,
53+
completing `!ls my*` gives:
54+
55+
```text
56+
(Cmd) !ls "my*file.txt"
57+
```
58+
59+
On POSIX systems the characters which get a match quoted are a space, a quote character, `*`, `?`,
60+
`[`, `{`, `}`, `(`, `)`, `<`, `>`, `|`, `&`, `;`, `$`, a backtick, a backslash, and a leading `#` or
61+
`=`. Single quotes are used when a match has a `$`, a backtick, a backslash, or a double quote in
62+
it, since a shell still interprets those within double quotes. On Windows the characters are the
63+
ones `cmd.exe` documents as requiring quotes, other than `~`, and the quotes are always double
64+
quotes.
65+
66+
There are limits to this:
67+
68+
- One pair of quotes goes around the whole argument, and it is chosen before you pick a match. So
69+
when several matches are offered and only one of them needs quotes, they all get them. An
70+
executable named `[` is common, so completing a shell command which could match it quotes every
71+
match.
72+
- For the same reason, one quote character is used for all the matches being offered. If any of them
73+
has a single quote in it, double quotes are used, and a `$`, a backtick, or a backslash in any of
74+
the matches is then still interpreted by a shell.
75+
- A `%` in a match is still interpreted by `cmd.exe` on Windows.
76+
- A [macro](./shortcuts_aliases_macros.md#macros) which runs a shell command is not covered. Its
77+
arguments are completed as paths, but they are only quoted for a space. An alias for the `shell`
78+
command is covered.
79+
- Your own commands are not covered, even if they pass their arguments to a shell. Quote or escape
80+
those arguments in the command.
81+
3682
## Included Tab Completion Functions
3783

3884
[cmd2.Cmd][] provides the following tab completion functions

‎tests/conftest.py‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,12 @@
33
import os
44
import subprocess
55
import sys
6-
from collections.abc import Callable
6+
from collections.abc import (
7+
Callable,
8+
Iterable,
9+
)
710
from contextlib import redirect_stderr
11+
from pathlib import Path
812
from typing import (
913
TYPE_CHECKING,
1014
ParamSpec,
@@ -61,6 +65,14 @@ def normalize(block: str) -> list[str]:
6165
return [line.rstrip() for line in block.splitlines()]
6266

6367

68+
def make_exes(directory: Path, names: Iterable[str]) -> None:
69+
"""Create an executable file in directory for each name."""
70+
for name in names:
71+
exe = directory / name
72+
exe.touch()
73+
exe.chmod(0o755)
74+
75+
6476
def run_cmd(app: cmd2.Cmd, cmd: str) -> tuple[list[str], list[str]]:
6577
"""Run the command in app and return what it writes to app.stdout and sys.stderr."""
6678

0 commit comments

Comments
 (0)