qt 0.1.0

data/scripts/generate_bridge/free_function_specs.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+RUNTIME_HEADER_PATH = File.expand_path('../../ext/qt_ruby_bridge/qt_ruby_runtime.hpp', __dir__)
+
+SCALAR_CLASS_METHOD_FFI_RETURNS = %i[void int bool string].freeze
+QAPPLICATION_STATIC_METHOD_EXCLUSIONS = %w[exec].freeze
+QAPPLICATION_STATIC_TEXT_SETTERS = %w[
+  setApplicationName
+  setDesktopFileName
+  setOrganizationName
+  setApplicationDisplayName
+].freeze
+
+def qt_free_function_specs(ast)
+  @qt_free_function_specs_cache ||= {}.compare_by_identity
+  return @qt_free_function_specs_cache[ast] if @qt_free_function_specs_cache.key?(ast)
+
+  qt_specs = []
+  qt_specs << qversion_free_function_spec(ast)
+  qt_specs.concat(qapplication_static_free_function_specs(ast))
+  qt_specs.concat(qapplication_static_text_setter_specs(ast))
+  qt_specs << qapplication_top_level_widgets_count_spec(ast)
+  runtime_specs = runtime_free_function_specs_from_header
+  @qt_free_function_specs_cache[ast] = merge_free_function_specs(qt_specs, runtime_specs).freeze
+end
+
+def merge_free_function_specs(primary_specs, secondary_specs)
+  merged = primary_specs.dup
+  existing_names = merged.to_set { |spec| spec[:name] }
+  secondary_specs.each do |spec|
+    if existing_names.include?(spec[:name])
+      warn "[gen][warn] skip runtime free-function #{spec[:name]}: already provided by Qt-derived spec"
+      next
+    end
+
+    merged << spec
+    existing_names << spec[:name]
+  end
+  merged
+end
+
+def runtime_free_function_specs_from_header
+  @runtime_free_function_specs_from_header ||= begin
+    raw = File.read(RUNTIME_HEADER_PATH)
+    parse_runtime_free_function_specs(raw).freeze
+  end
+end
+
+def parse_runtime_free_function_specs(raw)
+  in_namespace = false
+  specs = []
+  raw.each_line do |line|
+    in_namespace = true if line.include?('namespace QtRubyRuntime')
+    in_namespace = false if in_namespace && line.include?('}  // namespace QtRubyRuntime')
+    next unless in_namespace
+
+    decl = parse_runtime_function_decl(line)
+    next unless decl
+
+    specs << runtime_decl_to_free_function_spec(decl)
+  end
+  specs
+end
+
+def parse_runtime_function_decl(line)
+  md = line.strip.match(/\A(void|int)\s+([a-zA-Z_]\w*)\s*\(([^)]*)\)\s*;\z/)
+  return nil unless md
+
+  {
+    return_type: md[1],
+    name: md[2],
+    args: parse_runtime_decl_args(md[3])
+  }
+end
+
+def parse_runtime_decl_args(args_raw)
+  stripped = args_raw.to_s.strip
+  return [] if stripped.empty?
+
+  stripped.split(',').map { |arg| parse_runtime_decl_arg(arg) }
+end
+
+def parse_runtime_decl_arg(arg)
+  normalized = arg.to_s.strip.gsub(/\s+/, ' ')
+  md = normalized.match(/\A(.+?)\s+([a-zA-Z_]\w*)\z/)
+  raise "Unsupported runtime declaration argument: #{arg.inspect}" unless md
+
+  { cpp_type: md[1].strip, name: md[2] }
+end
+
+def runtime_cpp_type_to_ffi(cpp_type)
+  normalized = cpp_type.to_s.strip.gsub(/\s+/, ' ').gsub(/\s*\*\s*/, '*')
+  return :pointer if normalized == 'void*'
+  return :string if normalized == 'const char*'
+  return :int if normalized == 'int'
+
+  raise "Unsupported runtime declaration type for FFI: #{cpp_type.inspect}"
+end
+
+def runtime_decl_to_free_function_spec(decl)
+  cpp_args = decl[:args].map { |arg| "#{arg[:cpp_type]} #{arg[:name]}" }.join(', ')
+  call_args = decl[:args].map { |arg| arg[:name] }.join(', ')
+  cpp_body =
+    if decl[:return_type] == 'void'
+      ["QtRubyRuntime::#{decl[:name]}(#{call_args});"]
+    else
+      ["return QtRubyRuntime::#{decl[:name]}(#{call_args});"]
+    end
+
+  {
+    name: "qt_ruby_#{decl[:name]}",
+    ffi_return: decl[:return_type].to_sym,
+    args: decl[:args].map { |arg| runtime_cpp_type_to_ffi(arg[:cpp_type]) },
+    cpp_return: decl[:return_type],
+    cpp_args: cpp_args,
+    cpp_body: cpp_body
+  }
+end
+
+def qversion_free_function_spec(ast)
+  found = false
+  walk_ast(ast) do |node|
+    next unless node['kind'] == 'FunctionDecl'
+    next unless node['name'] == 'qVersion'
+    next unless node.dig('type', 'qualType').to_s.include?('const char *()')
+
+    found = true
+    break
+  end
+  raise 'Unable to find qVersion() in AST' unless found
+
+  {
+    name: 'qt_ruby_qt_version',
+    ffi_return: :string,
+    args: [],
+    cpp_return: 'const char*',
+    cpp_args: '',
+    cpp_body: ['return qVersion();'],
+    qapplication_method: { ruby_name: 'qtVersion', native: 'qt_version', args: [], return_cast: :qstring_to_utf8 }
+  }
+end
+
+def qapplication_top_level_widgets_count_spec(ast)
+  has_top_level_widgets = collect_method_decls_with_bases(ast, 'QApplication', 'topLevelWidgets').any?
+  raise 'Unable to find QApplication::topLevelWidgets in AST' unless has_top_level_widgets
+
+  {
+    name: 'qt_ruby_qapplication_top_level_widgets_count',
+    ffi_return: :int,
+    args: [],
+    cpp_return: 'int',
+    cpp_args: '',
+    cpp_body: ['return QApplication::topLevelWidgets().size();'],
+    qapplication_method: { ruby_name: 'topLevelWidgetsCount', native: 'qapplication_top_level_widgets_count', args: [] }
+  }
+end
+
+def qapplication_static_free_function_specs(ast)
+  int_cast_types = ast_int_cast_type_set(ast)
+  method_names = collect_method_names_with_bases(ast, 'QApplication').uniq
+  method_names -= QAPPLICATION_STATIC_METHOD_EXCLUSIONS
+  method_names.filter_map do |qt_name|
+    build_qapplication_static_free_function_spec(ast, qt_name, int_cast_types)
+  end
+end
+
+def qapplication_static_text_setter_specs(ast)
+  QAPPLICATION_STATIC_TEXT_SETTERS.filter_map do |qt_name|
+    build_qapplication_static_text_setter_spec(ast, qt_name)
+  end
+end
+
+def build_qapplication_static_text_setter_spec(ast, qt_name)
+  return nil unless resolve_qapplication_static_text_setter_candidate(ast, qt_name)
+
+  native_name = "qapplication_#{to_snake(qt_name)}"
+  {
+    name: "qt_ruby_#{native_name}",
+    ffi_return: :void,
+    args: [:string],
+    cpp_return: 'void',
+    cpp_args: 'const char* value',
+    cpp_body: ["QApplication::#{qt_name}(as_qstring(value));"],
+    qapplication_method: {
+      ruby_name: qt_name,
+      native: native_name,
+      args: [{ name: :value, ffi: :string, cast: :qstring }],
+      required_arg_count: 1
+    }
+  }
+end
+
+def resolve_qapplication_static_text_setter_candidate(ast, qt_name)
+  decls = collect_method_decls_with_bases(ast, 'QApplication', qt_name)
+  decls.any? do |decl|
+    next false unless decl['storageClass'] == 'static'
+    next false unless decl['__effective_access'] == 'public'
+
+    parsed = parse_method_signature(decl)
+    next false unless parsed
+    next false unless parsed[:return_type].to_s.strip == 'void'
+    next false unless parsed[:required_arg_count] == 1
+    next false unless parsed[:params].length == 1
+
+    normalized = normalized_cpp_type_name(parsed[:params].first[:type])
+    normalized == 'QString'
+  end
+end
+
+def build_qapplication_static_free_function_spec(ast, qt_name, int_cast_types)
+  candidate = resolve_qapplication_static_noarg_candidate(ast, qt_name, int_cast_types)
+  return nil unless candidate
+
+  native_name = "qapplication_#{to_snake(qt_name)}"
+  cpp_body =
+    if candidate[:ffi_return] == :void
+      ["QApplication::#{qt_name}();"]
+    elsif candidate[:enum_cast]
+      ["return static_cast<int>(QApplication::#{qt_name}());"]
+    elsif candidate[:ffi_return] == :string
+      [
+        "const QString value = QApplication::#{qt_name}();",
+        'thread_local QByteArray utf8;',
+        'utf8 = value.toUtf8();',
+        'return utf8.constData();'
+      ]
+    else
+      ["return QApplication::#{qt_name}();"]
+    end
+
+  {
+    name: "qt_ruby_#{native_name}",
+    ffi_return: candidate[:ffi_return],
+    args: [],
+    cpp_return: ffi_return_to_cpp(candidate[:ffi_return]),
+    cpp_args: '',
+    cpp_body: cpp_body,
+    qapplication_method: {
+      ruby_name: qt_name,
+      native: native_name,
+      args: [],
+      return_cast: candidate[:return_cast]
+    }
+  }
+end
+
+def resolve_qapplication_static_noarg_candidate(ast, qt_name, int_cast_types)
+  decls = collect_method_decls_with_bases(ast, 'QApplication', qt_name)
+  candidates = decls.filter_map do |decl|
+    next unless decl['storageClass'] == 'static'
+    next unless decl['__effective_access'] == 'public'
+
+    parsed = parse_method_signature(decl)
+    next unless parsed && parsed[:required_arg_count].zero?
+
+    ret_info = qapplication_static_return_info(parsed[:return_type], int_cast_types)
+    next unless ret_info
+
+    { decl: decl, param_count: parsed[:params].length }.merge(ret_info)
+  end
+  return nil if candidates.empty?
+
+  candidates.min_by { |item| item[:param_count] }
+end
+
+def qapplication_static_return_info(return_type, int_cast_types)
+  mapped = map_cpp_return_type(return_type)
+  if mapped && SCALAR_CLASS_METHOD_FFI_RETURNS.include?(mapped[:ffi_return])
+    return { ffi_return: mapped[:ffi_return], return_cast: mapped[:return_cast], enum_cast: false }
+  end
+
+  normalized = normalized_cpp_type_name(return_type)
+  return nil unless normalized.include?('::') && int_cast_types.include?(normalized)
+
+  { ffi_return: :int, return_cast: nil, enum_cast: true }
+end
+
+def qapplication_class_method_specs(ast)
+  qt_free_function_specs(ast).filter_map { |spec| spec[:qapplication_method] }
+end
+
+def append_cpp_free_function_definitions(lines, free_function_specs)
+  free_function_specs.each do |spec|
+    lines << "extern \"C\" #{spec[:cpp_return]} #{spec[:name]}(#{spec[:cpp_args]}) {"
+    Array(spec[:cpp_body]).each { |line| lines << "  #{line}" }
+    lines << '}'
+    lines << ''
+  end
+end

data/scripts/generate_bridge/spec_discovery.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+SCALAR_BRIDGED_QT_TYPES = Set.new(%w[QString QVariant QAnyStringView QByteArray QDateTime QDate QTime]).freeze
+
+def constructor_supports_parent_only?(decl)
+  return false unless decl['__effective_access'] == 'public'
+
+  parsed = parse_method_signature(decl)
+  return false unless parsed
+
+  params = parsed[:params]
+  return false if params.empty?
+
+  first_type = normalized_cpp_type_name(params.first[:type])
+  return false unless %w[QWidget* QObject*].include?(first_type)
+
+  params.drop(1).all? { |param| param[:has_default] }
+end
+
+def constructor_keysequence_parent_type(decl)
+  return nil unless decl['__effective_access'] == 'public'
+
+  parsed = parse_method_signature(decl)
+  return nil unless parsed
+
+  params = parsed[:params]
+  return nil if params.length < 2
+  return nil unless normalized_cpp_type_name(params.first[:type]) == 'QKeySequence'
+
+  parent_type = normalized_cpp_type_name(params[1][:type])
+  return nil unless %w[QWidget* QObject*].include?(parent_type)
+  return nil unless params.drop(2).all? { |param| param[:has_default] }
+
+  parent_type
+end
+
+def parent_constructor_first_type(decl)
+  return nil unless decl['__effective_access'] == 'public'
+
+  parsed = parse_method_signature(decl)
+  return nil unless parsed
+
+  params = parsed[:params]
+  return nil if params.empty?
+
+  first_type = normalized_cpp_type_name(params.first[:type])
+  return nil unless %w[QWidget* QObject*].include?(first_type)
+  return nil unless params.drop(1).all? { |param| param[:has_default] }
+
+  first_type
+end
+
+def constructor_supports_no_args?(decl)
+  return false unless decl['__effective_access'] == 'public'
+
+  parsed = parse_method_signature(decl)
+  return false unless parsed
+
+  parsed[:required_arg_count].zero?
+end
+
+def constructor_supports_string_path?(decl)
+  return false unless decl['__effective_access'] == 'public'
+
+  parsed = parse_method_signature(decl)
+  return false unless parsed
+  return false if parsed[:params].empty?
+  return false unless parsed[:required_arg_count] <= 1
+
+  constructor_string_like_type?(parsed[:params].first[:type])
+end
+
+def constructor_string_like_arg_cast(raw_type)
+  compact = raw_type.to_s.gsub(/\s+/, ' ').strip
+  normalized = normalized_cpp_type_name(raw_type)
+  return :qstring if normalized == 'QString'
+  return :qany_string_view if normalized == 'QAnyStringView'
+  return :cstr if compact.match?(/\A(?:const\s+)?char\s*\*\z/)
+
+  nil
+end
+
+def constructor_string_like_type?(raw_type)
+  !constructor_string_like_arg_cast(raw_type).nil?
+end
+
+def template_qt_classes(ast)
+  @template_qt_classes_cache ||= {}.compare_by_identity
+  return @template_qt_classes_cache[ast] if @template_qt_classes_cache.key?(ast)
+
+  @template_qt_classes_cache[ast] = build_template_qt_classes(ast)
+end
+
+def build_template_qt_classes(ast)
+  set = Set.new
+  timed('discover_template_qt_classes') do
+    walk_ast(ast) do |node|
+      next unless node['kind'] == 'ClassTemplateDecl'
+
+      name = node['name']
+      set << name if name&.start_with?('Q')
+    end
+  end
+
+  debug_log("template_qt_classes count=#{set.length}")
+  set
+end
+
+def q_class_names(ast)
+  ast_class_index(ast)[:methods_by_class].keys.select { |name| name.start_with?('Q') }.uniq
+end
+
+def class_matches_scope?(ast, qt_class, scope)
+  case scope
+  when 'widgets' then widget_target_qt_class?(ast, qt_class)
+  when 'qobject' then qobject_target_qt_class?(ast, qt_class)
+  when 'all' then all_scope_target_qt_class?(ast, qt_class)
+  else
+    raise "Unsupported QT_RUBY_SCOPE=#{scope.inspect}. Supported: #{SUPPORTED_SCOPES.join(', ')}"
+  end
+end
+
+def all_scope_target_qt_class?(ast, qt_class)
+  widget_target_qt_class?(ast, qt_class) || qobject_target_qt_class?(ast, qt_class)
+end
+
+def discover_target_for_scope(ast, scope, all_classes, template_classes)
+  all_classes.select do |qt_class|
+    next false if template_classes.include?(qt_class)
+    next false unless class_matches_scope?(ast, qt_class, scope)
+
+    constructor_usable_for_codegen?(ast, qt_class)
+  end.sort
+end
+
+def discover_related_value_classes(ast, seed_classes, all_classes, template_classes)
+  discovered = seed_classes.to_set
+  queue = seed_classes.dup
+
+  until queue.empty?
+    klass = queue.shift
+    related_qt_type_names(ast, klass).each do |candidate|
+      next if discovered.include?(candidate)
+      next unless related_value_class_candidate?(ast, candidate, all_classes, template_classes)
+
+      discovered << candidate
+      queue << candidate
+    end
+  end
+
+  discovered.to_a
+end
+
+def related_value_class_candidate?(ast, qt_class, all_classes, template_classes)
+  return false if SCALAR_BRIDGED_QT_TYPES.include?(qt_class)
+  return false unless all_classes.include?(qt_class)
+  return false if template_classes.include?(qt_class)
+  return false if qt_class.end_with?('Private')
+  return false if qt_class == 'QApplication'
+  return false if abstract_class?(ast, qt_class)
+  return false if class_inherits?(ast, qt_class, 'QObject')
+
+  constructor_usable_for_codegen?(ast, qt_class)
+end
+
+def related_qt_type_names(ast, qt_class)
+  index = ast_class_index(ast)
+  decls = index[:methods_by_class].fetch(qt_class, {}).values.flatten
+  decls.each_with_object(Set.new) do |decl, out|
+    next unless decl['__effective_access'] == 'public'
+
+    parsed = parse_method_signature(decl)
+    next unless parsed
+
+    append_related_qt_types_from_decl(out, parsed, decl['name'])
+  end
+end
+
+def append_related_qt_types_from_decl(out, parsed, method_name)
+  candidates = []
+  candidates << normalized_cpp_type_name(parsed[:return_type]).to_s if parsed[:return_type]
+  parsed[:params].each { |param| candidates << normalized_cpp_type_name(param[:type]).to_s }
+  candidates.each do |candidate|
+    next if candidate.empty? || !candidate.start_with?('Q')
+    next unless related_type_name_matches_method?(candidate, method_name)
+
+    out << candidate
+  end
+end
+
+def related_type_name_matches_method?(qt_type, method_name)
+  token = qt_type.delete_prefix('Q').downcase
+  return false if token.empty?
+
+  method_name.to_s.downcase.include?(token)
+end
+
+def discover_target_qt_classes(ast, scope)
+  all_classes = q_class_names(ast)
+  template_classes = template_qt_classes(ast)
+
+  base_targets = timed("discover_target_qt_classes/#{scope}/base") do
+    discover_target_for_scope(ast, scope, all_classes, template_classes)
+  end
+
+  targets = timed("discover_target_qt_classes/#{scope}/related") do
+    discover_related_value_classes(ast, base_targets, all_classes, template_classes).sort
+  end
+  debug_log(
+    "discover_target_qt_classes scope=#{scope} total_q=#{all_classes.length} " \
+    "base=#{base_targets.length} targets=#{targets.length}"
+  )
+  targets
+end
+
+def widget_target_qt_class?(ast, qt_class)
+  return false if qt_class.end_with?('Private')
+  return false if qt_class == 'QApplication'
+  return false if abstract_class?(ast, qt_class)
+
+  class_inherits?(ast, qt_class, 'QWidget') ||
+    class_inherits?(ast, qt_class, 'QLayout') ||
+    qt_class == 'QTableWidgetItem'
+end
+
+def qobject_target_qt_class?(ast, qt_class)
+  return false if qt_class.end_with?('Private')
+  return false if qt_class == 'QApplication'
+  return false if abstract_class?(ast, qt_class)
+  return false unless class_inherits?(ast, qt_class, 'QObject')
+
+  # qobject scope is additive stage after widgets: exclude widget/layout branch.
+  return false if class_inherits?(ast, qt_class, 'QWidget')
+  return false if class_inherits?(ast, qt_class, 'QLayout')
+
+  true
+end
+
+def constructor_usable_for_codegen?(ast, qt_class)
+  ctor_decls = collect_constructor_decls(ast, qt_class)
+  ctor_decls.any? do |decl|
+    constructor_keysequence_parent_type(decl) ||
+    constructor_supports_parent_only?(decl) ||
+      constructor_supports_no_args?(decl) ||
+      constructor_supports_string_path?(decl)
+  end
+end
+
+def build_base_spec_for_qt_class(ast, qt_class)
+  ctor_decls = collect_constructor_decls(ast, qt_class)
+  keysequence_parent_type = ctor_decls.filter_map { |decl| constructor_keysequence_parent_type(decl) }.first
+  parent_type = ctor_decls.filter_map { |decl| parent_constructor_first_type(decl) }.first
+  string_path_cast = ctor_decls.filter_map do |decl|
+    parsed = parse_method_signature(decl)
+    next nil unless parsed && parsed[:params].first
+
+    constructor_string_like_arg_cast(parsed[:params].first[:type])
+  end.first
+  widget_child = qt_class != 'QWidget' && class_inherits?(ast, qt_class, 'QWidget')
+  parent_ctor =
+    if keysequence_parent_type
+      { parent: true, parent_type: keysequence_parent_type, mode: :keysequence_parent, register_in_parent: widget_child }
+    elsif parent_type
+      parent_constructor_for_type(parent_type, widget_child)
+    elsif string_path_cast
+      string_path_constructor(string_path_cast)
+    else
+      { parent: false }
+    end
+  base_spec_hash(qt_class, parent_ctor)
+end
+
+def base_spec_hash(qt_class, parent_ctor)
+  auto_method_rules = {}
+  # Prefer QShortcut#setKeys(StandardKey) in generated API and provide
+  # QKeySequence path via setKey(QKeySequence) + Ruby-level compatibility shim.
+  auto_method_rules[:setKeys] = { param_types: ['QKeySequence::StandardKey'] } if qt_class == 'QShortcut'
+
+  {
+    qt_class: qt_class,
+    ruby_class: qt_class,
+    include: qt_class,
+    prefix: prefix_for_qt_class(qt_class),
+    constructor: parent_ctor,
+    methods: [],
+    auto_methods: :all,
+    auto_method_rules: auto_method_rules,
+    # Constructor availability is already filtered during discovery.
+    # Keep validation lightweight for auto-discovered classes to avoid false negatives
+    # on template/specialized constructor names in Clang AST.
+    validate: { constructors: [], methods: [] }
+  }
+end
+
+def parent_constructor_for_type(parent_type, widget_child)
+  { parent: true, parent_type: parent_type, register_in_parent: widget_child }
+end
+
+def string_path_constructor(arg_cast)
+  { parent: false, mode: :string_path, arg_cast: arg_cast }
+end
+
+def build_base_specs(ast)
+  specs = [build_qapplication_spec(ast)]
+  target_qt_classes = discover_target_qt_classes(ast, GENERATOR_SCOPE)
+  debug_log("target_classes scope=#{GENERATOR_SCOPE} count=#{target_qt_classes.length}")
+
+  target_qt_classes.each do |qt_class|
+    specs << build_base_spec_for_qt_class(ast, qt_class)
+  end
+
+  specs
+end