hollasch / timeprint

Print date and time information on the Windows command line

Here's my stuff. Feel free to ask questions or log issues.

Books

Site	Description
raytracing.github.io	The Ray Tracing in One Weekend book series. Three online books (with source) on how to write your own raytracer

Tools

Repo	Description
calendar	Windows command-line tool to print specific months or years
csub	Command substitution for the Windows command line
drives	Windows command-line tool to display all current drive information
eol	Windows command-line filter to convert End-Of-Line character sequences
ftimecomp	Windows command-line tool for the comparison of file timestamps
hex	Windows command-line hexadecimal dump utility
pathmatch	Windows command-line tool to print directories and files matching wildcard specifications of arbitrary depth.
timeprint	Nice Windows command-line tool to very flexibly print elapsed, relative or absolute times and dates
win-scripts	A collection of useful Windows CMD scripts and fragments

Experimental / Miscellaneous

Repo	Description
fpWorkbench	A set of C++ programs for experimenting with floating point numbers
gibber	I have a personal Perl script to generate English-like gibberish (for password inspiration). Someday I hope to port this to multiple platforms as a C++ tool.
hollasch	Magical repository that allows me to have a profile README
jumpdir	Sigh. Someday I'll get to this V2 port of a very awesome tool I wrote years ago.
LSON	Needs a better name. Yet another rethinking of JSON, with tables, graphs, and much better freedom for expressing arbitrary data types.
pi-lab	Archive of some Raspberry Pi Python scripts I wrote a while ago.
ray4	Source + doc of my master's thesis Four-Space Visualization of 4D Objects. 4D raytracer.
srhlab	Random fragments and notes to document various programming concepts I've learned.

timeprint's Issues

`%i` format code yields full ISO-8601 date-time

Equivalent to %Y-%m-%dT%H:%M:%S%z.

Switch to new time reporting semantics: two times = diff, one time = explicit

The old semantics were such that --modTime reported the time elapsed since the modification time and now.

The new semantics will report the modification time explicitly (and access time and explicit time). If two times are supplied, then the difference will be reported.

So, for example, to get the old behavior of --modTime, you'd do this:

timeprint --modTime someFile --time now "%_s seconds since someFile was modified."

Rename `--modTime` to `--modification`, `--accessTime` to `--access`

Add help on --help (-h) switch

Include the --help (-h) switch.

Delta time options need field width specifier with optional leading zeros

Currently, a time delta of "%_H:%_hM:%_mS" may yield output like 22:1:5. We need to support a field width specifier, and away to choose between padding with spaces and padding with zeros.

Implement automatic decimal length for delta formats

• Y. = Y.8
• T. = T.8
• D. = D.5
• H. = H.4
• M. = M.2

See #20.

Address remaining issues with explicit time

There seem to be some issues with setting unit values, with local versus UTC, and with properly accounting for time zone specification.

timeprint.md should be auto-generated somehow

Too easy to have it drift from the current implementation, and too much work to continually convert from plaintext to markdown. Probably just capture plaintext in each session.

Delta time formats need a way to specify leading zeros

For a time diff of 10:04:08, delta time formats would report 10:4:8. Need to revisit the syntax to specify zero-padding of appropriate (manual or appropriate) width. Perhaps key off of next greater unit?

format	Leading zeros
y0D	3
y0H	4
y0M	6
y0S	8
d0H	2
d0M	4
d0S	5
h0M	2
h0S	4
m0S	2

Yup, I think that would be a nice solution.

Support Gregorian dates from 1582 to 1970

See https://en.wikipedia.org/wiki/Gregorian_calendar.

The Gregorian calendar was enacted 1582-10-15. Add code to support such dates. For delta display, we have room to use negative 64-bit values. This task is made easier by the fact that leap seconds didn't exist until 1972, so the calendar is predictable for that time period.

For non-delta values, this may not be simple.

Add `--delta` option

To enter a single-valued time delta, in ISO 8601 format. Note that this precludes any other time values on the command line.

timeprint.md needs update for format codes

It currently lists %_S as elapsed whole seconds, but needs instead to refer to delta formats.

Refactor main() function

All of the code for this tool is in a single monolithic function. Enough already.

Deprecate old `%_d` and `%_h` options

Also ensure that the remaining %_s option works according to the new delta time spec.

See #20.

Add TOC links to README.md

Revise timeprint help header

Change to something like this:

timeprint v2.1.1 - Prints time and date information
https://github.com/hollasch/timeprint

<remainder of help text>

Implement `$_[YTDHMS]` delta options

These values are the floor of nominal years, tropical years, days, hours, minutes and seconds.

See #20.

Crashes on %P

Use std::string instead of C char buffers

There are several latent issues where it's possible to have a buffer overflow in the code. Rather than fix these, the code should just be switched to std::string.

Add acceptance testing

Just a script with expected outputs and a diff from accepted output should do it.

Add options for simple elapsed time printing

One option is to specify the modification age of a file. Equivalent to

timeprint --modification <file> --now ...

A second improvement would be a simple, smart elapsed time format code. This would be in the format

%_Y, %_yD, %_Dh:%_h0M:%_m0S

In practice it would be a bit smarter than that, eliding large units with zero value. For example, if the total elapsed time was under a day, then elide years and days.

Add README

Add --time (-t) switch

Add a switch to take in a specified time in ISO 8601 format. This can be used as either the time to report, or as the two times for computing differences (this would require two such arguments).

See http://en.wikipedia.org/wiki/ISO_8601.

Incorrect delta time reported: 1932 to now

> timeprint --time 1932-04-17 --now %_Y years, %_yD days.
48 years, 104 days

Add `--now` as a short form of `--time now`

Keep --time now; just add the new option -n/--now.

Crash on missing modTime switch argument

timeprint --modTime crashes.

Switch to Unicode support

• Unicode arguments
• Unicode file name references
• Unicode format string
• Unicode output

Implement locale-dependent thousands/decimal characters for delta formats

This is the ' prefix.

See #20.

Review elapsed time formats

Currently %_s (elapsed whole seconds), %_h (elapsed whole hours) and %_d (elapsed whole days) are the only fields that make much sense when reporting time differences.

Hours and days should be real-valued, with modifiers to control formatting. Likely, fractional formats should be truncated rather than rounded. For example, if half a day has elapsed, then 0 should be output. There should also be a way to report days-hours-minutes-seconds and others in a sensible way. Perhaps format controls could also specify whole modulo values for use in multi-value fields.

Design in this issue first.

Crash on missing --timeZone argument

timeprint --timeZone crashes.

Break up help output

The help output is 182 lines and growing. The --help command should take multiple arguments to subsets of the help documentation. Suggested subsets:

• no args — Main short usage info
• timezone — Supported time zone formats
• format — Format codes
• examples — Helpful examples

Add output comparitive tests

Lots of valid uses of timeprint are difficult to test with acceptance testing, since any time-varying outputs (like --now) will change from run to run. Add utilities to redirect output to a file and then compare that output with the output from other runs. That would make it possible, for example, to test -n and --now. It could also be used to validate file access, creation, and modification times.

Consider beefing up the time & date accuracy

For example, consider using ICU Datetime: http://userguide.icu-project.org/datetime

Add default format for time deltas

If no format is specified, and if a delta time is computed, use a default format that generally works for deltas.

Add format numeric prefix handling for %a (abbreviated weekday name)

%a = %3a

Format
%3a	Mon	Tue	Wed	Thu	Fri	Sat	Sun
%2a	Mo	Tu	We	Th	Fr	Sa	Su
%1a	M	T	W	T	F	S	S

Release v2.0.0

After the latest changes, release the updated version.

Add `--time` option to specify an explicit time

Implement the following syntax:

<timeValue> = now                 use current date + time + zone
<timeValue> = <date>              time = current time
<timeValue> = <time>              date = current date
<timeValue> = <date>T<time>

<date> = <YYYY>-?<MM>-?<DD>
<date> = <YYYY>                   month = current month, day = current day
<date> = <YYYY>-<MM>              day = current day
<date> = --<MM>-?<DD>             year = current year
<date> = <YYYY>-?<DDD>

<time> = <HH>:?<MM>:?<SS><zone>
<time> = <HH>:?<MM><zone>         seconds = current seconds
<time> = <HH><zone>               minutes = current minutes, seconds = current seconds

<zone> = <null>                   use current local time zone
<zone> = Z
<zone> = [+-]<HH>:?<MM>
<zone> = [+-]<HH>

-?     = - | <null>
:?     = : | <null>
+-     = + | -
<YYYY> = 0000-9999
<MM>   = 01-12
<DD>   = 01-31
<DDD>  = 001-366
<HH>   = 00-24                    24 = midnight / 00 of next day
<MM>   = 00-59
<SS>   = 00-60                    Accomodates leap seconds

Implement `[,.]` specifier for thousands/decimal characters in delta formats

See #20 for description. This is for the explicit characters; the locale-dependent character is another issue.

status:closed

Support `--creation <someFile>` switch

Report on the creation time of the named file.

feature: alternate format codes

Consider alternate format codes. For example,

"%Y-%m-%d"

could be

"{yr}-{min}-{day}"

Given the current abundance of format codes (43 at this point in time), doing any non-trivial task pretty much requires consulting the help.

Revisit delta time formats

timeprint should be able to track the next greater unit automatically, left to right. Possibly try out a new experimental delta token that does this automatically. Try new delta symbol -. This would yield the following syntax:

                   %-['kd][0]<U>[.[#]]
                      -v-  v  v  --v-
Numeric Format --------'   |  |    |
Optional leading zeros ----'  |    |
Units ------------------------'    |
Decimal Precision -----------------'

How to handle the case where the next greater unit was equal or smaller than the current? Consider suppressing the interpretation of the current code (printing it literally), or insert an error indicator.

As an example, this:

timeprint --now --time 20181029T160000 %_Dd %_d0H:%_h0M:%_m0S

becomes this:

timeprint --now --time 20181029T160000 %-Dd %-0H:%-0M:%-0S

More intuitive and less error-prone. An sketch of an erroneous format string:

timeprint --now --time 20181029T160000 %-Dd %-0H:%-0D:%-0S
15d 23:<ERROR: %-0D>:2718

Low-precision times should zero unspecified fields

Here's an example:

> timeprint --now --time 20181029T160000 %_Dd %_d0H:%_h0M:%_m0S
3d 05:13:30

> timeprint --now --time 20181029T1600 %_Dd %_d0H:%_h0M:%_m0S
3d 05:14:00

Notice that if the time here is specified as 1600, then the delta time uses the same precision for --now, zeroing out the seconds. In this situation, a time of 1600 (or even 16) should be interpreted as 160000.

Provide a way for the TIMEFORMAT environment variable to also specify a delta time format

See issue #44.

Either introduce a new TIMEFORMATD (or TIMEFORMATDELTA) environment variable, or a way to specify default absolute and delta time formats in the existing TIMEFORMAT environment variable. For the latter option, try to choose some kind of separator before the second, delta, format (this is mostly backwards compatible). What would be a good separator in this case?

Add -- switch variants

-e = --escapeChar
-m = --modTime
-z = --timezone

Help output error: command switches may use `-` or `/`

Help output line:

Command switches may be prefixed with a dash (-) or a slash (/).

This is incorrect; they can be a double dash or a slash.

Implement delta format decimal operators

This suffixes the delta format with [.[#]]. It should print the floor of the given number of digits, rather than rounding.

See #20.

Add --accessTime option

timeprint --accessTime <fileName> should use the access time of the named file.

Implement preceding modulus for delta formats

Implement the lowercase letter prefix in a delta format code, which indicates a preceding modulus.

See #20 for more information.

Update README

The README file is now out of date with reality. Bring it up to date.