cpick 0.0.7

Curses List Picker

CURSES LIST PICKER

Pick items from a list with a nice TUI, & comfy Vi keybindings.

INSTALLATION

pip install cpick

CLI USAGE

USAGE: cpick:

[-h]        [--help]
[-l LIMIT]  [--limit LIMIT]
[-n]        [--numbers]
[-H HEADER] [--header HEADER]
[-F FOOTER] [--footer FOOTER]
[ITEMS]     [items ...]

Curses List Picker.

Positional Arguments:
  [ITEMS]                : Items for the picker.

Optional Arguments:
  -h, --help             : Show this help message and exit.
  -l, --limit [LIMIT]    : Limit number of picks.
  -n, --numbers          : Show line numbers.
  -H, --header [HEADER]  : A string to use as a header.
  -F, --footer [FOOTER]  : A string to use as a footer.

PYTHON USAGE

Example using all available arguments

import cpick

# keyword argument dictionary
kwargs = {
	# list to feed into the picker
	'items': ['a', 'list', 'of', 'items'],
	# only allow five items to be picked, defaults to sys.maxsize
	'limit': 5,
	# turn line numbering on
	'numbers': True,
	# defaults to 'PICK ITEMS FROM THIS LIST'
	'header': 'My Awesome Custom Header',
	# defaults to 'Press [?] to view keybindings'
	'footer': 'My Awesome Custom Footer',
}

# splat args using ** to unpack kwargs dictionary
picked = cpick.pick(**kwargs)

# print picked list
print(*picked, sep=", ")
# output if all items picked: a, list, of, items

Example using only a list

# pass in only mandatory arg - a list.
picked = cpick.pick(items=['just', 'a', 'list'])
print(*picked, sep=", ")
# output if all items picked: just, a, list

KEYBINDINGS

KEY	ACTION
k,UP	Move up one line
j,DOWN	Move down one line
g,HOME	Jump to first line
G,END	Jump to last line
f,PGDN	Jump down a page of lines
b,PGUP	Jump up a page of lines
#	Jump to line number
/	Find items via wildcards, regex or range
n	Jump to next search result
p	Jump to previous search result
CTRL-n	Jump to next pick
CTRL-p	Jump to previous pick
r,F5	Reset search results and picks
z,CTRL-l	Recenter current line on screen
RET	Pick an item
;	Pick via wildcards, regex or range
u	Undo the last pick
U	Undo the last pick and move to it's line
t	Toggle an item
SPC	Toggle item and go down a line
CTRL-SPC	Toggle item and go up a line
a	Toggle all items
:	Toggle via wildcards, regex or range
v	View picked items
?,F1	View this help page
w,CTRL-s	Save picks to a file
q,ESC	Quit and display all marked paths

NOTES

Picking[;], toggling [:], and searching[/] is supported via the following methods:

• Unix Style Wildcards.

• Regular Expressions.

• Matching a complete string (ie. not substrings - use wildcards for this.)

• Specifying the line number of an item.

• Specifying a range of line numbers in the following forms:

  PROMPT	ACTION
  x..y	Match line numbers between x and y
  x-y	Match line numbers between x and y
  x..	Match line numbers from x until the end of the list
  ..y	Match line numbers from beginning of list until y
  x-	Match line numbers from x until the end of the list
  -y	Match line numbers from beginning of list until y

These can also be combined. You can enter multiple patterns, ranges and strings at one Pick:, Toggle: or Find: prompt.

However, be aware, that when toggling - if patterns, ranges or strings are entered that match the same items, they will cancel each other out.

For example, if you entered 1..10 ^[A-Z][a-z]+$ on a list where the first 10 items were capitalised words, nothing would be picked.

The 1..10 would pick the first ten items, and then the ^[A-Z][a-z]+$ would unpick them, since they call the toggle method consecutively.

If you do not want this (you probably don't..) - use the Pick: prompt instead.

EXAMPLES

Pick a number from 1 to 100, using custom header/footer and limiting picks to 5.

cpick --header "My header" --footer "My footer" --limit 5 {1..100}

Pick 5 random words from the dictionary, using the default header/footer.

cpick --limit 5 $(shuf -n 100 /usr/share/dict/words)

Pick an unlimited number of paths from the current directory.

cpick $(ls)