RubyGems - ipxact-ruby - Versions diffs - 0.11.1 - Mend

ipxact-ruby 0.11.1

Files changed (142) hide show

data/.autotest ADDED Viewed

@@ -0,0 +1,15 @@
+require 'autotest/growl'
+Autotest.add_hook(:initialize) {|at|
+  at.add_exception %r{^\.git}  # ignore Version Control System
+  at.add_exception %r{^./tmp}  # ignore temp files, lest autotest will run again, and again...
+  at.clear_mappings         # take out the default (test/test*rb)
+  at.add_mapping(%r{^.*\.rb$}) {|f, _|
+    Dir['spec/**/*.rb']
+  }
+  at.add_mapping(%r{^ipxact/.*\.rb$}) {|f, _|
+    Dir['spec/*.rb']
+  }
+  nil
+}

data/.gitignore ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ *.swp
2	+ cscope.files

data/README.html ADDED Viewed

@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC
+    "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN"
+    "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd">
+<html xml:lang='en' xmlns:svg='http://www.w3.org/2000/svg' xmlns='http://www.w3.org/1999/xhtml'>
+<head><meta content='application/xhtml+xml;charset=utf-8' http-equiv='Content-type' /><title>IPXACT-Ruby</title><link href='style.css' rel='stylesheet' type='text/css' />
+</head>
+<body>
+<h1 id='ipxactruby'>IPXACT-Ruby</h1>
+<p><strong>IPXACT-Ruby</strong> is a ruby library for extracting data from an <strong>IPXACT</strong> platform description. It was developed at <a href='http://tima-sls.imag.fr'>TIMA Laboratory</a>, France, for simplifying recurring platform parsing tasks. As such, this gem relies heavily on Aaron Patterson&#8217;s <a href='http://nokogiri.org'>Nokogiri gem</a> for parsing the XML data. This gem also provides methods for computing values that cannot be explicitly defined using the <strong>IPXACT</strong> format, such as component base addresses, relative to other components. Finally, please note that, in its current state, the <strong>IPXACT-Ruby</strong> gem does not handle all the aspects of the <strong>IPXACT</strong> format, but focuses on its <strong>Component</strong> and <strong>Design</strong> concepts .</p>
+<h2 id='history'>History</h2>
+<p>XXX Latest changes</p>
+<h2 id='ipxact_format'>IPXACT format</h2>
+<p><strong>IPXACT</strong> is an XML format for describing electronic components and their designs. First managed by the SPIRIT Consortium, the evolution of the format is now supervised by <a href='http://www.accelera.org'>Accelera</a>. Additionally, the <strong>IPXACT</strong> format is now an IEEE standard, under the reference <a href='http://standards.ieee.org/getieee/1685/index.html'>IEEE-1685</a>. Its full specification may be downloaded <a href='http://www.accellera.org/pressroom/2010/Get_1685_01Jun10.pdf'>here</a>.</p>
+<h2 id='basic_usage'>Basic Usage</h2>
+<p>An IPXACT platform is basically composed of two types of elements:</p>
+<ul>
+<li>
+<p>Component files, which describe the structure of an IPXACT component</p>
+<p>component_docs = IPXACT::load_components(COMPONENT_PATH) design_docs = IPXACT::load_designs(DESIGN_PATH)</p>
+</li>
+<li>
+<p>Design files</p>
+</li>
+</ul>
+<p>The whole platform will then be parsed by the IPXACT gem:</p>
+<pre><code>platform = IPXACT::Parser::PlatformData.parse_platform(&lt;platform_name&gt;, component_docs, design_docs)</code></pre>
+<p>Or if you&#8217;d rather specify the platform&#8217;s version that should be loaded:</p>
+<pre><code>platform = IPXACT::Parser::PlatformData.parse_platform([&lt;platform_name&gt;, &lt;platform_version&gt;], \
+                                                        component_docs, design_docs)</code></pre>
+<p>In most cases, when methods require identifying a component you may use either specification:</p>
+<ul>
+<li><code>&lt;component_name&gt;</code> will fetch the most recent component.</li>
+<li><code>[&lt;component_name, &lt;component_version&gt;]</code> wil get the component with the specified version, thus allowing different component versions to coexist in the same path.</li>
+</ul>
+<p>Additionally, the same approach may be used for setting parsing constraints, which are passed as a final argument (<code>Array</code>) to the <code>parse_platform</code> method.</p>
+<p>When builder the platform object, IPXACT will combine component and design descriptions, identify hierarchical components and parse subcomponents when possible. In fact, in platform should be considered as a component except for a basic method aliasing (the <code>subcomponents</code> and <code>subcomponents=</code> methods are respectively aliased to <code>components</code> and <code>components=</code>, for the sake of DSL legibility). Thus, a component is composed of:</p>
+<ul>
+<li><code>subcomponents</code></li>
+<li><code>ports</code></li>
+<li><code>interconnections</code>, which define how its subcomponents are connected with one another.</li>
+<li><code>hierconnections</code>, which correspond the components&#8217; connections between its ports and its subcomponents.</li>
+</ul>
+<p>For more information, please refer to the specs provided with the gem.</p>
+<h2 id='installation'>Installation</h2>
+<p>Standard gem install command:</p>
+<pre><code>gem install ipxact</code></pre>
+<h2 id='support'>Support</h2>
+<ul>
+<li>guillaume (dot) godetbar (at) gmail (dot) com</li>
+</ul>
+<h2 id='license'>License</h2>
+<p>Copyright (C) 2010 TIMA Laboratory</p>
+<p>This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.</p>
+<p>This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.</p>
+</body></html>

data/README.mdown ADDED Viewed

@@ -0,0 +1,91 @@
+CSS: style.css
+IPXACT-Ruby
+===========
+**IPXACT-Ruby** is a ruby library for extracting data from an **IPXACT** platform description. It was developed at [TIMA Laboratory](http://tima-sls.imag.fr), France, for simplifying recurring platform parsing tasks. As such, this gem relies heavily on Aaron Patterson's [Nokogiri gem](http://nokogiri.org) for parsing the XML data. This gem also provides methods for computing values that cannot be explicitly defined using the **IPXACT** format, such as component base addresses, relative to other components.
+Finally, please note that, in its current state, the **IPXACT-Ruby** gem does not handle all the aspects of the **IPXACT** format, but focuses on its **Component** and **Design** concepts .
+History
+-------
+XXX Latest changes
+IPXACT format
+-------------
+**IPXACT** is an XML format for describing electronic components and their designs. First managed by the SPIRIT Consortium, the evolution of the format is now supervised by [Accelera](http://www.accelera.org). Additionally, the **IPXACT** format is now an IEEE standard, under the reference [IEEE-1685](http://standards.ieee.org/getieee/1685/index.html). Its full specification may be downloaded [here](http://www.accellera.org/pressroom/2010/Get_1685_01Jun10.pdf).
+Basic Usage
+-----------
+An IPXACT platform is basically composed of two types of elements:
+* Component files, which describe the structure of an IPXACT component
+    component_docs = IPXACT::load_components(COMPONENT_PATH)
+    design_docs = IPXACT::load_designs(DESIGN_PATH)
+* Design files
+The whole platform will then be parsed by the IPXACT gem:
+    platform = IPXACT::Parser::PlatformData.parse_platform(<platform_name>, component_docs, design_docs)
+Or if you'd rather specify the platform's version that should be loaded:
+    platform = IPXACT::Parser::PlatformData.parse_platform([<platform_name>, <platform_version>], \
+                                                            component_docs, design_docs)
+In most cases, when methods require identifying a component you may use either specification:
+* `<component_name>` will fetch the most recent component.
+* `[<component_name, <component_version>]` wil get the component with the specified version, thus allowing different component versions to coexist in the same path.
+Additionally, the same approach may be used for setting parsing constraints, which are passed as a final argument (`Array`) to the `parse_platform` method.
+When builder the platform object, IPXACT will combine component and design
+descriptions, identify hierarchical components and parse subcomponents when
+possible. In fact, in platform should be considered as a component except for a
+basic method aliasing (the `subcomponents` and `subcomponents=` methods are
+respectively aliased to `components` and `components=`, for the sake of DSL
+legibility). Thus, a component is composed of:
+* `subcomponents`
+* `ports`
+* `interconnections`, which define how its subcomponents are connected with one another.
+* `hierconnections`, which correspond the components' connections between its ports and its subcomponents.
+For more information, please refer to the specs provided with the gem.
+Installation
+------------
+Standard gem install command:
+    gem install ipxact-ruby
+Support
+-------
+* guillaume (dot) godetbar (at) gmail (dot) com
+License
+-------
+Copyright (C) 2010 TIMA Laboratory
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.

data/Rakefile ADDED Viewed

@@ -0,0 +1,31 @@
+# Copyright (C) 2010 TIMA Laboratory
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "ipxact-ruby"
+    gemspec.summary = "Ruby library for parsing IPXACT specifications and extracting relevant information."
+    gemspec.email = "guillaume.godetbar@gmail.com "
+    gemspec.homepage = "http://tima-sls.imag.fr"
+    gemspec.authors = ["Guillaume Godet-Bar"]
+    gemspec.files = FileList["{spec,schemas,autotest}/**/*", "lib/ipxact.rb", "lib/ipxact/*", "lib/ipxact/parser/*", "lib/ipxact/pathfinder/graph_pathfinder.rb", ".autotest", ".gitignore", "Rakefile", "VERSION"]
+    gemspec.add_dependency 'nokogiri'
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/VERSION ADDED Viewed

	@@ -0,0 +1 @@
1	+ 0.11.1

data/autotest/discover.rb ADDED Viewed

@@ -0,0 +1,17 @@
+# Copyright (C) 2010 TIMA Laboratory
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+Autotest.add_discovery { "rspec2" }

data/lib/ipxact.rb ADDED Viewed

@@ -0,0 +1,263 @@
+# Copyright (C) 2010 TIMA Laboratory
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+require 'nokogiri'
+require 'set'
+# Root and commodity module for the IPXACT Ruby library. In particular, this
+# module should be used for loading the component design files.
+#
+# @example Default initialization process
+#   component_docs = IPXACT::load_components("my/component/path")
+#   design_docs = IPXACT::load_designs("my/design/path")
+#   platform = IPXACT::Parser::PlatformData::parse_platform("platform_id",
+#                                             component_docs, design_docs)
+# @author Guillaume Godet-Bar
+#
+module IPXACT
+  # Path to the +design.xsd+ file
+  DESIGN_SCHEMA_PATH = File.join File.dirname(__FILE__), '../schemas/design.xsd'
+  # Path to the +component.xsd+ file
+  COMPONENT_SCHEMA_PATH = File.join File.dirname(__FILE__), '../schemas/component.xsd'
+  # Returns whether the XML file is an IPXACT component (i.e., it is consistent
+  # with the +component.xsd+ schema.
+  #
+  # @param [String] file_path path to the file that should be tested
+  #
+  # @return [Boolean] whether the file is a valid IPXACT component
+  #
+  def self.is_valid_component?(path)
+    raise ArgumentError unless path.is_a? String
+    component_schema_file = File.open(COMPONENT_SCHEMA_PATH)
+    component_schema = Nokogiri::XML::Schema(component_schema_file)
+    component_schema_file.close
+    component_file = File.open(path)
+    component_doc = Nokogiri::XML(component_file)
+    component_file.close
+    component_schema.validate(component_doc).size == 0
+  end
+  # Returns whether the XML file is an IPXACT design (i.e., it is consistent
+  # with the +design.xsd+ schema).
+  #
+  # @param [String] file_path path to the file that should be tested
+  #
+  # @return [Boolean] whether the file is a valid IPXACT design
+  #
+  def self.is_valid_design?(path)
+    raise ArgumentError unless path.is_a? String
+    design_schema_file = File.open(DESIGN_SCHEMA_PATH)
+    design_schema = Nokogiri::XML::Schema design_schema_file
+    design_schema_file.close
+    design_file = File.open(path)
+    design_doc = Nokogiri::XML(design_file)
+    design_file.close
+    design_schema.validate(design_doc).size == 0
+  end
+  # Returns the component's identifier (i.e., name, library, vendor, version).
+  #
+  # @param [String] path The path to the component's XML file
+  #
+  # @return [Hash] The component's identifier or nil if the path is invalid
+  #
+  def self.identifier(path)
+    if is_valid_design?(path) || is_valid_component?(path)
+      ipxact_file = File.open(path)
+      ipxact_doc = Nokogiri::XML(ipxact_file)
+      ipxact_file.close
+      {
+        :name     => ipxact_doc.xpath("./*/spirit:name").first.text,
+        :vendor   => ipxact_doc.xpath("./*/spirit:vendor").first.text,
+        :library  => ipxact_doc.xpath("./*/spirit:library").first.text,
+        :version  => ipxact_doc.xpath("./*/spirit:version").first.text
+      }
+    else
+      nil
+    end
+  end
+  # Loads the components from an IPXACT XML specification.
+  #
+  # @param [String] components_path path to the components of the target
+  #                                 platform. All subdirectories will be
+  #                                 scanned and all valid files (i.e., from an
+  #                                 XML and +component.xsd+ schema point of
+  #                                 view) are loaded into the resulting
+  #                                 structure.
+  #
+  # @return [Hash] a Hash that associates the name and version of the component
+  #   with the IPXACT XML (Nokogiri) structure of the component. No
+  #   post-processing is made on this structure, which should not be used for
+  #   any serious work (i.e.,its values may be modified when instantiating any
+  #   design file linked to the components).
+  # @raise a generic exception if no component could be found.
+  #
+  def self.load_components(components_path)
+    component_schema_file = File.open(COMPONENT_SCHEMA_PATH)
+    component_schema = Nokogiri::XML::Schema(component_schema_file)
+    component_schema_file.close
+    xml_files = Dir.glob(File.join(components_path, "**", "*.xml"))
+    component_docs = xml_files.inject({}) do |acc, file|
+      component_file = File.open(file)
+      component_doc = Nokogiri::XML(component_file)
+      component_file.close
+      version_tag = component_doc.xpath("/spirit:component/spirit:version")
+      version = version_tag.first.nil? ? "0" : version_tag.first.text
+      name_tag = component_doc.xpath("/spirit:component/spirit:name")
+      name = name_tag.first.nil? ? nil : name_tag.first.text
+      unless name.nil?
+        key = [component_doc.xpath("/spirit:component/spirit:name").first.text, version]
+        acc[key] = component_doc  \
+          if component_schema.validate(component_doc).size == 0
+      end
+      acc
+    end
+    raise 'No valid component was found!' if component_docs.keys.empty?
+    component_docs
+  end
+  # Loads the designs from an IPXACT XML specification.
+  #
+  # @param [String] designs_path  a path to the design instances of the target
+  #                 platform. All subdirectories will be scanned and all valid
+  #                 files (i.e., from an XML and design.xsd schema point of
+  #                 view) are loaded into the resulting structure.
+  #
+  # @return [Hash] a Hash that associates the name and version of the design
+  # with the IPXACT XML (Nokogiri) structure of the design. Should not be used,
+  # as this is 'raw' IPXACT data.
+  #
+  # @raise a generic exception if no design document could be found.
+  #
+  def self.load_designs(designs_path)
+    design_schema_file = File.open(DESIGN_SCHEMA_PATH)
+    design_schema = Nokogiri::XML::Schema design_schema_file
+    design_schema_file.close
+    xml_files = Dir.glob(File.join(designs_path, "**", "*.xml"))
+    design_docs = xml_files.inject({}) do |acc, xml_file|
+      design_file = File.open(xml_file)
+      design_doc = Nokogiri::XML(design_file)
+      design_file.close
+      if design_schema.validate(design_doc).size == 0
+        design_name = design_doc.xpath("./spirit:design/spirit:name").text
+        design_version = design_doc.xpath("./spirit:design/spirit:version").text
+        acc[[design_name, design_version]] = design_doc
+      end
+      acc
+    end
+    raise 'No valid design could be found!' if design_docs.keys.empty?
+    design_docs
+  end
+  # Decides whether version_a is strictly more recent than version_b. Accepts
+  # any relaxed version of semantic versioning markup (i.e., +X(\.Y(\.Z)?)?+).
+  #
+  # @param [String] version_a a version number
+  # @param [String] version_b a version number
+  #
+  # @return [Boolean] a Boolean that states if +version_a > version_b+
+  #
+  def self.is_most_recent_version?(version_a, version_b)
+    split_a = version_a.split('.')
+    split_b = version_b.split('.')
+    split_a.each_with_index do |el,i|
+      return true if split_b.size <= i && el.to_i != 0
+      return true if el.to_i > split_b[i].to_i
+    end
+    false
+  end
+  # Decides whether version_a and version_b are the same version. Accepts any
+  # relaxed version of the semantic versioning markup (i.e., +X(\.Y(\.Z)?)?+).
+  # When comparing versions with different lengths, the method will 'pad' the
+  # shortest version string with 0s.
+  #
+  # @example
+  #   IPXACT::is_same_version('1.0', '1.1')
+  #   # => false
+  #
+  #   IPXACT::is_same_version('1.0', '1.0')
+  #   # => true
+  #
+  #   IPXACT::is_same_version('1.0.0', '1.0')
+  #   # => true
+  #
+  #   IPXACT::is_same_version('1.0.1', '1.0')
+  #   # => false
+  #
+  # @return [Boolean] a Boolean that states if +version_a == version_b+
+  #   (relaxed equivalence)
+  #
+  def self.is_same_version?(version_a, version_b)
+    return !(self.is_most_recent_version?(version_a, version_b) || self.is_most_recent_version?(version_b, version_a))
+  end
+  # Parses an IPXACT reference element (i.e., any +spirit:hierarchyRef+ or
+  # +spirit:componentRef+).
+  #
+  # @param [Nokogiri::Node] reference The IPXACT reference, as an XML
+  #                                   (Nokogiri) fragment
+  #
+  # @return [Hash] a Hash with the following keys:
+  #   +:library+ the referenced element's library;
+  #   +:name+ the referenced element's name;
+  #   +:vendor+ the referenced element's vendor;
+  #   +:version+ the referenced element's version.
+  #
+  def self.parse_reference(reference)
+    {
+      :library => reference['library'],
+      :name => reference['name'],
+      :vendor => reference['vendor'],
+      :version => reference['version']
+    }
+  end
+end
+require File.join File.dirname(__FILE__), 'ipxact/parser'
+require File.join File.dirname(__FILE__), 'ipxact/platform'
+require File.join File.dirname(__FILE__), 'ipxact/pathfinder/graph_pathfinder'