def __init__(self,
                 parameters=None,
                 version=None,
                 install_dir=None,
                 argv=None,
                 launch=True,
                 # Most of the rest of the args are highly situational.
                 # Consider calling with **get_metainfo(__file__) instead. 
                 progname=None,
                 author=None,
                 title='%(progname)s v%(version)s by %(author)s.',
                 description=None,
                 contact=None,
                 website=None,
                 download=None,
                 git=None,
                 subversion=None,
                 license=None,
                 copyright=None,
                 command=None,
                 usage=None,
                 general=None,
                 additional=None,
                 note=None,
                 filedocs=None,
                 docsfiles=None,
                 docsfilenames=None,
                 width=None,
                 configfiles=None,
                 configdirs=None,
                 configfilenames=None,
                 sections=None,
                 ignore=None,
                 helpoption=help_option,
                 longhelpoption=longhelp_option,
                 versionoption=version_option,
                 settingsoption=settings_option):
        """
        Many of the metainfo parameters (author, progname...) should already
        be present in the program docstring if you're coding by the book. You 
        can avoid repeating them by doing something like: 
        ui = tui(..., **get_metainfo(__file__)).
        The parameters that will be available using the above incantation are
        marked with asterixes* below.
        
        .readdocs() can read most user documentaion from external docsfiles, 
        so there is typically no need to supply that on instantiation. See the
        docsfile parameter. Parameters that can be set using .readdocs() are 
        marked with percent% below.
        
        All parameters that take a list of indented paragraphs can use docvars.
        They also accept just a string which, is then taken as a list of one 
        paragraph. None means there is no such documentation.
        
        All parameters that take an Option also accept factory functions for
        Option objects (like a class, or a function like help_option). None
        means don't add such an option. Note however that just adding the 
        helpoption, longhelpoption, versionoption and settingsoption at 
        instantiation will not activate their documented functionality. Use 
        e.g. .start() for this.
        
        parameters is a list of Options and PositionalArguments to be added
        to the user interface.
        
        version* is the current program version string. Although you *can* set
        this using get_metainfo, you typically want to pass __version__ here
        instead. Available as a docvar.

        install_dir (if given) will be searched for configfiles and docsfiles.
        Use containing dir if given a python package or a path to a file (e.g. 
        mypackage or __file__).
        
        argv is the list of command line arguments to use (see launch just 
        below). None means use a copy of sys.argv.

        If launch is True (default) then .launch(argv) will be called after 
        initiallization.
         
        *progname is the user friendly name of the program. Available as a 
        docvar. 
        
        *author is who made the program. Available as a docvar. 
        
        title is what to put in the title line on help pages. Can use docvars.

        *%description is a oneliner describing the program. Can use docvars.
        
        *%contact is contact information as a list of indented paragraphs.

        *%website is the url to the website of the program. Can be given as a
        list of indented paragraphs if needed.

        *%download is where the program can be downloaded. Can be given as a
        list of indented paragraphs if needed.
        
        *%git is where the source can be accessed by git. Can be given as a
        list of indented paragraphs if needed.
        
        *%subversion is where the source can be accessed by svn. Can be given 
        as a list of indented paragraphs if needed.
        
        *%copyright is copyright information as a list of indented paragraphs. 
        
        *%license is brief information on the licensing conditions of the 
        program. Can be given as a list of indented paragraphs if needed.

        *command* is how to execute the program. Available as a docvar. None 
        means use the basename of sys.argv[0].
        
        usage is user friendly help on how to execute the program. Can 
        use docvars. None means auto generate from options and positional 
        arguments.
        
        %general is general program documentation as a list of indented
        paragraphs. Typically displayed on the normal help page. 

        %additional is additional program documentation as a list of indented
        paragraphs. Typically only displayed in verbose help (longhelp). 

        %note is the same as additional, only with a different label.

        %filedocs is documentation on files used by the program, as a dict of
        file names and indented paragraphs. Typically only displayed in 
        verbose help (longhelp). Keys and values may use docvars. None means 
        no such documentation.
        
        docsfilenames is a list of basenames of docsfiles and is only useful 
        together with install_dir. A str means a list of one item. None means 
        [basename(install_dir) + 'docs' (if given), command + '.docs']. 
        Do not use together with the docsfiles parameter.

        docsfiles is a list of paths to potential DocParser docsfiles; parse if
        present, in the given order. None means look for each docsfilename in
        install_dir (if given). A str means a list of one item. Note that no 
        docs will be read on instantation. Use .readdocs() (or .launch()) for 
        that.
        
        width is the maximum allowed width for help text. 0 means try to guess
        the terminal width, and use 79 if that fails.
        
        configdirs is a list of paths to directories to search for configfiles.
        None means [install_dir (if given), '/etc/' + command, '~/.' + command].
        A str means the same, but with this string replacing command. Do not 
        use together with the configfiles parameter.
        
        configfilenames is a list of basenames of configfiles. A str means a 
        list of one item. None means [command + '.conf']. Do not use together 
        with the configfiles parameter.
        
        configfiles is a list of config files to parse. None means try each 
        configfilename in the given order, in each of the configdirs in the 
        given order. configfiles are parsed incrementally by .parsefiles() (or
        .launch()). A str means a list of one item. [] means no configfiles.
        
        sections is a list of sections to read in config files. A str means a 
        list of one item. None means [command]. The DEFAULT section (note 
        uppercase) is always read, and it is read as if its contents were 
        copied to the beginning of all other sections.
        
        ignore is a list of option and positional argument names that should be
        ignored if encountered in configfiles or docsfiles. Any other unknown 
        names will raise an error. This is primarily to help users catch 
        spelling mistakes. This feature is useful for example if you are using
        the same files for several programs in a suite, where some parameters 
        are shared and you want to ignore the others. Set to None to ignore all
        all unknown (not recommended). 
        
        options can be used to supply a preconfigured option dictionary, if you
        for some reason prefer this to .makeoption(). tui will not check this 
        for you. See also option_order and abbreviations.
        
        option_order determines the order in which the options will be shown in
        help texts.
        
        abbreviations is a abbreviation:option dict, similar to options.
        
        positional_args can be used to supply a list of preconfigured positional
        arguments, if you for some reason prefer this to .makeposarg(). tui will 
        not check this for you. See also positional_arg_names.
        
        positional_arg_names are the display names for positional arguments in
        help texts.
        
        helpoption adds an option that lets the user request help in the usual
        way. Default is '--help' or '-h', option reserved for command line use.
        None means don't add such an option.
        
        longhelpoption adds an option that lets the user request verbose help.
        Default is '--HELP' or '-H', option reserved for command line use. None
        means don't add such an option. 

        versionoption adds an option that lets the user print the version 
        string. Default is '--version' or '-V', option reserved for command
        line use). None means don't add such an option.

        settingsoption adds an option that lets the user print a brief summary
        of program settings. Default is '--settings' or '-S', option reserved 
        for command line use). None means don't add such an option.
        """
        params = locals()
        self.options = dict()
        self.option_order = []
        self.abbreviations = dict()
        self.positional_args = []
        for p in parameters:
            if isinstance(p, Option):
                self._add_option(p)
            elif isinstance(p, PositionalArgument):
                self._add_positional_argument(p)
            else:
                raise TypeError('unknown parameter type')
        self.basic_option_names = dict()
        for optiontype in ['help', 'longhelp', 'settings', 'version']:
            option = params[optiontype + 'option']
            if not option:
                continue
            if not isinstance(option, Option):
                option = option()
            self._add_option(option)
            self.basic_option_names[optiontype] = option.name

        # Did the user give a module/package rather than a path? 
        if isinstance(install_dir, type(sys)):
            install_dir = install_dir.__file__
        if isinstance(install_dir, basestring) and os.path.isfile(install_dir):
            install_dir = os.path.dirname(install_dir)
        
        self.docvars = dict((s, params[s]) for s in ['author', 'progname', 'version'])
        if command is None:
            command = os.path.basename(sys.argv[0])
        self.docvars['command'] = command
        command_base = command
        if command.endswith('.py'):
            command_base = command[:-3]
        
        self.docs = dict(title=_docs(title, self.docvars),
                         usage=_docs(usage, self.docvars),
                         files=_docs(filedocs, self.docvars))
        if filedocs is None:
            filedocs = dict()
        self.docs['files'] = filedocs
        self.docs.update((name, _list(params[name])) for name in ['additional', 'contact', 'copyright', 'description', 'download', 'general', 'git', 'license', 'subversion', 'website'])
        self.ignore = _list(ignore)
        if docsfiles is None:
            if install_dir:
                if docsfilenames is None:
                    docsfilenames = [os.path.basename(install_dir) + '.docs']
                    if command_base:
                        docsfilenames.append(command_base + '.docs')
                docsfiles = [os.path.join(install_dir, f) for f in docsfilenames]
        elif docsfilenames:
            raise ValueError('do not use docsfilenames together with docsfiles')
        self.read_docs(docsfiles)
        
        self.sections = _list(sections, [command_base])
        if configfiles is None:
            dirname = command_base
            if isinstance(configdirs, basestring):
                dirname = configdirs
                configdirs = None
            if configdirs is None:
                configdirs = []
                if install_dir is not None:
                    configdirs.append(install_dir)
                configdirs += [os.path.join('/etc', dirname), 
                               os.path.expanduser(os.path.join('~', '.' + dirname))]
            configfilenames = _list(configfilenames, [command_base + '.conf'])
            configfiles = [os.path.join(d, f) for d in configdirs for f in configfilenames]
        elif configdirs or configfilenames:
            raise ValueError('do not use configfiles together with configdirs and configfilenames')
        elif isinstance(configfiles, basestring):
            configfiles = [configfiles]
        self.configfiles = configfiles
        if self.configfiles:
            self.addconfigfiledocs()
        
        if not width:
            width = get_terminal_size()[0]
        self.width = width
        
        if launch:
            self.launch(argv)
def __init__ ( self , parameters = None , version = None , install_dir = None , argv = None , launch = True , progname = None , author = None , title = '%(progname)s v%(version)s by %(author)s.' , description = None , contact = None , website = None , download = None , git = None , subversion = None , license = None , copyright = None , command = None , usage = None , general = None , additional = None , note = None , filedocs = None , docsfiles = None , docsfilenames = None , width = None , configfiles = None , configdirs = None , configfilenames = None , sections = None , ignore = None , helpoption = help_option , longhelpoption = longhelp_option , versionoption = version_option , settingsoption = settings_option ) : params = locals ( ) self . options = dict ( ) self . option_order = [ ] self . abbreviations = dict ( ) self . positional_args = [ ] for p in parameters : if isinstance ( p , Option ) : self . _add_option ( p ) elif isinstance ( p , PositionalArgument ) : self . _add_positional_argument ( p ) else : raise TypeError ( 'unknown parameter type' ) self . basic_option_names = dict ( ) for optiontype in [ 'help' , 'longhelp' , 'settings' , 'version' ] : option = params [ optiontype + 'option' ] if not option : continue if not isinstance ( option , Option ) : option = option ( ) self . _add_option ( option ) self . basic_option_names [ optiontype ] = option . name if isinstance ( install_dir , type ( sys ) ) : install_dir = install_dir . __file__ if isinstance ( install_dir , basestring ) and os . path . isfile ( install_dir ) : install_dir = os . path . dirname ( install_dir ) self . docvars = dict ( ( s , params [ s ] ) for s in [ 'author' , 'progname' , 'version' ] ) if command is None : command = os . path . basename ( sys . argv [ 0 ] ) self . docvars [ 'command' ] = command command_base = command if command . endswith ( '.py' ) : command_base = command [ : - 3 ] self . docs = dict ( title = _docs ( title , self . docvars ) , usage = _docs ( usage , self . docvars ) , files = _docs ( filedocs , self . docvars ) ) if filedocs is None : filedocs = dict ( ) self . docs [ 'files' ] = filedocs self . docs . update ( ( name , _list ( params [ name ] ) ) for name in [ 'additional' , 'contact' , 'copyright' , 'description' , 'download' , 'general' , 'git' , 'license' , 'subversion' , 'website' ] ) self . ignore = _list ( ignore ) if docsfiles is None : if install_dir : if docsfilenames is None : docsfilenames = [ os . path . basename ( install_dir ) + '.docs' ] if command_base : docsfilenames . append ( command_base + '.docs' ) docsfiles = [ os . path . join ( install_dir , f ) for f in docsfilenames ] elif docsfilenames : raise ValueError ( 'do not use docsfilenames together with docsfiles' ) self . read_docs ( docsfiles ) self . sections = _list ( sections , [ command_base ] ) if configfiles is None : dirname = command_base if isinstance ( configdirs , basestring ) : dirname = configdirs configdirs = None if configdirs is None : configdirs = [ ] if install_dir is not None : configdirs . append ( install_dir ) configdirs += [ os . path . join ( '/etc' , dirname ) , os . path . expanduser ( os . path . join ( '~' , '.' + dirname ) ) ] configfilenames = _list ( configfilenames , [ command_base + '.conf' ] ) configfiles = [ os . path . join ( d , f ) for d in configdirs for f in configfilenames ] elif configdirs or configfilenames : raise ValueError ( 'do not use configfiles together with configdirs and configfilenames' ) elif isinstance ( configfiles , basestring ) : configfiles = [ configfiles ] self . configfiles = configfiles if self . configfiles : self . addconfigfiledocs ( ) if not width : width = get_terminal_size ( ) [ 0 ] self . width = width if launch : self . launch ( argv )
Many of the metainfo parameters (author, progname...) should already
        be present in the program docstring if you're coding by the book. You 
        can avoid repeating them by doing something like: 
        ui = tui(..., **get_metainfo(__file__)).
        The parameters that will be available using the above incantation are
        marked with asterixes* below.
        
        .readdocs() can read most user documentaion from external docsfiles, 
        so there is typically no need to supply that on instantiation. See the
        docsfile parameter. Parameters that can be set using .readdocs() are 
        marked with percent% below.
        
        All parameters that take a list of indented paragraphs can use docvars.
        They also accept just a string which, is then taken as a list of one 
        paragraph. None means there is no such documentation.
        
        All parameters that take an Option also accept factory functions for
        Option objects (like a class, or a function like help_option). None
        means don't add such an option. Note however that just adding the 
        helpoption, longhelpoption, versionoption and settingsoption at 
        instantiation will not activate their documented functionality. Use 
        e.g. .start() for this.
        
        parameters is a list of Options and PositionalArguments to be added
        to the user interface.
        
        version* is the current program version string. Although you *can* set
        this using get_metainfo, you typically want to pass __version__ here
        instead. Available as a docvar.

        install_dir (if given) will be searched for configfiles and docsfiles.
        Use containing dir if given a python package or a path to a file (e.g. 
        mypackage or __file__).
        
        argv is the list of command line arguments to use (see launch just 
        below). None means use a copy of sys.argv.

        If launch is True (default) then .launch(argv) will be called after 
        initiallization.
         
        *progname is the user friendly name of the program. Available as a 
        docvar. 
        
        *author is who made the program. Available as a docvar. 
        
        title is what to put in the title line on help pages. Can use docvars.

        *%description is a oneliner describing the program. Can use docvars.
        
        *%contact is contact information as a list of indented paragraphs.

        *%website is the url to the website of the program. Can be given as a
        list of indented paragraphs if needed.

        *%download is where the program can be downloaded. Can be given as a
        list of indented paragraphs if needed.
        
        *%git is where the source can be accessed by git. Can be given as a
        list of indented paragraphs if needed.
        
        *%subversion is where the source can be accessed by svn. Can be given 
        as a list of indented paragraphs if needed.
        
        *%copyright is copyright information as a list of indented paragraphs. 
        
        *%license is brief information on the licensing conditions of the 
        program. Can be given as a list of indented paragraphs if needed.

        *command* is how to execute the program. Available as a docvar. None 
        means use the basename of sys.argv[0].
        
        usage is user friendly help on how to execute the program. Can 
        use docvars. None means auto generate from options and positional 
        arguments.
        
        %general is general program documentation as a list of indented
        paragraphs. Typically displayed on the normal help page. 

        %additional is additional program documentation as a list of indented
        paragraphs. Typically only displayed in verbose help (longhelp). 

        %note is the same as additional, only with a different label.

        %filedocs is documentation on files used by the program, as a dict of
        file names and indented paragraphs. Typically only displayed in 
        verbose help (longhelp). Keys and values may use docvars. None means 
        no such documentation.
        
        docsfilenames is a list of basenames of docsfiles and is only useful 
        together with install_dir. A str means a list of one item. None means 
        [basename(install_dir) + 'docs' (if given), command + '.docs']. 
        Do not use together with the docsfiles parameter.

        docsfiles is a list of paths to potential DocParser docsfiles; parse if
        present, in the given order. None means look for each docsfilename in
        install_dir (if given). A str means a list of one item. Note that no 
        docs will be read on instantation. Use .readdocs() (or .launch()) for 
        that.
        
        width is the maximum allowed width for help text. 0 means try to guess
        the terminal width, and use 79 if that fails.
        
        configdirs is a list of paths to directories to search for configfiles.
        None means [install_dir (if given), '/etc/' + command, '~/.' + command].
        A str means the same, but with this string replacing command. Do not 
        use together with the configfiles parameter.
        
        configfilenames is a list of basenames of configfiles. A str means a 
        list of one item. None means [command + '.conf']. Do not use together 
        with the configfiles parameter.
        
        configfiles is a list of config files to parse. None means try each 
        configfilename in the given order, in each of the configdirs in the 
        given order. configfiles are parsed incrementally by .parsefiles() (or
        .launch()). A str means a list of one item. [] means no configfiles.
        
        sections is a list of sections to read in config files. A str means a 
        list of one item. None means [command]. The DEFAULT section (note 
        uppercase) is always read, and it is read as if its contents were 
        copied to the beginning of all other sections.
        
        ignore is a list of option and positional argument names that should be
        ignored if encountered in configfiles or docsfiles. Any other unknown 
        names will raise an error. This is primarily to help users catch 
        spelling mistakes. This feature is useful for example if you are using
        the same files for several programs in a suite, where some parameters 
        are shared and you want to ignore the others. Set to None to ignore all
        all unknown (not recommended). 
        
        options can be used to supply a preconfigured option dictionary, if you
        for some reason prefer this to .makeoption(). tui will not check this 
        for you. See also option_order and abbreviations.
        
        option_order determines the order in which the options will be shown in
        help texts.
        
        abbreviations is a abbreviation:option dict, similar to options.
        
        positional_args can be used to supply a list of preconfigured positional
        arguments, if you for some reason prefer this to .makeposarg(). tui will 
        not check this for you. See also positional_arg_names.
        
        positional_arg_names are the display names for positional arguments in
        help texts.
        
        helpoption adds an option that lets the user request help in the usual
        way. Default is '--help' or '-h', option reserved for command line use.
        None means don't add such an option.
        
        longhelpoption adds an option that lets the user request verbose help.
        Default is '--HELP' or '-H', option reserved for command line use. None
        means don't add such an option. 

        versionoption adds an option that lets the user print the version 
        string. Default is '--version' or '-V', option reserved for command
        line use). None means don't add such an option.

        settingsoption adds an option that lets the user print a brief summary
        of program settings. Default is '--settings' or '-S', option reserved 
        for command line use). None means don't add such an option.