1// Copyright (C) 2013 Google Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//
15// An object to store address metadata, describing the addressing rules for
16// regions and sub-regions. The address metadata format is documented here:
17//
18// https://code.google.com/p/libaddressinput/wiki/AddressValidationMetadata
19
20#ifndef I18N_ADDRESSINPUT_RULE_H_
21#define I18N_ADDRESSINPUT_RULE_H_
22
23#include <libaddressinput/address_field.h>
24#include <libaddressinput/util/basictypes.h>
25#include <libaddressinput/util/scoped_ptr.h>
26
27#include <string>
28#include <vector>
29
30namespace i18n {
31namespace addressinput {
32
33class FormatElement;
34class Json;
35struct RE2ptr;
36
37// Stores address metadata addressing rules, to be used for determining the
38// layout of an address input widget or for address validation. Sample usage:
39//    Rule rule;
40//    if (rule.ParseSerializedRule("{\"fmt\": \"%A%n%C%S %Z\"}")) {
41//      Process(rule.GetFormat());
42//    }
43class Rule {
44 public:
45  Rule();
46  ~Rule();
47
48  // Returns the default rule at a country level. If a country does not specify
49  // address format, for example, then the format from this rule should be used
50  // instead.
51  static const Rule& GetDefault();
52
53  // Copies all data from |rule|.
54  void CopyFrom(const Rule& rule);
55
56  // Parses |serialized_rule|. Returns |true| if the |serialized_rule| has valid
57  // format (JSON dictionary).
58  bool ParseSerializedRule(const std::string& serialized_rule);
59
60  // Reads data from |json|, which must already have parsed a serialized rule.
61  void ParseJsonRule(const Json& json);
62
63  // Returns the ID string for this rule.
64  const std::string& GetId() const { return id_; }
65
66  // Returns the format elements for this rule. The format can include the
67  // relevant address fields, but also strings used for formatting, or newline
68  // information.
69  const std::vector<FormatElement>& GetFormat() const { return format_; }
70
71  // Returns the approximate address format with the Latin order of fields. The
72  // format can include the relevant address fields, but also strings used for
73  // formatting, or newline information.
74  const std::vector<FormatElement>& GetLatinFormat() const {
75    return latin_format_;
76  }
77
78  // Returns the required fields for this rule.
79  const std::vector<AddressField>& GetRequired() const { return required_; }
80
81  // Returns the sub-keys for this rule, which are the administrative areas of a
82  // country, the localities of an administrative area, or the dependent
83  // localities of a locality. For example, the rules for "US" have sub-keys of
84  // "CA", "NY", "TX", etc.
85  const std::vector<std::string>& GetSubKeys() const { return sub_keys_; }
86
87  // Returns all of the language tags supported by this rule, for example ["de",
88  // "fr", "it"].
89  const std::vector<std::string>& GetLanguages() const { return languages_; }
90
91  // Returns a pointer to a RE2 regular expression object created from the
92  // postal code format string, if specified, or NULL otherwise. The regular
93  // expression is anchored to the beginning of the string so that it can be
94  // used either with RE2::PartialMatch() to perform prefix matching or else
95  // with RE2::FullMatch() to perform matching against the entire string.
96  const RE2ptr* GetPostalCodeMatcher() const {
97    return postal_code_matcher_.get();
98  }
99
100  // Returns the sole postal code for this rule, if there is one.
101  const std::string& GetSolePostalCode() const { return sole_postal_code_; }
102
103  // The message string identifier for admin area name. If not set, then
104  // INVALID_MESSAGE_ID.
105  int GetAdminAreaNameMessageId() const { return admin_area_name_message_id_; }
106
107  // The message string identifier for postal code name. If not set, then
108  // INVALID_MESSAGE_ID.
109  int GetPostalCodeNameMessageId() const {
110    return postal_code_name_message_id_;
111  }
112
113  // Returns the name for the most specific place described by this rule, if
114  // there is one. This is typically set when it differs from the key.
115  const std::string& GetName() const { return name_; }
116
117  // Returns the Latin-script name for the most specific place described by this
118  // rule, if there is one.
119  const std::string& GetLatinName() const { return latin_name_; }
120
121  // Returns the postal code example string for this rule.
122  const std::string& GetPostalCodeExample() const {
123    return postal_code_example_;
124  }
125
126  // Returns the post service URL string for this rule.
127  const std::string& GetPostServiceUrl() const { return post_service_url_; }
128
129 private:
130  std::string id_;
131  std::vector<FormatElement> format_;
132  std::vector<FormatElement> latin_format_;
133  std::vector<AddressField> required_;
134  std::vector<std::string> sub_keys_;
135  std::vector<std::string> languages_;
136  scoped_ptr<const RE2ptr> postal_code_matcher_;
137  std::string sole_postal_code_;
138  int admin_area_name_message_id_;
139  int postal_code_name_message_id_;
140  std::string name_;
141  std::string latin_name_;
142  std::string postal_code_example_;
143  std::string post_service_url_;
144
145  DISALLOW_COPY_AND_ASSIGN(Rule);
146};
147
148}  // namespace addressinput
149}  // namespace i18n
150
151#endif  // I18N_ADDRESSINPUT_RULE_H_
152