vatsim_online 0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.2

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in vatsim_online.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,5 @@
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Svilen Vassilev
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,202 @@
+# Vatsim Online
+
+A Ruby gem for selectively pulling, parsing and displaying Vatsim online
+stations data. Essentially it's a "Who's online" library, capable of displaying
+online ATC and/or pilots for given airports, areas or globally. Stations are
+returned as objects, exposing a rich set of attributes. Vatsim data is pulled
+on preset intervals and cached locally to avoid flooding the servers.
+
+### Badges of (dis)honour
+
+* Testing (Travis CI): [![Build Status](https://secure.travis-ci.org/tarakanbg/vatsim_online.png?branch=master)](http://travis-ci.org/tarakanbg/vatsim_online)
+* Code Analysis (CodeClimate): [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/tarakanbg/vatsim_online)
+* Dependencies: (Gemnasium) [![Gemnasium](https://gemnasium.com/tarakanbg/vatsim_online.png?travis)](https://gemnasium.com/tarakanbg/vatsim_online)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'vatsim_online'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install vatsim_online
+
+## Usage
+
+This gem provides one public method: `vatsim_online`, which can be applied to
+any string (or variable containing a string) representing a full or partial ICAO
+code. The provided ICAO code or fragment will be used as a search criteria and
+matched against the current vatsim data.
+
+For example if you want to retrieve all active stations (ATC positions and pilots)
+for Vienna airport (ICAO: LOWW), then you can use:
+
+```ruby
+# Attaching the method directly to a string:
+"LOWW".vatsim_online
+
+# Attaching the method to a variable containing a string:
+icao = "LOWW"
+icao.vatsim_online
+```
+If you want to retrieve the currently active stations for an entire region
+(FIR/ARTCC), then you can use the first 2-3 letters of the region's ICAO name.
+For example if you want to pull all the stations active in Austria (ICAO code
+for the FIR is LOVV), you can use `"LO"` as your ICAO search string: all Austrian
+airports and ATC station callsigns start with `"LO"`:
+
+```ruby
+# Attaching the method directly to a string:
+"LO".vatsim_online
+
+# Attaching the method to a variable containing a string:
+icao = "LO"
+icao.vatsim_online
+```
+When parsing the pilot stations for particular airport or area, the library will
+return the pilots that are flying **to or from** the given area or airport,
+not the current enroute stations. The discovery algorithm is based on **origin
+and destination**.
+
+
+### Anatomy of method returns
+
+The `vatsim_online` method returns a **hash** of 2 elements: the matching atc
+stations and pilots stations. Each of those is an **array**, cosnsisting of
+station **objects**. Each of these objects includes a number of **attributes**:
+
+```ruby
+icao_vatsim_online # => {:atc => [a1, a2, a3 ...], :pilots => [p1, p2, p3 ...]}
+
+icao_vatsim_online[:atc] #=> [a1, a2, a3 ...]
+icao_vatsim_online[:pilots] #=> [p1, p2, p3 ...]
+
+icao_vatsim_online[:atc].first #=> a1
+icao_vatsim_online[:pilots].first #=> p1
+
+a1.callsign #=> "LQSA_TWR"
+a1.frequency #=> "118.25"
+a1.name #=> "Svilen Vassilev"
+...
+
+p1.callsign #=> "ACH217S"
+p1.departure #=> "LQSA"
+p1.destination #=> "LDSP"
+p1.remarks #=> "/V/ RMK/CHARTS"
+...
+```
+
+### Station attributes
+
+Here's a complete list of the station object attributes that can be accessed:
+
+* callsign
+* name
+* role
+* frequency
+* altitude
+* groundspeed
+* aircraft
+* departure
+* destination
+* rating
+* facility
+* remarks
+* route
+* atis
+* logon
+
+### Customizing the request
+
+The `vatsim online` method can be customized by passing in a hash-style collection
+of arguments. The currently supported arguments and their defaults are:
+
+* :atc => true (Possible values: true, false. Default value: true)
+* :pilots => true (Possible values: true, false. Default value: true)
+
+Both options can be used to exclude all ATC or pilots stations respectively from
+the request, in order to speed it up and avoid processing useless data.
+
+**Examples:**
+
+```ruby
+# Lets exclude all ATC from our request and get the pilots only
+"LO".vatsim_online(:atc => false)[:pilots] #=> [p1, p2, p3...]
+
+# Lets exclude all pilots from our request and get the ATC only
+"LO".vatsim_online(:pilots => false)[:atc] #=> [a1, a2, a3...]
+
+"LO".vatsim_online(:atc => false)[:pilots].first.callsign #=> "ACH0838"
+"LO".vatsim_online(:pilots => false)[:atc].first.callsign #=> "LOVV_CTR"
+
+```
+
+### Example of Ruby on Rails implementation
+
+Here's a possible scenario of using this gem in a Ruby on Rails application.
+Verbosity is kept on purpose for clarity.
+
+**In your controller:**
+```ruby
+def index
+  # We want to retrieve all Austrian online stations (ATC and pilots)
+  icao = "LO"
+  stations = icao.vatsim_online
+
+  # Now we will assign the ATCs and the pilots to separate instance variables,
+  # to be able to loop through them separately in the view
+  @atc = stations[:atc]
+  @pilots = stations[:pilots]
+end
+```
+
+**In your view (HAML is used for clarity):**
+
+```haml
+- for atc in @atc
+  %li
+    = atc.callsign
+    = atc.frequency
+    = atc.rating
+    = atc.name
+    = atc.atis
+
+- for pilot in @pilots
+  %li
+    = pilot.callsign
+    = atc.name
+    = atc.origin
+    = atc.destination
+    = atc.route
+    = atc.altitude
+    = atc.groundspeed
+    = atc.remarks
+```
+
+### Notes
+
+* Vatsim status and data files are cached locally to reduce the load on vatsim
+servers. Random server is chosen to retrieve the data each time. By default the
+status file is updated once every 4 hours and the data file once every 3 minutes
+regardless of the number of incoming requests.
+* The data is cached in your default TEMP directory (OS specific)
+* All the data retrieval and caching logic is encapsulated in a separate class
+`VatsimTools::DataDownloader` which can be mixed in other applications and
+libraries too.
+* The ICAO string used as a search criteria **is not** case sensitive
+* Pilot stations returned are based on origin and destination airports, the
+current algorithm does not evaluate enroute flights.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Make sure all tests are passing!
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/vatsim_online.rb

@@ -0,0 +1,16 @@
+%w{vatsim_online/version vatsim_online/station vatsim_online/data_downloader
+   vatsim_online/station_parser}.each { |lib| require lib }
+
+class String
+  def vatsim_online(args={})
+    VatsimOnline.vatsim_online(self, args)
+  end
+end
+
+module VatsimOnline
+
+  def self.vatsim_online(icao, args)
+    VatsimTools::StationParser.new(icao,args).sorted_station_objects
+  end
+
+end

data/lib/vatsim_online/data_downloader.rb

@@ -0,0 +1,58 @@
+module VatsimTools
+
+  class DataDownloader
+
+    %w{curb tempfile time_diff tmpdir csv}.each { |lib| require lib }
+
+    STATUS_URL = "http://status.vatsim.net/status.txt"
+    LOCAL_STATUS = "#{Dir.tmpdir}/vatsim_status.txt"
+    LOCAL_DATA = "#{Dir.tmpdir}/vatsim_data.txt"
+
+    def initialize
+      data_file
+    end
+
+    def create_status_tempfile
+      status = Tempfile.new('vatsim_status')
+      File.rename status.path, LOCAL_STATUS
+      File.open(LOCAL_STATUS, "w+") {|f| f.write(Curl::Easy.perform(STATUS_URL).body_str) }
+    end
+
+    def read_status_tempfile
+      status = File.open(LOCAL_STATUS)
+      difference = Time.diff(status.ctime, Time.now)[:hour]
+      difference > 3 ? create_status_tempfile : status.read
+    end
+
+    def status_file
+      File.exists?(LOCAL_STATUS) ? read_status_tempfile : create_status_tempfile
+      LOCAL_STATUS
+    end
+
+    def servers
+      urls = []
+      CSV.foreach(status_file, :col_sep =>'=') {|row| urls << row[1] if row[0] == "url0"}
+      urls
+    end
+
+    def create_local_data_file
+      data = Tempfile.new('vatsim_data', :encoding => 'iso-8859-15')
+      File.rename data.path, LOCAL_DATA
+      data = Curl::Easy.perform(servers.sample).body_str.gsub(/["]/, '\s').force_encoding('iso-8859-15')
+      File.open(LOCAL_DATA, "w+") {|f| f.write(data)}
+    end
+
+    def read_local_datafile
+      data = File.open(LOCAL_DATA)
+      difference = Time.diff(data.ctime, Time.now)[:minute]
+      difference > 2 ? create_local_data_file : data.read
+    end
+
+    def data_file
+      File.exists?(LOCAL_DATA) ? read_local_datafile : create_local_data_file
+      LOCAL_DATA
+    end
+
+  end
+
+end

data/lib/vatsim_online/station.rb

@@ -0,0 +1,27 @@
+module VatsimTools
+  class Station
+    attributes = %w{callsign name role frequency altitude groundspeed aircraft
+                 departure destination rating facility remarks route atis logon}
+    attributes.each {|attribute| attr_accessor attribute.to_sym }
+
+
+    def initialize(station)
+      @callsign = station[0]
+      @name = station[2]
+      @role = station[3]
+      @frequency = station[4]
+      @altitude = station[7]
+      @groundspeed = station[8]
+      @aircraft = station[9]
+      @departure = station[11]
+      @destination = station[13]
+      @rating = station[16]
+      @facility = station[18]
+      @remarks = station[29]
+      @route = station[30]
+      @atis = station[35]
+      @logon = station[37]
+    end
+
+  end
+end

data/lib/vatsim_online/station_parser.rb

@@ -0,0 +1,51 @@
+module VatsimTools
+
+  class StationParser
+
+    %w{tmpdir csv}.each { |lib| require lib }
+    require_relative "data_downloader"
+    require_relative "station"
+
+    attr_accessor :role
+    attr_accessor :icao
+
+    LOCAL_DATA = "#{Dir.tmpdir}/vatsim_data.txt"
+
+    def initialize(icao, args = nil)
+      VatsimTools::DataDownloader.new
+      args.class == Hash ? @role = determine_role(args) : @role = "all"
+      @icao = icao.upcase
+    end
+
+    def determine_role(args)
+      args[:atc] == false ? role = "pilot" : role = "all"
+      args[:pilots] == false ? role = "atc" : role = role
+      role = "all" if args[:pilots] == false && args[:atc] == false
+      role
+    end
+
+    def stations
+      stations = []
+      CSV.foreach(LOCAL_DATA, :col_sep =>':', encoding: "iso-8859-15") do |row|
+        callsign, origin, destination, client = row[0].to_s, row[11].to_s, row[13].to_s, row[3].to_s
+        stations << row if (callsign[0...@icao.length] == @icao && client == "ATC") unless @role == "pilot"
+        stations << row if (origin[0...@icao.length] == @icao || destination[0...@icao.length] == @icao) unless @role == "atc"
+      end
+      stations
+    end
+
+    def station_objects
+      station_objects= []
+      stations.each {|station| station_objects << VatsimTools::Station.new(station) }
+      station_objects
+    end
+
+    def sorted_station_objects
+      atc = []; pilots = []
+      station_objects.each {|sobj| sobj.role == "ATC" ? atc << sobj : pilots << sobj}
+      {:atc => atc, :pilots => pilots}
+    end
+
+  end
+
+end

data/lib/vatsim_online/version.rb

@@ -0,0 +1,3 @@
+module VatsimOnline
+  VERSION = "0.1"
+end

data/spec/data_downloader_spec.rb

@@ -0,0 +1,91 @@
+require 'spec_helper.rb'
+require 'data_downloader_spec_helper.rb'
+
+describe VatsimTools::DataDownloader do
+
+  target = VatsimTools::DataDownloader
+  LOCAL_STATUS = "#{Dir.tmpdir}/vatsim_status.txt"
+  LOCAL_DATA = "#{Dir.tmpdir}/vatsim_data.txt"
+
+  describe "create_status_tempfile" do
+    it "should create a file" do
+      delete_local_files
+      File.exists?(LOCAL_STATUS).should be false
+      target.new.create_status_tempfile
+      File.exists?(LOCAL_STATUS).should be true
+      File.open(LOCAL_STATUS).path.should eq("#{Dir.tmpdir}/vatsim_status.txt")
+      File.open(LOCAL_STATUS).size.should be > 100
+    end
+  end
+
+  describe "read_status_tempfile" do
+    it "should confirm a file exists" do
+      target.new.read_status_tempfile
+      File.exists?(LOCAL_STATUS).should be true
+      File.open(LOCAL_STATUS).size.should be > 100
+    end
+  end
+
+  describe "status_file" do
+    it "should return status.txt path" do
+      delete_local_files
+      File.exists?(LOCAL_STATUS).should be false
+      target.new.status_file.class.should eq(String)
+      target.new.status_file.should include("vatsim_status.txt")
+      target.new.status_file.should eq(LOCAL_STATUS)
+      target.new.status_file.should eq("#{Dir.tmpdir}/vatsim_status.txt")
+      File.exists?(LOCAL_STATUS).should be true
+    end
+  end
+
+  describe "servers" do
+    it "should contain an array of server URLs" do
+      File.exists?(LOCAL_STATUS).should be true
+      target.new.servers.class.should eq(Array)
+      target.new.servers.size.should eq(5)
+    end
+  end
+
+  describe "create_local_data_file" do
+    it "should confirm a file exists" do
+      target.new.create_local_data_file
+      File.exists?(LOCAL_DATA).should be true
+      File.open(LOCAL_DATA).path.should eq("#{Dir.tmpdir}/vatsim_data.txt")
+      File.open(LOCAL_DATA).size.should be > 100
+    end
+  end
+
+  describe "read_local_datafile" do
+    it "should confirm a file exists" do
+      target.new.read_local_datafile
+      File.exists?(LOCAL_DATA).should be true
+      File.open(LOCAL_DATA).size.should be > 100
+    end
+  end
+
+  describe "data_file" do
+    it "should contain file path" do
+      delete_local_files
+      File.exists?(LOCAL_DATA).should be false
+      target.new.data_file.class.should eq(String)
+      target.new.data_file.should include("vatsim_data.txt")
+      target.new.data_file.should eq(LOCAL_DATA)
+      target.new.data_file.should eq("#{Dir.tmpdir}/vatsim_data.txt")
+      File.exists?(LOCAL_DATA).should be true
+    end
+  end
+
+  describe "new" do
+    it "should return" do
+      delete_local_files
+      File.exists?(LOCAL_DATA).should be false
+      File.exists?(LOCAL_STATUS).should be false
+      target.new
+      File.exists?(LOCAL_DATA).should be true
+      File.exists?(LOCAL_STATUS).should be true
+      File.open(LOCAL_DATA).size.should be > 100
+      File.open(LOCAL_STATUS).size.should be > 100
+    end
+  end
+
+end