ruby_header_parser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 73e54692bd969e0639672d95e7b5315bd5bbf8857c988343c0291af3ff5a3ab6
+  data.tar.gz: '099e7a0d30b0ef67d5c21853d123bf34927bae48915fef6cc1377fcea9e56689'
+SHA512:
+  metadata.gz: 282901b284812616deb5c0f5c180aa67397fac1b52c6b121df2462e6094f8e0b88e4ab57b45d2a371fe5f6682cd113e5ff2fb7b99f23f77660a803865a3f61c6
+  data.tar.gz: c87c969a18e295904f4e35f56d83fb8173f7606464c46828ac27f56d1ebb4a4d2db164bcff20d6865fe2446e266fbbfde725ac3773327982e493d0077ce2e70e

data/.rspec

@@ -0,0 +1,3 @@
+--format progress
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,55 @@
+AllCops:
+  TargetRubyVersion: 3.3
+  NewCops: enable
+  SuggestExtensions: false
+
+Gemspec/DevelopmentDependencies:
+  EnforcedStyle: gemspec
+
+Layout/DotPosition:
+  EnforcedStyle: trailing
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Layout/SpaceAroundOperators:
+  Exclude:
+    # Suppress line breaks in spec files (e.g `it { should xxxx }`, `its(:method) { should xxxx }` )
+    - "**/*_spec.rb"
+
+Lint/BinaryOperatorWithIdenticalOperands:
+  Exclude:
+    - "**/*_spec.rb" # for rspec-parameterized
+
+Metrics/AbcSize:
+  Max: 20
+
+Metrics/BlockLength:
+  Exclude:
+    - "*.gemspec"
+    - "**/*_spec.rb"
+
+Metrics/MethodLength:
+  Max: 21
+
+Style/NumericPredicate:
+  EnforcedStyle: comparison
+
+Style/SingleLineMethods:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma

data/.yardopts

@@ -0,0 +1,7 @@
+--markup markdown
+--no-private
+--hide-void-return
+-
+CHANGELOG.md
+CONFIG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0](https://github.com/sue445/ruby_header_parser/releases/tag/v0.1.0) - 2024-10-14
+
+- Initial release

data/CONFIG.md

@@ -0,0 +1,126 @@
+# Configuration file specification
+
+## Example
+```yaml
+function:
+  include_name:
+    - !ruby/regexp /^rb_/i
+    - !ruby/regexp /^rstring_/i
+
+  exclude_name:
+    # deprecated functions
+    - !ruby/regexp /^rb_check_safe_str$/i
+    - !ruby/regexp /^rb_clear_constant_cache$/i
+    - !ruby/regexp /^rb_clone_setup$/i
+
+  pointer_hint:
+    RSTRING_PTR:
+      self: raw
+    rb_data_object_make:
+      4: sref
+
+struct:
+  include_name:
+    - !ruby/regexp /^rb_/i
+    - re_registers
+
+  exclude_name:
+    - rb_data_type_struct
+
+type:
+  include_name:
+    - !ruby/regexp /^rb_/i
+    - !ruby/regexp /^st_/i
+    - ID
+    - VALUE
+
+  exclude_name: []
+
+enum:
+  include_name:
+    - ruby_value_type
+    - rb_io_wait_readwrite
+
+  exclude_name: []
+```
+
+## Full configuration file
+[config/default.yml](config/default.yml) is used by https://github.com/sue445/go-gem-wrapper to generate bindings for Go.
+
+## `function.include_name`, `struct.include_name`, `type.include_name`, `enum.include_name`
+Return functions and structures that match the condition with a [RubyHeaderParser::Parser](lib/ruby_header_parser/parser.rb)
+
+e.g.
+
+```yaml
+struct:
+  include_name:
+    - !ruby/regexp /^rb_/i
+    - re_registers
+```
+
+Elements in the array accept the following
+
+* `String`: Exact match
+* `Regexp`(`!ruby/regexp`): Regular expression match
+
+## `function.exclude_name`, `struct.exclude_name`, `type.exclude_name`, `enum.exclude_name`
+Doesn't return functions and structures that match the condition with a [RubyHeaderParser::Parser](lib/ruby_header_parser/parser.rb)
+
+e.g.
+
+```yaml
+function:
+  exclude_name:
+    - !ruby/regexp /^rb_check_safe_str$/i
+    - rb_scan_args_bad_format
+```
+
+`exclude_name` is preferred over `include_name`
+
+Other specifications are the same as `include_name`
+
+## `function.pointer_hint`
+Provide a hint if the function argument type is a pointer
+
+e.g.
+
+```yaml
+function:
+  pointer_hint:
+    RSTRING_PTR: # function name (Exact match)
+      self: raw
+    rb_data_object_make:
+      4: sref
+```
+
+### Function arguments (`1`, `2`, `3`, ...)
+* `ref` (default)
+    * normal pointer
+    * e.g. 1st argument of `VALUE rb_const_list(void*)`
+* `in_ref`
+    * input only pointer
+    * e.g. 2nd argument of `void rb_define_variable(const char *name, VALUE *var)`
+* `sref`
+    * special one for multiple pointer
+    * e.g. 3rd argument of `rb_data_typed_object_make(VALUE klass, const rb_data_type_t *type, void **datap, size_t size)`
+* `array`
+    * array
+    * e.g. 4th argument of `VALUE rb_funcallv(VALUE recv, ID mid, int argc, const VALUE *argv)`
+* `ref_array`
+    * array of pointer
+    * e.g. 10th argument of `rb_scan_args_set(int kw_flag, int argc, const VALUE *argv, int n_lead, int n_opt, int n_trail, bool f_var, bool f_hash, bool f_block, VALUE *vars[], RB_UNUSED_VAR(const char *fmt), RB_UNUSED_VAR(int varc))`
+* `str_array`
+    * array of string
+    * e.g. 2nd argument of `int rb_find_file_ext(VALUE *feature, const char *const *exts)`
+* `function`
+    * function pointer
+    * e.g. 4th argument of `void rb_define_method(VALUE klass, const char *mid, VALUE (*func)(), int arity)`
+
+### Function return value (`self`)
+* `ref` (default)
+    * normal pointer
+    * e.g. Return value of `int *rb_errno_ptr(void)`
+* `raw`
+    * In many cases `char*` can be interpreted as a string. But if `raw` is specified, it suppresses interpretation as a string
+    * e.g. Return value of `char* RSTRING_PTR(VALUE str)`

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 sue445
+
+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,67 @@
+# RubyHeaderParser
+Parser for `ruby.h`
+
+[![test](https://github.com/sue445/ruby_header_parser/actions/workflows/test.yml/badge.svg)](https://github.com/sue445/ruby_header_parser/actions/workflows/test.yml)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add ruby_header_parser
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install ruby_header_parser
+```
+
+## Requirements
+Following is required in addition to Ruby.
+
+### ctags
+macOS
+
+```bash
+brew install universal-ctags
+```
+
+Ubuntu
+
+```bash
+apt-get install -y universal-ctags
+```
+
+## Usage
+```ruby
+require "ruby_header_parser"
+
+parser = RubyHeaderParser::Parser.new
+
+function_definitions = parser.extract_function_definitions
+static_inline_function_definitions = parser.extract_static_inline_function_definitions
+struct_definitions = parser.extract_struct_definitions
+type_definitions = parser.extract_type_definitions
+enum_definitions = parser.extract_enum_definitions
+```
+
+See below for details.
+
+https://sue445.github.io/ruby_header_parser/RubyHeaderParser/Parser.html
+
+See [CONFIG.md](CONFIG.md) for config file details
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sue445/ruby_header_parser.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+namespace :rbs do
+  desc "`rbs collection install` and `git commit`"
+  task :install do
+    sh "rbs collection install"
+    sh "git add rbs_collection.lock.yaml"
+    sh "git commit -m 'rbs collection install' || true"
+  end
+end
+
+desc "Check rbs"
+task :rbs do
+  sh "rbs validate"
+  sh "steep check"
+end
+
+desc "Run all development tasks"
+task dev_all: %i[spec rubocop rbs]
+
+task default: :dev_all

data/Steepfile

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+
+  check "lib" # Directory name
+  # check "Gemfile"                   # File name
+  # check "app/models/**/*.rb"        # Glob
+  # ignore "lib/templates/*.rb"
+
+  # library "pathname"              # Standard libraries
+  # library "strong_json"           # Gems
+
+  collection_config "rbs_collection.yaml"
+
+  # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting (applies by default)
+  # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.lenient)      # `lenient` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.silent)       # `silent` diagnostics setting
+  # configure_code_diagnostics do |hash|             # You can setup everything yourself
+  #   hash[D::Ruby::NoMethod] = :information
+  # end
+end
+
+# target :test do
+#   signature "sig", "sig-private"
+#
+#   check "test"
+#
+#   # library "pathname"              # Standard libraries
+# end

data/config/default.yml

@@ -0,0 +1,170 @@
+function:
+  include_name:
+    - !ruby/regexp /^rb_/i
+    - !ruby/regexp /^rstring_/i
+
+  exclude_name:
+    # deprecated functions
+    - !ruby/regexp /^rb_check_safe_str$/i
+    - !ruby/regexp /^rb_clear_constant_cache$/i
+    - !ruby/regexp /^rb_clone_setup$/i
+    - !ruby/regexp /^rb_complex_polar$/i
+    - !ruby/regexp /^rb_data_object_alloc$/i
+    - !ruby/regexp /^rb_data_object_get_warning$/i
+    - !ruby/regexp /^rb_data_object_wrap_warning$/i
+    - !ruby/regexp /^rb_data_typed_object_alloc$/i
+    - !ruby/regexp /^rb_dup_setup$/i
+    - !ruby/regexp /^rb_gc_force_recycle$/i
+    - !ruby/regexp /^rb_iterate$/i
+    - !ruby/regexp /^rb_obj_infect$/i
+    - !ruby/regexp /^rb_obj_infect_raw$/i
+    - !ruby/regexp /^rb_obj_taint$/i
+    - !ruby/regexp /^rb_obj_taint_raw$/i
+    - !ruby/regexp /^rb_obj_taintable$/i
+    - !ruby/regexp /^rb_obj_tainted$/i
+    - !ruby/regexp /^rb_obj_tainted_raw$/i
+    - !ruby/regexp /^rb_scan_args_length_mismatch$/i
+    - !ruby/regexp /^rb_varargs_bad_length$/i
+
+    # internal functions in ruby.h
+    - rb_scan_args_bad_format
+
+    # internal macros
+    - !ruby/regexp /^rb_define_global_function_(m?[0-9]+|notimpl)$/i
+    - !ruby/regexp /^rb_define_method_(m?[0-9]+|notimpl)$/i
+    - !ruby/regexp /^rb_define_method_id_(m?[0-9]+|notimpl)$/i
+    - !ruby/regexp /^rb_define_module_function_(m?[0-9]+|notimpl)$/i
+    - !ruby/regexp /^rb_define_private_method_(m?[0-9]+|notimpl)$/i
+    - !ruby/regexp /^rb_define_protected_method_(m?[0-9]+|notimpl)$/i
+    - !ruby/regexp /^rb_define_singleton_method_(m?[0-9]+|notimpl)$/i
+
+    # FIXME: Both `rb_hash` and `rb_Hash` are defined in ruby.h
+    #        Converting to Go function names would result in both being `RbHash`
+    #        Exclude one of the function names because duplicate function names will result in an error.
+    - rb_Hash
+
+    # Available only in certain platform
+    - !ruby/regexp /^rb_w32_/i
+
+    # FIXME: Workaround for "could not determine kind of name for C.rb_gc_unprotect_logging"
+    - rb_gc_unprotect_logging
+
+    # FIXME: Workaround for "could not determine kind of name for C.rb_iterate_deprecated"
+    - rb_iterate_deprecated
+
+    # FIXME: Workaround for "could not determine kind of name for C.rb_gc_guarded_ptr_val"
+    - rb_gc_guarded_ptr_val
+
+    # FIXME: Workaround for "cannot use _cgo2 (variable of type _Ctype_va_list) as *_Ctype_struct___va_list_tag value in argument to _Cfunc_rb_str_vcatf" on GitHub Actions (Ubuntu 22.04)
+    - rb_str_vcatf
+
+    # FIXME: Workaround for "cannot use _cgo4 (variable of type _Ctype_va_list) as *_Ctype_struct___va_list_tag value in argument to _Cfunc_rb_vrescue2" on GitHub Actions (Ubuntu 22.04)
+    - rb_vrescue2
+
+    # FIXME: Workaround for "cannot use _cgo1 (variable of type _Ctype_va_list) as *_Ctype_struct___va_list_tag value in argument to _Cfunc_rb_vsprintf" on GitHub Actions (Ubuntu 22.04)
+    - rb_vsprintf
+
+    # FIXME: Workaround for "undefined reference to `rb_class_descendants'" on GitHub Actions (Ubuntu 22.04)
+    - rb_class_descendants
+
+  pointer_hint:
+    RSTRING_PTR:
+      self: raw
+    rb_data_object_make:
+      4: sref
+    rb_data_typed_object_make:
+      3: sref
+    rb_define_global_function:
+      2: function
+    rb_define_method:
+      3: function
+    rb_define_method_id:
+      3: function
+    rb_define_module_function:
+      3: function
+    rb_define_private_method:
+      3: function
+    rb_define_protected_method:
+      3: function
+    rb_define_singleton_method:
+      3: function
+    rb_define_variable:
+      2: in_ref
+    rb_ensure:
+      1: function
+      3: function
+    rb_exec_recursive:
+      1: function
+    rb_exec_recursive_outer:
+      1: function
+    rb_exec_recursive_paired:
+      1: function
+    rb_exec_recursive_paired_outer:
+      1: function
+    rb_feature_provided:
+      2: sref
+    rb_find_file_ext:
+      2: str_array
+    rb_funcallv:
+      4: array
+    rb_funcallv_public:
+      4: array
+    rb_get_values_at:
+      5: function
+    rb_glob:
+      2: function
+    rb_hash_foreach:
+      2: function
+    rb_ivar_foreach:
+      2: function
+    rb_marshal_define_compat:
+      3: function
+      4: function
+    rb_mutex_synchronize:
+      2: function
+    rb_protect:
+      1: function
+    rb_rescue:
+      1: function
+      3: function
+    rb_scan_args_set:
+      10: ref_array
+    rb_set_end_proc:
+      1: function
+    rb_st_insert2:
+      4: function
+    rb_thread_call_with_gvl:
+      1: function
+    rb_thread_create:
+      1: function
+    rb_vrescue2:
+      1: function
+      3: function
+
+struct:
+  include_name:
+    - !ruby/regexp /^rb_/i
+    - re_registers
+
+  exclude_name:
+    - rb_data_type_struct
+
+type:
+  include_name:
+    - !ruby/regexp /^rb_/i
+    - !ruby/regexp /^st_/i
+    - ID
+    - VALUE
+    - regex_t
+    - OnigPosition
+    - pid_t
+    - off_t
+
+  exclude_name: []
+
+enum:
+  include_name:
+    - ruby_value_type
+    - rb_io_wait_readwrite
+
+  exclude_name: []

data/lib/ruby_header_parser/argument_definition.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RubyHeaderParser
+  # argument definition for {RubyHeaderParser::FunctionDefinition}
+  class ArgumentDefinition
+    # @!attribute type
+    #   @return [String]
+    attr_accessor :type
+
+    # @!attribute name
+    #   @return [String]
+    attr_accessor :name
+
+    # @!attribute pointer
+    #   @return [Symbol,nil] :ref, :array
+    attr_accessor :pointer
+
+    # @!attribute length
+    #   @return [Integer]
+    attr_accessor :length
+
+    # @param type [String]
+    # @param name [String]
+    # @param pointer [Symbol,nil] :ref, :array
+    # @param length [String]
+    def initialize(type:, name:, pointer: nil, length: 0)
+      @type = type
+      @name = name
+      @pointer = pointer
+      @length = length
+    end
+
+    # @param other [ArgumentDefinition]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(ArgumentDefinition) && type == other.type && name == other.name && pointer == other.pointer &&
+        length == other.length
+    end
+
+    # @return [Boolean]
+    def pointer?
+      !!pointer
+    end
+  end
+end

data/lib/ruby_header_parser/config.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RubyHeaderParser
+  # Manager for config file
+  class Config
+    # @!attribute [r] data
+    #   @return [Hash]
+    attr_reader :data
+
+    # @param config_file [String]
+    #
+    # @note See [CONFIG.md](../file.CONFIG.html) for config file details
+    def initialize(config_file)
+      yaml = File.read(config_file)
+      @data = YAML.safe_load(yaml, aliases: true, permitted_classes: [Regexp])
+    end
+
+    # @param function_name [String]
+    # @param pos [Integer] arg position (1 origin)
+    # @return [Symbol] :ref, :array, :ref_array, :function, :sref, :str_array, :in_ref
+    def function_arg_pointer_hint(function_name:, pos:)
+      pointer_hint = data["function"]["pointer_hint"].dig(function_name, pos)
+      return pointer_hint.to_sym if pointer_hint
+
+      :ref
+    end
+
+    # @param function_name [String]
+    # @return [Symbol] :ref, :raw
+    def function_self_pointer_hint(function_name)
+      pointer_hint = data["function"]["pointer_hint"].dig(function_name, "self")
+      return pointer_hint.to_sym if pointer_hint
+
+      :ref
+    end
+
+    # rubocop:disable Style/CaseEquality
+
+    # Whether generate C function to go
+    # @param function_name [String]
+    # @return [Boolean]
+    def should_generate_function?(function_name)
+      return false if data["function"]["exclude_name"].any? { |format| format === function_name }
+
+      data["function"]["include_name"].any? { |format| format === function_name }
+    end
+
+    # Whether generate C struct to go
+    # @param struct_name [String]
+    # @return [Boolean]
+    def should_generate_struct?(struct_name)
+      return false if data["struct"]["exclude_name"].any? { |format| format === struct_name }
+
+      data["struct"]["include_name"].any? { |format| format === struct_name }
+    end
+
+    # Whether generate C type to go
+    # @param type_name [String]
+    # @return [Boolean]
+    def should_generate_type?(type_name)
+      return false if data["type"]["exclude_name"].any? { |format| format === type_name }
+
+      data["type"]["include_name"].any? { |format| format === type_name }
+    end
+
+    # Whether generate C enum to go
+    # @param enum_name [String]
+    # @return [Boolean]
+    def should_generate_enum?(enum_name)
+      return false if data["enum"]["exclude_name"].any? { |format| format === enum_name }
+
+      data["enum"]["include_name"].any? { |format| format === enum_name }
+    end
+
+    # rubocop:enable Style/CaseEquality
+  end
+end

data/lib/ruby_header_parser/enum_definition.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyHeaderParser
+  # enum definition in header file
+  class EnumDefinition
+    # @!attribute name
+    #   @return [String]
+    attr_accessor :name
+
+    # @!attribute enum_value_definitions
+    #   @return [Array<String>]
+    attr_accessor :values
+
+    # @param name [String]
+    # @param values [Array<String>]
+    def initialize(name:, values: [])
+      @name = name
+      @values = values
+    end
+
+    # @param other [EnumDefinition]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(EnumDefinition) && name == other.name && values == other.values
+    end
+  end
+end