vhdl_parser 0.1 → 0.2

data/lib/vhdl_parser/entity.rb

@@ -1,10 +1,20 @@
 module VHDL_Parser
   class Entity
 
-    attr_accessor :name
-    attr_reader :ports, :generics
+    # An array of all the Ports.
+    # @return [Array<Port>] An array of all the Ports on this entity.
+    attr_reader :ports
 
-    def initialize
+    # An array of all the Generics.
+    # @return [Array<Generic>] An array of all the Generics on this entity.
+    attr_reader :generics
+
+    # The name of the Entity.
+    # @return [String] The name of the Entity
+    attr_reader :name
+
+    def initialize(name)
+      @name = name
       @ports = Array.new
       @generics = Array.new
     end
@@ -19,6 +29,13 @@ module VHDL_Parser
     end
 
 
+    # Applies constants from a package to the entity. For example, if 
+    # the Entity has an input whose size is defined with a constant, like
+    # "std_logic_vector(MY_SIZE-1 downto 0)", and "MY_SIZE" is defined in
+    # the package, this method will evaluate the size to a real number.
+    #
+    # @param [package] Package The package instance to merge.
+    # @return [nil] Nothing
     def merge_package(package)
       # TODO: do some type checking
       @generics.each do |g|
@@ -35,6 +52,7 @@ module VHDL_Parser
             g.right = Utility.sub_constants(g.right, k, v)
           end
         end
+        nil
       end
 
       @ports.each do |p|
@@ -50,6 +68,8 @@ module VHDL_Parser
       end
     end
 
+    # Re-processes Generics. May not be needed, so don't worry about it.
+    # @visibility private
     def process_generics
       @ports.each do |p|
         @generics.each do |g|

data/lib/vhdl_parser/extractor.rb

@@ -1,4 +1,7 @@
 module VHDL_Parser
+
+  # Helper class with methods that extract a portion of interest from
+  # a given String.
   class Extractor
 
     def self.extract_name(string)

data/lib/vhdl_parser/generic.rb

@@ -1,6 +1,39 @@
 module VHDL_Parser
+
+  # Describes a VHDL Generic.
   class Generic
-    attr_accessor :name, :value, :type, :size, :left, :right, :size_dir, :comment
+
+    # Name of the Generic.
+    # @return [String]
+    attr_accessor :name
+
+    # Value of the Generic.
+    # @return [String]
+    attr_accessor :value
+
+    # Type of the Generic.
+    # @return [String]
+    attr_accessor :type
+
+    # Size String of the Generic.
+    # @return [String]
+    attr_accessor :size
+
+    # The left part of the size definition, if there is one.
+    # @return [String]
+    attr_accessor :left
+
+    # The right part of the size definition, if there is one.
+    # @return [String]
+    attr_accessor :right
+
+    # The direction of the size, i.e. "to" or "downto"
+    # @return [String]
+    attr_accessor :size_dir
+
+    # Any inline comments of that Generic.
+    # @return [String]
+    attr_accessor :comment
 
     def initialize
       @left = 0
@@ -8,6 +41,8 @@ module VHDL_Parser
       @size_dir = "downto"
     end
 
+    # Basic String representation of the Generic
+    # @return [String]
     def to_s
       name.ljust(15) + "\t" +
       type + " " + 

data/lib/vhdl_parser/magic.rb

@@ -1,4 +1,8 @@
 class String
+
+  # Addition to String class that determines if a String is 
+  # numeric.
+  # @return [boolean] Whether the String is numeric.
   def is_numeric?
     true if Float(self) rescue false
   end

data/lib/vhdl_parser/package.rb

@@ -1,16 +1,23 @@
 module VHDL_Parser
+  # Represents a VHDL Package
   class Package
 
+    # A Hash of all the constants defined in this Package.
+    # @return [Hash]
     attr_accessor :constants
 
     def initialize
       @constants = Hash.new
     end
 
+    # @return [String]
     def to_s
       @constants.to_s
     end
 
+    # Processes the constants defined in the package. This resolves
+    # constants being dependent on other constants in this package.
+    # @return [nil] Nothing
     def process
       @constants.each do |k,v|
         @constants.each do |k2,v2|

data/lib/vhdl_parser/port.rb

@@ -1,6 +1,39 @@
 module VHDL_Parser
+  # Defines an input or output on the Entity
   class Port
-    attr_accessor :name, :direction, :comment, :type, :size, :left, :right, :size_dir
+    # The name of the Port
+    # @return [String]
+    attr_accessor :name
+
+    # The direction of the port. 
+    # I.e. "in", "out", "inout"
+    # @return [String]
+    attr_accessor :direction
+
+    # Any inline comment on the Port
+    # @return [String]
+    attr_accessor :comment
+
+    # The type of the Port
+    # @return [String]
+    attr_accessor :type
+
+    # String representation of the size, 
+    # e.g. "(7 downto 0)"
+    # @return [String]
+    attr_accessor :size
+
+    # Left part of the size, e.g. "7"
+    # @return [String]
+    attr_accessor :left
+
+    # Right part of the size, e.g. "0"
+    # @return [String]
+    attr_accessor :right
+
+    # Left part of the size, e.g. "downto"
+    # @return [String]
+    attr_accessor :size_dir
 
     def initialize
       @left = 0
@@ -8,6 +41,7 @@ module VHDL_Parser
       @size_dir = "downto"
     end
 
+    # @return [String]
     def to_s
       name.ljust(15) + "\t" +
       direction + "\t" + 
@@ -16,6 +50,8 @@ module VHDL_Parser
       comment + "\n"
     end
 
+    # Returns a string based on the left, right, and size_dir attributes.
+    # @return [String] The size formatted as a String.
     def size
       unless @left.nil?
         "(#{@left} #{@size_dir} #{@right})"

data/lib/vhdl_parser/utility.rb

@@ -1,5 +1,16 @@
 module VHDL_Parser
+  # Utility class with helpers
   class Utility
+
+    # Substitutes a constant with an actual value, and does so smartly.
+    # This method uses the `eval` method to evaluate the final Math expression
+    # into a single value. It does some basic input checking and replaces everything
+    # that's not a number or mathematical operator with "x". That should prevent
+    # some abuse.
+    #
+    # @param [target] String The size string, e.g. "MY_VALUE-1"
+    # @param [key] String The key string, e.g. "MY_VALUE". This gets compared to the target.
+    # @param [value] String The value string, e.g. "8". That's what MY_VALUE gets replaced with.
     def self.sub_constants(target, key, value)
       # first get all the words of the size. That could be
       # a number or a constant.

data/lib/vhdl_parser.rb

@@ -7,16 +7,24 @@ require 'vhdl_parser/generic'
 require 'vhdl_parser/package'
 
 
+# VHDL Parser Module. It parses a given VHDL entity into Ruby objects that can 
+# then be used further in code, e.g. for visualization or automation.
 module VHDL_Parser
 
   class << self
   end
 
+  # Parses the given file and returns an Entity object.
+  # @param [filename] String the path to the file.
+  # @return [Entity] Entity object
   def self.parse_file(filename)
     string = File.read(filename)
     self.parse(string)
   end
 
+  # Parses the given string and returns an Entity object.
+  # @param [vhdl_string] String The VHDL entity as a String
+  # @return [Entity] Entity object
   def self.parse(vhdl_string)
     info = vhdl_string.match /entity\s+(.*)\s+is\s+(?:generic\s*\((.*)\);)?\s*port\s*\((.*)\);\s*end\s*\1;/im
 
@@ -28,8 +36,7 @@ module VHDL_Parser
     ports.map! { |s| s.strip!}
     ports.delete_if { |l| l.match /^--/}
     
-    @entity = Entity.new
-    @entity.name = info[1]
+    @entity = Entity.new(info[1])
 
     
     self.parse_generics(generics)
@@ -40,11 +47,17 @@ module VHDL_Parser
     return @entity
   end
 
+  # Parses the given VHDL package file and returns a Package object.
+  # @param [filename] String the path to the file.
+  # @return [Package] Package object
   def self.parse_package_file(filename)
     string = File.read(filename)
     self.parse_package(string)
   end
 
+  # Parses the given VHDL package string and returns a Package object.
+  # @param [string] String The VHDL package as a String
+  # @return [Package] Package object
   def self.parse_package(string)
     package = Package.new
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vhdl_parser
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: '0.2'
   prerelease: 
 platform: ruby
 authors:
@@ -51,3 +51,4 @@ signing_key:
 specification_version: 3
 summary: VHDL Entity Parser
 test_files: []
+has_rdoc: