wrapture 0.2.2 → 0.5.0

data/lib/wrapture/param_spec.rb

@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+#--
+# Copyright 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/type_spec'
+
+module Wrapture
+  # A description of a parameter used in a generated function.
+  class ParamSpec
+    # Returns a list of new ParamSpecs based on the provided array of parameter
+    # specification hashes.
+    def self.new_list(spec_list)
+      spec_list.map { |spec| new(spec) }
+    end
+
+    # Returns a normalized copy of a list of parameter hash specifications in
+    # place.
+    #
+    # Multiple variadic parameters (named '...') will be removed and only the
+    # first used. If the variadic parameter is not last, it will be moved to
+    # the end of the list.
+    def self.normalize_param_list(spec_list)
+      if spec_list.nil?
+        []
+      elsif spec_list.count { |spec| spec['name'] == '...' }.zero?
+        spec_list.map { |spec| normalize_spec_hash(spec) }
+      else
+        error_msg = "'...' may not be the only parameter"
+        raise(InvalidSpecKey, error_msg) if spec_list.count == 1
+
+        i = spec_list.find_index { |spec| spec['name'] == '...' }
+        var = spec_list[i]
+
+        spec_list
+          .reject { |spec| spec['name'] == '...' }
+          .map { |spec| normalize_spec_hash(spec) }
+          .push(var)
+      end
+    end
+
+    # Returns a normalized copy of the hash specification of a parameter in
+    # +spec+. See normalize_spec_hash! for details.
+    def self.normalize_spec_hash(spec)
+      normalize_spec_hash!(Marshal.load(Marshal.dump(spec)))
+    end
+
+    # Normalizes the hash specification of a parameter in +spec+ in place.
+    # Normalization will remove duplicate entries from include lists and
+    # validate that required key values are set.
+    def self.normalize_spec_hash!(spec)
+      Comment.validate_doc(spec['doc']) if spec.key?('doc')
+      spec['includes'] = Wrapture.normalize_includes(spec['includes'])
+
+      spec['type'] = '...' if spec['name'] == '...'
+
+      unless spec.key?('type')
+        missing_type_msg = 'parameters must have a type key defined'
+        raise(MissingSpecKey, missing_type_msg)
+      end
+
+      spec
+    end
+
+    # A string with a comma-separated list of parameters (using resolved type)
+    # and names, fit for use in a function signature or declaration. param_list
+    # must be a list of ParamSpec instances, and owner must be the FunctionSpec
+    # that the parameters belong to.
+    def self.signature(param_list, owner)
+      if param_list.empty?
+        'void'
+      else
+        param_list.map { |param| param.signature(owner) }.join(', ')
+      end
+    end
+
+    # The type of the parameter.
+    attr_reader :type
+
+    # Creates a parameter specification based on the provided hash spec.
+    def initialize(spec)
+      @spec = ParamSpec.normalize_spec_hash(spec)
+      @type = TypeSpec.new(@spec['type'])
+    end
+
+    # A Comment holding the parameter documentation.
+    def doc
+      if @spec.key?('doc')
+        Comment.new("@param #{@spec['name']} #{@spec['doc']}")
+      else
+        Comment.new
+      end
+    end
+
+    # A list of includes needed for this parameter.
+    def includes
+      @spec['includes'].dup.concat(@type.includes)
+    end
+
+    # The name of the parameter.
+    def name
+      @spec['name']
+    end
+
+    # The parameter type and name, suitable for use in a function signature or
+    # declaration. +owner+ must be the FunctionSpec that the parameter belongs
+    # to.
+    def signature(owner)
+      @type.resolve(owner).variable(name)
+    end
+
+    # True if this parameter is variadic (the name is equal to '...').
+    def variadic?
+      @type.variadic?
+    end
+  end
+end

data/lib/wrapture/rule_spec.rb

@@ -0,0 +1,118 @@
+# 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 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 map of condition strings to their operators.
+    CONDITIONS = { 'equals' => '==',
+                   'greater-than' => '>',
+                   'greater-than-equal' => '>=',
+                   'less-than' => '<',
+                   'less-than-equal' => '<=',
+                   '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.keys.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. Rules may be one of a
+    # number of different varieties.
+    #
+    # Available conditions are available in the RuleSpec::CONDITIONS map, with
+    # the mapped values being the operate each one translates to.
+    #
+    # For a rule that checks a struct member against a given value (a
+    # +struct-member+ rule):
+    # member-name:: the name of the struct member the rule applies to
+    # condition:: the condition this rule uses
+    # value:: the value to use in the condition check
+    #
+    # For a rule that compares two expressions against one another (an
+    # +expression+ rule):
+    # left-expression:: the left expression in the comparison
+    # condition:: the condition this rule uses
+    # right-expression:: the right expression in the comparison
+    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.
+    #
+    # +variable+ can be provided to provide the variable holding a struct
+    # pointer for +struct-member+ rules.
+    #
+    # +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 check(variable: nil, return_val: 'return_val')
+      condition = RuleSpec::CONDITIONS[@spec['condition']]
+
+      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
+
+    # True if this rule requires a return value. This is equivalent to checking
+    # for the presence of RETURN_VALUE_KEYWORD in any of the expressions.
+    #
+    # This method was added in release 0.4.2.
+    def use_return?
+      @spec['type'] == 'expression' &&
+        [@spec['left-expression'],
+         @spec['right-expression']].include?(RETURN_VALUE_KEYWORD)
+    end
+  end
+end

data/lib/wrapture/scope.rb

@@ -0,0 +1,112 @@
+# 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
+  # Describes a scope of one or more class specifications.
+  class Scope
+    # A list of classes currently in the scope.
+    attr_reader :classes
+
+    # A list of enumerations currently in the scope.
+    attr_reader :enums
+
+    # A list of the templates defined in the scope.
+    attr_reader :templates
+
+    # Creates an empty scope with no classes in it.
+    def initialize(spec = nil)
+      @classes = []
+      @enums = []
+      @templates = []
+
+      return if spec.nil?
+
+      @version = Wrapture.spec_version(spec)
+
+      @templates = spec.fetch('templates', []).collect do |template_hash|
+        TemplateSpec.new(template_hash)
+      end
+
+      @classes = spec.fetch('classes', []).collect do |class_hash|
+        ClassSpec.new(class_hash, scope: self)
+      end
+
+      @enums = spec.fetch('enums', []).collect do |enum_hash|
+        EnumSpec.new(enum_hash)
+      end
+    end
+
+    # Adds a class or template specification to the scope.
+    #
+    # This does not set the scope as the owner of the class for a ClassSpec.
+    # This must be done during the construction of the class spec.
+    def <<(spec)
+      @templates << spec if spec.is_a?(TemplateSpec)
+      @classes << spec if spec.is_a?(ClassSpec)
+      @enums << spec if spec.is_a?(EnumSpec)
+    end
+
+    # Adds a class to the scope created from the given specification hash.
+    def add_class_spec_hash(spec)
+      ClassSpec.new(spec, scope: self)
+    end
+
+    # Adds an enumeration to the scope created from the given specification
+    # hash.
+    def add_enum_spec_hash(spec)
+      @enums << EnumSpec.new(spec)
+    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
+
+      @enums.each do |enum_spec|
+        files.concat(enum_spec.generate_wrapper)
+      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, if one exists.
+    def type(type)
+      @classes.find { |class_spec| class_spec.name == type.base }
+    end
+
+    # Returns true if there is a class matching the given +type+ in this scope.
+    def type?(type)
+      @classes.any? { |class_spec| class_spec.name == type.base }
+    end
+  end
+end

data/lib/wrapture/struct_spec.rb

@@ -0,0 +1,129 @@
+# 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 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 << TypeSpec.new(member['type']).variable(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 = TypeSpec.new(member['type']).variable(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