autoc 1.4 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: cc85e9cdc08a443fcc50ad0c86c681b205b47057
-  data.tar.gz: d0a444d8b827b87478e1d26dbb70a2b3c27c09be
+SHA256:
+  metadata.gz: a598879205b51d5bf574b70b370ef805efe3681e0ea4ad8b6347e45296cc304b
+  data.tar.gz: d5c3290746c096a666627ff544903afe2b1f31e61b7706cf5a5e531c410191ea
 SHA512:
-  metadata.gz: f39cbdc42cb01f0fda4878fb755c9db3d9276976dfaa4822fa27b5bff02febb3e07a38d27a398beac07341de1de4f851e9bb42157fef8542fe8586bb1bb94ee1
-  data.tar.gz: 7934c79a433127ed3396ee6170bbfd30a3a47579180fd0eb9d52a93f6d4a125b0e59b7d4d5552c68ec4d685c83c3b27fffa4a4e34db50ba394a5b190797d0cb4
+  metadata.gz: cb81338f80898d88975a0bc204b5245c6fe4e0deb931c91ff007bff5dca026f4f99fe5702d56033fa0387786cb20b03445dbb662c07ebcf7f8ba81f993848520
+  data.tar.gz: da094ff14cf393a2c7178fb45083d18b3513d686e29a693895dd4cea51bbcf406776fe26de0d550605102f7f5976170a3715fedc1d9520e1f4c1944c034b56d1

data/CHANGES.md

@@ -0,0 +1,3 @@
+# 2.0.0
+
+A complete package overhaul.

data/README.md

@@ -0,0 +1,149 @@
+# Reinvention of the C wheel, automatized
+
+The project AutoC ships a collection of [Ruby](https://www.ruby-lang.org) classes related to automagic
+C source code generation.
+
+Specifically, it provides a means of generating strongly-typed general purpose C data containers
+(vectors, lists, maps etc.) similar to those provided by
+the C++'s [STL template containers](https://en.cppreference.com/w/cpp/container)
+but implemented in ***pure ANSI C language***.
+
+Unlike similar attempts to introduce type-generic data containers to the C language which
+are typically the macro libraries, the AutoC is an ***explicit source code generator***
+with 100% of provided functionality is implemented as (inline or extern) C functions
+making the code explicit, browseable and debuggable.
+
+## Qickstart
+
+Install the `autoc` Ruby package from [RubyGems](https://rubygems.org)
+
+```shell
+gem install autoc
+```
+
+### Extract sample documentation
+
+Generate a documentation header `auto.h` with reference of what can be provided by the AutoC
+
+```shell
+ruby -r autoc/scaffold -e docs
+```
+
+Extract the documentation with [Doxygen](https://www.doxygen.nl)
+
+```shell
+doxygen .
+```
+
+Explore the rendered HTML documentation starting at `html/index.html`
+
+### Build & run sample project
+
+Create auto code descriptor in Ruby `sample.rb`
+
+```ruby
+require 'autoc/module'
+require 'autoc/hash_set'
+AutoC::Module.render(:sample) do |m|
+  m << AutoC::HashSet.new(:IntSet, :int)
+end
+```
+
+Generate C code into `sample_auto.[ch]`
+
+```shell
+ruby sample.rb
+```
+
+Create sample C code `sample.c`
+
+```c
+#include <stdio.h>
+#include "sample_auto.h"
+int main(int argc, char** argv) {
+  IntSet set;
+  IntSetCreate(&set);
+  IntSetPut(&set, 1);
+  IntSetPut(&set, 0);
+  IntSetPut(&set, 1);
+  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);
+}
+```
+
+Build sample program
+
+```shell
+cc -g -o sample sample.c sample_auto.c
+```
+
+Test sample with [Valgrind](https://valgrind.org)
+
+```shell
+valgrind sample
+```
+
+### Build & run test suite
+
+Generate C test suite into `tests_auto.[ch]`
+
+```shell
+ruby -r autoc/scaffold -e tests
+```
+
+Build test suite
+
+```shell
+cc -g -o tests tests_auto.c
+```
+
+Witness the test suite run time correctness
+
+```shell
+valgrind tests
+```
+
+### Create CMake project from template
+
+Create CMake-powered skeleton project named `runme` in the current directory
+
+```shell
+ruby -r autoc/scaffold -e project runme
+```
+
+Configure the generated project
+
+```shell
+cmake .
+```
+
+Build the generated project
+
+```shell
+cmake --build .
+```
+
+## Licensing & availability
+
+This code is distributed under terms of the 2-clause BSD {file:LICENSE}.
+
+The project's home page is [GitHub](https://github.com/okhlybov/autoc).
+
+The released ruby gems are published in [RubyGems](https://rubygems.org/gems/autoc).
+
+The condensed description of the changes is in the {file:CHANGES.md}.
+
+
+## Assorted related stuff
+
+- [STC](https://github.com/tylov/STC)
+
+---
+
+_Cheers && happy coding!_
+
+Oleg A. Khlybov <fougas@mail.ru>

data/cmake/AutoC.cmake

@@ -0,0 +1,39 @@
+cmake_minimum_required(VERSION 3.15)
+
+find_package(Ruby 3.2)
+
+if(NOT Ruby_FOUND)
+  message(STATUS "Attempting to locate default Ruby executable")
+  find_program(Ruby ruby REQUIRED)
+endif()
+
+function(add_autoc_module module)
+  set(args DIRECTORY MAIN_DEPENDENCY)
+  set(listArgs COMMAND DEPENDS)
+  cmake_parse_arguments(key "${flags}" "${args}" "${listArgs}" ${ARGN})
+  if(NOT key_DIRECTORY)
+    set(key_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
+  endif()
+  if(NOT key_MAIN_DEPENDENCY)
+    set(key_MAIN_DEPENDENCY ${key_DIRECTORY}/${module}.rb)
+  endif()
+  set(module_state ${key_DIRECTORY}/${module}.state)
+  set(module_cmake ${key_DIRECTORY}/${module}.cmake)
+  set(module_target ${module}-generate)
+  if(NOT EXISTS ${module_state} OR NOT EXISTS ${module_cmake})
+    message(CHECK_START "Bootstrapping AutoC module " ${module})
+    execute_process(WORKING_DIRECTORY ${key_DIRECTORY} COMMAND ${key_COMMAND} VERBATIM)
+  endif()
+  include(${module_cmake})
+  add_custom_command(
+    OUTPUT ${module_state}
+    BYPRODUCTS ${module_cmake}
+    MAIN_DEPENDENCY ${key_MAIN_DEPENDENCY}
+    DEPENDS ${key_DEPENDS}
+    WORKING_DIRECTORY ${key_DIRECTORY}
+    COMMAND ${key_COMMAND}
+    VERBATIM
+  )
+  add_custom_target(${module_target} DEPENDS ${module_state})
+  add_dependencies(${module} ${module_target})
+endfunction()

data/lib/autoc/allocators.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+
+require 'singleton'
+require 'autoc/std'
+require 'autoc/type'
+require 'autoc/module'
+
+
+module AutoC
+
+
+  # Standard C malloc()-based dynamic memory handler
+  class Allocator
+
+    include STD
+
+    include Singleton
+
+    include Entity
+
+    def initialize = dependencies << STDLIB_H
+
+    def allocate(type, count = 1, zero: false, **kws)
+      zero ? "(#{type}*)calloc(#{count}, sizeof(#{type}))" : "(#{type}*)malloc((#{count})*sizeof(#{type}))"
+    end
+
+    def free(pointer) = "free(#{pointer})"
+
+  end # Allocator
+
+
+  # Boehm-Demers-Weiser garbage-collecting memory handler https://www.hboehm.info/gc/
+  class BDWAllocator
+
+    include Singleton
+
+    include Entity
+
+    def initialize = dependencies << SystemHeader.new('gc.h')
+
+    def allocate(type, count = 1, atomic: false, **kws)
+      atomic ? "(#{type}*)GC_malloc_atomic((#{count})*sizeof(#{type}))" : "(#{type}*)GC_malloc((#{count})*sizeof(#{type}))"
+    end
+
+    def free(pointer) = nil
+
+  end # Allocator
+
+
+end

data/lib/autoc/association.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+
+require 'autoc/std'
+require 'autoc/collection'
+
+
+module AutoC
+
+
+  using STD::Coercions
+    
+
+  # @abstract
+  # Generator for C types for direct access using index of specific type (hash/tree maps, string, vector etc.)
+  class Association < Collection
+
+    attr_reader :index
+
+    def initialize(type, element, index, **kws)
+      super(type, element, **kws)
+      dependencies << (@index = index.to_type)
+    end
+
+    # For associative container to be copyable both hashable element and index types are required
+    def copyable? = super && index.copyable?
+
+    # For associative container to be comparable both hashable element and index types are required
+    def comparable? = super && index.comparable?
+
+    # For associative container to be orderable both hashable element and index types are required
+    def orderable? = super && index.orderable?
+
+    # The associative destructible element and index types mandates creation of the container's destructor
+    def destructible? = super || index.destructible?
+
+    # For associative container to be hashable both hashable element and index types are required
+    def hashable? = super && index.hashable?
+
+    def type_tag = "#{signature}<#{element},#{index}>"
+  
+  private
+
+    def configure
+      super
+      method(:int, :check, { target: const_rvalue, index: index.const_rvalue } ).configure do
+        header %{
+          @brief Validate specified index
+
+          @param[in] target container to query
+          @param[in] index index to verify
+          @return non-zero value if there is an element associated with specified index and zero value otherwise
+
+          This function performs the index validity check.
+          For the contiguous containers (vector, string etc.) the yields non-zero value if the index passes the boundaries check.
+          For the mappings (hash/tree maps) this yields non-zero value if there exists a index->element association.
+
+          In any case, this function should be used for the index validation prior getting direct access to contained elements
+          as the container functions do not normally do it themselves for performance reasons.
+
+          @since 2.0
+        }
+      end
+      method(element.const_lvalue, :view, { target: const_rvalue, index: index.const_rvalue } ).configure do
+        header %{
+          @brief Get a view of the element
+
+          @param[in] target container
+          @param[in] index lookup index
+          @return a view of contained element
+
+          This function returns a constant view of the contained element associated with specified index in the form constant C pointer to the storage.
+          It is generally not wise to modify the value pointed to (especially in the case of mapping).
+
+          It is the caller's responsibility to check for the index validity prior calling this function (see @ref #{check}).
+
+          @since 2.0
+        }
+      end
+      method(element, :get, { target: const_rvalue, index: index.const_rvalue }, inline: true, constraint:-> { element.copyable? } ).configure do
+        dependencies << check << view
+        header %{
+          @brief Get specific element
+
+          @param[in] target container
+          @param[in] index lookup index
+          @return a copy of contained element
+
+          This function returns an independent copy of the contained element associated with specified index.
+
+          It is the caller's responsibility to check for the index validity prior calling this function (see @ref #{check}).
+
+          @since 2.0
+        }
+        inline_code %{
+          #{result} r;
+          #{element.const_lvalue} e;
+          assert(target);
+          assert(#{check.(target, index)});
+          e = #{view.(target, index)};
+          #{element.copy.(:r, '*e')};
+          return r;
+        }
+      end
+      method(:void, :set, { target: rvalue, index: index.const_rvalue, value: element.const_rvalue }, constraint:-> { index.copyable? && element.copyable? } ).configure do
+        header %{
+          @brief Set specific element
+
+          @param[in] target container
+          @param[in] index lookup index
+          @param[in] value source value
+
+          This function unconditionally sets the element at specified index to a copy of the source value.
+          A previous element (if any) is destroyed with specific destructor.
+
+          It is the caller's responsibility to check for the index validity prior calling this function (see @ref #{check}).
+
+          @since 2.0
+        }
+      end
+    end
+
+  end # Association
+
+
+end

data/lib/autoc/box.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+
+require 'autoc/std'
+require 'autoc/composite'
+
+
+module AutoC
+
+
+  using STD::Coercions
+
+
+  # C union wrapper with managed fields
+  class Box < Composite
+
+    attr_reader :variants
+
+    attr_reader :tag_
+
+    def default_constructible? = true
+    def custom_constructible? = false
+    def destructible? = variants.values.any? { |t| t.destructible? }
+    def comparable? = variants.values.all? { |t| t.comparable? }
+    def orderable? = variants.values.all? { |t| t.orderable? }
+    def copyable? = variants.values.all? { |t| t.copyable? }
+    def hashable? = variants.values.all? { |t| t.hashable? }
+
+    def initialize(type, variants, visibility: :public)
+      super(type, visibility:)
+      setup_variants(variants)
+      @tag_ = "#{signature}_";
+      @default = 'abort();'
+    end
+
+    def render_interface(stream)
+      if public?
+        stream << %{
+          /**
+            #{defgroup}
+            @brief Value type wrapper of the C union
+          */
+        }
+        stream << %{
+          /**
+            #{ingroup}
+
+            @brief Box tag set
+
+            Use @ref #{identifier(:tag)} to query current box contents. Empty box is always tagged as 0.
+
+            @since 2.0
+          */
+        }
+      else
+        stream << PRIVATE
+      end
+      stream << 'typedef enum {'
+      i = 0; stream << (variants.collect { |name, type| "#{identifier(name)} = #{i+=1}" }).join(',')
+      stream << "} #{tag_};"
+      if public?
+        stream << %{
+          /**
+            #{ingroup}
+
+            @brief Opaque struct holding state of the box
+
+            @since 2.0
+          */
+        }
+      else
+        stream << PRIVATE
+      end
+      stream << 'typedef struct {union {'
+        variants.each { |name, type| stream << field_declaration(type, name) }
+      stream << "} variant; /**< @private */ #{tag_} tag; /**< @private */} #{signature};"
+    end
+
+    def type_tag = "#{signature}<#{variants.values.join(',')}>"
+
+  private
+
+    # @private
+    def setup_variants(variants)
+      @variants = variants.transform_values { |type| type.to_type }
+      self.variants.each_value { |type| dependencies << type }
+    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 += '/**< @private */' if @opaque
+      s
+    end
+
+    def configure
+      super
+      default_create.configure do
+        inline_code %{
+          assert(target);
+          target->tag = (#{tag_})0;
+        }
+      end
+      method(tag_, :tag, { target: const_rvalue }).configure do
+        inline_code %{
+          assert(target);
+          return target->tag;
+        }
+        header %{
+          @brief Get type of contained element
+
+          @param[in] target box to query
+          @return tag of currently contained element
+
+          This function returns a tag of currently contained element (@ref #{tag_}) or zero value if the box is empty (i.e. contains nothing).
+
+          @since 2.0
+        }
+      end
+      method(:void, :purge, { target: rvalue }).configure do
+        code %{
+          assert(target);
+          #{destroy.(target) if destructible?};
+          #{default_create.(target)};
+        }
+        header %{
+          @brief Reset box
+
+          @param[in] target box to purge
+
+          This function resets the box by destroying containing element (if any).
+          The box is left empty.
+
+          @since 2.0
+        }
+      end
+      ### destroy
+        _code = %$
+          assert(target);
+          if(target->tag) switch(target->tag) {
+        $
+        variants.each do |name, type|
+          _code += "case #{identifier(name)}:"
+          _code += type.destroy.("target->variant.#{name}") if type.destructible?
+          _code += ';break;'
+        end
+        _code += %{
+          default: #{@default}
+        }
+        _code += '}'
+        destroy.configure { code _code }
+      ### copy
+        _code = %$
+          assert(target);
+          assert(source);
+          if(source->tag) switch(source->tag) {
+        $
+        variants.each do |name, type|
+          _code += "case #{identifier(name)}:"
+          _code += type.copy.("target->variant.#{name}", "source->variant.#{name}")
+          _code += ';break;'
+        end
+        _code += %{
+          default: #{@default}
+        }
+        _code += '} target->tag = source->tag;'
+        copy.configure { code _code }
+      ### equal
+        _code = %$
+          assert(left);
+          assert(right);
+          if(left->tag != right->tag) return 0;
+          if(!left->tag) return 1;
+          switch(left->tag) {
+        $
+        variants.each do |name, type|
+          _code += "case #{identifier(name)}:"
+          _code += 'return '
+          _code += type.equal.("left->variant.#{name}", "right->variant.#{name}")
+          _code += ';'
+        end
+        _code += %{
+          default: #{@default}
+        }
+        _code += '}'
+        equal.configure { code _code }
+      ### compare
+        _code = %$
+          assert(left);
+          assert(right);
+          assert(left->tag == right->tag);
+          if(!left->tag) return 0;
+          switch(left->tag) {
+        $
+        variants.each do |name, type|
+          _code += "case #{identifier(name)}: return "
+          _code += type.compare.("left->variant.#{name}", "right->variant.#{name}")
+          _code += ';'
+        end
+        _code += %{
+          default: #{@default}
+        }
+        _code += '}'
+        compare.configure { code _code }
+      ### hash_code
+        _code = %$
+          assert(target);
+          if(!target->tag) return AUTOC_HASHER_SEED;
+          switch(target->tag) {
+        $
+        variants.each do |name, type|
+          _code += "case #{identifier(name)}: return "
+          _code += type.hash_code.("target->variant.#{name}")
+          _code += ';'
+        end
+        _code += %{
+          default: #{@default}
+        }
+        _code += '}'
+        hash_code.configure { code _code }
+      ### typed accessors
+      _type = self
+      variants.each do |name, type|
+        method(type.const_lvalue, "view_#{name}", { target: const_rvalue }).configure do
+          code %{
+            assert(target);
+            assert(target->tag == #{identifier(name)});
+            return &target->variant.#{name};
+          }
+          header %{
+            @brief Get a view of contained value of type #{type}
+
+            @param[in] target box to query
+            @return a view of the value of type #{type}
+
+            This function is used to get a constant reference (in form of the C pointer) to value contained in `target`.
+
+            It is the caller's responsibility to check the type of currently contained value.
+            Consider using guard `if(#{identifier(:tag)}(...) == #{identifier(name)}) ...`
+
+            @see @ref #{tag}
+
+            @since 2.0
+          }
+        end
+        if type.copyable?
+          method(type, "get_#{name}", { target: const_rvalue }).configure do
+            code %{
+              #{type} result;
+              assert(target);
+              assert(target->tag == #{identifier(name)});
+              #{type.copy.(:result, "target->variant.#{name}")};
+              return result;
+            }
+            header %{
+              @brief Get a copy of contained value of type #{type}
+  
+              @param[in] target box to query
+              @return a copy of the value of type #{type}
+  
+              This function is used to get a copy of the value contained in `target`.
+  
+              It is the caller's responsibility to check the type of currently contained value.
+              Consider using guard `if(#{identifier(:tag)}(...) == #{identifier(name)}) ...`
+  
+              @see @ref #{tag}
+  
+              @since 2.0
+            }
+          end
+          method(:void, "put_#{name}", { target: rvalue, value: type.const_rvalue }).configure do
+            code %{
+              assert(target);
+              #{destroy.(target) if destructible?};
+              #{type.copy.("target->variant.#{name}", value)};
+              target->tag = #{identifier(name)};
+            }
+            header %{
+              @brief Put value of type #{type} into box
+  
+              @param[in] target box to set
+              @param[in] value value of type #{type} to put
+  
+              This function is used to put a copy of the value into the box.
+              Previously contained value is destroyed with respective destructor.
+  
+              After call to this function the value type may be obtained with @ref #{identifier(:tag)}.
+
+              @see @ref #{tag}
+  
+              @since 2.0
+            }
+          end
+        end
+      end
+    end
+
+  end # Box
+
+
+end