cim 0.3.0 → 0.5.0

data/lib/cim/indication.rb

@@ -1,6 +1,20 @@
+#
+# cim/indication.rb - class CIM::Indication
+#
+# A pure-Ruby implementation of the CIM meta model.
+#
+# Copyright (c) 2010 Klaus Kämpf <kkaempf@suse.de>
+#
+# Licensed under the Ruby license
+#
 module CIM
+  #
+  # Indication is a Class whose Instances are sending asynchronous notifications
+  #
   class Indication < Class
+    #
     # true if class has indications (indication provider)
+    #
     def indication?
       true
     end

data/lib/cim/instance.rb

@@ -1,3 +1,19 @@
-class Instance
-  # FIXME
+#
+# cim/instance.rb - class CIM::Instance
+#
+# A pure-Ruby implementation of the CIM meta model.
+#
+# Copyright (c) 2010 Klaus Kämpf <kkaempf@suse.de>
+#
+# Licensed under the Ruby license
+#
+module CIM
+  #
+  # Instance represents a static Class object (defined in a MOF file)
+  #
+  # --
+  # - to be implemented
+  #
+  class Instance < Class
+  end
 end

data/lib/cim/method.rb

@@ -1,15 +1,42 @@
+#
+# cim/method.rb - class CIM::Method
+#
+# A pure-Ruby implementation of the CIM meta model.
+#
+# Copyright (c) 2010 Klaus Kämpf <kkaempf@suse.de>
+#
+# Licensed under the Ruby license
+#
 module CIM
+  #
+  # A Method defines a function member of a Class.
+  #
+  # For data members, see Property.
+  #
   class Method < CIM::ClassFeature
     attr_reader :parameters
+    #
+    # Create a Method with return type (Type) and name (String), optional Qualifiers and parameters (Property)
+    #
+    # call-seq:
+    #   Method.new(:bool, "do_something")
+    #   Method.new(:bool, "do_something", qualifiers)
+    #   Method.new(:bool, "do_something", qualifiers, parameters)
+    #
     def initialize type, name, qualifiers = nil, parameters = nil
       parameters = nil if parameters.kind_of?(::Enumerable) && parameters.empty?
       @parameters = parameters
-      qualifiers = [ qualifiers ] unless qualifiers.kind_of?(Enumerable)
       super type,name,qualifiers
     end
+    #
+    # Makes a Method recognizable in the set of Class features.
+    #
     def method?
       true
     end
+    #
+    # returns a string representation in MOF syntax format
+    #
     def to_s
       p = @parameters.join(", ") if @parameters
       "#{super}(#{p})"

data/lib/cim/named_element.rb

@@ -1,17 +1,65 @@
+#
+# cim/named_element.rb - class CIM::NamedElement
+#
+# A pure-Ruby implementation of the CIM meta model.
+#
+# Copyright (c) 2010 Klaus Kämpf <kkaempf@suse.de>
+#
+# Licensed under the Ruby license
+#
 module CIM
+  #
+  # The NamedElement is a basic building block for the CIM schema, acting as a base class
+  # for Class and Property
+  #
+  # A NamedElement has a name (String) and qualifiers (Qualifiers)
+  #
   class NamedElement
-    attr_reader :name, :characteristics
-    def initialize name
+    attr_reader :name, :qualifiers
+    #
+    # Create a NamedElement with a name and qualifiers
+    #
+    def initialize name, qualifiers = nil
       raise "NamedElement must have a name" unless name
       @name = name.to_s
-      @characteristics = []
+      unless qualifiers.nil?
+	unless qualifiers.is_a?(QualifierSet)
+	  if qualifiers.kind_of?(::Enumerable) && qualifiers.empty?
+	    qualifiers = nil 
+	  else
+	    qualifiers = QualifierSet.new qualifiers
+	  end
+	end
+      end
+      @qualifiers = qualifiers
     end
+    #
+    # Add a Qualifier to the NamedElements qualifiers
+    #
     def << qualifier
-      @characteristics << qualifier
+      @qualifiers << (normalize qualifier)
     end
-    def has? qualifier
-      @characteristics.include? qualifier
+    #
+    # Check if a Qualifier is included 
+    #
+    def include? qualifier
+      @qualifiers.include?(normalize qualifier)
+    end
+    alias includes? include?
+    #
+    # Returns a string representation of the NamedElement
+    #
+    def to_s
+      s = ""
+      s << "[#{@qualifiers.join(', ')}]\n " if @qualifiers
+      s << "#{@name}"
+    end
+    private
+    def normalize qualifier
+      unless qualifier.is_a?(CIM::Qualifier)
+	qualifier = Qualifier.new(qualifier)
+      end
+      qualifier
     end
   end
 end
-

data/lib/cim/property.rb

@@ -1,13 +1,35 @@
+#
+# cim/property.rb - class CIM::Property
+#
+# A pure-Ruby implementation of the CIM meta model.
+#
+# Copyright (c) 2010 Klaus Kämpf <kkaempf@suse.de>
+#
+# Licensed under the Ruby license
+#
 module CIM
+  #
+  # A Property defines a data member of a Class.
+  #
+  # For method members, see Method.
+  #
   class Property < CIM::ClassFeature
     attr_reader :default
-    def initialize type, name, qualifiers=nil, default=nil
+    #
+    # Create a Property with type (Type) and name (String), optional QualifierSet and default value
+    #
+    # call-seq:
+    #   Property.new(:bool, "flag")
+    #   Property.new(:bool, "flag", qualifier_set)
+    #   Property.new(:bool, "flag", qualifier_set, true)
+    #
+    def initialize type, name, qualifier_set=nil, default=nil
       @default = default
-      unless qualifiers.nil? || qualifiers.kind_of?(Enumerable)
-	qualifiers = [ qualifiers ]
-      end
-      super type, name, qualifiers
+      super type, name, qualifier_set
     end
+    #
+    # Makes a Property recognizable in the set of Class features.
+    #
     def property?
       true
     end

data/lib/cim/qualifier.rb

@@ -1,12 +1,37 @@
+#
+# cim/qualifier.rb - class CIM::Qualifier
+#
+# A pure-Ruby implementation of the CIM meta model.
+#
+# Copyright (c) 2010 Klaus Kämpf <kkaempf@suse.de>
+#
+# Licensed under the Ruby license
+#
 module CIM
+  #
+  # A Qualifier is a modifier containing information to describe a Class, an Instance,
+  # a Property, a Method or a parameter.
+  #
+  # Qualifier can be seen as an instance of QualifierDeclaration
+  #
   class Qualifier
     attr_reader :declaration, :value, :flavor
+    #
+    # call-seq:
+    #   Qualifier.new qualifier_declaration
+    #   Qualifier.new qualifier_declaration, value
+    #   Qualifier.new qualifier_declaration, value, flavor
+    #
     def initialize declaration, value = nil, flavor = nil
       raise "Not a CIM::QualifierDeclaration: #{declaration.inspect}" unless declaration.is_a?(CIM::QualifierDeclaration)
       @declaration = declaration
+      # FIXME, check if the value type matches the declaration type
       @value = value
       @flavor = flavor
     end
+    #
+    # Check for equality against Qualifier, QualifierDeclaration, String, or Symbol
+    #
     def == q
       #	puts "CIM::Qualifier ->#{self} == #{q.inspect}"
       case q
@@ -16,15 +41,35 @@ module CIM
 	(@flavor == q.flavor)
       when CIM::QualifierDeclaration
 	@declaration == q  
+      when String
+	@declaration.name.downcase == q.downcase && @value.nil? && @flavor.nil?
       when Symbol
-	q.to_s.downcase == @declaration.name.downcase && @value.nil? && @flavor.nil?
+	self == q.to_s # recycle
       else
 	false
       end
     end
+    #
+    # Name of qualifier (String)
+    #
+    def name
+      @declaration.name
+    end
+    #
+    # Type of qualifier (Type)
+    #
+    def type
+      @declaration.type
+    end
+    #
+    # Name of qualifier as symbol (Symbol)
+    #
     def to_sym
-      @declaration.downcase.to_sym
+      @declaration.to_sym
     end
+    #
+    # returns a string representation in MOF syntax format
+    #
     def to_s
       s = "#{@declaration.name.capitalize}"
       case @value

data/lib/cim/qualifier_declaration.rb

@@ -1,31 +1,77 @@
+#
+# cim/qualifier_declaration.rb - class CIM::QualifierDeclaration
+#
+# A pure-Ruby implementation of the CIM meta model.
+#
+# Copyright (c) 2010 Klaus Kämpf <kkaempf@suse.de>
+#
+# Licensed under the Ruby license
+#
 module CIM
+  #
+  # A Qualifier is a modifier containing information to describe a Class, an Instance,
+  # a Property, a Method or a parameter.
+  #
+  # A qualifier needs to be declared before it can be used.
+  #
+  # Typical qualifiers are e.g.
+  # Description:: (string type) to add a textual information about an element of the CIM model.
+  # Counter,Gauge:: to explain how a numeric value is to be interpreted
+  # Deprecated:: to denote end-of-life for model elements
+  # Min, Max:: (MinLen, MaxLen, MinValue, MaxValue) limits
+  #
+  # A QualifierDeclaration declares a qualifier by
+  # name:: (String)
+  # type:: (Type) (defaults to bool)
+  # default value:: (Variant) (defaults to false)
+  # scopes:: (QualifierScopes) (where the qualifier can be used)
+  # flavor:: (QualifierFlavors) (how the qualifier is applied)
+  #
+  #
   class QualifierDeclaration < NamedElement
 
-    attr_reader :type, :default, :scope, :flavor
-
-    def initialize name, type = :bool, default = false, scope = nil, flavor = nil
+    attr_reader :type, :default, :scopes, :flavors
+    #
+    # Create a new QualifierDeclaration
+    #
+    def initialize name, type = :bool, default = false, scopes = nil, flavors = nil
       @type = (type.kind_of? Type) ? type : Type.new(type)
       @default = (default.nil? || default.is_a?(CIM::Variant)) ? default : CIM::Variant.new(@type, default)
-      @scope = scope
-      @flavor = flavor
+      @scopes = scopes
+      @flavors = flavors
       super name
     end
-      
+    #
+    # Test for equality by comparing name and type
+    #
     def == q
-      #	puts "#{@name}:#{@type} == #{q.name}:#{q.type}"
-      (@name.downcase == q.name.downcase) &&
-        (@type.nil? || q.type.nil? || (@type == q.type))
+#      puts "QualifierDeclaration(#{@name}:#{@type}) == #{q.class}(#{q})"
+      case q
+      when QualifierDeclaration
+	(@name.downcase == q.name.downcase) &&
+          (@type.nil? || q.type.nil? || (@type == q.type))
+      when String
+	@name.downcase == q.downcase
+      when Symbol
+	@name.downcase == q.to_s.downcase
+      else
+	false
+      end
     end
-
+    #
+    # return a Symbol representation of the qualifier name
+    #
     def to_sym
       @name.downcase.to_sym
     end
-
+    #
+    # returns a String representation in MOF syntax format
+    #
     def to_s
       s = "Qualifier #{@name} : #{@type}"
       s << " = #{@default}" if @default
-      s << ",\n\t#{@scope}" if @scope
-      s << ",\n\t#{@flavor}" if @flavor
+      s << ",\n\t#{@scopes}" if @scopes
+      s << ",\n\t#{@flavors}" if @flavors
       s
     end
   end

data/lib/cim/qualifier_flavors.rb

@@ -1,5 +1,16 @@
+#
+# cim/qualifier_flavor.rb - class CIM::QualifierFlavors, class CIM::QualifierFlavorError
+#
+# A pure-Ruby implementation of the CIM meta model.
+#
+# Copyright (c) 2010 Klaus Kämpf <kkaempf@suse.de>
+#
+# Licensed under the Ruby license
+#
 module CIM
-
+  #
+  # QualifierFlavorError is raised during QualifierFlavors creation
+  #
   class QualifierFlavorError < ArgumentError
     def initialize flavor
       @flavor = flavor
@@ -8,26 +19,89 @@ module CIM
       "#{@flavor} is not a valid qualifier flavor"
     end
   end
-
+  #
+  # Qualifier flavors are a fixed set. QualifierFlavors tracks which flavors are enabled for a specific QualifierDeclaration.
+  #
+  # Allowed flavors are
+  #
+  # amended:: [wmi] Marks a qualifier value for localization (default: false)
+  # enableoverride:: The qualifier can be overriden (in a subclass) (default: true)
+  # disableoverride:: The qualifier can not be overriden (default: false)
+  # restricted:: The qualifier only applies to the class in which it is declared (default: false)
+  # toinstance:: [wmi]
+  # tosubclass:: The qualifier is inherited by any subclass (default: true)
+  # translatable:: Marks a qualifier value for localization (default: false)
+  #
   class QualifierFlavors
     FLAVORS = [:amended, :enableoverride, :disableoverride, :restricted, :toinstance, :tosubclass, :translatable]
     attr_reader :flavors
-    def initialize flavor
+    #
+    # Create QualifierFlavors with an initial flavor. More flavors can be added through the << method.
+    #
+    # call-seq:
+    #   QualifierFlavors.new :tosubclass => qualifier_flavors
+    #   QualifierFlavors.new "tosubclass" => qualifier_flavors
+    #   QualifierFlavors.new "ToSubClass" => qualifier_flavors
+    #    
+    # The flavor can be named as a string or a symbol.
+    #
+    def initialize *flavors
       @flavors = []
-      self << flavor
+      flavors.flatten.each do |flavor|
+	self << flavor
+      end
     end
+    #
+    # Add a flavor to the set
+    # The flavor can be named as a string or a symbol.
+    #
+    # call-seq:
+    #   qualifier_flavors << :tosubclass
+    #   qualifier_flavors << "tosubclass"
+    #   qualifier_flavors << "ToSubClass"
+    #
+    # Raises QualifierFlavorError if its not an allowed flavor
+    #
     def << flavor
-      flavor.downcase! if flavor.kind_of? String
-      f = flavor.to_sym
-      raise QualifierFlavorError.new("#{flavor}") unless FLAVORS.include? f
-      @flavors << f
+      @flavors << normalize(flavor)
       self
     end
-    def to_sym
-      @flavors.first
+    #
+    # Number of flavors in the set
+    #
+    def size
+      @flavors.size
+    end
+    #
+    # Check if a specific flavor is included in the set
+    #
+    # call-seq:
+    #   qualifier_flavors.include? :tosubclass
+    #   qualifier_flavors.include? "tosubclass"
+    #   qualifier_flavors.include? "ToSubClass"
+    #
+    # Raises QualifierFlavorError if its not an allowed flavor
+    #
+    def include? flavor
+      @flavors.include?(normalize flavor)
     end
+    alias includes? include?
+    #
+    # returns a string representation in MOF syntax format
+    #
     def to_s
       "Flavor(#{@flavors.join(', ')})"
     end
+    private
+    #
+    # Normalize a flavor passed as string or symbol
+    # Raises QualifierFlavorError if its not an allowed flavor
+    #
+    def normalize flavor
+      flavor.downcase! if flavor.kind_of? String
+      f = flavor.to_sym
+      raise QualifierFlavorError.new("#{flavor}") unless FLAVORS.include? f
+      f
+    end
   end
 end