The help command
================

One of the built-in pieces of functionality that Glint provides is the help command which will display an automatically
generated help screen for the user.  This screen is generated by inspecting the commands which have been defined. In this 
section we will walk through building out the help data for the following example hello world application: ::

	#! /bin/env python

	import glint

	def hello(name, wave = False, message = None):
		print('Hello %s.' % name)
		
		if wave:
			print('I\'m waving at you!')
		
		if message is not None:
			print('I want to tell you: %s' % message)

	if __name__ == '__main__':
		runner = glint.Runner()
		runner['hello'] = (hello, 'Prints a hello message and exits.')
		runner.run()

When we run the built-in help command we get the following output: ::

	usage: ./example.py <command>

	Commands:

	  help    Show this message and exit
	  hello

	See './example.py help --command <command>' for help on that command.

From that you see we can further inspect a command by calling ``./example.py help --command hello`` which will produce: ::

	usage: ./example.py hello <name> [--message <message>] [--wave]

	Arguments:

	  name

	Optional Arguments:

	  --message

	Flags:

	  --wave

This gives us a good place to start but we can do better to bulk up what we're telling the user. The first place we should start is give 
the user some context about what the call does, we can do this by supplying a description for the command. A command description is defined 
when a method is assigned, we change it from being assigned to just a method to a tuple containing the method and description like so ::

	runner['hello'] = (hello, 'Prints a hello message and exits.')

Now when we run the help command we get. ::

	usage: ./example.py <command>

	Commands:

	  hello   Prints a hello message and exits.
	  help    Show this message and exit

	See './example.py help --command <command>' for help on that command.

That helps our users when trying to figure out what a command does, but it doesn't do much for telling them what an argument means. To do that 
Glint hijacks the `annotations <http://www.python.org/dev/peps/pep-3107/>`_ of the parameters. If we are to do this in our example script we
update the function signature to look like the following. ::

	def hello(name: 'Who we are saying hello to.', wave: 'Add this flag if you want to wave.' = False, message:'A message we want to tell.' = None):

When we run the help command we won't notice any change, though when the run help for the hello command ::

	Prints a hello message and exits.

	usage: ./example.py hello <name> [--message <message>] [--wave]

	Arguments:

	  name        Who we are saying hello to.

	Optional Arguments:

	  --message   A message we want to tell.

	Flags:

	  --wave      Add this flag if you want to wave.

We now have a lot more information that can help our users understand what our application does.  The final script after we made the changes on this 
page ends up looking like. ::

	#! /bin/env python

	import glint

	def hello(name: 'Who we are saying hello to.', wave: 'Add this flag if you want to wave.' = False, message:'A message we want to tell.' = None):
		print('Hello %s.' % name)
		
		if wave:
			print('I\'m waving at you!')
		
		if message is not None:
			print('I want to tell you: %s' % message)

	if __name__ == '__main__':
		runner = glint.Runner()
		runner['hello'] = (hello, 'Prints a hello message and exits.')
		runner.run()

.. toctree::
	:hidden:
	
	inheritance