about summary refs log tree commit diff stats
path: root/README
blob: 39776dddf5591ea634d55844fc840c80e0e08bd9 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
                               ━━━━━━━━━
                                  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>