carbon-core 0.1.0

data/lib/carbon/concrete/item.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "carbon/concrete/item/base"
+require "carbon/concrete/item/data"
+require "carbon/concrete/item/function"
+require "carbon/concrete/item/internal"
+require "carbon/concrete/item/struct"
+require "carbon/concrete/item/trait"
+
+module Carbon
+  module Concrete
+    # Items.  These are buildable concepts that have dependencies.  Each item
+    # includes {Item::Base} in order to respond to the item API.  The main
+    # API for items are the following set of methods:
+    #
+    # - `#intern` (`String`) - Returns an "interned" name of the item.  See
+    #   {Base#intern}.
+    # - `#name` (`String`) - The full name of the item.  See {Base#name}.
+    # - `#generics` (`<Type::Generic>`) - The generics of the item.
+    #   This is normally something like `[T]`; these most likely have no
+    #   correspondance to an actual type.  See {Base#generics}.
+    # - `#dependencies` (`Set<Request>`) - A set of dependencies that
+    #   the item has.  This includes the generics that the item uses.
+    #   See {Base#dependencies}.
+    # - `#==`, `#eql?` (`Boolean`) - Comparison.  Normally uses the `#intern`
+    #   name for a basis of comarison.  See {Base#==}.
+    # - `#call` - Builds the item for compilation.  This is the last stage.
+    #   This should generate something for LLVM in some way.  See {Base#call}.
+    # - `#corrected_dependencies` (`Enumerable`) - Corrects the depdenencies of
+    #   the Item.  This makes it so that the generics of the passed request
+    #   are matched with the generics of the dependencies, essentially
+    #   resolving them.  See {Base#corrected_dependencies}.
+    module Item
+    end
+  end
+end

data/lib/carbon/concrete/item/base.rb

@@ -0,0 +1,153 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Carbon
+  module Concrete
+    module Item
+      # A "base" for other items.  This just has some common methods that all
+      # items need to share to be compatible with the index.  This module is
+      # the bases of the build system in the {Concrete} module.
+      module Base
+        # Returns the interned name of the item.  This contains no generic
+        # information.  Interned names are mostly used to match generic
+        # information laden types with the items that define them; for example,
+        # it is meant to be used to match the type
+        # `Carbon::Pointer<Carbon::String>` to the module `Carbon::Pointer<T>`.
+        # The common parts of both is the module name that the type uses - or,
+        # rather, everything but the generic information.  Interned names
+        # discard the information that is unneeded for matching the two.
+        #
+        # This methodology has the downside that a module with the same name
+        # as the base of a generic module cannot exist; however, allowing such
+        # would ultimately be confusing.
+        #
+        # @api public
+        # @example For a module.
+        #   item.name # => "Carbon::Pointer<T>"
+        #   item.intern # => "Carbon::Pointer"
+        # @example For a function.
+        #   item.name
+        #     # => "Carbon::Pointer<T>.+(Carbon::Pointer<T>, Carbon::Int32)"
+        #   item.intern
+        #     # => "Carbon::Pointer.+(Carbon::Pointer, Carbon::Int32)"
+        # @return [::String] The interned name.
+        attr_reader :intern
+
+        # Returns the full name of the item.  This can include generic
+        # information.
+        #
+        # @example
+        #   item.name # => "Carbon::Pointer<T>"
+        # @return [::String]
+        attr_reader :name
+
+        # Returns the generic information associated with this item.  This is
+        # used internally for generic substitution later on.
+        #
+        # @api semipublic
+        # @example
+        #   item.generics # => [#<Carbon::Concrcete::Type::Generic T>]
+        # @return [<Type::Generic>]
+        attr_reader :generics
+
+        # The dependencies that this item is based on.  These are requests
+        # because we _request_ the item from the index as a dependency.
+        # Requests contain the module name that it builds and the generics
+        # it requires.
+        #
+        # @api semipublic
+        # @example
+        #   item.dependencies # => Set[#<Carbon::Concrete::Request T>]
+        # @return [Set<Request>]
+        attr_reader :dependencies
+
+        # Creates a hash from a given {Concrete::Type} that can be used to
+        # intialize an instance of this object.  This is mostly used for
+        # {Index#define} and shouldn't be used anywhere else.
+        #
+        # @api private
+        # @param type [Concrete::Type] The type.
+        # @return [{::Symbol => ::Object}]
+        def self.from(type)
+          { module: type }
+        end
+
+        # Compares this item to another object.  If the other object _is_ this
+        # item, then it returns true; otherwise, if the other object is an
+        # item, and the other object's {#intern} is equal to this object's
+        # {#intern}, then it returns true; otherwise, it returns false.
+        #
+        # @api public
+        # @example
+        #   first.intern # => "Carbon::Pointer"
+        #   second.intern # => "Carbon::Pointer"
+        #   first == first # => true
+        #   first == second # => true
+        #   second == second # => true
+        #   second == first # => true
+        # @param other [Base, ::String, ::Object] The object to compare.
+        # @return [::Boolean] The result of comparison.
+        def ==(other)
+          equal?(other) || (other.is_a?(Base) && intern == other.intern)
+        end
+        alias_method :eql?, :==
+
+        # Creates a hash of the item.  This is used mostly in the Hash
+        # class.
+        #
+        # @api private
+        # @return [Numeric]
+        def hash
+          intern.hash
+        end
+
+        # rubocop:disable Lint/UnusedMethodArgument
+
+        # Performs compilation for the item.  This converts the item into an
+        # LLVM-based value or type, to be used for compiling.  If
+        # unimplemented, it raises a `NotImplementedError`.
+        #
+        # @api private
+        # @param build [Concrete::Build] The build information for the item.
+        # @param generics [{Concrete::Type => Concrete::Type}] The generics
+        #   to apply for the item.
+        # @return [void]
+        # @raise [NotImplementedError] If it is not implemented.
+        def call(build, generics)
+          fail NotImplementedError, "Could not build #{self.class}"
+        end
+
+        # Modifies the dependencies of this item so that they conform to the
+        # given request.  This should resolve all of our dependencies so that
+        # they no longer hold any sort of generic class.
+        #
+        # @api private
+        # @param request [Request] The request.
+        # @yield [dep] The corrected dependencies.
+        # @yieldparam dep [Request] The corrected dependency.
+        # @return [::Enumerable] An enumerator of the corrected dependencies,
+        #   if no block was given.
+        # @return [void] If a block was given.
+        def corrected_dependencies(request, &block)
+          return to_enum(:corrected_dependencies, request) unless block_given?
+          return dependencies.each(&block) if generics.empty?
+
+          forced_corrected_dependencies(request, &block)
+        end
+
+      private
+
+        def forced_corrected_dependencies(request, &block)
+          # Array<Type::Generic> -> Array<(Type::Generic, Numeric)> ->
+          # Array<(String, Type::Generic)> -> {String => Type::Generic}
+          mapping = generics
+                    .each_with_index
+                    .map { |gen, i| [gen.name.intern, request.generics[i]] }
+                    .to_h
+
+          dependencies.map { |dep| dep.sub(mapping) }.each(&block)
+        end
+      end
+    end
+  end
+end

data/lib/carbon/concrete/item/data.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Carbon
+  module Concrete
+    module Item
+      # A data definition.  All data definitions include this module, which
+      # acts as a sort of hirearchy.  It makes it easy to identify if an item
+      # is a data definition or a function definition.
+      module Data
+        include Base
+
+        # The traits that the data type implements.  This is mostly used for
+        # validation and logic.
+        #
+        # @api public
+        # @return [<Type>]
+        attr_reader :implements
+      end
+    end
+  end
+end

data/lib/carbon/concrete/item/function.rb

@@ -0,0 +1,97 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Carbon
+  module Concrete
+    module Item
+      # A function definition.  This contains all of the information needed to
+      # build a proper LLVM function.  This is stored within an index and
+      # serialized as needed, in order to defer compilation.  There are two
+      # main types of functions: "normal," or "extern."  "Normal" functions
+      # have an actual definition (i.e. {Tacky::Function}), and are written
+      # in Ruby/Carbon.  "Extern" functions do not have a definition; they
+      # map a Carbon function to a C/low-level function.  Instead of a
+      # definition, they have a function name, that maps to the C/low-level
+      # function.  This is normally specified with an `:extern` directive.
+      #
+      # @api private
+      # @note
+      #   **This class is frozen upon initialization.**  This means that any
+      #   attempt to modify it will result in an error.  In most cases, the
+      #   attributes on this class will also be frozen, as well.
+      class Function
+        include Base
+
+        # (see Item::Base.from)
+        def self.from(type)
+          {
+            module: type.to_module,
+            internal: type.name.function.name,
+            arguments: type.name.function.parameters,
+            generics: type.generics,
+            definition: Tacky::Function.new(type.name.function.parameters)
+          }
+        end
+
+        def initialize(data)
+          @module = data.fetch(:module)
+          @internal = data.fetch(:internal)
+          @parameters = data.fetch(:arguments) { data.fetch(:parameters) }
+          @definition = data.fetch(:definition)
+          @generics = data.fetch(:generics) { @module.generics }
+          @return = data.fetch(:return)
+
+          derive_name
+          derive_dependencies
+          deep_freeze!
+        end
+
+        # (see Base#call)
+        def call(build, generics)
+          value = case @definition
+                  when Tacky::Function
+                    build_function_intern(build, generics)
+                  when ::String, ::Symbol
+                    build_function_extern(build, generics)
+                  else fail ArgumentError,
+                    "Unknown definition #{@definition.class}"
+                  end
+
+          build.functions[@module.sub(generics)] = value
+        end
+
+      private
+
+        # rubocop:disable Metrics/AbcSize
+        def build_function_intern(build, generics)
+          full = @full.sub(generics)
+          params = @parameters
+            .map { |p| build.types.fetch(p.sub(generics)).last }
+          ret = build.types.fetch(@return.sub(generics)).last
+          func = build.module.functions.add(full, params, ret)
+          @definition.call(func, build, generics)
+          build.functions[full] = func
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        # @todo TODO: finish.
+        def build_function_extern(build, generics)
+        end
+
+        def derive_name
+          @full = @module.call(@internal, @parameters)
+          @intern = @full.intern
+          @name = @full.to_s
+        end
+
+        def derive_dependencies
+          @dependencies = Set.new
+          @dependencies << @return.to_request
+          @dependencies.merge(@parameters.map(&:to_request))
+          @dependencies.merge(@definition.dependencies.map(&:to_request)) if \
+            @definition.is_a?(Tacky::Function)
+        end
+      end
+    end
+  end
+end

data/lib/carbon/concrete/item/internal.rb

@@ -0,0 +1,83 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Carbon
+  module Concrete
+    module Item
+      # An internal data type.  In most cases, this is just integers and
+      # pointers that can't be easily serialized because of links to LLVM and
+      # FFI.
+      #
+      # @api private
+      # @note
+      #   **This class is frozen upon initialization.**  This means that any
+      #   attempt to modify it will result in an error.  In most cases, the
+      #   attributes on this class will also be frozen, as well.
+      class Internal
+        include Data
+
+        # Retreives the LLVM type information for the given integer size.
+        # This cannot be serialized by marshal or any other serialization
+        # library.
+        #
+        # @api private
+        # @return [Proc<Numeric, LLVM::Type>]
+        TYPE = proc { |size| LLVM.const_get("Int#{size}").type }
+
+        # (see Item::Base.from)
+        def self.from(type)
+          { module: type, implements: [] }
+        end
+
+        # Initialize the internal data type.  Internal data types may not have
+        # generic information, and have no dependencies, but can still
+        # implement traits.
+        #
+        # @param data [::Hash] The options for the internal data type.
+        # @option data [Type] :module The module of the internal data type.
+        # @option data [::String, ::Symbol] :kind The kind of the internal data
+        #   type.  Valid values are `:integer`, `:pointer`, `:int_pointer`,
+        #   `:ary_pointer`, or the string version of any of those.  This
+        #   controls the underlying LLVM type of the internal data type.
+        # @option data [::String, ::Numeric, #to_i] :size The size of the
+        #   internal data type.  For integers, it is the number of bits in the
+        #   integer; for pointers, it is the number of bits of the element it
+        #   points to.
+        # @option data [<Type>] :implements ([]) The types that the
+        #   internal data type implements.
+        def initialize(data)
+          @module = data.fetch(:module)
+          @kind = data.fetch(:kind) { data.fetch(:type) }.to_s
+          @size = data.fetch(:size, 8)
+
+          @generics = @module.generics
+          @implements = Set.new(data.fetch(:implements, []))
+          @dependencies = Set.new
+
+          derive_name
+          deep_freeze!
+        end
+
+        # (see Base#call)
+        def call(build, generics)
+          value = case @kind.to_s
+                  when "integer" then TYPE.call(@size)
+                  when "pointer"
+                    type = build.types.fetch(generics.fetch("T"))
+                    type.last.pointer
+                  else fail ArgumentError, "Unknown kind #{@kind}"
+                  end
+
+          build.types[@module.sub(generics)] = [self, value]
+        end
+
+      private
+
+        def derive_name
+          @intern = @module.intern
+          @name = @module.to_s
+        end
+      end
+    end
+  end
+end

data/lib/carbon/concrete/item/struct.rb

@@ -0,0 +1,65 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "carbon/concrete/item/struct/element"
+
+module Carbon
+  module Concrete
+    module Item
+      # A struct data type.  This is normally a sequence of elements that are
+      # stored sequentially in memory.  Each element has a name, to reference
+      # which position, and a type.
+      #
+      # @api private
+      # @note
+      #   **This class is frozen upon initialization.**  This means that any
+      #   attempt to modify it will result in an error.  In most cases, the
+      #   attributes on this class will also be frozen, as well.
+      class Struct
+        include Data
+
+        # (see Item::Base.from)
+        def self.from(type)
+          { module: type, implements: [], elements: [] }
+        end
+
+        # Initialize the struct with the given data.
+        #
+        # @param data [::Hash] The data to initialize with.
+        # @option data [Type] :module The name of the struct.
+        # @option data [<::String, Type>] :elements The elements of
+        #   the struct.
+        # @option data [<Type>] :implements The traits that this
+        #   data type implements.
+        def initialize(data)
+          @module   = data.fetch(:module)
+          @generics = @module.generics
+          @intern   = @module.intern
+          @name     = @module.to_s
+
+          @implements   = Set.new(data.fetch(:implements))
+          @dependencies = Set.new
+
+          derive_elements(data.fetch(:elements))
+          derive_dependencies
+          deep_freeze!
+        end
+
+        # (see Base#call)
+        def call(build, generics)
+          super # TODO: fixme.
+        end
+
+      private
+
+        def derive_elements(elements)
+          @elements = elements.map { |e| Element.new(*e) }
+        end
+
+        def derive_dependencies
+          @dependencies.merge(@elements.map { |e| e.type.to_request })
+        end
+      end
+    end
+  end
+end