ccharts 3.0.0

data/lib/ccharts/chart.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Ccharts
+  # High-level chart API. A dataset built with {Chart.from_arrays},
+  # {Chart.from_json} or {Chart.from_csv} is immutable; the pie / histogram /
+  # sparkline / bar / stacked_bar / heatmap / boxplot renderers take their data
+  # directly (they have no OHLC dataset, exactly like the C ABI they wrap).
+  class Chart
+    # ------------------------------------------------------------------
+    # Building a dataset
+    # ------------------------------------------------------------------
+
+    # Build a dataset from four equal-length price columns and optional epoch
+    # seconds. `ts` may be nil (all timestamps unknown).
+    def self.from_arrays(open:, high:, low:, close:, ts: nil)
+      n = open.length
+      raise Error, "need at least one candle" if n == 0
+      unless [high, low, close].all? { |a| a.length == n }
+        raise Error, "open, high, low and close must have the same length"
+      end
+      if ts && ts.length != n
+        raise Error, "ts must have the same length as the price columns"
+      end
+
+      open_ptr = FFI.pack_doubles(open)
+      high_ptr = FFI.pack_doubles(high)
+      low_ptr = FFI.pack_doubles(low)
+      close_ptr = FFI.pack_doubles(close)
+      ts_ptr = ts ? FFI.pack_i64(ts) : Fiddle::NULL
+
+      out = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP)
+      status = FFI::FROM_ARRAYS.call(open_ptr, high_ptr, low_ptr, close_ptr, ts_ptr, n, out)
+      _from_data_status(status, out)
+    end
+
+    # Build a dataset from the fixed-schema JSON document accepted by the
+    # C layer (an array of {ts, open, high, low, close} objects).
+    def self.from_json(text)
+      json = FFI.cstr(text)
+      out = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP)
+      status = FFI::PARSE_JSON.call(json, out)
+      _from_data_status(status, out)
+    end
+
+    # Build a dataset from CSV rows of `open,high,low,close[,timestamp]`.
+    def self.from_csv(text, value_separator: ",", line_separator: "\n")
+      csv = FFI.cstr(text)
+      vs = value_separator.ord
+      ls = line_separator.ord
+      raise Error, "separators must not be NUL" if vs == 0 || ls == 0
+      out = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP)
+      status = FFI::PARSE_CSV.call(csv, vs, ls, out)
+      _from_data_status(status, out)
+    end
+
+    def self._from_data_status(status, out)
+      Ccharts.raise_on(status)
+      addr = FFI.read_ptr_int(out, Fiddle::SIZEOF_VOIDP)
+      raise Error, "no dataset handle returned" if addr.zero?
+      _from_handle(Fiddle::Pointer.new(addr))
+    end
+
+    # ------------------------------------------------------------------
+    # Rendering an OHLC dataset (line / candle)
+    # ------------------------------------------------------------------
+
+    def line(width, height, settings = nil)
+      _render(FFI::LINE, width, height, settings || Settings::ChartSettings.new)
+    end
+
+    def candle(width, height, settings = nil)
+      _render(FFI::CANDLE, width, height, settings || Settings::ChartSettings.new)
+    end
+
+    # Number of candles in this dataset.
+    def size
+      FFI::DATA_LEN.call(@handle)
+    end
+    alias_method :length, :size
+
+    # ------------------------------------------------------------------
+    # Pie / histogram / sparkline / bar / stack / heat / box renderers
+    # ------------------------------------------------------------------
+
+    def self.pie(slices, width, height, settings = nil)
+      raise Error, "need at least one slice" if slices.empty?
+      settings ||= Settings::PieSettings.new
+
+      keep = []
+      rows = slices.map do |sl|
+        label = sl[:label] || sl["label"]
+        value = (sl[:value] || sl["value"] || 0.0).to_f
+        lp = FFI.cstr(label)
+        keep << lp
+        [[0, 8, "Q", lp.to_i], [8, 8, "d", value]] # label @0, value @8
+      end
+      slices_ptr = FFI.contiguous_structs(16, rows) # ccharts_pie_slice = 16 B
+      keep << slices_ptr
+
+      colors_ptr_addr = settings.colors_ptr(keep).to_i
+      center_ptr = settings.center_text_ptr(keep)
+      donut, show_legend, show_pct, slice_gap, inner_radius_ratio,
+        legend_format, start_angle, counter_clockwise = settings._scalars
+
+      # `_scalars` already returns the flags as C ints 0/1 — pass them straight
+      # through. Do NOT write `x ? 1 : 0` here: in Ruby `0` is truthy, so a
+      # zeroed flag would be coerced to 1 (pct/ccw always on → mirrored pie).
+      _read_string(
+        FFI::PIE, slices_ptr, slices.length, width, height,
+        donut, colors_ptr_addr, settings.colors_count,
+        show_legend, show_pct,
+        slice_gap, inner_radius_ratio, legend_format,
+        start_angle, counter_clockwise, center_ptr
+      )
+    end
+
+    def self.histogram(samples, width, height, settings = nil)
+      raise Error, "need at least one sample" if samples.empty?
+      settings ||= Settings::HistSettings.new
+      ptr = FFI.pack_doubles(samples)
+      s, keep = settings.to_ffi
+      _read_string(FFI::HIST, ptr, samples.length, width, height, s.to_ptr)
+    end
+
+    def self.sparkline(samples, width, height, settings = nil)
+      raise Error, "need at least one sample" if samples.empty?
+      settings ||= Settings::SparkSettings.new
+      ptr = FFI.pack_doubles(samples)
+      s, keep = settings.to_ffi
+      _read_string(FFI::SPARK, ptr, samples.length, width, height, s.to_ptr)
+    end
+
+    def self.bar(labels, values, width, height, settings = nil)
+      raise Error, "need at least one bar" if labels.empty?
+      raise Error, "labels and values must have the same length" unless labels.length == values.length
+      settings ||= Settings::BarSettings.new
+
+      keep = []
+      rows = labels.zip(values).map do |lbl, val|
+        lp = FFI.cstr(lbl)
+        keep << lp
+        [[0, 8, "Q", lp.to_i], [8, 8, "d", val.to_f]] # label @0, value @8
+      end
+      items_ptr = FFI.contiguous_structs(16, rows) # ccharts_bar_slice = 16 B
+      keep << items_ptr
+      s, skeep = settings.to_ffi
+      keep.concat(skeep)
+      _read_string(FFI::BAR, items_ptr, labels.length, width, height, s.to_ptr)
+    end
+
+    # series: array of {name:, values:} hashes sharing one category count.
+    def self.stacked_bar(series, width, height, settings = nil)
+      raise Error, "need at least one series" if series.empty?
+      cats = series[0][:values]&.length || series[0]["values"].length
+      raise Error, "series values must not be empty" if cats == 0
+      series.each do |sv|
+        vs = sv[:values] || sv["values"]
+        raise Error, "all series must have the same number of values" unless vs.length == cats
+      end
+      settings ||= Settings::StackSettings.new
+      settings.counts(series.length, cats)
+
+      keep = []
+      rows = series.map do |sv|
+        vs = sv[:values] || sv["values"]
+        name = sv[:name] || sv["name"]
+        np = FFI.cstr(name)
+        vp = FFI.pack_doubles(vs)
+        keep << np << vp
+        [[0, 8, "Q", np.to_i], [8, 8, "Q", vp.to_i]] # name @0, values @8
+      end
+      series_ptr = FFI.contiguous_structs(16, rows) # ccharts_stack_series = 16 B
+      keep << series_ptr
+      s, skeep = settings.to_ffi
+      keep.concat(skeep)
+      _read_string(FFI::STACK, series_ptr, series.length, width, height, s.to_ptr)
+    end
+
+    # values: a rows x cols matrix (array of equal-length arrays).
+    def self.heatmap(values, width, height, settings = nil)
+      raise Error, "need a non-empty value matrix" if values.empty?
+      cols = values[0].length
+      raise Error, "matrix columns must not be empty" if cols == 0
+      values.each { |row| raise Error, "all rows must have the same number of values" unless row.length == cols }
+      settings ||= Settings::HeatSettings.new
+
+      flat = values.flatten
+      flat_ptr = FFI.pack_doubles(flat)
+      s, keep = settings.to_ffi
+      _read_string(FFI::HEAT, flat_ptr, values.length, cols, width, height, s.to_ptr)
+    end
+
+    # series: array of {name:, samples:} hashes (per-category samples).
+    def self.boxplot(series, width, height, settings = nil)
+      raise Error, "need at least one category" if series.empty?
+      series.each do |c|
+        sm = c[:samples] || c["samples"]
+        raise Error, "every category must have at least one sample" if sm.empty?
+      end
+      settings ||= Settings::BoxSettings.new
+
+      keep = []
+      rows = series.map do |c|
+        sm = c[:samples] || c["samples"]
+        name = c[:name] || c["name"]
+        np = FFI.cstr(name)
+        sp = FFI.pack_doubles(sm)
+        keep << np << sp
+        [[0, 8, "Q", np.to_i], [8, 8, "Q", sp.to_i], [16, 4, "l", sm.length]] # name@0, samples@8, n@16 (24 B)
+      end
+      cats_ptr = FFI.contiguous_structs(24, rows) # ccharts_box_category = 24 B
+      keep << cats_ptr
+      s, skeep = settings.to_ffi
+      keep.concat(skeep)
+      _read_string(FFI::BOX, cats_ptr, series.length, width, height, s.to_ptr)
+    end
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def self._from_handle(handle)
+      obj = allocate
+      obj.instance_variable_set(:@handle, handle)
+      ObjectSpace.define_finalizer(obj, _finalizer(handle.to_i))
+      obj
+    end
+
+    def self._finalizer(addr)
+      proc { FFI::DATA_FREE.call(Fiddle::Pointer.new(addr)) }
+    end
+
+    def _render(fn, width, height, settings)
+      s, = settings.to_ffi
+      self.class._read_string(fn, @handle, width, height, s.to_ptr)
+    end
+
+    # Call a render function and copy the returned C string, releasing it.
+    def self._read_string(fn, *args)
+      out = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP)
+      out_len = Fiddle::Pointer.malloc(Fiddle::SIZEOF_SIZE_T)
+      status = fn.call(*args, out, out_len)
+      Ccharts.raise_on(status)
+      addr = FFI.read_ptr_int(out, Fiddle::SIZEOF_VOIDP)
+      len = FFI.read_ptr_int(out_len, Fiddle::SIZEOF_SIZE_T)
+      s = Fiddle::Pointer.new(addr).to_s(len).force_encoding("UTF-8")
+      FFI::STRING_FREE.call(Fiddle::Pointer.new(addr))
+      s
+    end
+    private_class_method :_from_handle, :_from_data_status, :_finalizer
+    private :_render
+  end
+end

data/lib/ccharts/color.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Ccharts
+  # ANSI color escapes matching the C library's ccharts_color_index values
+  # (abi/ccharts_abi.h). These come straight from the library: a binding passes
+  # the escape string (or NULL for the library default) through the settings
+  # structs, so every binding resolves the same names to the same escapes.
+  module Color
+    ESCAPES = {
+      "black"        => "\e[30m",
+      "red"          => "\e[31m",
+      "green"        => "\e[32m",
+      "yellow"       => "\e[33m",
+      "blue"         => "\e[34m",
+      "magenta"      => "\e[35m",
+      "cyan"         => "\e[36m",
+      "white"        => "\e[37m",
+      "bright_black" => "\e[90m",
+      "bright_red"   => "\e[91m",
+      "bright_green" => "\e[92m",
+      "bright_yellow"=> "\e[93m",
+      "bright_blue"  => "\e[94m",
+      "bright_magenta"=> "\e[95m",
+      "bright_cyan"  => "\e[96m",
+      "bright_white" => "\e[97m",
+      "reset"        => "\e[0m",
+    }.freeze
+
+    # Resolve a color given either a name ("blue"), a Symbol (:blue), or a raw
+    # ANSI escape sequence (256-color/truecolor strings passed straight through).
+    # Returns the escape string, or nil if the value is nil/empty (library
+    # default). Unknown names fall back to the literal string so raw escapes
+    # keep working.
+    def self.resolve(value)
+      return nil if value.nil?
+      s = value.to_s
+      return nil if s.empty?
+      ESCAPES[s] || s
+    end
+
+    # The ANSI escape for a named color, or nil when unknown.
+    def self.[](name)
+      ESCAPES[name.to_s]
+    end
+  end
+end

data/lib/ccharts/ffi.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "fiddle"
+require "fiddle/import"
+require "rbconfig"
+
+module Ccharts
+  # Raw Fiddle bindings to the vendored ccharts ABI (ext/ccharts/vendor).
+  #
+  # The extension (ccharts_ext.so) is built from ext/ccharts/vendor/ccharts_abi.c
+  # by mkmf — it is pure object code, so Fiddle just dlopens it and resolves
+  # the 20 ccharts_* symbols below. The struct layouts mirror abi/ccharts_abi.h
+  # exactly (field order + C alignment); a mismatch shows up as a conformance
+  # failure, not a crash.
+  module FFI
+    extend Fiddle::Importer
+
+    DLEXT = RbConfig::CONFIG["DLEXT"] # e.g. "so"
+
+    # ---- native library location ---------------------------------------
+    def self.native_candidates
+      lib_dir = File.expand_path("..", __dir__)           # .../lib
+      here = __dir__                                      # .../lib/ccharts
+      repo_ext = File.expand_path("../../ext/ccharts", here) # repo build dir
+      [
+        File.join(lib_dir, "ccharts_ext.#{DLEXT}"),       # dev build drops it in lib/
+        File.join(here, "ccharts_ext.#{DLEXT}"),          # some install layouts
+        File.join(repo_ext, "ccharts_ext.#{DLEXT}"),      # built in-place
+      ]
+    end
+
+    LIB = begin
+      path = native_candidates.find { |p| File.file?(p) }
+      raise LoadError, "ccharts native (ccharts_ext.#{DLEXT}) not built — run `rake compile` (or the Rakefile :compile task) first" unless path
+      Fiddle.dlopen(path)
+    end
+
+    # ---- type constants -------------------------------------------------
+    T_VOID   = Fiddle::TYPE_VOID
+    T_VOIDP  = Fiddle::TYPE_VOIDP
+    T_INT    = Fiddle::TYPE_INT
+    T_DOUBLE = Fiddle::TYPE_DOUBLE
+    T_CHAR   = Fiddle::TYPE_CHAR
+    T_LL     = Fiddle::TYPE_LONG_LONG
+
+    def self.fn(name, args, ret)
+      Fiddle::Function.new(LIB[name], args, ret)
+    end
+
+    # ---- the 20 exported ccharts_* functions ----------------------------
+    FROM_ARRAYS  = fn("ccharts_from_arrays", [T_VOIDP, T_VOIDP, T_VOIDP, T_VOIDP, T_VOIDP, T_INT, T_VOIDP], T_INT)
+    PARSE_JSON   = fn("ccharts_parse_json", [T_VOIDP, T_VOIDP], T_INT)
+    PARSE_CSV    = fn("ccharts_parse_csv", [T_VOIDP, T_CHAR, T_CHAR, T_VOIDP], T_INT)
+    DATA_LEN     = fn("ccharts_data_len", [T_VOIDP], T_INT)
+    DATA_FREE    = fn("ccharts_data_free", [T_VOIDP], T_VOID)
+    STRING_FREE  = fn("ccharts_string_free", [T_VOIDP], T_VOID)
+    LINE         = fn("ccharts_line", [T_VOIDP, T_INT, T_INT, T_VOIDP, T_VOIDP, T_VOIDP], T_INT)
+    CANDLE       = fn("ccharts_candle", [T_VOIDP, T_INT, T_INT, T_VOIDP, T_VOIDP, T_VOIDP], T_INT)
+    PIE          = fn("ccharts_pie_from_slices",
+                      [T_VOIDP, T_INT, T_INT, T_INT, T_INT, T_VOIDP, T_INT, T_INT, T_INT,
+                       T_DOUBLE, T_DOUBLE, T_INT, T_DOUBLE, T_INT, T_VOIDP, T_VOIDP, T_VOIDP], T_INT)
+    HIST         = fn("ccharts_hist", [T_VOIDP, T_INT, T_INT, T_INT, T_VOIDP, T_VOIDP, T_VOIDP], T_INT)
+    SPARK        = fn("ccharts_spark", [T_VOIDP, T_INT, T_INT, T_INT, T_VOIDP, T_VOIDP, T_VOIDP], T_INT)
+    BAR          = fn("ccharts_bar", [T_VOIDP, T_INT, T_INT, T_INT, T_VOIDP, T_VOIDP, T_VOIDP], T_INT)
+    STACK        = fn("ccharts_stack", [T_VOIDP, T_INT, T_INT, T_INT, T_VOIDP, T_VOIDP, T_VOIDP], T_INT)
+    HEAT         = fn("ccharts_heat", [T_VOIDP, T_INT, T_INT, T_INT, T_INT, T_VOIDP, T_VOIDP, T_VOIDP], T_INT)
+    BOX          = fn("ccharts_box", [T_VOIDP, T_INT, T_INT, T_INT, T_VOIDP, T_VOIDP, T_VOIDP], T_INT)
+    COLOR        = fn("ccharts_color", [T_INT], T_VOIDP)
+    ERROR_MSG    = fn("ccharts_error_message", [T_INT], T_VOIDP)
+    VERSION      = fn("ccharts_version", [], T_VOIDP)
+    MAX_DIM      = fn("ccharts_max_dim", [], T_INT)
+    MAX_CELLS    = fn("ccharts_max_cells", [], T_INT)
+
+    # ---- settings structs (layouts from abi/ccharts_abi.h) --------------
+    # Every color is a pointer (void*); ints are int32. The Fiddle importer
+    # applies the same alignment/padding rules as the C compiler, so these
+    # match the ABI byte-for-byte.
+    Settings = struct [
+      "void* rise_color",
+      "void* fall_color",
+      "void* bg_color",
+      "void* area_color",
+      "int single_color",
+      "int show_prices",
+      "int show_times",
+    ]
+
+    PieSlice = struct [
+      "void* label",
+      "double value",
+    ]
+
+    HistSettings = struct [
+      "void* rise_color",
+      "void* bg_color",
+      "int bin_count",
+      "double min_value",
+      "double max_value",
+      "int show_bins",
+      "int show_prices",
+    ]
+
+    SparkSettings = struct [
+      "void* rise_color",
+      "void* area_color",
+      "int min_above",
+      "int min_below",
+    ]
+
+    BarSlice = struct [
+      "void* label",
+      "double value",
+    ]
+
+    BarSettings = struct [
+      "void* rise_color",
+      "void* bg_color",
+      "int show_labels",
+      "int show_prices",
+    ]
+
+    StackSeries = struct [
+      "void* name",
+      "void* values",
+    ]
+
+    StackSettings = struct [
+      "void* colors",
+      "void* bg_color",
+      "void* cat_labels",
+      "int series",
+      "int cats",
+      "int show_labels",
+      "int show_prices",
+    ]
+
+    HeatSettings = struct [
+      "void* low_color",
+      "void* high_color",
+      "void* mid_color",
+      "void* bg_color",
+      "void* row_labels",
+      "void* col_labels",
+      "int show_labels",
+    ]
+
+    BoxCategory = struct [
+      "void* name",
+      "void* samples",
+      "int n",
+    ]
+
+    BoxSettings = struct [
+      "void* rise_color",
+      "void* area_color",
+      "void* bg_color",
+      "int show_prices",
+    ]
+
+    # ---- helpers ---------------------------------------------------------
+    # A never-referenced empty string (plain mode: no ANSI escape at all).
+    EMPTY = Fiddle::Pointer["\0"]
+
+    # Turn a color value into a NUL-terminated escape pointer. `plain` forces
+    # the empty escape (overriding even a caller color) so no ANSI bytes are
+    # emitted. nil -> 0 (library default); else the resolved escape string.
+    def self.color_ptr(value, plain)
+      return EMPTY if plain
+      esc = Color.resolve(value)
+      return Fiddle::NULL if esc.nil?
+      Fiddle::Pointer[esc.b + "\0"]
+    end
+
+    # Pack a Ruby array of doubles into a C double[] pointer.
+    def self.pack_doubles(arr)
+      Fiddle::Pointer[arr.pack("d*")]
+    end
+
+    # Build ONE contiguous C array of `count` structs, each `size` bytes, so a
+    # `const ccharts_foo*`/array-of-structs argument points at a real C-layout
+    # block (`&arr[i]` is at `base + i*size`). Do NOT pass an array of pointers
+    # to separately-malloc'd structs — C reads this as a contiguous block and a
+    # pointer-array makes it read garbage at offset `i*size` (segfault / wrong
+    # data). `rows` is one entry per element: an array of `[offset, nbytes,
+    # pack_fmt, value]` field setters relative to that element's base.
+    def self.contiguous_structs(size, rows)
+      block = Fiddle::Pointer.malloc(size * rows.length)
+      rows.each_with_index do |fields, i|
+        base = i * size
+        fields.each { |off, nbytes, fmt, val| block[base + off, nbytes] = [val].pack(fmt) }
+      end
+      block
+    end
+
+    # Pack a Ruby array of integers into a C int64_t[] pointer.
+    def self.pack_i64(arr)
+      Fiddle::Pointer[arr.pack("q*")]
+    end
+
+    # NUL-terminated pointer for a Ruby string (or Fiddle::NULL for nil).
+    def self.cstr(str)
+      return Fiddle::NULL if str.nil?
+      Fiddle::Pointer[str.b + "\0"]
+    end
+
+    # Read a C string (NUL-terminated) from a returned pointer.
+    def self.read_cstr(ptr)
+      return nil if ptr.nil? || ptr.to_i == 0
+      ptr.to_s
+    end
+
+    # Read the integer value pointed to by a Fiddle::Pointer of the given size.
+    def self.read_ptr_int(buf, size)
+      buf[0, size].unpack1(size == 8 ? "Q" : "L")
+    end
+  end
+end