0.0
The project is in a healthy, maintained state
Unofficial gem to apply Royal Mail Rules & Exceptions when formatting PAF addresses.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Runtime

 Project Readme

PostmanPAF

Converts Royal Mail PAF (Postcode Address File) addresses to a printable format for an envelope or address label.

This is an unofficial gem to apply Royal Mail Rules & Exceptions when converting PAF addresses. Based on the Royal Mail Programmers' Guide, 'Formatting a PAF address for printing' (page 27).

Conversions aim to resemble addresses returned by Royal Mail Find a PostCode as accurately as possible.


Installation

Add this line to your application's Gemfile:

gem 'postman_paf'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install postman_paf

Usage

Add PostmanPAF into a project:

include PostmanPAF

Convert method

Converting this simple address:

PostmanPAF.convert({
                     buildingName: "1A",
                     thoroughfareName: "EXAMPLE ROAD",
                     postTown: "EXAMPLE TOWN",
                     postcode: "SA99 1BN",
                     dps: "1A",
                     language: "EN",
                     country: "WALES" 
                   })

Returns:

{"line1"=>"1A EXAMPLE ROAD", "line5"=>"EXAMPLE TOWN", "postcode"=>"SA99 1BN", "country"=>"WALES", "language"=>"EN", "dps"=>"1A"}

Converting this more complex address:

PostmanPAF.convert({
                     subBuildingName: "1 EXAMPLE HOUSE 2A",
                     buildingName: "EXAMPLE PLACE 3-4",
                     thoroughfareName: "EXAMPLE ROAD",
                     postTown: "EXAMPLE TOWN",
                     postcode: "SA99 1BN",
                     dps: "1A",
                     language: "EN",
                     country: "WALES" 
                   })

Returns:

{"line1"=>"1 EXAMPLE HOUSE 2A EXAMPLE PLACE", "line2"=>"3-4 EXAMPLE ROAD", "line5"=>"EXAMPLE TOWN", "postcode"=>"SA99 1BN", "country"=>"WALES", "language"=>"EN", "dps"=>"1A"}

PostmanPAF can convert a single PAF address as a Hash, or multiple PAF addresses as an Array of Hashes.

PAF address Hashes must include postTown and postcode keys as a minimum requirement.

Optional Arguments

To limit lines 1-5 of a printable address to a maximum number of characters, use the optional argument max_line_length. Note that this will cause data to be 'cut off' in places, e.g. 'TOWN' in postTown below:

PostmanPAF.convert({
                     buildingName: "1A",
                     thoroughfareName: "EXAMPLE ROAD",
                     postTown: "EXAMPLE TOWN",
                     postcode: "SA99 1BN",
                     dps: "1A",
                     language: "EN",
                     country: "WALES" }, max_line_length: 10)

Returns:

{"line1"=>"1A EXAMPLE", "line5"=>"EXAMPLE TO", "postcode"=>"SA99 1BN", "country"=>"WALES", "language"=>"EN", "dps"=>"1A"}

If you want to view the Rule & Exception(s) applied to the address during format conversion, set the optional argument logging to true. This:

PostmanPAF.convert({
                     buildingName: "1A",
                     thoroughfareName: "EXAMPLE ROAD",
                     postTown: "EXAMPLE TOWN",
                     postcode: "SA99 1BN",
                     dps: "1A",
                     language: "EN",
                     country: "WALES" }, logging: true)

Returns the converted address format along with a log to STDOUT:

[2023-12-25 11:11:11 +0000  INFO  PostmanPAF] -- ["1A EXAMPLE ROAD", "EXAMPLE TOWN"] | rule3 | exception_ii | SA99 1BN

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.


Special thanks to Alexander O'Mahoney, Christopher Thomas and Deepak Thankachan.

                                      .,,,.                                             
                                 ,@#.        /@*                                        
                               &*               %/                                      
                            %#                   .@                                     
                        /@/                       ,#                                    
                   (@%.         ./%%%(,            &                                    
               /@(          (@*    /./. ,@        */                                    
             @/           @,     ..    ,(  @      &                                     
           %(           %.          #*&     &    &                                      
          (/           &                     @ .*                                       
          @           %        ,&@@@&   *&@@@@@.                                        
          @          &      /@@@@@@@@@&%.,/(@@@@@@@.                                    
          #*         / #    *@,(%@@@#/     ./#.  *(                                     
           (#      /         (.  #            %  %                                      
             (@*   .,      (#             .*  # (/                                      
                  .,  .    ,,     % &     *  *, ,,                                      
                   /  *./%,.     .@&(,  . &@,%&,  &.                                    
                   (  ( %#..%%  @ &@&  @ @./%(   &                                    
                   #  # /      &        @          /(                                   
                    %  %       *.      .(             %                                 
                      % %/      ,&.  .&               ,/                                
                      # .(                            (.                                
                      ,( %              .///*,.    *&/                                  
                        .&/                    &                                        
                          &                    (,                                       
                          /,       %.       #   %                                       
                           &         //   #(    &                                       
                           #                    /.                                      
                            #                    /                                      
            @*@*&.          %                    (                                      
           %  *  .%         %%                  .%                                      
         #@,   #  *,       @ &&                 & .(                                    
        *  (.  #   %     /&( *.,&              &.&  ,@#.                                
       %   **  #   & (#   #,  &   #%.       /&   %    ,/ (((                            
       #   &   (   #,     //   #       .,@@@&,   / .%#(.    .(                          
      ,   .%  /@%, .(*@   .@    &       ,@@@@@.#.@  (#,       %.                        
      #   #(.            ,#   #  %&.    @.@@@%   (     %   (    &                       
      *                .@    #,   ,&      #@@@@( &    /#    (    &.                     
    .&.        (      *%      #*    *%   .@@@@@@@     @           //                    
    & %         ,    .&         (*     &*&@@@@@@,   .@             ,%                   
   (.  %        (   ,%&.           *#     #@@@@,   %*                @                  
   &    //     *  *@   @               .#/   .%  *.          .        @                 
   &       ,/*         &                       (             #   .     &                
   &                 .@,                       %             %  ,#.#   (.               
   /(               &. ,                       *.            %         /,               
    .@*           .@   ,                   ( %  (            %#        &.               
        &*      /@.   ..                   &,@  @         *    *      *#