rcap-rails-generators 1.3

data/CHANGELOG.rdoc

@@ -0,0 +1,25 @@
+= Change Log
+
+== 1.0 - 16th March 2011
+
+* Added Rails generators [pgeorge]
+
+== 0.4 - 6th March 2011
+
+* Implemented Hash generation and parsing
+* Implemented JSON generation and parsing
+* Circle is now a subclass of Point
+
+== 0.3 - 26th November 2009
+
+* Bugfix release
+
+== 0.2 - 20th November 2009
+
+* Implemented to_s/inspect methods for all classes
+* Implemented YAML generation and parsing
+* Documentation improvements
+
+== 0.1 - 5th November 2009
+
+* Initial release

data/README.rdoc

@@ -0,0 +1,248 @@
+= rcap-rails-generators - Generators for the Common Alerting Protocol for Ruby on Rails
+
+== Overview
+
+The Common Alerting Protocol is a lightweight standard to facilitate the distribution of alerting data. RCAP is an implementation of the CAP in Ruby. It allows for the creation of RCAP messages from Ruby applications and the parsing of external messages.
+
+RCAP currently supports only CAP Version 1.1 and rcap-rails-generators only supports Rails 3.X.
+
+This gem is a set of generators for creating RCAP ActiveRecord models and migrations.
+
+== Version
+
+1.3
+
+== Dependencies
+
+rcap-rails-generators depends on the following gems
+
+* {Assistance}[http://assistance.rubyforge.org]
+* {UUIDTools}[http://uuidtools.rubyforge.org]
+* {JSON}[http://json.rubyforge.org]
+
+rcap-rails-generators uses the REXML API, included in Ruby, to parse and generate XML.
+
+== Installation
+
+rcap-rails-generators is distributed as a Ruby gem and is available from {Gemcutter}[http://gemcutter.org]. If you have Gemcutter set as a source of your gems then rcap-rails-generators can be installed from the command line
+
+ gem install rcap-rails-generators
+
+or via Bundler
+
+ gem 'rcap-rails-generators'
+
+The gem is also available for download and manual installtion at http://www.aimred.com/gems .
+
+Once installed you can run:
+
+ rails generate rcap:models
+
+and
+
+ rails generate rcap:migrations
+
+to create the respective files.
+
+rcap:models also installs a couple of necessary modules in your Rails.root/lib directory.  You will need to make sure they are required:
+
+# config/initializers/load_extensions.rb
+require 'rcap'
+require 'validations'
+
+== Web resources
+
+* The RCAP project page can be found at http://www.aimred.com/projects/rcap
+* The RCAP API docs can be fount at http://www.aimred.com/projects/rcap/api
+* A public git repository can be found at git://github.com/farrel/RCAP.git
+
+== Usage
+
+To include RCAP into your application add the following require
+
+ require 'rcap'
+
+All RCAP classes reside in the RCAP namespace but including the RCAP module makes the classes available at the top level without the RCAP prefix.
+
+ alert = RCAP::Alert.new(...
+
+ include RCAP # Include RCAP module into namespace
+ alert = Alert.new(...
+
+=== Creating an Alert
+
+ alert = Alert.new( :sender   => 'cape_town_disaster_relief@capetown.municipal.za',
+                    :status   => Alert::STATUS_ACTUAL,
+                    :msg_type => Alert::MSG_TYPE_ALERT,
+                    :scope    => Alert::SCOPE_PUBLIC,
+                    :infos    => Info.new( :event       => 'Liquid Petroleoum Tanker Fire',
+                                           :language    => 'en-ZA',
+                                           :categories  => [ Info::CATEGORY_TRANSPORT, Info::CATEGORY_FIRE ],
+                                           :urgency     => Info::URGENCY_IMMEDIATE,
+                                           :severity    => Info::SEVERITY_SEVERE,
+                                           :certainty   => Info::CERTAINTY_OBSERVED,
+                                           :headline    => 'LIQUID PETROLEOUM TANKER FIRE ON N2 INCOMING FREEWAY',
+                                           :description => 'A liquid petroleoum tanker has caught fire on the N2 incoming freeway 1km
+                                                           after the R300 interchange.  Municipal fire fighting crews have been dispatched.
+                                                           Traffic control officers are on the scene and have diverted traffic onto
+                                                           alternate routes.' ))
+
+ # Accessing attributes
+ puts alert.status                          # Print out "Actual"
+ puts alert.infos[0].language               # Print out "en-ZA"
+ puts alert.infos[0].categories.join( ' ' ) # Print out "Transport Fire"
+
+=== Exporting an Alert
+
+==== To XML
+
+Using the alert message created above
+
+ puts alert.to_xml # Print out CAP XML message
+
+Will print the following CAP XML
+
+  <?xml version='1.0'?>
+  <alert xmlns='urn:oasis:names:tc:emergency:cap:1.1'>
+    <identifier>494207a7-f86b-4060-8318-a4b2a3ce565e</identifier>
+    <sender>cape_town_disaster_relief@capetown.municipal.za</sender>
+    <sent>2009-10-26T21:04:51+02:00</sent>
+    <status>Actual</status>
+    <msgType>Alert</msgType>
+    <scope>Public</scope>
+    <info>
+      <language>en-ZA</language>
+      <category>Transport</category>
+      <category>Fire</category>
+      <event>Liquid Petroleoum Tanker Fire</event>
+      <urgency>Immediate</urgency>
+      <severity>Severe</severity>
+      <certainty>Observed</certainty>
+      <headline>LIQUID PETROLEOUM TANKER FIRE ON N2 INCOMING FREEWAY</headline>
+      <description>
+        A liquid petroleoum tanker has caught fire on the N2 incoming freeway 1km
+        after the R300 interchange. Municipal fire fighting crews have been
+        dispatched. Traffic control officers are on the scene and have diverted
+        traffic onto alternate routes.
+      </description>
+    </info>
+  </alert>
+
+==== To YAML
+
+YAML is a plain text serialization format designed to be easily readable and editable by both human and machine. RCAP has custom YAML generation and parsing methods to produce a YAML document that is as human friednly as possible. The following code
+
+ alert.to_yaml
+
+will produce the following YAML document
+
+ ---
+ Identifier: 2a1ba96d-16e4-4f52-85ea-0258c1440bd5
+ Sender: cape_town_disaster_relief@capetown.municipal.za
+ Sent: 2009-11-19T02:41:29+02:00
+ Status: Actual
+ Message Type: Alert
+ Scope: Public
+ Information:
+ - Language: en-ZA
+   Categories: [Transport, Fire]
+   Event: Liquid Petroleoum Tanker Fire
+   Urgency: Immediate
+   Severity: Severe
+   Certainty: Observed
+   Headline: LIQUID PETROLEOUM TANKER FIRE ON N2 INCOMING FREEWAY
+   Description: |-
+     A liquid petroleoum tanker has caught fire on the N2 incoming freeway 1km
+     after the R300 interchange.  Municipal fire fighting crews have been dispatched.
+     Traffic control officers are on the scene and have diverted traffic onto
+     alternate routes.
+
+Note: If you use Ruby 1.8 the order of the attributes is jumbled due to hashes being unorderd (Ruby 1.9 implements ordered hashes). This does not affect the ability to parse documents generated from RCAP::Alert#to_yaml, it just makes things the output slightly messy.
+
+=== To JSON
+
+JSON(JavaScript Object Notation) is a text serialization format that can be easily loaded in a JavaScript environment.
+
+ alert.to_json
+
+will produce the following JSON string
+
+ {"identifier":"0eb97e40-195b-437b-9a01-55fe89691def",
+  "sender":"cape_town_disaster_relief@capetown.municipal.za",
+  "sent":"2011-03-04T15:58:01+02:00",
+  "status":"Actual",
+  "msg_type":"Alert",
+  "scope":"Public",
+  "infos":[
+    {"language":"en-ZA",
+     "categories":["Transport","Fire"],
+     "event":"Liquid Petroleoum Tanker Fire",
+     "urgency":"Immediate",
+     "severity":"Severe",
+     "certainty":"Observed",
+     "headline":"LIQUID PETROLEOUM TANKER FIRE ON N2 INCOMING FREEWAY",
+     "description":"A liquid petroleoum tanker has caught fire on the N2 incoming freeway 1km
+                    after the R300 interchange. Municipal fire fighting crews have been dispatched.
+                    Traffic control officers are on the scene and have diverted traffic onto \nalternate routes."}]}
+
+=== Parsing an Alert From An External Source
+
+==== From XML
+
+RCAP allows for the parsing of a CAP XML string
+
+ alert = RCAP::Alert.from_xml( xml_string )
+
+Currently RCAP only supports version 1.1 of the CAP standard and the parser is as strict as possible when parsing data.
+
+==== From YAML
+
+Alert messgaes can be read in from text files containing data formatted in YAML as generated by Alert#to_yaml.
+
+ alert = RCAP::Alert.from_yaml( yaml_string )
+
+==== From JSON
+
+An Alert can also be initialised from a JSON string produced by Alert#to_json
+
+ alert = RCAP::Alert.from_json( json_string )
+
+=== Validating an alert
+
+The RCAP API aims to codify as many of the rules of the CAP XML format into validation rules that can be checked using the Assistance API. The following Info object has two attributes ('severity' and 'certainty') set to incorrect values.
+
+ info = Info.new( :event      => 'Liquid Petroleoum Tanker Fire',
+                  :language   => 'en-ZA',
+                  :categories => [ Info::CATEGORY_TRANSPORT, Info::CATEGORY_FIRE ],
+                  :urgency    => Info::URGENCY_IMMEDIATE,
+                  :severity   => nil,                   # Severity is not assigned
+                  :certainty  => 'Unknown Certainty' )  # Certainty is assigned in incorrect value
+
+ puts "Is info valid: #{ info.valid? }"
+ info.errors.full_messages.each{ |message| puts "Error: #{ message }" }
+
+Will produce the folling output:
+
+ Is info valid: false
+ Error: severity is not present
+ Error: certainty can only be assigned the following values: Observed, Likely, Possible, Unlikely, Unknown
+
+All RCAP classes include the Validation module.
+
+A full spec suite using {RSpec}[http://www.rspec.info] was used to test the validations and currently numbers over 250 tests.
+
+=== DateTime and Time
+
+It is highly recommended that when dealing with date and time fields (onset, expires etc) that the DateTime class is used to ensure the correct formatting of dates. The Time class can be used when generating a CAP alert XML message however any CAP alert that is parsed from an external XML source will use DateTime by default.
+
+== Authors
+
+Farrel Lifson - farrel.lifson@aimred.com
+
+== License
+
+RCAP is released under the BSD License.
+
+== Copyright
+
+2009-2011 Aimred CC

data/lib/generators/rcap/migrations/migrations_generator.rb

@@ -0,0 +1,38 @@
+require 'rails/generators/migration'
+
+module Rcap
+  module Generators
+    class MigrationsGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      desc <<DESC
+Description:
+    Generate RCAP migrations.
+DESC
+
+      def self.source_root
+        @_rcap_source_root ||= File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
+      end
+
+      def create_migration_file
+        Dir[File.join(MigrationsGenerator.source_root, '*_migration.rb')].each do |file|
+          model = file[/(.*\/)?(.*)_migration.rb/, 2]
+          migration_template file, "db/migrate/create_#{model}_table.rb"
+          Kernel::sleep 1
+        end
+      end
+
+      protected
+
+      no_tasks do
+        def self.next_migration_number(dirname) #:nodoc:
+          if ActiveRecord::Base.timestamped_migrations
+            Time.now.utc.strftime("%Y%m%d%H%M%S")
+          else
+            "%.3d" % (current_migration_number(dirname) + 1)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/rcap/migrations/templates/alerts_migration.rb

@@ -0,0 +1,27 @@
+class CreateAlertsTable < ActiveRecord::Migration
+  def self.up
+    create_table :alerts do |t|
+      t.integer :user_id
+
+      t.string :identifier
+      t.string :sender
+      t.datetime :sent_at
+      t.string :status
+      t.string :msg_type
+      t.string :source
+      t.string :scope
+      t.text   :restriction
+      t.text   :addresses
+      t.string :code
+      t.text   :note
+      t.text   :references
+      t.text   :incidents
+
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :alerts
+  end
+end

data/lib/generators/rcap/migrations/templates/areas_migration.rb

@@ -0,0 +1,14 @@
+class CreateAreasTable < ActiveRecord::Migration
+  def self.up
+    create_table :areas do |t|
+      t.integer :alert_id
+      t.text :description
+
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :areas
+  end
+end

data/lib/generators/rcap/migrations/templates/infos_migration.rb

@@ -0,0 +1,33 @@
+class CreateInfosTable < ActiveRecord::Migration
+  def self.up
+    create_table :infos do |t|
+      t.integer :alert_id
+
+      t.string :language
+      t.string :categories
+      t.string :event
+      t.string :response_types
+      t.string :urgency
+      t.string :severity
+      t.string :certainty
+      t.string :audience
+      t.string :event_codes
+      t.datetime :effective_at
+      t.datetime :onset_at
+      t.datetime :expires_at
+      t.string :sender_name
+      t.text   :headline
+      t.text   :description
+      t.text   :instruction
+      t.string :web
+      t.string :contact
+      t.text   :parameters
+
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :infos
+  end
+end

data/lib/generators/rcap/migrations/templates/resources_migration.rb

@@ -0,0 +1,14 @@
+class CreateResourcesTable < ActiveRecord::Migration
+  def self.up
+    create_table :resources do |t|
+      t.integer :alert_id
+      t.string :description
+
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :resources
+  end
+end

data/lib/generators/rcap/models/models_generator.rb

@@ -0,0 +1,33 @@
+module Rcap
+  module Generators
+    class ModelsGenerator < Rails::Generators::Base
+      desc <<DESC
+Description:
+    Copy RCAP models to your application.
+DESC
+
+      def self.source_root
+        @_rcap_source_root ||= File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
+      end
+
+      def self.banner
+        "rails generate rcap:models"
+      end
+
+      def copy_model_files
+        directory 'models', 'app/models'
+      end
+
+      def copy_lib_files
+        copy_file 'modules/rcap.rb', 'lib/rcap.rb'
+      end
+
+      private
+
+      def print_usage
+        self.class.help(Thor::Base.shell.new)
+        exit
+      end
+    end
+  end
+end

data/lib/generators/rcap/models/templates/models/alert.rb

@@ -0,0 +1,365 @@
+require 'uuidtools'
+
+# An Alert object is valid if
+# * it has an identifier
+# * it has a sender
+# * it has a sent time
+# * it has a valid status value
+# * it has a valid messge type value
+# * it has a valid scope value
+# * all Info objects contained in infos are valid
+class Alert < ActiveRecord::Base
+  include Validation
+  include RCAP
+
+  belongs_to :user
+  has_many :infos
+
+  before_validation :set_identifier, :set_sent_at
+
+  STATUS_ACTUAL   = "Actual"   # :nodoc:
+  STATUS_EXERCISE = "Exercise" # :nodoc:
+  STATUS_SYSTEM   = "System"   # :nodoc:
+  STATUS_TEST     = "Test"     # :nodoc:
+  STATUS_DRAFT    = "Draft"    # :nodoc:
+  # Valid values for status
+  VALID_STATUSES = [ STATUS_ACTUAL, STATUS_EXERCISE, STATUS_SYSTEM, STATUS_TEST, STATUS_DRAFT ]
+
+  MSG_TYPE_ALERT  = "Alert"   # :nodoc:
+  MSG_TYPE_UPDATE = "Update"  # :nodoc:
+  MSG_TYPE_CANCEL = "Cancel"  # :nodoc:
+  MSG_TYPE_ACK    = "Ack"     # :nodoc:
+  MSG_TYPE_ERROR  = "Error"   # :nodoc:
+  # Valid values for msg_type
+  VALID_MSG_TYPES = [ MSG_TYPE_ALERT, MSG_TYPE_UPDATE, MSG_TYPE_CANCEL, MSG_TYPE_ACK, MSG_TYPE_ERROR ]
+
+  SCOPE_PUBLIC     = "Public"        # :nodoc:
+  SCOPE_RESTRICTED = "Restricted"    # :nodoc:
+  SCOPE_PRIVATE    = "Private"       # :nodoc:
+  # Valid values for scope
+  VALID_SCOPES = [ SCOPE_PUBLIC, SCOPE_PRIVATE, SCOPE_RESTRICTED ]
+
+  XML_ELEMENT_NAME         = 'alert'       # :nodoc:
+  IDENTIFIER_ELEMENT_NAME  = 'identifier'  # :nodoc:
+  SENDER_ELEMENT_NAME      = 'sender'      # :nodoc:
+  SENT_ELEMENT_NAME        = 'sent'        # :nodoc:
+  STATUS_ELEMENT_NAME      = 'status'      # :nodoc:
+  MSG_TYPE_ELEMENT_NAME    = 'msgType'     # :nodoc:
+  SOURCE_ELEMENT_NAME      = 'source'      # :nodoc:
+  SCOPE_ELEMENT_NAME       = 'scope'       # :nodoc:
+  RESTRICTION_ELEMENT_NAME = 'restriction' # :nodoc:
+  ADDRESSES_ELEMENT_NAME   = 'addresses'   # :nodoc:
+  CODE_ELEMENT_NAME        = 'code'        # :nodoc:
+  NOTE_ELEMENT_NAME        = 'note'        # :nodoc:
+  REFERENCES_ELEMENT_NAME  = 'references'  # :nodoc:
+  INCIDENTS_ELEMENT_NAME   = 'incidents'   # :nodoc:
+
+  XPATH             = 'cap:alert'                         # :nodoc:
+  IDENTIFIER_XPATH  = "cap:#{ IDENTIFIER_ELEMENT_NAME }"  # :nodoc:
+  SENDER_XPATH      = "cap:#{ SENDER_ELEMENT_NAME }"      # :nodoc:
+  SENT_XPATH        = "cap:#{ SENT_ELEMENT_NAME }"        # :nodoc:
+  STATUS_XPATH      = "cap:#{ STATUS_ELEMENT_NAME }"      # :nodoc:
+  MSG_TYPE_XPATH    = "cap:#{ MSG_TYPE_ELEMENT_NAME }"    # :nodoc:
+  SOURCE_XPATH      = "cap:#{ SOURCE_ELEMENT_NAME }"      # :nodoc:
+  SCOPE_XPATH       = "cap:#{ SCOPE_ELEMENT_NAME }"       # :nodoc:
+  RESTRICTION_XPATH = "cap:#{ RESTRICTION_ELEMENT_NAME }" # :nodoc:
+  ADDRESSES_XPATH   = "cap:#{ ADDRESSES_ELEMENT_NAME }"   # :nodoc:
+  CODE_XPATH        = "cap:#{ CODE_ELEMENT_NAME }"        # :nodoc:
+  NOTE_XPATH        = "cap:#{ NOTE_ELEMENT_NAME }"        # :nodoc:
+  REFERENCES_XPATH  = "cap:#{ REFERENCES_ELEMENT_NAME }"  # :nodoc:
+  INCIDENTS_XPATH   = "cap:#{ INCIDENTS_ELEMENT_NAME }"   # :nodoc:
+
+  # # If not set a UUID will be set by default
+  # attr_accessor( :identifier)
+  # attr_accessor( :sender )
+  # # Sent Time - If not set will value will be time of creation.
+  # attr_accessor( :sent )
+  # # Value can only be one of VALID_STATUSES
+  # attr_accessor( :status )
+  # # Value can only be one of VALID_MSG_TYPES
+  # attr_accessor( :msg_type )
+  # # Value can only be one of VALID_SCOPES
+  # attr_accessor( :scope )
+  # attr_accessor( :source )
+  # # Depends on scope being SCOPE_RESTRICTED.
+  # attr_accessor( :restriction )
+  # attr_accessor( :code )
+  # attr_accessor( :note )
+  #
+  # # Collection of address strings. Depends on scope being SCOPE_PRIVATE.
+  # attr_reader( :addresses )
+  # # Collection of reference strings - see Alert#to_reference
+  # attr_reader( :references)
+  # # Collection of incident strings
+  # attr_reader( :incidents )
+  # # Collection of Info objects
+  # attr_reader( :infos )
+
+  validates_presence_of( :identifier, :sender, :sent_at, :status, :msg_type, :scope )
+
+  validates_inclusion_of( :status,   :in => VALID_STATUSES )
+  validates_inclusion_of( :msg_type, :in => VALID_MSG_TYPES )
+  validates_inclusion_of( :scope,    :in => VALID_SCOPES )
+
+  validates_format_of( :identifier, :with => ALLOWED_CHARACTERS )
+  validates_format_of( :sender ,    :with => ALLOWED_CHARACTERS )
+
+  validates_dependency_of( :addresses,   :on => :scope, :with_value => SCOPE_PRIVATE )
+  validates_dependency_of( :restriction, :on => :scope, :with_value => SCOPE_RESTRICTED )
+
+  # validates_collection_of( :infos )
+
+  # def initialize( attributes = {})
+  #   attributes = {} unless attributes
+  #   @identifier  = attributes[ :identifier ] || UUIDTools::UUID.random_create.to_s
+  #   @sender      = attributes[ :sender ]
+  #   @sent        = attributes[ :sent ] || DateTime.now
+  #   @status      = attributes[ :status ]
+  #   @msg_type    = attributes[ :msg_type ]
+  #   @scope       = attributes[ :scope ]
+  #   @source      = attributes[ :source ]
+  #   @restriction = attributes[ :restriction ]
+  #   @addresses   = Array( attributes[ :addresses ])
+  #   @references  = Array( attributes[ :references ])
+  #   @incidents   = Array( attributes[ :incidents ])
+  #   @infos       = Array( attributes[ :infos ])
+  # end
+
+  def to_xml_element #:nodoc:
+    xml_element = REXML::Element.new( XML_ELEMENT_NAME )
+    xml_element.add_namespace( RCAP::XMLNS )
+    xml_element.add_element( IDENTIFIER_ELEMENT_NAME ).add_text( self.identifier )
+    xml_element.add_element( SENDER_ELEMENT_NAME ).add_text( self.sender )
+    xml_element.add_element( SENT_ELEMENT_NAME ).add_text( self.sent.to_s )
+    xml_element.add_element( STATUS_ELEMENT_NAME ).add_text( self.status )
+    xml_element.add_element( MSG_TYPE_ELEMENT_NAME ).add_text( self.msg_type )
+    xml_element.add_element( SOURCE_ELEMENT_NAME ).add_text( self.source ) if self.source
+    xml_element.add_element( SCOPE_ELEMENT_NAME ).add_text( self.scope )
+    xml_element.add_element( RESTRICTION_ELEMENT_NAME ).add_text( self.restriction ) if self.restriction
+    unless self.addresses.empty?
+      xml_element.add_element( ADDRESSES_ELEMENT_NAME ).add_text( self.addresses.to_s_for_cap )
+    end
+    xml_element.add_element( CODE_ELEMENT_NAME ).add_text( self.code ) if self.code
+    xml_element.add_element( NOTE_ELEMENT_NAME ).add_text( self.note ) if self.note
+    unless self.references.empty?
+      xml_element.add_element( REFERENCES_ELEMENT_NAME ).add_text( self.references.join( ' ' ))
+    end
+    unless self.incidents.empty?
+      xml_element.add_element( INCIDENTS_ELEMENT_NAME ).add_text( self.incidents.join( ' ' ))
+    end
+    self.infos.each do |info|
+      xml_element.add_element( info.to_xml_element )
+    end
+    xml_element
+  end
+
+  def to_xml_document #:nodoc:
+    xml_document = REXML::Document.new
+    xml_document.add( REXML::XMLDecl.new )
+    xml_document.add( self.to_xml_element )
+    xml_document
+  end
+
+  # Returns a string containing the XML representation of the alert.
+  def to_xml
+    self.to_xml_document.to_s
+  end
+
+  # Returns a string representation of the alert suitable for usage as a reference in a CAP message of the form
+  #  sender,identifier,sent
+  def to_reference
+    "#{ self.sender },#{ self.identifier },#{ self.sent }"
+  end
+
+  def inspect # :nodoc:
+    alert_inspect = <<EOF
+CAP Version:  #{ RCAP::CAP_VERSION }
+Identifier:   #{ self.identifier }
+Sender:       #{ self.sender }
+Sent:         #{ self.sent_at }
+Status:       #{ self.status }
+Message Type: #{ self.msg_type }
+Source:       #{ self.source }
+Scope:        #{ self.scope }
+Restriction:  #{ self.restriction }
+Addresses:    #{ self.addresses.to_s_for_cap if self.addresses }
+Code:         #{ self.code }
+Note:         #{ self.note }
+References:   #{ self.references.join( ' ' ) if self.references }
+Incidents:    #{ self.incidents.join( ' ') if self.incidents }
+Information:
+#{ self.infos.map{ |info| "  " + info.to_s }.join( "\n" )}
+EOF
+    RCAP.format_lines_for_inspect( 'ALERT', alert_inspect )
+  end
+
+  # Returns a string representation of the alert of the form
+  #  sender/identifier/sent
+  # See Alert#to_reference for another string representation suitable as a CAP reference.
+  def to_s
+    "#{ self.sender }/#{ self.identifier }/#{ self.sent }"
+  end
+
+  def self.from_xml_element( alert_xml_element ) # :nodoc:
+    self.new( :identifier  => RCAP.xpath_text( alert_xml_element, RCAP::Alert::IDENTIFIER_XPATH ),
+              :sender      => RCAP.xpath_text( alert_xml_element, SENDER_XPATH ),
+              :sent_at     => (( sent = RCAP.xpath_first( alert_xml_element, SENT_XPATH )) ? DateTime.parse( sent.text ) : nil ),
+              :status      => RCAP.xpath_text( alert_xml_element, STATUS_XPATH ),
+              :msg_type    => RCAP.xpath_text( alert_xml_element, MSG_TYPE_XPATH ),
+              :source      => RCAP.xpath_text( alert_xml_element, SOURCE_XPATH ),
+              :scope       => RCAP.xpath_text( alert_xml_element, SCOPE_XPATH ),
+              :restriction => RCAP.xpath_text( alert_xml_element, RESTRICTION_XPATH ),
+              :addresses   => (( address = RCAP.xpath_text( alert_xml_element, ADDRESSES_XPATH )) ? address.unpack_cap_list : nil ),
+              :code        => RCAP.xpath_text( alert_xml_element, CODE_XPATH ),
+              :note        => RCAP.xpath_text( alert_xml_element, NOTE_XPATH ),
+              :references  => (( references = RCAP.xpath_text( alert_xml_element, REFERENCES_XPATH )) ? references.split( ' ' ) : nil ),
+              :incidents   => (( incidents = RCAP.xpath_text( alert_xml_element, INCIDENTS_XPATH )) ? incidents.split( ' ' ) : nil )
+              # :infos       => RCAP.xpath_match( alert_xml_element, RCAP::Info::XPATH ).map{ |element| RCAP::Info.from_xml_element( element )}
+    )
+  end
+
+  def self.from_xml_document( xml_document ) # :nodoc:
+    self.from_xml_element( xml_document.root )
+  end
+
+  # Initialise an Alert object from an XML string. Any object that is a subclass of IO (e.g. File) can be passed in.
+  def self.from_xml( xml )
+    self.from_xml_document( REXML::Document.new( xml ))
+  end
+
+  CAP_VERSION_YAML = "CAP Version"        # :nodoc:
+  IDENTIFIER_YAML  = "Identifier"         # :nodoc:
+  SENDER_YAML      = "Sender"             # :nodoc:
+  SENT_YAML        = "Sent"               # :nodoc:
+  STATUS_YAML      = "Status"             # :nodoc:
+  MSG_TYPE_YAML    = "Message Type"       # :nodoc:
+  SOURCE_YAML      = "Source"             # :nodoc:
+  SCOPE_YAML       = "Scope"              # :nodoc:
+  RESTRICTION_YAML = "Restriction"        # :nodoc:
+  ADDRESSES_YAML   = "Addresses"          # :nodoc:
+  CODE_YAML        = "Code"               # :nodoc:
+  NOTE_YAML        = "Note"               # :nodoc:
+  REFERENCES_YAML  = "References"         # :nodoc:
+  INCIDENTS_YAML   = "Incidents"          # :nodoc:
+  INFOS_YAML       = "Information"        # :nodoc:
+
+  # Returns a string containing the YAML representation of the alert.
+  def to_yaml( options = {} )
+    RCAP.attribute_values_to_hash(
+      [ CAP_VERSION_YAML,  RCAP::CAP_VERSION ],
+      [ IDENTIFIER_YAML,    self.identifier ],
+      [ SENDER_YAML,        self.sender ],
+      [ SENT_YAML,          self.sent_at ],
+      [ STATUS_YAML,        self.status ],
+      [ MSG_TYPE_YAML,      self.msg_type ],
+      [ SOURCE_YAML,        self.source ],
+      [ SCOPE_YAML,         self.scope ],
+      [ RESTRICTION_YAML,   self.restriction ],
+      [ ADDRESSES_YAML,     self.addresses ],
+      [ CODE_YAML,          self.code ],
+      [ NOTE_YAML,          self.note ],
+      [ REFERENCES_YAML,    self.references ],
+      [ INCIDENTS_YAML,     self.incidents ],
+      [ INFOS_YAML,         self.infos ]
+    ).to_yaml( options )
+  end
+
+  # Initialise an Alert object from a YAML string. Any object that is a subclass of IO (e.g. File) can be passed in.
+  def self.from_yaml( yaml )
+    self.from_yaml_data( YAML.load( yaml ))
+  end
+
+  def self.from_yaml_data( alert_yaml_data ) # :nodoc:
+    Alert.new(
+      :identifier  => alert_yaml_data[ IDENTIFIER_YAML ],
+      :sender      => alert_yaml_data[ SENDER_YAML ],
+      :sent_at     => ( sent = alert_yaml_data[ SENT_YAML ]).blank? ? nil : DateTime.parse( sent.to_s ),
+      :status      => alert_yaml_data[ STATUS_YAML ],
+      :msg_type    => alert_yaml_data[ MSG_TYPE_YAML ],
+      :source      => alert_yaml_data[ SOURCE_YAML ],
+      :scope       => alert_yaml_data[ SCOPE_YAML ],
+      :restriction => alert_yaml_data[ RESTRICTION_YAML ],
+      :addresses   => alert_yaml_data[ ADDRESSES_YAML ],
+      :code        => alert_yaml_data[ CODE_YAML ],
+      :note        => alert_yaml_data[ NOTE_YAML ],
+      :references  => alert_yaml_data[ REFERENCES_YAML ],
+      :incidents   => alert_yaml_data[ INCIDENTS_YAML ]
+      # :infos       => Array( alert_yaml_data[ INFOS_YAML ]).map{ |info_yaml_data| RCAP::Info.from_yaml_data( info_yaml_data )}
+    )
+  end
+
+  CAP_VERSION_KEY = 'cap_version' # :nodoc:
+  IDENTIFIER_KEY  = 'identifier'  # :nodoc:
+  SENDER_KEY      = 'sender'      # :nodoc:
+  SENT_KEY        = 'sent'        # :nodoc:
+  STATUS_KEY      = 'status'      # :nodoc:
+  MSG_TYPE_KEY    = 'msg_type'    # :nodoc:
+  SOURCE_KEY      = 'source'      # :nodoc:
+  SCOPE_KEY       = 'scope'       # :nodoc:
+  RESTRICTION_KEY = 'restriction' # :nodoc:
+  ADDRESSES_KEY   = 'addresses'   # :nodoc:
+  CODE_KEY        = 'code'        # :nodoc:
+  NOTE_KEY        = 'note'        # :nodoc:
+  REFERENCES_KEY  = 'references'  # :nodoc:
+  INCIDENTS_KEY   = 'incidents'   # :nodoc:
+  INFOS_KEY       = 'infos'       # :nodoc:
+
+  # Returns a Hash representation of an Alert object
+  def to_h
+    RCAP.attribute_values_to_hash( [ CAP_VERSION_KEY, RCAP::CAP_VERSION ],
+                                  [ IDENTIFIER_KEY,   self.identifier ],
+                                  [ SENDER_KEY,       self.sender ],
+                                  [ SENT_KEY,         RCAP.to_s_for_cap( self.sent )],
+                                  [ STATUS_KEY,       self.status ],
+                                  [ MSG_TYPE_KEY,     self.msg_type ],
+                                  [ SOURCE_KEY,       self.source ],
+                                  [ SCOPE_KEY,        self.scope ],
+                                  [ RESTRICTION_KEY,  self.restriction ],
+                                  [ ADDRESSES_KEY,    self.addresses ],
+                                  [ CODE_KEY,         self.code ],
+                                  [ NOTE_KEY,         self.note ],
+                                  [ REFERENCES_KEY,   self.references ],
+                                  [ INCIDENTS_KEY,    self.incidents ],
+                                  [ INFOS_KEY,        self.infos.map{ |info| info.to_h  }])
+  end
+
+  # Initialises an Alert object from a Hash produced by Alert#to_h
+  def self.from_h( alert_hash )
+    self.new(
+      :identifier  => alert_hash[ IDENTIFIER_KEY ],
+      :sender      => alert_hash[ SENDER_KEY ],
+      :sent_at     => RCAP.parse_datetime( alert_hash[ SENT_KEY ]),
+      :status      => alert_hash[ STATUS_KEY ],
+      :msg_type    => alert_hash[ MSG_TYPE_KEY ],
+      :source      => alert_hash[ SOURCE_KEY ],
+      :scope       => alert_hash[ SCOPE_KEY ],
+      :restriction => alert_hash[ RESTRICTION_KEY ],
+      :addresses   => alert_hash[ ADDRESSES_KEY ],
+      :code        => alert_hash[ CODE_KEY ],
+      :note        => alert_hash[ NOTE_KEY ],
+      :references  => alert_hash[ REFERENCES_KEY ],
+      :incidents   => alert_hash[ INCIDENTS_KEY ]
+      # :infos       => Array( alert_hash[ INFOS_KEY ]).map{ |info_hash| RCAP::Info.from_h( info_hash )}
+    )
+  end
+
+  # Returns a JSON string representation of an Alert object
+  def to_json
+    self.to_h.to_json
+  end
+
+  # Initiialises an Alert object from a JSON string produced by Alert#to_json
+  def self.from_json( json_string )
+    self.from_h( JSON.parse( json_string ))
+  end
+
+  private
+
+  def set_identifier
+    self.identifier = UUIDTools::UUID.random_create.to_s if identifier.blank?
+  end
+
+  def set_sent_at
+    self.sent_at = Time.now if sent_at.blank?
+  end
+end