Add plain-text README file

cgit doesn't render Org files. I think I'll add `*.org' to
`.gitignore' & export to plain text for README. My website will still
have the html version.

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