autoc 1.4 → 2.0.0

data/lib/autoc/record.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+
+require 'autoc/std'
+require 'autoc/composite'
+
+
+module AutoC
+
+
+  using STD::Coercions
+
+
+  # C struct wrapper with managed fields
+  class Record < Composite
+
+    attr_reader :fields
+
+    def default_constructible? = fields.values.all? { |t| t.default_constructible? }
+    def custom_constructible? = fields.values.all? { |t| t.copyable? }
+    def destructible? = fields.values.any? { |t| t.destructible? }
+    def comparable? = fields.values.all? { |t| t.comparable? }
+    def copyable? = fields.values.all? { |t| t.copyable? }
+    def hashable? = fields.values.all? { |t| t.hashable? }
+    def orderable? = false
+  
+    def initialize(type, fields, visibility: :public, profile: :blackbox, **kws)
+      super(type, visibility:, **kws)
+      setup_profile(profile)
+      setup_fields(fields)
+    end
+
+    def render_interface(stream)
+      if public?
+        stream << %{
+          /**
+            #{defgroup}
+
+            @brief Value type wrapper of the C struct
+
+            @since 2.0
+          */
+        }
+        if @opaque
+          stream << %{
+            /**
+              #{ingroup}
+
+              @brief Opaque struct holding state of the record
+
+              @since 2.0
+            */
+          }
+        else
+          stream << %{
+            /**
+              #{ingroup}
+
+              @brief Open struct holding state of the record
+
+              The struct's fields are directly acessible.
+              However, care must be taken when modifying the struct's contents directly
+              as it may break the contract(s) of certain (namely, hash- and tree-based) containers.
+
+              For the safety reasons these fields should be generally treated read-only.
+
+              @since 2.0
+            */
+          }
+        end
+      else
+        stream << PRIVATE
+      end
+      stream << 'typedef struct {'
+        fields.each { |name, type| stream << field_declaration(type, name) }
+      stream << "} #{signature};"
+    end
+
+    def type_tag = "#{signature}<#{fields.values.join(',')}>"
+
+  private
+
+    # @private
+    def setup_fields(fields)
+      @fields = fields.transform_values { |type| type.to_type }
+      self.fields.each_value { |type| dependencies << type }
+    end
+
+    # @private
+    def setup_profile(profile)
+      case profile
+      when :blackbox
+        #@inline_methods = false
+        @omit_accessors = false
+        @opaque = true
+      when :glassbox
+        #@inline_methods = true
+        @omit_accessors = true
+        @opaque = false
+      else raise "unsupported profile #{profile}"
+      end
+    end
+
+    # @private
+    def field_variable(opt)
+      if opt.is_a?(::Hash)
+        obj, name = opt.first
+        "#{obj}->#{name}"
+      else
+        opt
+      end
+    end
+
+    # @private
+    def field_declaration(type, name)
+      s = "#{type} #{field_variable(name)};"
+      s += @opaque ? '/**< @private */' : "/**< @brief Field of type #{type} */"
+      s
+    end
+
+    def configure
+      super
+      ### set
+        params = []
+        docs = []
+        args = { target: lvalue }
+        fields.each do |name, type|
+          formal = "#{name}".to_sym
+          value = type.const_rvalue
+          params << [name, Parameter.new(value, formal)]
+          args[formal] = value
+          docs << "@param[in] #{formal} `#{name}` field initializer of type @ref #{type}"
+        end
+        method(:void, :create_set, args, instance: :custom_create).configure do
+          _code = 'assert(target);'
+          params.each do |field, parameter|
+            _code += parameter.value.type.copy.("target->#{field}", parameter) + ';'
+          end
+          code _code
+          header %{
+            @brief Initialize record
+
+            @param[in] target record to create
+
+            This function initializes new record's fields with copies of respective arguments.
+
+            Previous contents of `*target` is overwritten.
+
+            @since 2.0
+          }
+        end
+      ### default_create
+        _code = 'assert(target);'
+        fields.each { |name, type| _code += type.default_create.("target->#{name}") + ';' }
+        default_create.configure { code _code }
+      ### destroy
+        _code = 'assert(target);'
+        fields.each { |name, type| _code += type.destroy.("target->#{name}") + ';' if type.destructible? }
+        destroy.configure { code _code }
+      ### copy
+        _code = 'assert(target); assert(source);'
+        fields.each { |name, type| _code += type.copy.("target->#{name}", "source->#{name}") + ';' }
+        copy.configure { code _code }
+      ### equal
+        _code = 'assert(left); assert(right);'
+        _code += 'return ' + fields.collect { |name, type| type.equal.("left->#{name}", "right->#{name}") }.join(' && ') + ';'
+        equal.configure { code _code }
+      ### hash_code
+        _code = %{
+          #{hasher.to_s} hash;
+          size_t result;
+          assert(target);
+          #{hasher.create(:hash)};
+        }
+        fields.each { |name, type| _code += hasher.update(:hash, type.hash_code.("target->#{name}")) + ';' if type.hashable? }
+        _code += %{
+          result = #{hasher.result(:hash)};
+          #{hasher.destroy(hash)};
+          return result;
+        }
+        hash_code.configure { code _code }
+      ###
+      unless @omit_accessors
+        fields.each do |name, type|
+          method(type.const_lvalue, "view_#{name}",  { target: const_lvalue }, inline: true ).configure do
+            code %{
+              assert(target);
+              return &target->#{name};
+            }
+          header %{
+            @brief Get a view of the field #{name}
+
+            @param[in] target record to query
+            @return a view of the value of type #{type} contained in field #{name}
+
+            This function is used to get a constant reference (in form of the C pointer) to the value in field #{name} contained in `target`.
+
+            @since 2.0
+          }
+          end
+          if type.copyable?
+            method(type, "get_#{name}",  { target: const_rvalue } ).configure do
+              code %{
+                #{type} result;
+                assert(target);
+                #{type.copy.(:result, "target->#{name}")};
+                return result;
+              }
+            header %{
+              @brief Get a copy of the value of field #{name}
+
+              @param[in] target record to query
+              @return a copy of the value of type #{type} contained in field #{name}
+
+              This function is used to get a copy the value in field #{name} contained in `target`.
+
+              @since 2.0
+            }
+            end
+            method(:void, "set_#{name}",  { target: rvalue, name.to_sym => type.const_rvalue } ).configure do
+              code %{
+                assert(target);
+                #{type.destroy.("target->#{name}") if type.destructible?};
+                #{type.copy.("target->#{name}", name)};
+              }
+            header %{
+              @brief Set value of field #{name}
+
+              @param[in] target record to modify
+              @param[in] #{name} value to initalize field #{name} with
+
+              This function sets the field #{name} to contain a copy of specified value.
+
+              Previous field's contents is destroyed the respective destructor.
+
+              @since 2.0
+            }
+            end
+          end
+        end
+      end
+  end
+
+  end # Record
+
+
+end

data/lib/autoc/scaffold/docs.rb

@@ -0,0 +1,117 @@
+require 'autoc'
+require 'autoc/module'
+
+main = AutoC::Code.new interface: %{
+  /**
+    @mainpage AutoC-generated interface reference version #{AutoC::VERSION}
+
+    @section intro Introduction
+
+    The AutoC provides a set of source code generators for widely-known containers such as vector, list, set, map etc.
+    The result is similar to that of the C++ STL template classes which generate the specialized versions of
+    the generic containers but in this case in ***pure C language***.
+
+    @section start Kick start
+
+    Suppose one needs to have a pure C implementation of the set of integer values (`std::unordered_set<int>` in C++ terms).
+    Such code may be obtained with AutoC by executing the following instructions.
+
+    1. Install the AutoC gem
+    ```shell
+    > gem install autoc
+    ```
+    2. Create the type implementation generator in file `test.rb`
+    ```ruby
+    require 'autoc/hash_set'
+    AutoC::Module.render(:test) do |m|
+      m << AutoC::HashSet.new(:IntSet, :int)
+    end
+    ```
+    3. Generate the type implementation
+    ```shell
+    > ruby test.rb
+    ```
+    4. Extract the code-specific auto-generated interface documentation
+    ```shell
+    > doxygen .
+    ```
+    5. Create a test code in file `test.c`
+    ```c
+    #include <stdio.h>
+    #include "test_auto.h"
+    int main(int argc, char** argv) {
+      IntSet set;
+      IntSetCreate(&set);
+      IntSetPut(&set, 1);
+      IntSetPut(&set, 0);
+      IntSetPut(&set, 1);
+      printf("size = %d\\n", IntSetSize(&set));
+      for(IntSetRange r = IntSetRangeNew(&set); !IntSetRangeEmpty(&r); IntSetRangePopFront(&r)) {
+        printf("%d\\n", IntSetRangeTakeFront(&r));
+      }
+      IntSetDestroy(&set);
+    }
+    ```
+    6. Compile the test executable
+    ```shell
+    > cc -g -o test test.c test_auto.c
+    ```
+    7. Perform a test run with Valgrind
+    ```shell
+    > valgrind ./test
+    ```
+  */
+  }
+
+require_relative 'generic_value'
+
+# @private
+class DocsValue < GenericValue
+  attr_reader :description
+  def initialize(type, desc)
+    super(type)
+    @description = desc
+  end
+end
+
+A = DocsValue.new(:A, 'Generic value type')
+B = DocsValue.new(:B, 'Generic value type')
+T = DocsValue.new(:T, 'Generic value type')
+K = DocsValue.new(:K, 'Generic hashable value type')
+
+# @private
+class Docs < AutoC::Module
+  def initialize(*args, **kws)
+    super
+    class << header
+      def file_name = 'autoc.h'
+    end
+  end
+  def render
+    distribute_entities
+    header.render
+  end
+end
+
+require 'autoc/cstring'
+
+require 'autoc/list'
+require 'autoc/vector'
+require 'autoc/hash_set'
+require 'autoc/hash_map'
+
+require 'autoc/box'
+require 'autoc/record'
+
+m = Docs.new(:autoc)
+
+m << main
+m << AutoC::CString.new
+m << AutoC::Vector.new(:Vector, T)
+m << AutoC::List.new(:List, T)
+m << AutoC::HashSet.new(:HashSet, T)
+m << AutoC::HashMap.new(:HashMap, T, K)
+m << AutoC::Box.new(:Box, { a: A, b: B })
+m << AutoC::Record.new(:Record, { a: A, b: B })
+
+m.render

data/lib/autoc/scaffold/generic_value.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+
+require 'autoc/std'
+require 'autoc/composite'
+
+
+# Full-fledged value type equipped with dynamic memory management
+# useful for testing & documentation purposes
+class GenericValue < AutoC::Composite
+
+  using AutoC::STD::Coercions
+
+  def render_interface(stream)
+    super
+    stream << %{
+      /**
+        @brief #{description}
+      */
+      typedef struct {
+        int* value; /**< @private */
+      } #{signature};
+    }
+  end
+
+  def rvalue = @rv ||= AutoC::Value.new(self, reference: true)
+  
+  def lvalue = @lv ||= AutoC::Value.new(self, reference: true)
+  
+  def const_rvalue = @crv ||= AutoC::Value.new(self, constant: true)
+  
+  def const_lvalue = @clv ||= AutoC::Value.new(self, constant: true, reference: true)
+
+private
+  
+  def configure
+    super
+    method(:void, :set, { target: lvalue, value: :int.const_rvalue }, instance: :custom_create).configure do
+      code %{
+        #{default_create.(target)};
+        *target->value = value;
+      }
+    end
+    method(:int, :get, { target: const_rvalue }).configure do
+      code %{
+        return *target.value;
+      }
+    end
+    default_create.configure do
+      code %{
+        assert(target);
+        target->value = #{memory.allocate('int')};
+        *target->value = 0;
+      }
+    end
+    destroy.configure do
+        code %{
+        assert(target);
+        #{memory.free('target->value')};
+      }
+    end
+    copy.configure do
+      code %{
+        assert(target);
+        #{default_create}(target);
+        *target->value = *source.value;
+      }
+    end
+    equal.configure do
+      code %{
+        return *left.value == *right.value;
+      }
+    end
+    compare.configure do
+      code %{
+        return *left.value < *right.value ? -1 : (*left.value > *right.value ? +1 : 0);
+      }
+    end
+    hash_code.configure do
+      code %{
+        return *target.value;
+      }
+    end
+  end
+
+end

data/lib/autoc/scaffold/project.rb

@@ -0,0 +1,75 @@
+###
+def project_c(project)
+<<END
+#include "_#{project}_auto.h"
+
+#include <stdio.h>
+
+int main(int argc, char **argv) {
+  CString msg;
+  CStringCreateFormat(&msg, "Hello %s!\\n", "#{project}");
+  printf(msg);
+  CStringDestroy(&msg);
+  return 0;
+}
+END
+end
+
+
+###
+def cmakelists_txt(project)
+<<END
+project(#{project})
+
+cmake_minimum_required(VERSION 3.15)
+
+set(AUTOC_MODULE_NAME _${PROJECT_NAME})
+set(AUTOC_MODULE_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_NAME}.rb)
+
+list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR}/cmake)
+
+include(AutoC)
+
+add_autoc_module(
+  ${AUTOC_MODULE_NAME}
+  DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+  MAIN_DEPENDENCY ${AUTOC_MODULE_SOURCE}
+  COMMAND ${Ruby_EXECUTABLE} ${AUTOC_MODULE_SOURCE}
+)
+
+add_executable(${PROJECT_NAME} ${PROJECT_NAME}.c)
+target_link_libraries(${PROJECT_NAME} ${AUTOC_MODULE_NAME})
+END
+end
+
+
+###
+def project_rb(project)
+<<END
+require 'autoc/module'
+require 'autoc/cstring'
+
+m = AutoC::Module.render(:_#{project}) do |m|
+  m << AutoC::CString.new
+end
+
+require 'autoc/cmake'
+
+AutoC::CMake.render(m)
+END
+end
+
+
+if ARGV.size < 1
+  $stderr << "usage: ruby -r autoc/scaffold -e project project_name\n"
+  exit 1
+end
+
+project = ARGV[0]
+
+require 'fileutils'
+FileUtils.copy_entry(File.dirname(__FILE__)+'/../../../cmake', 'cmake')
+
+File.write('CMakeLists.txt', cmakelists_txt(project))
+File.write("#{project}.rb", project_rb(project))
+File.write("#{project}.c", project_c(project))

data/lib/autoc/scaffold/test_cstring.rb

@@ -0,0 +1,113 @@
+require 'autoc/cstring'
+
+CString = type_test(AutoC::CString,  :CString) do
+
+  ###
+
+  setup %{
+    #{self} s;
+  }
+
+  cleanup %{
+    #{destroy.(:s)};
+  }
+
+  test :create_empty, %{
+    #{custom_create.(:s, %{""})};
+    TEST_EQUAL( #{size.(:s)}, 0 );
+    TEST_TRUE( #{empty}(s) );
+  }
+
+  test :create_non_empty, %{
+    #{custom_create.(:s, %{"hello"})};
+    TEST_EQUAL( #{size.(:s)}, 5 );
+  }
+
+  test :format_empty, %{
+    TEST_TRUE( #{create_format.(:s, %{""})} );
+    TEST_TRUE( #{empty}(s) );
+  }
+
+  test :format_empty_params, %{
+    TEST_TRUE( #{create_format.(:s, %{"hello"})} );
+    TEST_TRUE( #{equal}(s, "hello") );
+    TEST_FALSE( #{empty}(s) );
+  }
+  
+  test :format_int, %{
+    TEST_TRUE( #{create_format.(:s, %{"hello%d"}, -3)} );
+    TEST_TRUE( #{equal}("hello-3", s) );
+  }
+
+  test :equal_cstr, %{
+    #{custom_create.(:s, %{"hello"})};
+    TEST_TRUE( #{equal.(:s, %{"hello"})} );
+  }
+
+  test :compare_cstr, %{
+    #{custom_create.(:s, %{"hello"})};
+    TEST_FALSE( #{equal.(%{"hello1"}, :s)} );
+    TEST_FALSE( #{equal.(:s, %{"hello1"})} );
+    TEST_TRUE( #{compare.(:s, %{"hello1"})} < 0 );
+    TEST_TRUE( #{compare.(%{"hello1"}, :s)} > 0 );
+  }
+
+  ###
+
+  setup %{
+    #{self} s1, s2;
+  }
+
+  cleanup %{
+    #{destroy.(:s1)};
+    #{destroy.(:s2)};
+  }
+
+  test :compare_equal, %{
+    #{custom_create.(:s1, %{"hello"})};
+    #{custom_create.(:s2, %{"hello"})};
+    TEST_TRUE( #{equal.(:s1, :s2)} );
+    TEST_EQUAL( #{compare.(:s1, :s2)}, 0 );
+    TEST_EQUAL( #{hash_code.(:s1)}, #{hash_code.(:s2)} );
+  }
+
+  test :compare_non_equal, %{
+    #{custom_create.(:s1, %{"hello1"})};
+    #{custom_create.(:s2, %{"hello2"})};
+    TEST_FALSE( #{equal.(:s1, :s2)} );
+    TEST_FALSE( #{equal.(:s2, :s1)} );
+    TEST_TRUE( #{compare.(:s1, :s2)} < 0 );
+    TEST_TRUE( #{compare.(:s2, :s1)} > 0 );
+  }
+
+  ###
+
+  setup %{
+    #{self} s;
+    #{custom_create.(:s, %{"hello"})};
+  }
+
+  cleanup %{
+    #{destroy.(:s)};
+  }
+
+  test :char_access, %{
+    TEST_EQUAL( #{get.(:s, 0)}, 'h' );
+    TEST_EQUAL( *#{view}(s, 4), 'o' );
+  }
+
+  test :range_access, %{
+    #{range} r = #{range.new.(:s)};
+    TEST_EQUAL( #{size}(s), 5 );
+    TEST_EQUAL( #{range.size}(&r), #{size}(s) );
+    TEST_EQUAL( #{range.take_front}(&r), 'h' );
+    TEST_EQUAL( *#{range.view_back}(&r), 'o' );
+    #{range.pop_front}(&r);
+    TEST_EQUAL( *#{range.view_front}(&r), 'e' );
+    TEST_EQUAL( #{range.size}(&r), #{size}(s)-1 );
+    #{range.pop_back}(&r);
+    TEST_EQUAL( #{range.take_back}(&r), 'l' );
+    TEST_EQUAL( #{range.size}(&r), #{size}(s)-2 );
+  }
+  
+end

data/lib/autoc/scaffold/test_cstring_hash_set.rb

@@ -0,0 +1,35 @@
+require 'autoc/hash_set'
+
+require_relative 'test_cstring'
+
+type_test(AutoC::HashSet, :CStringHashSet, CString) do
+
+  ###
+
+  setup %{
+    #{self} t;
+  }
+
+  cleanup %{
+    #{destroy}(&t);
+  }
+
+  test :create_default, %{
+    #{default_create}(&t);
+    TEST_EQUAL( #{size}(&t), 0 );
+  }
+
+  test :create_custom, %{
+    #{create_capacity}(&t, 1024);
+    TEST_EQUAL( #{size}(&t), 0 );
+  }
+
+  test :put, %{
+    #{default_create}(&t);
+    #{put}(&t, "kitty");
+    #{put}(&t, "hello");
+    #{put}(&t, "kitty");
+    TEST_EQUAL( #{size}(&t), 2 );
+  }
+
+end

data/lib/autoc/scaffold/test_int_box.rb

@@ -0,0 +1,22 @@
+require 'autoc/box'
+require_relative 'test_int_vector'
+
+type_test(AutoC::Box, :IntBox, { number: :int, numbers: IntVector }) do
+
+  ###
+
+  setup %{
+    #{self} t;
+    #{default_create.(:t)};
+  }
+
+  cleanup %{
+    #{destroy.(:t)};
+  }
+
+  test :create_empty, %{
+    #{purge.(:t)};
+    TEST_FALSE( #{tag.(:t)} );
+  }
+
+end