diff options
author | Kevin Van Brunt <kmvanbrunt@gmail.com> | 2019-07-11 15:16:38 -0400 |
---|---|---|
committer | Kevin Van Brunt <kmvanbrunt@gmail.com> | 2019-07-11 15:16:38 -0400 |
commit | c1312cadba42f273179a6bc08ec5a8d22ca23891 (patch) | |
tree | 42a8d0ee8cf37f605c5db5e020794a88a8f67e1d | |
parent | eb5b4fff8b1042d6a5b30a768bf35496acc4c593 (diff) | |
download | cmd2-git-c1312cadba42f273179a6bc08ec5a8d22ca23891.tar.gz |
Updated documentation
-rw-r--r-- | cmd2/argparse_custom.py | 71 | ||||
-rw-r--r-- | cmd2/cmd2.py | 6 |
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 ############################################################################################################ |