wrapture 0.2.2 → 0.5.0

data/lib/wrapture/comment.rb

@@ -0,0 +1,107 @@
+# 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.
+#++
+
+module Wrapture
+  # A comment that can be inserted in generated source code.
+  #
+  # Comments are primarily used to insert documentation about generated code for
+  # documentation generation tools such as Doxygen.
+  class Comment
+    # Validates a doc string.
+    def self.validate_doc(doc)
+      raise InvalidDoc, 'a doc must be a string' unless doc.is_a?(String)
+    end
+
+    # The raw text of the comment.
+    attr_reader :text
+
+    # Creates a comment from a string. If the provided string is nil, then an
+    # empty string is used.
+    def initialize(comment = '')
+      @text = comment.nil? ? '' : comment
+    end
+
+    # True if this comment is empty, false otherwise.
+    def empty?
+      @text.empty?
+    end
+
+    # Yields each line of the comment formatted as specified.
+    def format(line_prefix: '// ', first_line: nil, last_line: nil,
+               max_line_length: 80)
+      return if @text.empty?
+
+      yield first_line if first_line
+
+      paragraphs(max_line_length - line_prefix.length) do |line|
+        yield "#{line_prefix}#{line}".rstrip
+      end
+
+      yield last_line if last_line
+    end
+
+    # Calls the given block for each line of the comment formatted using Doxygen
+    # style.
+    def format_as_doxygen(max_line_length: 80, &block)
+      format(line_prefix: ' * ', first_line: '/**',
+             last_line: ' */', max_line_length: max_line_length) do |line|
+        block.call(line)
+      end
+    end
+
+    private
+
+    # Yields the comment converted into paragraph-style blocks.
+    #
+    # Consecutive lines with text are concatenated together to the maximum line
+    # length, regardless of the original line length in the comment. One or more
+    # empty lines are written as a single empty line, separating paragraphs.
+    #
+    # Yielded lines may have trailing spaces, which are not considered part of
+    # the maximum length. The caller must strip these off.
+    def paragraphs(line_length)
+      running_line = String.new
+      newline_mode = true
+      @text.each_line do |line|
+        if line.strip.empty?
+          unless newline_mode
+            yield running_line
+            yield ''
+            running_line.clear
+            newline_mode = true
+          end
+        else
+          newline_mode = false
+        end
+
+        line.scan(/\S+/) do |word|
+          if running_line.length + word.length > line_length
+            yield running_line
+            running_line = String.new("#{word} ")
+          else
+            running_line << word << ' '
+          end
+        end
+      end
+
+      yield running_line
+    end
+  end
+end

data/lib/wrapture/constant_spec.rb

@@ -1,34 +1,76 @@
+# 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 constant.
   class ConstantSpec
+    # Normalizes a hash specification of a constant. 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 = spec.dup
+      Comment.validate_doc(spec['doc']) if spec.key?('doc')
+
+      normalized = spec.dup
 
-      normalized_spec['includes'] ||= []
-      normalized_spec['includes'].uniq!
+      normalized['version'] = Wrapture.spec_version(spec)
+      normalized['includes'] = Wrapture.normalize_includes spec['includes']
 
-      normalized_spec
+      normalized
     end
 
+    # Creates a constant spec based on the provided hash spec
+    #
+    # The hash must have the following keys:
+    # name:: the name of the constant
+    # type:: the type of the constant
+    # value:: the value to assign to the constant
+    # includes::  a list of includes that need to be added in order for this
+    # constant to be valid (for example, includes for the type and value).
+    #
+    # The following keys are optional:
+    # doc:: a string containing the documentation for this constant
     def initialize(spec)
-      @spec = ConstantSpec.normalize_spec_hash spec
+      @spec = ConstantSpec.normalize_spec_hash(spec)
+      @doc = @spec.key?('doc') ? Comment.new(@spec['doc']) : nil
+      @type = TypeSpec.new(@spec['type'])
     end
 
+    # A list of includes needed for the declaration of this constant.
     def declaration_includes
       @spec['includes'].dup
     end
 
+    # A list of includes needed for the definition of this constant.
     def definition_includes
       @spec['includes'].dup
     end
 
-    def declaration
-      "static const #{ClassSpec.typed_variable(@spec['type'], @spec['name'])}"
+    # Calls the given block once for each line of the declaration of this
+    # constant, including any documentation.
+    def declaration(&block)
+      @doc&.format_as_doxygen(max_line_length: 76) { |line| block.call(line) }
+      block.call("static const #{@type.variable(@spec['name'])};")
     end
 
+    # The definition of this constant.
     def definition(class_name)
       expanded_name = "#{class_name}::#{@spec['name']}"
       "const #{@spec['type']} #{expanded_name} = #{@spec['value']}"

data/lib/wrapture/constants.rb

@@ -0,0 +1,41 @@
+# 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 string denoting an equivalent struct type or value.
+  EQUIVALENT_STRUCT_KEYWORD = 'equivalent-struct'
+
+  # A string denoting a pointer to an equivalent struct type or value.
+  EQUIVALENT_POINTER_KEYWORD = 'equivalent-struct-pointer'
+
+  # A string denoting the return value of a wrapped function call.
+  RETURN_VALUE_KEYWORD = 'return-value'
+
+  # A string denoting a reference to the object a method is called on.
+  SELF_REFERENCE_KEYWORD = 'self-reference'
+
+  # A string denoting a reference to a template.
+  TEMPLATE_USE_KEYWORD = 'use-template'
+
+  # A list of all keywords.
+  KEYWORDS = [EQUIVALENT_STRUCT_KEYWORD, EQUIVALENT_POINTER_KEYWORD,
+              SELF_REFERENCE_KEYWORD, RETURN_VALUE_KEYWORD,
+              TEMPLATE_USE_KEYWORD].freeze
+end

data/lib/wrapture/enum_spec.rb

@@ -0,0 +1,155 @@
+# 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.
+#++
+
+module Wrapture
+  # A description of an enumeration.
+  class EnumSpec
+    # Returns a normalized copy of a hash specification of an enumeration in
+    # place. See normalize_spec_hash! for details.
+    def self.normalize_spec_hash(spec)
+      normalize_spec_hash!(Marshal.load(Marshal.dump(spec)))
+    end
+
+    # Normalizes a hash specification of an enumeration in place. Normalization
+    # will remove duplicate entries in include lists and check for a name key.
+    def self.normalize_spec_hash!(spec)
+      unless spec.key?('name')
+        raise MissingSpecKey, 'a name is required for enumerations'
+      end
+
+      if spec.key?('elements')
+        unless spec['elements'].is_a?(Array)
+          raise InvalidSpecKey, 'the elements key must be an array'
+        end
+      else
+        raise MissingSpecKey, 'elements are required for enumerations'
+      end
+
+      spec['includes'] = Wrapture.normalize_includes(spec['includes'])
+      spec['elements'].each do |element|
+        element['includes'] = Wrapture.normalize_includes(element['includes'])
+      end
+
+      spec
+    end
+
+    # Creates an enumeration specification based on the provided hash spec.
+    def initialize(spec)
+      @spec = EnumSpec.normalize_spec_hash(spec)
+
+      @doc = Comment.new(@spec.fetch('doc', nil))
+    end
+
+    # Generates the wrapper definition file.
+    def generate_wrapper
+      filename = "#{@spec['name']}.hpp"
+
+      File.open(filename, 'w') do |file|
+        definition_contents do |line|
+          file.puts(line)
+        end
+      end
+
+      [filename]
+    end
+
+    # The name of the enumeration.
+    def name
+      @spec['name']
+    end
+
+    private
+
+    # Yields each line of the definition of the wrapper for this enum.
+    def definition_contents
+      indent = 0
+
+      yield "#ifndef #{header_guard}"
+      yield "#define #{header_guard}"
+      yield
+
+      definition_includes.each { |filename| yield "#include <#{filename}>" }
+      yield
+
+      if @spec.key?('namespace')
+        yield "namespace #{@spec['namespace']} {"
+        yield
+        indent += 2
+      end
+
+      @doc.format_as_doxygen(max_line_length: 76) do |line|
+        yield "#{' ' * indent}#{line}"
+      end
+
+      yield "#{' ' * indent}enum class #{name} {"
+      indent += 2
+
+      elements = @spec['elements']
+      elements[0...-1].each do |element|
+        element_doc(element) { |line| yield "#{' ' * indent}#{line}" }
+        element_definition(element) { |line| yield "#{' ' * indent}#{line}," }
+      end
+
+      element_doc(elements.last) { |line| yield "#{' ' * indent}#{line}" }
+      element_definition(elements.last) do |line|
+        yield "#{' ' * indent}#{line}"
+      end
+
+      indent -= 2
+      yield "#{' ' * indent}};"
+      yield
+      yield '}' if @spec.key?('namespace')
+      yield
+      yield "#endif /* #{header_guard} */"
+    end
+
+    # A list of the includes needed for the definition of the enumeration.
+    def definition_includes
+      includes = @spec['includes'].dup
+
+      @spec['elements'].each do |element|
+        includes.concat(element['includes'])
+      end
+
+      includes.uniq
+    end
+
+    # Yields each line of the definition of an element.
+    def element_definition(element)
+      if element.key?('value')
+        yield "#{element['name']} = #{element['value']}"
+      else
+        yield element['name']
+      end
+    end
+
+    # Calls the given block once for each line of the documentation for an
+    # element.
+    def element_doc(element, &block)
+      doc = Comment.new(element.fetch('doc', nil))
+      doc.format_as_doxygen(max_line_length: 74) { |line| block.call(line) }
+    end
+
+    # The header guard for the enumeration.
+    def header_guard
+      "__#{@spec['name'].upcase}_HPP"
+    end
+  end
+end

data/lib/wrapture/errors.rb

@@ -0,0 +1,67 @@
+# 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
+  # An error from the Wrapture library
+  class WraptureError < StandardError
+  end
+
+  # A documentation string is invalid.
+  class InvalidDoc < WraptureError
+  end
+
+  # A template has been invoked in an unsupported way.
+  class InvalidTemplateUsage < WraptureError
+  end
+
+  # The spec has a key that is not valid.
+  class InvalidSpecKey < WraptureError
+    # Creates an InvalidSpecKey with the given message. A list of valid values
+    # may optionally be passed to +valid_keys+ which will be added to the end
+    # of the message.
+    def initialize(message, valid_keys: [])
+      complete_message = message.dup
+
+      unless valid_keys.empty?
+        complete_message << ' (valid values are \''
+        complete_message << valid_keys.join('\', \'')
+        complete_message << '\')'
+      end
+
+      super(complete_message)
+    end
+  end
+
+  # The spec is missing a key that is required.
+  class MissingSpecKey < WraptureError
+  end
+
+  # Missing a namespace in the class spec
+  class NoNamespace < WraptureError
+  end
+
+  # The spec cannot be defined due to missing information.
+  class UndefinableSpec < WraptureError
+  end
+
+  # The spec version is not supported by this version of Wrapture.
+  class UnsupportedSpecVersion < WraptureError
+  end
+end