autoc 1.4 → 2.0.0

data/lib/autoc/cmake.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+
+require 'digest'
+require 'autoc/module'
+
+
+module AutoC
+
+
+# CMake package renderer for the AutoC module
+class CMake
+
+  attr_reader :module
+
+  def file_name = "#{self.module.name}.cmake"
+
+  def initialize(m) = @module = m
+
+  def render
+    m = self.module
+    sources = self.module.sources.collect { |s| "${CMAKE_CURRENT_SOURCE_DIR}/#{s.file_name}" } .join(' ')
+    stream = %{
+      set(#{m.name}_HEADER ${CMAKE_CURRENT_SOURCE_DIR}/#{m.header.file_name})
+      set(#{m.name}_SOURCES #{sources})
+      add_library(#{m.name} OBJECT ${#{m.name}_SOURCES})
+      target_include_directories(#{m.name} INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>)
+    }
+    unless Digest::MD5.digest(stream) == (Digest::MD5.digest(File.read(file_name)) rescue nil)
+      File.write(file_name, stream)
+    end
+  end
+  
+  def self.render(m) = self.new(m).render
+
+end # CMake
+
+
+end
+
+
+### On code generation vs. CMake
+
+# https://here-be-braces.com/integrating-a-flexible-code-generator-into-cmake/
+# https://blog.kangz.net/posts/2016/05/26/integrating-a-code-generator-with-cmake/
+
+
+### On code packaging
+
+# https://www.youtube.com/watch?v=sBP17HQAQjk
+# https://www.youtube.com/watch?v=_5weX5mx8hc
+
+# https://alexreinking.com/blog/how-to-use-cmake-without-the-agonizing-pain-part-1.html
+# https://alexreinking.com/blog/how-to-use-cmake-without-the-agonizing-pain-part-1.html

data/lib/autoc/collection.rb

@@ -1,145 +1,118 @@
-require "autoc/code"
-require "autoc/type"
+# frozen_string_literal: true
 
 
-module AutoC
-
-
-=begin
+require 'autoc/std'
+require 'autoc/composite'
 
-== Implemented types
 
-- {AutoC::UserDefinedType} user-defined custom type
-
-- {AutoC::Reference} counted reference type
+module AutoC
 
-- {AutoC::String} string builder type with value semantics
 
-== Implemented collections
+  using STD::Coercions
+    
 
-- {AutoC::Vector} resizable array
+  # @abstract
+  # Generator for C types which contain zero or more elements of a particular type
+  class Collection < Composite
 
-- {AutoC::List} singly linked list
+    attr_reader :element
 
-- {AutoC::Queue} doubly linked list
+    attr_reader :range
 
-- {AutoC::HashSet} hash-based unordered set
+    def self.new(*args, **kws)
+      obj = super
+      obj.references << obj.range # Range has to be referenced after the iterable object gets fully configured
+      obj
+    end
 
-- {AutoC::HashMap} hash-based unordered map
+    def initialize(signature, element, **kws)
+      super(signature, **kws)
+      dependencies << (@element = element.to_type)
+    end
 
-- {AutoC::TreeSet} tree-based sorted set
+    # For container to be copyable a copyable element type is required
+    def copyable? = super && element.copyable?
 
-- {AutoC::TreeMap} tree-based sorted map
+    # For container to be comparable a comparable element type is required
+    def comparable? = super && element.comparable?
 
-== Ruby side operation
+    # For container to be orderable an orderable element type is required
+    def orderable? = super && element.orderable?
 
-.Complete example for generation of a list of integers collection:
-[source,ruby]
-----
-require "autoc"
-AutoC::Module.generate!(:Test) do |c|
-  c << AutoC::List.new(:IntList, :int)
-end
-----
-In the above example a C module Test represented by the C header +test_auto.h+ and the C source +test_auto.c+ is generated.
-The C++ counterpart of the generated collection is +std::forward_list<int>+.
+    # A destructible element type mandates creation of the container's destructor
+    def destructible? = super || element.destructible?
 
-== C interface
+    # For container to be hashable a hashable element type is required
+    def hashable? = super && element.hashable?
+  
+    def type_tag = "#{signature}<#{element}>"
 
-=== Element types: values, references
+  private
 
-Collections may contain both value and reference types, including other collections.
+    def configure
+      super
+      method(:int, :empty, { target: const_rvalue })
+      method(:size_t, :size, { target: const_rvalue })
+      # Separate certain methods creation from documenting due to mutual dependency
+      empty.configure do
+        header %{
+          @brief Check container for emptiness
 
-=== Thread safety
+          @param[in] target container to check
+          @return non-zero value if container is empty (i.e. contains no elements) and zero value otherwise
 
-WARNING: In its current state the implemented collections are *not* thread-safe.
+          @note This function's behavior must be consistent with @ref #{size}.
 
-=== Iteration
+          @since 2.0
+        }
+      end
+      size.configure do
+        header %{
+          @brief Return number of contained elements
 
-At the moment a fairly simple iteration functionality is implemented.
-The iterators are modeled after the C# language.
-All implemented iterators do not require destruction after use.
+          @param[in] target container to query
+          @return number of contained elements
 
-.Basic iterator usage example:
-[source,c]
-----
-MyVector c;
-MyVectorIt it;
-...
-MyVectorItCtor(&it, &c);
-while(MyVectorItMove(&it)) {
-  Element e = MyVectorItGet(&it);
-  ...
-  ElementDtor(e);
-}
-----
+          @note This function's behavior must be consistent with @ref #{empty}.
 
-WARNING: the collection being iterated *must not* be modified in any way otherwise the iterator behavior is undefined.
-=end
-class Collection < Type
+          @since 2.0
+        }
+      end
+      method(:int, :contains, { target: const_rvalue, value: element.const_rvalue }, constraint:-> { element.comparable? }).configure do
+        header %{
+          @brief Look up for specific element in container
 
-  include Redirecting
-  
-  attr_reader :element, :it_ref
-  
-  def hash; super ^ element.hash end
-  
-  def ==(other) super && element == other.element end
-  
-  alias :eql? :==
+          @param[in] target container to query
+          @param[in] value element to look for
+          @return non-zero value if container has (at least one) element equal to the specified value and zero value otherwise
 
-  def entities; super << element end
-  
-  def initialize(type_name, element_type, visibility = :public)
-    super(type_name, visibility)
-    @it_ref = "#{it}*"
-    @element = Type.coerce(element_type)
-    initialize_redirectors
-    element_requirement(element)
-  end
-  
-  # Normally all collections are expected to provide all special functions
-  # If a collection does not provide specific function it should override the respective method
-  
-  # Collection always has default constructor
-  def constructible?; true end
+          This function scans through the container's contents to look for an element which is considered equal to the specified value.
+          The equality testing is performed with the element type's equality criterion.
 
-  # Collection always has constructor
-  def initializable?; true end
+          @since 2.0
+        }
+      end
+      method(element.const_lvalue, :find_first, { target: const_rvalue, value: element.const_rvalue }, constraint:-> { element.comparable? }).configure do
+        header %{
+          @brief Search for specific element
 
-  # Collection always has destructor but the element is required to be destructible on its own
-  # because collection destruction incurs destruction of all contained elements
-  def destructible?; true && element.destructible? end
+          @param[in] target container to search through
+          @param[in] value value to look for
+          @return a view of element equivalent to specified value or NULL value
 
-  # Collection always has copy constructor but the element is required to be copyable on its own
-  # because collection copying incurs copying of all contained elements
-  def copyable?; true && element.copyable? end
+          This function scans through `target` and returns a constant reference (in form of the C pointer)
+          a contained element equivalent to the specified `target` or NULL value is there is no such element.
 
-  # Collection always has equality tester but the element is required to be comparable on its own
-  # because collection comparison incurs comparison of all contained elements
-  def comparable?; true && element.comparable? end
+          This function usually (but not neccessarily) yields first suitable element.
 
-  # So far there are no orderable collections therefore inherit false-returning #orderable? 
+          This function requires the element type to be *comparable* (i.e. to have a well-defined comparison operation).
 
-  # Collection always has hash calculation function but the element is required to be hashable on its own
-  # because collection comparison incurs hash calculation for all contained elements
-  def hashable?
-    # Since using collection as an element of a hash-based container also requires it to be comparable as well 
-    comparable? && element.hashable?
-  end
+          @since 2.0
+        }
+      end
+    end
 
-  def write_intf_decls(stream, declare, define)
-    write_redirectors(stream, declare, define)
-  end
-  
-  private
-  
-  def element_requirement(obj)
-    raise "type #{obj.type} (#{obj}) must be destructible" unless obj.destructible?
-    raise "type #{obj.type} (#{obj}) must be copyable" unless obj.copyable?
-  end
-  
-end # Collection
+  end # Collection
 
 
-end # AutoC
+end

data/lib/autoc/composite.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+
+require 'autoc/std'
+require 'autoc/type'
+require 'autoc/module'
+require 'autoc/hashers'
+require 'autoc/allocators'
+require 'autoc/function'
+
+
+module AutoC
+
+
+  using STD::Coercions
+
+
+  # @abstract
+  class Composite < Type
+
+    PRIVATE = '/** @private */'
+
+    include STD
+
+    include Entity
+
+    attr_reader :visibility
+
+    attr_reader :_master # Internal reference to the containing type if this type is used as implementing type
+
+    def initialize(signature, visibility: :public, decorator: nil, allocator: nil, hasher: nil, _master: nil)
+      super(signature)
+      @methods = {}
+      @hasher = hasher
+      @decorator = decorator
+      @allocator = allocator
+      @visibility = visibility
+      dependencies << DEFINITIONS << ASSERT_H << self.memory << self.hasher
+      @_master = _master
+    end
+
+    def self.new(*args, **kws, &block)
+      obj = super
+      obj.send(:configure)
+      obj
+    end
+
+    def to_value = Value.new(self)
+
+    def rvalue = @rv ||= Value.new(self, reference: true)
+  
+    def lvalue = @lv ||= Value.new(self, reference: true)
+  
+    def const_rvalue = @crv ||= Value.new(self, constant: true, reference: true)
+  
+    def const_lvalue = @clv ||= Value.new(self, constant: true, reference: true)
+
+    # Prefix used to generate type-qualified identifiers
+    # By default it returns the C side type signature but can be overridden
+    # to handle the cases where the signature is not itself a valid C identifier (char*, for example)
+    def prefix = signature
+
+    def inspect = "#{signature} <#{self.class}>"
+
+    # Decorate identifier with type-specific prefix
+    def identifier(id, **kws) = (@decorator.nil? ? Composite.decorator : @decorator).(self, id, **kws)
+
+    def public? = @visibility == :public
+
+    def respond_to_missing?(meth, include_private = false) = @methods.has_key?(meth) ? true : super
+
+    def type_tag = signature
+
+    def defgroup = (public? ? :@public : :@internal).to_s + " @defgroup #{signature} #{type_tag}"
+
+    def ingroup = (public? ? :@public : :@internal).to_s + " @ingroup #{signature}"
+
+    def memory = (@allocator.nil? ? Composite.allocator : @allocator)
+
+    def hasher = (@hasher.nil? ? Composite.hasher : @hasher)
+
+    def self.decorator=(decorator) @decorator = decorator end
+
+    def self.decorator = @decorator
+
+    def self.allocator=(allocator) @allocator = allocator end
+
+    def self.allocator = @allocator
+
+    self.allocator = Allocator.instance # Standard C malloc() & free() memory handler
+
+    def self.hasher=(hasher) @hasher = hasher end
+
+    def self.hasher = @hasher
+
+    self.hasher = Hasher.instance # Default cycle-xor hasher
+
+    # Pluggable CamelCase identifier decorator
+    CAMEL_CASE_DECORATOR = -> (type, symbol, abbreviate: false, **kws) {
+      id = symbol.to_s.sub(/[!?]$/, '') # Strip trailing !?
+      _ = # Check for leading underscore
+        if /^(_+)(.*)/ =~ id
+          id = Regexp.last_match(2) # Chop leading underscore
+          true
+        else
+          false
+        end
+      id = id[0] if abbreviate
+      # Convert _separated_names to the CamelCase
+      id = type.prefix + id.split('_').collect{ |s| s[0].upcase << s[1..-1] }.join
+      # Carry over the method name's leading underscore only if the prefix is not in turn underscored
+      _ && !type.prefix.start_with?('_') ? Regexp.last_match(1) + id : id
+    }
+
+    # Pluggable _snake_case identifier decorator
+    SNAKE_CASE_DECORATOR = -> (type, symbol, abbreviate: false, **kws) {
+      id = symbol.to_s.sub(/[!?]$/, '') # Strip trailing !?
+      # Check for leading underscore
+      _ =
+        if /^(_+)(.*)/ =~ id
+          id = Regexp.last_match(2)
+          true
+        else
+          false
+        end
+      id = abbreviate ? "#{type.prefix}#{id[0]}" : "#{type.prefix}_#{id}"
+      # Carry over the method name's leading underscore only if the prefix is not in turn underscored
+      _ && !type.prefix.start_with?('_') ? Regexp.last_match(1) + id : id
+    }
+
+    self.decorator = CAMEL_CASE_DECORATOR
+
+  private
+    
+    def method_missing(meth, *args)
+      if (method = @methods[meth]).nil?
+        # On anything thats not a defined method return a type-decorated identifier
+        # This allows to generate arbitrary type-qualified identifiers with #{type.foo}
+        raise "unexpected arguments" unless args.empty?
+        identifier(meth)
+      else
+        method
+      end
+    end
+
+    # Overridable for custom method in derived classes
+    def method_class = Method
+
+    # Create a new type-bound function (aka method)
+    def method(result, name, parameters, inline: false, visibility: nil, constraint: true, instance: name, **kws)
+      method = method_class.new(
+        self,
+        result,
+        name,
+        parameters, # TODO force parameter types coercion
+        inline:,
+        visibility: (visibility.nil? ? self.visibility : visibility), # Method's visibility property can be borrowed from the type itself
+        constraint: constraint,
+        **kws
+      )
+      raise "##{instance} method redefinition is not allowed" if @methods.has_key?(instance)
+      @methods[instance] = method
+      references << method # Avoid introducing cyclic dependency due to the method's dependency on self
+      method
+    end
+
+    def configure
+      method(:void, :destroy, { target: lvalue }, constraint: -> { destructible? }).configure do
+        header %{
+          @brief Destroy existing value
+
+          @param[out] target value to be destroyed
+
+          This function destroys the value previously constructed with any constructor.
+          It involves freeing allocated memory and destroying the constituent values with the respective destructors.
+
+          It is an error to use the value after call to this function (`*target` is considered to contain garbage afterwards).
+
+          @since 2.0
+        }
+      end
+      method(:void, :create, { target: lvalue }, instance: :default_create, constraint: -> { default_constructible? }).configure do
+        header %{
+          @brief Create a new value
+
+          @param[out] target value to be created
+
+          This function constructs the value with parameterless constructor.
+
+          Previous contents of `*target` is overwritten.
+
+          Once constructed, the value is to be destroyed with @ref #{destroy}.
+
+          @since 2.0
+        }
+      end
+      method(:void, :copy, { target: lvalue, source: const_rvalue }, constraint: -> { copyable? }).configure do
+        header %{
+          @brief Create a copy of source value
+
+          @param[out] target value to be created
+          @param[in]  source value to be cloned
+
+          This function is meant to an independent copy (a clone) of `*source` value in place of `*target`.
+
+          Previous contents of `*target` is overwritten.
+
+          Once constructed, the value is to be destroyed with @ref #{destroy}.
+          
+          @since 2.0
+        }
+      end
+      method(:int, :equal, { left: const_rvalue, right: const_rvalue }, constraint: -> { comparable? }).configure do
+        header %{
+          @brief Perform equality testing of two values
+
+          @param[in] left  value to test for equality
+          @param[in] right value to test for equality
+
+          @return non-zero if values are considered equal and zero otherwise
+
+          This function returns a non-zero value if specified values are considered equal and zero value otherwise.
+          Normally the values' contents are considered on equality testing.
+
+          @since 2.0
+        }
+      end
+      method(:int, :compare, { left: const_rvalue, right: const_rvalue }, constraint: -> { orderable? }).configure do
+        header %{
+          @brief Compute relative ordering of two values
+
+          @param[in] left  value to order
+          @param[in] right value to order
+
+          @return negative, positive or zero value depending on comparison of the specified values
+
+          This function returns negative value if `left` precedes `right`, positive value if `left` follows `right` and zero if both values are considered equal.
+
+          Normally the values' contents are considered on comparison.
+
+          This function is in general independent to but is expected to be consistent with @ref #{equal} function.
+
+          @since 2.0
+        }
+      end
+      method(:size_t, :hash_code, { target: const_rvalue }, constraint: -> { hashable? } ).configure do
+        header %{
+          @brief Compute hash code
+
+          @param[in] target value to compute hash code for
+
+          @return hash code
+
+          This function computes a hash code which reflects the value's contents in some way,
+          that is two values considered equal must yield identical hash codes.
+          Two different values may or may not yield identical hash codes, however.
+
+          @since 2.0
+        }
+      end
+    end
+
+  end # Composite
+
+
+  # Type-bound C side function
+  class Composite::Method < Function
+
+    attr_reader :type
+  
+    def initialize(type, result, name, parameters, **kws)
+      @type = type
+      super(result.to_value, self.type.identifier(name), parameters, **kws)
+      dependencies << self.type << self.result.to_type
+      # TODO register parameters' types as dependencies
+    end
+
+    def method_missing(meth, *args) 
+      if parameters.has_key?(meth) then parameters[meth]
+      elsif type.respond_to?(meth) then type.send(meth, *args)
+      else meth
+      end
+    end
+
+  private
+
+    def render_function_header(stream)
+      if public?
+        stream << %{
+          /**
+            #{type.ingroup}
+            #{@header}
+          */
+        }
+      end
+    end
+
+    def render_declaration_specifier(stream)
+      stream << (inline? ? 'AUTOC_INLINE ' : 'AUTOC_EXTERN ')
+    end
+
+    def render_implementation(stream)
+      render_function_definition(stream) if live? && !inline?
+    end
+
+  end # Method
+
+
+  Composite::DEFINITIONS = Code.new(
+    interface: %{
+      #ifndef AUTOC_INLINE
+        #if defined(__cplusplus)
+          #define AUTOC_INLINE inline
+        #elif defined(__clang__)
+          #define AUTOC_INLINE static __inline __attribute__((unused))
+        #elif __STDC_VERSION__ >= 199901L
+          #define AUTOC_INLINE static inline
+        #else
+          #define AUTOC_INLINE static __inline
+        #endif
+      #endif
+      #ifndef AUTOC_EXTERN
+        #ifdef __cplusplus
+          #define AUTOC_EXTERN extern "C"
+        #else
+          #define AUTOC_EXTERN extern
+        #endif
+      #endif
+    }
+  )
+
+
+end