Regexp::Common::zip(3pm)

1Regexp::Common::zip(3)User Contributed Perl DocumentationRegexp::Common::zip(3)
2
3
4

NAME

6       Regexp::Common::zip -- provide regexes for postal codes.
7

SYNOPSIS

9           use Regexp::Common qw /zip/;
10
11           while (<>) {
12               /^$RE{zip}{Netherlands}$/   and  print "Dutch postal code\n";
13           }
14

DESCRIPTION

16       Please consult the manual of Regexp::Common for a general description
17       of the works of this interface.
18
19       Do not use this module directly, but load it via Regexp::Common.
20
21       This module offers patterns for zip or postal codes of many different
22       countries. They all have the form "$RE{zip}{Country}[{options}]".
23
24       The following common options are used:
25
26       "{-prefix=[yes⎪no⎪allow]}" and "{-country=PAT}".
27
28       Postal codes can be prefixed with a country abbreviation. That is, a
29       dutch postal code of 1234 AB can also be written as NL-1234 AB.  By
30       default, all the patterns will allow the prefixes. But this can be
31       changed with the "-prefix" option. With "-prefix=yes", the returned
32       pattern requires a country prefix, while "-prefix=no" disallows a pre‐
33       fix. Any argument that doesn't start with a "y" or a "n" allows a coun‐
34       try prefix, but doesn't require them.
35
36       The prefixes used are, unfortunally, not always the same. Officially,
37       ISO country codes need to be used, but the usage of CEPT codes (the
38       same ones as used on cars) is common too. By default, each postal code
39       will recognize a country prefix that's either the ISO standard or the
40       CEPT code. That is, German postal codes may prefixed with either "DE"
41       or "D". The recognized prefix can be changed with the "-country"
42       option, which takes a (sub)pattern as argument. The arguments "iso" and
43       "cept" are special, and indicate the language prefix should be the ISO
44       country code, or the CEPT code.
45
46       Examples:
47        /$RE{zip}{Netherlands}/;
48                  # Matches '1234 AB' and 'NL-1234 AB'.
49        /$RE{zip}{Netherlands}{-prefix => 'no'}/;
50                  # Matches '1234 AB' but not 'NL-1234 AB'.
51        /$RE{zip}{Netherlands}{-prefix => 'yes'}/;
52                  # Matches 'NL-1234 AB' but not '1234 AB'.
53
54        /$RE{zip}{Germany}/;
55                  # Matches 'DE-12345' and 'D-12345'.
56        /$RE{zip}{Germany}{-country => 'iso'}/;
57                  # Matches 'DE-12345' but not 'D-12345'.
58        /$RE{zip}{Germany}{-country => 'cept'}/;
59                  # Matches 'D-12345' but not 'DE-12345'.
60        /$RE{zip}{Germany}{-country => 'GER'}/;
61                  # Matches 'GER-12345'.
62
63       "{-sep=PAT}"
64
65       Some countries have postal codes that consist of two parts. Typically
66       there is an official way of separating those parts; but in practise
67       people tend to use different separators. For instance, if the official
68       way to separate parts is to use a space, it happens that the space is
69       left off. The "-sep" option can be given a pattern as argument which
70       indicates what to use as a separator between the parts.
71
72       Examples:
73        /$RE{zip}{Netherlands}/;
74                  # Matches '1234 AB' but not '1234AB'.
75        /$RE{zip}{Netherlands}{-sep => '\s*'}/;
76                  # Matches '1234 AB' and '1234AB'.
77
78       $RE{zip}{Australia}
79
80       Returns a pattern that recognizes Australian postal codes. Australian
81       postal codes consist of four digits; the first two digits, which range
82       from '10' to '97', indicate the state. Territories use '02' or '08' as
83       starting digits; the leading zero is optional. '0909' is the only
84       postal code starting with '09' (the leading zero is optional here as
85       well) - this is the postal code for the Nothern Territory University).
86       The (optional) country prefixes are AU (ISO country code) and AUS (CEPT
87       code).  Regexp::Common 2.107 and before used $RE{zip}{Australia}. This
88       is still supported.
89
90       If "{-keep}" is used, the following variables will be set:
91
92       $1  The entire postal code.
93
94       $2  The country code prefix.
95
96       $3  The postal code without the country prefix.
97
98       $4  The state or territory.
99
100       $5  The last two digits.
101
102       $RE{zip}{Belgium}
103
104       Returns a pattern than recognizes Belgian postal codes. Belgian postal
105       codes consist of 4 digits, of which the first indicates the province.
106       The (optional) country prefixes are BE (ISO country code) and B (CEPT
107       code).
108
109       If "{-keep}" is used, the following variables will be set:
110
111       $1  The entire postal code.
112
113       $2  The country code prefix.
114
115       $3  The postal code without the country prefix.
116
117       $4  The digit indicating the province.
118
119       $5  The last three digits of the postal code.
120
121       $RE{zip}{Denmark}
122
123       Returns a pattern that recognizes Danish postal codes. Danish postal
124       codes consist of four numbers; the first digit (which cannot be 0),
125       indicates the distribution region, the second the distribution dis‐
126       trict. The (optional) country prefix is DK, which is both the ISO coun‐
127       try code and the CEPT code.
128
129       If "{-keep}" is used, the following variables will be set:
130
131       $1  The entire postal code.
132
133       $2  The country code prefix.
134
135       $3  The postal code without the country prefix.
136
137       $4  The digit indicating the distribution region.
138
139       $5  The digit indicating the distribution district.
140
141       $6  The last two digits of the postal code.
142
143       $RE{zip}{France}
144
145       Returns a pattern that recognizes French postal codes. French postal
146       codes consist of five numbers; the first two numbers, which range from
147       '01' to '98', indicate the department. The (optional) country prefixes
148       are FR (ISO country code) and F (CEPT code).  Regexp::Common 2.107 and
149       before used $RE{zip}{French}. This is still supported.
150
151       If "{-keep}" is used, the following variables will be set:
152
153       $1  The entire postal code.
154
155       $2  The country code prefix.
156
157       $3  The postal code without the country prefix.
158
159       $4  The department.
160
161       $5  The last three digits.
162
163       $RE{zip}{Germany}
164
165       Returns a pattern that recognizes German postal codes. German postal
166       codes consist of five numbers; the first number indicating the distri‐
167       bution zone, the second the distribution region, while the latter three
168       indicate the distribution district and the postal town.  The (optional)
169       country prefixes are DE (ISO country code) and D (CEPT code).  Reg‐
170       exp::Common 2.107 and before used $RE{zip}{German}. This is still sup‐
171       ported.
172
173       If "{-keep}" is used, the following variables will be set:
174
175       $1  The entire postal code.
176
177       $2  The country code prefix.
178
179       $3  The postal code without the country prefix.
180
181       $4  The distribution zone.
182
183       $5  The distribution region.
184
185       $6  The distribution district and postal town.
186
187       $RE{zip}{Greenland}
188
189       Returns a pattern that recognizes postal codes from Greenland.  Green‐
190       land, being part of Denmark, uses Danish postal codes.  All postal
191       codes of Greenland start with 39.  The (optional) country prefix is DK,
192       which is both the ISO country code and the CEPT code.
193
194       If "{-keep}" is used, the following variables will be set:
195
196       $1  The entire postal code.
197
198       $2  The country code prefix.
199
200       $3  The postal code without the country prefix.
201
202       $4  39, being the distribution region and distribution district for
203           Greenland.
204
205       $5  The last two digits of the postal code.
206
207       $RE{zip}{Italy}
208
209       Returns a pattern recognizing Italian postal codes. Italian postal
210       codes consist of 5 digits. The first digit indicates the region, the
211       second the province. The third digit is odd for province capitals, and
212       even for the province itself. The fourth digit indicates the route, and
213       the fifth a place on the route (0 for small places, alphabetically for
214       the rest).
215
216       The country prefix is either IT (the ISO country code), or I (the CEPT
217       code).
218
219       If "{-keep}" is used, the following variables will be set:
220
221       $1  The entire postal code.
222
223       $2  The country code prefix.
224
225       $3  The postal code without the country prefix.
226
227       $4  The region.
228
229       $5  The province.
230
231       $6  Capital or province.
232
233       $7  The route.
234
235       $8  The place on the route.
236
237       $RE{zip}{Netherlands}
238
239       Returns a pattern that recognizes Dutch postal codes. Dutch postal
240       codes consist of 4 digits and 2 letters, separated by a space.  The
241       separator can be changed using the "{-sep}" option, as discussed above.
242       The (optional) country prefix is NL, which is both the ISO country code
243       and the CEPT code. Regexp::Common 2.107 and earlier used
244       $RE{zip}{Dutch}. This is still supported.
245
246       If "{-keep}" is used, the following variables will be set:
247
248       $1  The entire postal code.
249
250       $2  The country code prefix.
251
252       $3  The postal code without the country prefix.
253
254       $4  The digits part of the postal code.
255
256       $5  The separator between the digits and the letters.
257
258       $6  The letters part of the postal code.
259
260       $RE{zip}{Norway}
261
262       Returns a pattern that recognizes Norwegian postal codes. Norwegian
263       postal codes consist of four digits.
264
265       The country prefix is either NO (the ISO country code), or N (the CEPT
266       code).
267
268       If "{-keep}" is used, the following variables will be set:
269
270       $1  The entire postal code.
271
272       $2  The country code prefix.
273
274       $3  The postal code without the country prefix.
275
276       $RE{zip}{Spain}
277
278       Returns a pattern that recognizes Spanish postal codes. Spanish postal
279       codes consist of 5 digits. The first 2 indicate one of Spains fifties
280       provinces (in alphabetical order), starting with 00. The third digit
281       indicates a main city or the main delivery rounds. The last two digits
282       are the delivery area, secondary delivery route or a link to rural
283       areas.
284
285       The country prefix is either ES (the ISO country code), or E (the CEPT
286       code).
287
288       If "{-keep}" is used, the following variables will be set:
289
290       $1  The entire postal code.
291
292       $2  The country code prefix.
293
294       $3  The postal code without the country prefix.
295
296       $4  The two digits indicating the province.
297
298       $5  The digit indicating the main city or main delivery route.
299
300       $6  The digits indicating the delivery area, secondary delivery route
301           or a link to rural areas.
302
303       $RE{zip}{US}{-extended => [yes⎪no⎪allow]}
304
305       Returns a pattern that recognizes US zip codes. US zip codes consist of
306       5 digits, with an optional 4 digit extension. By default, extensions
307       are allowed, but not required. This can be influenced by the
308       "-extended" option. If its argument starts with a "y", extensions are
309       required; if the argument starts with a "n", extensions will not be
310       recognized. If an extension is used, a dash is used to separate the
311       main part from the extension, but this can be changed with the "-sep"
312       option.
313
314       The country prefix is either US (the ISO country code), or USA (the
315       CEPT code).
316
317       If "{-keep}" is being used, the following variables will be set:
318
319       $1  The entire postal code.
320
321       $2  The country code prefix.
322
323       $3  The postal code without the country prefix.
324
325       $4  The first 5 digits of the postal code.
326
327       $5  The first three digits of the postal code, indicating a sectional
328           center or a large city. New in Regexp::Common 2.119.
329
330       $6  The last 2 digits of the 5 digit part of the postal code, indicat‐
331           ing a post office facility or delivery area. New in Regexp::Common
332           2.119.
333
334       $7  The separator between the 5 digit part and the 4 digit part. Up to
335           Regexp::Common 2.118, this used to be $5.
336
337       $8  The 4 digit part of the postal code (if any). Up to Regexp::Common
338           2.118, this used to be $6.
339
340       $9  The first two digits of the 4 digit part of the postal code, indi‐
341           cating a sector, or several blocks. New in Regexp::Common 2.119.
342
343       $10 The last two digits of the 4 digit part of the postal code, indi‐
344           cating a segment or one side of a street. New in Regexp::Common
345           2.119.
346
347       You need at least version 5.005_03 to be able to use US postal codes.
348       Older versions contain a bug that let the pattern match invalid US
349       postal codes.
350
351       Questions
352
353       ·   Can the 5 digit part of the zip code (in theory) start with 000?
354
355       ·   Can the 5 digit part of the zip code (in theory) end with 00?
356
357       ·   Can the 4 digit part of the zip code (in theory) start with 00?
358
359       ·   Can the 4 digit part of the zip code (in theory) end with 00?
360

HISTORY

362        $Log: zip.pm,v $
363        Revision 2.112  2005/01/01 16:34:04  abigail
364        - Modified the -keep captures for US zip codes. Both the 5 and 4 digit parts
365          of the zip codes can be dissected into 2 parts.
366        - Updated the copyright notice.
367
368        Revision 2.111  2004/12/14 23:15:13  abigail
369        Disable '-prefix' for Danish postal codes for pre-5.00503 perls.
370
371        Revision 2.110  2004/06/09 21:44:13  abigail
372        - Norway, Italy, Spain.
373        - References.
374        - POD nits.
375
376        Revision 2.109  2003/07/04 13:34:05  abigail
377        Fixed assignment to
378
379        Revision 2.108  2003/06/24 23:23:14  abigail
380        Australia currently has a postal code '0909' (or '909') for the
381        Northern Territory University; this is the only postal code starting
382        with '09'. $RE{zip}{Australia} now accepts '0909', and rejects all
383        other postal codes starting with '09'. (Ron Savage).
384
385        Revision 2.107  2003/03/25 23:46:58  abigail
386        Added RCS Id: tag
387
388        Revision 2.106  2003/02/09 21:31:16  abigail
389        Postal codes for Denmark and Greenland
390
391        Revision 2.105  2003/02/09 12:41:31  abigail
392        Added Belgian postal codes
393
394        Revision 2.104  2003/02/01 22:55:31  abigail
395        Changed Copyright years
396
397        Revision 2.103  2003/02/01 22:49:25  abigail
398        Added Australian postal codes
399
400        Revision 2.102  2003/01/23 02:18:42  abigail
401        Added French postal codes
402
403        Revision 2.101  2003/01/22 17:23:26  abigail
404        German postal codes added.
405
406        Revision 2.100  2003/01/21 23:19:40  abigail
407        The whole world understands RCS/CVS version numbers, that 1.9 is an
408        older version than 1.10. Except CPAN. Curse the idiot(s) who think
409        that version numbers are floats (in which universe do floats have
410        more than one decimal dot?).
411        Everything is bumped to version 2.100 because CPAN couldn't deal
412        with the fact one file had version 1.10.
413
414        Revision 1.5  2003/01/16 11:06:27  abigail
415        Typo fix.
416
417        Revision 1.4  2003/01/16 11:02:17  abigail
418        For US zip codes, version needs to be at least 5.005_03; older 5.005
419        versions seem to have a bug in the regex machine, creating false
420        positives.
421
422        Revision 1.3  2003/01/13 21:45:01  abigail
423        Complete redoing of Dutch & US postal codes. Documented them.
424
425        Revision 1.2  2003/01/01 15:09:47  abigail
426        Added US zip codes.
427
428        Revision 1.1  2002/12/31 02:01:33  abigail
429        First version
430

AUTHORS

456       Damian Conway (damian@conway.org) and Abigail (regexp-common@abi‐
457       gail.nl).
458

MAINTAINANCE

460       This package is maintained by Abigail (regexp-common@abigail.nl).
461

BUGS AND IRRITATIONS

463       Zip codes for most countries are missing.  Send them in to regexp-com‐
464       mon@abigail.nl.
465

COPYRIGHT

467          Copyright (c) 2001 - 2005, Damian Conway and Abigail. All Rights
468        Reserved. This module is free software. It may be used, redistributed
469            and/or modified under the terms of the Perl Artistic License
470                  (see http://www.perl.com/perl/misc/Artistic.html)
471
472
473
474perl v5.8.8                       2003-03-23            Regexp::Common::zip(3)