class Wrapture::WrappedFunctionSpec

A description of a function to be wrapped by another language.

Public Class Methods

new(spec) click to toggle source

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

# File lib/wrapture/wrapped_function_spec.rb, line 63
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

normalize_spec_hash(spec) click to toggle source

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).

# File lib/wrapture/wrapped_function_spec.rb, line 28
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

Public Instance Methods

call_from(function_spec) click to toggle source

Generates a function call from a provided FunctionSpec. Paremeters and types are resolved using this function's context.

# File lib/wrapture/wrapped_function_spec.rb, line 78
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

error_check(return_val: 'return_val') { |"if( #{join(' && ')} ){"| ... } click to toggle source

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.

# File lib/wrapture/wrapped_function_spec.rb, line 95
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

error_check?() click to toggle source

True if the wrapped function has an error check associated with it.

# File lib/wrapture/wrapped_function_spec.rb, line 105
def error_check?
  !@error_rules.empty?
end

includes() click to toggle source

A list of includes required for this function call.

# File lib/wrapture/wrapped_function_spec.rb, line 110
def includes
  includes = @spec['includes'].dup

  includes.concat(@error_action.includes) if error_check?

  includes
end

return_val_type() click to toggle source

A TypeSpec describing the type of the return value.

Changed in release 0.4.2 to return a TypeSpec instead of a String.

# File lib/wrapture/wrapped_function_spec.rb, line 121
def return_val_type
  TypeSpec.new(@spec['return']['type'])
end

use_return?() click to toggle source

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.

# File lib/wrapture/wrapped_function_spec.rb, line 130
def use_return?
  @error_rules.any?(&:use_return?)
end