carray 2.0.1 → 3.0.1

data/lib/carray/frame/verbs.rb

@@ -0,0 +1,316 @@
+# CAFrame column verbs (memo §11.4, §12-A, §13.2).
+#
+# Each verb touches this frame's own columns Hash (per-frame, §12-B) and
+# returns self so calls chain. Column data is still shared with any parent
+# (view-frame), but membership — which columns this frame names — is local:
+# append/drop/rename here never change a parent's column set.
+
+class CAFrame
+  # Add (or replace) a column, returning a new frame — the column set changes,
+  # so the result is a different table (memo §3.8). The column is shared by
+  # reference; the envelope is cheap. Chain or reassign: +df = df.append(...)+.
+  def append(name, col)
+    key = name.to_s
+    ca  = coerce_column(col)
+    rebuild(@columns.merge(key => ca))
+  end
+
+  # Remove one or more columns, returning a new frame (column set changes,
+  # memo §3.8). Column data is untouched and shared with the original.
+  def drop(*names)
+    cols = @columns.dup
+    names.each do |name|
+      key = name.to_s
+      raise KeyError, "no column #{key.inspect}" unless cols.key?(key)
+      cols.delete(key)
+    end
+    rebuild(cols)
+  end
+
+  # Rename columns, returning a new frame (column names change, memo §3.8).
+  # Column order is preserved (memo §13.2 "column order = insertion order");
+  # columns are shared by reference.
+  def rename(mapping)
+    norm = {}
+    mapping.each do |old, new|
+      o = old.to_s
+      n = new.to_s
+      raise KeyError, "no column #{o.inspect}" unless @columns.key?(o)
+      if n != o && @columns.key?(n)
+        raise ArgumentError, "rename target #{n.inspect} already exists"
+      end
+      norm[o] = n
+    end
+    rebuilt = {}
+    @columns.each { |k, v| rebuilt[norm[k] || k] = v }
+    rebuild(rebuilt)
+  end
+
+  # Mask cells of a column that equal +value+ (sentinel -> mask, memo §11.4).
+  # In-place on the column (write-through, §4.3): numeric/object columns
+  # mask in place; a categorical column's codes are read-only (§13.4) so this
+  # raises — recode by rebuilding and rebinding instead.
+  def mask_eq(name, value)
+    self[name][:eq, value] = UNDEF
+    self
+  end
+
+  # Cast columns to a data type and rebind them (memo §11.4). Uses to_type,
+  # so parse failures on string columns become UNDEF (parse-mask, §6-2).
+  # Three call shapes, disambiguated by the fact that column names are always
+  # Strings and types always Symbols (§3.7):
+  #
+  #   cast("temp", :float64)                     # one column (chains)
+  #   cast("temp" => :float64, "rh" => :int32)   # name => type map
+  #   cast(["temp", "rh"] => :float64)           # names sharing one type
+  #
+  # A map key may be a single name or an Array of names; the value is the
+  # target type. Returns self so calls chain.
+  def cast(name_or_map, type = nil)
+    if name_or_map.is_a?(Hash)
+      unless type.nil?
+        raise ArgumentError, "cast(map) takes no positional type argument"
+      end
+      name_or_map.each do |names, t|
+        Array(names).each { |name| cast_one(name, t) }
+      end
+    else
+      cast_one(name_or_map, type)
+    end
+    self
+  end
+
+  # Bring every column to one common data type and rebind them (memo §11.4).
+  # The frame-level counterpart of +CArray.promote_list+: where +cast+ forces
+  # named columns to a type, +promote+ widens the whole table until it has a
+  # single type. Returns self so calls chain (§3.8 -- a type-interpretation
+  # change), and like +cast+ it allocates fresh columns, so a parent frame
+  # sharing the old ones is untouched. The index is not a column and is left
+  # alone.
+  #
+  #   df.promote             # the common type CArray.result_type would pick
+  #   df.promote(:object)    # force the widest type: anything fits
+  #
+  # Without an argument the common type is whatever +promote_list+ picks --
+  # the same decision +to_ca+ / +CArray.stack+ make internally, so
+  # +df.promote+ is exactly "make this frame stackable". Columns that are
+  # already uniform (including a uniformly Face-typed frame) are left as they
+  # are.
+  #
+  # With an argument the type must be a widening for every column: promoting
+  # is not the place to lose values, so a narrowing target raises and points
+  # at +cast+, which is the verb that forces. +:object+ is the widest type
+  # and therefore always accepted -- it is the way a frame mixing text,
+  # Face-typed and numeric columns becomes a single-type table (and so the
+  # way +to_ca+ can hand back a matrix for it).
+  def promote(type = nil)
+    return self if @columns.empty?
+    type.nil? ? promote_to_common : promote_to_type(type)
+    self
+  end
+
+  # Parse a string column into a time column and rebind it (memo §11.2).
+  # The column must be string-bearing (an object CArray of Strings, or a
+  # CAString / CAConstString / CAFixlenString) — this is the "text -> time"
+  # mode, distinct from the integer-serial mode of +to_time+. Delegates to
+  # +CArray.time(col, on_error: :mask)+: +format+ picks strptime parsing
+  # (auto-detect when nil), +unit+ the storage resolution; masked / nil and
+  # unparseable cells become UNDEF (bulk column parse tolerates bad cells).
+  # Make it the index with +set_index+ afterward.
+  #
+  #   df.parse_to_time("time").set_index("time")
+  def parse_to_time(name, format = nil, unit: :s)
+    key = name.to_s
+    col = @columns.fetch(key) { raise KeyError, "no column #{key.inspect}" }
+    unless string_column?(col)
+      raise ArgumentError,
+            "parse_to_time needs a string column (object / CAString / " \
+            "CAConstString / CAFixlenString); #{key.inspect} is #{col.data_type}"
+    end
+    @columns[key] = CArray.time(col, format: format, unit: unit, on_error: :mask)
+    self
+  end
+
+  # Reinterpret an integer column as time serial counts and rebind it (memo
+  # §11.2). This is the "serial -> time" mode: each value is a count of
+  # +unit+ resolution since +epoch+ (default the Unix epoch, 1970-01-01 UTC).
+  # +epoch+ takes any time literal (String / Time / Integer), so a column
+  # measured from another origin — a netCDF "hours since 1990-01-01" axis, an
+  # Excel serial date (epoch "1899-12-30", unit :D) — converts directly.
+  #
+  # A float column is accepted only when every value is whole (no fractional
+  # part); a fractional serial has sub-unit precision that a finer +unit+ should
+  # carry, so it raises rather than silently truncate. Make it the index with
+  # +set_index+ afterward.
+  #
+  # A +CATime::Grid+ carries the same (unit, epoch) pair as one value, so a
+  # netCDF +units+ attribute goes straight in. It also carries a phase the
+  # keyword form cannot: the keyword +epoch+ is read on the +unit+ grid, so
+  # an epoch off that grid ("days since 1980-01-01 12:00") loses its
+  # time-of-day, while a grid resolves the finer storage that holds it.
+  #
+  #   df.to_time("time", unit: :h, epoch: "1990-01-01").set_index("time")
+  #   df.to_time("time", CATime::Grid.parse("hours since 1990-01-01"))
+  #   df.to_time("time", CATime::Grid.parse("days since 1980-01-01 12:00"))
+  def to_time(name, grid = nil, unit: :s, epoch: nil)
+    key = name.to_s
+    col = @columns.fetch(key) { raise KeyError, "no column #{key.inspect}" }
+    raw = integer_serial_column(col, key)
+    grid = unit if unit.is_a?(CATime::Grid)
+    if grid.is_a?(CATime::Grid)
+      @columns[key] = grid.at(raw)
+      return self
+    end
+    unless grid.nil?
+      raise ArgumentError,
+            "the positional argument must be a CATime::Grid (got #{grid.class})"
+    end
+    if epoch
+      raw = raw + CArray.time(epoch, unit: unit).ticks[0]
+    end
+    @columns[key] = raw.time(unit: unit)
+    self
+  end
+
+  # Fill masked cells of a column (memo §6, §11.8).  A Symbol selects a
+  # scan method; anything else is a constant fill value.  The fill is
+  # write-through: it edits the live shared column rather than rebinding a
+  # filled copy (memo §3.8).  Returns self so calls chain.
+  #
+  #   fill("temp", :ffill)   # forward hold  (carry last valid value)
+  #   fill("temp", :bfill)   # backward hold (carry next valid value)
+  #   fill("temp", :linear)  # linear interpolation; x = this frame's index
+  #                          # coordinate when present, else the cell position
+  #   fill("temp", 0.0)      # constant fill
+  #
+  # :ffill / :bfill work for any writable column data_type (numeric, time,
+  # object, fixlen, …); :linear needs a numeric or time (CATime /
+  # CATimedelta) column.  A categorical column's codes are read-only
+  # (memo §13.4), so any fill on it raises — rebind a filled copy instead:
+  # `df.append(name, df[name].strip_mask(method: :forward))`.
+  def fill(name, method_or_value)
+    key = name.to_s
+    raise KeyError, "no column #{key.inspect}" unless @columns.key?(key)
+    col = @columns[key]
+    case method_or_value
+    when :ffill  then col.unmask(method: :forward)
+    when :bfill  then col.unmask(method: :backward)
+    when :linear then fill_linear_column(key, col)
+    when Symbol
+      raise ArgumentError,
+            "fill: unknown method #{method_or_value.inspect} " \
+            "(:ffill | :bfill | :linear, or a constant fill value)"
+    else
+      col.unmask(method_or_value)   # constant fill, in place
+    end
+    self
+  end
+
+  private def fill_linear_column(key, col)
+    # A time column interpolates through CATime#linear_fetch /
+    # CATimedelta#linear_fetch, which keep the Face and its unit.
+    time_face = col.is_a?(CATime) || col.is_a?(CATimedelta)
+    unless col.numeric? || time_face
+      raise ArgumentError,
+            "fill(#{key.inspect}, :linear): numeric or time column required " \
+            "(got #{col.data_type_name})"
+    end
+    # Without an index coordinate x is the cell position, which is exactly what
+    # the core scan already interpolates against -- time columns included.
+    return col.unmask(method: :linear) if @index.nil?
+    present = col.is_not_masked
+    return if present.count(true) < 2
+    addr = @index[present].linear_section(@index)
+    if time_face
+      filled = col[present].linear_fetch(addr)   # UNDEF beyond the valid span
+      # Write through the storage: a bulk store into the Face itself would try
+      # to cast int64 ticks to its fixlen surface.  Both sides carry the same
+      # unit (selection preserves it), so the ticks land exactly, mask included.
+      col.parent[] = filled.parent
+      return
+    end
+    yvalid = col.value.float64[present]
+    col[] = yvalid.linear_fetch(addr).to_type(col.data_type).mask_invalid   # write-through
+  end
+
+  private def cast_one(name, type)
+    key = name.to_s
+    raise KeyError, "no column #{key.inspect}" unless @columns.key?(key)
+    @columns[key] = @columns[key].to_type(type)
+  end
+
+  # +promote+ with no target: let +promote_list+ decide the common type --
+  # the same call +to_ca+ / +CArray.stack+ make -- then materialise each
+  # column it had to coerce. +promote_list+ hands a column back untouched
+  # when it needs no coercion, so identity says which ones to rebind.
+  private def promote_to_common
+    cols = @columns.values
+    begin
+      promoted = CArray.promote_list(cols)
+    rescue ArgumentError, RuntimeError => e
+      raise ArgumentError,
+            "#{e.message} -- promote(:object) brings every column to its " \
+            "surface values, which any column set can share; a numeric target " \
+            "works too when every Face column declares #to_numeric"
+    end
+    @columns.keys.each_with_index do |key, i|
+      coerced = promoted[i]
+      next if coerced.equal?(cols[i])
+      @columns[key] = cols[i].to_type(coerced.data_type)
+    end
+  end
+
+  # +promote+ with a target: every column must widen into it.
+  private def promote_to_type(type)
+    unless type.is_a?(Symbol)
+      raise ArgumentError,
+            "promote takes a data type Symbol (got #{type.class}); " \
+            "class-shaped targets are not promotion destinations"
+    end
+    @columns.each_key do |key|
+      col = @columns[key]
+      # A Face column answers for itself: :object is its surface values, a
+      # numeric target is whatever it declares in #to_numeric (and a TypeError
+      # naming that method when it declares nothing). result_type has nothing
+      # to say about a surface it cannot read, so the widening check -- which
+      # is about primitive promotion -- applies to plain columns only.
+      refuse_narrowing(key, col, type) unless col.face?
+      @columns[key] = col.to_type(type)
+    end
+  end
+
+  private def refuse_narrowing(key, col, type)
+    common = begin
+      CArray.result_type(col, type)
+    rescue StandardError => e
+      raise ArgumentError,
+            "promote: column #{key.inspect} (#{col.data_type}) has no common " \
+            "type with #{type.inspect} (#{e.message})"
+    end
+    return if common == type
+    raise ArgumentError,
+          "promote widens: column #{key.inspect} (#{col.data_type}) would " \
+          "narrow to #{type.inspect} -- cast is the verb that forces a " \
+          "lossy change"
+  end
+
+  private def string_column?(col)
+    col.is_a?(CArray::StringOperationMixin) || col.data_type == :object
+  end
+
+  private def integer_serial_column(col, key)
+    if INTEGER_TYPES.include?(col.data_type)
+      col.to_type(:int64)
+    elsif col.data_type == :float32 || col.data_type == :float64
+      unless col.floor.eq(col).all
+        raise ArgumentError,
+              "to_time: float column #{key.inspect} has fractional values; " \
+              "use a finer unit: or convert to integer counts explicitly"
+      end
+      col.to_type(:int64)
+    else
+      raise ArgumentError,
+            "to_time needs an integer serial column; #{key.inspect} is #{col.data_type}"
+    end
+  end
+end

data/lib/carray/frame.rb

@@ -0,0 +1,16 @@
+# CAFrame — a DataFrame whose columns are real CArrays.
+#
+# Thin loader. The frame is a small Ruby layer over CArray: columns are
+# genuine CArrays, so every CArray operation (mask / view / Face /
+# memory_view) is reachable by escaping to a column. See
+# devel/MEMO_DATAFRAME_ON_CARRAY.md for the design.
+
+require 'carray/frame/frame'
+require 'carray/frame/verbs'
+require 'carray/frame/convert'
+require 'carray/frame/io'
+require 'carray/frame/records'
+require 'carray/frame/group'
+require 'carray/frame/join'
+require 'carray/frame/concat'
+require 'carray/frame/sort'

data/lib/carray/fuse_source.rb

@@ -0,0 +1,123 @@
+# ---------------------------------------------------------------------------
+#  Reading `CArray.fuse { a + b * c }`.
+#
+#  The block is not called.  Its `a` is the array itself, so calling it would
+#  evaluate the expression eagerly -- which is the thing fuse exists to avoid.
+#  The source is read instead, every name that holds a CArray is given `.lazy`,
+#  and the result is evaluated back in the block's own binding, so `self`,
+#  instance variables, methods and constants are what they were.
+#
+#  Ruby has no macro, so the alternative was to pass the arrays in and take
+#  shadows back -- `fuse(a, b) { |x, y| ... }` -- which names each of them
+#  twice.  Julia writes `@.` for the same reason and does the same thing to
+#  the expression underneath.
+# ---------------------------------------------------------------------------
+
+require "prism"
+
+class CArray
+
+  module FuseSource
+
+    # Runtime coercion, so the rewrite never has to work out what a name
+    # holds: anything that is not an array passes through untouched.
+    def self.shadow (value)
+      value.is_a?(CArray) ? value.lazy : value
+    end
+
+    def self.evaluate (block)
+      result = eval(rewrite(body_source(block)), block.binding,
+                    *block.source_location)
+      # An expression that is just an array is that array; the shadow put
+      # around it has nothing to fuse.
+      result.is_a?(CALazyMarker) ? result.parent : result
+    end
+
+    # -- the block's own text ---------------------------------------------
+
+    def self.body_source (block)
+      text = extract(block)
+      wrapped = "proc " + text
+      node = Prism.parse(wrapped).value
+                  .breadth_first_search { |n| n.is_a?(Prism::BlockNode) }
+      inner = node && node.body
+      unless inner
+        raise ArgumentError,
+              "CArray.fuse could not read an expression out of this block"
+      end
+      wrapped.byteslice(inner.location.start_offset...inner.location.end_offset)
+    end
+
+    def self.extract (block)
+      sequence = RubyVM::InstructionSequence.of(block) rescue nil
+      location = sequence && sequence.to_a[4][:code_location]
+      path     = sequence && (sequence.absolute_path || sequence.path)
+      unless location && path && File.readable?(path)
+        raise ArgumentError,
+              "CArray.fuse cannot read this block's source (defined in irb, " \
+              "eval, or a file that is no longer there).  Write `.lazy` on " \
+              "the operands instead: `a.lazy + b.lazy`."
+      end
+      lines = File.readlines(path)
+      first_line, first_column, last_line, last_column = location
+      # The columns count bytes, not characters, so a line with anything
+      # multi-byte on it slices in the wrong place unless this does too.
+      if first_line == last_line
+        lines[first_line - 1].byteslice(first_column...last_column)
+      else
+        [lines[first_line - 1].byteslice(first_column..),
+         *lines[first_line...(last_line - 1)],
+         lines[last_line - 1].byteslice(0...last_column)].join
+      end
+    end
+
+    # -- the rewrite -------------------------------------------------------
+
+    # The leaves are the names being read.  Everything else keeps its shape:
+    # calls are inserted around leaves and the expression they sit in is
+    # left alone.
+    class Leaves < Prism::Visitor
+      attr_reader :spots
+
+      def initialize
+        @spots = []
+      end
+
+      def visit_local_variable_read_node (node)    = mark(node)
+      def visit_instance_variable_read_node (node) = mark(node)
+      def visit_constant_read_node (node)          = mark(node)
+
+      # `Math::PI` is one name, not `Math` with something after it.
+      def visit_constant_path_node (node)
+        mark(node)
+      end
+
+      def visit_call_node (node)
+        if node.name == :[] || node.name == :[]=
+          # An index is a position, not a value to fuse: `a[i]` shadows `a`
+          # and leaves `i` alone.
+          visit(node.receiver)
+          return
+        end
+        mark(node) if node.receiver.nil? && node.arguments.nil? && node.block.nil?
+        super
+      end
+
+      private
+
+      def mark (node)
+        @spots << [node.location.start_offset, node.location.end_offset]
+      end
+    end
+
+    def self.rewrite (source)
+      visitor = Leaves.new
+      Prism.parse(source).value.accept(visitor)
+      out = source.dup
+      visitor.spots.sort_by { |start, _| -start }.each do |start, stop|
+        out[start...stop] = "::CArray::FuseSource.shadow(#{source[start...stop]})"
+      end
+      out
+    end
+  end
+end

data/lib/carray/fusion.rb

@@ -0,0 +1,218 @@
+# ---------------------------------------------------------------------------
+#  Turning a lazy expression into a plan a compiler can read.
+#
+#  A lazy view is already a typed, closed expression graph, and the kernels
+#  already carry the C that computes each operation (CArray.__kernel_body__).
+#  What is missing between them is the reading: which operation each node is,
+#  what its mask does, and where the leaves are.  That is what a plan holds.
+#
+#  Nothing here compiles anything.  A plan is plain data, and CArray itself
+#  never needs one -- it can always walk the view.  What a plan is for is a
+#  second evaluator: hand it to one, and the answer must be the same.
+# ---------------------------------------------------------------------------
+
+class CArray
+
+  module Fusion
+
+    # One value per node, in evaluation order; the last is the result.
+    #
+    #   Op    an operation, reading the nodes named in `args`
+    #   Leaf  an array, the `index`-th of plan.leaves
+    #   Const a scalar written into the expression
+    Op    = Struct.new(:kind, :name, :data_type, :args, :body, :mask, :trapping)
+    Leaf  = Struct.new(:index, :data_type, :masked)
+    Const = Struct.new(:value, :data_type)
+
+    Plan  = Struct.new(:nodes, :leaves, :data_type, :dim, :masked, :signature)
+
+    LAZY_CLASSES = [CAMonOp, CABinOp, CATriOp, CAMonCmp, CABinCmp, CALazyMarker]
+
+    # A lazy node names its operation by an id and the kernels name it by a
+    # symbol.  These are the same operations, spelled the way each side
+    # spells them; the rest are spelled alike.
+    BINOP_NAMES = {
+      :+  => :add,        :-  => :sub,        :*  => :mul,
+      :/  => :div,        :** => :power,      :%  => :mod,
+      :&  => :bit_and_i,  :|  => :bit_or_i,   :^  => :bit_xor_i,
+      :<< => :bit_lshift, :>> => :bit_rshift,
+    }.freeze
+    TRIOP_NAMES = { :__clip_ki__ => :clip }.freeze
+
+    MONOP_BY_ID = CArray::LAZY_MONOP_OP_IDS.invert.freeze
+    BINOP_BY_ID = CArray::LAZY_BINOP_OP_IDS.invert.freeze
+    TRIOP_BY_ID = CArray::LAZY_TRIOP_OP_IDS.invert.freeze
+
+    # Integer division and its relatives raise on a zero divisor, so a cell
+    # the mask excludes must not be computed at all -- the divisor there is
+    # nobody's business (ca_binop_dispatch.c).
+    TRAPPING = %i[div mod quo_i fmod].freeze
+    INTEGERS = %i[int8 int16 int32 int64 uint8 uint16 uint32 uint64].freeze
+
+    class Refused < StandardError; end
+
+    # ---- who computes a plan --------------------------------------------
+    #
+    # CArray can always walk the expression, so nothing has to be registered
+    # and nothing changes when nothing is.  What a registered evaluator adds
+    # is a second way to arrive at the same answer; it is asked, and it may
+    # decline.  The dispatch point stays on CArray's side, which is what
+    # keeps the threshold below a decision about CArray's own walk rather
+    # than one that moves with whatever is installed.
+    #
+    # The evaluator itself is held by CArray (see carray/lazy.rb), so that
+    # materialising an expression need not reach for this file at all until
+    # something has been registered.
+
+    # Reaching a compiled kernel costs about the same whatever the array's
+    # size, and what it buys is the passes the walk would make.  Below this
+    # the walk is the faster answer.  The crossing moves with how wide the
+    # expression is -- measured, thirty thousand cells at one operation, six
+    # thousand at six -- and this brackets those: a one-operation expression
+    # loses a couple of microseconds here, a six-operation one wins ten.
+    THRESHOLD = 10_000
+
+    # Returns the array, or nil where nothing computed it.
+    def self.evaluate (view)
+      return nil unless askable?(view)
+      out = CArray.__alloc_uninit__(view.data_type, view.dim)
+      evaluate_into(view, out) ? out : nil
+    end
+
+    # Fills an array the caller already has.  Called from the store as well,
+    # where making one and copying it over would be most of the work.
+    # Returns true when something computed it.
+    def self.evaluate_into (view, out)
+      evaluator = CArray.expression_evaluator or return false
+      return false unless askable?(view)
+      plan = plan(view) or return false
+      # A marker over an array, or anything else with nothing to compute,
+      # is not worth handing over.
+      return false unless plan.nodes.any? { |n| n.is_a?(Op) }
+      out.mask = 0 if plan.masked && ! out.has_mask?
+      evaluator.call(plan, out) ? true : false
+    rescue StandardError => error
+      CArray.expression_evaluator = nil
+      warn "CArray: the registered expression evaluator raised " \
+           "(#{error.class}: #{error.message}); expressions will be walked " \
+           "from here on"
+      false
+    end
+
+    def self.askable? (view)
+      ! CArray.expression_evaluator.nil? && view.elements >= THRESHOLD
+    end
+
+    # Returns a Plan, or nil where the expression holds something a plan
+    # cannot describe.  Refusing is ordinary: the caller walks instead.
+    def self.plan (view)
+      build(view)
+    rescue Refused
+      nil
+    end
+
+    def self.build (view)
+      raise Refused, "not a lazy expression" unless lazy?(view)
+      w = Walk.new
+      w.visit(view)
+      Plan.new(w.nodes, w.leaves, view.data_type, view.dim,
+               w.leaves.any? { |a| a.has_mask? }, w.signature)
+    end
+
+    def self.lazy? (x)
+      LAZY_CLASSES.any? { |k| x.is_a?(k) }
+    end
+
+    # ---- the walk -------------------------------------------------------
+
+    class Walk
+      attr_reader :nodes, :leaves, :signature
+
+      def initialize
+        @nodes = []
+        @leaves = []
+        @seen = {}
+        @signature = +""
+      end
+
+      def visit (n)
+        @seen[n.object_id] ||= build(n)
+      end
+
+      private
+
+      def build (n)
+        case n
+        when CALazyMarker then visit(n.parent)
+        when CAMonOp      then unary(n)
+        when CABinOp      then binary(n)
+        when CATriOp      then ternary(n)
+        when CScalar      then constant(n)
+        when CArray       then leaf(n)
+        else raise Refused, "#{n.class} in an expression"
+        end
+      end
+
+      def unary (n)
+        name = spell(MONOP_BY_ID, n.__op_id__, {})
+        args = [visit(n.parent)]
+        # A view over one array is masked exactly where that array is
+        # (ca_obj_monop.c).
+        op(:monop, name, n.data_type, args, :pass)
+      end
+
+      def binary (n)
+        name = spell(BINOP_BY_ID, n.__op_id__, BINOP_NAMES)
+        args = [visit(n.parent), visit(n.__binop_right__)]
+        # Boolean `&` and `|` are three-valued: a masked cell whose known
+        # side settles the answer comes back unmasked (ca_obj_binop.c).
+        rule = if n.data_type == :boolean && name == :bit_or_i  then :kleene_or
+               elsif n.data_type == :boolean && name == :bit_and_i then :kleene_and
+               else :union
+               end
+        op(:binop, name, n.data_type, args, rule)
+      end
+
+      def ternary (n)
+        name = spell(TRIOP_BY_ID, n.__op_id__, TRIOP_NAMES)
+        args = [visit(n.parent), visit(n.__triop_op2__), visit(n.__triop_op3__)]
+        op(:triop, name, n.data_type, args, :union)
+      end
+
+      def op (kind, name, type, args, mask)
+        body = CArray.__kernel_body__(kind, name, type) or
+          raise Refused, "#{kind} #{name} has no body at #{type}"
+        note(kind.to_s[0], name, type)
+        push Op.new(kind, name, type, args, body, mask,
+                    TRAPPING.include?(name) && INTEGERS.include?(type))
+      end
+
+      def leaf (n)
+        note("a", n.data_type, n.has_mask? ? 1 : 0)
+        @leaves << n
+        push Leaf.new(@leaves.size - 1, n.data_type, n.has_mask?)
+      end
+
+      def constant (n)
+        note("k", n[0], n.data_type)
+        push Const.new(n[0], n.data_type)
+      end
+
+      def push (node)
+        @nodes << node
+        @nodes.size - 1
+      end
+
+      def spell (table, id, renames)
+        ruby = table[id] or raise Refused, "operation id #{id}"
+        renames.fetch(ruby, ruby)
+      end
+
+      # Two expressions of the same shape compute alike, whatever arrays
+      # they are over, so a consumer can keep one compiled kernel for both.
+      def note (*parts)
+        @signature << parts.join(":") << ";"
+      end
+    end
+  end
+end