SL/XMLInvoice/Base.pm

   1 package SL::XMLInvoice::Base;
   2
   3 use strict;
   4 use warnings;
   5
   6 =head1 ATTRIBUTES
   7
   8 =over 4
   9
  10 =item dom
  11
  12 A XML::LibXML document object model (DOM) object created from the XML data supplied.
  13
  14 =item message
  15
  16 Will contain a detailed error message if the C<result> attribute is anything
  17 other than C<SL::XMLInvoice::RES_OK>.
  18
  19 =item result
  20
  21 A status field indicating whether the supplied XML data could be parsed. It
  22 can take the following values:
  23
  24 =item SL::XMLInvoice::RES_OK
  25
  26 File has been parsed successfully.
  27
  28 =item SL::XMLInvoice::RES_XML_PARSING FAILED
  29
  30 Parsing the file failed.
  31
  32 =item SL::XMLInvoice::RES_UNKNOWN_ROOT_NODE_TYPE
  33
  34 The root node is of an unknown type. Currently, C<rsm:CrossIndustryInvoice> and
  35 C<ubl:Invoice> are supported.
  36
  37 =back
  38
  39 =head1 METHODS
  40
  41 =head2 Data structure definition methods (only in C<SL::XMLInvoice>)
  42
  43 These methods are only implemented in C<SL::XMLInvoice> itself and define the
  44 data structures to be exposed by any child classes.
  45
  46 =over 4
  47
  48 =item data_keys()
  49
  50 Returns all keys the hash returned by any child's C<metadata()> method must
  51 contain. If you add keys to this list, you need to add them to all classes
  52 inheriting from C<SL::XMLInvoice> as well. An application may use this method
  53 to discover the metadata keys guaranteed to be present.
  54
  55 =cut
  56
  57 sub data_keys {
  58   my @keys = (
  59     'currency',      # The bill's currency, such as "EUR"
  60     'direct_debit',  # Boolean: whether the bill will get paid by direct debit (1) or not (0)
  61     'duedate',       # The bill's due date in YYYY-MM-DD format.
  62     'gross_total',   # The invoice's sum total with tax included
  63     'iban',          # The creditor's IBAN
  64     'invnumber',     # The invoice's number
  65     'net_total',     # The invoice's sum total without tax
  66     'taxnumber',     # The creditor's tax number (Steuernummer in Germany). May be present if
  67                      # there is no VAT ID (USTiD in Germany).
  68     'transdate',     # The date the invoice was issued in YYYY-MM-DD format.
  69     'type',          # Numeric invoice type code, e.g. 380
  70     'ustid',         # The creditor's UStID.
  71     'vendor_name',   # The vendor's company name
  72   );
  73   return \@keys;
  74 }
  75
  76 =item item_keys()
  77
  78 Returns all keys the item hashes returned by any child's C<items()> method must
  79 contain. If you add keys to this list, you need to add them to all classes
  80 inheriting from C<SL::XMLInvoice> as well. An application may use this method
  81 to discover the metadata keys guaranteed to be present.
  82
  83 =back
  84
  85 =cut
  86
  87 sub item_keys  {
  88   my @keys = (
  89     'currency',
  90     'description',
  91     'price',
  92     'quantity',
  93     'subtotal',
  94     'tax_rate',
  95     'tax_scheme',
  96     'vendor_partno',
  97   );
  98   return \@keys;
  99 }
 100
 101 =head2 User/application facing methods
 102
 103 Any class inheriting from C<SL::XMLInvoice> must implement the following
 104 methods. To ensure this happens, C<SL::XMLInvoice> contains stub functions that
 105 raise an exception if a child class does not override them.
 106
 107 =over 4
 108
 109 =item new($xml_data)
 110
 111 Constructor for C<SL::XMLInvoice>. This method takes a scalar containing the
 112 entire XML document to be parsed as a flat string as its sole argument. It will
 113 instantiate the appropriate child class to parse the XML document in question,
 114 call its C<parse_xml> method and return the C<SL::XMLInvoice> child object it
 115 instantiated. From that point on, the structured data retrieved from the XML
 116 document will be available through the object's C<metadata> and C<items()>
 117 methods.
 118
 119 =item metadata()
 120
 121 This method returns a hash of document level metadata, such as the invoice
 122 number, the total, or the the issuance date. Its keys are the keys returned by
 123 the C<(data_keys()> method. Its values are plain scalars containing strings or
 124 C<undef> for any data items not present or empty in the XML document.
 125
 126 =cut
 127
 128 sub metadata {
 129   my $self = shift;
 130   die "Children of $self must implement a metadata() method returning the bill's metadata as a hash.";
 131 }
 132
 133 =item check_signature($dom)
 134
 135 This static method takes a DOM object and returns 1 if this DOM object can be
 136 parsed by the child class in question, 0 otherwise. C<SL::XMLInvoice> uses this
 137 method to determine which child class to instantiate for a given document. All
 138 child classes must implement this method.
 139
 140 =cut
 141
 142 sub check_signature {
 143   my $self = shift;
 144   die "Children of $self must implement a check_signature() method returning 1 for supported XML, 0 for unsupported XML.";
 145 }
 146
 147 =item supported()
 148
 149 This static method returns an array of free-form strings describing XML invoice
 150 types parseable by the child class. C<SL::XMLInvoice> uses this method to
 151 output a list of supported XML invoice types if its constructor fails to find
 152 to find an appropriate child class to parse the given document with. All child
 153 classes must implement this method.
 154
 155 =cut
 156
 157 sub supported {
 158   my $self = shift;
 159   die "Children of $self must implement a supported() method returning a list of supported XML invoice types.";
 160 }
 161
 162
 163 =item items()
 164
 165 This method returns an array of hashes containing line item metadata, such as
 166 the quantity, price for one unit, or subtotal. These hashes' keys are the keys
 167 returned by the C<(item_keys()> method. Its values are plain scalars containing
 168 strings or C<undef> for any data items not present or empty in the XML
 169 document.
 170
 171 =cut
 172
 173 sub items {
 174   my $self = shift;
 175   die "Children of $self must implement a item() method returning the bill's items as a hash.";
 176 }
 177
 178
 179 =item parse_xml()
 180
 181 This method is only implemented in child classes of C<SL::XMLInvoice> and is
 182 called by the C<SL::XMLInvoice> constructor once the appropriate child class has been
 183 determined and instantiated. It uses C<$self->{dom}>, an C<XML::LibXML>
 184 instance to iterate through the XML document to parse. That XML document is
 185 created by the C<SL::XMLInvoice> constructor.
 186
 187 =back
 188
 189 =cut
 190
 191 sub parse_xml {
 192   my $self = shift;
 193   die "Children of $self must implement a parse_xml() method.";
 194 }
 195
 196 =head2 Internal methods
 197
 198 These methods' purpose is child classs selection and making sure child classes
 199 implent the interface promised by C<SL::XMLInvoice::Base>. You can safely ignore them
 200 if you don't plan on implementing any child classes.
 201
 202 =over 4
 203
 204 =item _data_keys()
 205
 206 Returns a list of all keys present in the hash returned by the class'
 207 C<metadata()> method. Must be implemented in all classes inheriting from
 208 C<SL::XMLInvoice> This list must contain the same keys as the list returned by
 209 C<data_keys>. Omitting this method from a child class will cause an exception.
 210
 211 =cut
 212
 213 sub _data_keys {
 214   my $self = shift;
 215   die "Children of $self must implement a _data_keys() method returning the keys an invoice item hash will contain.";
 216 }
 217
 218 =item _item_keys()
 219
 220 Returns a list of all keys present in the hashes returned by the class'
 221 C<items()> method. Must be implemented in all classes inheriting from
 222 C<SL::XMLInvoice> This list must contain the same keys as the list returned by
 223 C<item_keys>. Omitting this method from a child class will cause an exception.
 224
 225 =back
 226
 227 =head1 AUTHOR
 228
 229   Johannes Grassler <info@computer-grassler.de>
 230
 231 =cut
 232
 233 sub _item_keys {
 234   my $self = shift;
 235   die "Children of $self must implement a _item_keys() method returning the keys an invoice item hash will contain.";
 236 }
 237
 238
 239
 240 1;