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

ipxact-ruby 0.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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'