factbook 1.1.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. checksums.yaml +4 -4
  2. data/{HISTORY.md → CHANGELOG.md} +3 -3
  3. data/Manifest.txt +23 -1
  4. data/README.md +548 -568
  5. data/Rakefile +34 -33
  6. data/data/attributes.yml +337 -0
  7. data/data/categories.csv +1 -1
  8. data/data/codes.csv +262 -262
  9. data/data/codesxref.csv +280 -280
  10. data/lib/factbook.rb +68 -60
  11. data/lib/factbook/almanac.rb +72 -0
  12. data/lib/factbook/attributes.rb +74 -0
  13. data/lib/factbook/builder.rb +39 -41
  14. data/lib/factbook/builder_item.rb +95 -62
  15. data/lib/factbook/builder_json.rb +79 -0
  16. data/lib/factbook/counter.rb +48 -0
  17. data/lib/factbook/normalize.rb +43 -0
  18. data/lib/factbook/page.rb +52 -97
  19. data/lib/factbook/page_info.rb +12 -0
  20. data/lib/factbook/reader_json.rb +51 -0
  21. data/lib/factbook/sanitizer.rb +125 -161
  22. data/lib/factbook/utils_info.rb +37 -10
  23. data/lib/factbook/version.rb +21 -22
  24. data/script/almanac.rb +48 -0
  25. data/script/attributes.rb +34 -0
  26. data/script/build.rb +28 -0
  27. data/script/counter.rb +145 -0
  28. data/script/json.rb +19 -0
  29. data/test/data/json/au.json +892 -0
  30. data/test/data/src/ag.html +716 -0
  31. data/test/data/src/au-2015-09-24.html +2006 -0
  32. data/test/data/src/au.html +318 -1666
  33. data/test/data/src/be-2015-09-24.html +2011 -0
  34. data/test/data/src/be.html +273 -1636
  35. data/test/helper.rb +11 -11
  36. data/test/test_attribs.rb +53 -17
  37. data/test/test_attribs_def.rb +20 -0
  38. data/test/test_counter.rb +31 -0
  39. data/test/test_fields.rb +52 -52
  40. data/test/test_importer.rb +6 -5
  41. data/test/test_json.rb +45 -44
  42. data/test/test_json_builder.rb +25 -0
  43. data/test/test_normalize.rb +23 -0
  44. data/test/test_page.rb +38 -38
  45. data/test/test_sanitizer.rb +9 -5
  46. data/test/test_sanitizer_regex.rb +89 -0
  47. metadata +54 -12
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 24d96765bcda05d51ce7f72baa5f565da45aa85b
4
- data.tar.gz: 7841f960d9905ad051c6ef255f374ed875091f88
3
+ metadata.gz: 644b296946acd4f2c6993fd8b6f35342058e14f5
4
+ data.tar.gz: 2ee8bfffd3efe837e42dc400434f40fe5359a0a9
5
5
  SHA512:
6
- metadata.gz: 93fac1f61de8fcd72e98afb4ed5bb6619cb849fac69ef979c2a5703fd2886a0cf8b6a9c260cb179c3209d6d61a57170ac7dc11e81c59928ec3532efcbf212180
7
- data.tar.gz: 5e84df0a02a7278b9cb54f19fd02364abe302c78a1aa222b334e3844141b13d82c10e1e51b53d5a906bbb8f43ee59cd44b02abde2aff58c6f1cff37355346ce8
6
+ metadata.gz: f5e0b528262e1f5399eed7b6cebcace7a8311025212c1be05c266e5f6cf479e852d6682d566f3759d714cf6d37b39ac29692e4cb8d6c13352336768d270eff42
7
+ data.tar.gz: 25c5c82128a134f68ec139e031b2825c5e820cb2e21f42c10d41430b702693e7cfd9a9a248e5c3f5b899f159e34bc02980f77eed8130414f54bc94e4d68a8b79
data/{HISTORY.md → CHANGELOG.md} RENAMED
@@ -1,3 +1,3 @@
1
- ### 0.0.1 / 2014-07-07
2
-
3
- * Everything is new. First release.
1
+ ### 0.0.1 / 2014-07-07
2
+
3
+ * Everything is new. First release.
data/Manifest.txt CHANGED
@@ -1,20 +1,28 @@
1
- HISTORY.md
1
+ CHANGELOG.md
2
2
  Manifest.txt
3
3
  README.md
4
4
  Rakefile
5
+ data/attributes.yml
5
6
  data/categories.csv
6
7
  data/codes.csv
7
8
  data/codesxref.csv
8
9
  data/comparisons.csv
9
10
  lib/factbook.rb
11
+ lib/factbook/almanac.rb
12
+ lib/factbook/attributes.rb
10
13
  lib/factbook/builder.rb
11
14
  lib/factbook/builder_item.rb
15
+ lib/factbook/builder_json.rb
12
16
  lib/factbook/codes.rb
13
17
  lib/factbook/comparisons.rb
18
+ lib/factbook/counter.rb
14
19
  lib/factbook/db/importer.rb
15
20
  lib/factbook/db/models.rb
16
21
  lib/factbook/db/schema.rb
22
+ lib/factbook/normalize.rb
17
23
  lib/factbook/page.rb
24
+ lib/factbook/page_info.rb
25
+ lib/factbook/reader_json.rb
18
26
  lib/factbook/sanitizer.rb
19
27
  lib/factbook/sect.rb
20
28
  lib/factbook/subsect.rb
@@ -22,23 +30,37 @@ lib/factbook/table.rb
22
30
  lib/factbook/utils.rb
23
31
  lib/factbook/utils_info.rb
24
32
  lib/factbook/version.rb
33
+ script/almanac.rb
34
+ script/attributes.rb
35
+ script/build.rb
36
+ script/counter.rb
37
+ script/json.rb
25
38
  script/testbr.rb
26
39
  script/testcodes.rb
27
40
  test/data/au.html
28
41
  test/data/au.yml
29
42
  test/data/be.html
30
43
  test/data/be.yml
44
+ test/data/json/au.json
45
+ test/data/src/ag.html
46
+ test/data/src/au-2015-09-24.html
31
47
  test/data/src/au.html
48
+ test/data/src/be-2015-09-24.html
32
49
  test/data/src/be.html
33
50
  test/helper.rb
34
51
  test/test_attribs.rb
52
+ test/test_attribs_def.rb
35
53
  test/test_builder.rb
36
54
  test/test_codes.rb
37
55
  test/test_comparisons.rb
38
56
  test/test_convert.rb
57
+ test/test_counter.rb
39
58
  test/test_fields.rb
40
59
  test/test_importer.rb
41
60
  test/test_item_builder.rb
42
61
  test/test_json.rb
62
+ test/test_json_builder.rb
63
+ test/test_normalize.rb
43
64
  test/test_page.rb
44
65
  test/test_sanitizer.rb
66
+ test/test_sanitizer_regex.rb
data/README.md CHANGED
@@ -1,568 +1,548 @@
1
- # factbook - scripts for the world factbook (get open structured data e.g JSON etc.)
2
-
3
- * home :: [github.com/worlddb/factbook](https://github.com/worlddb/factbook)
4
- * bugs :: [github.com/worlddb/factbook/issues](https://github.com/worlddb/factbook/issues)
5
- * gem :: [rubygems.org/gems/factbook](https://rubygems.org/gems/factbook)
6
- * rdoc :: [rubydoc.info/gems/factbook](http://rubydoc.info/gems/factbook)
7
- * forum :: [groups.google.com/group/openmundi](https://groups.google.com/group/openmundi)
8
-
9
-
10
-
11
- ## What's the World Factbook?
12
-
13
- The World Factbook [1][2] published by the Central Intelligence Agency (CIA)
14
- offers free country profiles in the public domain (that is, no copyright(s), no rights reserved).
15
-
16
- - [1] [The World Factbook](https://www.cia.gov/library/publications/the-world-factbook/)
17
- - [2] [Wikipedia Article: The World Factbook](http://en.wikipedia.org/wiki/The_World_Factbook)
18
-
19
-
20
- ## Usage
21
-
22
- ### Get country profile page as a hash (that is, structured data e.g. nested key/values)
23
-
24
- ```ruby
25
- page = Factbook::Page.new( 'br' ) # br is the country code for Brazil
26
- pp page.data # pretty print hash
27
- ```
28
-
29
- resulting in:
30
-
31
- ```ruby
32
- {"Introduction"=>
33
- {"Background"=>
34
- {"text"=>
35
- "Following more than three centuries under Portuguese rule,
36
- Brazil gained its independence in 1822, ..."}},
37
- "Geography"=>
38
- {"Location"=>{"text"=>"Eastern South America, bordering the Atlantic Ocean"},
39
- "Geographic coordinates"=>{"text"=>"10 00 S, 55 00 W"},
40
- "Map references"=>{"text"=>"South America"},
41
- "Area"=>
42
- {"total"=>{"text"=>"8,515,770 sq km"},
43
- "land"=>{"text"=>"8,358,140 sq km"},
44
- "water"=>{"text"=>"157,630 sq km"},
45
- "note"=>
46
- {"text"=>
47
- "includes Arquipelago de Fernando de Noronha, Atol das Rocas, ..."}},
48
- "Area - comparative"=>
49
- {"text"=>"slightly smaller than the US"},
50
- "Land boundaries"=>
51
- {"total"=>{"text"=>"16,145 km"},
52
- "border countries (10)"=>
53
- {"text"=>
54
- "Argentina 1,263 km, Bolivia 3,403 km, Colombia 1,790 km,
55
- French Guiana 649 km, Guyana 1,308 km, Paraguay 1,371 km, Peru 2,659 km,
56
- Suriname 515 km, Uruguay 1,050 km, Venezuela 2,137 km"}},
57
- "Climate"=>{"text"=>"mostly tropical, but temperate in south"},
58
- "Elevation extremes"=>
59
- {"lowest point"=>{"text"=>"Atlantic Ocean 0 m"},
60
- "highest point"=>{"text"=>"Pico da Neblina 2,994 m"}},
61
- "Natural resources"=>
62
- {"text"=>
63
- "bauxite, gold, iron ore, manganese, nickel, phosphates, ..."},
64
- ...
65
- ```
66
-
67
- ### Use shortcut attribute accessors
68
-
69
- ```ruby
70
- pp page.background ## same as page['Introduction']['Background']['text']
71
- # => "Following more than three centuries..."
72
- pp page.area ## same as page['Geography'][''Area']['total']['text']
73
- # => "8,515,770 sq km"
74
- pp page.area_land ## same as page['Geography'][''Area']['land']['text']
75
- # => "8,358,140 sq km"
76
- pp page.area_water ## same as page['Geography'][''Area']['water']['text']
77
- # => "157,630 sq km"
78
- pp page.area_note ## same as page['Geography'][''Area']['note']['text']
79
- # => "includes Arquipelago de Fernando de Noronha, Atol das Rocas, ..."
80
- pp page.area_comparative ## same as page['Geography']['Area - comparative']['text']
81
- # => "slightly smaller than the US"
82
- pp page.climate ## same as page['Geography']['Climate']['text']
83
- # => "mostly tropical, but temperate in south"
84
- pp page.terrain ## same as page['Geography']['Terrain']['text']
85
- # => "mostly flat to rolling lowlands in north; ..."
86
- pp page.elevation_lowest ## same as page['Geography']['Elevation extremes']['lowest point']['text']
87
- # => "Atlantic Ocean 0 m"
88
- pp page.elevation_highest ## same as page['Geography']['Elevation extremes']['highest point']['text']
89
- # => "Pico da Neblina 2,994 m"
90
- pp page.resources ## same as page['Geography'][Natural resources']['text']
91
- # => "bauxite, gold, iron ore, manganese, nickel, phosphates, ..."
92
- ...
93
- ```
94
-
95
- ### Save to disk as JSON
96
-
97
- ```ruby
98
- page = Factbook::Page.new( 'br' )
99
- File.open( 'br.json', 'w') do |f|
100
- f.write page.to_json
101
- end
102
- ```
103
-
104
-
105
- ### List all codes
106
-
107
- ```ruby
108
- Factbook.codes.each do |code|
109
- pp code
110
- end
111
- ```
112
-
113
- resulting in:
114
-
115
- ```ruby
116
- #<struct Factbook::Codes::Code
117
- code="af",
118
- name="Afghanistan",
119
- category="Countries",
120
- region="South Asia">
121
- #<struct Factbook::Codes::Code
122
- code="al",
123
- name="Albania",
124
- category="Countries",
125
- region="Europe">
126
- #<struct Factbook::Codes::Code
127
- code="ag",
128
- name="Algeria",
129
- category="Countries",
130
- region="Africa">
131
- #<struct Factbook::Codes::Code
132
- code="an",
133
- name="Andorra",
134
- category="Countries",
135
- region="Europe">
136
- ...
137
- ```
138
-
139
- Note: You can filter codes by category e.g. Countries, Dependencies, Miscellaneous, Oceans, etc.
140
- and/or by region e.g. Africa, Europe, South Asia, Central America and Caribbean, etc.
141
-
142
-
143
- ```ruby
144
-
145
- assert_equal 261, Factbook.codes.size
146
-
147
- ## categories
148
- assert_equal 195, Factbook.codes.countries.size
149
- assert_equal 52, Factbook.codes.dependencies.size
150
- assert_equal 5, Factbook.codes.oceans.size
151
- assert_equal 1, Factbook.codes.world.size
152
- assert_equal 2, Factbook.codes.others.size
153
- assert_equal 6, Factbook.codes.misc.size
154
-
155
- ## regions
156
- assert_equal 55, Factbook.codes.europe.size
157
- assert_equal 9, Factbook.codes.south_asia.size
158
- assert_equal 6, Factbook.codes.central_asia.size
159
- assert_equal 22, Factbook.codes.east_n_souteast_asia.size
160
- assert_equal 19, Factbook.codes.middle_east.size
161
- assert_equal 56, Factbook.codes.africa.size
162
- assert_equal 7, Factbook.codes.north_america.size
163
- assert_equal 33, Factbook.codes.central_america_n_caribbean.size
164
- assert_equal 14, Factbook.codes.south_america.size
165
- assert_equal 30, Factbook.codes.australia_oceania.size
166
- assert_equal 4, Factbook.codes.antartica.size
167
- assert_equal 5, Factbook.codes.region('Oceans').size
168
- assert_equal 1, Factbook.codes.region('World').size
169
-
170
- ## categories + regions
171
- assert_equal 45, Factbook.codes.countries.europe.size
172
- ...
173
- ```
174
-
175
-
176
- ## The World Factbook Summary (267 Entries)
177
-
178
- The World Factbook includes 267 entries -
179
- 195 sovereign countries /
180
- 2 others /
181
- 58 dependencies /
182
- 6 miscellaneous /
183
- 5 oceans /
184
- 1 world:
185
-
186
-
187
- ### Sovereign Countries (195)
188
-
189
- **A**
190
- `af` Afghanistan
191
- `al` Albania
192
- `ag` Algeria
193
- `an` Andorra
194
- `ao` Angola
195
- `ac` Antigua and Barbuda
196
- `ar` Argentina
197
- `am` Armenia
198
- `as` Australia
199
- `au` Austria
200
- `aj` Azerbaijan
201
- **B**
202
- `bf` The Bahamas
203
- `ba` Bahrain
204
- `bg` Bangladesh
205
- `bb` Barbados
206
- `bo` Belarus
207
- `be` Belgium
208
- `bh` Belize
209
- `bn` Benin
210
- `bt` Bhutan
211
- `bl` Bolivia
212
- `bk` Bosnia and Herzegovina
213
- `bc` Botswana
214
- `br` Brazil
215
- `bx` Brunei
216
- `bu` Bulgaria
217
- `uv` Burkina Faso
218
- `bm` Burma
219
- `by` Burundi
220
- **C**
221
- `cb` Cambodia
222
- `cm` Cameroon
223
- `ca` Canada
224
- `cv` Cape Verde
225
- `ct` Central African Republic
226
- `cd` Chad
227
- `ci` Chile
228
- `ch` China
229
- `co` Colombia
230
- `cn` Comoros
231
- `cg` Congo DR
232
- `cf` Congo
233
- `cs` Costa Rica
234
- `iv` Cote d'Ivoire
235
- `hr` Croatia
236
- `cu` Cuba
237
- `cy` Cyprus
238
- `ez` Czech Republic
239
- **D**
240
- `da` Denmark
241
- `dj` Djibouti
242
- `do` Dominica
243
- `dr` Dominican Republic
244
- **E**
245
- `ec` Ecuador
246
- `eg` Egypt
247
- `es` El Salvador
248
- `ek` Equatorial Guinea
249
- `er` Eritrea
250
- `en` Estonia
251
- `et` Ethiopia
252
- **F**
253
- `fj` Fiji
254
- `fi` Finland
255
- `fr` France
256
- **G**
257
- `gb` Gabon
258
- `ga` The Gambia
259
- `gg` Georgia
260
- `gm` Germany
261
- `gh` Ghana
262
- `gr` Greece
263
- `gj` Grenada
264
- `gt` Guatemala
265
- `gv` Guinea
266
- `pu` Guinea-Bissau
267
- `gy` Guyana
268
- **H**
269
- `ha` Haiti
270
- `ho` Honduras
271
- `hu` Hungary
272
- **I**
273
- `ic` Iceland
274
- `in` India
275
- `id` Indonesia
276
- `ir` Iran
277
- `iz` Iraq
278
- `ei` Ireland
279
- `is` Israel
280
- `it` Italy
281
- **J**
282
- `jm` Jamaica
283
- `ja` Japan
284
- `jo` Jordan
285
- **K**
286
- `kz` Kazakhstan
287
- `ke` Kenya
288
- `kr` Kiribati
289
- `kn` North Korea
290
- `ks` South Korea
291
- `kv` Kosovo
292
- `ku` Kuwait
293
- `kg` Kyrgyzstan
294
- **L**
295
- `la` Laos
296
- `lg` Latvia
297
- `le` Lebanon
298
- `lt` Lesotho
299
- `li` Liberia
300
- `ly` Libya
301
- `ls` Liechtenstein
302
- `lh` Lithuania
303
- `lu` Luxembourg
304
- **M**
305
- `mk` Macedonia
306
- `ma` Madagascar
307
- `mi` Malawi
308
- `my` Malaysia
309
- `mv` Maldives
310
- `ml` Mali
311
- `mt` Malta
312
- `rm` Marshall Islands
313
- `mr` Mauritania
314
- `mp` Mauritius
315
- `mx` Mexico
316
- `fm` Micronesia
317
- `md` Moldova
318
- `mn` Monaco
319
- `mg` Mongolia
320
- `mj` Montenegro
321
- `mo` Morocco
322
- `mz` Mozambique
323
- **N**
324
- `wa` Namibia
325
- `nr` Nauru
326
- `np` Nepal
327
- `nl` Netherlands
328
- `nz` New Zealand
329
- `nu` Nicaragua
330
- `ng` Niger
331
- `ni` Nigeria
332
- `no` Norway
333
- **O**
334
- `mu` Oman
335
- **P**
336
- `pk` Pakistan
337
- `ps` Palau
338
- `pm` Panama
339
- `pp` Papua New Guinea
340
- `pa` Paraguay
341
- `pe` Peru
342
- `rp` Philippines
343
- `pl` Poland
344
- `po` Portugal
345
- **Q**
346
- `qa` Qatar
347
- **R**
348
- `ro` Romania
349
- `rs` Russia
350
- `rw` Rwanda
351
- **S**
352
- `sc` Saint Kitts and Nevis
353
- `st` Saint Lucia
354
- `vc` Saint Vincent and the Grenadines
355
- `ws` Samoa
356
- `sm` San Marino
357
- `tp` Sao Tome and Principe
358
- `sa` Saudi Arabia
359
- `sg` Senegal
360
- `ri` Serbia
361
- `se` Seychelles
362
- `sl` Sierra Leone
363
- `sn` Singapore
364
- `lo` Slovakia
365
- `si` Slovenia
366
- `bp` Solomon Islands
367
- `so` Somalia
368
- `sf` South Africa
369
- `od` South Sudan
370
- `sp` Spain
371
- `ce` Sri Lanka
372
- `su` Sudan
373
- `ns` Suriname
374
- `wz` Swaziland
375
- `sw` Sweden
376
- `sz` Switzerland
377
- `sy` Syria
378
- **T**
379
- `ti` Tajikistan
380
- `tz` Tanzania
381
- `th` Thailand
382
- `tt` Timor-Leste
383
- `to` Togo
384
- `tn` Tonga
385
- `td` Trinidad and Tobago
386
- `ts` Tunisia
387
- `tu` Turkey
388
- `tx` Turkmenistan
389
- `tv` Tuvalu
390
- **U**
391
- `ug` Uganda
392
- `up` Ukraine
393
- `ae` United Arab Emirates
394
- `uk` United Kingdom
395
- `us` United States
396
- `uy` Uruguay
397
- `uz` Uzbekistan
398
- **V**
399
- `nh` Vanuatu
400
- `vt` Vatican City (Holy See)
401
- `ve` Venezuela
402
- `vm` Vietnam
403
- **Y**
404
- `ym` Yemen
405
- **Z**
406
- `za` Zambia
407
- `zi` Zimbabwe
408
-
409
-
410
- ### Other (2)
411
-
412
- `tw` Taiwan
413
- `ee` European Union
414
-
415
- ### Dependencies (58)
416
-
417
- Australia (6):
418
- `at` Ashmore and Cartier Islands
419
- `kt` Christmas Island
420
- `ck` Cocos (Keeling) Islands
421
- `cr` Coral Sea Islands
422
- `hm` Heard Island and McDonald Islands
423
- `nf` Norfolk Island
424
-
425
- China (2):
426
- `hk` Hong Kong
427
- `mc` Macau
428
-
429
- Denmark (2):
430
- `fo` Faroe Islands
431
- `gl` Greenland
432
-
433
- France (8):
434
- `ip` Clipperton Island
435
- `fp` French Polynesia
436
- `fs` French Southern and Antarctic Lands
437
- `nc` New Caledonia
438
- `tb` Saint Barthelemy
439
- `rn` Saint Martin
440
- `sb` Saint Pierre and Miquelon
441
- `wf` Wallis and Futuna
442
-
443
- Netherlands (3):
444
- `aa` Aruba
445
- `uc` Curacao
446
- `nn` Sint Maarten
447
-
448
- New Zealand (3):
449
- `cw` Cook Islands
450
- `ne` Niue
451
- `tl` Tokelau
452
-
453
- Norway (3):
454
- `bv` Bouvet Island
455
- `jn` Jan Mayen
456
- `sv` Svalbard
457
-
458
- Great Britain (17):
459
- `ax` Akrotiri (Sovereign Base)
460
- `av` Anguilla
461
- `bd` Bermuda
462
- `io` British Indian Ocean Territory
463
- `vi` British Virgin Islands
464
- `cj` Cayman Islands
465
- `dx` Dhekelia (Sovereign Base)
466
- `fk` Falkland Islands
467
- `gi` Gibraltar
468
- `gk` Guernsey
469
- `je` Jersey
470
- `im` Isle of Man
471
- `mh` Montserrat
472
- `pc` Pitcairn Islands
473
- `sh` Saint Helena
474
- `sx` South Georgia and the South Sandwich Islands
475
- `tk` Turks and Caicos Islands
476
-
477
- United States (14):
478
- `aq` American Samoa
479
- `gq` Guam
480
- `bq` Navassa Island
481
- `cq` Northern Mariana Islands
482
- `rq` Puerto Rico
483
- `vq` US Virgin Islands
484
- `wq` Wake Island
485
- `um` US Pacific Island Wildlife Refuges
486
- (Baker Island, Howland Island, Jarvis Island, Johnston Atoll, Kingman Reef, Midway Islands, Palmyra Atoll)
487
-
488
-
489
- ### Miscellaneous (6)
490
-
491
- `ay` Antarctica
492
- `gz` Gaza Strip
493
- `pf` Paracel Islands
494
- `pg` Spratly Islands
495
- `we` West Bank
496
- `wi` Western Sahara
497
-
498
- ### Oceans (5)
499
-
500
- `xq` Arctic Ocean
501
- `zh` Atlantic Ocean
502
- `xo` Indian Ocean
503
- `zn` Pacific Ocean
504
- `oo` Southern Ocean
505
-
506
- ### World (1)
507
-
508
- `xx` World
509
-
510
-
511
-
512
-
513
- ## Ready-To-Use Public Domain Factbook Datasets
514
-
515
- [factbook/factbook.json](https://github.com/factbook/factbook.json) - open (public domain)
516
- factbook country profiles in JSON for all the world's countries (using internet domain names
517
- for country codes e.g. Austria is `at.json` not `au.json`, Germany is `de.json` not `gm.json` and so on)
518
-
519
-
520
-
521
- ## Alternatives (Libraries and Gems)
522
-
523
- Ruby
524
-
525
- - [worldfactbook gem](https://github.com/sayem/worldfactbook)
526
- by Sayem Khan (aka sayem);
527
- fetches data from its own mirror, that is, [rubyworldfactbook.com](http://rubyworldfactbook.com)
528
- (last updated 2011?)
529
-
530
- - [the_country_identity gem](https://github.com/p1nox/the_country_identity)
531
- by Raul Pino (aka p1nox);
532
- fetches data from an [RDF Turtle endpoint](http://wifo5-03.informatik.uni-mannheim.de/factbook/)
533
- hosted by the Research Group Data and Web Science at the University of Mannheim, Germany
534
-
535
- JavaScript
536
-
537
- - [worldfactbook-dataset](https://github.com/twigkit/worldfactbook-dataset)
538
- by Richard Marr (aka richmarr); fetches data using Node.js
539
- (last updated 2013)
540
-
541
- Python
542
-
543
- - [openfactbook datasets & tools](https://github.com/openfactbook)
544
- by Eckhard Licher; uses official (offline) download archive (last updated 2014); incl. flags, maps, and more
545
-
546
- Others
547
-
548
- TBD
549
-
550
-
551
-
552
- ## Install
553
-
554
- Just install the gem:
555
-
556
- $ gem install factbook
557
-
558
-
559
- ## License
560
-
561
- The `factbook` scripts are dedicated to the public domain.
562
- Use it as you please with no restrictions whatsoever.
563
-
564
-
565
- ## Questions? Comments?
566
-
567
- Send them along to the [Open Mundi (world.db) Database Forum/Mailing List](http://groups.google.com/group/openmundi).
568
- Thanks!
1
+ # factbook - scripts for the world factbook (get open structured data e.g JSON etc.)
2
+
3
+ * home :: [github.com/factbook/factbook](https://github.com/factbook/factbook)
4
+ * bugs :: [github.com/factbook/factbook/issues](https://github.com/factbook/factbook/issues)
5
+ * gem :: [rubygems.org/gems/factbook](https://rubygems.org/gems/factbook)
6
+ * rdoc :: [rubydoc.info/gems/factbook](http://rubydoc.info/gems/factbook)
7
+ * forum :: [groups.google.com/group/openmundi](https://groups.google.com/group/openmundi)
8
+
9
+
10
+
11
+ ## What's the World Factbook?
12
+
13
+ The World Factbook [1][2] published by the Central Intelligence Agency (CIA)
14
+ offers free country profiles in the public domain (that is, no copyright(s), no rights reserved).
15
+
16
+ - [1] [The World Factbook](https://www.cia.gov/library/publications/the-world-factbook/)
17
+ - [2] [Wikipedia Article: The World Factbook](http://en.wikipedia.org/wiki/The_World_Factbook)
18
+
19
+
20
+ ## Usage
21
+
22
+ ### Get country profile page as a hash (that is, structured data e.g. nested key/values)
23
+
24
+ ```ruby
25
+ page = Factbook::Page.new( 'br' ) # br is the country code for Brazil
26
+ pp page.data # pretty print hash
27
+ ```
28
+
29
+ resulting in:
30
+
31
+ ```ruby
32
+ {"Introduction"=>
33
+ {"Background"=>
34
+ {"text"=>
35
+ "Following more than three centuries under Portuguese rule,
36
+ Brazil gained its independence in 1822, ..."}},
37
+ "Geography"=>
38
+ {"Location"=>{"text"=>"Eastern South America, bordering the Atlantic Ocean"},
39
+ "Geographic coordinates"=>{"text"=>"10 00 S, 55 00 W"},
40
+ "Map references"=>{"text"=>"South America"},
41
+ "Area"=>
42
+ {"total"=>{"text"=>"8,515,770 sq km"},
43
+ "land"=>{"text"=>"8,358,140 sq km"},
44
+ "water"=>{"text"=>"157,630 sq km"},
45
+ "note"=>
46
+ {"text"=>
47
+ "includes Arquipelago de Fernando de Noronha, Atol das Rocas, ..."}},
48
+ "Area - comparative"=>
49
+ {"text"=>"slightly smaller than the US"},
50
+ "Land boundaries"=>
51
+ {"total"=>{"text"=>"16,145 km"},
52
+ "border countries (10)"=>
53
+ {"text"=>
54
+ "Argentina 1,263 km, Bolivia 3,403 km, Colombia 1,790 km,
55
+ French Guiana 649 km, Guyana 1,308 km, Paraguay 1,371 km, Peru 2,659 km,
56
+ Suriname 515 km, Uruguay 1,050 km, Venezuela 2,137 km"}},
57
+ "Climate"=>{"text"=>"mostly tropical, but temperate in south"},
58
+ "Elevation extremes"=>
59
+ {"lowest point"=>{"text"=>"Atlantic Ocean 0 m"},
60
+ "highest point"=>{"text"=>"Pico da Neblina 2,994 m"}},
61
+ "Natural resources"=>
62
+ {"text"=>
63
+ "bauxite, gold, iron ore, manganese, nickel, phosphates, ..."},
64
+ ...
65
+ ```
66
+
67
+ ### Use shortcut attribute accessors
68
+
69
+ ```ruby
70
+ pp page.background ## same as page['Introduction']['Background']['text']
71
+ # => "Following more than three centuries..."
72
+ pp page.area ## same as page['Geography'][''Area']['total']['text']
73
+ # => "8,515,770 sq km"
74
+ pp page.area_land ## same as page['Geography'][''Area']['land']['text']
75
+ # => "8,358,140 sq km"
76
+ pp page.area_water ## same as page['Geography'][''Area']['water']['text']
77
+ # => "157,630 sq km"
78
+ pp page.area_note ## same as page['Geography'][''Area']['note']['text']
79
+ # => "includes Arquipelago de Fernando de Noronha, Atol das Rocas, ..."
80
+ pp page.area_comparative ## same as page['Geography']['Area - comparative']['text']
81
+ # => "slightly smaller than the US"
82
+ pp page.climate ## same as page['Geography']['Climate']['text']
83
+ # => "mostly tropical, but temperate in south"
84
+ pp page.terrain ## same as page['Geography']['Terrain']['text']
85
+ # => "mostly flat to rolling lowlands in north; ..."
86
+ pp page.elevation_lowest ## same as page['Geography']['Elevation extremes']['lowest point']['text']
87
+ # => "Atlantic Ocean 0 m"
88
+ pp page.elevation_highest ## same as page['Geography']['Elevation extremes']['highest point']['text']
89
+ # => "Pico da Neblina 2,994 m"
90
+ pp page.resources ## same as page['Geography'][Natural resources']['text']
91
+ # => "bauxite, gold, iron ore, manganese, nickel, phosphates, ..."
92
+ ...
93
+ ```
94
+
95
+ See [`data/attributes.yml`](data/attributes.yml) for the full listing of all built-in attribute shortcut accessors.
96
+ See [Attributes](ATTRIBUTES.md) for a quick reference listing.
97
+
98
+
99
+ ### Save to disk as JSON
100
+
101
+ ```ruby
102
+ page = Factbook::Page.new( 'br' )
103
+ File.open( 'br.json', 'w:utf-8') do |f|
104
+ f.write page.to_json
105
+ end
106
+ ```
107
+
108
+
109
+ ### List all codes
110
+
111
+ ```ruby
112
+ Factbook.codes.each do |code|
113
+ pp code
114
+ end
115
+ ```
116
+
117
+ resulting in:
118
+
119
+ ```
120
+ #<struct Factbook::Codes::Code
121
+ code ="af",
122
+ name ="Afghanistan",
123
+ category="Countries",
124
+ region ="South Asia">
125
+ #<struct Factbook::Codes::Code
126
+ code ="al",
127
+ name ="Albania",
128
+ category="Countries",
129
+ region ="Europe">
130
+ #<struct Factbook::Codes::Code
131
+ code ="ag",
132
+ name ="Algeria",
133
+ category="Countries",
134
+ region ="Africa">
135
+ #<struct Factbook::Codes::Code
136
+ code ="an",
137
+ name ="Andorra",
138
+ category="Countries",
139
+ region ="Europe">
140
+ ...
141
+ ```
142
+
143
+ Note: You can filter codes by category e.g. Countries, Dependencies, Miscellaneous, Oceans, etc.
144
+ and/or by region e.g. Africa, Europe, South Asia, Central America and Caribbean, etc.
145
+
146
+
147
+ ```ruby
148
+
149
+ assert_equal 261, Factbook.codes.size
150
+
151
+ ## categories
152
+ assert_equal 195, Factbook.codes.countries.size
153
+ assert_equal 52, Factbook.codes.dependencies.size
154
+ assert_equal 5, Factbook.codes.oceans.size
155
+ assert_equal 1, Factbook.codes.world.size
156
+ assert_equal 2, Factbook.codes.others.size
157
+ assert_equal 6, Factbook.codes.misc.size
158
+
159
+ ## regions
160
+ assert_equal 55, Factbook.codes.europe.size
161
+ assert_equal 9, Factbook.codes.south_asia.size
162
+ assert_equal 6, Factbook.codes.central_asia.size
163
+ assert_equal 22, Factbook.codes.east_n_souteast_asia.size
164
+ assert_equal 19, Factbook.codes.middle_east.size
165
+ assert_equal 56, Factbook.codes.africa.size
166
+ assert_equal 7, Factbook.codes.north_america.size
167
+ assert_equal 33, Factbook.codes.central_america_n_caribbean.size
168
+ assert_equal 14, Factbook.codes.south_america.size
169
+ assert_equal 30, Factbook.codes.australia_oceania.size
170
+ assert_equal 4, Factbook.codes.antartica.size
171
+ assert_equal 5, Factbook.codes.region('Oceans').size
172
+ assert_equal 1, Factbook.codes.region('World').size
173
+
174
+ ## categories + regions
175
+ assert_equal 45, Factbook.codes.countries.europe.size
176
+ ...
177
+ ```
178
+
179
+ See [`data/codes.csv`](data/codes.csv) for the built-in listing of all codes with categories and regions.
180
+
181
+
182
+
183
+ ## The World Factbook Summary (267 Entries)
184
+
185
+ The World Factbook includes 267 entries -
186
+ 195 sovereign countries /
187
+ 2 others /
188
+ 58 dependencies /
189
+ 6 miscellaneous /
190
+ 5 oceans /
191
+ 1 world:
192
+
193
+
194
+ ### Sovereign Countries (195)
195
+
196
+ **A**
197
+ `af` Afghanistan
198
+ `al` Albania
199
+ `ag` Algeria
200
+ `an` Andorra
201
+ `ao` Angola
202
+ `ac` Antigua and Barbuda
203
+ `ar` Argentina
204
+ `am` Armenia
205
+ `as` Australia
206
+ `au` Austria
207
+ `aj` Azerbaijan
208
+ **B**
209
+ `bf` The Bahamas
210
+ `ba` Bahrain
211
+ `bg` Bangladesh
212
+ `bb` Barbados
213
+ `bo` Belarus
214
+ `be` Belgium
215
+ `bh` Belize
216
+ `bn` Benin
217
+ `bt` Bhutan
218
+ `bl` Bolivia
219
+ `bk` Bosnia and Herzegovina
220
+ `bc` Botswana
221
+ `br` Brazil
222
+ `bx` Brunei
223
+ `bu` Bulgaria
224
+ `uv` Burkina Faso
225
+ `bm` Burma
226
+ `by` Burundi
227
+ **C**
228
+ `cb` Cambodia
229
+ `cm` Cameroon
230
+ `ca` Canada
231
+ `cv` Cape Verde
232
+ `ct` Central African Republic
233
+ `cd` Chad
234
+ `ci` Chile
235
+ `ch` China
236
+ `co` Colombia
237
+ `cn` Comoros
238
+ `cg` Congo DR
239
+ `cf` Congo
240
+ `cs` Costa Rica
241
+ `iv` Cote d'Ivoire
242
+ `hr` Croatia
243
+ `cu` Cuba
244
+ `cy` Cyprus
245
+ `ez` Czech Republic
246
+ **D**
247
+ `da` Denmark
248
+ `dj` Djibouti
249
+ `do` Dominica
250
+ `dr` Dominican Republic
251
+ **E**
252
+ `ec` Ecuador
253
+ `eg` Egypt
254
+ `es` El Salvador
255
+ `ek` Equatorial Guinea
256
+ `er` Eritrea
257
+ `en` Estonia
258
+ `et` Ethiopia
259
+ **F**
260
+ `fj` Fiji
261
+ `fi` Finland
262
+ `fr` France
263
+ **G**
264
+ `gb` Gabon
265
+ `ga` The Gambia
266
+ `gg` Georgia
267
+ `gm` Germany
268
+ `gh` Ghana
269
+ `gr` Greece
270
+ `gj` Grenada
271
+ `gt` Guatemala
272
+ `gv` Guinea
273
+ `pu` Guinea-Bissau
274
+ `gy` Guyana
275
+ **H**
276
+ `ha` Haiti
277
+ `ho` Honduras
278
+ `hu` Hungary
279
+ **I**
280
+ `ic` Iceland
281
+ `in` India
282
+ `id` Indonesia
283
+ `ir` Iran
284
+ `iz` Iraq
285
+ `ei` Ireland
286
+ `is` Israel
287
+ `it` Italy
288
+ **J**
289
+ `jm` Jamaica
290
+ `ja` Japan
291
+ `jo` Jordan
292
+ **K**
293
+ `kz` Kazakhstan
294
+ `ke` Kenya
295
+ `kr` Kiribati
296
+ `kn` North Korea
297
+ `ks` South Korea
298
+ `kv` Kosovo
299
+ `ku` Kuwait
300
+ `kg` Kyrgyzstan
301
+ **L**
302
+ `la` Laos
303
+ `lg` Latvia
304
+ `le` Lebanon
305
+ `lt` Lesotho
306
+ `li` Liberia
307
+ `ly` Libya
308
+ `ls` Liechtenstein
309
+ `lh` Lithuania
310
+ `lu` Luxembourg
311
+ **M**
312
+ `mk` Macedonia
313
+ `ma` Madagascar
314
+ `mi` Malawi
315
+ `my` Malaysia
316
+ `mv` Maldives
317
+ `ml` Mali
318
+ `mt` Malta
319
+ `rm` Marshall Islands
320
+ `mr` Mauritania
321
+ `mp` Mauritius
322
+ `mx` Mexico
323
+ `fm` Micronesia
324
+ `md` Moldova
325
+ `mn` Monaco
326
+ `mg` Mongolia
327
+ `mj` Montenegro
328
+ `mo` Morocco
329
+ `mz` Mozambique
330
+ **N**
331
+ `wa` Namibia
332
+ `nr` Nauru
333
+ `np` Nepal
334
+ `nl` Netherlands
335
+ `nz` New Zealand
336
+ `nu` Nicaragua
337
+ `ng` Niger
338
+ `ni` Nigeria
339
+ `no` Norway
340
+ **O**
341
+ `mu` Oman
342
+ **P**
343
+ `pk` Pakistan
344
+ `ps` Palau
345
+ `pm` Panama
346
+ `pp` Papua New Guinea
347
+ `pa` Paraguay
348
+ `pe` Peru
349
+ `rp` Philippines
350
+ `pl` Poland
351
+ `po` Portugal
352
+ **Q**
353
+ `qa` Qatar
354
+ **R**
355
+ `ro` Romania
356
+ `rs` Russia
357
+ `rw` Rwanda
358
+ **S**
359
+ `sc` Saint Kitts and Nevis
360
+ `st` Saint Lucia
361
+ `vc` Saint Vincent and the Grenadines
362
+ `ws` Samoa
363
+ `sm` San Marino
364
+ `tp` Sao Tome and Principe
365
+ `sa` Saudi Arabia
366
+ `sg` Senegal
367
+ `ri` Serbia
368
+ `se` Seychelles
369
+ `sl` Sierra Leone
370
+ `sn` Singapore
371
+ `lo` Slovakia
372
+ `si` Slovenia
373
+ `bp` Solomon Islands
374
+ `so` Somalia
375
+ `sf` South Africa
376
+ `od` South Sudan
377
+ `sp` Spain
378
+ `ce` Sri Lanka
379
+ `su` Sudan
380
+ `ns` Suriname
381
+ `wz` Swaziland
382
+ `sw` Sweden
383
+ `sz` Switzerland
384
+ `sy` Syria
385
+ **T**
386
+ `ti` Tajikistan
387
+ `tz` Tanzania
388
+ `th` Thailand
389
+ `tt` Timor-Leste
390
+ `to` Togo
391
+ `tn` Tonga
392
+ `td` Trinidad and Tobago
393
+ `ts` Tunisia
394
+ `tu` Turkey
395
+ `tx` Turkmenistan
396
+ `tv` Tuvalu
397
+ **U**
398
+ `ug` Uganda
399
+ `up` Ukraine
400
+ `ae` United Arab Emirates
401
+ `uk` United Kingdom
402
+ `us` United States
403
+ `uy` Uruguay
404
+ `uz` Uzbekistan
405
+ **V**
406
+ `nh` Vanuatu
407
+ `vt` Vatican City (Holy See)
408
+ `ve` Venezuela
409
+ `vm` Vietnam
410
+ **Y**
411
+ `ym` Yemen
412
+ **Z**
413
+ `za` Zambia
414
+ `zi` Zimbabwe
415
+
416
+
417
+ ### Other (2)
418
+
419
+ `tw` Taiwan
420
+ `ee` European Union
421
+
422
+ ### Dependencies (58)
423
+
424
+ Australia (6):
425
+ `at` Ashmore and Cartier Islands
426
+ `kt` Christmas Island
427
+ `ck` Cocos (Keeling) Islands
428
+ `cr` Coral Sea Islands
429
+ `hm` Heard Island and McDonald Islands
430
+ `nf` Norfolk Island
431
+
432
+ China (2):
433
+ `hk` Hong Kong
434
+ `mc` Macau
435
+
436
+ Denmark (2):
437
+ `fo` Faroe Islands
438
+ `gl` Greenland
439
+
440
+ France (8):
441
+ `ip` Clipperton Island
442
+ `fp` French Polynesia
443
+ `fs` French Southern and Antarctic Lands
444
+ `nc` New Caledonia
445
+ `tb` Saint Barthelemy
446
+ `rn` Saint Martin
447
+ `sb` Saint Pierre and Miquelon
448
+ `wf` Wallis and Futuna
449
+
450
+ Netherlands (3):
451
+ `aa` Aruba
452
+ `uc` Curacao
453
+ `nn` Sint Maarten
454
+
455
+ New Zealand (3):
456
+ `cw` Cook Islands
457
+ `ne` Niue
458
+ `tl` Tokelau
459
+
460
+ Norway (3):
461
+ `bv` Bouvet Island
462
+ `jn` Jan Mayen
463
+ `sv` Svalbard
464
+
465
+ Great Britain (17):
466
+ `ax` Akrotiri (Sovereign Base)
467
+ `av` Anguilla
468
+ `bd` Bermuda
469
+ `io` British Indian Ocean Territory
470
+ `vi` British Virgin Islands
471
+ `cj` Cayman Islands
472
+ `dx` Dhekelia (Sovereign Base)
473
+ `fk` Falkland Islands
474
+ `gi` Gibraltar
475
+ `gk` Guernsey
476
+ `je` Jersey
477
+ `im` Isle of Man
478
+ `mh` Montserrat
479
+ `pc` Pitcairn Islands
480
+ `sh` Saint Helena
481
+ `sx` South Georgia and the South Sandwich Islands
482
+ `tk` Turks and Caicos Islands
483
+
484
+ United States (14):
485
+ `aq` American Samoa
486
+ `gq` Guam
487
+ `bq` Navassa Island
488
+ `cq` Northern Mariana Islands
489
+ `rq` Puerto Rico
490
+ `vq` US Virgin Islands
491
+ `wq` Wake Island
492
+ `um` US Pacific Island Wildlife Refuges
493
+ (Baker Island, Howland Island, Jarvis Island, Johnston Atoll, Kingman Reef, Midway Islands, Palmyra Atoll)
494
+
495
+
496
+ ### Miscellaneous (6)
497
+
498
+ `ay` Antarctica
499
+ `gz` Gaza Strip
500
+ `pf` Paracel Islands
501
+ `pg` Spratly Islands
502
+ `we` West Bank
503
+ `wi` Western Sahara
504
+
505
+ ### Oceans (5)
506
+
507
+ `xq` Arctic Ocean
508
+ `zh` Atlantic Ocean
509
+ `xo` Indian Ocean
510
+ `zn` Pacific Ocean
511
+ `oo` Southern Ocean
512
+
513
+ ### World (1)
514
+
515
+ `xx` World
516
+
517
+
518
+
519
+
520
+ ## Ready-To-Use Public Domain Factbook Datasets
521
+
522
+ [factbook/factbook.json](https://github.com/factbook/factbook.json) - open (public domain)
523
+ factbook country profiles in JSON for all the world's countries (using internet domain names
524
+ for country codes e.g. Austria is `at.json` not `au.json`, Germany is `de.json` not `gm.json` and so on)
525
+
526
+
527
+ ## Install
528
+
529
+ Use
530
+
531
+ gem install factbook
532
+
533
+ or add to your Gemfile
534
+
535
+ gem 'factbook'
536
+
537
+
538
+
539
+ ## License
540
+
541
+ The `factbook` scripts are dedicated to the public domain.
542
+ Use it as you please with no restrictions whatsoever.
543
+
544
+
545
+ ## Questions? Comments?
546
+
547
+ Send them along to the [Open Mundi (world.db) Database Forum/Mailing List](http://groups.google.com/group/openmundi).
548
+ Thanks!