summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKevin Van Brunt <kmvanbrunt@gmail.com>2019-07-11 15:16:38 -0400
committerKevin Van Brunt <kmvanbrunt@gmail.com>2019-07-11 15:16:38 -0400
commitc1312cadba42f273179a6bc08ec5a8d22ca23891 (patch)
tree42a8d0ee8cf37f605c5db5e020794a88a8f67e1d
parenteb5b4fff8b1042d6a5b30a768bf35496acc4c593 (diff)
downloadcmd2-git-c1312cadba42f273179a6bc08ec5a8d22ca23891.tar.gz
Updated documentation
-rw-r--r--cmd2/argparse_custom.py71
-rw-r--r--cmd2/cmd2.py6
2 files changed, 46 insertions, 31 deletions
diff --git a/cmd2/argparse_custom.py b/cmd2/argparse_custom.py
index 342360ae..dbe12d93 100644
--- a/cmd2/argparse_custom.py
+++ b/cmd2/argparse_custom.py
@@ -85,6 +85,47 @@ Tab Completion:
path_filter=lambda path: os.path.isdir(path))
parser.add_argument('-o', '--options', choices_method=completer_method)
+CompletionItem Class:
+ This class was added to help in cases where uninformative data is being tab completed. For instance,
+ tab completing ID numbers isn't very helpful to a user without context. Returning a list of CompletionItems
+ instead of a regular string for completion results will signal the AutoCompleter to output the completion
+ results in a table of completion tokens with descriptions instead of just a table of tokens.
+
+ Instead of this:
+ 1 2 3
+
+ The user sees this:
+ ITEM_ID Item Name
+ 1 My item
+ 2 Another item
+ 3 Yet another item
+
+
+ The left-most column is the actual value being tab completed and its header is that value's name.
+ The right column header is defined using the descriptive_header parameter of add_argument(). The right
+ column values come from the CompletionItem.description value.
+
+ Example:
+ token = 1
+ token_description = "My Item"
+ completion_item = CompletionItem(token, token_description)
+
+ Since descriptive_header and CompletionItem.description are just strings, you can format them in
+ such a way to have multiple columns.
+
+ ITEM_ID Item Name Checked Out Due Date
+ 1 My item True 02/02/2022
+ 2 Another item False
+ 3 Yet another item False
+
+ To use CompletionItems, just return them from your choices or completer functions.
+
+ To avoid printing a ton of information to the screen at once when a user presses tab, there is
+ a maximum threshold for the number of CompletionItems that will be shown. It's value is defined
+ in cmd2.Cmd.max_completion_items. It defaults to 50, but can be changed. If the number of completion
+ suggestions exceeds this number, they will be displayed in the typical columnized format and will
+ not include the description value of the CompletionItems.
+
############################################################################################################
# Patched argparse functions:
###########################################################################################################
@@ -101,6 +142,7 @@ argparse.ArgumentParser._match_argument - adds support to for nargs ranges
import argparse
import re as _re
import sys
+
# noinspection PyUnresolvedReferences,PyProtectedMember
from argparse import ZERO_OR_MORE, ONE_OR_MORE, ArgumentError, _
from typing import Any, Callable, Iterable, List, Optional, Tuple, Union
@@ -129,34 +171,7 @@ class CompletionItem(str):
"""
Completion item with descriptive text attached
- Returning this instead of a regular string for completion results will signal the
- autocompleter to output the completions results in a table of completion tokens
- with descriptions instead of just a table of tokens.
-
- For example, you'd see this:
- TOKEN Description
- MY_TOKEN Info about my token
- SOME_TOKEN Info about some token
- YET_ANOTHER Yet more info
-
- Instead of this:
- TOKEN_ID SOME_TOKEN YET_ANOTHER
-
- This is especially useful if you want to complete ID numbers in a more
- user-friendly manner. For example, you can provide this:
-
- ITEM_ID Item Name
- 1 My item
- 2 Another item
- 3 Yet another item
-
- Instead of this:
- 1 2 3
-
- Example:
- token = 1
- token_description = "My Item"
- completion_item = CompletionItem(token, token_description)
+ See header of this file for more information
"""
def __new__(cls, value: object, *args, **kwargs) -> str:
return super().__new__(cls, value)
diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py
index 14107f5b..ee40d79d 100644
--- a/cmd2/cmd2.py
+++ b/cmd2/cmd2.py
@@ -467,9 +467,9 @@ class Cmd(cmd.Cmd):
# Otherwise it can be set to any custom key to meet your needs.
self.matches_sort_key = ALPHABETICAL_SORT_KEY
- # The maximum number of CompletionItems to display during tab completion. If the number of possible
- # completions exceeds this number, suggestions will be displayed in the typical columnized format and
- # will not include the description value of the CompletionItems.
+ # The maximum number of CompletionItems to display during tab completion. If the number of completion
+ # suggestions exceeds this number, they will be displayed in the typical columnized format and will
+ # not include the description value of the CompletionItems.
self.max_completion_items = 50
############################################################################################################