README.rdoc in rcap-0.3 vs README.rdoc in rcap-0.4
- old
+ new
@@ -6,35 +6,36 @@
RCAP currently supports only CAP Version 1.1.
== Version
-0.3
+0.4
== Dependencies
RCAP depends on the following gems
* {Assistance}[http://assistance.rubyforge.org]
* {UUIDTools}[http://uuidtools.rubyforge.org]
+* {JSON}[http://json.rubyforge.org]
RCAP uses the REXML API, included in Ruby, to parse and generate XML.
== Installation
RCAP 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 can be installed from the command line
-
+
gem install rcap
The gem is also available for download and manual installtion at http://www.aimred.com/gems .
== 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 http:///www.aimred.com/git/rcap.git
-
+* 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'
@@ -134,10 +135,36 @@
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
@@ -150,31 +177,38 @@
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 info.valid?
- puts info.errors.full_messages
+ puts "Is info valid: #{ info.valid? }"
+ info.errors.full_messages.each{ |message| puts "Error: #{ message }" }
+
Will produce the folling output:
- false
- severity is not present
- certainty can only be assigned the following values: Observed, Likely, Possible, Unlikely, Unknown
+ 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 150 tests.
+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.