code-ruby 3.1.2 → 4.0.1

data/lib/code/object/duration.rb

@@ -3,6 +3,30 @@
 class Code
   class Object
     class Duration < Object
+      CLASS_DOCUMENTATION = {
+        name: "Duration",
+        description: "stores a length of time for shifting dates and times.",
+        examples: ["1.day", "2.hours", "Duration.new(\"P1D\")"]
+      }.freeze
+      INSTANCE_FUNCTIONS = {
+        "ago" => {
+          name: "ago",
+          description: "returns the current time minus this duration.",
+          examples: %w[1.day.ago 2.hours.ago 30.minutes.ago]
+        },
+        "from_now" => {
+          name: "from_now",
+          description: "returns the current time plus this duration.",
+          examples: %w[1.day.from_now 2.hours.from_now 30.minutes.from_now]
+        }
+      }.freeze
+
+      def self.function_documentation(scope)
+        return INSTANCE_FUNCTIONS if scope == :instance
+
+        {}
+      end
+
       def initialize(*args, **_kargs, &_block)
         self.raw =
           if args.first.is_an?(::ActiveSupport::Duration)

data/lib/code/object/function.rb

@@ -3,9 +3,91 @@
 class Code
   class Object
     class Function < Object
-      attr_reader :code_parameters, :code_body, :definition_context, :parent
+      CLASS_DOCUMENTATION = {
+        name: "Function",
+        description:
+          "stores a callable block with parameters, captured context, and documentation.",
+        examples: [
+          "Function.new",
+          "((value) => { value + 1 }).call(1)",
+          "((value) => { value }).parameters.length"
+        ]
+      }.freeze
+      INSTANCE_FUNCTIONS = {
+        "call" => {
+          name: "call",
+          description:
+            "evaluates the function body with the provided arguments.",
+          examples: [
+            "((value) => { value + 1 }).call(1)",
+            "((name:) => { name }).call(name: :ada)",
+            "((a, b = 2) => { a + b }).call(3)"
+          ]
+        },
+        "extend" => {
+          name: "extend",
+          description:
+            "creates a child function that can call the receiver through super.",
+          examples: [
+            "Base = () => { self.name = :base } Child = Base.extend(() => { super() }) Child().name",
+            "Base = () => { 1 } Child = Base.extend(() => { super() }) Child()",
+            "Base = (name) => { self.name = name } Child = Base.extend((...) => { super(...) }) Child(:a).name"
+          ]
+        },
+        "documentation" => {
+          name: "documentation",
+          description:
+            "returns or replaces the function documentation dictionary.",
+          examples: [
+            "f = () => { 1 } f.documentation",
+            "f = () => { 1 } f.documentation(description: \"returns one\", examples: [\"f()\"])",
+            "f = () => { 1 } f.documentation(description: \"returns one\", examples: [\"f()\"]).description"
+          ]
+        },
+        "documentation=" => {
+          name: "documentation=",
+          description: "replaces the function documentation dictionary.",
+          examples: [
+            "f = () => { 1 } f.documentation = { description: \"returns one\", examples: [\"f()\"] }",
+            "f = () => { 1 } f.documentation = { name: \"one\", description: \"returns one\", examples: [\"one()\"] } f.documentation.name",
+            "f = () => { 1 } f.documentation = { description: \"returns one\", examples: [\"f()\"] } f.documentation.examples.first"
+          ]
+        },
+        "parameters" => {
+          name: "parameters",
+          description:
+            "returns a list of parameter descriptors for the function.",
+          examples: [
+            "((name) => { name }).parameters.first.name",
+            "((name = :a) => { name }).parameters.first.default",
+            "((...values) => { values }).parameters.first.spread?"
+          ]
+        },
+        "to_string" => {
+          name: "to_string",
+          description: "formats the function as source code.",
+          examples: [
+            "(() => { 1 }).to_string",
+            "((value) => { value + 1 }).to_string",
+            "((name:) => { name }).to_string"
+          ]
+        }
+      }.freeze
+
+      def self.function_documentation(scope)
+        return INSTANCE_FUNCTIONS if scope == :instance
+
+        {}
+      end
+
+      attr_accessor :documentation
+      attr_reader :code_parameters,
+                  :code_body,
+                  :definition_context,
+                  :instance_functions,
+                  :parent
 
-      def initialize(*args, parent: nil, methods: nil, **_kargs, &_block)
+      def initialize(*args, parent: nil, functions: nil, **_kargs, &_block)
         @code_parameters =
           List
             .new(args.first)
@@ -16,8 +98,15 @@ class Code
         @code_body = Code.new(args.second.presence)
         @definition_context = args.third if args.third.is_a?(Context)
         @parent = parent.to_code
-        self.methods = methods.to_code
-        self.methods = Dictionary.new if self.methods.nothing?
+        self.functions = functions.to_code
+        self.functions = Dictionary.new if self.functions.nothing?
+        @instance_functions = Dictionary.new
+        self.documentation =
+          Dictionary.new(
+            "name" => String.new(""),
+            "description" => String.new(""),
+            "examples" => List.new
+          )
 
         self.raw = List.new([code_parameters, code_body])
       end
@@ -25,6 +114,7 @@ class Code
       def call(**args)
         code_operator = args.fetch(:operator, nil).to_code
         code_arguments = args.fetch(:arguments, List.new).to_code
+        code_value = code_arguments.code_first
         globals = multi_fetch(args, *GLOBALS)
 
         case code_operator.to_s
@@ -34,11 +124,27 @@ class Code
             *code_arguments.raw,
             explicit_arguments: args.fetch(:explicit_arguments, true),
             bound_self: args.fetch(:bound_self, nil),
+            constructing_literal_classes:
+              args.fetch(:constructing_literal_classes, nil),
             **globals
           )
         when "extend"
           sig(args) { Function }
           code_extend(code_arguments.code_first)
+        when "documentation"
+          if code_arguments.any?
+            sig(args) { Dictionary }
+            self.documentation = code_value.code_to_dictionary
+          else
+            sig(args)
+            documentation
+          end
+        when "documentation="
+          sig(args) { Dictionary }
+          self.documentation = code_value.code_to_dictionary
+        when "parameters"
+          sig(args)
+          code_parameters
         when /=$/
           sig(args) { Object }
           code_set(code_operator.to_s.chop, code_value)
@@ -60,18 +166,22 @@ class Code
         *arguments,
         explicit_arguments: true,
         bound_self: nil,
+        constructing_literal_classes: nil,
         **globals
       )
         code_arguments = arguments.to_code
         code_context = Context.new({}, definition_context || globals[:context])
         code_self = bound_self.to_code
+        if (code_self.nil? || code_self.nothing?) && parent.is_a?(Class)
+          code_self = parent.code_call(*arguments, **globals)
+        end
         code_self = Dictionary.new if code_self.nil? || code_self.nothing?
         code_parent = captured_self.to_code
 
         code_context.code_set("self", code_self)
         bind_parent(code_context, code_self, code_parent)
 
-        if parent.is_a?(Function)
+        if parent.is_a?(Function) || parent.is_a?(Class)
           code_context.code_set(
             "super",
             Super.new(
@@ -84,19 +194,44 @@ class Code
           )
         end
 
+        captures_function_arguments =
+          code_parameters.raw.any? do |parameter|
+            parameter.block? || parameter.blocks?
+          end
+        reserved_function_arguments =
+          captures_function_arguments ? code_arguments.raw.grep(Function) : []
+        code_block_argument =
+          if code_parameters.raw.any?(&:block?)
+            code_arguments.raw.detect { |argument| argument.is_a?(Function) }
+          end
+
         code_parameters.raw.each.with_index do |code_parameter, index|
           code_argument =
-            if code_parameter.spread? || code_parameter.regular_splat?
+            if code_parameter.spread?
               code_arguments
+            elsif code_parameter.regular_splat?
+              Object::List.new(
+                code_arguments.raw.reject do |argument|
+                  argument.is_a?(Dictionary) ||
+                    reserved_function_arguments.include?(argument)
+                end
+              )
             elsif code_parameter.keyword_splat?
-              code_arguments.raw.detect do |code_argument|
-                code_argument.is_a?(Dictionary)
-              end || Dictionary.new
-            elsif code_parameter.block?
               code_arguments
                 .raw
-                .detect { |code_argument| code_argument.is_a?(Function) }
-                .to_code
+                .grep(Dictionary)
+                .inject(Dictionary.new) do |memo, argument|
+                  memo.code_merge!(argument)
+                end
+            elsif code_parameter.block?
+              code_block_argument.to_code
+            elsif code_parameter.blocks?
+              Object::List.new(
+                code_arguments
+                  .raw
+                  .grep(Function)
+                  .reject { |argument| argument == code_block_argument }
+              )
             elsif code_parameter.keyword?
               code_arguments
                 .raw
@@ -118,18 +253,30 @@ class Code
               if code_default.is_a?(Code)
                 code_default.code_evaluate(
                   **globals,
-                  context: code_context
+                  context: code_context,
+                  trusted_evaluation: true
                 )
               else
                 code_default
               end
           end
 
-          code_context.code_set(code_parameter.code_name, code_argument)
+          code_name = code_parameter.code_name
+          unless code_name.blank?
+            code_context.code_set(code_name, code_argument)
+          end
         end
 
-        code_body.code_evaluate(**globals, context: code_context)
+        code_body
+          .code_evaluate(
+            **globals,
+            constructing_literal_classes: constructing_literal_classes,
+            context: code_context,
+            trusted_evaluation: true
+          )
+          .tap { persist_instance_functions(code_self) }
       rescue Error::Return => e
+        persist_instance_functions(code_self)
         e.code_value
       end
 
@@ -139,8 +286,10 @@ class Code
           .inject([]) do |signature, code_parameter|
             if code_parameter.spread? || code_parameter.regular_splat?
               signature + [Object.repeat]
+            elsif code_parameter.blocks?
+              signature + [Function.repeat]
             elsif code_parameter.block?
-              signature + [Function]
+              signature + [Function.maybe]
             elsif code_parameter.keyword_splat?
               signature + [Dictionary.maybe]
             elsif code_parameter.keyword? && code_parameter.required?
@@ -186,33 +335,142 @@ class Code
       def code_extend(function)
         code_function = function.to_code
 
-        Function.new(
-          code_function.code_parameters,
-          code_function.code_body.raw,
-          code_function.definition_context,
-          parent: self,
-          methods: methods.code_deep_duplicate
+        Function
+          .new(
+            code_function.code_parameters,
+            code_function.code_body.raw,
+            code_function.definition_context,
+            parent: self,
+            functions: functions.code_deep_duplicate
+          )
+          .tap do |extended_function|
+            extended_function.instance_functions.code_merge!(instance_functions)
+          end
+      end
+
+      def code_deep_duplicate(seen = {})
+        seen.compare_by_identity unless seen.compare_by_identity?
+        return seen[self] if seen.key?(self)
+
+        duplicate = Function.new
+        seen[self] = duplicate
+
+        duplicate.code_replace(
+          code_parameters: code_parameters.code_deep_duplicate(seen),
+          code_body: code_body.code_deep_duplicate(seen),
+          definition_context: definition_context&.code_deep_duplicate(seen),
+          parent:
+            parent.is_a?(Function) ? parent.code_deep_duplicate(seen) : parent,
+          functions: functions.code_deep_duplicate(seen),
+          instance_functions: instance_functions.code_deep_duplicate(seen),
+          documentation: documentation.code_deep_duplicate(seen)
         )
+        duplicate
+      end
+
+      def code_replace(
+        code_parameters:,
+        code_body:,
+        definition_context:,
+        parent:,
+        functions:,
+        instance_functions:,
+        documentation:
+      )
+        @code_parameters = code_parameters
+        @code_body = code_body
+        @definition_context = definition_context
+        @parent = parent
+        self.functions = functions
+        @instance_functions = instance_functions
+        self.documentation = documentation
+        self.raw = List.new([code_parameters, code_body])
+        self
+      end
+
+      def code_functions
+        code_class_functions
+      end
+
+      def code_instance_functions
+        parent_functions =
+          if parent.is_a?(Function)
+            parent.code_instance_functions
+          else
+            Dictionary.new
+          end
+
+        Object.sorted_dictionary(
+          parent_functions.code_merge(
+            function_dictionary_for(instance_functions)
+          ).raw
+        )
+      end
+
+      def code_class_functions
+        function_dictionary_for(functions)
       end
 
       def code_fetch(key)
-        methods.code_fetch(key)
+        functions.code_fetch(key)
       end
 
       def code_get(key)
-        methods.code_get(key)
+        functions.code_get(key)
       end
 
       def code_has_key?(key)
-        methods.code_has_key?(key)
+        functions.code_has_key?(key)
       end
 
       def code_set(key, value)
-        methods.code_set(key, value)
+        functions.code_set(key, value)
       end
 
       private
 
+      def function_dictionary_for(dictionary)
+        Object.sorted_dictionary(
+          dictionary.raw.to_h do |key, value|
+            name = key.to_s
+            [
+              name,
+              Dictionary.new(
+                "name" => String.new(name),
+                "description" => String.new(function_description(value)),
+                "examples" => List.new(function_examples(value))
+              )
+            ]
+          end
+        )
+      end
+
+      def function_description(value)
+        code_value = value.to_code
+        return "" unless code_value.is_a?(Function)
+
+        code_value.documentation.code_get("description").to_s
+      end
+
+      def function_examples(value)
+        code_value = value.to_code
+        return [] unless code_value.is_a?(Function)
+
+        code_value.documentation.code_get("examples").to_code.code_to_list.raw
+      end
+
+      def persist_instance_functions(code_self)
+        return unless code_self.is_a?(Object)
+
+        instance_functions.code_merge!(
+          documentable_instance_functions(code_self)
+        )
+      end
+
+      def documentable_instance_functions(code_self)
+        code_self.code_documentable_functions
+      end
+
       def bind_parent(code_context, code_self, code_parent)
         return if code_parent.nothing?
 
@@ -247,7 +505,9 @@ class Code
 
       def parameter_to_raw(parameter)
         code_parameter = parameter.to_code
-        raw_parameter = { name: code_parameter.code_name.to_s }
+        raw_parameter = {}
+        code_name = code_parameter.code_name
+        raw_parameter[:name] = code_name.to_s unless code_name.blank?
 
         if code_parameter.keyword?
           raw_parameter[:keyword] = ":"
@@ -257,6 +517,8 @@ class Code
           raw_parameter[:regular_splat] = "*"
         elsif code_parameter.block?
           raw_parameter[:block] = "&"
+        elsif code_parameter.blocks?
+          raw_parameter[:blocks] = "&&"
         elsif code_parameter.spread?
           raw_parameter[:spread] = "..."
         end