NAME:
	eon.between
 PURPOSE:
	Check whether time is in specified time period
 CALLING SEQUENCE:
	is_between = tt.between( t0, t1)
 PROCEDURE:
	if both start_time and stop_time are not None then
		True means start_time <= self < stop_time
	if only start_time is not None then
		True means self >= start_time.
	If only stop_time is not None then
		True mean self < stop_time
	If both start_time and stop_time are None then
		always True is returned

 NAME:
	eon.normalize
 PURPOSE:
	(Internal purposes only)
	Is used to normalize eon object (see PROCEDURE).
 PROCEDURE:
	Ensures that self.tictac is positive and is less than one
	day. As a result self.ticday will always refer to the
	midnight at the beginning of day (in UTC) for the eon object.
	Note that neither self.ticday nor self.tictac are forced to
	be integer. This is intentional. By the time this routine is
	called (by eon.__init__) these quantities should already be
	integers.
 TODO??: make self-exponent as small as possible while keeping
	tictac value exact.

 NAME:
	eon
 PURPOSE:
	Converts dates or time periods (delta times) between various formats.
	Adds and subtracts dates and delta times.
 CALLING SEQUENCE:
	eon.py -i IN_DATE <DATE> [ ] -o <OUT_DATE>
 INPUTS:

	-i <IN_DATE> t1 [t2 t3 ..]
	--in-date=<IN_DATE>  t1 [t2 t3 ..]
		is used to indicate that input times are calendar dates

		IN_DATE is a string specifying the format describing the input
		dates t1, t2, etc.

		The following strings are used to specify dates as single numbers (integer or float)
			posix		posix time (secs since 1970/01/01 00:00:00 UTC
			jd			Julian day (days since -4713/11/24 12:00:00 UTC
			njd			'new' Julian day (days since 2000/01/01 12:00:00 UTC)
			mjd			modified Julian day (days since 1858/11/16 12:00:00 UTC)
			jepoch		Julian epoch
			bepoch		Besselian epoch

		The second option is to set IN_DATE to a string explicitly specifying the
		format needed to interpret the input times t1, t2, etc.. The format must be
		constructed from the components
			YYYY		year
			DOY			day of year
			MM		 	month
			DD			day of month
			hh			hours
			mm			minutes
			ss			seconds
			TZ			timezone

		A number of special values for IN_DATE can be used to specify a couple
		of commonly used formats:

			ymd			same as format YYYYMMDD-hhmmss
			-ymd		same as format YYYY-MM-DD hh:mm:ss
			_ymd		same as format YYYY_MM_DD_hhmmss
			ydoy		same as format YYYYDOY-hhmmss
			-ydoy		same as format YYYY-DOY hh:mm:ss
			_ydoy		same as format YYYY_DOY_hhmmss
			iso8601		same as format YYYY-DD-MMThh:mm:ss

		The third options is to set IN_DATE to 'time'; this must be followed by a single (quoted)
		string containing the following components for describing a date:
			'year=<year> doy=<doy> hour=<hour> minute=<minute> second=<second> tz=<tz>'
			'year=<year> month=<month> day=<day> hour=<hour> minute=<minute> second=<second> tz=<tz>'

		Missing leading components are filled in from the current time; missing trailing
		components are set to zero.

		Multiple input dates can be specified in a single call. If one of the input
		dates is set to '-', then input is read from standard input.

	-I <IN_DELTA> dt1 [dt2 dt3 ..]
	--in-delta=<IN_DELTA> dt1 [dt2 dt3 ..]
		is used to indicate that input times are time periods.

		IN_DELTA is a string specifying the format describing the input
		delta times dt1, dt2, etc.

		The following strings are used to specify delta times as single numbers (integer or float)
		(the trailing 's' is optional):
			year[s]		number of Julian years (=365.25 days)
			day[s]		number of days
			hour[s]		number of hours
			minute[s]	mumber of minutes
			second[s]	number of seconds

		The second option is to set IN_DELTA to a string explicitly specifying the
		format needed to interpret the input delta times dt1, dt2, etc.
		The format must be constructed from the components
			YYYY		Julian years
			DD			days
			hh			hours
			mm			minutes
			ss			seconds

		The third options is to set IN_DELTA to 'time'; this must be followed by a single (quoted)
		string containing the following components for describing a delta time:
			'year=<year> day=<day> hour=<hour> minute=<minute> second=<second>

		Multiple input delta times can be specified in a single call. If one of the input
		delta times is set to '-', then input is read from standard input.

	-A dt1
	--plus-delta dt1
		is used to add a delta time to an input date or delta time

	-s
	--minus-date
		is used to subtract a date from an input date

	-S
	--minus-delta
		is used to subtract a delta time to an input date or delta time

 RESTRICTIONS:
	--in-date and --in-delta are mutually exclusive
	--minus-date is incompatible with --in-delta
 TODO:
	eon.py -p 1029340800.000058055 -s posix 1029369599.999996230
	gives -01:16:00:00.000061825
	should be -00:08:00.00 ??

	Keywords -f --date-format, and -F --delta-format to specify format string

	Find a way to deal with delta times that are not really a uniquely
	defined time period: year, month
 EXAMPLES:
 PROCEDURE:
	http://en.wikipedia.org/wiki/ISO_8601#Calendar_dates
 MODIFICATION HISTORY:
	NOV-2011, Paul Hick (UCSD/CASS; pphick@uscd.edu), V1.01
		Original version, translated from IDL functions
	DEC-2011, Paul Hick (UCSD/CAIDA; pphick@caida.org), V1.02
		Started to add shortcut options (-p)
	JAN-2012, Paul Hick (UCSD/CAIDA; pphick@caida.org), V1.03
		Added shortcut option -P
	MAY-2012, Paul Hick (UCSD/CAIDA; pphick@caida.org), V1.04
	    Added support for timezones

 NAME:
	eon_date.__init__
 PURPOSE:
	Creates eon_date object
 CALLING SEQUENCE:
	tt = eon_date()
 INPUTS:
 OPTIONAL INPUTS:
	exponent    defines units in which time of day is specified as
	            10^(-exponent).
				Default: g_EXPONENT (defined in eon_helper.py)
 OUTPUTS:
	tt          eon_date object
	            tt.exponent     integer
								set from optional input 'exponent'
	                            (i.e. defaults to g_EXPONENT)
 PROCEDURE:
	The __init__ procedure MUST set tt.ticday and tt.tictac:
	  tt.ticday     number of whole days since 2000 January 1, 0 UTC
	  tt.tictac		time of days in units of 10^(-tt.exponent)
	  tt.exponent   defines units of tt.tictac
	As a side effect a number of attributes may get set, but this
	is not really necessary.

 NAME:
	eon_date.init
 PURPOSE:
	Create eon_date object
 CALLING SEQUENCE:
	 1. tt = eon_date('time-string' [,'time_format',julian=True])
	 2. tt = eon_date('time-string' , 'regex'[, julian=True])
	 3. tt = eon_date(year=YYYY,month=MONTH,day=DAY, hour=HOUR,minute=MINUTE,second=SECOND,chipsec=CHIPSEC[,tz=TZ,julian=True])
	 4. tt = eon_date(year=YYYY,doy=DOY, hour=HOUR,minute=MINUTE,second=SECOND,chipsec=CHIPSEC[,tz=TZ,julian=True])
	 5. tt = eon_date(jd=JD)
	 6. tt = eon_date(njd=NJD)
	 7. tt = eon_date(mjd=MJD)
	 8. tt = eon_date(posix=POSIX)
	 9. tt = eon_date(jepoch=JEPOCH)
	10 = eon_date(bepoch=BEPOCH)
	11 = eon_date(carrington=CARRINGTON) [NOT IMPLEMENTED YET]
	12 = eon_date(now=TRUE)
	13 = eon_date(tictay=TICDAY,tictac=TICTAC,exponent=EXPONENT)
 PROCEDURE:
	For 1. and 2. the time zone can be coded into 'time-string' (with TZ in 'format' and 'regex')
	The timezone specified as keyword tz is only used if not specified in 'time-string'
	For 3. and 4. keyword tz is always used, if present.
	julian=TRUE forces use of Julian calendar for input date (1,2,3,4)

 NAME:
	eon_delta.get
 PURPOSE:
	Extract attributes of eon_delta (time difference) object
 CALLING SEQUENCE:
	result = dt.get(format=FORMAT)
	result = dt.get(regex=REGEX)	[not implemented yet]
	result = dt.get(attr=ATTR)
	result = dt.ATTR
 INPUTS:
	FORMAT  format for printing time difference.
	        the main component is one of these:
	        Dhms, hms, ms, s, Dhm, hm, m, Dh, h, D
	        followed by '.ddd', where the number of 'd's
	        indicates the number of digits after the
	        decimal point. If one of the components ending
	        with 's' is used then a trailing '.d#' says
			to use dt.exponent to set the number of digits.
			Add a colon (:) after the first character in
	        in FORMAT to force the different time components
	        to be separated by a colon (i.e. D:hms instead of Dhms).
	ATTR	passed to dt.__getattr__
			see eon_delta.attr dictionary for a list
			of implemented attributes.
 OUTPUT:
	result  if FORMAT is used, the returned format will
	        always start with a plus (+) or minus (-) sign
 EXAMPLE:
	eon_delta(hour=2,minute=30).get('hm') = '+0230'
	eon_delta(hour=-2,minute=-30).get('hm') = '-0230'
	eon_delta(hour=2,minute=30,second=30).get('h:m.dd') = '+02:30.50'
 PROCEDURE:
	

 NAME:
       eon_delta.round
 PURPOSE:
       Rounds to nearest multiple of a specified delta time
 CALLING SEQUENCE:
       dt_rounded = dt.round(du)
 INPUTS:
       du                      delta time object
 OUTPUTS:
       dt_rounded      delta time object, rounded to nearest du

 NAME:
	eon_filter.py
 PURPOSE:
 CATEGORY:
	tools/python/bin
 CALLING SEQUENCE:
 INPUTS:
 OPTIONAL INPUT PARAMETERS:
	-v	--verbose			verbose mode
 OUTPUTS:
 CALLS:
 EXAMPLE:
 PROCEDURE:
 MODIFICATION HISTORY:
	JAN-2013, Paul Hick (UCSD/CAIDA)
	OCT-2013, Paul Hick (UCSD/CAIDA; pphick@caida.org)
		Added --strict, and exception handler to catch names
		that do not match the regex