origen_testers 0.51.2 → 0.51.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1ba41af6b65ac674916979e0732f2ec945cd3871a9764ed26eed0c1fc9ad9df
-  data.tar.gz: 63be076e3b7dfc1dfa525b420b233b8a79eb33f6c86a06852f0069f01cfd7668
+  metadata.gz: 3762e544f419c1c77e9f1d670c7203cd44e9ad6fef0246463f62c77e8592be92
+  data.tar.gz: 3c2e4679fae95dbb6f9976be317bbcf6c9fe3f8eff113d40fbdafe68cea06973
 SHA512:
-  metadata.gz: 13f984fad6402b0749eaa3029aa8ccecf3870f6e534c553884a6dc6de42a11b4383e268378ec84968b7e71ce2ed75b800fe9c8f7128f37c32e3b1b78a7d70ec7
-  data.tar.gz: a4b421dfd78750be92b44112ca13506a6f281a98ee9f84faa3ccf49b08a4e1f32fecfe979aa7f2eafb4f66a1875a66ad092949d39bd7638ccdbfb6ba812308a6
+  metadata.gz: 563af43372ac16a7159e4f1ca6d8aa8aed2fc630dc9224f477cb427332f76ec9ada304428caa15695cf48e7923fa3243154de71bc12b737e170d5370946a44f3
+  data.tar.gz: 2674ab9dda1e9b8e6a7816d5cab6add7eb9dc44b037ac2b12ef46a5d2473324632034faf88cf34998d501140eda7545a7ac19a8e0710ffb062c5523f93bdff49

data/config/commands.rb

@@ -175,7 +175,7 @@ when "tags"
 # Run the unit tests  
 when "specs"
   require "rspec"
-  exit RSpec::Core::Runner.run(['spec'])
+  exit RSpec::Core::Runner.run($ARGV.empty? ? ['spec'] : $ARGV)
 
 # Run the example-based (diff) tests
 when "examples", "test"

data/config/version.rb

@@ -1,7 +1,7 @@
 module OrigenTesters
   MAJOR = 0
   MINOR = 51
-  BUGFIX = 2
+  BUGFIX = 3
   DEV = nil
   VERSION = [MAJOR, MINOR, BUGFIX].join(".") + (DEV ? ".pre#{DEV}" : '')
 end

data/lib/origen_testers/charz/profile.rb

@@ -19,7 +19,7 @@ module OrigenTesters
       #   @return [Array] list of charz routines to be called under this profile
       # @!attribute charz_only
       #   @return [Boolean] indicates if the point tests should or shouldn't be added to the flow
-      attr_accessor :id, :name, :placement, :on_result, :enables, :flags, :routines, :charz_only, :and_enables, :and_flags
+      attr_accessor :id, :name, :placement, :on_result, :enables, :flags, :routines, :charz_only, :force_keep_parent, :and_enables, :and_flags
 
       def initialize(id, options, &block)
         @id = id
@@ -30,6 +30,7 @@ module OrigenTesters
         @placement ||= :inline
         @defined_routines = options.delete(:defined_routines)
         attrs_ok?
+        massage_gates
       end
 
       def attrs_ok?
@@ -91,6 +92,20 @@ module OrigenTesters
         end
       end
 
+      # convert hash gates to set convert their routines to type array if not already
+      def massage_gates
+        if @enables.is_a?(Hash)
+          @enables = {}.tap do |new_h|
+            @enables.each { |gates, routines| new_h[gates] = [routines].flatten }
+          end
+        end
+        if @flags.is_a?(Hash)
+          @flags = {}.tap do |new_h|
+            @flags.each { |gates, routines| new_h[gates] = [routines].flatten }
+          end
+        end
+      end
+
       def gate_check(gates, gate_type)
         case gates
         when Symbol, String

data/lib/origen_testers/charz/session.rb

@@ -1,30 +1,59 @@
 module OrigenTesters
   module Charz
     # A charz session
-    # contains the final combination of charz object (routines/profiles) and user options to determine how and what charz tests should be created
+    # contains a collection of the final combinations of charz object (routines/profiles) and user options to determine how and what charz tests should be created
     # the session should be checked in your interface to determine the current status and can be queried to make charz generation decisions
-    class Session < Profile
+    class Session
+      # @!attribute id
+      #   @return [Symbol] current session ID. Will be a concatenation of the instances' ids
+      # @!attribute instances
+      #   @return [Array] list of active instances (which are essentially Profiles)
+      # @!attribute current_instance
+      #   @return [Profile] Set when looping over instances via #loop_instances. The interface can query the charz_instance for more detailed info
+      # @!attribute valid
+      #   @return [Boolean] whether or not the current session setup is valid, if not then charz wont be created
       # @!attribute defaults
       #   @return [Hash] list of values to instantiate the inherited attributes from Profile with if not altered by the session update
-      attr_accessor :defaults
+      # @!attribute stored_instance
+      #   @return [Profile] This is to store the instance that the interface is storing. Its to support a legacy usecase of querying the session for instance level info during EOF
+      attr_accessor :id, :instances, :current_instance, :valid, :defaults, :stored_instance
 
       def initialize(options = {})
-        @id = :current_charz_session
+        @id = :empty_session
+        @instances = []
+        @current_instance = nil
+        @stored_instance = nil
         @active = false
         @valid = false
-        if options[:defaults]
-          @defaults = options[:defaults]
-        else
-          @defaults = {
-            placement:   :inline,
-            on_result:   nil,
-            enables:     nil,
-            flags:       nil,
-            enables_and: nil,
-            name:        'charz',
-            charz_only:  false
-          }
-        end
+        @defaults = {
+          placement:         :inline,
+          routines:          [],
+          on_result:         nil,
+          enables:           nil,
+          flags:             nil,
+          enables_and:       false,
+          and_enables:       false,
+          flags_and:         false,
+          and_flags:         false,
+          name:              'charz',
+          charz_only:        false,
+          force_keep_parent: false
+        }.merge((options[:defaults] || {}))
+      end
+
+      def on_result?
+        instances.any? { |charz_instance| !charz_instance.on_result.nil? }
+      end
+
+      def charz_only?
+        any_only = instances.any?(&:charz_only)
+        any_force = instances.any?(&:force_keep_parent)
+        !any_force && any_only && !on_result?
+      end
+
+      def charz_only
+        Origen.log.deprecate '#charz_only has been deprecated in favor of #charz_only? It is no longer an attribute, instead a runtime calculation.'
+        charz_only?
       end
 
       # Pauses the current session's activity while maintaining everthing else about the sessions state
@@ -32,6 +61,11 @@ module OrigenTesters
         @active = false
       end
 
+      def active?
+        !!@active
+      end
+      alias_method :active, :active?
+
       # Resume activity, if the session is valid
       def resume
         if @valid
@@ -39,72 +73,103 @@ module OrigenTesters
         end
       end
 
-      # Takes a Routine or Profile, and queries it to setup the session's attributes
+      def current_instance
+        instance = @current_instance || instances.first
+        if instance.nil? && @stored_instance
+          Origen.log.deprecate '@current_instance had to source @stored_instance. This likely means charz_session.<some_attr> is being queried when the newer charz_instance.<some_attr> should be instead'
+          instance = @stored_instance
+        end
+        instance
+      end
+
+      def loop_instances
+        instances.each do |charz_instance|
+          @current_instance = charz_instance
+          yield
+          @current_instance = nil
+        end
+      end
+
+      # Takes a CharzTuple and queries it to setup an instance's attributes
       # the attributes values can be set from 3 different sources, in order of priority (first is most important):
       #   - options
-      #   - charz object
+      #   - charz object (Profile or Routine)
       #   - defaults
       #
       # If the resulting session is invalid, @valid will turn false. Otherwise, the session becomes active
-      def update(charz_obj, options)
+      def update(charz_tuples)
+        @instances = []
         @valid = false
-        if charz_obj.nil?
+        if charz_tuples.nil? || charz_tuples.empty?
           @active = false
           @valid = false
+          @current_instance = nil
           return @valid
         end
-        @defined_routines = options.delete(:defined_routines)
+        @defined_routines = charz_tuples.map(&:defined_routines).flatten.uniq.compact
 
-        if charz_obj.and_flags
-          @and_flags = charz_obj.and_flags
-        else
-          @and_flags = false
-        end
-        if charz_obj.and_enables
-          @and_enables = charz_obj.and_enables
-        else
-          @and_enables = false
+        charz_tuples.each do |charz_tuple|
+          profile_options = assign_by_priority(charz_tuple)
+          @instances << Profile.new(charz_tuple.obj.id, profile_options.merge(defined_routines: @defined_routines))
         end
-        assign_by_priority(:placement, charz_obj, options)
-        assign_by_priority(:on_result, charz_obj, options)
-        assign_by_priority(:enables, charz_obj, options)
-        assign_by_priority(:flags, charz_obj, options)
-        assign_by_priority(:routines, charz_obj, options)
-        assign_by_priority(:name, charz_obj, options)
-        assign_by_priority(:charz_only, charz_obj, options)
-        attrs_ok?
-        massage_gates
+        @id = instances.map(&:id).join('_').to_sym
         @active = true
         @valid = true
       end
 
       private
 
-      # convert hash gates to set convert their routines to type array if not already
-      def massage_gates
-        if @enables.is_a?(Hash)
-          @enables = {}.tap do |new_h|
-            @enables.each { |gates, routines| new_h[gates] = [routines].flatten }
-          end
-        end
-        if @flags.is_a?(Hash)
-          @flags = {}.tap do |new_h|
-            @flags.each { |gates, routines| new_h[gates] = [routines].flatten }
+      def assign_by_priority(charz_tuple)
+        options = charz_tuple.options
+        charz_obj = charz_tuple.obj
+        instance_options = {}
+        get_instance_setting_keys(charz_obj).each do |ivar|
+          if options.keys.include?(ivar)
+            instance_options[ivar] = options[ivar]
+          elsif charz_obj.send(ivar)
+            instance_options[ivar] = charz_obj.send(ivar)
+          elsif @defaults.keys.include?(ivar)
+            instance_options[ivar] = @defaults[ivar]
+          else
+            Origen.log.error "Charz Session: No value could be determined for #{ivar}"
+            fail
           end
         end
+        instance_options
       end
 
-      # see initialize
-      def assign_by_priority(ivar, charz_obj, options)
-        if options.keys.include?(ivar)
-          instance_variable_set("@#{ivar}", options[ivar])
-        elsif charz_obj.send(ivar)
-          instance_variable_set("@#{ivar}", charz_obj.send(ivar))
-        elsif @defaults.keys.include?(ivar)
-          instance_variable_set("@#{ivar}", @defaults[ivar])
+      def get_instance_setting_keys(charz_obj)
+        keys = charz_obj.instance_variables | @defaults.keys
+        keys.map! { |k| k.to_s.sub('@', '').to_sym }
+        keys -= [:id]
+        keys
+      end
+
+      def method_missing(method, *args, &block)
+        deprecated_methods = [
+          :name,
+          :placement,
+          :on_result,
+          :enables,
+          :flags,
+          :routines,
+          :and_enables,
+          :enables_and,
+          :and_flags,
+          :flags_and,
+          :charz_only,
+          :force_keep_parent
+        ]
+        if deprecated_methods.include?(method.to_sym) || deprecated_methods.include?(method.to_s[0..-2].to_sym)
+          Origen.log.deprecate "charz_session.#{method} has been deprecated. Please query charz_instance.#{method} instead."
+          if current_instance.nil? && !valid
+            Origen.log.error "blocked call of 'charz_session.#{method}'!"
+            Origen.log.warn 'The charz instance attributes are no longer accessible when the session is invalid!'
+          else
+            current_instance.send(method, *args, &block)
+          end
         else
-          Origen.log.error "Charz Session: No value could be determined for #{ivar}"
-          fail
+          super
         end
       end
     end

data/lib/origen_testers/charz.rb

@@ -3,6 +3,7 @@ Dir.glob("#{File.dirname(__FILE__)}/charz/**/*.rb").sort.each do |file|
 end
 module OrigenTesters
   module Charz
+    CharzTuple = Struct.new(:obj, :options, :defined_routines, keyword_init: true)
     # @!attribute charz_stack
     #   @return [Array] FILO queue of charz session defining data
     # @!attribute charz_routines
@@ -11,13 +12,15 @@ module OrigenTesters
     #   @return [Hash] user defined charz profiles
     # @!attribute charz_session
     #   @return [Session] current charz session, based on data in the top of the charz_stack
+    # @!attribute charz_instance
+    #   @return [Session] current charz instance of the session. If there is not a current instance, will return the first instance of the session instance stack
     # @!attribute eof_charz_tests
     #   @return [Array] charz tests to be added at the end of the flow
     # @!attribute skip_group_eof_charz_tests
     #   @return [Boolean] whether or not to wrap eof charz tests in a group
     # @!attribute eof_charz_tests_group_name
     #   @return [String, Symbol] group name to be used to for eof charz tests
-    attr_accessor :charz_stack, :charz_routines, :charz_profiles, :charz_session, :eof_charz_tests, :skip_group_eof_charz_tests, :eof_charz_tests_group_name
+    attr_accessor :charz_stack, :charz_routines, :charz_profiles, :charz_session, :charz_instance, :eof_charz_tests, :skip_group_eof_charz_tests, :eof_charz_tests_group_name
 
     def charz_stack
       @charz_stack ||= []
@@ -35,6 +38,21 @@ module OrigenTesters
       @charz_session ||= Session.new
     end
 
+    # If there is a current instance present, that should always be used. However when running EOF charz,
+    # the instance to be used is no longer set, so instead of referencing the session, use the one that we've
+    # stored already
+    def charz_instance
+      unless charz_session.current_instance.nil?
+        set_charz_instance(charz_session.current_instance)
+      end
+      @charz_instance
+    end
+
+    def set_charz_instance(instance)
+      @charz_instance = instance
+      charz_session.stored_instance = instance
+    end
+
     def eof_charz_tests
       @eof_charz_tests ||= []
     end
@@ -106,12 +124,12 @@ module OrigenTesters
 
     # Queries the current charz session to see if its active, indicating point tests should be generating charz tests
     def charz_active?
-      charz_session.active
+      charz_session.active?
     end
 
     # Queries the current charz session to see if point tests should skip generation, only adding the resulting charz test
     def charz_only?
-      charz_active? && charz_session.charz_only
+      charz_active? && charz_session.charz_only?
     end
 
     # Pauses the current charz session, preventing point tests from generating charz tests even if the session is valid
@@ -129,10 +147,12 @@ module OrigenTesters
     # if not, the session will become inactive
     def charz_off
       charz_stack.pop
+      unless charz_session.update(charz_stack.last) || charz_stack.empty?
+        Origen.log.error 'charz_on failed to create a valid charz session'
+        fail
+      end
       if charz_stack.empty?
-        update_charz_session(nil)
-      else
-        update_charz_session(*charz_stack.last)
+        set_charz_instance(nil)
       end
     end
 
@@ -145,36 +165,61 @@ module OrigenTesters
     # @param [Hash] options charz_on options
     # @option options [Symbol] :type (:profile) whether the charz_id refers to a charz profile or routine
     def charz_on(charz_id, options = {})
-      options = {
-        type: :profile
-      }.merge(options)
-      case options[:type]
-      when :profile
-        charz_obj = charz_profiles[charz_id]
-      when :routine
-        if charz_id.is_a?(Array)
-          charz_obj = charz_routines[charz_id.first]
-          options[:routines] = charz_id
-        else
-          charz_obj = charz_routines[charz_id]
-          options[:routines] = [charz_id]
-        end
-      else
-        Origen.log.error "Unknown charz object type #{options[:type]}, valid types: :profile, :routine"
+      charz_stack.push([get_charz_tuple(charz_id, options)])
+      unless charz_session.update(charz_stack.last)
+        Origen.log.error 'charz_on failed to create a valid charz session'
         fail
       end
-      if charz_obj.nil?
-        Origen.log.error "No #{options[:type]} found for charz_id: #{charz_id}"
-        fail
+      if block_given?
+        yield
+        charz_off
       end
-      charz_stack.push([charz_obj, options])
-      unless update_charz_session(*charz_stack.last)
+    end
+
+    # Pushes a charz object (either a profile or a routine) onto the current sessions instance stack, along with any optional updates to modify that instance.
+    # This will result in subsequent charzable point tests in being processed against each of the current instances. In other words, this new push will not
+    # take priority over the current stack head, but instead append to it.
+    # Once pushed, the charz_session will attempt to update itself with the new data, failing if the resulting session is invalid
+    #
+    # If a block is passed, yield the block of tests to enable charz for those tests, then disable charz with a charz_off_truncate call
+    #
+    # @param [Symbol] charz_id either a routine or profile id. Method fails if the id can't be found in @charz_routines or @charz_profiles
+    # @param [Hash] options charz_on options
+    # @option options [Symbol] :type (:profile) whether the charz_id refers to a charz profile or routine
+    def charz_on_append(charz_id, options = {})
+      charz_tuple = get_charz_tuple(charz_id, options)
+
+      # take the current session and append to its instance stack
+      session = charz_stack.pop || []
+      session.push(charz_tuple)
+      charz_stack.push(session)
+
+      unless charz_session.update(charz_stack.last)
         Origen.log.error 'charz_on failed to create a valid charz session'
         fail
       end
       if block_given?
         yield
-        charz_off
+        charz_off_truncate
+      end
+    end
+
+    # Removes the current sessions last instance. If the session only had one instance, this is functionally the same as charz_off
+    # If charz data is still on the stack afterward, the session will update to reflect the new data
+    # if not, the session will become inactive
+    def charz_off_truncate
+      session = charz_stack.pop || []
+      session.pop
+      unless session.empty?
+        charz_stack.push(session)
+      end
+
+      unless charz_session.update(charz_stack.last) || charz_stack.empty?
+        Origen.log.error 'charz_on failed to create a valid charz session'
+        fail
+      end
+      if charz_stack.empty?
+        set_charz_instance(nil)
       end
     end
 
@@ -196,8 +241,12 @@ module OrigenTesters
       end
       unless options[:id]
         if charz_active?
-          if charz_session.on_result
-            options[:id] = "#{parent_test_name}_charz_#{charz_session.name}".to_sym
+          if charz_session.on_result?
+            md5_id = Digest::MD5.new
+            md5_id << parent_test_name.to_s
+            md5_id << options.to_s
+            md5_id << charz_session.id.to_s
+            options[:id] = "auto_charz_id_#{md5_id}".to_sym
           end
         end
       end
@@ -206,7 +255,7 @@ module OrigenTesters
     # Called after the relevant point test has been inserted into the flow
     # Takes the options used to build the previous point test as well as insert_charz_test specific options to then
     # drill down to the point of the flow where the charz test would go, at which point control is handed back to the user's
-    # interface to handle creating and inserting the test
+    # interface to handle creating and inserting the test. This will occur for each instance in the current session's instance stack
     #
     # By default, this method will handle:
     #   - the placement of the test (inline aka right after the point test, end of flow, or other)
@@ -224,25 +273,27 @@ module OrigenTesters
           current_id = options.delete(:id)
           options[:last_test_id] ||= current_id
         end
-        case charz_session.placement
-        when :inline
-          create_charz_group(options, &block)
-        when :eof
-          # collect the current session and options into a proc, stored in eof_charz_tests to be called later
-          current_session = charz_session.clone
-          eof_charz_tests << proc do
-            @charz_session = current_session
+        charz_session.loop_instances do
+          case charz_instance.placement
+          when :inline
             create_charz_group(options, &block)
-          end
-        else
-          # inline is the default behavior, and eof (end of flow) has built in support.
-          if respond_to?(:"create_#{charz_session.placement}_charz_tests")
-            send(:"create_#{charz_session.placement}_charz_tests", options, &block)
-          elsif respond_to?(:"insert_#{charz_session.placement}_charz_tests")
-            send(:"insert_#{charz_session.placement}_charz_tests", options, &block)
+          when :eof
+            # collect the current instance and options into a proc, stored in eof_charz_tests to be called later
+            current_instance = charz_instance.clone
+            eof_charz_tests << proc do
+              set_charz_instance(current_instance)
+              create_charz_group(options, &block)
+            end
           else
-            Origen.log.error "No handling specified for #{charz_session.placement} placement charz tests"
-            fail
+            # inline is the default behavior, and eof (end of flow) has built in support.
+            if respond_to?(:"create_#{charz_instance.placement}_charz_tests")
+              send(:"create_#{charz_instance.placement}_charz_tests", options, &block)
+            elsif respond_to?(:"insert_#{charz_instance.placement}_charz_tests")
+              send(:"insert_#{charz_instance.placement}_charz_tests", options, &block)
+            else
+              Origen.log.error "No handling specified for #{charz_instance.placement} placement charz tests"
+              fail
+            end
           end
         end
       end
@@ -265,9 +316,29 @@ module OrigenTesters
 
     private
 
-    # called by charz_on, updates the current session, and passes the available routines in for validity checks
-    def update_charz_session(charz_obj, options = {})
-      charz_session.update(charz_obj, options.merge(defined_routines: charz_routines.ids))
+    # helper method for charz_on and charz_on_append
+    def get_charz_tuple(charz_id, options)
+      options[:type] ||= :profile
+      case options[:type]
+      when :profile
+        charz_obj = charz_profiles[charz_id]
+      when :routine
+        if charz_id.is_a?(Array)
+          charz_obj = charz_routines[charz_id.first]
+          options[:routines] = charz_id
+        else
+          charz_obj = charz_routines[charz_id]
+          options[:routines] = [charz_id]
+        end
+      else
+        Origen.log.error "Unknown charz object type #{options[:type]}, valid types: :profile, :routine"
+        fail
+      end
+      if charz_obj.nil?
+        Origen.log.error "No #{options[:type]} found for charz_id: #{charz_id}"
+        fail
+      end
+      CharzTuple.new(obj: charz_obj, options: options, defined_routines: charz_routines.ids)
     end
 
     # called by insert_charz_tests
@@ -280,7 +351,7 @@ module OrigenTesters
       if options[:skip_group]
         process_on_result(options, &block)
       else
-        group_name = options[:group_name] || "#{options[:parent_test_name]} charz #{charz_session.name}"
+        group_name = options[:group_name] || "#{options[:parent_test_name]} charz #{charz_instance.name}"
         group group_name.to_sym do
           process_on_result(options, &block)
         end
@@ -298,8 +369,8 @@ module OrigenTesters
     #
     # @see set_conditional_charz_id
     def process_on_result(options, &block)
-      if charz_session.on_result
-        case charz_session.on_result
+      if charz_instance.on_result
+        case charz_instance.on_result
         when :on_fail, :fail, :failed
           last_test_id = options[:last_test_id] || @last_test_id
           if_failed last_test_id do
@@ -311,10 +382,10 @@ module OrigenTesters
             process_gates(options, &block)
           end
         else
-          if respond_to?(:"process_#{charz_session.placement}_charz_tests")
-            send(:"process_#{charz_session.on_result}_charz_tests", options, &block)
+          if respond_to?(:"process_#{charz_instance.placement}_charz_tests")
+            send(:"process_#{charz_instance.on_result}_charz_tests", options, &block)
           else
-            Origen.log.error "No handling specified for result #{charz_session.on_result} charz tests"
+            Origen.log.error "No handling specified for result #{charz_instance.on_result} charz tests"
             fail
           end
         end
@@ -338,29 +409,29 @@ module OrigenTesters
     # Pass an "and_if_true" variable for enables and flags? And use that to to decide what to do? Then we don't need 4.
     # But the hash has to be structured a different way for the enable_and (routine is key, enables is value.)
     def process_gates(options, &block)
-      if options[:skip_gates] || !(charz_session.enables || charz_session.flags)
-        charz_session.routines.each do |routine|
+      if options[:skip_gates] || !(charz_instance.enables || charz_instance.flags)
+        charz_instance.routines.each do |routine|
           block.call(options.merge(current_routine: routine))
         end
       else
-        if charz_session.and_enables
-          if charz_session.flags
+        if charz_instance.and_enables
+          if charz_instance.flags
             # Wrap all tests in flag, wrap some tests in anded enables.
-            ungated_routines = charz_session.routines - charz_session.enables.keys
+            ungated_routines = charz_instance.routines - charz_instance.enables.keys
             ungated_routines.each do |routine|
-              if_flag charz_session.flags do
+              if_flag charz_instance.flags do
                 block.call(options.merge(current_routine: routine))
               end
             end
-            gated_routines = charz_session.routines - ungated_routines
+            gated_routines = charz_instance.routines - ungated_routines
             # Build the proc which contains the nested if statements for each routine so they are anded.
             gated_routines.each do |routine|
               my_proc = -> do
-                if_flag charz_session.flags do
+                if_flag charz_instance.flags do
                   block.call(options.merge(current_routine: routine))
                 end
               end
-              charz_session.enables[routine].inject(my_proc) do |my_block, enable|
+              charz_instance.enables[routine].inject(my_proc) do |my_block, enable|
                 lambda do
                   if_enable :"#{enable}" do
                     my_block.call
@@ -369,15 +440,15 @@ module OrigenTesters
               end.call
             end
           else
-            ungated_routines = charz_session.routines - charz_session.enables.keys
+            ungated_routines = charz_instance.routines - charz_instance.enables.keys
             ungated_routines.each do |routine|
               block.call(options.merge(current_routine: routine))
             end
             # Build the proc which contains the nested if statements for each routine so they are anded.
-            gated_routines = charz_session.routines - ungated_routines
+            gated_routines = charz_instance.routines - ungated_routines
             gated_routines.each do |routine|
               my_proc = -> { block.call(options.merge(current_routine: routine)) }
-              charz_session.enables[routine].inject(my_proc) do |my_block, enable|
+              charz_instance.enables[routine].inject(my_proc) do |my_block, enable|
                 lambda do
                   if_enable :"#{enable}" do
                     my_block.call
@@ -386,24 +457,24 @@ module OrigenTesters
               end.call
             end
           end
-        elsif charz_session.and_flags
-          if charz_session.enables
+        elsif charz_instance.and_flags
+          if charz_instance.enables
             # Wrap all tests in enable, some tests in anded flags.
-            ungated_routines = charz_session.routines - charz_session.flags.keys
+            ungated_routines = charz_instance.routines - charz_instance.flags.keys
             ungated_routines.each do |routine|
-              if_enable charz_session.enables do
+              if_enable charz_instance.enables do
                 block.call(options.merge(current_routine: routine))
               end
             end
             # Build the proc which contains the nested if statemements for each routine so they are anded.
-            gated_routines = charz_session.routines - ungated_routines
+            gated_routines = charz_instance.routines - ungated_routines
             gated_routines.each do |routine|
               my_proc = -> do
-                if_enable charz_session.enables do
+                if_enable charz_instance.enables do
                   block.call(options.merge(current_routine: routine))
                 end
               end
-              charz_session.flags[routine].inject(my_proc) do |my_block, flag|
+              charz_instance.flags[routine].inject(my_proc) do |my_block, flag|
                 lambda do
                   if_flag :"#{flag}" do
                     my_block.call
@@ -412,15 +483,15 @@ module OrigenTesters
               end.call
             end
           else
-            ungated_routines = charz_session.routines - charz_session.flags.keys
+            ungated_routines = charz_instance.routines - charz_instance.flags.keys
             ungated_routines.each do |routine|
               block.call(options.merge(current_routine: routine))
             end
             # Build the proc which contains the nested if statemements for each routine so they are anded.
-            gated_routines = charz_session.routines - ungated_routines
+            gated_routines = charz_instance.routines - ungated_routines
             gated_routines.each do |routine|
               my_proc = -> { block.call(options.merge(current_routine: routine)) }
-              charz_session.flags[routine].inject(my_proc) do |my_block, flag|
+              charz_instance.flags[routine].inject(my_proc) do |my_block, flag|
                 lambda do
                   if_flag :"#{flag}" do
                     my_block.call
@@ -429,28 +500,28 @@ module OrigenTesters
               end.call
             end
           end
-        elsif charz_session.enables && charz_session.flags
-          if charz_session.enables.is_a?(Hash) && !charz_session.flags.is_a?(Hash)
+        elsif charz_instance.enables && charz_instance.flags
+          if charz_instance.enables.is_a?(Hash) && !charz_instance.flags.is_a?(Hash)
             # wrap all tests in flags, wrap specific tests in enables
-            if_flag charz_session.flags do
-              insert_hash_gates(options, charz_session.enables, :if_enable, &block)
+            if_flag charz_instance.flags do
+              insert_hash_gates(options, charz_instance.enables, :if_enable, &block)
             end
-          elsif !charz_session.enables.is_a?(Hash) && charz_session.flags.is_a?(Hash)
+          elsif !charz_instance.enables.is_a?(Hash) && charz_instance.flags.is_a?(Hash)
             # wrap all tests in enables, wrap specific tests in flags
-            if_enable charz_session.enables do
-              insert_hash_gates(options, charz_session.flags, :if_flag, &block)
+            if_enable charz_instance.enables do
+              insert_hash_gates(options, charz_instance.flags, :if_flag, &block)
             end
-          elsif charz_session.enables.is_a?(Hash) && charz_session.flags.is_a?(Hash)
+          elsif charz_instance.enables.is_a?(Hash) && charz_instance.flags.is_a?(Hash)
             # first insert the tests that are not tied to an enable or flag gate
-            ungated_routines = charz_session.routines - (charz_session.enables.values.flatten | charz_session.flags.values.flatten)
+            ungated_routines = charz_instance.routines - (charz_instance.enables.values.flatten | charz_instance.flags.values.flatten)
             ungated_routines.each do |routine|
               block.call(options.merge(current_routine: routine))
             end
             # wrap tests in an enable gate, flag gate, or both
-            gated_routines = charz_session.routines - ungated_routines
+            gated_routines = charz_instance.routines - ungated_routines
             gated_routines.each do |routine|
-              enable = charz_session.enables.find { |gates, routines| routines.include?(routine) }&.first
-              flag = charz_session.flags.find { |gates, routines| routines.include?(routine) }&.first
+              enable = charz_instance.enables.find { |gates, routines| routines.include?(routine) }&.first
+              flag = charz_instance.flags.find { |gates, routines| routines.include?(routine) }&.first
               if enable && flag
                 if_enable enable do
                   if_flag flag do
@@ -472,9 +543,9 @@ module OrigenTesters
             end
           else
             # both enable and flag is set, and both apply to all routines in session
-            if_enable charz_session.enables do
-              if_flag charz_session.flags do
-                charz_session.routines.each do |routine|
+            if_enable charz_instance.enables do
+              if_flag charz_instance.flags do
+                charz_instance.routines.each do |routine|
                   block.call(options.merge(current_routine: routine))
                 end
               end
@@ -482,11 +553,11 @@ module OrigenTesters
           end
         else
           # only enables or flags is set, not both
-          if charz_session.enables
-            gates = charz_session.enables
+          if charz_instance.enables
+            gates = charz_instance.enables
             gate_method = :if_enable
-          elsif charz_session.flags
-            gates = charz_session.flags
+          elsif charz_instance.flags
+            gates = charz_instance.flags
             gate_method = :if_flag
           end
           if gates.is_a?(Hash)
@@ -495,7 +566,7 @@ module OrigenTesters
           else
             # wrap all tests in the indicated gates
             send(gate_method, gates) do
-              charz_session.routines.each do |routine|
+              charz_instance.routines.each do |routine|
                 block.call(options.merge(current_routine: routine))
               end
             end
@@ -507,7 +578,7 @@ module OrigenTesters
     # helper method for the process gates method above
     # handles wrapping routines in specific gates, and passing ungated routines back to the user
     def insert_hash_gates(options, gate_hash, gate_method, &block)
-      ungated_routines = charz_session.routines - gate_hash.values.flatten
+      ungated_routines = charz_instance.routines - gate_hash.values.flatten
       ungated_routines.each do |routine|
         block.call(options.merge(current_routine: routine))
       end

data/program/charz.rb

@@ -54,11 +54,16 @@ Flow.create interface: 'OrigenTesters::Test::Interface' do
     
     charz_on :complex_anded_flags, {flags: { routine1: [:my_flag1, :my_flag2]}}
       func_with_charz :func_complex_anded_flags
+      charz_on_append :routine2, { type: :routine }
+      func_with_charz :func_complex_anded_flags_add_simple_rt2
+      charz_off_truncate
     charz_off
 
     charz_on :complex_anded_enables, {enables: { routine1: [:my_enable1, :my_enable2]}}
       func_with_charz :func_complex_anded_enables
     charz_off
 
+    
+
   end
 end

data/templates/origen_guides/program/charz.md.erb

@@ -79,6 +79,63 @@ add_charz_profile :anded_enables do |profile|
 end
 ~~~
 
+### Flow API
+
+Once your profiles and routines are initialized, the primary way of using the Charz API are through charz on/off calls as well as their append/truncate counterparts:
+
+#### charz_on / charz_off
+
+Pushes/pops a charz object (either a profile or a routine) onto the stack, along with any optional updates to modify the current session.
+Once pushed, the charz_session will attempt to update itself with the new data, failing if the resulting session is invalid. The updates will be stored as an "instance" which
+is essentially a dummy Profile, and placed inside the sessions instance stack, effectively making the charz_stack a 2D array.
+
+Once an instance is pushed onto the stack, the session becomes active and valid, allowing your apps hooks to query that state to know if a charz test needs to be inserted.
+
+Basic Usage:
+
+~~~ruby
+# pushes the profile :my_profile onto the charz stack
+charz_on :my_profile
+# after you've updated your app to insert charz tests,
+# this line will make two tests: point test and charz variant
+func :my_test
+# pops :my_profile off the charz stack
+charz_off
+
+# alternate block form, functionally identical
+charz_on :my_profile do
+  func :my_test
+end
+~~~
+
+#### charz_on_append / charz_off_truncate
+
+Very similar to the previous charz_on/off, the append/truncate instead operates in the 2nd dimension of the 2D array that is the charz stack.
+Pushes/pops a charz object (either a profile or a routine) onto the current sessions instance stack, along with any optional updates to modify that instance.
+This will result in subsequent charzable point tests in being processed against each of the current instances. In other words, this new push will not take
+priority over the current stack head, but instead append to it.
+
+Basic Usage:
+
+~~~ruby
+# pushes the profile :my_profile onto the charz stack
+charz_on :my_profile
+# after you've updated your app to insert charz tests, this line will make two tests:
+# point test and charz variant
+func :my_test
+# instead of pushing onto the charz stack itself,
+# this will push :my_other_profile onto the instance stack of the current session,
+# which is the at the head of the charz stack
+charz_on_append :my_other_profile
+# this line now makes 3 tests: the point test, a charz variant
+# per :my_profile, and another per :my_other_profile
+func :my_other_test
+# pops the session of the stack, meaning both :my_profile and :my_other_profile
+# are gone since they were in the same session alternately run charz_off_truncate
+# to only remove :my_other_profile
+charz_off
+~~~
+
 ### Charz Session
 
 The charz session (stored in your interfaces `@charz_session` attribute) monitors the current state of characterization at a given point in flow generation.
@@ -210,7 +267,10 @@ Where insert_current_charz_test is a method defined in the company charz flow me
 
 ### Flow Usage Examples
 
-Now that the interface has charz routines and profiles, lets look at how to use the API within the flow itself:
+Now that the interface has charz routines and profiles, lets look at how to use the API within the flow itself. Basic usage is to make charz_on/off calls, which will set the
+session to contain the called profile as the current instance to generate against.
+
+Additionally if you would like to add additional profiles to the current session, you can use the `charz_on_append` (and its counter part: `charz_off_truncate`) to do so.
 
 ~~~ruby
 Flow.create(interface: 'MyApp:Interface') do
@@ -235,6 +295,19 @@ Flow.create(interface: 'MyApp:Interface') do
     func :my_test4
   end
 
+  # create profileA charz test variants of my_test5, as well as profileA and profileB charz variants of my_test6
+  # this would produce the following tests in order:
+  # my_test5
+  # my_test5_routineA
+  # my_test6
+  # my_test6_routineA
+  # my_test6_routineB
+  charz_on :profileA do
+    func :my_test5
+    charz_on_append :profileB
+    func :my_test6
+  end
+
 end
 ~~~
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: origen_testers
 version: !ruby/object:Gem::Version
-  version: 0.51.2
+  version: 0.51.3
 platform: ruby
 authors:
 - Stephen McGinty
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-20 00:00:00.000000000 Z
+date: 2023-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: origen