━━━━━━━━━
ARA
Andinus
━━━━━━━━━
Table of Contents
─────────────────
Documentation
Demo Videos
Ara is a simple cli program that prints Covid-19 stats. Currently it
only prints India's Covid stats.
Documentation
═════════════
`ara' by default will first look for the file in `$XDG_CACHE_HOME', if
that is not set then `HOME/.cache' is used, the file name is assumed
to be `ara.json', there is currently no option to override this or the
full path.
If you run `ara' on OpenBSD then it should use `OpenBSD::Unveil'.
Default logic is to check if the file is available locally & if it's
not older than 8 minutes, in any other case it fetches the latest
data. This can be controlled with `local' & `latest' option.
The file is downloaded over a secure connection & the server's
identity is verified.
Options
───────
local
╌╌╌╌╌
This option forces `ara' to use the data available locally, it will
only override this option when the file doesn't exist on disk.
latest
╌╌╌╌╌╌
This will force `ara' to fetch the latest data.
*Note*: `local' & `latest' option cannot be used together, `ara' will
print a warning & latest option will be ignored.
notes
╌╌╌╌╌
Only state notes will be printed if this option is passed.
rows
╌╌╌╌
`rows' option takes an integer as argument which can be passed as
`--rows n', where `n' is an integer.
`ara' will only print maximum these many number of rows, if you pass 0
or a negative number then `ara' will ignore it & print all the rows.
showdelta
╌╌╌╌╌╌╌╌╌
This will show delta values for every row, default is to show delta
only on rows that were updated "Today".
*Note*: This can be disabled by `autohide' option.
nodelta
╌╌╌╌╌╌╌
This will remove delta values from every column.
nototal
╌╌╌╌╌╌╌
This will remove the "Total" or "India" row from the table.
`hide' option should be used for this purpose, this option is only
kept for backwards compatibility.
nowords
╌╌╌╌╌╌╌
"Confirmed", "Recovered" & "Deaths" column format numbers in words.
For example, "1.6 lakhs" instead of "1,60,000" which makes it easier
to read. This option will disable this behaviour.
"Active" column doesn't format numbers in words because it's alignment
is set as "right" & formatting it this way doesn't look good. There is
currently no option to change this behaviour.
autohide
╌╌╌╌╌╌╌╌
This will automatically hide some columns if the term size is smaller
than expected, it's just a bunch of `if' blocks.
┌────
│ push @to_hide, "updated" if $t_columns < 110;
│ push @to_hide, "active" if $t_columns < 100;
│ undef $show_delta if $t_columns < 80;
│ $no_delta = 0 if $t_columns < 80;
└────
Currently (2020-08-03) it's just these lines pasted above but that
might change so look at the source for latest rules.
hide
╌╌╌╌
`hide' is able to hide states & columns from the table, the values
should be space seperated like `--hide active "last updated"
recovered'. These are case sensitive & should be lowercase.
Arguments can be passed as they're printed, for example `--hide "jammu
and kashmir"' is equivalent to `--hide jk' because "JK" is what's
printed on the table.
Only "States" & "Notes" column cannot be hidden, `ara' will print a
warning if you try to do so.
*Note*: "updated" is aliased to "last updated", so you can pass
`--hide updated' & it would hide the "last updated" column.
*Note*: The feature to get space seperated values is marked as
experimental in `Getopt::Long' so the behaviour can change in future,
worse even get removed. To guarantee backwards compatibility pass each
value by itself like `--hide jk --hide active', this is equivalent to
`--hide jk active'.
◊ Implementation
`%hide' hash is created from `@to_hide' which was created from user
arguments by `Getopt::Long'.
┌────
│ undef @hide{ @to_hide }
│ if scalar @to_hide;
└────
`%hide' contains values of `@to_hide' as keys & the value to those
keys is not defined, hence `undef'. This one line says Perl to "undef
these keys from the hash `%hide'" where these refers to the values of
`@to_hide'. This will fail if `@to_hide' is empty so we have to check
for that.
Alternatively we can do `@hide { @to_hide } = ()' which works even if
`@to_hide' is empty & does the same thing otherwise, this looks more
cryptic so I use the first way.
To check if a specific column is to be hidden or not we use `exists'
like `exists $hide{something}'.
There are other ways of doing this & maybe those would be better, I
didn't test which one was the best.
◊ Columns
To make `hide' work we put create `@columns' & push columns to it
unless the user has asked to hide it.
┌────
│ my @columns;
│
│ push @columns, 'Confirmed' unless exists $hide{confirmed};
│ push @columns, 'Active' unless exists $hide{active};
└────
◊ States
The whole block is skipped if the user has asked to hide the state.
As said above, statecode is also check if that's what is printed in
the table which is true only if `length $state > 16'. There is no
good reason for not checking statecode for everything.
┌────
│ next
│ if exists $hide{lc $state}
│ # User sees the statecode if length $state > 16 so we also match
│ # against that.
│ or ( length $state > 16
│ and exists $hide{lc $statewise->[$i]{statecode}});
└────
show
╌╌╌╌
`show' also accepts space seperated values & just like in `hide''s
case it's experimental & can change in future.
`show' will only show states that are passed. For example, `--show jk'
will only print data for Jammu & Kashmir. If both `show' & `hide' is
used for states then `hide' is ignored. `show' for states can be used
with `hide' for columns.
◊ Implementation
`show''s implementation is similar to `hide''s. `%show' hash is
created from `@to_show'.
┌────
│ undef @show{ @to_show }
│ if scalar @to_show;
└────
If user has used `show' then `hide' is ignored, this is achieved by an
if-else block. This also means that invalid values in state would
cause `hide' to be ignored, for example passing `--show invalid'
wouldn't match anything but `hide' will still be ignored. This is
intentional.
┌────
│ if ( scalar @to_show ) {
│ next
│ unless exists $show{lc $state}
│ or ( length $state > 16
│ and exists $show{lc $statewise->[$i]{statecode}});
│ } else { ... }
└────
help
╌╌╌╌
`help' will print help for `ara' which will have little information
about all these options listed above.
• `nototal' was removed from `help' because `hide' option does the
same thing & is recommended.
Cross-platform compatibility
────────────────────────────
Previously `ara' had OpenBSD specific code & would simply fail to run
on other OSes, now it runs on all platforms. There is still OpenBSD
specific code but it's used only when `ara' detects to be running on
OpenBSD.
┌────
│ use constant is_OpenBSD => $^O eq "openbsd";
│ require OpenBSD::Unveil
│ if is_OpenBSD;
│ sub unveil {
│ if (is_OpenBSD) {
│ return OpenBSD::Unveil::unveil(@_);
│ } else {
│ return 1;
│ }
│ }
└────
`is_OpenBSD' is a constant so the if-else block is optimized at
compile time. Another way would be to define the sub inside the
if-else block which is what I did initially but that is not the same
thing as this.
You cannot define sub like that in Perl because this step happens at
compile time & so the if-else block is ignored, which means the code
will be equivalent to else block being true all the time because
that's what comes later.
┌────
│ if (is_OpenBSD) {
│ require OpenBSD::Unveil;
│ OpenBSD::Unveil->import;
│ } else {
│ sub unveil { return 1; }
│ }
└────
Above code block will override the unveil sub to be `return 1;'
everytime, this was fixed in commit
`245aebe3da915afc0feafc7257f025e2e66a987f'.
This will still fail on OpenBSD if users don't have `OpenBSD::Unveil'
in `@INC', this shouldn't be an issue with Perl in base but if user
runs custom Perl then it might not be in `@INC', in that case user is
expected to fix this by adding the path to `OpenBSD::' in `@INC'.
Demo Videos
═══════════
• [Ara 2020-06-14] (new options)
• [Ara 2020-06-06]
[Ara 2020-06-14]
<https://diode.zone/videos/watch/95868534-8aae-497b-806e-5766236bb058>
[Ara 2020-06-06]
<https://diode.zone/videos/watch/03be044d-6ab7-4f01-8769-0084674dec93>