teek 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4a6639b7742fe7c1be6b94ddb2e7ea7e5f65f66d4525931f5a916a92ebe45a90
+  data.tar.gz: 0ef9c6a423201a35123193b951577f6f1aa2e375cbabdd20d5d34a35bdd47335
+SHA512:
+  metadata.gz: 252f099b49231033ba5b59d7108c79f920247e357d80ac236b2ead0772b09e5af9aa023855b91597d73586e1c9d78a16724f8d57d7a1d12cddb082ce35e23de7
+  data.tar.gz: bb50dfed0ede92e95c55a74a047a9382498605579c28c6a874cbd5837ceb5a4e13d94b1360446dca0af22ab556a35c9e9ea7919f10235fb4332f52c7f1529129

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in teek.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present James Cook
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,139 @@
+# Teek
+
+A Ruby interface to Tcl/Tk.
+
+[API Documentation](https://jamescook.github.io/teek/)
+
+## Quick Start
+
+```ruby
+require 'teek'
+
+app = Teek::App.new
+
+app.show
+app.tcl_eval('wm title . "Hello Teek"')
+
+# Create widgets with tcl_eval
+app.tcl_eval('ttk::label .lbl -text "Hello, world!"')
+app.tcl_eval('pack .lbl -pady 10')
+
+# Or use the command helper — Ruby values are auto-quoted,
+# symbols pass through bare, and procs become callbacks
+app.command('ttk::button', '.btn', text: 'Click me', command: proc {
+  app.command('.lbl', :configure, text: 'Clicked!')
+})
+app.command(:pack, '.btn', pady: 10)
+
+app.mainloop
+```
+
+## Callbacks
+
+Register Ruby procs as Tcl callbacks using `app.register_callback`:
+
+```ruby
+app = Teek::App.new
+
+cb = app.register_callback(proc { |*args|
+  puts "clicked!"
+})
+app.tcl_eval("button .b -text Click -command {ruby_callback #{cb}}")
+```
+
+### Stopping event propagation
+
+In `bind` handlers, you can stop an event from propagating to subsequent binding tags by throwing `:teek_break`:
+
+```ruby
+cb = app.register_callback(proc { |*|
+  puts "handled - stop here"
+  throw :teek_break
+})
+app.tcl_eval("bind .entry <Key-Return> {ruby_callback #{cb}}")
+```
+
+This is equivalent to Tcl's `break` command in a bind script.
+
+Two other control flow signals are available for advanced use:
+
+- `throw :teek_continue` - skip remaining bind scripts for this event (Tcl `continue`)
+- `throw :teek_return` - return from the current Tcl proc (Tcl `return`)
+
+### Errors in callbacks
+
+If a callback raises a Ruby exception, it becomes a Tcl error. The exception message is preserved and can be caught on the Tcl side with `catch`.
+
+## List operations
+
+Convert between Ruby arrays and Tcl list strings:
+
+```ruby
+# Ruby array → Tcl list string (properly quoted)
+Teek.make_list("hello world", "foo", "bar baz")
+# => "{hello world} foo {bar baz}"
+
+# Tcl list string → Ruby array
+Teek.split_list("{hello world} foo {bar baz}")
+# => ["hello world", "foo", "bar baz"]
+```
+
+Also available as `app.make_list` and `app.split_list` on an interpreter instance.
+
+## Boolean conversion
+
+Convert between Tcl boolean strings and Ruby booleans:
+
+```ruby
+# Tcl boolean string → Ruby bool
+Teek.tcl_to_bool("yes")   # => true
+Teek.tcl_to_bool("0")     # => false
+
+# Ruby bool → Tcl boolean string
+Teek.bool_to_tcl(true)    # => "1"
+Teek.bool_to_tcl(nil)     # => "0"
+```
+
+`tcl_to_bool` recognizes all Tcl boolean forms: `true`/`false`, `yes`/`no`, `on`/`off`, `1`/`0`, and numeric values (case-insensitive).
+
+## Tcl Packages
+
+Load external Tcl packages (BWidget, tkimg, etc.):
+
+```ruby
+app.require_package('BWidget')
+app.require_package('BWidget', '1.9')  # with version constraint
+```
+
+For packages in non-standard locations:
+
+```ruby
+app.add_package_path('/path/to/packages')
+app.require_package('mypackage')
+```
+
+Query what's available:
+
+```ruby
+app.package_names          # => ["Tk", "BWidget", ...]
+app.package_present?('Tk') # => true
+app.package_versions('Tk') # => ["9.0.1"]
+```
+
+## Debugger
+
+Pass `debug: true` to open a debugger window alongside your app:
+
+```ruby
+app = Teek::App.new(debug: true)
+```
+
+Or set the `TEEK_DEBUG` environment variable to enable it without changing code.
+
+The debugger provides three tabs:
+
+- **Widgets** — live tree of all widgets with a detail panel showing configuration
+- **Variables** — all global Tcl variables with search/filter, auto-refreshes every second
+- **Watches** — right-click or double-click a variable to watch it; tracks last 50 values with timestamps
+
+The debugger runs in the same interpreter as your app (as a [Toplevel](https://www.tcl-lang.org/man/tcl8.6/TkCmd/toplevel.htm) window) and filters its own widgets from `app.widgets`.

data/Rakefile

@@ -0,0 +1,316 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+require 'rake/clean'
+
+# Documentation tasks - all doc gems are in docs_site/Gemfile
+namespace :docs do
+  desc "Install docs dependencies (docs_site/Gemfile)"
+  task :setup do
+    Dir.chdir('docs_site') do
+      Bundler.with_unbundled_env { sh 'bundle install' }
+    end
+  end
+
+  task :yard_clean do
+    FileUtils.rm_rf('doc')
+    FileUtils.rm_rf('docs_site/_api')
+    FileUtils.rm_rf('docs_site/_site')
+    FileUtils.rm_rf('docs_site/.jekyll-cache')
+    FileUtils.rm_f('docs_site/assets/js/search-data.json')
+  end
+
+  desc "Generate YARD JSON (uses docs_site/Gemfile)"
+  task yard_json: :yard_clean do
+    Bundler.with_unbundled_env do
+      sh 'BUNDLE_GEMFILE=docs_site/Gemfile bundle exec yard doc'
+    end
+  end
+
+  desc "Generate API docs (YARD JSON -> HTML)"
+  task yard: :yard_json do
+    Bundler.with_unbundled_env do
+      sh 'BUNDLE_GEMFILE=docs_site/Gemfile bundle exec ruby docs_site/build_api_docs.rb'
+    end
+  end
+
+  desc "Bless recordings from recordings/ into docs_site/assets/recordings/"
+  task :bless_recordings do
+    require 'fileutils'
+    src = 'recordings'
+    dest = 'docs_site/assets/recordings'
+    FileUtils.mkdir_p(dest)
+    videos = Dir.glob("#{src}/*.{mp4,webm}")
+    if videos.empty?
+      puts "No recordings in #{src}/ to bless."
+      next
+    end
+    videos.each do |path|
+      FileUtils.cp(path, dest)
+      puts "  #{File.basename(path)} -> #{dest}/"
+    end
+    puts "Blessed #{videos.size} recording(s)."
+  end
+
+  desc "Generate recordings gallery page"
+  task :recordings do
+    sh 'ruby docs_site/build_recordings.rb'
+  end
+
+  desc "Generate full docs site (YARD + Jekyll)"
+  task generate: [:yard, :recordings] do
+    Dir.chdir('docs_site') do
+      Bundler.with_unbundled_env { sh 'bundle exec jekyll build' }
+    end
+    puts "Docs generated in docs_site/_site/"
+  end
+
+  desc "Serve docs locally"
+  task serve: [:yard, :recordings] do
+    Dir.chdir('docs_site') do
+      Bundler.with_unbundled_env { sh 'bundle exec jekyll serve' }
+    end
+  end
+end
+
+# Aliases for convenience
+task doc: 'docs:yard'
+task yard: 'docs:yard'
+
+# Compiling on macOS with Homebrew:
+#
+# Tcl/Tk 9.0:
+#   rake clean && rake compile -- --with-tcltkversion=9.0 \
+#     --with-tcl-lib=$(brew --prefix tcl-tk)/lib \
+#     --with-tcl-include=$(brew --prefix tcl-tk)/include/tcl-tk \
+#     --with-tk-lib=$(brew --prefix tcl-tk)/lib \
+#     --with-tk-include=$(brew --prefix tcl-tk)/include/tcl-tk \
+#     --without-X11
+#
+# Tcl/Tk 8.6:
+#   rake clean && rake compile -- --with-tcltkversion=8.6 \
+#     --with-tcl-lib=$(brew --prefix tcl-tk@8)/lib \
+#     --with-tcl-include=$(brew --prefix tcl-tk@8)/include \
+#     --with-tk-lib=$(brew --prefix tcl-tk@8)/lib \
+#     --with-tk-include=$(brew --prefix tcl-tk@8)/include \
+#     --without-X11
+
+# Clean up extconf cached config files
+CLEAN.include('ext/teek/config_list')
+CLOBBER.include('tmp', 'lib/*.bundle', 'lib/*.so', 'ext/**/*.o', 'ext/**/*.bundle', 'ext/**/*.bundle.dSYM')
+
+# Clean coverage artifacts before test runs to prevent accumulation
+CLEAN.include('coverage/.resultset.json', 'coverage/results')
+
+# Conditionally load rake-compiler
+if Gem::Specification.find_all_by_name('rake-compiler').any?
+  require 'rake/extensiontask'
+  Rake::ExtensionTask.new do |ext|
+    ext.name = 'tcltklib'
+    ext.ext_dir = 'ext/teek'
+    ext.lib_dir = 'lib'
+  end
+end
+
+desc "Clear stale coverage artifacts"
+task :clean_coverage do
+  require 'fileutils'
+  FileUtils.rm_f('coverage/.resultset.json')
+  FileUtils.rm_rf('coverage/results')
+  FileUtils.mkdir_p('coverage/results')
+end
+
+namespace :coverage do
+  desc "Collate coverage results from multiple test runs into a single report"
+  task :collate do
+    require 'simplecov'
+    require 'simplecov_json_formatter'
+    require_relative 'test/simplecov_config'
+
+    result_files = Dir['coverage/results/*/.resultset.json']
+    if result_files.empty?
+      puts "No coverage results found in coverage/results/"
+      next
+    end
+
+    puts "Collating coverage from: #{result_files.map { |f| File.dirname(f).split('/').last }.join(', ')}"
+
+    SimpleCov.collate(result_files) do
+      coverage_dir 'coverage'
+      formatter SimpleCov::Formatter::MultiFormatter.new([
+        SimpleCov::Formatter::HTMLFormatter,
+        SimpleCov::Formatter::JSONFormatter
+      ])
+      SimpleCovConfig.apply_filters(self)
+      SimpleCovConfig.apply_groups(self)
+    end
+
+    puts "Coverage report generated: coverage/index.html, coverage/coverage.json"
+  end
+
+  desc "Full coverage pipeline: collate results"
+  task :full => :collate
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/test_*.rb']
+  t.verbose = true
+end
+
+task test: [:compile, :clean_coverage]
+
+def detect_platform
+  case RUBY_PLATFORM
+  when /darwin/ then 'darwin'
+  when /linux/ then 'linux'
+  when /mingw|mswin/ then 'windows'
+  else 'unknown'
+  end
+end
+
+task :default => :compile
+
+# Docker tasks for local testing and CI
+namespace :docker do
+  DOCKERFILE = 'Dockerfile.ci-test'
+  DOCKER_LABEL = 'project=teek'
+
+  def docker_image_name(tcl_version, ruby_version = nil)
+    ruby_version ||= ruby_version_from_env
+    base = tcl_version == '8.6' ? 'teek-ci-test-8' : 'teek-ci-test-9'
+    ruby_version == '4.0' ? base : "#{base}-ruby#{ruby_version}"
+  end
+
+  def tcl_version_from_env
+    version = ENV.fetch('TCL_VERSION', '9.0')
+    unless ['8.6', '9.0'].include?(version)
+      abort "Invalid TCL_VERSION='#{version}'. Must be '8.6' or '9.0'."
+    end
+    version
+  end
+
+  def ruby_version_from_env
+    ENV.fetch('RUBY_VERSION', '4.0')
+  end
+
+  desc "Build Docker image (TCL_VERSION=9.0|8.6, RUBY_VERSION=3.4|4.0|...)"
+  task :build do
+    tcl_version = tcl_version_from_env
+    ruby_version = ruby_version_from_env
+    image_name = docker_image_name(tcl_version, ruby_version)
+
+    verbose = ENV['VERBOSE'] || ENV['V']
+    quiet = !verbose
+    if quiet
+      puts "Building Docker image for Ruby #{ruby_version}, Tcl #{tcl_version}... (VERBOSE=1 for details)"
+    else
+      puts "Building Docker image for Ruby #{ruby_version}, Tcl #{tcl_version}..."
+    end
+    cmd = "docker build -f #{DOCKERFILE}"
+    cmd += " -q" if quiet
+    cmd += " --label #{DOCKER_LABEL}"
+    cmd += " --build-arg RUBY_VERSION=#{ruby_version}"
+    cmd += " --build-arg TCL_VERSION=#{tcl_version}"
+    cmd += " -t #{image_name} ."
+
+    sh cmd, verbose: !quiet
+  end
+
+  desc "Run tests in Docker (TCL_VERSION=9.0|8.6, RUBY_VERSION=3.4|4.0|..., TEST=path/to/test.rb)"
+  task test: :build do
+    tcl_version = tcl_version_from_env
+    ruby_version = ruby_version_from_env
+    image_name = docker_image_name(tcl_version, ruby_version)
+
+    require 'fileutils'
+    FileUtils.mkdir_p('coverage')
+
+    puts "Running tests in Docker (Ruby #{ruby_version}, Tcl #{tcl_version})..."
+    cmd = "docker run --rm --init"
+    cmd += " -v #{Dir.pwd}/coverage:/app/coverage"
+    cmd += " -e TCL_VERSION=#{tcl_version}"
+    cmd += " -e TEST='#{ENV['TEST']}'" if ENV['TEST']
+    cmd += " -e TESTOPTS='#{ENV['TESTOPTS']}'" if ENV['TESTOPTS']
+    if ENV['COVERAGE'] == '1'
+      cmd += " -e COVERAGE=1"
+      cmd += " -e COVERAGE_NAME=#{ENV['COVERAGE_NAME'] || 'main'}"
+    end
+    cmd += " #{image_name}"
+
+    sh cmd
+  end
+
+  desc "Run interactive shell in Docker (TCL_VERSION=9.0|8.6, RUBY_VERSION=3.4|4.0|...)"
+  task shell: :build do
+    tcl_version = tcl_version_from_env
+    ruby_version = ruby_version_from_env
+    image_name = docker_image_name(tcl_version, ruby_version)
+
+    cmd = "docker run --rm --init -it"
+    cmd += " -v #{Dir.pwd}/coverage:/app/coverage"
+    cmd += " -e TCL_VERSION=#{tcl_version}"
+    cmd += " #{image_name} bash"
+
+    sh cmd
+  end
+
+  desc "Remove dangling Docker images from teek builds"
+  task :prune do
+    sh "docker image prune -f --filter label=#{DOCKER_LABEL}"
+  end
+
+  Rake::Task['docker:test'].enhance { Rake::Task['docker:prune'].invoke }
+
+  # Scan sample files for # teek-record magic comment
+  # Format: # teek-record: title=My Demo, codec=vp9
+  def find_recordable_samples
+    Dir['sample/**/*.rb'].filter_map do |path|
+      first_lines = File.read(path, 500)
+      match = first_lines.match(/^#\s*teek-record(?::\s*(.+))?$/)
+      next unless match
+
+      options = {}
+      if match[1]
+        match[1].split(',').each do |pair|
+          key, value = pair.strip.split('=', 2)
+          options[key.strip] = value&.strip if key
+        end
+      end
+      options['sample'] = path
+      options
+    end
+  end
+
+  desc "Record demos in Docker (TCL_VERSION=9.0|8.6, DEMO=sample/foo.rb)"
+  task record_demos: :build do
+    require 'fileutils'
+    FileUtils.mkdir_p('recordings')
+
+    demos = if ENV['DEMO']
+              find_recordable_samples.select { |d| d['sample'] == ENV['DEMO'] }
+            else
+              find_recordable_samples
+            end
+
+    if demos.empty?
+      puts "No recordable samples found. Add '# teek-record' comment to samples."
+      next
+    end
+
+    demos.each do |demo|
+      sample = demo['sample']
+      codec = ENV['CODEC'] || demo['codec'] || 'x264'
+      name = demo['name']
+
+      puts
+      puts "Recording #{sample} (#{codec})..."
+      env = "CODEC=#{codec}"
+      env += " NAME=#{name}" if name
+      sh "#{env} ./scripts/docker-record.sh #{sample}"
+    end
+
+    puts "Done! Recordings in: recordings/"
+  end
+
+  Rake::Task['docker:record_demos'].enhance { Rake::Task['docker:prune'].invoke }
+end

data/ext/teek/extconf.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+
+# Always use stubs - no option to disable
+$CFLAGS << " -DUSE_TCL_STUBS -DUSE_TK_STUBS"
+
+def find_tcltk
+  # Try pkg-config first
+  tcl_found = pkg_config('tcl') || pkg_config('tcl9.0') || pkg_config('tcl8.6')
+  tk_found = pkg_config('tk') || pkg_config('tk9.0') || pkg_config('tk8.6')
+
+  unless tcl_found && tk_found
+    # Manual search paths
+    tcl_dirs = [
+      '/opt/homebrew/opt/tcl-tk',
+      '/usr/local/opt/tcl-tk',
+      '/usr/local',
+      '/usr'
+    ]
+
+    tcl_dirs.each do |dir|
+      inc = "#{dir}/include"
+      lib = "#{dir}/lib"
+      # Check for tcl-tk subdirectory (Homebrew layout)
+      if File.exist?("#{inc}/tcl-tk/tcl.h")
+        inc = "#{inc}/tcl-tk"
+      end
+      if File.exist?("#{inc}/tcl.h") && File.exist?("#{inc}/tk.h")
+        $INCFLAGS << " -I#{inc}"
+        $LDFLAGS << " -L#{lib}"
+        break
+      end
+    end
+  end
+
+  # Check for required headers
+  have_header('tcl.h') or abort "tcl.h not found"
+  have_header('tk.h') or abort "tk.h not found"
+
+  # Link against STUB libraries, not main libraries
+  # Try versioned stub names first, then unversioned
+  tcl_stub = have_library('tclstub9.0') ||
+             have_library('tclstub8.6') ||
+             have_library('tclstub')
+
+  tk_stub = have_library('tkstub9.0') ||
+            have_library('tkstub8.6') ||
+            have_library('tkstub')
+
+  # MSYS2/MinGW uses names without dots (tclstub86 instead of tclstub8.6)
+  if RbConfig::CONFIG['host_os'] =~ /mingw|mswin/
+    tcl_stub ||= have_library('tclstub90') || have_library('tclstub86')
+    tk_stub ||= have_library('tkstub90') || have_library('tkstub86')
+  end
+
+  # If stub libraries not found by simple name, try via pkg-config
+  unless tcl_stub
+    # pkg-config may have added them already via --libs
+    # Check if we can find the stubs table
+    if try_link(<<~CODE)
+      #define USE_TCL_STUBS
+      #include <tcl.h>
+      int main() { return 0; }
+    CODE
+      tcl_stub = true
+    end
+  end
+
+  abort "Tcl stub library not found" unless tcl_stub
+  abort "Tk stub library not found" unless tk_stub
+end
+
+find_tcltk
+
+# Source files for the extension
+$srcs = ['tcltkbridge.c', 'tkphoto.c', 'tkfont.c', 'tkwin.c']
+
+create_makefile('tcltklib')

data/ext/teek/stubs.h

@@ -0,0 +1,33 @@
+#include <tcl.h>
+
+extern int ruby_open_tcl_dll(char *);
+extern int ruby_open_tk_dll(void);
+extern int ruby_open_tcltk_dll(char *);
+extern int tcl_stubs_init_p(void);
+extern int tk_stubs_init_p(void);
+extern Tcl_Interp *ruby_tcl_create_ip_and_stubs_init(int*);
+extern int ruby_tcl_stubs_init(void);
+extern int ruby_tk_stubs_init(Tcl_Interp*);
+extern int ruby_tk_stubs_safeinit(Tcl_Interp*);
+extern int ruby_tcltk_stubs(void);
+
+/* no error */
+#define TCLTK_STUBS_OK     (0)
+
+/* return value of ruby_open_tcl_dll() */
+#define NO_TCL_DLL         (1)
+#define NO_FindExecutable  (2)
+
+/* return value of ruby_open_tk_dll() */
+#define NO_TK_DLL         (-1)
+
+/* status value of ruby_tcl_create_ip_and_stubs_init(st) */
+#define NO_CreateInterp    (3)
+#define NO_DeleteInterp    (4)
+#define FAIL_CreateInterp  (5)
+#define FAIL_Tcl_InitStubs (6)
+
+/* return value of ruby_tk_stubs_init() */
+#define NO_Tk_Init         (7)
+#define FAIL_Tk_Init       (8)
+#define FAIL_Tk_InitStubs  (9)