Anonymous avatar Anonymous committed ff9e130 Draft

updated readme for soon-to-exist functionality

Comments (0)

Files changed (1)

argparse_config.src/README.rst

 allow me to add defaults in the config file without writing more code.
 
 This is what ``argparse_config`` gives you. To use it with the mercurial client
-above::
+``arg_parser`` above::
 
-    >>> import ConfigParser # from the standard library
-    >>> config_parser = ConfigParser.SafeConfigParser()
-    >>> config_parser.read('/home/tikitu/.my_app.cfg')
-    ['/home/tikitu/.my_app.cfg']
-    >>>
     >>> import argparse_config
-    >>> argparse_config.set_defaults(arg_parser, config_parser) # using the arg_parser from above
+    >>> argparse_config.read_config(arg_parser, '/home/tikitu/.my_hg.cfg')
 
 ... and that's it. Calling ``arg_parser.parse_args()`` will parse args as usual,
 but the *default* values will be taken from the config file, if they are given
-there.
+there::
+
+    >>> parsed_args = arg_parser.parse_args(['merge'])
+    >>> parsed_args.tool
+    'meld'
+
+What can I put in the config file?
+----------------------------------
+
+Under the hood ``argparse_config`` uses the standard library ConfigParser_.
+Arguments that aren't for a subcommand go in the section ``[default]``. The
+names are munged from the commandline argument, removing leading dashes and
+converting internal dashes to underscores (e.g. ``--log-level`` becomes
+``log_level:``).
+
+.. _ConfigParser: http://docs.python.org/2/library/configparser.html
+
+Flags (i.e. commandline args that take no parameters) are turned on if present
+in the config, just like the commandline::
+
+    [default]
+    verbose:
+
+is the equivalent of ``--verbose``.
 
 How does it work?
 -----------------
 
-By gudgeling about in the private internals of ``argparse``. Yes, it's not pretty.
+By gudgeling about in the private internals of ``argparse``. Yes, that's not
+pretty.
+
+Gotchas
+-------
+
+Any required arguments that are present in a config file will show as optional,
+not required, in the ``--help`` output. (This is a bug-by-design, due to not
+having any clever idea about how to do it better.) It may help to tell
+yourself, "It's not required *on the commandline* because I gave it in the
+config file." (I will gladly make this dodgy rationalisation disappear if I
+figure out how to handle required arguments more tidily.)
 
 Hacking
 -------
 .. _issues list: http://bitbucket.org/tikitu/argparse_config/issues?status=new&status=open
 
 * A utility to output a config file, based on a set of commandline arguments.
-* Some tidier wrapping around the ``ConfigParser`` boilerplate, for the common use case.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.