Pacer is a CLI application that provides commands useful for runners. Pacer offers roughly two different services:
-
Taking running data and generating graphical charts e.g. plotting runs by distance.
-
Performing convenient calculations (e.g. deriving pace from a distance and duration).
The chart command generates a build directory that contains an html file with charts.
build/
├── bundle.js
└── index.html
1 directory, 2 files
Charts are generated from two inputs:
- A
runs.tomlfile, containing a list of all runs the user may want to chart. - A
chart-requests.tomlfile, that determines how to construct the chart(s). The html page will contain a chart for each request in the file.
Important
The chart command requires npm (nodejs) to be installed: https://nodejs.org/en/download
Usage: pacer chart [--chart-requests PATH] [-c|--clean] [-d|--data PATH]
[-j|--json] [--runs PATH]
Generates charts based on a chart-requests file and a runs file. Requires npm
to be installed.
Available options:
--chart-requests PATH Optional path to chart-requests file. Overrides
--data.
-c,--clean If active, cleans prior build files.
-d,--data PATH Path to data directory i.e. where we search for
chart-requests file and runs file. If not given,
defaults to the XDG config e.g. ~/.config/pacer/.
-j,--json If active, stops after generating the intermediate
json file. Primarily used for testing.
--runs PATH Optional path to runs file. Overrides --data.
-h,--help Show this help text
Building the example here i.e.
$ pacer chart -d examples/
will generate an html page with several charts like this one:
See the examples/ director for more information.
The convert command converts quantities to different units.
Usage: pacer convert [--distance DIST_STR] [--pace TIME_STR (/UNIT)]
(-u|--unit UNIT)
Converts a quantity. Requires exactly one quantity and the unit.
Available options:
--distance DIST_STR A distance with units e.g. '4 km'.
--pace TIME_STR (/UNIT) A pace e.g. '4m30s /km', '1h5m /mi'.
-u,--unit UNIT Output unit e.g. 'km', 'miles'.
-h,--help Show this help text
$ pacer convert --distance 5km --unit mi
3.11 mi
$ pacer convert --pace '5m20s /mi' --unit km
3'19" /km
Warning
With convert, pace must include units i.e. either /km or /mi. Furthermore, pace cannot be given in meters nor converted to meters; only kilometers and miles are allowed.
The derive command derives a third quantity from two others.
Usage: pacer derive [--duration TIME_STR] [--pace TIME_STR [/UNIT]]
[--distance DIST_STR] [-u|--unit UNIT]
Given two quantities, derives the third. For instance, given a distance and a
duration, derives the pace.
Available options:
--duration TIME_STR A length of time e.g. '1h2m3s'.
--pace TIME_STR [/UNIT] A pace e.g. '4m30s /km', '1h5m /mi', '4m30'. If the
units are not given, we use the distance's units.
Only kilometers and miles are allowed.
--distance DIST_STR A distance with units e.g. '4 km'.
-u,--unit UNIT Output unit e.g. 'km', 'miles'.
-h,--help Show this help text
# derives the pace from distance and duration
$ pacer derive --distance marathon --duration 3h15m
4'37" /km
# reverse of the above (slight difference due to rounding)
$ pacer derive --distance marathon --pace 4m37s
3h 14'48"
# we can also convert the final result to a different unit
$ pacer derive --distance marathon --duration 3h15m -u mi
7'26" /mi
$ pacer derive --pace '5m45s /mi' --duration 20m
3.48 mi
Note
Built-in values like marathon assume unit kilometers, if nothing else is given.
The scale command is used for scaling a single quantity.
Usage: pacer scale [--duration TIME_STR] [--pace TIME_STR [/UNIT]]
[--distance DIST_STR] [-u|--unit UNIT] (-k|--factor POS_INT)
Scales a quantity. Requires exactly one quantity and the scale factor.
Available options:
--duration TIME_STR A length of time e.g. '1h2m3s'.
--pace TIME_STR [/UNIT] A pace e.g. '4m30s /km', '1h5m /mi', '4m30'.
--distance DIST_STR A distance with units e.g. '4 km'.
-u,--unit UNIT Output unit e.g. 'km', 'miles'.
-k,--factor POS_INT The scaling factor.
-h,--help Show this help text
$ pacer scale --distance marathon -k 0.5
21.10 km
# we can convert the final result
$ pacer scale --distance marathon -k 0.5 -u miles
13.11 mi
$ pacer scale --pace '4m15s /km' -k 1.1
4'40" /km
# pace units are optional
$ pacer scale --pace 4m15s -k 1.1
4'40"
Warning
With scale, pace must include units if the final result is converted.
$ pacer scale --pace '4m15s' -k 1.1 -u mi
Scaling pace with --unit requires that the original units are given e.g. --pace '4m15s /km'.
If you have never built a haskell program before, Cabal is probably the best choice.
cabal 2.4+- One of:
The easiest way to install these is generally ghcup.
The current "blessed" version is ghc-9.10.1.
Once you have cabal and ghc, pacer can be built locally with cabal build or installed globally (e.g. ~/.local/bin/pacer) with cabal install.
For further reproducibility, optional freeze files can be used e.g.
cabal build --project-file cabal.ghc9101.projectNote
Freeze files are provided for only select compilers.
Building with nix uses flakes. pacer can be built with nix build, which will compile and run the tests.
Because pacer is a flake, it can be built as part of a nix expression. For instance, if you want to add pacer to NixOS, your flake.nix should have:
# flake.nix
{
inputs.pacer.url = "github:tbidne/pacer/main";
}Then include this in the systemPackages:
# wherever your global packages are defined
{
environment.systemPackages = [
pacer.packages."${system}".default
];
}See faq.md.