fitrecs − Simple command-line fitness record processor
fitrecs [-V] [-T] [-R] [-S] [-p] [-D time unit] [-s start date] [-k precision] [-e end date] [-F date format] [-d distance unit] [-w weight unit] [-t time unit (composite)] [-c config file] [-f data file]
fitrecs A simple command-line fitness record processor. Enter exercise records in a very simple line-oriented format in a text file; fitrecs will process it in various ways, as you tell it to, and output it in a sensible format.
|
-V |
Print version and copyright information and exit successfully. | ||
|
-T |
Print Totals for each exercise; that is, add up every time I’ve done that exercise and print that. | ||
|
-r |
Print records for each exercise; that is, pick the highest value for each type of exercise and print it. It will also print the date on which that highest value was reached. | ||
|
-R |
Print the Records that fitrecs is keeping track of. This is the only option that by default is true; that is, by default fitrecs will print out the records of each exercise. If you specify -R, this will turn such printing off; this is useful when you want to know, say, your totals (with -T) but not individual values. | ||
|
-S |
When there are appropriate other quantities (that is, a time and a distance) for an exercise, print also the speed (the distance divided by the time). | ||
|
-p |
When there are appropriate other quantities (that is, a time and a distance) for an exercise, print also the pace (the time divided by the distance). |
-s start date
The first date for which you want fitness records output. If you give this but no end date, you will get all fitness records for this date onward.
-e end date
The last date for which you want fitness records output. If you only want one day output, make this the same as the start date. If you give this but no start date, you will get all fitness records prior to this date.
-F date format
The format you’d like to see the date output in; this does not affect the formats that fitrecs will understand. This option follows the formal conversion characters for dates in a Unix-like system; e.g., "%d %b %Y" will give you the day, followed by an abbreviated month name, followed by a four-digit year. The default is "%Y-%2m-%2d", which will give the default ISO date format.
-D time unit
Specify a particular time unit for output. (Input will accept any of a wide variety of time units.) If you don’t like the "default" time format (HH:mm:ss.mmmm), you can ask fitrecs to give you times in some particular unit. Acceptable options are seconds ("s"); minutes ("min"); hours ("hr"); days ("day"); weeks ("wk"); and fortnights ("fort"). If you wish to make it explicit, you can ask for the default behavior by setting this value to "default". This only effects times alone; it will not effect times in composite units (e.g., speeds or paces), for which see the "-t" option.
-t time unit (composite)
Specify a particular time unit for output in composite units, such as speeds or paces. So you may wish simple times to be output as "HH:mm:ss.mmmm", but have speeds output as "mi/hr"; you would set this value to "hr" in this case. Acceptable units are the same as those for "-D". Default is "s".
-w weight unit
Specify a particular weight unit for output. (Input will accept any of a wide variety of weight units.) Available units are kilograms ("kg"); grams ("g"); pounds ("lb" or "lbs"); ounces ("oz"); stones ("st"); hundredweight ("cwt"). Default is "kg".
-d distance unit
Specify a particular time unit for output. (Input will accept any of a wide variety of distance units.) Acceptable units are kilometers ("km"); meters ("m"); centimeters ("cm"); miles ("mi"); yards ("yd"); feet ("ft"); inches ("in"); furlongs ("furl"). Default is "km".
-k precision
Specify a certain precision to print values to. This is a very imprecise label; in reality, this simply tells fitrecs how many places after the decimal point to use. Must be an integer value to be effective. E.g., -k 2 will print "3.33"; -k 5 will print 3.33333.
-c config file
Tells fitrecs to use a certain file for configuration options. By default, this will be ~/.config/fitrecs/fitrecsrc. If you want to use a different file, name it; if you want to use no config file at all, make the file name a simple hyphen: -c"-".
-f data file
Tell fitrecs to read fitness data from a particular file. By default, this will be ~/.config/fitrecs/datafile. If you want to use a different file, simply name it.
The data file used by fitrecs is a very simple format; the lines consist of the date, the name of the exercise, and the value assigned to it, all separated by tabs. Whitespace at the beginning and the end of lines is ignored. This means that, other than tabs which might be at the front of a line and tabs which might be at the end, each line can contain only two tabs: one between the date and the exercise type, and one between the exercise type and the value.
The date can be accepted in a few different formats. The traditional American date format, "%m/%d/%Y", is understood, but only if the parts are separated by slashes. Other formats are %Y-%m-%d, %Y %m %d, and %d %b %Y.
The exercise type is simply an arbitrary string; typically it will be something like "pushup", "weight", or "run".
Values are accepted in any number, each one separated by a semicolon and, optionally, some whitespace. They may come in a few varieties: "count", "distance", "weight", and "time". The rules are as follows:
|
count |
representing a mere count. This will normally be a simple integer. E.g.: pushups, "12". |
distance
followed by a distance unit, such as "mi" or "km". E.g.: "5.34mi".
|
weight |
by a weight unit, such as "lb" or "kg". E.g.: "180lb". | ||
|
time |
include either minutes and seconds (with optional fractional number of seconds) or hours, minutes, and seconds (with optional fractional number of seconds). E.g., "00:30.34" for 30.34 seconds, or "00:04:27" for "four minutes and twenty-seven seconds". |
Some examples of valid lines are as follows:
14 Aug 2021 pushups 12
14 Aug 2021 walk 3.2mi;00:45:33
14 Aug 2021 weight 185lb
There is a also a config file, or an rc file; this controls many of the aspects of what fitrecs does. Most of what we discussed under command-line options can be controlled in the config file, as well.
By default, the config file is ~/.config/fitrecs/fitrecsrc; but, as seen above, you can override this with the -c option. If you don’t want to use any config file, tell fitrecs so by saying -c"-" (that is, give it a single hyphen as a file name).
fitrecs will read any file you give it with -c; if you don’t give it one, it will read the default config file.
As noted, your
config file can control much of fitrecs’s
behavior. Each line in the config file is an independent
statement; the directive is a single word in all caps,
followed by a colon, followed by optional whitespace, and
finally followed by the value. The following values are
accepted:
OUTPUT_WGT_UNIT
Gives the unit you’d like weights output in.
OUTPUT_DIST_UNIT
Gives the unit you’d like distances output in.
OUTPUT_TIME_UNIT
Gives the unit you’d like times output in. Remember that this is only times themselves; times in composite units is defined elsewhere. As wth the command-line option, using "default" here will give the time in the default format: HH:mm:ss.mmmm.
OUTPUT_TIME_COMPOSITE
The time units to be used in composite units.
OUTPUT_DATE_FORMAT
The format to be used for dates in the output.
PRECISION
The precision (number of decimal places) for output to be displayed. E.g., PRECISION: 3.
PRINT_SPEED
PRINT_PACE
PRINT_SUMMARY
PRINT_TOTALS
Self-explanatory. These are interesting because by default these are false; therefore, any value here will set them to true. It’s probably good to say, e.g., PRINT_SPEED: true, so it’s clear what you’re doing, but giving it any value at all will do the same thing.
Some examples of valid lines are as follows:
OUTPUT_DATE_FORMAT: %d %b %Y
OUTPUT_DIST_UNIT: mi
|
0 |
All went well and we exit successfully. Yay! | ||
|
1 |
You used an option that requires an argument, but didn’t give fitrecs an argument to use. | ||
|
2 |
You used an option that fitrecs doesn’t recognize. | ||
|
3 |
You’ve given firecs a starting date that it can’t parse, despite its best efforts to do so. Consider giving the date in a different format. | ||
|
4 |
You’ve given firecs an ending date that it can’t parse, despite its best efforts to do so. Consider giving the date in a different format. | ||
|
5 |
fitrecs ran out of memory! This seems extremely unlikely and probably means that something is horribly wrong. | ||
|
6 |
You gave fitrecs a bad data file; that is, one that cannot be opened. fitrecs will appropriately gag on this and attempt to tell you why it couldn’t handle the file you wanted; probably it either doesn’t exist or you don’t have the proper permissions. | ||
|
7 |
You gave fitrecs a bad config file; that is, one that cannot be opened. fitrecs will appropriately gag on this and attempt to tell you why it couldn’t handle the file you wanted; probably it either doesn’t exist or you don’t have the proper permissions. |
None known at this time.
Donald P. Goodman III <dgoodmaniii at gmail dot com>