atp 0.1.0 → 0.2.0

data/lib/atp/flow.rb

@@ -0,0 +1,140 @@
+module ATP
+  # Implements the main user API for building and interacting
+  # with an abstract test program
+  class Flow
+    attr_reader :program
+    # Returns the raw AST
+    attr_reader :raw
+
+    def initialize(program)
+      @program = program
+      @builder = AST::Builder.new
+      @raw = builder.flow
+    end
+
+    # Returns a processed/optimized AST, this is the one that should be
+    # used to build and represent the given test flow
+    def ast
+      ast = Processors::PreCleaner.new.process(raw)
+      ast = Processors::Condition.new.process(ast)
+      ast = Processors::Relationship.new.process(ast)
+      ast = Processors::PostCleaner.new.process(ast)
+    end
+
+    # Group all tests generated within the given block
+    #
+    # @example
+    #   flow.group "RAM Tests" do
+    #     flow.test ...
+    #     flow.test ...
+    #   end
+    def group(name, options = {})
+      open_groups.push([])
+      yield
+      append builder.group(name, open_groups.pop, options)
+    end
+
+    # Add a test line to the flow
+    #
+    # @param [String, Symbol] the name of the test
+    # @param [Hash] options a hash to describe the test's attributes
+    # @option options [Symbol] :id A unique test ID
+    # @option options [String] :description A description of what the test does, usually formatted in markdown
+    # @option options [Hash] :on_fail What action to take if the test fails, e.g. assign a bin
+    # @option options [Hash] :on_pass What action to take if the test passes
+    # @option options [Hash] :conditions What conditions must be met to execute the test
+    def test(instance, options = {})
+      r = options.delete(:return)
+      if options[:context] == :current
+        options[:conditions] = builder.context[:conditions]
+      end
+      # Allows any continue, bin, or soft bin argument passed in at the options top-level to be assumed
+      # to be the action to take if the test fails
+      if b = options.delete(:bin)
+        options[:on_fail] ||= {}
+        options[:on_fail][:bin] = b
+      end
+      if b = options.delete(:softbin) || b = options.delete(:sbin) || b = options.delete(:soft_bin)
+        options[:on_fail] ||= {}
+        options[:on_fail][:softbin] = b
+      end
+      if options.delete(:continue)
+        options[:on_fail] ||= {}
+        options[:on_fail][:continue] = true
+      end
+      builder.new_context
+
+      t = builder.test(instance, options)
+      unless options[:context] == :current
+        open_conditions.each do |conditions|
+          t = builder.apply_conditions(t, conditions)
+        end
+      end
+      append(t) unless r
+      t
+    end
+
+    def bin(number, options = {})
+      fail 'A :type option set to :pass or :fail is required when calling bin' unless options[:type]
+      options[:bin] = number
+      options[:softbin] ||= options[:soft_bin] || options[:sbin]
+      append builder.set_result(options[:type], options)
+    end
+
+    def cz(instance, cz_setup, options = {})
+      options[:return] = true
+      append(builder.cz(cz_setup, test(instance, options)))
+    end
+    alias_method :characterize, :cz
+
+    # Append a log message line to the flow
+    def log(message, options = {})
+      append builder.log(message)
+    end
+
+    # Insert explicitly rendered content in to the flow
+    def render(str, options = {})
+      append builder.render(str)
+    end
+
+    def with_condition(options)
+      open_conditions.push(options)
+      yield
+      open_conditions.pop
+    end
+    alias_method :with_conditions, :with_condition
+
+    # Execute the given flow in the console
+    def run(options = {})
+      Formatters::Datalog.run_and_format(ast, options)
+      nil
+    end
+
+    private
+
+    # For testing
+    def raw=(ast)
+      @raw = ast
+    end
+
+    def open_conditions
+      @open_conditions ||= []
+    end
+
+    def open_groups
+      @open_groups ||= []
+    end
+
+    def append(node)
+      if open_groups.empty?
+        @raw = @raw.updated(nil, @raw.children + [node])
+      else
+        open_groups.last << node
+      end
+    end
+
+    def builder
+      @builder
+    end
+  end
+end

data/lib/atp/formatter.rb

@@ -0,0 +1,20 @@
+module ATP
+  class Formatter < Processor
+    def format(node, options = {})
+      process(node)
+    end
+
+    def self.format(node, options = {})
+      new.format(node, options)
+    end
+
+    def self.run_and_format(node, options = {})
+      ast = Runner.new.run(node, options)
+      format(ast, options)
+    end
+
+    def self.run(*args)
+      run_and_format(*args)
+    end
+  end
+end

data/lib/atp/formatters/basic.rb

@@ -0,0 +1,18 @@
+module ATP
+  module Formatters
+    # Returns the executed flow as a string of test names. This
+    # is mainly intended to be used for testing the runner.
+    class Basic < Formatter
+      def format(node, options = {})
+        @output = ''
+        process(node)
+        @output
+      end
+
+      def on_test(node)
+        @output += node.to_h[:name][0]
+        @output += "\n"
+      end
+    end
+  end
+end

data/lib/atp/formatters/datalog.rb

@@ -0,0 +1,20 @@
+module ATP
+  module Formatters
+    # Outputs the given AST to something resembling an ATE datalog,
+    # this can optionally be rendered to a file or the console (the default).
+    class Datalog < Formatter
+      def on_flow(node)
+        puts 'Number     Result   Test Name                 Pin            Channel   Low            Measured       High           Force          Loc'
+        process_all(node.children)
+      end
+
+      def on_test(node)
+        t = node.to_h
+        str = "#{t[:number]}".ljust(11)
+        str += "#{t[:failed] ? 'FAIL' : 'PASS'}".ljust(9)
+        str += "#{t[:name][0]}".ljust(20)
+        puts str
+      end
+    end
+  end
+end

data/lib/atp/not.rb

@@ -0,0 +1,13 @@
+module ATP
+  class NOT
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    def inspect
+      "NOT[#{value}]"
+    end
+  end
+end

data/lib/atp/or.rb

@@ -0,0 +1,11 @@
+module ATP
+  class OR < ::Array
+    def initialize(*vals)
+      vals.flatten.each { |v| self << v }
+    end
+
+    def inspect
+      "OR#{super}"
+    end
+  end
+end

data/lib/atp/parser.rb

@@ -0,0 +1,26 @@
+require 'sexpistol'
+module ATP
+  class Parser < Sexpistol
+    def initialize
+      self.ruby_keyword_literals = true
+    end
+
+    def string_to_ast(string)
+      to_sexp(parse_string(string))
+    end
+
+    def to_sexp(ast_array)
+      children = ast_array.map do |item|
+        if  item.is_a?(Array)
+          to_sexp(item)
+        else
+          item
+        end
+      end
+      type = children.shift
+      return type if type.is_a?(ATP::AST::Node)
+      type = type.to_s.gsub('-', '_').to_sym
+      ATP::AST::Node.new(type, children)
+    end
+  end
+end

data/lib/atp/processor.rb

@@ -0,0 +1,38 @@
+require 'ast'
+module ATP
+  # The base processor, this provides a default handler for
+  # all node types and will not make any changes to the AST,
+  # i.e. an equivalent AST will be returned by the process method.
+  #
+  # Child classes of this should be used to implement additional
+  # processors to modify or otherwise work with the AST.
+  #
+  # @see http://www.rubydoc.info/gems/ast/2.0.0/AST/Processor
+  class Processor
+    include ::AST::Processor::Mixin
+
+    def process(node)
+      if node.respond_to?(:to_ast)
+        super(node)
+      else
+        node
+      end
+    end
+
+    def handler_missing(node)
+      node.updated(nil, process_all(node.children))
+    end
+
+    def n(type, children)
+      ATP::AST::Node.new(type, children)
+    end
+
+    def n0(type)
+      n(type, [])
+    end
+
+    def n1(type, arg)
+      n(type, [arg])
+    end
+  end
+end

data/lib/atp/processors/condition.rb

@@ -0,0 +1,174 @@
+module ATP
+  module Processors
+    # This optimizes the condition nodes such that any adjacent flow nodes that
+    # have the same condition, will be grouped together under a single condition
+    # wrapper.
+    #
+    # For example this AST:
+    #
+    #   (flow
+    #     (group "g1"
+    #       (test
+    #         (name "test1"))
+    #       (flow-flag "bitmap" true
+    #         (test
+    #           (name "test2"))))
+    #     (flow-flag "bitmap" true
+    #       (group "g1"
+    #         (flow-flag "x" true
+    #           (test
+    #             (name "test3")))
+    #         (flow-flag "y" true
+    #           (flow-flag "x" true
+    #             (test
+    #               (name "test4")))))))
+    #
+    # Will be optimized to this:
+    #
+    #   (flow
+    #     (group "g1"
+    #       (test
+    #         (name "test1"))
+    #       (flow-flag "bitmap" true
+    #         (test
+    #           (name "test2"))
+    #         (flow-flag "x" true
+    #           (test
+    #             (name "test3"))
+    #           (flow-flag "y" true
+    #             (test
+    #               (name "test4")))))))
+    #
+    class Condition < Processor
+      CONDITION_NODES = [:flow_flag, :test_result, :test_executed, :group, :job]
+
+      def process(node)
+        # Bit of a hack - To get all of the nested conditions optimized away it is necessary
+        # to execute this recursively a few times. This guard ensures that the recursion is
+        # only performed on the top-level and not on every process operation.
+        if @top_level_called
+          super
+        else
+          @top_level_called = true
+          ast1 = nil
+          ast2 = node
+          while ast1 != ast2
+            ast1 = super(ast2)
+            ast2 = super(ast1)
+          end
+          @top_level_called = false
+          ast1
+        end
+      end
+
+      def on_boolean_condition(node)
+        children = node.children.dup
+        name = children.shift
+        state = children.shift
+        children = optimize_siblings(n(:temp, children))
+        if condition_to_be_removed?(node)
+          process_all(children)
+        else
+          node.updated(nil, [name, state] + process_all(children))
+        end
+      end
+      alias_method :on_flow_flag, :on_boolean_condition
+      alias_method :on_test_result, :on_boolean_condition
+      alias_method :on_test_executed, :on_boolean_condition
+
+      def on_condition(node)
+        children = node.children.dup
+        name = children.shift
+        children = optimize_siblings(n(:temp, children))
+        if condition_to_be_removed?(node)
+          process_all(children)
+        else
+          node.updated(nil, [name] + process_all(children))
+        end
+      end
+      alias_method :on_group, :on_condition
+      alias_method :on_job, :on_condition
+
+      # Returns true if the given node contains the given condition within
+      # its immediate children
+      def has_condition?(condition, node)
+        ([node] + node.children.to_a).any? do |n|
+          if n.is_a?(ATP::AST::Node)
+            equal_conditions?(condition, n)
+          end
+        end
+      end
+
+      def condition_to_be_removed?(node)
+        remove_condition.last && equal_conditions?(remove_condition.last, node)
+      end
+
+      def equal_conditions?(node1, node2)
+        if node1.type == node2.type
+          if node1.type == :group || node1.type == :job
+            node1.to_a.take(1) == node2.to_a.take(1)
+          else
+            node1.to_a.take(2) == node2.to_a.take(2)
+          end
+        end
+      end
+
+      def condition?(node)
+        node.is_a?(ATP::AST::Node) && CONDITION_NODES.include?(node.type)
+      end
+
+      def on_flow(node)
+        node.updated(nil, optimize_siblings(node))
+      end
+
+      def on_members(node)
+        node.updated(nil, optimize_siblings(node))
+      end
+
+      def optimize_siblings(top_node)
+        children = []
+        unprocessed_children = []
+        current = nil
+        last = top_node.children.size - 1
+        top_node.to_a.each_with_index do |node, i|
+          # If a condition has been identified in a previous node
+          if current
+            process_nodes = false
+            # If this node has the current condition, then buffer it for later processing
+            # and continue to the next node
+            if has_condition?(current, node)
+              unprocessed_children << node
+              node = nil
+            else
+              process_nodes = true
+            end
+            if process_nodes || i == last
+              remove_condition << current
+              current_children = current.children + [process_all(unprocessed_children)].flatten
+              unprocessed_children = []
+              remove_condition.pop
+              children << process(current.updated(nil, current_children))
+              if node && (!condition?(node) || i == last)
+                current = nil
+                children << process(node)
+              else
+                current = node
+              end
+            end
+          else
+            if condition?(node) && i != last
+              current = node
+            else
+              children << process(node)
+            end
+          end
+        end
+        children.flatten
+      end
+
+      def remove_condition
+        @remove_condition ||= []
+      end
+    end
+  end
+end