wrapture 0.2.2 → 0.3.0

data/lib/wrapture/rule_spec.rb

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+# Copyright 2019-2020 Joel E. Anderson
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'wrapture/constants'
+require 'wrapture/errors'
+
+module Wrapture
+  # A condition (or set of conditions) that a struct or its members must meet
+  # in order to conform to a given specification. This allows a single struct
+  # type to be equivalent to some class specifications, but not others.
+  class RuleSpec
+    # A list of valid condition strings.
+    CONDITIONS = %w[equals not-equals].freeze
+
+    # Normalizes a hash specification of a rule. Normalization checks for
+    # invalid keys and unrecognized conditions.
+    def self.normalize_spec_hash(spec)
+      normalized = spec.dup
+
+      required_keys = if spec.key?('member-name')
+                        normalized['type'] = 'struct-member'
+                        %w[member-name condition value].freeze
+                      else
+                        normalized['type'] = 'expression'
+                        %w[left-expression condition right-expression].freeze
+                      end
+
+      missing_keys = required_keys - spec.keys
+      unless missing_keys.empty?
+        missing_msg = "required keys are missing: #{missing_keys.join(', ')}"
+        raise(MissingSpecKey, missing_msg)
+      end
+
+      extra_keys = spec.keys - required_keys
+      unless extra_keys.empty?
+        extra_msg = "these keys are unrecognized: #{extra_keys.join(', ')}"
+        raise(InvalidSpecKey, extra_msg)
+      end
+
+      unless RuleSpec::CONDITIONS.include?(spec['condition'])
+        condition_msg = "#{spec['condition']} is an invalid condition"
+        raise(InvalidSpecKey, condition_msg)
+      end
+
+      normalized
+    end
+
+    # Creates a rule spec based on the provided spec.
+    #
+    # The hash must have the following keys:
+    # member-name:: the name of the struct member the rule applies to
+    # condition:: the condition this rule uses (supported values are held in the
+    # RuleSpec::CONDITIONS list)
+    # value:: the value to use in the condition check
+    def initialize(spec)
+      @spec = RuleSpec.normalize_spec_hash(spec)
+    end
+
+    # A string containing a check for a struct of the given name for this rule.
+    def check(variable: nil)
+      condition = @spec['condition'] == 'equals' ? '==' : '!='
+
+      if @spec['type'] == 'struct-member'
+        "#{variable}->#{@spec['member-name']} #{condition} #{@spec['value']}"
+      else
+        left = @spec['left-expression']
+        right = @spec['right-expression']
+        "#{left} #{condition} #{right}".sub(RETURN_VALUE_KEYWORD, 'return_val')
+      end
+    end
+  end
+end

data/lib/wrapture/scope.rb

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+# Copyright 2019 Joel E. Anderson
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Wrapture
+  # Describes a scope of one or more class specifications.
+  class Scope
+    # A list of classes currently in the scope.
+    attr_reader :classes
+
+    # Creates an empty scope with no classes in it.
+    def initialize(spec = nil)
+      @classes = []
+
+      return if spec.nil? || !spec.key?('classes')
+
+      @version = Wrapture.spec_version(spec)
+      spec['classes'].each do |class_hash|
+        ClassSpec.new(class_hash, scope: self)
+      end
+    end
+
+    # Adds a class specification to the scope.
+    #
+    # This does not set the scope as the owner of the class. This must be done
+    # during the construction of the class spec.
+    def <<(spec)
+      @classes << spec if spec.is_a?(ClassSpec)
+    end
+
+    # Generates the wrapper class files for all classes in the scope.
+    def generate_wrappers
+      files = []
+
+      @classes.each do |class_spec|
+        files.concat(class_spec.generate_wrappers)
+      end
+
+      files
+    end
+
+    # A list of ClassSpecs in this scope that are overloads of the given class.
+    def overloads(parent)
+      @classes.select { |class_spec| class_spec.overloads?(parent) }
+    end
+
+    # True if there is an overload of the given class in this scope.
+    def overloads?(parent)
+      @classes.any? { |class_spec| class_spec.overloads?(parent) }
+    end
+
+    # Returns the ClassSpec for the given type in the scope.
+    def type(type)
+      @classes.find { |class_spec| class_spec.name == type }
+    end
+
+    # Returns true if the given type is in the scope.
+    def type?(type)
+      @classes.each do |class_spec|
+        return true if class_spec.name == type
+      end
+
+      false
+    end
+  end
+end

data/lib/wrapture/struct_spec.rb

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+# Copyright 2019 Joel E. Anderson
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Wrapture
+  # A description of a struct.
+  class StructSpec
+    # Normalizes a hash specification of a struct. Normalization will check for
+    # things like invalid keys, duplicate entries in include lists, and will set
+    # missing keys to their default value (for example, an empty list if no
+    # includes are given).
+    def self.normalize_spec_hash(spec)
+      normalized = spec.dup
+      normalized.default = []
+
+      normalized['includes'] = Wrapture.normalize_includes spec['includes']
+
+      normalized['members'] ||= []
+
+      normalized
+    end
+
+    # A list of rules defined for this struct.
+    attr_reader :rules
+
+    # Creates a struct spec based on the provided spec hash.
+    #
+    # The hash must have the following keys:
+    # name:: the name of the struct
+    #
+    # The following keys are optional:
+    # includes:: a list of includes required for the struct
+    # members:: a list of the members of the struct, each with a type and name
+    # field
+    # rules:: a list of conditions this struct and its members must meet (refer
+    # to the RuleSpec class for more details)
+    def initialize(spec)
+      @spec = StructSpec.normalize_spec_hash(spec)
+
+      @rules = @spec['rules'].map { |rule_spec| RuleSpec.new(rule_spec) }
+    end
+
+    # A declaration of the struct with the given variable name.
+    def declaration(name)
+      "struct #{@spec['name']} #{name}"
+    end
+
+    # A list of includes required for this struct.
+    def includes
+      @spec['includes'].dup
+    end
+
+    # A string containing the typed members of the struct, separated by commas.
+    def member_list
+      members = []
+
+      @spec['members'].each do |member|
+        members << ClassSpec.typed_variable(member['type'], member['name'])
+      end
+
+      members.join ', '
+    end
+
+    # A string containing the typed members of the struct, with their default
+    # values if provided, separated by commas.
+    def member_list_with_defaults
+      @spec['members'].map do |member|
+        member_str = ClassSpec.typed_variable(member['type'], member['name'])
+
+        if member.key?('default-value')
+          default_value = member['default-value']
+
+          member_str += ' = '
+          member_str += if member['type'] == 'const char *'
+                          '"' + default_value + '"'
+                        elsif member['type'].end_with?('char')
+                          "'#{default_value}'"
+                        else
+                          default_value.to_s
+                        end
+        end
+
+        member_str
+      end.join(', ')
+    end
+
+    # The members of the struct
+    def members
+      @spec['members']
+    end
+
+    # True if there are members included in the struct specification.
+    def members?
+      !@spec['members'].empty?
+    end
+
+    # The name of this struct
+    def name
+      @spec['name']
+    end
+
+    # A declaration of a pointer to the struct with the given variable name.
+    def pointer_declaration(name)
+      "struct #{@spec['name']} *#{name}"
+    end
+
+    # A string containing an expression that returns true if the struct with
+    # the given name meets all rules defined for this struct.
+    def rules_check(name)
+      @rules.map { |rule| rule.check(variable: name) }.join(' && ')
+    end
+  end
+end

data/lib/wrapture/version.rb

@@ -1,5 +1,15 @@
 # frozen_string_literal: true
 
 module Wrapture
-  VERSION = '0.2.2'
+  # the current version of Wrapture
+  VERSION = '0.3.0'
+
+  # Returns true if the version of the spec is supported by this version of
+  # Wrapture. Otherwise returns false.
+  def self.supports_version?(version)
+    wrapture_version = Gem::Version.new(Wrapture::VERSION)
+    spec_version = Gem::Version.new(version)
+
+    spec_version <= wrapture_version
+  end
 end

data/lib/wrapture/wrapped_function_spec.rb

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+# Copyright 2019-2020 Joel E. Anderson
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Wrapture
+  # A description of a function to be wrapped by another language.
+  class WrappedFunctionSpec
+    # Normalizes a hash specification of a wrapped function. Normalization will
+    # check for things like invalid keys, duplicate entries in include lists,
+    # and will set missing keys to their default values (for example, an empty
+    # list if no includes are given).
+    def self.normalize_spec_hash(spec)
+      normalized = spec.dup
+
+      normalized['params'] ||= []
+      normalized['params'].each do |param_spec|
+        param_spec['value'] = param_spec['name'] if param_spec['value'].nil?
+      end
+
+      normalized['includes'] = Wrapture.normalize_includes(spec['includes'])
+
+      normalized['error-check'] ||= {}
+      normalized['error-check']['rules'] ||= []
+
+      unless spec.key?('return')
+        normalized['return'] = {}
+        normalized['return']['type'] = 'void'
+      end
+
+      normalized
+    end
+
+    # Creates a wrapped function spec based on the provided spec.
+    #
+    # The hash must have the following keys:
+    # name:: the name of the wrapped function
+    # params:: a list of parameters to supply when calling
+    #
+    # Each member of the params list must be a hash, with a mandatory key of
+    # 'value' holding the value to be supplied as the parameter. If only a
+    # 'name' key is provided, this will be used as the value. A 'type' may be
+    # supplied as well, and is necessary if an equivalent struct or pointer is
+    # to be supplied as the value so that casting can be performed correctly.
+    #
+    # The following key is optional:
+    # includes:: a list of includes needed for this function
+    def initialize(spec)
+      @spec = self.class.normalize_spec_hash(spec)
+
+      check = @spec['error-check']
+
+      @error_rules = check['rules'].map do |rule_spec|
+        RuleSpec.new(rule_spec)
+      end
+
+      action = check['error-action']
+      @error_action = ActionSpec.new(action) unless @error_rules.empty?
+    end
+
+    # Generates a function call from a provided FunctionSpec. Paremeters and
+    # types are resolved using this function's context.
+    def call_from(function_spec)
+      resolved_params = []
+
+      @spec['params'].each do |param|
+        resolved_params << function_spec.resolve_wrapped_param(param)
+      end
+
+      "#{@spec['name']}( #{resolved_params.join(', ')} )"
+    end
+
+    # Yields each line of the error check and any actions taken for this wrapped
+    # function. If this function does not have any error check defined, then
+    # this function returns without yielding anything.
+    def error_check
+      return if @error_rules.empty?
+
+      checks = @error_rules.map(&:check)
+      yield "if( #{checks.join(' && ')} ){"
+      yield "  #{@error_action.take};"
+      yield '}'
+    end
+
+    # True if the wrapped function has an error check associated with it.
+    def error_check?
+      !@error_rules.empty?
+    end
+
+    # A list of includes required for this function call.
+    def includes
+      includes = @spec['includes'].dup
+
+      includes.concat(@error_action.includes) if error_check?
+
+      includes
+    end
+
+    # A string with the type of the return value.
+    def return_val_type
+      @spec['return']['type']
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wrapture
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Joel Anderson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-01 00:00:00.000000000 Z
+date: 2020-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -17,13 +17,19 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.6.4
-  type: :runtime
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.6.4
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.2'
 description: Wraps C code in C++.
 email: joelanderson333@gmail.com
 executables:
@@ -33,10 +39,18 @@ extra_rdoc_files: []
 files:
 - bin/wrapture
 - lib/wrapture.rb
+- lib/wrapture/action_spec.rb
 - lib/wrapture/class_spec.rb
 - lib/wrapture/constant_spec.rb
+- lib/wrapture/constants.rb
+- lib/wrapture/errors.rb
 - lib/wrapture/function_spec.rb
+- lib/wrapture/normalize.rb
+- lib/wrapture/rule_spec.rb
+- lib/wrapture/scope.rb
+- lib/wrapture/struct_spec.rb
 - lib/wrapture/version.rb
+- lib/wrapture/wrapped_function_spec.rb
 homepage: http://rubygems.org/gems/wrapture
 licenses:
 - Apache-2.0