line-message-builder 0.8.0 → 0.10.0

data/lib/line/message/builder/base.rb

@@ -3,53 +3,49 @@
 module Line
   module Message
     module Builder
-      # The `Base` class serves as the foundation for all message builder classes
-      # within the `Line::Message::Builder` DSL. It provides core functionality
+      # The Base class serves as the foundation for all message builder classes
+      # within the Line::Message::Builder DSL. It provides core functionality
       # for defining options, handling initialization, and delegating method calls
       # to a context object.
       #
       # This class is not typically used directly but is inherited by specific
-      # message type builders (e.g., `Text`, `Flex`).
+      # message type builders (e.g., Text, Flex::Builder).
       class Base
         class << self
-          # @!visibility private
-          # @!parse extend ClassMethods
-          def inherited(subclass)
+          def inherited(subclass) # :nodoc:
             super
             subclass.extend ClassMethods
           end
         end
 
-        # The `ClassMethods` module is automatically extended by any class that
-        # inherits from {Base}. It provides class-level methods for defining
+        # The ClassMethods module is automatically extended by any class that
+        # inherits from Base. It provides class-level methods for defining
         # DSL options and configurations.
         module ClassMethods
-          # Returns an array of option names that have been defined for this class
-          # using the {option} method.
-          #
-          # @return [Array<Symbol>] A list of defined option names.
-          # @!visibility private
-          def options
+          def options # :nodoc:
             @options ||= []
           end
 
           # Defines a new option for the builder class.
+          #
           # This method dynamically creates an instance method on the builder class
-          # with the given `name`. When this instance method is called:
+          # with the given name. When this instance method is called:
           # - Without arguments, it returns the current value of the option, or
-          #   the `default` value if not set.
-          # - With an argument, it sets the value of the option. If a `validator`
+          #   the default value if not set.
+          # - With an argument, it sets the value of the option. If a validator
           #   is provided, the value is validated before being set.
           #
-          # @param name [Symbol] The name of the option to define. This will also
-          #   be the name of the generated instance method.
-          # @param default [Object, nil] The default value for the option if not
-          #   explicitly set.
-          # @param validator [#valid!?, nil] An optional validator object that must
-          #   respond to `valid!(value)`. If the value is invalid, the validator
-          #   should raise an error (typically a {ValidationError}).
-          # @return [void]
-          # @example
+          # [name]
+          #   The name of the option to define. This will also be the name of the
+          #   generated instance method.
+          # [default]
+          #   The default value for the option if not explicitly set.
+          # [validator]
+          #   An optional validator object that must respond to +valid!+ method.
+          #   If the value is invalid, the validator should raise an error.
+          #
+          # == Example
+          #
           #   class MyBuilder < Base
           #     option :color, default: "red"
           #     option :size, validator: SizeValidator.new
@@ -74,24 +70,39 @@ module Line
           end
         end
 
+        # The context object used for method delegation.
+        #
+        # When methods are called on the builder that it doesn't respond to,
+        # they are delegated to this context object if it responds to them.
+        # This allows accessing helper methods and variables from the surrounding
+        # environment within the builder DSL.
         attr_reader :context
 
         # Initializes a new instance of a builder class.
         #
-        # @param context [Object, nil] An optional external context object.
-        #   Methods not defined in the builder will be delegated to this context
-        #   if it responds to them. This allows for using helper methods or
-        #   accessing data from the surrounding environment within the builder DSL.
-        # @param options [Hash] A hash of options to set on the builder instance.
-        #   These options are typically defined using the {ClassMethods.option .option}
-        #   method in the builder class.
-        # @param block [Proc, nil] An optional block that is instance-eval'd
-        #   within the new builder instance. This is the primary way the DSL
-        #   is used to define message content.
+        # [context]
+        #   An optional external context object. Methods not defined in the builder
+        #   will be delegated to this context if it responds to them. This allows
+        #   for using helper methods or accessing data from the surrounding environment
+        #   within the builder DSL.
+        # [options]
+        #   A hash of options to set on the builder instance. These options are
+        #   typically defined using the +option+ method in the builder class.
+        # [block]
+        #   An optional block that is instance-eval'd within the new builder instance.
+        #   This is the primary way the DSL is used to define message content.
+        #
+        # == Example
+        #
+        #   builder = MyBuilder.new(context: view_context) do
+        #     text "Hello from context"
+        #   end
         def initialize(context: nil, **options, &block)
           @context = context
           @quick_reply = nil
 
+          validate_options!(options)
+
           self.class.options.each do |option|
             send(option, options[option]) if options.key?(option)
           end
@@ -100,15 +111,17 @@ module Line
         end
 
         # Defines a quick reply for the message.
+        #
         # A quick reply consists of a set of buttons that are displayed along
         # with the message, allowing users to make quick responses.
         #
-        # The provided block is executed in the context of a new {QuickReply}
+        # The provided block is executed in the context of a new QuickReply
         # instance, where you can define the quick reply buttons.
         #
-        # @yield [quick_reply] The block is yielded with a {QuickReply} instance.
-        # @return [QuickReply] The created {QuickReply} object.
-        # @example
+        # :yields: quick_reply
+        #
+        # == Example
+        #
         #   text_message do
         #     text "Please choose an option:"
         #     quick_reply do
@@ -120,34 +133,11 @@ module Line
           @quick_reply = QuickReply.new(context: context, &)
         end
 
-        # Determines if the builder can respond to a given method, including
-        # checking if the context object can respond to it.
-        # This is part of Ruby's mechanism for `method_missing` and is used
-        # here to enable delegation to the `context` object.
-        #
-        # @param method_name [Symbol] The name of the method.
-        # @param include_private [Boolean] Whether to include private methods
-        #   in the search.
-        # @return [Boolean] `true` if the builder or its context can respond to
-        #   the method, `false` otherwise.
-        # @!visibility private
-        def respond_to_missing?(method_name, include_private = false)
+        def respond_to_missing?(method_name, include_private = false) # :nodoc:
           context.respond_to?(method_name, include_private) || super
         end
 
-        # Handles calls to undefined methods by attempting to delegate them to the
-        # `context` object. If the `context` object responds to the method,
-        # it is called. Otherwise, it behaves like the standard `method_missing`.
-        # This allows the DSL to feel more integrated with the surrounding code
-        # by making methods from the `context` directly available within the
-        # builder block.
-        #
-        # @param method_name [Symbol] The name of the missing method.
-        # @param ... [Object] Arguments passed to the method.
-        # @raise [NoMethodError] If neither the builder nor the context can
-        #   handle the method call.
-        # @!visibility private
-        def method_missing(method_name, ...)
+        def method_missing(method_name, ...) # :nodoc:
           if context.respond_to?(method_name)
             context.public_send(method_name, ...)
           else
@@ -155,6 +145,20 @@ module Line
           end
         end
 
+        # Converts the builder to a hash representation.
+        #
+        # The format of the hash depends on the mode (API or SDK v2) determined
+        # by the builder's configuration. Subclasses must implement +to_api+ and
+        # +to_sdkv2+ methods to provide the actual conversion logic.
+        #
+        # [return]
+        #   A hash representation of the message in the appropriate format.
+        #
+        # == Example
+        #
+        #   builder = Text.new { text "Hello" }
+        #   builder.to_h
+        #   # => { type: "text", text: "Hello" }
         def to_h
           return to_sdkv2 if sdkv2?
 
@@ -163,11 +167,32 @@ module Line
 
         private
 
-        def to_api
+        # Rejects options the builder does not declare.
+        #
+        # An undeclared option is almost always a typo or a property the LINE API
+        # spells differently. Ignoring it produces a message that is silently
+        # missing the styling that was asked for, which nothing downstream can
+        # detect, so it is refused here instead.
+        #
+        # [options]
+        #   The hash of options passed to the constructor
+        #
+        # Raises ValidationError listing the unknown option and the ones this
+        # builder accepts.
+        def validate_options!(options) # :nodoc:
+          unknown = options.keys - self.class.options
+          return if unknown.empty?
+
+          raise ValidationError,
+                "Unknown option: #{unknown.join(", ")} for #{self.class}. " \
+                "Allowed options are: #{self.class.options.join(", ")}"
+        end
+
+        def to_api # :nodoc:
           raise NotImplementedError, "#{self.class} must implement #to_api"
         end
 
-        def to_sdkv2
+        def to_sdkv2 # :nodoc:
           raise NotImplementedError, "#{self.class} must implement #to_sdkv2"
         end
       end

data/lib/line/message/builder/container.rb

@@ -3,53 +3,58 @@
 module Line
   module Message
     module Builder
-      # The `Container` class is the top-level entry point for constructing a batch
+      # The +Container+ class is the top-level entry point for constructing a batch
       # of LINE messages using the builder DSL. It acts as a holder for one or
-      # more individual message objects (such as {Text} or {Flex} messages).
+      # more individual message objects (such as Text or Flex messages).
       #
-      # When you use `Line::Message::Builder.with {}`, you are operating within
-      # the context of a `Container` instance. This container allows you to define
+      # When you use <code>Line::Message::Builder.with {}</code>, you are operating within
+      # the context of a +Container+ instance. This container allows you to define
       # multiple messages that can be sent together in a single API call to LINE,
       # although the LINE API typically expects an array of message objects,
       # which this container helps to build.
       #
       # Each message added to the container can also have its own quick reply.
       #
-      # @example Building multiple messages
-      #   message_payload = Line::Message::Builder.with do |root|
-      #     root.text "Hello, this is the first message!"
-      #     root.flex alt_text: "This is a Flex Message" do |flex_builder|
-      #       flex_builder.bubble do |bubble|
-      #         bubble.body do |body|
+      # == Example
+      #
+      #   message_payload = Line::Message::Builder.with do
+      #     text "Hello, this is the first message!"
+      #     flex alt_text: "This is a Flex Message" do
+      #       bubble do
+      #         body do
       #           body.text "This is a Flex Message body."
       #         end
       #       end
       #     end
       #   end.build # => Returns an array of message hashes
       #
-      # @see Base
-      # @see Text
-      # @see Flex::Builder
-      # @see QuickReply
+      # See also:
+      # - Base
+      # - Text
+      # - Flex::Builder
+      # - QuickReply
       class Container
-        # @!attribute [r] context
-        #   @return [Context] The context object, which can hold external data or
-        #     helper methods accessible within the builder blocks.
+        # [return]
+        #   The context object, which can hold external data or
+        #   helper methods accessible within the builder blocks.
         attr_reader :context
 
         # Initializes a new message container.
-        # This is typically not called directly but through `Line::Message::Builder.with`.
+        # This is typically not called directly but through <code>Line::Message::Builder.with</code>.
         # The provided block is instance-eval'd, allowing DSL methods like
-        # {#text} and {#flex} to be called directly on the container instance.
+        # #text and #flex to be called directly on the container instance.
         #
-        # @param context [Object, nil] An optional context object that can be used
+        # [context]
+        #   An optional context object that can be used
         #   to share data or helper methods within the builder block. It's wrapped
-        #   in a {Context} object.
-        # @param mode [Symbol] The mode to use for building messages. Can be either
-        #   `:api` (default) for direct LINE Messaging API format or `:sdkv2` for
+        #   in a Context object.
+        # [mode]
+        #   The mode to use for building messages. Can be either
+        #   <code>:api</code> (default) for direct LINE Messaging API format or <code>:sdkv2</code> for
         #   LINE Bot SDK v2 compatible format.
-        # @param block [Proc] A block containing DSL calls to define messages
-        #   (e.g., `text "Hello"`, `flex { ... }`).
+        # [block]
+        #   A block containing DSL calls to define messages
+        #   (e.g., <code>text "Hello"</code>, <code>flex { ... }</code>).
         def initialize(context: nil, mode: :api, &block)
           @messages = [] # Initializes an empty array to store message objects
           @context = Context.new(context, mode:)
@@ -57,17 +62,20 @@ module Line
           instance_eval(&block) if ::Kernel.block_given?
         end
 
-        # Creates a new {Text} message and adds it to this container.
+        # Creates a new Text message and adds it to this container.
         #
-        # @param text [String] The text content of the message.
-        # @param options [Hash] Additional options for the text message,
-        #   such as `:quick_reply`. See {Text#initialize}.
-        # @param block [Proc, nil] An optional block that will be instance-eval'd
-        #   in the context of the new {Text} message instance. This can be used
+        # [text]
+        #   The text content of the message.
+        # [option]
+        #   Additional options for the text message,
+        #   such as <code>:quick_reply</code>. See Text#initialize.
+        # [block]
+        #   An optional block that will be instance-eval'd
+        #   in the context of the new Text message instance. This can be used
         #   to add a quick reply to the text message.
-        # @return [Text] The newly created {Text} message object.
         #
-        # @example
+        # == Example
+        #
         #   root.text "Hello, world!" do
         #     quick_reply do
         #       button action: :message, label: "Hi!", text: "Hi!"
@@ -77,24 +85,27 @@ module Line
           @messages << Text.new(text, context: context, **options, &)
         end
 
-        # Creates a new {Flex::Builder} for constructing a Flex Message and adds it
+        # Creates a new Flex::Builder for constructing a Flex Message and adds it
         # to this container. The block is mandatory and is used to define the
         # content of the Flex Message using the Flex Message DSL.
         #
-        # @param options [Hash] Options for the Flex Message, primarily `:alt_text`.
-        #   See {Flex::Builder#initialize}. It's important to provide `alt_text`.
-        # @param block [Proc] A block that will be instance-eval'd in the context
-        #   of the new {Flex::Builder} instance. This block is used to define the
+        # [option]
+        #   Options for the Flex Message, primarily <code>:alt_text</code>.
+        #   See Flex::Builder#initialize. It's important to provide +alt_text+.
+        # [block]
+        #   A block that will be instance-eval'd in the context
+        #   of the new Flex::Builder instance. This block is used to define the
         #   structure and content of the Flex Message (e.g., bubbles, carousels).
-        # @return [Flex::Builder] The newly created {Flex::Builder} object.
-        # @raise [ArgumentError] if `alt_text` is not provided in options (validation
-        #   is typically within Flex::Builder).
         #
-        # @example
-        #   root.flex alt_text: "Important information" do |fb|
-        #     fb.bubble do |bubble|
-        #       bubble.header { |h| h.text "Header" }
-        #       bubble.body   { |b| b.text "Body" }
+        # Raises ArgumentError if +alt_text+ is not provided in options (validation
+        # is typically within Flex::Builder).
+        #
+        # == Example
+        #
+        #   flex alt_text: "Important information" do
+        #     bubble do
+        #       header { text "Header" }
+        #       body   { text "Body" }
         #     end
         #   end
         def flex(**options, &)
@@ -102,47 +113,31 @@ module Line
         end
 
         # Converts all messages held by this container into their hash representations.
-        # This method iterates over each message object (e.g., {Text}, {Flex::Builder})
-        # stored in the container and calls its `to_h` method. The result is an
+        # This method iterates over each message object (e.g., Text, Flex::Builder)
+        # stored in the container and calls its +to_h+ method. The result is an
         # array of hashes, where each hash represents a single LINE message object
         # ready for JSON serialization and sending to the LINE Messaging API.
-        #
-        # @return [Array<Hash>] An array of message objects, each represented as a hash.
-        #   This is the format expected by the LINE API for the `messages` field
-        #   in a request body.
         def build
           @messages.map(&:to_h)
         end
 
-        # Converts the array of message hashes (obtained from {#build}) into a
+        # Converts the array of message hashes (obtained from #build) into a
         # JSON string. This is a convenience method for serializing the messages
         # payload.
         #
-        # @param args [Object] Optional arguments that are passed along to `to_json`
+        # [arg]
+        #   Optional arguments that are passed along to +to_json+
         #   method of the underlying array.
-        # @return [String] A JSON string representing the array of message objects.
         def to_json(*args)
           build.to_json(*args)
         end
 
-        # Checks if a method is defined in the context object.
-        # This is part of Ruby's method_missing mechanism.
-        #
-        # @param method_name [Symbol] The name of the method being checked
-        # @param include_private [Boolean] Whether to include private methods
-        # @return [Boolean] True if the method exists in the context, false otherwise
+        # :nodoc:
         def respond_to_missing?(method_name, include_private = false)
           context.respond_to?(method_name, include_private) || super
         end
 
-        # Delegates method calls to the context object if they exist there.
-        # This allows helper methods defined in the context to be called directly
-        # from within the builder DSL.
-        #
-        # @param method_name [Symbol] The name of the method being called
-        # @param args [Array] The arguments passed to the method
-        # @return [Object] The result of calling the method on the context
-        # @raise [NoMethodError] If the method doesn't exist in the context
+        # :nodoc:
         def method_missing(method_name, ...)
           return context.send(method_name, ...) if context.respond_to?(method_name)
 

data/lib/line/message/builder/context.rb

@@ -3,120 +3,93 @@
 module Line
   module Message
     module Builder
-      # The `Context` class is a crucial component of the `Line::Message::Builder`
+      # The Context class is a crucial component of the Line::Message::Builder
       # DSL, enabling a flexible and dynamic environment for message construction.
       # It acts as a wrapper around an optional user-provided context object and
-      # manages a separate hash of "assigns" (local variables for the DSL).
+      # manages a separate hash of +assigns+ (local variables for the DSL).
       #
-      # The primary purposes of the `Context` are:
-      # 1.  **To provide access to helper methods**: If a user passes a context object
+      # The primary purposes of the Context are:
+      # 1.  To provide access to helper methods: If a user passes a context object
       #     (e.g., a Rails view context, a presenter, or any custom object) during
-      #     builder initialization (`Line::Message::Builder.with(my_helper_object)`),
-      #     methods defined on `my_helper_object` become directly callable within
-      #     the DSL blocks.
-      # 2.  **To allow local data storage (`assigns`)**: The `assigns` hash allows
-      #     for setting and retrieving temporary data that can be shared across
-      #     different parts of a complex message construction block, without needing
-      #     to pass it explicitly or pollute the user-provided context.
+      #     builder initialization, methods defined on that object become directly
+      #     callable within the DSL blocks.
+      # 2.  To allow local data storage: The +assigns+ hash allows for setting and
+      #     retrieving temporary data that can be shared across different parts of
+      #     a complex message construction block, without needing to pass it
+      #     explicitly or pollute the user-provided context.
       #
       # Method calls within the DSL that are not defined on the builder objects
-      # themselves are resolved by `Context` in the following order:
-      # - First, it checks if the method name corresponds to a key in the `assigns` hash.
-      # - If not found in `assigns`, it checks if the wrapped user-context object
+      # themselves are resolved by Context in the following order:
+      # - First, it checks if the method name corresponds to a key in the +assigns+ hash.
+      # - If not found in +assigns+, it checks if the wrapped user-context object
       #   responds to the method.
       # - If neither, the call proceeds up the normal Ruby method lookup chain.
       #
       # This mechanism allows for a clean and powerful way to integrate external logic
       # and data into the message building process.
       #
-      # @example Using a custom context
-      #   class MyHelpers
+      # == Example: Using a custom context
+      #
+      #   class MyContext
       #     def current_user_name
       #       "Alice"
       #     end
       #   end
       #
-      #   helpers = MyHelpers.new
-      #   Line::Message::Builder.with(helpers) do |root|
-      #     # `current_user_name` is resolved from `helpers` by Context
-      #     root.text "Hello, #{current_user_name}!"
-      #
-      #     # Using assigns
-      #     assigns[:item_count] = 5
-      #     root.text "You have #{assigns[:item_count]} items."
+      #   context = MyContext.new
+      #   Line::Message::Builder.with(context) do
+      #     # current_user_name is resolved from context by Context
+      #     text "Hello, #{current_user_name}!"
       #   end
       class Context
-        # @!attribute assigns
-        #   A hash for storing arbitrary data that can be accessed within the
-        #   builder DSL. This is useful for temporary variables or shared state
-        #   during message construction.
-        #   @return [Hash] The hash of assigned values.
-        #   @example
-        #     context.assigns[:user_id] = 123
-        #     puts context.assigns[:user_id] # => 123
+        # A hash for storing arbitrary data that can be accessed within the
+        # builder DSL. This is useful for temporary variables or shared state
+        # during message construction.
+        #
+        # == Example
+        #
+        #   context.assigns[:user_id] = 123
+        #   puts context.assigns[:user_id] # => 123
         attr_accessor :assigns
 
-        # @!attribute [r] mode
-        #   The mode in which the builder is operating. This affects how messages
-        #   are formatted in the final output.
-        #   @return [Symbol] Either `:api` for direct LINE Messaging API format
-        #     or `:sdkv2` for LINE Bot SDK v2 compatible format.
+        # The mode in which the builder is operating. This affects how messages
+        # are formatted in the final output. Either +:api+ for direct LINE
+        # Messaging API format or +:sdkv2+ for LINE Bot SDK v2 compatible format.
         attr_reader :mode
 
         # Initializes a new Context object.
         #
-        # @param context [Object, nil] An optional object whose methods will be made
-        #   available within the DSL. If `nil`, only `assigns` and standard
-        #   builder methods will be available.
-        # @param mode [Symbol] The mode of the context, which can be `:api` (default)
-        #   for direct LINE Messaging API format or `:sdkv2` for LINE Bot SDK v2
-        #   compatible format.
+        # [context]
+        #   An optional object whose methods will be made available within the DSL.
+        #   If +nil+, only +assigns+ and standard builder methods will be available.
+        # [mode]
+        #   The mode of the context, which can be +:api+ (default) for direct LINE
+        #   Messaging API format or +:sdkv2+ for LINE Bot SDK v2 compatible format.
+        #
+        # == Example
+        #
+        #   # With a custom context object
+        #   my_context = MyHelpers.new
+        #   context = Line::Message::Builder::Context.new(my_context, mode: :api)
+        #
+        # === Example: Without context
+        #
+        #   # Without context, using only assigns
+        #   context = Line::Message::Builder::Context.new(nil)
+        #   context.assigns[:user_name] = "Alice"
         def initialize(context, mode: :api)
           @context = context
           @assigns = {}
           @mode = mode
         end
 
-        # Part of Ruby's dynamic method dispatch. It's overridden here to declare
-        # that instances of `Context` can respond to methods that are either:
-        # 1. Keys in the `@assigns` hash.
-        # 2. Methods to which the wrapped `@context` object responds.
-        #
-        # This ensures that `respond_to?` behaves consistently with how
-        # `method_missing` resolves method calls.
-        #
-        # @param method_name [Symbol] The name of the method being queried.
-        # @param include_private [Boolean] Whether to include private methods in
-        #   the check.
-        # @return [Boolean] `true` if the context can handle the method,
-        #   `false` otherwise.
-        # @!visibility private
-        def respond_to_missing?(method_name, include_private = false)
+        def respond_to_missing?(method_name, include_private = false) # :nodoc:
           @assigns.key?(method_name) ||
             @context.respond_to?(method_name, include_private) || # Check @context directly
             super
         end
 
-        # Handles calls to methods not explicitly defined on the `Context` class.
-        # The resolution order is:
-        # 1.  If `method_name` is a key in the `@assigns` hash, its value is returned.
-        # 2.  If the wrapped `@context` object responds to `method_name`, the call
-        #     is delegated to `@context`.
-        # 3.  Otherwise, `super` is called, allowing the standard Ruby method
-        #     lookup to continue (which will likely result in a `NoMethodError`
-        #     if the method is truly undefined).
-        #
-        # This is the core mechanism that allows DSL blocks to seamlessly access
-        # data from `assigns` or methods from the user-provided context.
-        #
-        # @param method_name [Symbol] The name of the invoked method.
-        # @param ... [Object] Arguments passed to the method.
-        # @return [Object, nil] The value from `@assigns`, the result of the
-        #   delegated call to `@context`, or raises `NoMethodError` via `super`.
-        # @raise [NoMethodError] If the method is not found in `assigns` or
-        #   on the wrapped context.
-        # @!visibility private
-        def method_missing(method_name, ...)
+        def method_missing(method_name, ...) # :nodoc:
           return @assigns[method_name] if @assigns.key?(method_name)
           # Check @context directly
           return @context.public_send(method_name, ...) if @context.respond_to?(method_name)
@@ -126,8 +99,10 @@ module Line
 
         # Checks if the current mode is set to SDK v2 compatibility.
         #
-        # @return [Boolean] `true` if the mode is `:sdkv2`, `false` otherwise.
-        # @example
+        # Returns +true+ if the mode is +:sdkv2+, +false+ otherwise.
+        #
+        # == Example
+        #
         #   if context.sdkv2?
         #     # Format message for LINE Bot SDK v2
         #   else