decade-public/over
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
over/core/app.py

660 lines
25 KiB
Python
Raw Blame History

#! /usr/bin/env python3
# encoding: utf-8
import os
import sys
import re
try:
import xdg.BaseDirectory as xdg_bd
except:
xdg_bd = None
from . import file
from . import text
from ..version import _version
prefix = text.prefix
# FIXME This very seriously needs to be heavily simplified and de-duplicated
# TODO same parser for cmdline and Config
# TODO zsh and fish integration
# --------------------------------------------------
def _parse(data, dtype):
if dtype == 'str':
if data.startswith('"') and data.endswith('"'):
value = data[1:-1].replace('\\"', '"')
elif data.startswith('\'') and data.endswith('\''):
value = data[1:-1].replace('\\\'', '\'')
else:
raise RuntimeError
elif dtype == 'bool':
if data == 'True':
value = True
elif data == 'False':
value = False
else:
raise RuntimeError
elif dtype == 'int':
try:
value = int(data)
except ValueError:
raise RuntimeError
elif dtype == 'float':
try:
value = float(data)
except ValueError:
raise RuntimeError
return value
_over_help_texts = [
('over.core: what, how and huh?', ['over.core is a Python 3 module that provides basic functionality for programs. Functionality such as configuration, commandline parsing, text handling and output, file handling, a non-interactive help system and (not all that much) more.']),
('Data Types', ['over.core currently supports 4 data types.', 'A §bbool§/ is either exactly §mTrue§/ or exactly §mFalse§/. Bool options that are §mTrue§/ look like this: §B--§goption§/. The same name only §mFalse§/ would be §B--no-§goption§/. Makes sense, doesn\'t it? Their short versions are either §B+§go§/ for §mTrue§/ or §B-§go§/ for §mFalse§/.', 'A §bstr§/ing is just any raw text. Remember to enclose it in quotes if it has spaces or other nasty characters in it.', 'An §bint§/eger is a whole number. Negative, zero, positive.', 'Finally, a §bfloat§/ is any real number.']),
('The Commandline Parser', ['This, in conjunction with the configuration system, is the strongest part of over.core and the very reason for its continued existence.', 'Each configurable option can be assigned to on the command line. Take an option named §Bres-file§/ as an example. To assign to it, you can use §B--§gres-file§/ §msomething§/ (it\'s case sensitive). That\'s it, now its value is §msomething§/! Pretty easy, right?', 'Now, you\'re probably thinking: \'I\'m not typing that all over again!\' Well, you don\'t have to! Options can have their short names. It\'s a single letter (again, case sensitive) with a plus or minus sign in front of it. So §B--§gres-file§/ §msomething§/ becomes §B+§gf§/ §msomething§/. That\'s much better, ain\'t it? And there\'s more. Short names can be grouped together. If you have a bunch of bool switches, like §B--§garmed§/ (short: §B+§gA§/), §B--no-§gsound§/ (short: §B-§gS§/), §B--no-§gstore§/ (short: §B-§gs§/) and §B--§gforce§/ (short: §B+§gF§/), you can group their shorts into groups with the same boolean value: §B-§gSs§/ §B+§gAF§/. You can even have a non-bool option in a group, it just has to be on the very right (because it needs to be followed by data): §B-§gSs§/ §B+§gAFf§/ §msomething§/. It doesn\'t matter if that group begins with §B+§/ or §B-§/.', 'If you use an option more than once, its last (rightmost) occurence applies. For example, after §B+§gf§/ §msomething§/ §B+§gf§/ §mor_other§/ is parsed, option §Bres-file§/ holds the value §mor_other§/. It goes the same for bools: after §B+§gA§/ §B--no-§garmed§/ §B+§gA§/, §Barmed§/ is §mTrue§/. However, if an option is §cplural§/, all occurences are used. Sequence §B+§gA§/ §B-§gA§/ §B+§gA§/ would be [§mTrue§/, §mFalse§/, §mTrue§/], and §B--§gnum§/ §m1§/ §B--§gnum§/ §m2§/ would end up looking like [§m1§/, §m2§/]. You don\'t need to type §B--§gnum§/ for every field either: §B--§gnum§/ §m1§/ §m2§/ would work exactly the same. That\'s because the parser keeps reading everything after a plural option (that takes data, i.e. not bools) right until it encounters two dashes, like those of a following option. You can use just the two dashes to stop the parsing manually, usually when you don\'t want to follow with a long option. Example: §B--§gnum§/ §m1§/ §m5§/ §m9§/ §B--§/. I repeat: a plural (non-bool) option needs to be terminated by two dashes. This wouldn\'t work: §B--§gnum§/ §m1§/ §m5§/ §m9§/ §B+§gf§/ §mthat_one§/, everything after §B--§gnum§/ would be consumed as its data, §Bincluding +§gf§/ §mthat_one§/.']),
('The Config File', ['If enabled in the program code, a config file will be generated when you first run it. By default, everything in the config file will be filled with default values and commented out. The general syntax as well as individual options are explained inside. If you run a newer version of the program that offers more configurable options, the config file will be automatically updated. If you\'d like to modify an option in the config file, first uncomment it and then change its value. Resolving order for option values is 1) default (hardcoded), 2) config file and 3) commandline arguments.']),
('Other', ['When enabled in the program, an over.core program offers two options: §B--§ghelp§/ and §B--§gover-help§/. The first describes the program and its options, including their types, current values and whether is their current value coming from defaults, config files or the command line. The second option displays the help you\'re reading right now. You may now guess which rank I hold in the Obvious Corps.', 'As the brighter amongst you might have noticed, over.core likes colors. A lot. Generally, I use blue for §bdata types§/, magenta for §mvalues§/, white and green for §B--§goptions§/ and reserve red and yellow for when §rshit hits§/ §ythe fan§/, where red letters usually tell you §Bwhy§/ and yellow ones tell you §Bwhat§/.', 'And it\'s not just colors! I like money, too. Push donations to §B1sekErApM4zh35RFW7qGWs5Yeo9EYWjyV§/, or catch me somewhere and force me to accept cash.'])
]
# --------------------------------------------------
def _output(raw, indent=0, newlines=1):
sys.stdout.write(text.render(text.paragraph(raw, indent=indent), True))
sys.stdout.write(newlines * '\n')
sys.stdout.flush()
# --------------------------------------------------
def _print_help(main, help_texts, chapter=None, list_options=False):
'''
Displays a help text and then quits the program.
str chapter display only this chapter
bool list_options follow the static printout by a list of options and their current values
'''
# dirty as fuck :-)
if not chapter and not main.version is None:
if help_texts == _over_help_texts:
_output('>>> §yover.core§/ version §y%d§/ (%s), licensed under the §yAO-JSL§/' %_version, newlines=2)
else:
_output('§y%s§/ version §y%s§/, licensed under the §y%s§/' %(main.name, main.version, main.license), newlines=2)
# general help texts
for help_text in help_texts:
_output('[§B%s§/]' %(help_text[0]))
for p in help_text[1]:
_output(p, indent=4, newlines=2)
if list_options:
_output('[§BAvailable Options§/]')
for option in [opt for opt in main.options if not opt.hidden]:
if option.dtype == 'bool' and not option.callback:
long_part = '§B--§g{0}§/ or §B--no-§g{0}§/'.format(option.name)
else:
long_part = '§B--§g%s§/' %(option.name)
if option.short_name:
if option.dtype == 'bool' and not option.callback:
short_part = ' (§B+§g{0}§/ or §B-§g{0}§/)'.format(option.short_name)
else:
short_part = ' (§B+§g%s§/)' %(option.short_name)
else:
short_part = ''
if option.plural:
plural_part = '§cplural§/ '
else:
plural_part = ''
# if option.dtype == 'boolaaa':
# _output('%s%s; §bbool§/' %(long_part, short_part), indent=4)
# else:
_output('%s%s; %s§b%s§/' %(long_part, short_part, plural_part, option.dtype), indent=4)
if option.source == 'cmdline':
src = '§mcmdline§/'
elif option.source == 'config':
src = '§yconfig§/'
else:
src = 'default'
if option.plural:
if option.dtype == 'str':
value = '§c[§/%s§c]§/' %(', '.join('\'§m%s§/\'' %(x) for x in option.value))
else:
value = '§c[§m%s§c]§/' %('§/, §m'.join(str(x) for x in option.value))
else:
if option.dtype == 'str':
value = '\'§m%s§/\'' %(option.value)
else:
value = '§m%s§/' %(option.value)
if not option.callback:
_output('Current value (%s): %s' %(src, value), indent=6)
if not option.use_cfg_file:
_output('§c(ignores config file)§/', indent=6)
_output(option.description, indent=8, newlines=2)
_output('[§BTargets§/]')
if main.targets:
_output('§m%s§/' %('§/, §m'.join(main.targets)), newlines=2, indent=4)
else:
_output('n/a', newlines=2, indent=4)
main.exit(1, True)
_allowed_types = {
'bool': [bool],
'str': [str],
'int': [int],
'float': [int, float]
}
# --------------------------------------------------
def _verify_type(data, dtype, plural=False):
if plural:
if type(data) == list:
for d in data:
v = _verify_type(d, dtype)
if not v:
return False
return True
else:
return False
else:
if type(data) in _allowed_types[dtype]:
return True
else:
return False
# --------------------------------------------------
class CfgAccessor:
'''
Provides convenient access to configuration options' values.
e.g. something = main.cfg.option_name
'''
def __init__(self, main):
self.main = main
def __getattr__(self, opt_name):
matches = [opt for opt in self.main.options if opt.name.replace('-', '_') == opt_name]
if matches:
if len(matches) == 1:
return matches[0].value
else:
self.main.print('game over, lights out! over.core internal buggaroo', prefix.fail)
raise RuntimeError
else:
self.main.print('option §r%s§/ doesn\'t exist' %(opt_name), prefix.fail)
raise RuntimeError
# --------------------------------------------------
class Main:
'''
Application backbone. Provides:
* A configuration system consisting of
* a given set of (hardcoded) default values
* a configuration file that overrides the defaults
* a command line parser that overrides all of the above
* Help system that generates help text based on program's configurable options.
'''
def __init__(self, name, full_name, version=None, license=None, use_cfg_file=False, cmdline=sys.argv[1:]):
'''
str name program name (e.g. 'grid')
str full_name human readable program name (e.g. 'Overwatch Grid')
str version program version
str license program license name
str use_cfg_file if True, a config file at ~/.config/(self.name)/main.cfg will be used
list cmdline command line to parse; defaults to system cmdline (sys.argv)
Initializes over.Main and opens/creates the config file (if desired).
'''
self.cfg = CfgAccessor(self)
self.name = name
self.full_name = full_name
self.version = version
self.license = license
self.cmdline = cmdline
self.help_texts = [] # (chapter, [paragraphs])
self.print = text.Output(self.name + '.main')
if xdg_bd:
xdg_data = xdg_bd.xdg_data_home
xdg_config = xdg_bd.xdg_config_home
else:
xdg_data = os.path.expanduser('~/.local/share')
xdg_config = os.path.expanduser('~/.config')
self.data_dir = os.path.join(xdg_data, self.name)
file.File(os.path.join(self.data_dir, '.keep'))
if use_cfg_file:
self.cfg_file = file.File(os.path.join(xdg_config, self.name, 'main.cfg'), encoding='utf-8')
if not self.cfg_file.data:
self.cfg_file.data = '''# Configuration file for %s
# Licensed under the %s
#
# Syntax
# There are 4 data types: bool, int, float and str (string).
# * Bools are exactly True or False.
# * Ints are negative integers, positive integers and zero.
# * Floats are all real numbers. They don\'t need to have a decimal point.
# * Strings need to be enclosed in double quotes, e.g. 'like this'.
#
# An option is either singular or plural. Plurals are arrays, so they ecpect to be
# in comma-separated lists: ['this', 'is', 'a', 'str', 'example'].
#
# Only lines beginning with a \'#\' are treated as comments.
''' %(self.name, self.license)
self.print('creating configuration file §B%s§/' %(self.cfg_file.path), prefix.start)
else:
self.cfg_file = None
# cmdline parser and config
self.options = [] # Option objects
self.targets = [] # target words directly from the command line
self.unknowns = [] # parser couldn't figure out how to chew these
self.help_texts = [] # (chapter, [paragraphs]) tuples
def __repr__(self):
return 'over.Main(name=%s)' %(self.name)
def exit(self, retval=0, silent=True):
'''
int retval return value
bool silent don't mention it
Shutdown the program and exit.
'''
if not silent:
self.print('exiting with §B%d§/' %(retval), prefix.info)
sys.exit(retval)
def dump(self, ignore=[]):
'''
return current configuration in Et Commandline format
'''
out = []
for option in [option for option in self.options if option.name not in ignore]:
if option.type == 'bool':
if option.plural:
for value in option.value:
if value:
out.append('--%s' %(option.name))
else:
out.append('--no-%s' %(option.name))
elif option.value is not None:
if option.value:
out.append('--%s' %(option.name))
else:
out.append('--no-%s' %(option.name))
else:
if option.plural:
out.append('--%s' %(option.name))
for value in option.value:
if option.type == 'str':
value = "'%s'" %(value.replace("'", r"\'"))
out.append(str(value))
out.append('--')
elif option.value is not None:
out.append('--%s' %(option.name))
if option.type == 'str':
option.value = "'%s'" %(option.value.replace("'", r"\'"))
out.append(str(option.value))
return out
def reset_to_default(self):
'''
Resets internal state to builtin defaults (i.e. as it is before self.parse() is called).
'''
self.targets = []
self.unknowns = []
for option in self.options:
option.source = 'default'
option.value = option.default
def add_option(self, name, dtype, default, description, short_name=None, plural=False, callback=None, use_cfg_file=True, hidden=False):
'''
str name Name of the option. See #0
str dtype Option's data type. See #1
str default Option's default value. See #2
str description Option's description (displayed in --help).
str short_name Option's short name. See #3
bool plural True to make the option plural.
bool use_cfg_file True to use the config file for this option.
fn callback Register a callback for this option. See #4
bool hidden hide the option from --help
Add an option to the configuration system.
#0 Option naming
Each option has a name. This name is directly used on the command line prefixed by two dashes.
For example option 'warp-speed' would be called like so: --warp-speed.
Bools take two appearances: --warp-speed is True, while --no-warp-speed is False.
Their values can be accessed from the program as main.cfg.option_name. Options with dashes
in their names (an operator in python) can be accessed as well, just substitute dashes
for underscores. Option --warp-speed would be available under main.cfg.warp_speed.
#1 Data types.
There are four data types.
* 'bool' - either exactly True or False.
* 'str' - a raw text string, nothing special going on here
* 'int' - an integer
* 'float' - a float
#2 Default values
These are the values the option will take if it's not called on the command line or
in the config file. Defaults need to have the proper data type, of course, and for
plural options they have to be lists.
#3 Short names
Options can have a short, single letter alias. These are prefixed by a single dash on the command
line and don't appear in the config file at all. Again, booleans take special treatment: -a is False,
while +a is True.
Short names can be grouped: -a -b becomes -ab (both are False), or +a +b becomes +ab (both will be True).
If an option requires a parameter (e.g. -f filename), it can still be grouped, it just has to be the
rightmost option in the group. Whether the group starts with a + or a - doesn't matter.
E.g. -af filename is the same as -a -f filename and +af filename is the same as +a -f filename.
#4 Callbacks
An option with a callback will invoke it if it appears on the command line (both +a and -a). This is
usually done for options like --help (internally), --list-modules, --show-something and similar.
The callback will be passed one argument: the main instance.
'''
for option in self.options:
if name == option.name:
self.print('option §B--§r%s§/ already exists' %(name), prefix.fail)
raise RuntimeError
if option.short_name and short_name == option.short_name:
self.print('option §B--§r%s§/\'s short name §r%s§/ is already taken by §B--§y%s§/' %(name, short_name, option.name), prefix.fail)
raise RuntimeError
if short_name and len(short_name) > 1:
self.print('short name must be a single character; option §B--§r%s§/ has §r%s§/'%(name, short_name), prefix.fail)
raise RuntimeError
if callback:
use_cfg_file = False
if dtype not in ['bool', 'str', 'int', 'float']:
self.print('option §B--§r%s§/\'s dtype is not of a supported type' %(name), prefix.fail)
raise RuntimeError
v = _verify_type(default, dtype, plural)
if not v:
if plural:
type_desc = 'a list of §m%s§rs' %(dtype)
else:
if dtype == 'int':
type_desc = 'an int'
else:
type_desc = 'a %s' %(dtype)
self.print('option §B--§r%s§/\'s default must be §y%s§/' %(name, type_desc), prefix.fail)
raise RuntimeError
o = Option(name, dtype, default, description, short_name, plural, use_cfg_file, callback, hidden)
self.options.append(o)
def parse(self, cmdline=None, reset_to_default=False):
'''
Parses the cfg file and the command line and sets the internal cfg state accordingly.
'''
ptr = 0
parsing_plural = False
unparsed = []
callbacks = []
if reset_to_default:
self.reset_to_default()
if cmdline is None:
cmdline = self.cmdline
while ptr < len(cmdline):
to_parse = []
word = cmdline[ptr]
if len(word) > 2 and word[0:2] == '--':
to_parse.append(word)
elif len(word) >= 2 and (word[0] == '+' or (word[0] == '-' and word[1] != '-')):
# expand and then parse
for s in word[1:]:
option = [opt for opt in self.options if opt.short_name == s]
if option:
if word[0] == '+' or option[0].dtype != 'bool':
to_parse.append('--{0.name}'.format(option[0]))
else:
to_parse.append('--no-{0.name}'.format(option[0]))
else:
self.unknowns.append(word[0] + s)
else:
unparsed.append(word)
ptr += 1
if to_parse:
for w in to_parse:
if w.startswith('--no-'):
bool_on = False
name = w[5:]
else:
bool_on = True
name = w[2:]
option = [opt for opt in self.options if opt.name == name]
if option:
o = option[0]
if o.callback:
callbacks.append(o.callback)
if o.plural and o.source != 'cmdline':
o.value = []
if o.dtype == 'bool':
o.source = 'cmdline'
if o.plural:
o.value.append(bool_on)
else:
o.value = bool_on
else:
if not bool_on:
self.print('§B--no-§r%s§/ makes no sense because this option is of type §y%s§/' %(name, o.dtype), prefix.fail)
raise RuntimeError
# This option takes arguments. These are all words at ptr and higher that don't begin with '--'.
# If this option is part of a shortgroup it must be at its end.
if to_parse.index(w) + 1 != len(to_parse):
self.print('option §B{0[0]}§r{1.short_name}§/ needs to be at the end of group §y{0}§/'.format(word, o), prefix.fail)
raise RuntimeError
got_something = False
# NOTE it shouldn't be hard to implement specific plurality (how many words to chew)
# NOTE REPLY: I'm still not doing it.
while ptr < len(cmdline) and not cmdline[ptr].startswith('--'):
arg = cmdline[ptr]
ptr += 1
if o.dtype == 'int':
try:
arg = int(arg)
except ValueError:
self.print('argument §r%s§/ passed to integer option §B--§y%s§/' %(arg, o.name), prefix.fail, exc=ValueError)
elif o.dtype == 'float':
try:
arg = float(arg)
except ValueError:
self.print('argument §r%s§/ passed to float option §B--§y%s§/' %(arg, o.name), prefix.fail, exc=ValueError)
got_something = True
o.source = 'cmdline'
if o.plural:
o.value.append(arg)
else:
o.value = arg
break
#if not got_something:
# self.print('option §B--§r%s§/ needs at least one argument' %(o.name), prefix.fail, exc=GeneralError)
else:
self.unknowns.append(w)
self.targets = [u for u in unparsed if u != '--']
if self.unknowns:
self.print('unknown options on the command line: §r%s§/' %('§/, §r'.join(self.unknowns)), prefix.fail)
raise RuntimeError
# parse the config file
if self.cfg_file:
new_lines = []
for opt in [o for o in self.options if o.use_cfg_file]:
match = re.findall('^(#?)\s*%s\s*=\s*(.+)' %(opt.name), self.cfg_file.data, re.M)
if match:
if opt.source == 'default':
if not match[0][0]: # if it isn't commented out
d = match[0][1]
opt.source = 'config'
if opt.plural:
opt.value = []
if opt.dtype != 'str':
elements = [x.strip() for x in d[1:-1].split(',')]
else:
d = re.sub('\',\s*\'', '\',\'', d) # remove spaces
d = d[1:-1].strip()[1:-1] # remove [] and outermost ''
elements = ['\'%s\'' %(x) for x in d.split('\',\'')] # split and re-pack them with ''
for element in elements:
try:
opt.value.append(_parse(element, opt.dtype))
except RuntimeError:
self.print('config file syntax error for option §B--§r%s§/' %(opt.name), prefix.fail)
raise
else:
try:
opt.value = _parse(d, opt.dtype)
except RuntimeError:
self.print('config file syntax error for option §B--§r%s§/' %(opt.name), prefix.fail)
raise
else:
self.print('updating config file with option §B--§y%s§/' %(opt.name))
new_lines.append('')
new_lines.append(text.paragraph(text.render(opt.description, colors=False), prefix='#', width=80))
new_lines.append('# *** data type: %s' %(opt.dtype))
if opt.plural:
new_lines.append('# *** plural option')
tmp = []
for v in opt.default:
if opt.dtype == 'str':
tmp.append('\'%s\'' %(v))
else:
tmp.append(str(v))
str_value = '[%s]' %(', '.join(tmp))
else:
if opt.dtype == 'str' and opt.default is not None:
str_value = '\'%s\'' %(opt.default)
else:
str_value = str(opt.default)
new_lines.append('#%s = %s\n' %(opt.name, str_value))
self.cfg_file.data += '\n'.join(new_lines)
# handle callbacks
for callback in callbacks:
callback(self)
def enable_help(self, short_name=None):
'''
Enable --help, --over-help and --help-over. If a short name is provided, it will be used for --help.
'''
self.add_option('help', 'bool', False, 'Display this help message.', callback=self.help, short_name=short_name, use_cfg_file=False)
self.add_option('over-help', 'bool', False, 'Display general usage information for over.core.', callback=self.help_over, use_cfg_file=False)
self.add_option('help-over', 'bool', False, 'Display general usage information for over.core.', callback=self.help_over, use_cfg_file=False, hidden=True)
def add_help(self, chapter, paragraphs):
self.help_texts.append((chapter, paragraphs))
def help(self, *dummy):
_print_help(self, self.help_texts, list_options=True)
def help_over(self, *dummy):
_print_help(self, _over_help_texts)
# --------------------------------------------------
class Option:
def __init__(self, name, dtype, default, description, short_name, plural, use_cfg_file, callback, hidden):
'''
Just a container. Move along...
'''
self.name = name
self.dtype = dtype # bool, int, str, float
self.default = default
self.description = description
self.short_name = short_name
self.plural = plural
self.use_cfg_file = use_cfg_file
self.callback = callback
self.hidden = hidden
self.source = 'default'
self.value = default
Reference in a new issue View git blame Copy permalink