code-ruby 3.1.2 → 4.0.1

data/lib/code/object/boolean.rb

@@ -3,6 +3,62 @@
 class Code
   class Object
     class Boolean < ::Code::Object
+      CLASS_DOCUMENTATION = {
+        name: "Boolean",
+        description: "represents true or false.",
+        examples: %w[Boolean Boolean.new(true) Boolean.new(false)]
+      }.freeze
+      INSTANCE_FUNCTIONS = {
+        "&" => {
+          name: "&",
+          description: "returns true when both booleans are true.",
+          examples: ["true & true", "true & false", "false & false"]
+        },
+        "bitwise_and" => {
+          name: "bitwise_and",
+          description: "returns true when both booleans are true.",
+          examples: %w[
+            true.bitwise_and(true)
+            true.bitwise_and(false)
+            false.bitwise_and(false)
+          ]
+        },
+        "|" => {
+          name: "|",
+          description: "returns true when either boolean is true.",
+          examples: ["true | false", "false | true", "false | false"]
+        },
+        "bitwise_or" => {
+          name: "bitwise_or",
+          description: "returns true when either boolean is true.",
+          examples: %w[
+            true.bitwise_or(false)
+            false.bitwise_or(true)
+            false.bitwise_or(false)
+          ]
+        },
+        "^" => {
+          name: "^",
+          description: "returns true when exactly one boolean is true.",
+          examples: ["true ^ false", "true ^ true", "false ^ false"]
+        },
+        "bitwise_xor" => {
+          name: "bitwise_xor",
+          description: "returns true when exactly one boolean is true.",
+          examples: %w[
+            true.bitwise_xor(false)
+            true.bitwise_xor(true)
+            false.bitwise_xor(false)
+          ]
+        }
+      }.freeze
+
+      def self.function_documentation(scope)
+        return INSTANCE_FUNCTIONS if scope == :instance
+
+        {}
+      end
+
       def initialize(*args, **_kargs, &_block)
         self.raw =
           (args.first.is_an?(Object) ? args.first.truthy? : !!args.first)

data/lib/code/object/class.rb

@@ -3,6 +3,79 @@
 class Code
   class Object
     class Class < Object
+      CLASS_DOCUMENTATION = {
+        name: "Class",
+        description:
+          "wraps a value constructor and documents its class and instance functions.",
+        examples: %w[Class Class.new(String) Class.documentation.name]
+      }.freeze
+      INSTANCE_FUNCTIONS = {
+        "documentation" => {
+          name: "documentation",
+          description: "returns documentation for this class.",
+          examples: %w[
+            Class.documentation.description
+            List.documentation.name
+            Dictionary.documentation.name
+          ]
+        },
+        "functions" => {
+          name: "functions",
+          description:
+            "returns documented class functions available on this class.",
+          examples: %w[
+            Class.functions.keys.include?(:new)
+            List.functions.keys.include?(:new)
+            Dictionary.functions.keys.include?(:from_entries)
+          ]
+        },
+        "instance_functions" => {
+          name: "instance_functions",
+          description:
+            "returns documented functions available on values built by this class.",
+          examples: %w[
+            Class.instance_functions.keys.include?(:documentation)
+            List.instance_functions.keys.include?(:map)
+            String.instance_functions.keys.include?(:upcase)
+          ]
+        },
+        "class_functions" => {
+          name: "class_functions",
+          description:
+            "returns documented class functions available on this class.",
+          examples: %w[
+            Class.class_functions.keys.include?(:new)
+            List.class_functions.keys.include?(:new)
+            Dictionary.class_functions.keys.include?(:from_entries)
+          ]
+        },
+        "call" => {
+          name: "call",
+          description: "returns a new value by calling this class constructor.",
+          examples: [
+            "Class.call(String)",
+            "List.call([1, 2])",
+            "String.call(:hello)"
+          ]
+        },
+        "extend" => {
+          name: "extend",
+          description:
+            "returns a function that builds a value from this class before running the body.",
+          examples: [
+            "Widget = Dictionary.extend(() => { self.name = :widget self }) Widget().fetch(:name)",
+            "Person = Dictionary.extend((name) => { self.name = name self }) Person(:Ada).fetch(:name)",
+            "Counter = Dictionary.extend(() => { self.count = 0 self }) Counter().fetch(:count)"
+          ]
+        }
+      }.freeze
+
+      def self.function_documentation(scope)
+        return INSTANCE_FUNCTIONS if scope == :instance
+
+        {}
+      end
+
       def initialize(*args, **_kargs, &_block)
         self.raw =
           if args.first.is_a?(Class)
@@ -16,13 +89,81 @@ class Code
           end
       end
 
-      def call(...)
-        raw.call(...)
+      def call(**args)
+        code_operator = args.fetch(:operator, nil).to_code
+        dynamic_result = code_dynamic_call(code_operator, **args)
+        return dynamic_result if dynamic_result
+
+        case code_operator.to_s
+        when "documentation"
+          sig(args)
+          code_documentation
+        when "functions"
+          sig(args)
+          code_functions
+        when "instance_functions"
+          sig(args)
+          code_instance_functions
+        when "class_functions"
+          sig(args)
+          code_class_functions
+        when "extend"
+          sig(args) { Function }
+          code_extend(args.fetch(:arguments).code_first)
+        when "call"
+          sig(args) { Object.repeat }
+          code_call(*args.fetch(:arguments, []).to_code.raw)
+        when /=$/
+          if raw_class_functions.code_has_key?(code_operator).truthy?
+            raw.call(**args)
+          else
+            super
+          end
+        else
+          raw.call(**args)
+        end
+      end
+
+      def code_call(*arguments, **_globals)
+        raw.code_new(*arguments)
+      end
+
+      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
+        )
+      end
+
+      def code_functions
+        code_class_functions
+      end
+
+      def code_instance_functions
+        Object.documented_functions_for(raw, :instance)
+      end
+
+      def code_class_functions
+        raw_class_functions
+      end
+
+      def code_documentation
+        Object.documentation_for(raw)
       end
 
       def code_to_string
         String.new(raw.name.to_s.split("::")[2..].join("::"))
       end
+
+      private
+
+      def raw_class_functions
+        Object.documented_functions_for(raw, :class)
+      end
     end
   end
 end

data/lib/code/object/code.rb

@@ -3,13 +3,72 @@
 class Code
   class Object
     class Code < Object
-      def initialize(*args, **_kargs, &_block)
-        self.raw =
-          if args.first.is_a?(Node::Code)
-            args.first
+      CLASS_DOCUMENTATION = {
+        name: "Code",
+        description: "stores parsed source code for later evaluation.",
+        examples: [
+          "Code",
+          "Code.evaluate(\"1 + 2\")",
+          "Code.new(\"1 + 2\").evaluate"
+        ]
+      }.freeze
+      CLASS_FUNCTIONS = {
+        "evaluate" => {
+          name: "evaluate",
+          description: "evaluates source code and returns the result.",
+          examples: [
+            "Code.evaluate(\"1\")",
+            "Code.evaluate(\"1 + 2\")",
+            "Code.evaluate(\"[1, 2].size\")"
+          ]
+        }
+      }.freeze
+      INSTANCE_FUNCTIONS = {
+        "evaluate" => {
+          name: "evaluate",
+          description: "evaluates stored source code and returns the result.",
+          examples: [
+            "Code(\"1\").evaluate",
+            "Code(\"1 + 2\").evaluate",
+            "Code(\"[1, 2].size\").evaluate"
+          ]
+        }
+      }.freeze
+
+      def self.function_documentation(scope)
+        return INSTANCE_FUNCTIONS if scope == :instance
+        return CLASS_FUNCTIONS if scope == :class
+
+        {}
+      end
+
+      class ScopedObject < Object
+        def call(**args)
+          code_operator = args.fetch(:operator, nil).to_code
+          code_context = args.fetch(:context).to_code
+
+          code_context = code_context.code_lookup!(code_operator)
+          code_result = code_context.code_fetch(code_operator)
+
+          if code_result.is_a?(Super) ||
+               (
+                 code_result.is_a?(Function) &&
+                   args.fetch(:explicit_arguments, false)
+               )
+            code_result.call(**args, operator: nil)
           else
-            Node::Code.new(::Code.parse(args.first.to_s))
+            sig(args)
+            code_result
           end
+        end
+      end
+
+      attr_reader :trusted
+
+      def initialize(*args, **_kargs, &_block)
+        @trusted = args.first.is_a?(Node::Code)
+        self.raw =
+          (trusted ? args.first : Node::Code.new(::Code.parse(args.first.to_s)))
       end
 
       def self.code_evaluate(*args, **globals)
@@ -18,8 +77,50 @@ class Code
         new(*code_args.raw).code_evaluate(**globals)
       end
 
-      def code_evaluate(...)
-        raw.evaluate(...)
+      def self.call(**args)
+        code_operator = args.fetch(:operator, nil).to_code
+        globals = multi_fetch(args, *GLOBALS)
+
+        case code_operator.to_s
+        when "evaluate"
+          sig(args) { Object }
+          code_evaluate(*args.fetch(:arguments, []).to_code.raw, **globals)
+        else
+          super
+        end
+      end
+
+      def call(**args)
+        code_operator = args.fetch(:operator, nil).to_code
+        globals = multi_fetch(args, *GLOBALS)
+
+        case code_operator.to_s
+        when "evaluate"
+          sig(args)
+          code_evaluate(**globals)
+        else
+          super
+        end
+      end
+
+      def code_evaluate(trusted_evaluation: false, **globals)
+        raw.evaluate(
+          **evaluation_globals(globals, trusted_evaluation: trusted_evaluation)
+        )
+      end
+
+      def code_deep_duplicate(_seen = {})
+        self.class.new(raw)
+      end
+
+      private
+
+      def evaluation_globals(globals, trusted_evaluation:)
+        return globals if trusted && trusted_evaluation
+
+        object = ScopedObject.new
+
+        globals.merge(context: Context.new, object: object, root_object: object)
       end
     end
   end

data/lib/code/object/context.rb

@@ -3,13 +3,54 @@
 class Code
   class Object
     class Context < Dictionary
-      attr_reader :parent
+      CLASS_DOCUMENTATION = {
+        name: "Context",
+        description:
+          "stores scoped identifier values used while evaluating code.",
+        examples: [
+          "context",
+          "Context.new(a: 1)",
+          "Context.new({ a: 1 }, Context.new(b: 2)).lookup!(:b)"
+        ]
+      }.freeze
+      INSTANCE_FUNCTIONS = {
+        "lookup!" => {
+          name: "lookup!",
+          description:
+            "returns the context that defines an identifier or raises when it is missing.",
+          examples: [
+            "Context.new(a: 1).lookup!(:a)",
+            "Context.new({ a: 1 }, Context.new(b: 2)).lookup!(:b)",
+            "Context.new(a: 1).lookup!(:missing) rescue nothing"
+          ]
+        }
+      }.freeze
+
+      def self.function_documentation(scope)
+        return INSTANCE_FUNCTIONS if scope == :instance
+
+        {}
+      end
+
+      attr_accessor :parent
 
       def initialize(*args, **_kargs, &_block)
         super(args.first)
         @parent = args.second if args.second.is_a?(Dictionary)
       end
 
+      def call(**args)
+        code_operator = args.fetch(:operator, nil).to_code
+
+        case code_operator.to_s
+        when "lookup!"
+          sig(args) { Object }
+          code_lookup!(args.fetch(:arguments, []).to_code.code_first)
+        else
+          super
+        end
+      end
+
       def code_lookup!(identifier)
         code_identifier = identifier.to_code
 
@@ -26,6 +67,23 @@ class Code
         Context.new(raw.merge(other.raw), parent || other.parent)
       end
 
+      def code_deep_duplicate(seen = {})
+        seen.compare_by_identity unless seen.compare_by_identity?
+        return seen[self] if seen.key?(self)
+
+        duplicate = Context.new
+        seen[self] = duplicate
+
+        raw.each do |key, value|
+          duplicate.code_set(
+            key.code_deep_duplicate(seen),
+            value.code_deep_duplicate(seen)
+          )
+        end
+        duplicate.parent = parent&.code_deep_duplicate(seen)
+        duplicate
+      end
+
       def parent?
         !!parent
       end

data/lib/code/object/cryptography.rb

@@ -3,6 +3,75 @@
 class Code
   class Object
     class Cryptography < Object
+      CLASS_DOCUMENTATION = {
+        name: "Cryptography",
+        description:
+          "computes md5, sha1, sha256, sha384, and sha512 message digests in hex, digest, or base64 format.",
+        examples: [
+          "Cryptography.md5(:hello)",
+          "Cryptography.sha256(:hello, format: :hex)",
+          "Cryptography.sha512(:hello, format: :base64)"
+        ]
+      }.freeze
+      CLASS_FUNCTIONS = {
+        "md5" => {
+          name: "md5",
+          description:
+            "returns an md5 message digest as hex text by default, with digest and base64 formats available.",
+          examples: [
+            "Cryptography.md5(:hello)",
+            "Cryptography.md5(:hello, format: :hex)",
+            "Cryptography.md5(:hello, format: :base64)"
+          ]
+        },
+        "sha1" => {
+          name: "sha1",
+          description:
+            "returns a sha1 message digest as hex text by default, with digest and base64 formats available.",
+          examples: [
+            "Cryptography.sha1(:hello)",
+            "Cryptography.sha1(:hello, format: :hex)",
+            "Cryptography.sha1(:hello, format: :base64)"
+          ]
+        },
+        "sha256" => {
+          name: "sha256",
+          description:
+            "returns a sha256 message digest as hex text by default, with digest and base64 formats available.",
+          examples: [
+            "Cryptography.sha256(:hello)",
+            "Cryptography.sha256(:hello, format: :hex)",
+            "Cryptography.sha256(:hello, format: :base64)"
+          ]
+        },
+        "sha384" => {
+          name: "sha384",
+          description:
+            "returns a sha384 message digest as hex text by default, with digest and base64 formats available.",
+          examples: [
+            "Cryptography.sha384(:hello)",
+            "Cryptography.sha384(:hello, format: :hex)",
+            "Cryptography.sha384(:hello, format: :base64)"
+          ]
+        },
+        "sha512" => {
+          name: "sha512",
+          description:
+            "returns a sha512 message digest as hex text by default, with digest and base64 formats available.",
+          examples: [
+            "Cryptography.sha512(:hello)",
+            "Cryptography.sha512(:hello, format: :hex)",
+            "Cryptography.sha512(:hello, format: :base64)"
+          ]
+        }
+      }.freeze
+
+      def self.function_documentation(scope)
+        return CLASS_FUNCTIONS if scope == :class
+
+        {}
+      end
+
       def self.call(**args)
         code_operator = args.fetch(:operator, nil).to_code
         code_arguments = args.fetch(:arguments, []).to_code