dataMetaDom 1.0.0

data/lib/dataMetaDom/sources.rb

@@ -0,0 +1,68 @@
+$:.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
+All sources including all includes from the master file.
+
+For command line details either check the new method's source or the README.rdoc file, the usage section.
+=end
+class Sources
+
+=begin rdoc
+Start parsing from the master file, collect all the files that are included.
+=end
+    def initialize(masterFile)
+        masterPath = File.dirname(masterFile)
+        @todo = {}; @done = {}
+        libSpec = ENV[DATAMETA_LIB]
+        @paths = libSpec ? libSpec.split(File::PATH_SEPARATOR).map { |e| uniPath(e) } : []
+        @paths.unshift(masterPath).flatten! if masterPath
+        @paths.unshift '.' # start looking in the current directory and then in the rest of the path
+        src = SourceFile.new(masterPath, File.basename(masterFile))
+        @todo[src.key] = src
+    end
+
+=begin rdoc
+Returns the set of the keys of the source files alredy parsed.
+=end
+    def doneKeys; @done.keys end
+
+=begin rdoc
+Fetches the instance of SourceFile by its key.
+=end
+    def [](key); @done[key] end
+
+# Queue a source file for parsing
+    def queue(name)
+        # need to resolve the name to the path first
+        includeDir = nil
+        @paths.each { |m|
+            fullName = "#{m}#{File::SEPARATOR}#{name}"
+            if File.exist?(fullName)
+                includeDir = m
+                break
+            end
+        }
+        raise "Missing include '#{name}' in the path #{@paths.join(File::PATH_SEPARATOR)}" unless includeDir
+        src = SourceFile.new(includeDir, name)
+        @todo[src.key]=src unless @todo[src.key] || @done[src.key]
+        self
+    end
+
+=begin rdoc
+Returns next source file in queue if any, returns +nil+ if no more source files left to parse.
+=end
+    def next
+        return nil if @todo.empty?
+        @key = nil
+        @todo.each_key { |k| @key = k; break }
+        @val = @todo[@key]
+        @todo.delete @key; @done[@key] = @val
+        @val
+    end
+end
+
+end

data/lib/dataMetaDom/util.rb

@@ -0,0 +1,279 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'set'
+require 'logger'
+
+module DataMetaDom
+
+# Logger set to WARN, daily rollover and max size 10M
+# Feel free to change any of it.
+L = Logger.new('dataMetaDom.log', 'daily', 10*1024*1024)
+L.level = Logger::WARN
+
+# Keyword: namespace
+NAMESPACE = :namespace
+
+# Keyword: include
+INCLUDE = :include
+
+# Keyword, data type: string with fixed length
+CHAR = :char
+
+# Keyword, data type: string with variable length
+STRING = :string
+
+# Keyword, data type: integer
+INT = :int
+
+# Keyword, data type: float (real numbers)
+FLOAT = :float
+
+# Keyword, data type: boolean
+BOOL = :bool
+
+# Keyword, data type: bitset
+BITSET = :bitset
+
+# Keyword, data type: URL
+URL = :url
+
+# Keyword, data type: map
+MAPPING = :mapping
+
+# Keyword, data type: datetime
+DATETIME = :datetime
+
+# Keyword, data type: numeric
+NUMERIC = :numeric
+
+# Keyword, identity
+IDENTITY = :identity
+
+# Keyword, unique
+UNIQUE = :unique
+
+# Keyword, matches
+MATCHES = :matches
+
+# Keyword, index
+INDEX = :index
+
+# Key to a no-namespace
+NO_NAMESPACE = ''.to_sym
+
+# Wiki for DataMeta DOM
+WIKI = 'https://github.com/eBayDataMeta/DataMeta'
+
+# HTML tag referencing the WIKI
+WIKI_REF_HTML = "<a href='#{WIKI}'>DataMeta</a>"
+
+# Keyword, data type, the RAW type refers to raw data, like a byte array
+RAW = :raw
+
+# the reference keyword was not a good idea, too much confusion and dupe functionality
+# with the better way, namely referencing an object by name
+#REFERENCE=:reference
+
+=begin rdoc
+Keyword +doc+, documentation.
+=end
+DOC = :doc
+
+=begin rdoc
+Keyword +ver+, version info.
+=end
+VER_KW = :ver
+
+# Keyword, data type, enum
+ENUM = :enum
+
+# Keyword, end
+END_KW = :end
+
+# Keyword, record
+RECORD = :record
+
+# Package separator in a namespace.
+PACK_SEPARATOR = '.'
+
+# Environment variable for DataMeta DOM library path.
+DATAMETA_LIB = 'DATAMETA_LIB'
+
+# for source code generation, 2 spaces
+SOURCE_INDENT = ' ' * 2
+
+# Prefix for a required field
+REQUIRED_PFX = '+'.to_sym
+
+# Prefix for an optional field
+OPTIONAL_PFX = '-'.to_sym
+
+# DataMeta DOM standard types that have a dimension with a scale
+SCALE_TYPES = Set.new [NUMERIC]
+
+=begin rdoc
+Data Types that must be dimensioned, with a length or with a length and a scale, as
+it includes all the SCALE_TYPES too..
+=end
+DIMMED_TYPES = Set.new ([FLOAT, INT, CHAR, RAW] << SCALE_TYPES.to_a).flatten
+
+# Optionally dimmable types - may have a dim or may have not
+OPT_DIMMABLE = Set.new ([STRING]).flatten
+
+# standard types is a superset of dimmensionable types, adding BOOL and DATETIME
+STANDARD_TYPES = Set.new(([BOOL, DATETIME, URL] << DIMMED_TYPES.to_a << OPT_DIMMABLE.to_a << SCALE_TYPES.to_a).flatten)
+
+=begin rdoc
+Record attribute keywords:
+* +identity+
+* +unique+
+* +index+
+=end
+REC_ATTR_KEYWORDS = Set.new [IDENTITY, UNIQUE, INDEX]
+# Valid first symbol of a DataMeta DOM idenifier such as entity or enum name, field name, enum item.
+ID_START = '[A-Za-z_]'
+
+# Valid first symbol for a DataMeta DOM Type
+TYPE_START = '[A-Z]'
+
+puts "Standard types: #{STANDARD_TYPES.to_a.map { |k| k.to_s }.sort.join(', ')}" if $DEBUG
+
+# Migration context - for a record
+    class MigrCtx
+        attr_accessor :rec, :canAuto, :isSkipped
+        def initialize(name)
+            @rec = name
+            @canAuto = true # assume we can automigrate unless encounter problems that would require a HIT
+            @isSkipped = false
+        end
+    end
+
+=begin rdoc
+Suffix for the java source files for the implementors of the DataMetaSame interface by all the fields on the class.
+=end
+    SAME_FULL_SFX = '_DmSameFull'
+
+=begin rdoc
+Suffix for the java source files for the implementors of the DataMetaSame interface by identity field(s) on the class.
+=end
+    SAME_ID_SFX = '_DmSameId'
+
+# +DataMetaSame+ generation style: Full Compare, compare by all the fields defined in the class
+    FULL_COMPARE = :full
+
+=begin rdoc
++DataMetaSame+ generation style: Compare by the identity fields only as defined on DataMetaDom::Record
+=end
+    ID_ONLY_COMPARE = :id
+
+# One indent step for java classes, spaces.
+    INDENT = ' ' * 4
+
+# keep in sync with generated classes such as the Java class `CannedRegexUtil` in DataMeta DOM Core/Java etc.
+    CANNED_RX = Set.new [:email, :phone]
+
+# holds a custom regex symbol and the variables that use this regex
+    class RegExEntry
+        attr_reader :r, :vars, :req
+# initializes interna variables
+        def initialize(regex, var, req)
+            @r = regex
+            @vars = Set.new [var]
+            @req = req
+        end
+# adds the variable to the instance
+        def <<(var)
+            @vars << var
+        end
+
+        def req?; @req end
+    end
+
+# Registry for the regexes so we don't repeat those
+    class RegExRoster
+        attr_reader :i_to_r, :r_to_i, :canned
+
+        class << self
+# Converts the given custom RegEx index to the matching Pattern static final variable name
+            def ixToVarName(index)
+                "REGEX___#{index}___"
+            end
+        end
+
+        # sets index to 0, initializes hashes
+        def initialize
+            @index = 0
+            @i_to_r = {}
+            @r_to_i = {}
+            @canned = {}
+        end
+
+        # adds a new regex to the registry
+        def register(f)
+            var = f.name
+            rx = f.regex
+            rx = rx[1..-2] if rx.length > 2 && rx.start_with?('/') && rx.end_with?('/')
+            k = rx.to_sym
+            if CANNED_RX.member?(k)
+                if @canned.has_key?(k)
+                    @canned[k] << var
+                else
+                    @canned[k] = RegExEntry.new(k, var, f.isRequired)
+                end
+            elsif @r_to_i.has_key?(k)
+                # this regex is already registered, just add the variable
+                @i_to_r[@index] << var
+            else
+                @index += 1
+                @i_to_r[@index] = RegExEntry.new(k, var, f.isRequired)
+                @r_to_i[k] = @index
+            end
+        end
+
+    end
+
+=begin rdoc
+With the given full type including the namespace if any and the given namespace (java package, python package etc),
+figures out whether the full type has to be reference in full, if it belongs to a different namespace,
+or just by the base name if it belongs to the same package.
+
+* Parameters
+  * +fullType+ - full data type including the namespace if any
+  * +namespace+ - reference namespace.
+
+For example, passed:
+    "com.acme.proj.Klass", "com.acme.lib"
+will return
+    "com.acme.proj.Klass"
+
+but when passed:
+    "com.acme.proj.Klass", "com.acme.proj"
+will return
+    "Klass"
+
+This is to avoid excessive verbosity when referencing entities in the same package.
+=end
+    def condenseType(fullType, ref_namespace)
+        ns, base = DataMetaDom.splitNameSpace(fullType)
+        # noinspection RubyNestedTernaryOperatorsInspection
+        DataMetaDom.validNs?(ns, base) ? ( ns == ref_namespace ? base : fullType) : fullType
+    end
+
+# Migrator implementor name
+    def migrClass(base, ver1, ver2); "Migrate_#{base}_v#{ver1.toVarName}_to_v#{ver2.toVarName}" end
+
+=begin rdoc
+Builds and returns the Java-style getter name for the given field. This style is used in other platforms such as
+Python, for consistency.
+=end
+    def getterName(f); "get#{DataMetaXtra::Str.capFirst(f.name.to_s)}" end
+
+=begin rdoc
+Builds and returns the Java-setter setter name for the given field. This style is used in other platforms such as
+Python, for consistency.
+=end
+    def setterName(f); "set#{DataMetaXtra::Str.capFirst(f.name.to_s)}" end
+
+    module_function :setterName, :getterName
+
+end

data/lib/dataMetaDom/ver.rb

@@ -0,0 +1,244 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'fileutils'
+require 'typesafe_enum'
+require 'set'
+require 'dataMetaDom/docs'
+
+module DataMetaDom
+
+=begin
+Semantic Version implementation.
+
+See {http://semver.org this page} for details
+=end
+    class SemVer
+        attr_reader :source, :semanticPartsOnly, :items
+# Version difference levels as an enum
+        class DiffLevel < TypesafeEnum::Base
+            new :NONE   # Versions are equal
+            new :MAJOR  # Difference in the Major part
+            new :MINOR  # Difference in the Minor part
+            new :UPDATE # Difference in the Update (Patch) part
+            new :BUILD  # Difference in the Build part
+        end
+
+       # Split by dots pattern
+        DOTS_SPLIT = %r<\.>
+       # Any Integral part of the Version - just digits
+        DIGITS = %r<^[0-9]+$>
+
+        # Major part index in the @items array
+        MAJOR_INDEX = 0
+        # Minor part index in the @items array
+        MINOR_INDEX = MAJOR_INDEX + 1
+        # Update part index in the @items array
+        UPDATE_INDEX = MINOR_INDEX + 1
+        # Build part index in the @items array
+        BUILD_INDEX = UPDATE_INDEX + 1
+        # Minimal size of the @items array
+        ITEMS_MIN_SIZE = UPDATE_INDEX + 1
+        # Max size of the @items array
+        ITEMS_MAX_SIZE = BUILD_INDEX + 1
+
+        # Equality for the saucer operator <=>
+        EQ = 0
+        # Strictly "greater than" for the saucer operator <=>
+        GT = 1
+        # Strictly "lesser than" for the saucer operator <=>
+        LT = -1
+
+# Parsing constructor
+        def initialize(src)
+            raise ArgumentError, "Attempted to create an instance of #{self.class.name} from a nil" if src.nil?
+            @source = src
+            # put everything in an array -- this provides free eql? and hash() methods
+            @items = []
+            src.split(DOTS_SPLIT).each { |i|
+                if i =~ DIGITS
+                    @items << i.to_i
+                else
+                    break
+                end
+            }
+            raise ArgumentError, %<Invalid semantic version format: #{src}> if items.size < ITEMS_MIN_SIZE ||
+                    items.size > ITEMS_MAX_SIZE
+
+            raise ArgumentError,
+                  %<Invalid semantic version format: "#{src}": build version can not be zero.> unless build.nil? ||
+                    build != 0
+
+            @semanticPartsOnly  = @items.map{|i| i.to_s}.join('.')
+
+        end
+
+        # Major part of the version
+        def major; @items[MAJOR_INDEX] end
+
+        # Minor part of the version
+        def minor; @items[MINOR_INDEX] end
+
+        # Update part of the version
+        def update; @items[UPDATE_INDEX] end
+
+        # Build part of the version or nil
+        def build; items.size > BUILD_INDEX ? @items[BUILD_INDEX] : nil end
+
+# Difference Level, computes one of the DiffLevel values
+        def diffLevel(other)
+            return DiffLevel::MAJOR if major != other.major
+            return DiffLevel::MINOR if minor != other.minor
+            return DiffLevel::UPDATE if update != other.update
+            if (
+               !build.nil? && !other.build.nil? && (build <=> other.build) != EQ
+            ) || (
+               build.nil? && !other.build.nil?
+            ) || ( !build.nil? && other.build.nil? )
+                return DiffLevel::BUILD
+            end
+            DiffLevel::NONE
+        end
+
+# Override the eql? for the == operator to work
+        def eql?(o); @items == o.items end
+
+# Override the hash() method for the sets and maps to work
+        def hash; @items.hash end
+
+# The Saucer Operator, Ruby equivalent of Java's compareTo(...)
+        def <=>(o)
+            raise ArgumentError, %<Attempt to compare #{self.class.name} "#{self}" to a nil> if o.nil?
+
+            0.upto(UPDATE_INDEX) { |x|
+                cmp = items[x] <=> o.items[x]
+                return cmp unless cmp == EQ #  not equal: end of the story, that's the comparison result
+            }
+            # if we are here, the Minor, Major and the Update are equal. See what's up with the build if any:
+
+            # this object is newer (version bigger) because it has a build number but the other does not
+            return GT if items.size > o.items.size
+
+            # this object is older (version lesser) because it does not have a build number but the other does
+            return LT if items.size < o.items.size
+
+            # We got build part in self and the other, return the build part comparison:
+            build <=> o.build
+        end
+
+        # For a simple string representation, just show the source
+        def to_s; @source end
+
+        # Long string for debugging and detailed logging - shows semantic parts as parsed
+        def to_long_s; "#{self.class.name}{#{@source}(#{@semanticPartsOnly})}" end
+
+=begin
+Consistently and reproducibly convert the version specs to the text suitable for making it a part of a class name or a
+variable name
+=end
+        def toVarName; @items.join('_') end
+
+# Overload the equals operator
+        def ==(other); self.<=>(other) == EQ end
+# Overload the greater-than operator
+        def >(other); self.<=>(other) == GT end
+# Overload the lesser-than operator
+        def <(other); self.<=>(other) == LT end
+# Overload the greater-than-or-equals operator
+        def >=(other); self.<=>(other) >= EQ end
+# Overload the lesser-than-or-equals operator
+        def <=(other); self.<=>(other) <= EQ end
+
+        class << self
+# Builds an instance of SemVer from the given specs whatever they are
+            def fromSpecs(specs)
+                case specs
+                    when SemVer
+                        specs
+                    when String
+                        SemVer.new(specs)
+                    else
+                        raise ArgumentError, %<Unsupported SemVer specs type #{specs}==#{specs.inspect}>
+                end
+            end
+        end
+    end
+
+=begin rdoc
+Version info.
+=end
+    class Ver
+=begin rdoc
+Full version info.
+=end
+        attr_accessor :full
+
+=begin rdoc
+Creates an instance with the given full version.
+=end
+        def initialize(specs)
+            @full = if specs.kind_of?(Integer)
+                        raise ArgumentError,
+                              %|Invalid version specs: "#{specs
+                              }"; a version must be of a valid Semantic format|
+                    else
+                       SemVer.fromSpecs(specs)
+                    end
+        end
+
+        class << self
+# Reversions all the files in the given paths recursively
+            def reVersion(path, namespace, globs, srcVer, trgVer)
+                vPat = srcVer ? srcVer.toVarName : '\d+_\d+_\d+'
+                globs.each { |g|
+                    Dir.glob("#{path}/#{g}").each { |f|
+                        origLines = IO.read(f).split("\n")
+                        newLines = []
+                        origLines.each { |line|
+                            newLines << (line.end_with?('KEEP') ? line :
+                                    line.gsub(%r~#{namespace.gsub(/\./, '\.')}\.v#{vPat}~, "#{namespace}.v#{trgVer.toVarName}"))
+                        }
+                        IO.write(f, newLines.join("\n"), mode: 'wb')
+                    }
+                }
+                Dir.entries(path).select{|e| File.directory?(File.join(path, e))}.reject{|e| e.start_with?('.')}.each {|d|
+                    reVersion File.join(path, d), namespace, globs, srcVer, trgVer
+                }
+
+            end
+
+        end
+
+=begin rdoc
+Textual presentation for the instance.
+=end
+        def to_s; "ver #{full}" end
+    end
+
+=begin rdoc
+Anything having a version. It must be also documentable, but not everything documentable is also versionable,
+like, for example, Record Field or an Enum part.
+=end
+    class VerDoccable < Documentable
+=begin rdoc
+The version info, an instance of Ver.
+=end
+        attr_accessor :ver
+=begin rdoc
+Resets stateful information on the entity level, like docs that should not apply to the next entity if missing.
+=end
+        def resetEntity
+            docs.clear
+        end
+
+=begin rdoc
+Attempts to parse an instance of Ver from the current line on the given instance of SourceFile.
+Returns the instance of Ver if successful, nil otherwise.
+Parameter:
+* +src+ - the instance of SourceFile to parse the version info from.
+=end
+        def self.verConsumed?(src)
+            src.line =~ /^\s*#{VER_KW}\s+(\S+)\s*$/ ? Ver.new($1) : nil
+        end
+
+    end
+end