plotrb 0.0.1

data/lib/plotrb/data.rb

@@ -0,0 +1,232 @@
+module Plotrb
+
+  # The basic tabular data model used by Vega.
+  # See {https://github.com/trifacta/vega/wiki/Data}
+  class Data
+
+    include ::Plotrb::Base
+
+    # @!attributes name
+    #   @return [String] the name of the data set
+    # @!attributes format
+    #   @return [Format] the format of the data file
+    # @!attributes values
+    #   @return [Hash, Array, String] the actual data set
+    # @!attributes source
+    #   @return [String, Data] the name of another data set to use as source
+    # @!attributes url
+    #   @return [String] the url from which to load the data set
+    # @!attributes transform
+    #   @return [Array<Transform>] an array of transform definitions
+    add_attributes :name, :format, :values, :source, :url, :transform
+
+    def initialize(&block)
+      define_single_val_attributes(:name, :values, :source, :url)
+      define_multi_val_attribute(:transform)
+      self.singleton_class.class_eval {
+        alias_method :file, :url
+      }
+      self.instance_eval(&block) if block_given?
+      ::Plotrb::Kernel.data << self
+      self
+    end
+
+    def format(*args, &block)
+      case args.size
+        when 0
+          @format
+        when 1
+          @format = ::Plotrb::Data::Format.new(args[0].to_sym, &block)
+          self
+        else
+          raise ArgumentError, 'Invalid Data format'
+      end
+    end
+
+    def extra_fields
+      @extra_fields ||= [:data, :index]
+      if @transform
+        @extra_fields.concat(@transform.collect { |t| t.extra_fields }).
+            flatten!.uniq!
+      end
+      @extra_fields
+    end
+
+    def method_missing(method, *args, &block)
+      case method.to_s
+        # set format of the data
+        when /^as_(csv|tsv|json|topojson|treejson)$/
+          self.format($1.to_sym, &block)
+        else
+          super
+      end
+    end
+
+  private
+
+    def attribute_post_processing
+      process_name
+      process_values
+      process_source
+      process_url
+      process_transform
+    end
+
+    def process_name
+      if @name.nil? || @name.strip.empty?
+        raise ArgumentError, 'Name missing for Data object'
+      end
+      if ::Plotrb::Kernel.duplicate_data?(@name)
+        raise ArgumentError, 'Duplicate names for Data object'
+      end
+    end
+
+    def process_values
+      return unless @values
+      case @values
+        when String
+          begin
+            Yajl::Parser.parse(@values)
+          rescue Yajl::ParseError
+            raise ArgumentError, 'Invalid JSON values in Data'
+          end
+        when Array, Hash
+          # leave as it is
+        else
+          raise ArgumentError, 'Unsupported value type in Data'
+      end
+    end
+
+    def process_source
+      return unless @source
+      case source
+        when String
+          unless ::Plotrb::Kernel.find_data(@source)
+            raise ArgumentError, 'Source Data not found'
+          end
+        when ::Plotrb::Data
+          @source = @source.name
+        else
+          raise ArgumentError, 'Unknown Data source'
+      end
+    end
+
+    def process_url
+      return unless @url
+      begin
+        URI.parse(@url)
+      rescue URI::InvalidURIError
+        raise ArgumentError, 'Invalid URL for Data'
+      end
+    end
+
+    def process_transform
+      return unless @transform
+      if @transform.any? { |t| not t.is_a?(::Plotrb::Transform) }
+        raise ArgumentError, 'Invalid Data Transform'
+      end
+    end
+
+    class Format
+
+      include ::Plotrb::Base
+
+      add_attributes :type
+
+      def initialize(type, &block)
+        case type
+          when :json
+            add_attributes(:parse, :property)
+            define_single_val_attributes(:parse, :property)
+          when :csv, :tsv
+            add_attributes(:parse)
+            define_single_val_attribute(:parse)
+          when :topojson
+            add_attributes(:feature, :mesh)
+            define_single_val_attributes(:feature, :mesh)
+          when :treejson
+            add_attributes(:parse, :children)
+            define_single_val_attributes(:parse, :children)
+          else
+            raise ArgumentError, 'Invalid Data format'
+        end
+        @type = type
+        self.instance_eval(&block) if block_given?
+        self
+      end
+
+      def date(*field, &block)
+        @parse ||= {}
+        field.flatten.each { |f| @parse.merge!(f => :date) }
+        self.instance_eval(&block) if block_given?
+        self
+      end
+      alias_method :as_date, :date
+
+      def number(*field, &block)
+        @parse ||= {}
+        field.flatten.each { |f| @parse.merge!(f => :number) }
+        self.instance_eval(&block) if block_given?
+        self
+      end
+      alias_method :as_number, :number
+
+      def boolean(*field, &block)
+        @parse ||= {}
+        field.flatten.each { |f| @parse.merge!(f => :boolean) }
+        self.instance_eval(&block) if block_given?
+        self
+      end
+      alias_method :as_boolean, :boolean
+
+    private
+
+      def attribute_post_processing
+        process_parse
+        process_property
+        process_feature
+        process_mesh
+        process_children
+      end
+
+      def process_parse
+        return unless @parse
+        valid_type = %i(number boolean date)
+        unless @parse.is_a?(Hash) && (@parse.values - valid_type).empty?
+          raise ArgumentError, 'Invalid parse options for Data format'
+        end
+      end
+
+      def process_property
+        return unless @property
+        unless @property.is_a?(String)
+          raise ArgumentError, 'Invalid JSON property'
+        end
+      end
+
+      def process_feature
+        return unless @feature
+        unless @feature.is_a?(String)
+          raise ArgumentError, 'Invalid TopoJSON feature'
+        end
+      end
+
+      def process_mesh
+        return unless @mesh
+        unless @mesh.is_a?(String)
+          raise ArgumentError, 'Invalid TopoJSON mesh'
+        end
+      end
+
+      def process_children
+        return unless @children
+        unless @children.is_a?(String)
+          raise ArgumentError, 'Invalid TreeJSON children'
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/plotrb/kernel.rb

@@ -0,0 +1,136 @@
+module Plotrb
+
+  # Kernel module includes most of the shortcuts used in Plotrb
+  module Kernel
+
+    # a global space keeping track of all Data objects defined
+    def self.data
+      @data ||= []
+    end
+
+    # @return [Data] find Data object by name
+    def self.find_data(name)
+      @data.find { |d| d.name == name.to_s }
+    end
+
+    # @return [Boolean] if a Data object with same name already exists
+    def self.duplicate_data?(name)
+      @data.select { |d| d.name == name.to_s }.size > 1
+    end
+
+    # a global space keeping track of all Axis objects defined
+    def self.axes
+      @axes ||= []
+    end
+
+    # a global space keeping track of all Scale objects defined
+    def self.scales
+      @scales ||= []
+    end
+
+    # @return [Scale] find Scale object by name
+    def self.find_scale(name)
+      @scales.find { |s| s.name == name.to_s }
+    end
+
+    # @return [Boolean] if a Scale object with same name already exists
+    def self.duplicate_scale?(name)
+      @scales.select { |s| s.name == name.to_s }.size > 1
+    end
+
+    # a global space keeping track of all Mark objects defined
+    def self.marks
+      @marks ||= []
+    end
+
+    # @return [Mark] find Mark object by name
+    def self.find_mark(name)
+      @marks.find { |m| m.name == name.to_s }
+    end
+
+    # @return [Boolean] if a Mark object with same name already exists
+    def self.duplicate_mark?(name)
+      @marks.select { |m| m.name == name.to_s }.size > 1
+    end
+
+    # a global space keeping track of all Transform objects defined
+    def self.transforms
+      @transforms ||= []
+    end
+    
+    # a global space keeping track of all Transform objects defined
+	def self.legends
+	  @legends ||= []
+	end
+
+    # Initialize ::Plotrb::Visualization object
+
+    def visualization(&block)
+      ::Plotrb::Visualization.new(&block)
+    end
+
+    # Initialize ::Plotrb::Data objects
+
+    def pdata(&block)
+      ::Plotrb::Data.new(&block)
+    end
+    
+    def legend(&block)
+	  ::Plotrb::Legend.new(&block)
+    end
+
+    def method_missing(method, *args, &block)
+      case method.to_s
+        when /^(\w)_axis$/
+          # Initialize ::Plotrb::Axis objects
+          if ::Plotrb::Axis::TYPES.include?($1.to_sym)
+            cache_method($1, 'axis')
+            self.send(method)
+          else
+            super
+          end
+        when /^(\w+)_scale$/
+          # Initialize ::Plotrb::Scale objects
+          if ::Plotrb::Scale::TYPES.include?($1.to_sym)
+            cache_method($1, 'scale')
+            self.send(method)
+          else
+            super
+          end
+        when /^(\w+)_transform$/
+          # Initialize ::Plotrb::Transform objects
+          if ::Plotrb::Transform::TYPES.include?($1.to_sym)
+            cache_method($1, 'transform')
+            self.send(method)
+          else
+            super
+          end
+        when /^(\w+)_mark$/
+          # Initialize ::Plotrb::Mark objects
+          if ::Plotrb::Mark::TYPES.include?($1.to_sym)
+            cache_method($1, 'mark')
+            self.send(method)
+          else
+            super
+          end
+        else
+          super
+      end
+    end
+
+  protected
+
+    def cache_method(type, klass)
+      self.class.class_eval {
+        define_method("#{type}_#{klass}") do |&block|
+          # class names are constants
+          # create shortcut methods to initialize Plotrb objects
+          ::Kernel::const_get("::Plotrb::#{klass.capitalize}").
+              new(type.to_sym, &block)
+        end
+      }
+    end
+
+  end
+
+end

data/lib/plotrb/legends.rb

@@ -0,0 +1,168 @@
+module Plotrb
+	
+	# Legends visualize scales. Legends aid interpretation of scales with ranges
+	# such as colors, shapes and sizes.
+	# See {https://github.com/trifacta/vega/wiki/Legends}
+	class Legend
+		
+		include ::Plotrb::Base
+		
+	    # @!attribute size
+		#   @return [Symbol] the name of the scale that determines an item's size
+		# @!attribute shape
+		#   @return [Symbol] the name of the scale that determines an item's shape
+		# @!attribute fill
+		#   @return [Symbol] the name of the scale that determines an item's fill color
+		# @!attribute stroke
+		#   @return [Symbol] the name of the scale that determines an item's stroke color
+		# @!attribute orient
+		#   @return [Symbol] the orientation of the legend
+		# @!attribute title
+		#   @return [Symbol] the title for the legend
+		# @!attribute format
+		#   @return [String] an optional formatting pattern for legend labels
+		# @!attribute offset
+		#   @return [Integer] the offset of the legend
+		#  @!attribute values
+		#   @return [Array] explicitly set the visible legend values
+		# @!attributes properties
+		#   @return [MarkProperty] the property set definitions
+		LEGEND_PROPERTIES = [:size, :shape, :fill, :stroke, :orient, :title, 
+		:format, :offset, :values, :properties]
+		
+		add_attributes *LEGEND_PROPERTIES
+		
+		def initialize(&block)
+			define_single_val_attributes(:size, :shape, :fill, :stroke, :orient, 
+			:title, :format, :offset)			
+			define_multi_val_attributes(:values)
+			self.singleton_class.class_eval {
+				alias_method :name, :title
+				alias_method :offset_by, :offset
+			}
+			self.instance_eval(&block) if block_given?
+			::Plotrb::Kernel.legends << self
+			self
+		end
+		
+		def properties(element=nil, &block)
+			@properties ||= {}
+			return @properties unless element
+			@properties.merge!(
+				element.to_sym => ::Plotrb::Mark::MarkProperty.new(:text, &block)
+			)
+			self
+		end
+		
+		def method_missing(method, *args, &block)
+			case method.to_s
+				when /^at_(left|right)$/ # set orient of the legend
+					self.orient($1.to_sym, &block)
+				when /^with_(\d+)_name/ # set the title of the legend
+					self.title($1.to_s, &block)
+				else
+					super
+			end
+		end
+		
+	private
+	
+		def attribute_post_processing
+			process_orient
+			process_format
+			process_properties
+			process_size
+			process_shape
+			process_fill
+			process_stroke
+		end		
+		
+		def process_orient
+			return unless @orient
+			unless %i(left right).include?(@orient.to_sym)
+			raise ArgumentError, 'Invalid Axis orient'
+			end
+		end
+
+		def process_format
+			return unless @format
+			# D3's format specifier has general form:
+			# [​[fill]align][sign][symbol][0][width][,][.precision][type]
+			# the regex is taken from d3/src/format/format.js
+			re =
+			/(?:([^{])?([<>=^]))?([+\- ])?([$#])?(0)?(\d+)?(,)?(\.-?\d+)?([a-z%])?/i
+			@format = @format.to_s
+			if @format =~ re
+				if "#{$1}#{$2}#{$3}#{$4}#{$5}#{$6}#{$7}#{$8}#{$9}" != @format
+				  raise ArgumentError, 'Invalid format specifier'
+				end
+			end
+		end
+		
+		def process_size
+			return unless @size
+			case @size
+				when String
+					unless ::Plotrb::Kernel.find_scale(@size)
+					raise ArgumentError, 'Scale not found'
+					end
+				when ::Plotrb::Scale
+					@size = @size.name
+				else
+					raise ArgumentError, 'Unknown Scale'
+			end
+		end
+
+		def process_shape
+			return unless @shape
+			case @shape
+				when String
+					unless ::Plotrb::Kernel.find_scale(@shape)
+					raise ArgumentError, 'Scale not found'
+					end
+				when ::Plotrb::Scale
+					@shape = @shape.name
+				else
+					raise ArgumentError, 'Unknown Scale'
+			end
+		end
+		
+		def process_fill
+			return unless @fill
+			case @fill
+				when String
+					unless ::Plotrb::Kernel.find_scale(@fill)
+					raise ArgumentError, 'Scale not found'
+					end
+				when ::Plotrb::Scale
+					@fill = @fill.name
+				else
+					raise ArgumentError, 'Unknown Scale'
+			end
+		end
+		
+		def process_stroke
+			return unless @stroke
+			case @stroke
+				when String
+					unless ::Plotrb::Kernel.find_scale(@stroke)
+					raise ArgumentError, 'Scale not found'
+					end
+				when ::Plotrb::Scale
+					@stroke = @stroke.name
+				else
+					raise ArgumentError, 'Unknown Scale'
+			end
+		end		
+
+		
+		def process_properties
+			return unless @properties
+			valid_elements = %i(title labels symbols gradient legend)
+			unless (@properties.keys - valid_elements).empty?
+				raise ArgumentError, 'Invalid property element'
+			end
+		end
+	
+	end
+end