dataMetaDom 1.0.0

data/lib/dataMetaDom/docs.rb

@@ -0,0 +1,122 @@
+$:.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
+
+# doc target for javadocs
+JAVA_DOC_TARGET = :java
+
+# doc target for plaintext
+PLAIN_DOC_TARGET = :plain
+
+# All documentation targets
+DOC_TARGETS = Set.new [PLAIN_DOC_TARGET, JAVA_DOC_TARGET]
+
+=begin rdoc
+Documentation tag
+
+For command line details either check the new method's source or the README.rdoc file, the usage section.
+=end
+class Doc
+=begin rdoc
+Documentation target such as PLAIN_DOC_TARGET or JAVA_DOC_TARGET or whatever is added in the future.
+May stick with plaintext unless it becomes easy to write in a common markup format and generate
+specific doc format from it.
+
+Can be one of the following:
+* PLAIN_DOC_TARGET - +plain+
+* JAVA_DOC_TARGET - +java+
+=end
+    attr_reader :target
+
+=begin rdoc
+The text of the documentation.
+=end
+    attr_accessor :text
+
+=begin rdoc
+Creates an instance for the given target and given text.
+=end
+    def initialize(target, text)
+        @target = target.to_sym
+        #noinspection RubyArgCount
+        raise "Unsupported docs target #@target" unless DOC_TARGETS.member?(@target)
+        @text = text
+    end
+
+=begin rdoc
+Parses the documentation from the given source, returns an instance of Doc.
+
+* Parameters:
+  * +source+ - an instance of SourceFile
+  * +params+ - an array, first member is the target.
+=end
+    def self.parse(source, params)
+        text = ''
+        while (line = source.nextLine(true))
+            case line
+                when /^\s*#{END_KW}\s*$/
+                    retVal = Doc.new params[0], text
+                    return retVal
+                else
+                    text << line
+            end # case
+        end # while line
+        raise "Parsing a doc: missing end keyword, source=#{source}"
+    end
+
+# Textual for the instance
+    def to_s; "Doc-#{target}\n#{text}" end
+end # class Doc
+
+# Anything that can have documentation.
+class Documentable
+
+=begin rdoc
+The hash keyed by the target.
+=end
+    attr_accessor :docs
+
+#Initializes the instance with an empty hash.
+    def initialize; @docs = {} end
+
+# Fetches the instance of Doc by the given key, the target
+    def getDoc(key); @docs[key] end
+
+# Adds the document by putting it into the underlying cache with the target key.
+    def addDoc(doc)
+        @docs[doc.target] = doc
+    end
+
+# All the ids, namely the targets of all the documents on this instance.
+    def ids; @docs.keys end
+
+# All the instances of the Doc stored on this instance.
+    def all; @docs.values end
+
+=begin rdoc
+Determines if the given document target is defined on this instance.
+* Parameter:
+  * +key+ - the target.
+=end
+    def has?(key) ; @docs.member?(key) end
+
+=begin rdoc
+Reinitializes the instance with no docs.
+=end
+    def clear; @docs[] = {} end
+
+=begin rdoc
+Attempts to consume a Doc from the given source, returns true if succeeded.
+* Parameters:
+  * +source+ - an instance of SourceFile
+  * +target+ - the target, the format of the Doc.
+=end
+    def docConsumed?(source)
+        source.line =~ /^\s*#{DOC}\s+(\w+)$/ ? addDoc(Doc.parse(source, [$1])) : nil
+    end
+
+end # class Docs
+
+end

data/lib/dataMetaDom/enum.rb

@@ -0,0 +1,125 @@
+$:.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
+Worded enum, enumeration expressed as a list of words, each word consisting of alphanumerical symbols only.
+
+For command line details either check the new method's source or the README.rdoc file, the usage section.
+=end
+class Enum < VerDoccable
+=begin rdoc
+The full name of the enum, including namespace if any
+=end
+    attr_reader :name
+
+=begin rdoc
+Attempts to consume/parse an enum from the given source on the given model, returns it if succeeds, returns +nil+ otherwise.
+* Parameters
+  * model - an instance of Model
+  * src - an instance of SourceFile
+=end
+    def self.consumed?(model, src)
+        src.line =~ /^\s*#{ENUM}\s+(\w+)$/ ? model.addEnum(Enum.new(combineNsBase(
+             nsAdjustment(src.namespace, model.options, src), $1)).parse(src)) : nil
+    end
+
+=begin rdoc
+Creates an instance for the given name, initializes internal variables.
+=end
+    def initialize(name); @name = name.to_sym; @map = {}; @format = nil; @counter = -1 end
+
+# Keyword for this entity - +enum+ literally.
+    def sourceKeyWord; ENUM end
+
+=begin rdoc
+Adds a word to the given enum - use judiciously, when building an Enum from memory.
+To parse DataMeta DOM source, use the consumed? method.
+=end
+    def addKey(word)
+        raise "Duplicate value '#{word}' in the enum '#@name'" if (@map.key?(word))
+        @counter += 1
+        @map[word] = @counter # ordinal
+    end
+
+=begin rdoc
+Parses the keys from the current line on the given source, yields one key at a time.
+Used by the parse method.
+* Parameter:
+  * +source+ - the instance of the SourceFile.
+=end
+    def getKeys(source)
+        newVals = source.line.split(/[\s,]+/)
+        puts newVals.join("|") if $DEBUG
+        newVals.each { |v|
+
+            raise "Invalid worded enum '#{v}', must start with #{ID_START}" \
+            ", line ##{source.lineNum}" unless v =~ /^#{ID_START}\w*$/
+            yield v.to_sym
+        }
+    end
+
+=begin rdoc
+Returns the ordinal enum value for the given word.
+=end
+    def ordinal(word); @map[word] end
+
+=begin rdoc
+Opposite to ordinal, for the given ordinal returns the word.
+=end
+    def [](ord); @map.invert[ord] end
+
+=begin rdoc
+All words defined on this enum, sorted alphabetically, *not* by enum order.
+=end
+    def values; @map.keys.sort end
+
+# Raw values, in the order in which they were inserted
+    def rawVals; @map.keys end
+
+=begin
+Determines if this enum is equal or an extention of the other. Extension means, it contains the whole other
+enum plus more members at the tail.
+
+Returns: +:ne+ if neither equal nor extension, +:eq+ if equal, +:xt+ if extension.
+=end
+    def isEqOrXtOf(other)
+       return :eq if @map.keys == other.rawVals
+       other.rawVals.each_index{ |x|
+          return :ne if @map.keys[x] != other.rawVals[x]
+       }
+       :xt
+    end
+
+    # All ordinals on this enum, sorted as integer values.
+    def keys; @map.values.sort end
+
+# Textual representation of this enum - a list of words separated by commma.
+    def to_s; "Enum #{@name}(#{@map.keys.join(', ')}, ver=#{self.ver})" end
+
+=begin rdoc
+Parses the given source into current instance. See the consumed? method for the details.
+* Parameter:
+  * +source+ - the instance of SourceFile.
+=end
+    def parse(source)
+        while (line = source.nextLine)
+
+            case line
+                when /^\s*#{END_KW}\s*$/
+                    self.ver = source.ver unless self.ver
+                    raise "Version missing for the enum #{name}" unless self.ver
+                    self.docs = source.docs.clone if source.docs
+                    source.docs.clear
+                    return self
+                else
+                    getKeys(source) { |k| addKey k }
+            end # case
+        end # while line
+        self
+    end # def parse
+end #class Enum
+
+end

data/lib/dataMetaDom/field.rb

@@ -0,0 +1,182 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'dataMetaDom/docs'
+require 'dataMetaDom/ver'
+
+module DataMetaDom
+
+=begin rdoc
+A field for a Record, with the full name including namespace if any, required flag, DataType and
+default value if any.
+
+For command line details either check the new method's source or the README.rdoc file, the usage section.
+=end
+class Field < VerDoccable
+
+# Aggregation type: Set
+    SET = 'set'
+# Aggregation type: List
+    LIST = 'list'
+# Aggregation type: Deque
+    DEQUE = 'deque'
+# Making a hash/set of 3 members is outright silly, use simple array:
+    AGGRS = [SET, LIST, DEQUE]
+# Map keyword, that's a different kind of aggregator with 2 types
+    MAP = 'map'
+
+=begin rdoc
+The name for this field, full name including namespace if any.
+=end
+    attr_reader :name
+
+=begin rdoc
+Required flag, true for a required field, false for an optional one.
+=end
+    attr_accessor :isRequired
+
+=begin rdoc
+Default value for this field if any.
+=end
+    attr_accessor :default
+
+=begin rdoc
+An instance of DataType for the given field. For a Map -- source type
+=end
+    attr_accessor :dataType
+
+=begin rdoc
+Aggregate indicator - one of the constants: SET, LIST, DEQUE. Note it does not include MAP.
+=end
+    attr_accessor :aggr
+
+=begin rdoc
+Target type for a Map
+=end
+    attr_accessor :trgType
+
+=begin rdoc
++matches+ Regular expression specification if any, for a string
+=end
+    attr_accessor :regex
+
+    class << self # static members of the class
+=begin rdoc
+Parses a new field from the given source, adds to the given record with the source info.
+* Parameters:
+  * +source+ - the instance of SourceFile to parse from
+  * +record+ - the instance of the Record to which the newly parsed Field will be added.
+=end
+    def consume(model, source, record)
+        newField = Field.new.parse(model, source)
+        if record.docs
+            newField.docs = record.docs.clone
+            record.docs.clear
+        end
+        record.addField newField, model, source.snapshot
+    end
+
+=begin rdoc
+Creates a new field with the the given name, type and required flag. Use to build a Model from the code.
+* Parameters:
+  * +name+ - full name for the new field, including namespace if any.
+  * +dataType+ - an instance of DataType, can use reusable types defined on util.rb.
+  * +req+ - the required flag, true for required, see isRequired for details.
+=end
+        def create(name, dataType, req=false)
+            raise ArgumentError, 'Must specify name and type when creating a field from the code' if !name || !dataType
+            result = Field.new name
+            result.dataType = dataType
+            result.isRequired = req
+            result
+        end
+    end
+
+# For readability - determine if the field is aggregated type: LIST, DEQUE, SET
+        def aggr?; defined?(@aggr) && @aggr != nil; end
+# For readability - determine if the field is a map
+        def map?; defined?(@trgType) && @trgType != nil; end
+        def set?; defined?(@aggr) && @aggr == SET; end
+
+
+=begin rdoc
+Another way ot create a Field from the code - a constructor, with the given name if any.
+See the class method create for more details.
+=end
+    def initialize(name=nil)
+        super()
+        @length = nil
+        if name
+            raise ArgumentError, %<Invlalid field name "#{name}", must be alphanum starting with alpha> unless name =~ /^#{ID_START}\w*$/
+            @name = name.to_sym
+        end
+        @default = nil
+    end
+
+=begin rdoc
+Parses this field from the given source.
+* Parameter:
+  * +source+ - an instance of SourceFile
+=end
+    def parse(model, source)
+        @aggr = nil
+        @trgType = nil
+        src = nil
+
+        if source.line =~ /^\s*([#{REQUIRED_PFX}#{OPTIONAL_PFX}])\s*#{MAP}\{\s*([^\s,]+)\s*,\s*([^\}]+)}(.+)/
+           # is it a map{} ?
+           ro, srcSpec, trgSpec, tail = $1, $2, $3, $4
+           src = %|#{ro}#{srcSpec}#{tail ? tail : ''}|
+           @trgType = DataType.parse(source, trgSpec)
+           unless STANDARD_TYPES.member?(@trgType.type)
+               ns, base = DataMetaDom.splitNameSpace(@trgType.type)
+               newNs = nsAdjustment(ns, model.options, source)
+               newNsVer = "#{newNs}.#{base}".to_sym
+               @trgType.type = newNsVer # adjust the type for the map target type too
+           end
+#        elsif source.line =~ /^\s*([#{REQUIRED_PFX}#{OPTIONAL_PFX}])\s*(string)\s+(#{ID_START}\w*)\s*(.+)?$/
+            # is it a string with no length?
+#            req, typeSpec, name, tail = $1, $2, $3, $4
+#            src = %|#{req}#{typeSpec}[0] #{name} #{tail}|
+        else # is it a list, deque or set?
+            AGGRS.each { |a| ## aggregates do not allow matching nor they allow defaults
+               if source.line =~ /^\s*([#{REQUIRED_PFX}#{OPTIONAL_PFX}])\s*#{a}\{([^\}]+)\}(.+)/
+                   @aggr = a
+                   src = %|#{$1}#{$2}#{$3}|
+                   break
+               end
+            }
+        end
+        r = (src ? src : source.line).scan(/^\s*([#{REQUIRED_PFX}#{OPTIONAL_PFX}])\s*(\S+)\s+(#{ID_START}\w*)\s*(.+)?$/)
+        raise "Invalid field spec '#{line}'" unless r
+        req, typeSpec, name, tail = r[0]
+        defaultSpec = tail =~ /(=\S.+)/ ? $1.strip : nil
+        @regex  = tail =~ /#{MATCHES}\s+(.+)/ ? $1.strip : nil # regex can have any symbols, even space, but it starts with a non-space
+        #puts "<#{line}> <#{req}>  <#{typeSpec}> <#{dimSpec}> <#@name>"
+        raise 'Invalid field spec format' if !name || name.empty? || !req || !typeSpec
+        @name = name.to_sym
+        @dataType = DataType.parse(source, typeSpec)
+        @default = defaultSpec[1..-1] if defaultSpec # skip the = sign
+        @isRequired = req.to_sym == REQUIRED_PFX
+        self
+    end
+
+=begin rdoc
+Specification of a default value per the DataMeta DOM syntax or empty string if there is no default value on this field.
+=end
+    def default_spec; @default ? "=#{@default}" : '' end
+# matches specification
+    def matches_spec; @regex ? " matches #{@regex}" : '' end
+
+=begin rdoc
+Required flag as per the DataMeta DOM syntax, either DataMetaDom::REQUIRED_PFX or DataMetaDom::OPTIONAL_PFX,
+the constants defined in the util.rb
+=end
+    def req_spec; @isRequired ? REQUIRED_PFX : OPTIONAL_PFX end
+
+=begin rdoc
+Textual representation of all aspects of the field.
+=end
+    def to_s; "Field #{@name}(#{req_spec}#{@dataType})#{@default ? '=<' + @default + '>' : ''}" end
+end
+
+end

data/lib/dataMetaDom/help.rb

@@ -0,0 +1,41 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+module DataMetaDom
+
+=begin rdoc
+Helper method for runnables.
+
+Prints help and exits placing the purpose of the runnable and the parameters description in proper spots.
+
+Exits with code 0 if errorText is +nil+, exits with code 1 otherwise. Prints errorText with
+proper dressing to the +STDERR+.
+=end
+def help(file, purpose, params, errorText = nil)
+    puts <<HELP
+DataMeta DOM version #{DataMetaDom::VERSION}
+
+#{purpose}. Usage: #{File.basename(file)} #{params}
+
+HELP
+
+$stderr.puts "\nERROR: #{errorText}" if errorText
+exit errorText ? 0 : 1
+end
+
+# Shortcut to help for the Pojo Generator.
+def helpPojoGen(file, errorText=nil)
+    help(file, 'POJO generator', '<DataMeta DOM source> <target directory>', errorText)
+end
+
+# Shortcut to help for the MySQL DDL Generator.
+def helpMySqlDdl(file, errorText=nil)
+    help(file, 'MySQL DDL generator', '<DataMeta DOM source> <target directory>', errorText)
+end
+
+# Shortcut to help for the Oracle DDL Generator.
+def helpOracleDdl(file, errorText=nil)
+    help(file, 'Oracle DDL generator', '<DataMeta DOM source> <target directory>', errorText)
+end
+
+module_function :help, :helpPojoGen, :helpMySqlDdl
+end