ruby-ise 0.4.0 → 0.6.1

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - jruby-18mode # JRuby in 1.8 mode
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-18mode
+  - rbx-19mode
+  - 1.8.7

data/Gemfile

@@ -2,3 +2,15 @@
 source "https://rubygems.org"
 gem "inifile"
 gem "nokogiri"
+gem "rake"
+gem "highline"
+gem "smart_colored"
+
+group :development do
+  gem "pry"
+  gem "pry-debundle"
+end
+
+group :test do
+  gem "rspec"
+end

data/Rakefile

@@ -1 +1,25 @@
 require "bundler/gem_tasks"
+
+task :default => :test_all
+
+task :test_all do
+  sh "rspec -Ilib"
+end
+
+desc 'Builds the ruby-ise gem.'
+task :build do
+  sh "gem build ruby-ise.gemspec"
+end
+
+desc 'Builds and installs the ruby-ise gem.'
+task :install => :build do
+  sh "gem install pkg/ruby-ise-#{ISE::VERSION}.gem"
+end
+
+desc 'Tags the current version, pushes it GitHub, and pushes the gem.'
+task :release => :build do
+  sh "git tag v#{ISE::VERSION}"
+  sh "git push origin master"
+  sh "git push origin v#{ISE::VERSION}"
+  sh "git push pkg.ruby-ise-#{ISE::VERSION}.gem"
+end

data/bin/xoptimize

@@ -22,8 +22,12 @@ rescue
 end
 
 puts
-puts "You're about to move the working directory for #{project.filename.bold} to RAM.".yellow
-puts "This will dramatically speed up synthesis and save disk space, but you'll need to re-run 'Generate Programming Files' after each reboot."
+puts "You're about to move the working directory for" 
+puts  project.filename.bold.yellow
+puts  " to RAM.".yellow
+puts
+puts "This will dramatically speed up synthesis and save disk space," 
+puts "but you'll need to re-run 'Generate Programming Files' after each reboot."
 puts
 exit unless prompt.agree('Do you want to continue? [y/n]'.bold + " ") 
 

data/lib/ise/{preference_set.rb → preference_file.rb}

@@ -11,6 +11,7 @@ module ISE
 
     #
     # Determines the location of the ISE preferences file.
+    # TODO: Generalize to work on Windows?
     #
     def self.ise_preference_file_path
       "~/.config/Xilinx/ISE.conf"
@@ -49,7 +50,7 @@ module ISE
 
       #Traverse the path, creating any "folders" necessary along the way.
       until keys.one?
-        target[keys.first] = {} unless target[keys.first].respond_to?(:[])
+        target[keys.first] = {} unless target[keys.first].is_a?(Hash)
         target = target[keys.shift]
       end
      

data/lib/ise/project.rb

@@ -6,8 +6,8 @@ require 'tmpdir'
 
 module ISE
 
-  class Project 
-
+  class Project < XMLFile
+    
     GoalProperty = 'Last Applied Goal'
     ShortNameProperty = 'PROP_DesignName'
     OutputNameProperty = 'Output File Name'
@@ -16,31 +16,6 @@ module ISE
 
     attr_reader :filename
 
-
-    #
-    # Creates a new ISE Project from an XML string or file object. 
-    #
-    def initialize(xml, filename)
-      @xml = Nokogiri.XML(xml)
-      @filename = filename
-      @base_path = File.dirname(filename)
-    end
-
-
-    #
-    # Factory method which creates a new Project from a project file.
-    #
-    def self.load(file_path)
-      new(File::read(file_path), file_path)
-    end
-
-    #
-    # Writes the project to disk, saving any changes.
-    #
-    def save(file_path=@filename)
-      File::write(file_path, @xml)
-    end
-  
     #
     # Returns the value of a project property.
     #

data/lib/ise/project_navigator.rb

@@ -11,13 +11,20 @@ module ISE
 
     RecentProjectsPath = 'Project Navigator/Recent Project List1'
 
+    #
+    # Sets the path of the preference file to look for.
+    #
+    def set_preference_file(preference_file=nil)
+      @preference_file = preference_file
+    end
+
     #
     # Loads preferences.
     # By default, preferences are only loaded once.
     #
     def load_preferences(force_reload=false)
       @preferences = nil if force_reload
-      @preferences ||= PreferenceFile.load
+      @preferences ||= PreferenceFile.load(@preference_file)
     end
 
     #
@@ -25,14 +32,14 @@ module ISE
     #
     def version
       load_preferences
-      @preferences.sections.first
+      @preferences.sections.last
     end
 
     #
     # 
     #
     def preferences
-      load_preferences
+      load_preferencers
       return @preferences[version]
     end
 
@@ -49,6 +56,9 @@ module ISE
     # that project will be used. This function re-loads the preferences file upon each call,
     # to ensure we don't have stale data.
     #
+    # TODO: When more than one ISE version is loaded, parse _all_ of the recent projects,
+    # and then return the project with the latest timestamp.
+    #
     def most_recent_project_path
 
       #Re-load the preference file, so we have the most recent project.
@@ -66,7 +76,8 @@ module ISE
     # Returns a project object representing the most recently open project.
     #
     def most_recent_project
-      Project.load(most_recent_project_path)
+      path = most_recent_project_path
+      path ? Project.load(path) : nil
     end
 
   end

data/lib/ise/symbol.rb

@@ -0,0 +1,235 @@
+
+require 'ise'
+require 'nokogiri'
+require 'enumerator'
+
+module ISE
+
+  #
+  # Class representing an ISE symbol file.
+  #
+  class Symbol < XMLFile
+
+    PIN_NAME_REGEX = /^([A-Za-z0-9_]+)(\(([0-9]+)\:([0-9]+)\))?$/
+
+    #
+    # Get the name of the given schematic symbol;
+    # this also indicates which component this symbol is meant to wrap.
+    #
+    def name
+      @xml.css('symbol').attribute('name').value
+    end
+
+    #
+    # Sets the name of the given schematic symbol;
+    # adjusting the name of the 
+    #
+    def name=(new_name)
+      @xml.css('symbol').attribute('name').value = new_name
+    end
+
+    #
+    # Special constructor used for creating deep copies of
+    # this object. We use this to clone the inner XML AST.
+    #
+    def initialize_copy(source)
+      super
+      @xml = @xml.clone
+    end
+
+    #
+    # Returns a true-like value if the symbol has the given attribute.
+    #
+    def has_attribute?(name)
+      attribute_value_object(name)
+    end
+    alias_method :include?, :has_attribute?
+
+    #
+    # Gets the value of the provided Symbol attribute. 
+    #
+    def get_attribute(name)
+      attribute_value_object(name).value
+    end
+
+    #
+    # Sets the value of the provided Symbol attribute.
+    #
+    def set_attribute(name, new_value)
+      attribute_value_object(name).value = new_value.to_s
+    end
+    
+    #Allow the indexing operator to be used to access attributes.
+    alias_method :[], :get_attribute
+    alias_method :[]=, :set_attribute
+
+    #
+    # Returns an array of I/O pins present on the given symbol.
+    # 
+    def pins
+      @xml.css("symbol pin")
+    end
+
+    #
+    # Iterates over each attribute present in the given symbol.
+    #
+    def each_attribute
+      
+      #If we weren't passed a block, return an enumerator referencing this function.
+      return enum_for(:each_attribute) unless block_given?
+
+      #Yield each of the known attributes in turn.
+      @xml.css("symbol attr").each do |attr|
+        yield attr.attribute('name').value, attr.attribute('value').value
+      end
+
+    end
+
+    #
+    # Iterates over all of the I/O pins in the given design.
+    #
+    def each_pin(&block)
+
+      #If no block was provided, return an enumerator.
+      return pins.to_enum unless block
+
+      #Otherwise, iterate over the pins.
+      pins.each(&block)
+
+    end
+
+
+    #
+    # Iterates over all of the I/O pins in the given design, providing their names
+    # as well as their node objects.
+    #
+    def each_pin_with_name
+
+      #If we weren't passed a block, return an enumerator referencing this function.
+      return enum_for(:each_pin_with_name) unless block_given?
+
+      #Otherwise, yield each pin with its name.
+      each_pin do |pin|
+        yield pin, get_pin_name(pin)
+      end
+
+    end
+
+    #
+    # Renames each of the pins in the design according to a rule.
+    #
+    # Requires a block, which should accept a pin name and provide the
+    # pin's new name.
+    #
+    def rename_pins!
+      pins.each { set_pin_name(yield get_pin_name(pin)) }
+    end
+    
+    #
+    # Returns the name of a given pin, given its node.
+    #
+    def get_pin_name(node)
+      node.attribute("name").value
+    end
+
+    #
+    # Sets name of the pin represented by the given node, updating all values 
+    #
+    def set_pin_name(node, name)
+
+      return unless node.name == "pin"
+
+      #Change the name of any pin-label "text attributes" that reference the given pin.
+      original_name = get_pin_name(node)
+
+      #Retrieve a collection of all attributes that match the pin's original name...
+      pin_labels = @xml.css("symbol graph attrtext[attrname=\"PinName\"][type=\"pin #{original_name}\"]")
+
+      #And modify them so they now match the new node's name.
+      pin_labels.each { |pin| pin.attribute('type').value = "pin #{name}" }
+
+      #Finally, set the name of the node itself.
+      node.attribute("name").value = name
+      
+    end
+
+    #
+    # Adjusts the "bounds" of the given bus-- its maximum and minimum pin numbers-- in-place.
+    #
+    # node: The node whose value should be adjusted.
+    # left: The left bound. This is typically higher than the right bound, but doesn't have to be.
+    # right: The right bound. 
+    #
+    def set_pin_bounds!(node, left, right)
+   
+      #Extract the base name of the pin, removing any existing bounds.
+      name, _, _ =  parse_pin_name(get_pin_name(node))
+
+      #And adjust the pin's name to feature the new bounds.
+      set_pin_name(node, "#{name}(#{left}:#{right})")
+    
+    end
+
+    #
+    # Adjusts the "bounds" of the given bus so the bus is of the provided width
+    # by modifying the bus's upper bound. If the node is not a bus, it will be
+    # made into a bus whose right bound is 0.
+    #
+    # node: The node to be modified.
+    # width: The width to apply.
+    #
+    def set_pin_width!(node, width)
+
+      #Get the components of the given bus' name.
+      _, left, right = parse_pin_name(get_pin_name(node))
+
+      #If the pin wasn't initially a bus, make it one.
+      left  ||= 0
+      right ||= 0
+
+      #If our right bound is greater than our left one, adjust it.
+      if right > left
+        right = left + width - 1
+      #Otherwise, adjust the left width.
+      else
+        left = right + width - 1
+      end
+
+      #Set the pin's bounds.
+      set_pin_bounds!(node, left, right)
+
+    end
+
+    private
+
+    #
+    # Break a schematic-format pin name into three elements, and return them.
+    # Returns a list including: 1) the base name, 2) the range's left bound, and 3) the range's right bound.
+    #
+    def parse_pin_name(name)
+      components = PIN_NAME_REGEX.match(name)
+      return components[1], components[3].to_i, components[4].to_i
+    end
+
+
+    #
+    # Returns a reference to the XML attribute that corresponds to the _value_
+    # of an ISE _symbol_ attribute. (If that's not a confusing clash of nomenclature, what is?)
+    #
+    def attribute_value_object(name)
+  
+      #Ensure we have a string- this allows us to use symbols as attribute names, as well.
+      #This is more idiomatic.
+      name = name.to_s
+
+      #Get the node that corresponds to the given attribute, if it exists.
+      node = @xml.at_css("symbol attr[name=\"#{name}\"]")
+
+      #If the node exists, return its value; otherwise, return nil.
+      return node ? node.attribute('value') : nil
+
+    end
+
+  end
+
+end

data/lib/ise/version.rb

@@ -1,5 +1,3 @@
-module Ruby
-  module Ise
-    VERSION = "0.4.0"
-  end
+module ISE
+  VERSION = "0.6.1"
 end

data/lib/ise/xml_file.rb

@@ -0,0 +1,38 @@
+
+require 'nokogiri'
+
+module ISE
+
+  #
+  # Module which implements the functionality used to wrap an ISE XML file.
+  #
+  class XMLFile
+
+    attr_accessor :filename 
+
+    #
+    # Creates a new ISE Project from an XML string or file object. 
+    #
+    def initialize(xml, filename)
+      @xml = Nokogiri.XML(xml)
+      @filename = filename
+      @base_path = File.dirname(filename)
+    end
+
+    #
+    # Factory method which creates a new instance from an XML file.
+    #
+    def self.load(file_path)
+      new(File::read(file_path), file_path)
+    end
+
+    #
+    # Writes the project to disk, saving any changes.
+    #
+    def save(file_path=@filename)
+      File::write(file_path, @xml)
+    end
+    
+  end
+
+end

data/lib/ise.rb

@@ -1,5 +1,8 @@
 
+require 'ise/xml_file'
+
 require 'ise/project_navigator'
-require 'ise/preference_set'
+require 'ise/preference_file'
 require 'ise/project'
+require 'ise/symbol'
 

data/ruby-ise.gemspec

@@ -6,11 +6,11 @@ require 'ise/version'
 
 Gem::Specification.new do |gem|
   gem.name          = "ruby-ise"
-  gem.version       = Ruby::Ise::VERSION
+  gem.version       = ISE::VERSION
   gem.authors       = ["Kyle J. Temkin"]
   gem.email         = ["ktemkin@binghamton.edu"]
-  gem.description   = %q{Simple gem which extracts meta-data from Xilinx ISE files. Intended to simplify using Rake with ruby-adept, and with ISE/XST.}
-  gem.summary       = %q{Simple gem which extracts metadata from Xilinx ISE files.}
+  gem.description   = %q{Simple gem which extracts and modifies meta-data from Xilinx ISE files. Intended to simplify using Rake with ruby-adept, and with ISE/XST.}
+  gem.summary       = %q{Simple gem which extracts and modifies metadata from Xilinx ISE files.}
   gem.homepage      = "http://www.github.com/ktemkin/ruby-ise"
 
   gem.files         = `git ls-files`.split($/)

data/spec/ise/project_navigator_spec.rb

@@ -0,0 +1,20 @@
+
+require 'ise'
+
+describe ISE::ProjectNavigator do
+
+  describe "#most_recent_project_path" do
+
+    subject { ISE::ProjectNavigator }
+   
+    #Adjust the preference file location so it points to the test-data preference file.
+    let(:preference_file) { File.expand_path('../test_data/ISE.conf', __FILE__) }
+    before(:each) { ISE::ProjectNavigator.set_preference_file(preference_file) }
+
+    it "should return the path of the most recently edited ISE project file" do
+      subject.most_recent_project_path.should == "/home/ktemkin/Documents/Projects/ISESymbolLibrary/MSI_Components/MSI_Components.xise" 
+    end
+
+  end
+
+end

data/spec/ise/project_spec.rb

@@ -4,7 +4,7 @@ require 'ise'
 describe ISE::Project do
  
   #Operate on the same file provided.
-  subject { ISE::Project.load(File.expand_path('../project.xise', __FILE__)) }
+  subject { ISE::Project.load(File.expand_path('../test_data/project.xise', __FILE__)) }
 
 
   describe ".get_property" do
@@ -22,7 +22,7 @@ describe ISE::Project do
   describe ".top_level_file" do
 
     let(:relative_path) { './toplevel.vhd' }
-    let(:full_path) { File.expand_path(relative_path, "#{__FILE__}/..") } 
+    let(:full_path) { File.expand_path(relative_path, "#{__FILE__}/../test_data") } 
 
     context "when absolute_path is false" do
       it "should return a relative path to top-level file, as it appears in the project file" do
@@ -43,7 +43,7 @@ describe ISE::Project do
   #
   describe ".bit_file" do
 
-    let(:full_path) { File.expand_path('toplevel.bit', "#{__FILE__}/..") } 
+    let(:full_path) { File.expand_path('toplevel.bit', "#{__FILE__}/../test_data") } 
 
     it "should return the absolute path to the top-level bit file, if it exists" do
       subject.bit_file.should == full_path

data/spec/ise/symbol_spec.rb

@@ -0,0 +1,132 @@
+require 'ise'
+
+describe ISE::Symbol do
+ 
+  #Operate on the sample symbol file.
+  subject { ISE::Symbol.load(File.expand_path('../test_data/symbol.sym', __FILE__)) }
+
+  #Provide an example node for some tests to operate on.
+  let(:node) { subject.pins.first }
+
+  #Get a reference to the Symbol's internal XML.
+  let(:xml) { subject.instance_variable_get(:@xml) }
+
+  def pin_should_exist(name)
+    xml.at_css("symbol graph attrtext[type=\"pin #{name}\"]").should_not be_nil, "Pin #{name} should exist, but does not."
+  end
+
+  describe ".name" do
+    it "should return the symbol's name" do
+      subject.name.should == "BusMux16"
+    end
+  end
+
+  describe ".name=" do
+    it "should set the symbol's name" do
+      subject.name = "NewName"
+      subject.name.should == "NewName"
+    end
+  end
+
+  describe ".has_attribute?" do
+    context "when provided with an existing attribute" do
+      it"should return true" do
+        subject.has_attribute?(:BusWidth).should be_true
+      end
+    end
+    
+    context "when provided with an attribute that does not exist" do
+      it "should return false" do
+        subject.has_attribute?(:SomethingElse).should be_false
+      end
+    end
+  end
+
+  describe ".get_attribute" do
+    it "should return the value of the provided attribute" do
+      subject.get_attribute(:BusWidth).should == '8'
+    end
+  end
+
+  describe ".set_attribute" do
+    it "should set the value of the provided attribute" do
+      subject.set_attribute(:BusWidth, 3)
+      subject.get_attribute(:BusWidth).should == '3'
+    end
+  end
+
+  describe ".each_attribute" do
+    #TODO: better test that doesn't require enumerator funcitonality?
+    it "should iterate over each of the attributes in the file" do
+      subject.each_attribute.to_a.should == [['BusWidth', '8']]
+    end
+  end
+
+  describe ".pins" do 
+    it "should return a list of each pin in the design" do
+      #Generate a list of expected pin names.
+      expected_names = (0..15).map { |n| "i#{n}(7:0)" }
+      expected_names |= ['sel(3:0)', 'o(7:0)'] 
+
+      #Get a list of pin names in the design.
+      pin_names = subject.pins.collect { |p| p.attribute("name").value }
+      pin_names.should == expected_names
+    end
+  end
+
+  describe ".rename_pin" do
+    it "should change the name of the provided pin" do
+      subject.set_pin_name(node, 'a(1:0)') 
+      node.attribute('name').value.should == 'a(1:0)'
+    end
+
+    it "should change the name of any pin labels referencing the pin" do
+      subject.set_pin_name(node, 'a(1:0)') 
+      pin_should_exist('a(1:0)')
+    end
+  end
+
+  describe ".set_pin_bounds!" do
+
+    it "should change the boundaries of the given pin to match its arguments" do
+      subject.set_pin_bounds!(node, 14, 3)
+      pin_should_exist('i0(14:3)')
+    end
+
+  end
+
+  describe ".set_pin_width!" do
+
+    context "when provided with an MSB-to-the-left range" do
+      it "should move the upper (left) bound to create the correct width" do
+        subject.set_pin_width!(node, 4)
+        pin_should_exist('i0(3:0)')
+      end
+    end
+
+    context "when provided with an LSB-to-the-left range" do
+      it "should move the upper (right) bound to create the correct width" do
+        
+        #Create an LSB-to-the-left range.
+        subject.set_pin_name(node, 'i0(0:7)')
+
+        subject.set_pin_width!(node, 4)
+        pin_should_exist('i0(0:3)')
+      end
+    end
+
+    context "when provided with a non-bus" do
+      it "should create a bus that is bounded at zero" do
+       
+        #Create a non-bus input.
+        subject.set_pin_name(node, 'i')
+
+        subject.set_pin_width!(node, 10)
+        pin_should_exist('i(9:0)')
+
+      end
+    end
+  end
+
+
+end