documentation

bestpractical · Jan 26, 2011 · e966694 · e966694
1 parent cd8346e
commit e966694
Show file tree

Hide file tree

Showing 2 changed files with 182 additions and 9 deletions.
diff --git a/README b/README
@@ -3,12 +3,91 @@ NAME
 
 SYNOPSIS
         use Parse::ACNS;
-        my $parser = Parse::ACNS->new(
-            version => 'compat',
-        );
-        $parser->parse( );
+        my $data = Parse::ACNS->new->parse( XML::LibXML->load_xml( string => $xml ) );
 
 DESCRIPTION
+    ACNS stands for Automated Copyright Notice System. It's an open source,
+    royalty free system that universities, ISP's, or anyone that handles
+    large volumes of copyright notices can implement on their network to
+    increase the efficiency and reduce the costs of responding to the
+    notices... See "http://mpto.unistudios.com/xml/" for more details.
+
+    This module parses ACNS XML into a perl data structure. Supports both
+    0.6 and 0.7 version. Parser strictly follows XML Schemas, so throws
+    errors on malformed data.
+
+    However, it doesn't extract ACNS XML from email messages.
+
+METHODS
+  new
+    Constructor, takes list of named arguments.
+
+    version - version of the specification
+
+        compat - default value, can parse both 0.7 and 0.6 XML by making
+        TimeStamp element in Infringement/Content/Item optional. This is the
+        only difference between the spec versions.
+        0.7 or 0.6 - strict parsing of the specified version.
+
+  parse
+        my $data = Parse::ACNS->new->parse( XML::LibXML->load_xml(...) );
+
+    Takes XML::LibXML::Document containing an ACNS XML and returns it as a
+    perl struture. Read XML::LibXML::Parser on parsing from different
+    sources.
+
+    Returned data structure follows XML and its Schema, for example:
+
+        {
+            'Case' => {
+                'ID' => 'A1234567',
+                'Status' => ...,
+                ...
+            },
+            'Complainant' => {
+                'Email' => 'antipiracy@contentowner.com',
+                'Phone' => ...,
+                ...
+            },
+            'Source' => {
+                'TimeStamp' => '2003-08-30T12:34:53Z',
+                'UserName' => 'guest',
+                'Login' => { ... },
+                'IP_Address' => ...,
+                ...
+            }
+            'Service_Provider' => { ... }
+            'Content' => {
+                'Item' => [
+                    {
+                        'TimeStamp' => '2003-08-30T12:34:53Z',
+                        'FileName' => '8Mile.mpg',
+                        'Hash' => {
+                                'Type' => 'SHA1',
+                                '_' => 'EKR94KF985873KD930ER4KD94'
+                              },
+                        ...
+                    },
+                    { ... },
+                    ...
+                ]
+            },
+            'History' => {
+                'Notice' => [
+                    {
+                        'ID' => '12321',
+                        'TimeStamp' => '2003-08-30T10:23:13Z',
+                        '_' => 'freeform text area'
+                    },
+                    { ... },
+                    ...
+                ]
+            },
+            'Notes' => '
+                Open area for freeform text notes, filelists, etc...
+            '
+        }
+
 AUTHOR
     Ruslan Zakirov <ruz@bestpractical.com>
 

diff --git a/lib/Parse/ACNS.pm b/lib/Parse/ACNS.pm
@@ -11,15 +11,24 @@ our $VERSION = '0.01';
 Parse::ACNS - parser for Automated Copyright Notice System (ACNS) XML
 
 =head1 SYNOPSIS
-    
+
     use Parse::ACNS;
-    my $parser = Parse::ACNS->new(
-        version => 'compat',
-    );
-    $parser->parse( );
+    my $data = Parse::ACNS->new->parse( XML::LibXML->load_xml( string => $xml ) );
 
 =head1 DESCRIPTION
 
+ACNS stands for Automated Copyright Notice System. It's an open source,
+royalty free system that universities, ISP's, or anyone that handles large
+volumes of copyright notices can implement on their network to increase
+the efficiency and reduce the costs of responding to the notices... 
+See "http://mpto.unistudios.com/xml/" for more details.
+
+This module parses ACNS XML into a perl data structure. Supports both 0.6 and
+0.7 version. Parser strictly follows XML Schemas, so throws errors on malformed
+data.
+
+However, it B<doesn't> extract ACNS XML from email messages.
+
 =cut
 
 use File::ShareDir ();
@@ -31,6 +40,30 @@ use XML::Compile::Schema;
 our %CACHE = (
 );
 
+=head1 METHODS
+
+=head2 new
+
+Constructor, takes list of named arguments.
+
+=over 4
+
+=item version - version of the specification
+
+=over 4
+
+=item compat - default value, can parse both 0.7 and 0.6 XML by making
+TimeStamp element in Infringement/Content/Item optional. This is the
+only difference between the spec versions.
+
+=item 0.7 or 0.6 - strict parsing of the specified version.
+
+=back
+
+=back
+
+=cut
+
 sub new {
     my $proto = shift;
     return (bless { @_ }, ref($proto) || $proto)->init;
@@ -61,6 +94,67 @@ sub init {
     return $self;
 }
 
+=head2 parse
+
+    my $data = Parse::ACNS->new->parse( XML::LibXML->load_xml(...) );
+
+Takes L<XML::LibXML::Document> containing an ACNS XML and returns it as a perl
+struture. Read L<XML::LibXML::Parser> on parsing from different sources.
+
+Returned data structure follows XML and its Schema, for example:
+
+    {
+        'Case' => {
+            'ID' => 'A1234567',
+            'Status' => ...,
+            ...
+        },
+        'Complainant' => {
+            'Email' => 'antipiracy@contentowner.com',
+            'Phone' => ...,
+            ...
+        },
+        'Source' => {
+            'TimeStamp' => '2003-08-30T12:34:53Z',
+            'UserName' => 'guest',
+            'Login' => { ... },
+            'IP_Address' => ...,
+            ...
+        }
+        'Service_Provider' => { ... }
+        'Content' => {
+            'Item' => [
+                {
+                    'TimeStamp' => '2003-08-30T12:34:53Z',
+                    'FileName' => '8Mile.mpg',
+                    'Hash' => {
+                            'Type' => 'SHA1',
+                            '_' => 'EKR94KF985873KD930ER4KD94'
+                          },
+                    ...
+                },
+                { ... },
+                ...
+            ]
+        },
+        'History' => {
+            'Notice' => [
+                {
+                    'ID' => '12321',
+                    'TimeStamp' => '2003-08-30T10:23:13Z',
+                    '_' => 'freeform text area'
+                },
+                { ... },
+                ...
+            ]
+        },
+        'Notes' => '
+            Open area for freeform text notes, filelists, etc...
+        '
+    }
+
+=cut
+
 sub parse {
     my $self = shift;
     return $self->{'reader'}->( shift );