qt 0.1.0

data/lib/qt/string_codec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Qt
+  # Normalizes Ruby strings for bridge text paths.
+  module StringCodec
+    module_function
+
+    REPLACEMENT_CHAR = "\uFFFD"
+
+    def to_qt_text(value)
+      text = value.to_s
+      return normalize_binary_as_utf8(text) if text.encoding == Encoding::ASCII_8BIT
+
+      normalize_encoded_text(text)
+    end
+
+    def from_qt_text(value)
+      normalize_binary_as_utf8(value.to_s)
+    end
+
+    def binary_bytes?(value)
+      return false unless value.is_a?(String)
+      return false unless value.encoding == Encoding::ASCII_8BIT
+
+      !value.dup.force_encoding(Encoding::UTF_8).valid_encoding?
+    end
+
+    def normalize_encoded_text(text)
+      text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: REPLACEMENT_CHAR)
+    rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
+      normalize_binary_as_utf8(text.b)
+    end
+
+    def normalize_binary_as_utf8(text)
+      utf8 = text.dup.force_encoding(Encoding::UTF_8)
+      utf8.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: REPLACEMENT_CHAR)
+    rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
+      text.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: REPLACEMENT_CHAR)
+    end
+
+    module_function :normalize_encoded_text, :normalize_binary_as_utf8
+    private_class_method :normalize_encoded_text, :normalize_binary_as_utf8
+  end
+end

data/lib/qt/variant_codec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Qt
+  # Encodes/decodes Ruby values for QVariant bridge transport.
+  module VariantCodec
+    module_function
+
+    PREFIX = 'qtv:'
+    DIRECT_ENCODERS = {
+      Integer => ->(v) { ['int', v.to_s] },
+      Float => ->(v) { ['float', v.to_s] },
+      String => lambda { |v|
+        if StringCodec.binary_bytes?(v)
+          ['ba', base64_encode(v)]
+        else
+          ['str', base64_encode(StringCodec.to_qt_text(v))]
+        end
+      }
+    }.freeze
+    JSON_ENCODABLE_CLASSES = [Array, Hash].freeze
+
+    def encode(value)
+      return "#{PREFIX}nil" if value.nil?
+      return encode_boolean(value) if [true, false].include?(value)
+
+      tag, payload = encoded_tag_and_payload(value)
+      "#{PREFIX}#{tag}:#{payload}"
+    end
+
+    def decode(value)
+      raw = value.to_s
+      return raw unless raw.start_with?(PREFIX)
+      return nil if raw == "#{PREFIX}nil"
+
+      tag, payload = raw.delete_prefix(PREFIX).split(':', 2)
+      return raw if tag.nil? || payload.nil?
+
+      decode_typed_payload(tag, payload, raw)
+    rescue ArgumentError, JSON::ParserError
+      raw
+    end
+
+    def encode_boolean(value)
+      "#{PREFIX}bool:#{value ? 1 : 0}"
+    end
+
+    def decode_typed_payload(tag, payload, raw)
+      case tag
+      when 'bool' then payload == '1'
+      when 'int' then Integer(payload, 10)
+      when 'float' then Float(payload)
+      when 'str' then StringCodec.from_qt_text(base64_decode(payload))
+      when 'ba' then base64_decode(payload).b
+      when 'json' then JSON.parse(StringCodec.from_qt_text(base64_decode(payload)))
+      else raw
+      end
+    end
+
+    def base64_encode(value)
+      [value].pack('m0')
+    end
+
+    def base64_decode(value)
+      value.unpack1('m0')
+    end
+
+    def encoded_tag_and_payload(value)
+      direct = DIRECT_ENCODERS[value.class]
+      return direct.call(value) if direct
+
+      return ['json', base64_encode(JSON.generate(value))] if JSON_ENCODABLE_CLASSES.any? { |k| value.is_a?(k) }
+
+      ['str', base64_encode(value.to_s)]
+    end
+  end
+end

data/lib/qt/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Qt
+  VERSION = '0.1.0'
+end

data/lib/qt.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+
+ROOT = File.expand_path('..', __dir__)
+GENERATOR = File.join(ROOT, 'scripts', 'generate_bridge.rb')
+GENERATED_DIR = File.join(ROOT, 'build', 'generated')
+GENERATED_WIDGETS = File.join(GENERATED_DIR, 'widgets.rb')
+GENERATED_API = File.join(GENERATED_DIR, 'bridge_api.rb')
+GENERATED_CONSTANTS = File.join(GENERATED_DIR, 'constants.rb')
+
+unless File.exist?(GENERATED_WIDGETS) && File.exist?(GENERATED_API) && File.exist?(GENERATED_CONSTANTS)
+  ok = system(RbConfig.ruby, GENERATOR)
+  raise 'Failed to generate Qt Ruby bindings. Run: bundle exec rake compile' unless ok
+end
+
+require_relative 'qt/version'
+require_relative 'qt/errors'
+require_relative 'qt/constants'
+require_relative 'qt/string_codec'
+require_relative 'qt/date_time_codec'
+require_relative 'qt/key_sequence_codec'
+require_relative 'qt/variant_codec'
+require_relative 'qt/inspectable'
+require_relative 'qt/children_tracking'
+require_relative 'qt/application_lifecycle'
+require_relative 'qt/bridge'
+require_relative 'qt/native'
+require_relative 'qt/event_runtime_dispatch'
+require_relative 'qt/event_runtime_qobject_methods'
+require_relative 'qt/event_runtime'
+require GENERATED_WIDGETS
+require_relative 'qt/shortcut_compat'
+Qt::GeneratedConstantsRuntime.apply_generated_scoped_constants!(Qt)
+
+# Root namespace for all Qt Ruby bindings.
+module Qt
+end
+
+Qt.constants(false)
+  .grep(/\AQ[A-Z]\w*\z/)
+  .sort
+  .each do |qt_const|
+    next if Object.const_defined?(qt_const, false)
+
+    Object.const_set(qt_const, Qt.const_get(qt_const))
+  end

data/scripts/generate_bridge/ast_introspection.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+# Collects enum/typedef names that should be cast as integers for FFI.
+class IntCastTypeCollector
+  INTEGER_ALIAS_PATTERN = /\A(?:unsigned\s+|signed\s+)?(?:char|short|int|long|long long)\z/
+
+  def initialize(ast)
+    @ast = ast
+    @types = Set.new
+  end
+
+  def collect
+    walk_ast_scoped(@ast) do |node, scope|
+      name = node['name']
+      next if name.nil? || name.empty?
+
+      qualified = (scope + [name]).join('::')
+      ast_append_int_cast_type!(@types, INTEGER_ALIAS_PATTERN, node, qualified)
+    end
+    @types
+  end
+end
+
+# Records method/constructor declarations and effective access for a class AST node.
+class AstClassMemberRecorder
+  def initialize(class_name, methods_by_class, ctors_by_class, ctor_decls_by_class)
+    @class_name = class_name
+    @methods_by_class = methods_by_class
+    @ctors_by_class = ctors_by_class
+    @ctor_decls_by_class = ctor_decls_by_class
+  end
+
+  def record(node)
+    current_access = node['tagUsed'] == 'struct' ? 'public' : 'private'
+    method_decl_count = ctor_decl_count = 0
+    Array(node['inner']).each do |inner|
+      current_access, method_decl_count, ctor_decl_count = record_inner(
+        inner, current_access, method_decl_count, ctor_decl_count
+      )
+    end
+    [method_decl_count, ctor_decl_count]
+  end
+
+  private
+
+  def record_inner(inner, current_access, method_decl_count, ctor_decl_count)
+    return [inner['access'] || current_access, method_decl_count, ctor_decl_count] if inner['kind'] == 'AccessSpecDecl'
+    return [current_access, method_decl_count + 1, ctor_decl_count] if record_method_member?(inner, current_access)
+    return [current_access, method_decl_count, ctor_decl_count + 1] if record_constructor_member?(inner, current_access)
+
+    [current_access, method_decl_count, ctor_decl_count]
+  end
+
+  def record_method_member?(inner, current_access)
+    return false unless inner['kind'] == 'CXXMethodDecl' && inner['name']
+
+    access = inner['access'] || current_access
+    @methods_by_class[@class_name][inner['name']] << inner.merge('__effective_access' => access)
+    true
+  end
+
+  def record_constructor_member?(inner, current_access)
+    return false unless inner['kind'] == 'CXXConstructorDecl' && inner['name']
+
+    @ctors_by_class[@class_name] << inner['name']
+    @ctor_decls_by_class[@class_name] << inner.merge('__effective_access' => current_access)
+    true
+  end
+end
+
+def pkg_config_cflags
+  cflags = `pkg-config --cflags Qt6Widgets 2>/dev/null`.strip
+  raise 'pkg-config Qt6Widgets is required' if cflags.empty?
+
+  cflags
+end
+
+def ast_dump
+  cflags = timed('pkg_config_cflags') { pkg_config_cflags }
+
+  Tempfile.create(['qt_ruby_probe', '.cpp']) do |file|
+    required_includes(GENERATOR_SCOPE).each { |inc| file.write("#include <#{inc}>\n") }
+    file.flush
+
+    cmd = "clang++ -std=c++17 -x c++ -Xclang -ast-dump=json -fsyntax-only #{cflags} #{file.path}"
+    out = timed('clang_ast_dump') { `#{cmd}` }
+    raise "clang AST dump failed: #{cmd}" unless Process.last_status.success?
+
+    timed('ast_json_parse') { JSON.parse(out, max_nesting: false) }
+  end
+end
+
+def walk_ast(node, &)
+  return unless node.is_a?(Hash)
+
+  yield node
+  Array(node['inner']).each { |child| walk_ast(child, &) }
+end
+
+def walk_ast_scoped(node, scope = [], &)
+  return unless node.is_a?(Hash)
+
+  local_scope = scope
+  name = node['name']
+  local_scope = scope + [name] if name && !name.empty? && %w[NamespaceDecl CXXRecordDecl].include?(node['kind'])
+
+  yield node, local_scope
+  Array(node['inner']).each { |child| walk_ast_scoped(child, local_scope, &) }
+end
+
+def ast_append_int_cast_type!(types, integer_alias_pattern, node, qualified)
+  case node['kind']
+  when 'EnumDecl'
+    types << qualified
+  when 'TypedefDecl', 'TypeAliasDecl'
+    aliased = node.dig('type', 'qualType').to_s.strip
+    return if aliased.empty?
+
+    types << qualified if aliased.match?(integer_alias_pattern)
+    types << qualified if aliased.include?('QFlags<')
+  end
+end
+
+def ast_int_cast_type_set(ast)
+  @ast_int_cast_type_set_cache ||= {}.compare_by_identity
+  return @ast_int_cast_type_set_cache[ast] if @ast_int_cast_type_set_cache.key?(ast)
+
+  @ast_int_cast_type_set_cache[ast] = IntCastTypeCollector.new(ast).collect
+end
+
+def collect_class_api(ast, class_name)
+  index = ast_class_index(ast)
+  methods = index[:methods_by_class].fetch(class_name, {}).keys
+  ctors = index[:ctors_by_class].fetch(class_name, [])
+  { methods: methods, constructors: ctors }
+end
+
+def normalize_cpp_type_name(raw)
+  return nil if raw.nil? || raw.empty?
+
+  name = raw.dup
+  name = name.sub(/\A(class|struct)\s+/, '')
+  name = name.split('<').first
+  name = name.split(/\s+/).first
+  name = name.split('::').last
+  name&.strip
+end
+
+def ast_record_base_classes(node, class_name, bases_by_class)
+  Array(node['bases']).each do |base|
+    type_info = base['type'] || {}
+    raw = type_info['desugaredQualType'] || type_info['qualType']
+    parsed_base = normalize_cpp_type_name(raw)
+    bases_by_class[class_name] << parsed_base if parsed_base && !parsed_base.empty?
+  end
+end
+
+def ast_record_class_members(node, class_name, methods_by_class, ctors_by_class, ctor_decls_by_class)
+  AstClassMemberRecorder.new(
+    class_name, methods_by_class, ctors_by_class, ctor_decls_by_class
+  ).record(node)
+end
+
+def ast_class_index_method_collections
+  {
+    methods_by_class: Hash.new { |h, k| h[k] = Hash.new { |h2, k2| h2[k2] = [] } },
+    bases_by_class: Hash.new { |h, k| h[k] = [] }
+  }
+end
+
+def ast_class_index_constructor_collections
+  {
+    ctors_by_class: Hash.new { |h, k| h[k] = [] },
+    ctor_decls_by_class: Hash.new { |h, k| h[k] = [] },
+    abstract_by_class: Hash.new(false)
+  }
+end
+
+def ast_class_index_collections
+  ast_class_index_method_collections.merge(ast_class_index_constructor_collections)
+end
+
+def init_ast_class_index_data
+  ast_class_index_collections.merge(method_decl_count: 0, ctor_decl_count: 0)
+end
+
+def ast_index_track_record_decl(node, data)
+  class_name = node['name']
+  return if class_name.nil? || class_name.empty?
+
+  data[:abstract_by_class][class_name] ||= node.dig('definitionData', 'isAbstract') == true
+  ast_record_base_classes(node, class_name, data[:bases_by_class])
+  method_count, ctor_count = ast_record_class_members(
+    node, class_name, data[:methods_by_class], data[:ctors_by_class], data[:ctor_decls_by_class]
+  )
+  data[:method_decl_count] += method_count
+  data[:ctor_decl_count] += ctor_count
+end
+
+def finalize_ast_class_index!(data)
+  data[:bases_by_class].each_value(&:uniq!)
+  data[:ctors_by_class].each_value(&:uniq!)
+  debug_log("ast_class_index classes=#{data[:methods_by_class].length} method_decls=#{data[:method_decl_count]}")
+  debug_log("ast_class_index ctor_decls=#{data[:ctor_decl_count]}")
+  data.slice(:methods_by_class, :bases_by_class, :ctors_by_class, :ctor_decls_by_class, :abstract_by_class)
+end
+
+def ast_class_index(ast)
+  @ast_class_index_cache ||= {}.compare_by_identity
+  return @ast_class_index_cache[ast] if @ast_class_index_cache.key?(ast)
+
+  data = init_ast_class_index_data
+
+  timed('ast_class_index_build') do
+    walk_ast(ast) do |node|
+      next unless node['kind'] == 'CXXRecordDecl'
+
+      ast_index_track_record_decl(node, data)
+    end
+  end
+
+  @ast_class_index_cache[ast] = finalize_ast_class_index!(data)
+end
+
+def collect_method_decls(ast, class_name, method_name)
+  index = ast_class_index(ast)
+  index[:methods_by_class].dig(class_name, method_name) || []
+end
+
+def collect_method_decls_with_bases(ast, class_name, method_name, visited = {})
+  return [] if class_name.nil? || class_name.empty? || visited[class_name]
+
+  visited[class_name] = true
+  own = collect_method_decls(ast, class_name, method_name)
+  return own unless own.empty?
+
+  collect_class_bases(ast, class_name).flat_map do |base|
+    collect_method_decls_with_bases(ast, base, method_name, visited)
+  end
+end
+
+def collect_class_bases(ast, class_name)
+  index = ast_class_index(ast)
+  Array(index[:bases_by_class][class_name]).uniq
+end
+
+def collect_constructor_decls(ast, class_name)
+  index = ast_class_index(ast)
+  Array(index[:ctor_decls_by_class][class_name])
+end
+
+def abstract_class?(ast, class_name)
+  index = ast_class_index(ast)
+  index[:abstract_by_class][class_name] == true
+end
+
+def class_inherits?(ast, class_name, ancestor, visited = {})
+  return false if class_name.nil? || class_name.empty? || visited[class_name]
+  return true if class_name == ancestor
+
+  visited[class_name] = true
+  collect_class_bases(ast, class_name).any? { |base| class_inherits?(ast, base, ancestor, visited) }
+end
+
+def class_has_method?(ast, class_name, method_name)
+  collect_class_api(ast, class_name)[:methods].include?(method_name)
+end

data/scripts/generate_bridge/auto_method_spec_resolver.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Resolves auto-generated methods for a class spec while tracking counters.
+class AutoMethodSpecResolver
+  def initialize(spec:, auto_mode:, existing_names:, resolve_method:)
+    @spec = spec
+    @auto_mode = auto_mode
+    @existing_names = existing_names
+    @resolve_method = resolve_method
+  end
+
+  def resolve(entry, skipped:, resolved:)
+    qt_name = entry_name(entry)
+    return [nil, skipped + 1, resolved] if existing_names.include?(qt_name)
+
+    method, skipped_entry = resolve_entry(entry)
+    return [nil, skipped + 1, resolved] if skipped_entry
+
+    [method, skipped, resolved + 1]
+  end
+
+  private
+
+  attr_reader :spec, :auto_mode, :existing_names, :resolve_method
+
+  def entry_name(entry)
+    entry.is_a?(String) ? entry : entry[:qt_name]
+  end
+
+  def resolve_entry(entry)
+    method = resolve_method.call(entry)
+    return [method, false] unless method.nil?
+    return [nil, true] if auto_mode == :all
+
+    raise "Failed to auto-resolve #{spec[:qt_class]}##{entry_name(entry)}"
+  end
+end