factbook 1.1.0 → 2.0.0

Sign up to get free protection for your applications and to get access to all the features.
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!