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

AUTHORS

382       Damian Conway (damian@conway.org) and Abigail
383       (regexp-common@abigail.be).
384

MAINTAINANCE

386       This package is maintained by Abigail (regexp-common@abigail.be).
387

BUGS AND IRRITATIONS

389       Zip codes for most countries are missing.  Send them in to
390       regexp-common@abigail.be.
391

LICENSE and COPYRIGHT

393       This software is Copyright (c) 2001 - 2009, Damian Conway and Abigail.
394
395       This module is free software, and maybe used under any of the following
396       licenses:
397
398        1) The Perl Artistic License.     See the file COPYRIGHT.AL.
399        2) The Perl Artistic License 2.0. See the file COPYRIGHT.AL2.
400        3) The BSD Licence.               See the file COPYRIGHT.BSD.
401        4) The MIT Licence.               See the file COPYRIGHT.MIT.
402
403
404
405perl v5.12.0                      2010-01-02            Regexp::Common::zip(3)