wrapture 0.2.2 → 0.5.0

data/lib/wrapture/version.rb

@@ -1,5 +1,33 @@
+# 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
-  VERSION = '0.2.2'
+  # the current version of Wrapture
+  VERSION = '0.5.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,134 @@
+# 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.
+    #
+    # +return_val+ is used as the replacement for a return value signified by
+    # the use of RETURN_VALUE_KEYWORD in the spec. If not specified it defaults
+    # to +'return_val'+. This parameter was added in release 0.4.2.
+    def error_check(return_val: 'return_val')
+      return if @error_rules.empty?
+
+      checks = @error_rules.map { |rule| rule.check(return_val: return_val) }
+      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 TypeSpec describing the type of the return value.
+    #
+    # Changed in release 0.4.2 to return a TypeSpec instead of a String.
+    def return_val_type
+      TypeSpec.new(@spec['return']['type'])
+    end
+
+    # True if calling this wrapped function needs to save/use the return value
+    # for error checking. This is equivalent to checking all error rules for the
+    # use of RETURN_VALUE_KEYWORD.
+    #
+    # This method was added in release 0.4.2.
+    def use_return?
+      @error_rules.any?(&:use_return?)
+    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.5.0
 platform: ruby
 authors:
 - Joel Anderson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-01 00:00:00.000000000 Z
+date: 2020-12-15 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.3'
+  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.3'
 description: Wraps C code in C++.
 email: joelanderson333@gmail.com
 executables:
@@ -33,16 +39,30 @@ extra_rdoc_files: []
 files:
 - bin/wrapture
 - lib/wrapture.rb
+- lib/wrapture/action_spec.rb
 - lib/wrapture/class_spec.rb
+- lib/wrapture/comment.rb
 - lib/wrapture/constant_spec.rb
+- lib/wrapture/constants.rb
+- lib/wrapture/enum_spec.rb
+- lib/wrapture/errors.rb
 - lib/wrapture/function_spec.rb
+- lib/wrapture/normalize.rb
+- lib/wrapture/param_spec.rb
+- lib/wrapture/rule_spec.rb
+- lib/wrapture/scope.rb
+- lib/wrapture/struct_spec.rb
+- lib/wrapture/template_spec.rb
+- lib/wrapture/type_spec.rb
 - lib/wrapture/version.rb
-homepage: http://rubygems.org/gems/wrapture
+- lib/wrapture/wrapped_function_spec.rb
+homepage: https://goatshriek.github.io/wrapture/
 licenses:
 - Apache-2.0
 metadata:
   bug_tracker_uri: https://github.com/goatshriek/wrapture/issues
-  changelog_uri: https://github.com/goatshriek/wrapture/blob/master/ChangeLog.md
+  changelog_uri: https://github.com/goatshriek/wrapture/blob/latest/ChangeLog.md
+  documentation_uri: https://goatshriek.github.io/wrapture/rdoc/
   source_code_uri: https://github.com/goatshriek/wrapture/
 post_install_message: 
 rdoc_options: []
@@ -52,14 +72,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.3'
+      version: '2.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.2.1
 signing_key: 
 specification_version: 4
 summary: wrap C in C++