address_composer 0.1.1.pre → 0.1.2.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5dc6f7150d8ff02dc9efb23da97a41bd3dd4b4bd
-  data.tar.gz: 88e13e1d05454799ee6adaf4ea06e09095bbc5bd
+  metadata.gz: 1ff29a1fb1a5be6de0536d15665c65b35446cc59
+  data.tar.gz: 5aff1357c3033f2c68c05978317f23bbc72d9947
 SHA512:
-  metadata.gz: a553c8298de626fb00d2590db4126d71394ba30c4db559adc520c547bde5c6508df06eedd25a0d1ccfefa35818d203c2a2545f574441d19e74d3e64974bf4e10
-  data.tar.gz: 92e81fa2932ec9b88f145aa603a3e9def4c4a3d11b1984d1b62c832fb0bc02b34d990a76a38d33be8356ea0866c7a7bed652232fb722b8cd02545985b848b3e8
+  metadata.gz: 6ada0e4482655f7d0d0c8f9bb0d7755b10abd8e41e7b6c973e5c4ad3fc982a57268ad70f6520e11f1d4e9f22135cfd745ddc692f0e4167a437fdc2b79258dd41
+  data.tar.gz: 1d8f70916066338be173a8ffb3f6ab435280601303706880984a8100ddc14f8205903c1506ac0c4dfa405840e84189a783a553fe5a02572e0a0af56da7af39c4

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    address_composer (0.1.0)
+    address_composer (0.1.1.pre)
       mustache (~> 1.1)
 
 GEM
@@ -18,7 +18,7 @@ GEM
     pry-byebug (3.9.0)
       byebug (~> 11.0)
       pry (~> 0.13.0)
-    rake (10.5.0)
+    rake (13.0.1)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)
       rspec-expectations (~> 3.9.0)
@@ -41,7 +41,7 @@ DEPENDENCIES
   bundler (~> 1.17)
   pry (~> 0.13)
   pry-byebug (~> 3.9)
-  rake (~> 10.0)
+  rake (~> 13.0)
   rspec (~> 3.0)
 
 BUNDLED WITH

data/README.md

@@ -54,7 +54,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/mirubiri@gmail.com/address_composer.
+Bug reports and pull requests are welcome on GitHub at https://github.com/mirubiri/address_composer
 
 
 

data/address-formatting/.travis.yml

@@ -0,0 +1,10 @@
+---
+language: 'perl'
+perl:
+  - "5.26" # Ubuntu 18
+env: PERL_CPANM_OPT="--notest --force --skip-satisfied"
+install:
+  - cpanm File::Find::Rule~0.34
+  - cpanm Geo::Address::Formatter~1.76
+script:
+  - bin/run_tests.t

data/address-formatting/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Opencage GmbH - https://opencagedata.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/address-formatting/README.md

@@ -0,0 +1,153 @@
+# address formatting
+
+### Overview
+
+This project contains templates and test cases for address formats used in territories around the world. The templates can then be processed in any programming language ([see below for list of processors](#processing-logic)).
+
+### Build Status
+
+[![Build Status](https://travis-ci.org/OpenCageData/address-formatting.svg?branch=master)](https://travis-ci.org/OpenCageData/address-formatting)
+
+### An example:
+
+Given a set of address parts like
+
+     house_number:  17
+     road:          Rue du Médecin-Colonel Calbairac
+     neighbourhood: Lafourguette
+     suburb:        Toulouse Ouest
+     postcode:      31000
+     city:          Toulouse
+     county:        Toulouse
+     state:         Midi-Pyrénées
+     country:       France
+     country_code:  FR
+
+we want to write logic to compile an address in the format consumers expect
+
+    17 Rue du Médecin-Colonel Calbairac
+    31000 Toulouse
+    France
+
+### Why would you want to do this?
+
+The intended use case is database or geocoding systems (forward, reverse, autocomplete) where we know both the country of the address and the language of the user/reader. The address is displayed to a consumer (for example in an app) and not used to print on an envelope for actual postal delivery. We use it to format output from the [OpenCage Geocoder](https://opencagedata.com).
+
+### Which addresses are we talking about?
+
+We have to deal with
+
+   * incomplete data
+   * anything with a name (peaks, bridges, bus stops)
+
+Unlike [physical post (office) mail](http://www.bitboost.com/ref/international-address-formats.html) we don't have to deal with
+
+   * apartment/flat number, floor numbers
+   * PO boxes
+   * translating the language of the (destination) address. Whatever language is input is output. 
+  
+### Processing logic
+
+Our goal with this repository is a series of (programming) language independent templates. Those templates can then be processed by whatever software you like. 
+
+There are open-source implementations in
+
+  * [Javascript](https://github.com/fragaria/address-formatter)
+  * [Perl](https://metacpan.org/release/Geo-Address-Formatter)
+  * [PHP](https://github.com/predicthq/address-formatter-php)
+  * [Rust](https://github.com/CanalTP/address-formatter-rs)
+
+We would love more language implementations. The more people who use the templates, the more likely bugs will be reported. 
+If you write a processor, please submit a pull request adding it to the list. Thanks. 
+
+### International coverage
+
+As of `Sun 17 Feb 2019` coverage is:
+
+    We are aware of 248 territories
+    We have tests for 248 (100%) territories
+    We have rules for 248 (100%) territories
+    0 (0%) territories have neither rules nor tests
+    
+This output is generated by `bin/coverage.pl`    
+
+We need more language specific abbreviations. Please see `conf/abbreviations`. Pull requests wil lbe glaldy received. 
+
+A detailed breakdown of test and configuration coverage can be found by running `bin/coverage.pl -d`. A list of all known territories is in `conf/country_codes.yaml`
+
+_Please note: the list is simple all officially assigned [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements), and is not a political statement on whether or not these territories are or are not or should or should not be political states._
+
+### File format
+
+The files are in [YAML](http://yaml.org/) format. The templates are written in [Mustache](http://mustache.github.io/). Both formats are human readable, strict, solve escaping and support comments. YAML allows references (called "ankers") to avoid copy&paste, Mustache allows sub-templates (called "partials").
+
+### How to add your country/territory
+
+1. edit the .yaml testcase for the country/territory in `testcases/countries`. The file names correspond to the appropriate ISO 3166-1 alpha-2 code - see `conf/country_codes.yaml`
+  * a good way to get sample data is:
+      * find an addressed location (house, business, etc) in your
+        target territory in OpenStreetMap
+      * get the coordinates (lat, long) of the location
+      * put the coordinates into the [OpenCage Geocoder demo
+        page](https://opencagedata.com/demo)
+      * look at the resulting JSON in the *Raw Response* tab
+
+2. edit `conf/countries/worldwide.yaml`
+  * Possibly your country/territory uses an existing generic format as
+    defined at the top of the file. If so, great, just map you
+    country_code to the generic template. You may still want to add
+    clean up code (see the entry for `DE` as an example).
+  * If not you need to define a new generic rule set
+      * possibly you will need to define new state/region mappings in `conf/state_codes.yaml`
+
+3. to test you will now need to process the .yaml test via a processer
+   (see above) and ensure the input leads to the desired output.
+
+If in doubt, please get in touch by submitting an issue. 
+
+### Formatting rules
+
+Currently we support the following formatting rules:
+
+* `replace:` regex that operates on the input values, useful for removing bureaucratic cruft like "London Borough of ". Note if you define the regex starting with format _X=_, for example _city=_ it should operate only on values with that key
+* `postformat_replace:` regex that operates on the final output
+* `add_component:` with a value of the form `component=XXXX`
+* `change_country:` change the country value of the input, useful for dependent territories. Can include a substitution like `$state` so that that component value is then inserted into the new country value. See `testcases/countries/sh.yaml` for an example.
+* `use_country:` use the formating configuration of another country, useful for dependent territories to avoid duplicating configuration
+
+### The future
+
+More tests! For every rule about addresses there are exceptions and edge cases to consider. More test cases are always needed.
+
+Planned features:
+
+  * basic error checking, for example ignore things which obviously can not be postcodes
+  * define rules for postcode format specifically
+
+We welcome your pull requests. Together we can address the world!
+
+### License
+
+This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details
+
+### Further reading on the challenge of address
+
+Here's [our blog post anouncing this project](https://blog.opencagedata.com/post/99059889253/good-looking-addresses-solving-the-berlin-berlin) and the motivations behind it.
+
+You may enjoy Michael Tandy's [Falsehoods Programmers Believe about Addresses](http://www.mjt.me.uk/posts/falsehoods-programmers-believe-about-addresses/).
+
+If it's actual address data you're after, check out [OpenStreetMap](https://www.openstreetmap.org) and [OpenAddresses](http://openaddresses.io/).
+
+If you want to turn longitude, latitude into well formatted addresses or placenames, well that's what a geocoder does. Check out ours: [OpenCage Geocoder](https://opencagedata.com).
+
+If all this convinces you that address are evil, please check out [what3words](http://what3words.com) which allows you to dispense with them entirely. 
+
+### Who is OpenCage GmbH?
+
+<a href="https://opencagedata.com"><img src="opencage_logo_300_150.png"></a>
+
+We run the [OpenCage Geocoder](https://opencagedata.com). Learn more [about us](https://opencagedata.com/about). 
+
+We also run [Geomob](https://thegeomob.com), a series of regular meetups for location based service creators, where we do our best to highlight geoinnovation. If you like geo stuff, you will probably enjoy [the Geomob podcast](https://thegeomob.com/podcast/).
+
+

data/address-formatting/bin/coverage.pl

@@ -0,0 +1,120 @@
+#!/usr/bin/env perl
+#
+# scan the tests and templates and tell us which territories
+# don't yet have rules and tests
+# 
+use strict;
+use warnings;
+use utf8;
+use feature "unicode_strings";
+
+use Data::Dumper;
+use Getopt::Long;
+use File::Basename qw(dirname);
+
+my $help    = 0;
+my $details = 0;
+GetOptions (
+    'details' => \$details,
+    'help'    => \$help,
+) or die "invalid options";
+
+if ($help) {
+    usage();
+    exit(0);
+}
+
+# get the list of countries
+my %countries;
+my $country_file = dirname(__FILE__) . "/../conf/country_codes.yaml";
+open my $FH, "<:encoding(UTF-8)", $country_file or die "unable to open $country_file $!";
+while (my $line = <$FH>){
+    chomp($line);
+    if ($line =~ m/^(\w\w): \# (.*)$/){
+        $countries{$1} = $2;
+    }
+}
+close $FH;
+my $total_countries = scalar(keys %countries); 
+print "We are aware of " . $total_countries . " territories \n";
+
+
+# which countries have tests?
+my $test_dir = dirname(__FILE__) . '/../testcases/countries';
+opendir(my $dh, $test_dir) || die "Error: Couldn't opendir($test_dir): $!\n";
+my @files = grep { -f "$test_dir/$_" } readdir($dh);
+closedir($dh);
+
+my %test_countries;
+foreach my $f (sort @files){
+    $f =~ s/\.yaml//;
+    $f = uc($f);
+    $test_countries{$f} = 1;
+}
+my $test_countries = scalar(keys %test_countries);
+my $test_perc = int(100 * $test_countries / $total_countries );
+print "We have tests for " .  $test_countries . ' ('
+    . $test_perc . '%) territories' .  "\n";
+if ($details){
+    print "We need tests for:\n";
+    foreach my $cc (sort keys %countries){
+        next if (defined($test_countries{$cc}));
+        print "\t" . $cc . "\t". $countries{$cc}. "\n";
+    }
+}
+
+# which countries have rules?
+my $rules_file = dirname(__FILE__) . '/../conf/countries/worldwide.yaml';
+open my $RFH, "<:encoding(UTF-8)", $rules_file or die "unable to open $rules_file $!";
+my %rules;
+while (my $line = <$RFH>){
+    chomp($line);
+    if ($line =~ m/^"?(\w\w)"?:\s*$/){
+        $rules{$1} = 1;
+    }
+}
+close $RFH;
+my $rules_countries = scalar(keys %rules);
+my $rules_perc = int(100 * $rules_countries / $total_countries );
+print "We have rules for " .  $rules_countries . ' ('
+    . $rules_perc . '%) territories' . "\n";
+
+if ($details){
+    print "We need rules for:\n";
+    foreach my $cc (sort keys %countries){
+        next if (defined($rules{$cc}));
+        print "\t" . $cc . "\t". $countries{$cc}. "\n";
+    }
+}
+
+# find territories without rules or tests
+my %neither;
+foreach my $cc (sort keys %countries){
+    next if (defined($rules{$cc}));
+    next if (defined($test_countries{$cc}));
+    $neither{$cc} = 1;
+}
+my $neither_countries = scalar(keys %neither);
+my $neither_perc = int(100 * $neither_countries / $total_countries );
+print $neither_countries . ' (' . $neither_perc . '%) territories have neither rules nor tests' . "\n";
+if ($details){
+    print "Territories with no test and no rules:\n";
+    foreach my $cc (sort keys %neither){
+        print "\t" . $cc . "\t". $countries{$cc}. "\n";
+    }
+}
+
+
+sub usage {
+    print "\tHow many territories have formatting rules and tests?\n";
+    print "\tBy default prints just a high level summary\n";
+    print "\tusage:\n";
+    print "\t\t no required parameters\n";
+    print "\n";
+    print "\t\t optional parameters:\n";
+    print "\t\t --detail\t print full list of countries missing rules and tests\n";
+    print "\t\t --help\t print this message \n";
+    print "\n";
+}
+
+

data/address-formatting/bin/run_tests.t

@@ -0,0 +1,62 @@
+#!/usr/bin/env perl
+
+# copy of
+# https://github.com/OpenCageData/perl-Geo-Address-Formatter/blob/master/t/unit/countries.t
+# and runs in travis-CI (see .travis.yml)
+
+use strict;
+use lib 'perl/lib/perl5';
+use File::Basename qw(basename dirname);
+use File::Find::Rule;
+use File::Spec;
+use Test::Exception;
+use Test::More;
+use YAML::XS qw(LoadFile);
+
+use utf8;
+# nicer output for diag and failures, see
+# http://perldoc.perl.org/Test/More.html#CAVEATS-and-NOTES
+my $builder = Test::More->builder;
+binmode $builder->output,         ":utf8";
+binmode $builder->failure_output, ":utf8";
+binmode $builder->todo_output,    ":utf8";
+
+
+my $path = dirname(__FILE__) . '/../testcases';
+
+my @files = File::Find::Rule->file()->name( '*.yaml' )->in( $path );
+
+ok(scalar(@files), 'found at least one file');
+
+my $CLASS = 'Geo::Address::Formatter';
+use_ok($CLASS);
+
+my $conf_path = dirname(__FILE__) . '/../conf';
+my $GAF = $CLASS->new( conf_path => $conf_path );
+
+sub _one_testcase {
+    my $country    = shift;
+    my $rh_testcase = shift;
+    is(
+        $GAF->format_address($rh_testcase->{components}),
+        $rh_testcase->{expected},
+        $country . ' - ' . $rh_testcase->{description}
+    );
+}
+
+foreach my $filename (@files){
+    my $country = basename($filename);
+    $country =~ s/\.\w+$//; # us.yaml => us
+
+    my @a_testcases = ();
+    lives_ok {
+        @a_testcases = LoadFile($filename);
+    } "parsing file $filename";
+
+    foreach my $rh_testcase (@a_testcases){
+        _one_testcase($country, $rh_testcase);
+    }
+}
+
+
+done_testing();

data/address-formatting/conf/abbreviations/ca.yaml

@@ -0,0 +1,4 @@
+road:
+     Carrer de: C
+     Rambla: Rbla
+     

data/address-formatting/conf/abbreviations/cs.yaml

@@ -0,0 +1,7 @@
+road:
+     Ulice: Ul
+     Třída: Tř
+     Náměstí: Nám
+
+
+     

data/address-formatting/conf/abbreviations/de.yaml

@@ -0,0 +1,7 @@
+road:
+     Platz: Pl
+     Sankt: St
+     Straße: Str
+     Strasse: Str
+
+