68 lines
4.2 KiB
Python
68 lines
4.2 KiB
Python
#! /usr/bin/env python3
|
|
# encoding: utf-8
|
|
|
|
from collections import OrderedDict
|
|
from .text import ansi_colors
|
|
|
|
over_docs = OrderedDict()
|
|
over_docs["What"] = ["<G>over<.> is a Python 3 library that attempts to provide essential and convenient application functionality. Configuration, command line parsing, text handling and output, a non-interactive help system, human-readable exception processing, subprocess execution and many more are available."]
|
|
over_docs["Why"] = ["It started with a need for a more powerful command line interface than what <c>argparse<.> can provide. Things snowballed on and several generations later..."]
|
|
over_docs["Options"] = [
|
|
"At the core of over is the command line parser (<c>over<.>.<c>app<.>.<c>Main<.>.<y>parse_command_line<.>). There are 6 basic design principles:",
|
|
'Options accept one or more words as arguments, e.g. <W>--<g>tag<.> <M>ARTIST "Within Temptation"<.> accepts two, <W>--<g>age<.> <M>31<.> accepts one.',
|
|
"Boolean options can accept 0 words - then they become flags (switches) and are toggled directly by their names: <W>--<g>enabled<.> evaluates to <M>True<.>, <R>--no-<g>enabled<.> to <M>False<.>.",
|
|
"Other flags (options that accept 0 words) directly trigger callbacks. Those are usually referred to as actions. A good example is <W>--<g>help<.>.",
|
|
"Options can be referred to by their abbreviated, single character names, if defined by the application. Abbreviated names are interchangeable with full names. Boolean flags get shortened from <W>--<g>enabled<.> to <W>+<G>E<.>, and <R>--no-<g>enabled<.> to <R>-<G>E<.>.",
|
|
"Multiple abbreviated options can be grouped together, with one condition: all except the last (rightmost) option must be flags or actions. For example <R>-<G>Exp<.> <M>primary<.> is the same as <R>--no-<g>enabled<.> <R>--no-<g>execute<.> <W>--<g>pool<.> <M>primary<.>, or <W>+<G>Nv<.> <M>drop<.> expands to <W>--<g>normalize<.> <W>--<g>video<.> <M>drop<.>. Notice how the entire group takes on the boolean value of the leading <W>+<.> or <R>-<.>.",
|
|
'If an option is overwriting (<c>over<.>.<c>app<.>.<c>Option<.>.<y>overwrite<.> = <M>True<.>) the latest (rightmost) instance of the same option overwrites all previous ones. Otherwise, all instances are used. For example, <W>+<G>v<.> <M>drop<.> <W>+<G>v<.> <M>copy<.> <W>+<G>v<.> <M>x264<.> evaluates to <M>["x264"]<.> if the option is defined as overwriting, whereas if it was not it would evaluate to <M>["drop", "copy", "x264"]<.>.'
|
|
]
|
|
over_docs["Configuration sources"] = ["Each option can take its state either from (in order) the application default value, the config file, or the command line. Combining multiple sources (e.g. extending values in the config file with the command line) is not permitted - a new source always resets the option's state. It is possible for an option to have no value."]
|
|
over_docs["Config File"] = ["If enabled by the application, a config file will be generated when first executed. The config file will be populated with all known options, their descriptions and some instructions on how to proceed. If a newer version of the application that offers more configurable options is executed, the config file will be automatically updated."]
|
|
|
|
colors = []
|
|
|
|
for code, (_, name) in ansi_colors.items():
|
|
c = "<<%s> = <%s>%s<.>" %(code, code, name)
|
|
|
|
if code == "k":
|
|
c += ' (this one says "black")'
|
|
|
|
colors.append(c)
|
|
|
|
over_docs["Available Colors"] = [", ".join(colors)]
|
|
|
|
config_file_header = """# Configuration file for %s-%s
|
|
# Generated by over-%s
|
|
#
|
|
# There are three types of lines:
|
|
# - an empty line (contains no non-whitespace characters)
|
|
# - a comment (the first non-whitespace character is a #)
|
|
# - an assignment (option-name = option-value)
|
|
#
|
|
# Option names are the literal names used in app setup.
|
|
#
|
|
# Option values are the same as on the command line, no
|
|
# quoting or escaping is needed unless required for
|
|
# multi-argument options with spaces in values.
|
|
#
|
|
# Non-overwriting options (overwrite = False) work as
|
|
# expected as well, simply specify the option more than
|
|
# once.
|
|
#
|
|
# Examples:
|
|
# TODO :)
|
|
|
|
"""
|
|
|
|
config_file_item = """# --------------------------------------------------
|
|
# ---- %s ----
|
|
# Option %s
|
|
# callback: %s
|
|
# takes %s argument%s
|
|
# %s
|
|
#
|
|
%s
|
|
#
|
|
%s%s = %s
|
|
|
|
"""
|