diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 296 |
1 files changed, 296 insertions, 0 deletions
diff --git a/README b/README new file mode 100644 index 0000000..bfe34bc --- /dev/null +++ b/README @@ -0,0 +1,296 @@ + ━━━━━━━━━ + ARA + + Andinus + ━━━━━━━━━ + + +Table of Contents +───────────────── + +1 Documentation +.. 1.1 Options +.. 1.2 Cross-platform compatibility +2 Demo Videos + + +Ara is a simple cli program that prints Covid-19 stats. Currently it +only prints India's Covid stats. + + +1 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. + + +1.1 Options +─────────── + +1.1.1 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. + + +1.1.2 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. + + +1.1.3 notes +╌╌╌╌╌╌╌╌╌╌╌ + + Only state notes will be printed if this option is passed. + + +1.1.4 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. + + +1.1.5 showdelta +╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ + + This will show delta values for every row, default is to show delta + only on rows that were updated "Today". + + +1.1.6 nodelta +╌╌╌╌╌╌╌╌╌╌╌╌╌ + + This will remove delta values from every column. + + +1.1.7 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. + + +1.1.8 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. + + +1.1.9 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'. + + +◊ 1.1.9.1 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. + + + ◊ 1.1.9.1.1 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}; + └──── + + + ◊ 1.1.9.1.2 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}}); + └──── + + +1.1.10 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. + + +◊ 1.1.10.1 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 { ... } + └──── + + +1.1.11 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. + + +1.2 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'. + + +2 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 |