NAME:
	table_by_month
 PURPOSE:
	Prints counts stored in a dictionary in tabular form
 CALLING SEQUENCE:
 	table_by_month( count, key_replacement, sort_by_count, in_html )
 INPUTS:
 PROCEDURE:
	in_html = False
		print as simple table: year, 12 months, followed by annual total
		final line of dots, with total counts over all years and months
	; key-name (or replacement value)
	; code-red
	 2011     0    0    0    0    0    1    0    0    0    0    0    0 |    1
	 2012     0    0    0    0    0    0    0    0    1    0    0    0 |    1
	;................................................................. |    2

	in_html = True
		print as html table
 MODIFICATION HISTORY:
	MAY-2013, Paul Hick (UCSD/CAIDA; pphick@caida.org)

 NAME:
	tiny
 PURPOSE:
	Couple of trivial Python functions
 CATEGORY:
	smei/gen/python
 CALLING SEQUENCE:
	result = keys( a )
	result = args( a )
	is_there( k, a )
	start( x, a )
	result = run_cmd( cmd, verbose )
	result = tomb( size )
	result = which( program )
	say( csay, wseif, key, message )
 INPUTS:
	keys:	  a	: sys.argv
	args:	  a	: sys.argv
	is_there: a	: sys.argv
		  k	: keyword (usually starting with dash)
	start:	  a	: sys.argv
		  k	: argument (usually of form 'arg=')
	run_cmd:  cmd	: shell command to be executed
	 	  verbose : 0 : do not print the command log
      			    1 : print command log
 OUTPUTS:
	keys	: result : list of keywords starting with dash (-)
	args	: result : list of arguments not starting with dash (-)
	is_there: result : 0 if keyword 'k' is not present in 'a'
			   1 if keyword 'k' is present in 'a'
		  result : 0 if 'a' does not contain entry starting with 'k'
			   1 if 'a' contains entry starting with 'k'
	start	: result : substring of argument in 'a' trailing 'k'
			   blank string is 'a' does not contain 'k'
	run_cmd	: result : command log
 MODIFICATION HISTORY:
	MAR-2003, Paul Hick (UCSD/CASS)
	FEB-2004, Paul Hick (UCSD/CASS)
		Added tomb function
	APR-2005, Paul Hick (UCSD/CASS)
		Removed dependence on string module
	DEC-2005, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added say.

 NAME:
	tiny_echo_lines
 PURPOSE:
	Displays line with specified string including a couple of neighboring lines
 INPUTS:
	$1      fully-qualified name of text file
	$2		string to search for
	$3		number of lines to be displayed before line with $2
	$4		number of lines to be displayed after line with $2
	$5		user to use in sudo to read files (plan B if there is no read permission)
 OUTPUT:
	echo to stdin

 NAME:
	tiny_grep_lines
 PURPOSE:
	Displays line with specified string including a couple of neighboring lines
 INPUTS:
	$1      fully-qualified name of text file
	$2		start string to search for
	$3		stop string to search for
 OUTPUT:
	echo to stdin

 NAME:
	tiny_message
 PURPOSE:
	Prints message to stderr
 PROCEDURE:
	Same as tiny_note, but prints to stderr
	instead of stdout.

 NAME:
	tiny_note
 PURPOSE:
	Prints a string to stdout.
 INPUTS:
	$1		user message
	$2		positive integer indicating the "verbosity" threshold.
			If get_options is used then messages with threshold $2=1
			become visible when --verbose, or --debug=1 is set.
			(see also tiny_say below).
			If the threshold is set to 'n' then the message becomes
			visible if $2 is set to n or larger ($2 >= n)
	$3		single char: S,I,E,W. The default is 'I'
 OUTPUTS:
	Modified string $1 to stdout
 NOTE:
	A collection of functions implement special cases of tiny_note:

	For echoing to stdin
	--------------------
	Always echo (i.e. ignore VERBOSE or DEBUG setting):
		tiny_echo

	For echoing to stderr
	---------------------
		tiny_message		behaves exactly as tiny_note

	Always echo (i.e. ignore VERBOSE or DEBUG setting):
		tiny_yell			used to print informational messages
							that must always be visible
		tiny_warn			used to print warning messages that
							must always be visible
		tiny_die			echos and exits with code 1.
							used to signal fatal condition
		tiny_done			echos and exit with code 0.
							used to signal normal completion.

	Echo for every non-zero threshold:
		tiny_say			used for non-critical messages
							they become visible by setting --verbose
							(VERBOSE=1) or --debug=1 (or higher;
							DEBUG>=1) when get_options is used.

	For some of the functions above there is a 'bare'
	version that prints the message under the same conditions
	as the 'dressed-up' version, but echos the message
	unmodified except for an optional, fixed, prefix (see PROCEDURE).
	These are usually used following a call to the non-bare
	version.

	For echoing to stdin
	--------------------
		tiny_note_bare
		tiny_echo_bare

	For echoing to stderr
	---------------------
		tiny_message_bare
		tiny_yell_bare
		tiny_warn_bare
		tiny_say_bare

 PROCEDURE:
	The main intent is to provide a mechanism for
	echoing a message after adding the name of the
	calling routine identified in the bash variable
	__CALLER__.

	Action is controlled by several bash variables:

	DEBUG, VERBOSE

	These are most easily set by using get_options,
	which introduces DEBUG as a positive integer,
	and VERBOSE as a boolean variable. Setting the
	bool VERBOSE is equivalent to DEBUG=1.

	The message is only echoed if
		max(DEBUG,VERBOSE) >= $2
	i.e. if the user-requested "verbosity" level in
	DEBUG and/or VERBOSE is equal to or larger then the
	threshold $2 set by the call to tiny_note.

	__CALLER__

	If this is not set, or is the null string, then
	the string $1 is printed with the content of
	__NOTE_PREFIX__ at the start. By default this is
	a string of four spaces. This is used for the
	'bare' functions listed above.

	Usually __CALLER__ is set to a string identifying
	the calling routine. For a top-level script this
	can be `basename $0 .sh`. Bash functions need
	to hardcode a string as a local variable:
		local __CALLER__="function name"

	The string echoed to stdout has the form
		[DRYRUN ]%$__CALLER__[-SEIW][-$TIME]-$1
	where the components between square brackets
	may not be present.

	The components are:

	'DRYRUN'
	Is added if the bash variable DRYRUN is set to a
	non-zero integer (DRYRUN is a boolean option defined
	by get_options).

	__CALLER__
	identifies the calling function (see above)

	SEIW (from $3; default: 'I')
	Single character:
	'S'	success, used by tiny_done
	'E'	error, used by tiny_die
	'I'	information, used by tiny_say
	'W'	warning:, used by tiny_warn

	TIME
	The system time. This is added only if variable
	__TIME_TAG__ is defined. This should be a valid
	format accepted by the 'date' utility (without
	the leading plus sign, e.g. "%m/%d %H:%M")
 MODICATION HISTORY:
	JAN-2013, Paul Hick (UCSD/CAIDA; pphick@caida.org)

 NAME:
	tiny_note_bare
 PURPOSE:
	Print message, obeying verbosity rules from
	tiny_note, prefixed by content of __NOTE_PREFIX__