dataMetaDom 1.0.0

data/lib/dataMetaDom/record.rb

@@ -0,0 +1,397 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+%w(fileutils set dataMetaXtra dataMetaDom/docs dataMetaDom/ver).each { |r| require r }
+
+module DataMetaDom
+
+=begin rdoc
+A mapping - of values from one data type to values of another data types. Supports only DataMeta DOM standard types
+
+For command line details either check the new method's source or the README.rdoc file, the usage section.
+=end
+class Mapping < VerDoccable
+
+    # Empty binding for evaluation to avoid exposing class variables
+    BINDING_NONE = DataMetaXtra.nilBinding
+
+=begin rdoc
+Name of this mapping data type including namespace if any.
+=end
+    attr_accessor :name
+=begin rdoc
+DataType "from" (source)
+=end
+    attr_accessor :fromT
+=begin rdoc
+DataType "to" (target)
+=end
+    attr_accessor :toT
+
+=begin rdoc
+The hash of the "from" (source) values to the "to" (target) values.
+=end
+    attr_accessor :base
+
+=begin rdoc
+Creates an instance for the given full data type name, including namespace if any.
+=end
+    def initialize(name)
+        #noinspection RubyArgCount
+        super()
+        @name = name.to_sym; @base = {}
+    end
+
+=begin rdoc
+Returns the value for the given key as mapped.
+* Parameters:
+  * +key+ - the value of the type "from" (source) to get the matching value of the type "to" (target) for.
+=end
+    def [](key); @base[key] end
+
+=begin rdoc
+Assign the mapped value for the given key, useful for building a mapping from the code.
+* Parameters:
+  * +key+ - the value of the type "from" (source)
+  * +val+ - the matching value of the type "to" (target).
+=end
+    def []=(key, val); base[key] = val end
+
+=begin rdoc
+All the values of the type "to" (target) defined on the mapping, sorted
+=end
+    def values; @base.values.sort end
+
+=begin rdoc
+All the keys of the type "from" (source) defined on the mapping, sorted
+=end
+    def keys; @base.keys.sort end
+
+=begin rdoc
+Parses the mapping, the keys and the values from the given source.
+* Parameters
+  * +source+ - an instance of SourceFile
+=end
+    def parseBase(source)
+        hashSource = '{'
+        while (line = source.nextLine)
+            case line
+                when /^\s*#{END_KW}\s*$/
+                    self.ver = source.ver unless self.ver
+                    self.docs = source.docs.clone
+                    source.docs.clear
+                    raise "Version missing for the Mapping #{name}" unless self.ver
+                    break
+                else
+                    hashSource << line
+            end # case
+        end # while line
+        @base = eval(hashSource + '}', BINDING_NONE)
+        self
+    end # def parse
+end
+
+=begin rdoc
+A Bit Set mapping, one instance holding a set of references to the values packed tightly as a bit set.
+=end
+class BitSet < Mapping
+
+=begin rdoc
+Attempts to consume the instance from the given source, returns it if successful, returns nil otherwise.
+* Parameters
+  * +model+ - an instance of a Model
+  * +src+ - an instance of SourceFile
+=end
+    def self.consumed?(model, src)
+        src.line =~ /^\s*#{BITSET}\s+(\w+)\s+.+$/ ? model.addEnum(BitSet.new(combineNsBase(DataMetaDom.nsAdjustment(src.namespace, model.options, src), $1)).parse(src)) : nil
+    end
+
+=begin rdoc
+Returns the keyword for this Mapping implementation, in this case "<tt>bitset</tt>"
+=end
+    def sourceKeyWord; BITSET end
+
+=begin rdoc
+Parses the current instance from the given source.
+* Parameters
+  * +src+ - an instance of SourceFile
+=end
+    def parse(src)
+        r = src.line.scan(/^\s*\w+\s+\w+\s+(\S+)\s*$/)
+        raise 'Invalid bitset specification' unless r && r[0] && r[0][0]
+        self.fromT = INT4 #platform type is up to the concrete generator
+        self.toT = DataType.parse(src, r[0][0])
+        parseBase src
+    end
+end
+
+=begin rdoc
+A single-value map of a key to a value.
+=end
+class Mappings < Mapping
+
+=begin rdoc
+Attempts to consume the instance from the given source, returns it if successful, returns nil otherwise.
+* Parameters
+  * +model+ - an instance of a Model
+  * +src+ - an instance of SourceFile
+=end
+    def self.consumed?(model, src)
+        src.line =~ /^\s*#{MAPPING}\s+(\w+)\s+.+$/ ? model.addEnum(Mappings.new(combineNsBase(DataMetaDom.nsAdjustment(src.namespace, model.options, src), $1)).parse(src)) : nil
+    end
+
+=begin rdoc
+Returns the keyword for this Mapping implementation, in this case "<tt>map</tt>"
+=end
+    def sourceKeyWord; MAPPING end
+
+=begin rdoc
+Parses the current instance from the given source.
+* Parameters
+  * +src+ - an instance of SourceFile
+=end
+    def parse(src)
+        r = src.line.scan(/^\s*\w+\s+\w+\s+(\S+)\s+(\S+)\s*$/)
+        raise 'Invalid map specification' unless r && r[0] && r[0][0] && r[0][1]
+        self.fromT = DataType.parse(src, r[0][0])
+        self.toT = DataType.parse(src, r[0][1])
+        parseBase src
+    end
+end
+
+=begin rdoc
+A data structure comprised of fields with the notion of identity, indexes, unique and not.
+@!attribute [r] namespace
+    @return [String] part of the {#name}, the prefix before last dot, "package" in Java and Scala, "namespace" in C
+
+@!attribute [r] baseName
+    @return [String] part of the {#name}, the suffix after last dot
+
+=end
+class Record < VerDoccable
+
+=begin rdoc
+Full Record datatype name, including namespace if any. Should be unique in the model.
+=end
+    attr_accessor :name
+
+=begin rdoc
+The fields as a map keying a field name to the matching instance of a Field
+=end
+    attr_reader :fields
+
+=begin rdoc
+An instance of RecIdentity.
+=end
+    attr_reader :identity
+
+=begin rdoc
+A hash mapping to RecUnique from its key. Meaning, RecUnique.key to the matching RecUnique
+=end
+    attr_reader :uniques
+
+=begin rdoc
+A hash mapping to RecIndex from its key. Meaning, RecIndex.key to the matching RecIndex
+=end
+    attr_reader :indexes
+
+=begin rdoc
+An array of Reference
+=end
+    attr_reader :refs
+
+=begin rdoc
+The unique key for the record, unique across the Model.
+=end
+    attr_reader :key
+
+    attr_reader :namespace
+
+    attr_reader :baseName
+
+=begin rdoc
+Attempts to consume the instance from the given source, returns it if successful, returns nil otherwise.
+* Parameters
+  * +model+ - an instance of a Model
+  * +src+ - an instance of SourceFile
+=end
+    def self.consumed?(model, src)
+        if src.line =~ /^\s*#{RECORD}\s+(\w+)$/
+            newRecord = Record.new(DataMetaDom.combineNsBase(DataMetaDom.nsAdjustment(src.namespace, model.options, src).to_sym, $1)).parse(model, src)
+            $stderr.puts %<WARN: Record redefinition: "#{newRecord.key}"> if model.records[newRecord.key]
+            model.addRecord(newRecord)
+        else
+            nil
+        end
+    end
+
+=begin rdoc
+Creates an instance for the given full data type name, including namespace.
+Namespace is required.
+
+
+=end
+    def initialize(name)
+        #noinspection RubyArgCount
+        super()
+        @namespace, @baseName = DataMetaDom.splitNameSpace(name)
+
+        raise %Q<Record "#{@baseName}": no namespace; namespaces are required!> unless @namespace
+        @name = name.to_sym
+        @key = @name
+        @fields={}; @uniques={}; @identity=nil; @indexes = {}; @refs=[]
+    end
+
+=begin rdoc
+Fetches the field by the field key, i.e. Field.name
+=end
+    def [](fieldKey); @fields[fieldKey] end
+
+=begin rdoc
+Verifies that the list of ids is valid, meaning that there is a field with the given name on this record.
+* Parameter
+  * +ids+ - an array of strings, each should be a valid field name already defined on this Record.
+=end
+    def assertIds(ids)
+        ids.each { |id|
+            k = id.to_sym
+            raise "Undeclared field '#{id}'" unless @fields.has_key?(k)
+        }
+    end
+
+=begin rdoc
+Set the identity on the Record.
+* Parameter:
+  * +newIdy+ - an instance of RecIdentity
+=end
+    def identity=(newIdy)
+        raise 'There can be only one identity statement in a record' if @identity
+        @identity = newIdy
+        assertIds(@identity.args)
+        @identity.args.each { |id|
+            f = @fields[id.to_sym]
+
+            raise ArgumentError, %|Field "#{
+                id}" is made identity; no aggregate types or maps can be identity| if f.aggr? || f.map?
+
+            raise ArgumentError, %|Optional field "#{
+                id}" is made identity; only required fields may be identity| unless f.isRequired
+        }
+    end
+
+=begin rdoc
+Add another unique index to the record.
+* Parameter:
+  * +newUq+ - an instance of RecUnique to add ot this record.
+=end
+    def addUnique(newUq)
+        assertIds(newUq.args)
+        raise "Duplicate unique set declaration #{newUq}" if @uniques.has_key?(newUq.key)
+        @uniques[newUq.key] = newUq
+    end
+
+=begin rdoc
+Add another non-unique index to the record.
+* Parameter:
+  * +newIx+ - an instance of RecIndex to add to this Record
+=end
+    def addIndex(newIx)
+        assertIds(newIx.args)
+        raise "Duplicate index declaration #{newIx}" if @indexes.has_key?(newIx.key)
+        @indexes[newIx.key] = newIx
+    end
+
+=begin rdoc
+Add another field to this Record's definition along with the source reference if any.
+* Parameters:
+  * +newField+ - an instance of Field to add to this Record
+  * +source+ - a reference to the SourceFile where this field has been defined, pass +nil+ if
+   built from the code.
+=end
+    def addField(newField, model, source=nil)
+        fieldKey = newField.name
+        raise "Duplicate field name '#{fieldKey}' in the Record '#{@name}'" if (@fields.key?(fieldKey))
+        @fields[fieldKey] = newField
+        unless STANDARD_TYPES.member?(newField.dataType.type)
+            ns, base = DataMetaDom.splitNameSpace(newField.dataType.type)
+            newNs = DataMetaDom.nsAdjustment(ns, model.options, source)
+            reRefName = "#{newNs}.#{base}".to_sym
+            newField.dataType.type = reRefName # adjust the type for finding the reference again
+            @refs << Reference.new(self, newField, reRefName, source ? source.snapshot : nil)
+        end
+    end
+
+=begin rdoc
+Add several Field definitions to this Record.
+* Parameters:
+  * +fields+ - an array of the instances of Field to add to this Record
+=end
+    def addFields(fields, model, source=nil); fields.each { |f| addField f, model, source } end
+
+=begin rdoc
+Add several non-unique indexes to the record.
+* Parameter:
+  * +ixs+ - an array of the instances of RecIndex to add to this Record
+=end
+    def addIndexes(ixs); ixs.each { |ix| addIndex ix } end
+
+=begin rdoc
+Add several unique indexes to the record.
+* Parameter:
+  * +uqs+ - an array of instances of RecUnique to add ot this record.
+=end
+    def addUniques(uqs); uqs.each { |uq| addUnique uq } end
+
+=begin rdoc
+Parse the Record from the given source into this instance.
+* Parameter:
+  * +source+ - an instance of SourceFile to parse from
+=end
+    def parse(model, source)
+        while (line = source.nextLine)
+            next if docConsumed?(source)
+            case line
+                when /^\s*#{END_KW}\s*$/
+                    if source.docs
+                        self.docs = source.docs.clone
+                        source.docs.clear
+                    end
+                    self.ver = source.ver unless self.ver
+                    raise "Version missing for the Record #{name}" unless self.ver
+                    return self
+                when ''
+                    next
+                else
+                    isTokenConsumed = false
+                    RECORD_LEVEL_TOKENS.each { |t|
+                        isTokenConsumed = t.consumed? source, self
+                        break if isTokenConsumed
+                    }
+                    unless isTokenConsumed
+                        raise ArgumentError, "Record #{@name}: all field declarations must precede identity" if @identity
+                        Field.consume(model, source, self)
+                    end
+                    resetEntity
+            end # case line
+        end # while line
+        self # for call chaining
+    end
+
+=begin rdoc
+Textual representation of this instance, with all the fields, attributes and references if any.
+=end
+    def to_s
+        "Record{#{@name}(#{@fields.values.join(';')},uq=[#{@uniques.map { |u| '[' + u.join(',') + ']' }.join('; ')}]"\
+       ";idy=[#{@identity ? @identity.args.join(',') : ''}]; refs=[#{@refs.join(',')}]}, #{self.ver}"
+    end
+end
+
+=begin rdoc
+DataMeta DOM source tokens on the Model level:
+* Record
+* Enum
+* BitSet
+* Map
+=end
+MODEL_LEVEL_TOKENS=[Record, Enum, BitSet, Mappings]
+
+end

data/lib/dataMetaDom/ref.rb

@@ -0,0 +1,127 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+%w(fileutils set).each { |r| require r }
+
+module DataMetaDom
+
+=begin rdoc
+A reference to another entity on this Model, any of:
+* Record
+* Enum
+* BitSet
+* Map
+
+For command line details either check the new method's source or the README.rdoc file, the usage section.
+=end
+class Reference
+
+=begin rdoc
+Type of a reference - unresolved.
+=end
+    UNRESOLVED = :u
+
+=begin rdoc
+Type of a reference - to a Record.
+=end
+    RECORD = :r
+
+=begin rdoc
+Type of a reference - to an Enum, a BitSet or a Map.
+=end
+    ENUM_REF = :e
+
+=begin rdoc
+The unique key for the reference to use in a hashmap.
+=end
+    attr_accessor :key
+
+=begin rdoc
+The field the reference originates from, an instance of a Field
+=end
+    attr_accessor :fromField
+
+=begin rdoc
+The Record the reference originates from, an instance of a Record
+=end
+    attr_accessor :fromEntity
+
+=begin rdoc
+The target Field of the reference, must be the only one field in the target Record's identity,
+determined by the resolve method.
+=end
+    attr_accessor :toFields
+
+=begin rdoc
+The target entity for this Reference, determined by the resolve method. If it is a Record,
+the record must have an identity consisting from only one field.
+=end
+    attr_accessor :toEntity
+
+=begin rdoc
+Reference to the source where this reference has been defined, if any.
+=end
+    attr_accessor :sourceRef
+
+=begin rdoc
+The type of the reference, UNRESOLVED or RECORD or ENUM_REF.
+=end
+    attr_accessor :type
+
+=begin rdoc
+Creates an instance with the given parameters.
+* Parameters:
+  * +sourceEntity+ - the instance of Record the reference originates from.
+  * +sourceField+ - the instance of Field the reference originates from
+  * +targetEntitySpec+ - a string, specification of the target entity to be resolved
+  * +sourceRef+ - an instance of SourceFile
+=end
+    def initialize(sourceEntity, sourceField, targetEntitySpec, sourceRef = nil)
+        @sourceRef = sourceRef
+        @targetEntitySpec = targetEntitySpec.to_sym; @fromEntity = sourceEntity; @fromField = sourceField
+        @type = UNRESOLVED
+        self
+    end
+
+=begin rdoc
+Resolve the target entity and the field on the given Model.
+=end
+    def resolve(model)
+        #@fromField = @fromEntity[@sourceFieldSpec.to_sym]
+        #raise "The field #@sourceFieldSpec is not defined on this entity: #@fromEntity, #@sourceRef" unless @fromField
+        @toEntity = model.records[@targetEntitySpec] || model.enums[@targetEntitySpec]
+        raise "Target entity #{@targetEntitySpec} is not defined; #{@sourceRef}" unless @toEntity
+        case # IMPORTANT!! make sure that you do not inspect and do not use Entity.to_s - this will blow up the stack
+            when @toEntity.kind_of?(Enum), @toEntity.kind_of?(BitSet), @toEntity.kind_of?(Mappings)
+                @type = ENUM_REF
+                @key= "#{@type}/#{@fromEntity.name}.#{@fromField.name}->#{@toEntity.name}"
+            when @toEntity.kind_of?(Record)
+                idy = @toEntity.identity
+#                raise "#@targetEntitySpec does not have an identity, can not be referenced to in IDL; #@sourceRef" unless idy
+#
+#                raise "Invalid ref #{@fromEntity.name}.#{@toField.name} -> #@toEntity"\
+#             "- it has no singular ID; #@sourceRef" unless idy.args.length == 1
+
+                @type = RECORD
+                @toFields = idy ? idy.args : @toEntity.fields.keys
+#                raise "The field #{idy.args[0]} is not defined on this entity: #@toEntity; #@sourceRef" unless @toField
+                @key = "#{@type}/#{@fromEntity.name}.#{@fromField.name}->#{@toEntity.name}.#{@toFields.join(',')}"
+            else
+                raise "Unsupported target entity: #{@toEntity.name}, for #{@sourceRef}"
+        end
+    end
+
+=begin rdoc
+Textual representation of this Reference. Need to be careful because the to_s on the Record includes a list of references
+and if you include a Record in this textual, this will cause infinite recursion with the stack failure.
+=end
+    def to_s
+        case @type
+            when UNRESOLVED; "Unresolved: #{@fromEntity.name}.#{@fromField.name} ==> #@targetEntitySpec; #@sourceRef"
+            when RECORD; "Record Ref: #@key"
+            when ENUM_REF; "Enum ref: #@key"
+            else; raise "Unsupported reference type #@type; #@sourceRef"
+        end
+    end
+end
+
+end

data/lib/dataMetaDom/sourceFile.rb

@@ -0,0 +1,150 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+%w(fileutils set dataMetaDom/docs dataMetaDom/ver).each { |r| require r }
+
+module DataMetaDom
+=begin rdoc
+A Model coupled with the DataMeta DOM source file info
+
+For command line details either check the new method's source or the README.rdoc file, the usage section.
+=end
+class SourceFile < VerDoccable
+=begin rdoc
+The directory to this source file.
+=end
+    attr_reader :path
+
+=begin rdoc
+The name of this source file in the directory indicated by the path property.
+=end
+    attr_reader :name
+
+=begin rdoc
+Unique key of this source file to use in hash maps, the absolute path to avoid duplicates by
+different ways to point to the file, turned into a symbol.
+=end
+    attr_reader :key
+
+=begin rdoc
+The namespace associated with the source file.
+=end
+    attr_reader :namespace
+
+=begin rdoc
+Current source line.
+=end
+    attr_reader :line
+
+=begin rdoc
+Current source line number
+=end
+    attr_reader :lineNum
+
+=begin rdoc
+Create an instance with the given parameters.
+* Parameters:
+  * +path+ - directory where the source file is located
+  * +name+ - the base name of this source file
+  * +line+ - source line if any, useful when creating the source reference from the code when source is not trivial.
+  * +lineNum+ - line number, useful when creating the source reference from the code
+  * +namespace+ - namespace associated with this source file, useful when creating the source reference from the code
+=end
+    def initialize(path, name, line = nil, lineNum = 0, namespace = nil)
+        #noinspection RubyArgCount
+        super()
+        @path = path
+        @name = name
+        @namespace = namespace
+        # use the Absolute Path to avoid double-dipping via different subdir references
+        @key = File.absolute_path("#{@path}#{File::SEPARATOR}#{@name}").to_sym
+        @lineNum = lineNum
+        @line = line # nil interpolates to an empty string
+    end
+
+=begin rdoc
+Create a shapshot of the source file information, useful for saving a status about an element currently parsed.
+Can not use this instance - as the parsing progresses, the stateful information will change.
+=end
+    def snapshot # for the history
+        snap = SourceFile.new(@path, @name, @line, @lineNum, @namespace)
+        snap.ver = Ver.new(self.ver.full)
+        snap
+    end
+
+=begin rdoc
+Parses this DataMeta DOM source into the given Model.
+=end
+    def parse model
+        while nextLine
+            puts "Source: #{@line}" if $DEBUG
+            next if docConsumed?(self)
+            if (newVer = VerDoccable.verConsumed?(self))
+                raise RuntimeError, "Only one version definition allowed, second one found in line #{@lineNum}" if self.ver
+               self.ver = newVer
+               model.ver = newVer # plant it straight into the model per the latest design
+               raise ArgumentError,
+                     %<Model version already defined as #{model.ver} but the file #{@path} tries to redefine it to #{newVer}.
+This is not allowed: all included files should define same version> unless model.ver && newVer == model.ver
+               next
+            end
+            case @line
+            # treat the namespace operator as a special case
+                when /^\s*#{NAMESPACE}\s+([\w\.]+)$/
+                    @namespace = $1
+                    next
+                when /^\s*#{INCLUDE}\s+(\S+)$/
+                    model.sources.queue "#{$1}.dmDom"
+                    next
+                else
+                    isTokenOk = false
+                    MODEL_LEVEL_TOKENS.each { |c|
+                        isTokenOk = c.consumed?(model, self)
+                        if isTokenOk
+                            resetEntity
+                            break
+                        end
+                    }
+                    raise "Syntax error; #{model.diagn}" unless isTokenOk
+
+            end
+
+        end # while
+    end
+
+=begin rdoc
+Advances a line, skipping empty lines and comments.
+Parameter:
+* +verbatim+ - pass true to maintain formatting and keep empty lines
+=end
+    def nextLine(verbatim = false)
+        @file = File.open("#{@path}#{File::SEPARATOR}#{@name}") unless defined?(@file) && @file
+        while (line = @file.gets)
+            unless line
+                @file.close
+                nil
+            end
+            @lineNum += 1
+            return (@line = line) if verbatim
+            @line = line.chomp.strip
+
+            case @line
+                when '', /^\s*#.*$/ # skip comments and empty lines
+                    next
+                else
+                    return @line
+            end
+        end
+    end
+
+=begin rdoc
+Full name of this source file, absolute path. Derived from the key property turned into a string.
+=end
+    def fullName; @key.to_s end
+
+=begin rdoc
+Textual representation of this source file reference, includes line number and the current source line.
+=end
+    def to_s; "#{fullName}##{@lineNum}{{#{@line}}}" end # file name, line number and line
+end
+
+end