line-message-builder 0.9.0 → 0.10.0

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

@@ -3,19 +3,20 @@
 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
+      # == Example
+      #
       #   message_payload = Line::Message::Builder.with do
       #     text "Hello, this is the first message!"
       #     flex alt_text: "This is a Flex Message" do
@@ -27,29 +28,33 @@ module Line
       #     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,20 +85,23 @@ 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
+        # 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" }
@@ -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,33 +3,33 @@
 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
+      # == Example: Using a custom context
+      #
       #   class MyContext
       #     def current_user_name
       #       "Alice"
@@ -38,81 +38,58 @@ module Line
       #
       #   context = MyContext.new
       #   Line::Message::Builder.with(context) do
-      #     # `current_user_name` is resolved from `context` by Context
+      #     # 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)
@@ -122,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

data/lib/line/message/builder/flex/actionable.rb

@@ -4,64 +4,85 @@ module Line
   module Message
     module Builder
       module Flex
-        # The `Actionable` module provides a DSL for defining an action that can be
+        # The Actionable module provides a DSL for defining an action that can be
         # triggered when a user interacts with certain Flex Message components
-        # (e.g., a {Button} component, or an entire {Bubble} or {Box} component
+        # (e.g., a Button component, or an entire Bubble or Box component
         # if it's made tappable).
         #
-        # When a component includes this module, it gains methods like {#message}
-        # and {#postback} to associate a specific LINE action with itself. The
-        # chosen action is stored in the `action` attribute.
+        # When a component includes this module, it gains methods like +message+,
+        # +postback+ and +uri+ to associate a specific LINE action with itself.
+        # The chosen action is stored in the +action+ attribute.
         #
-        # @!attribute [r] action
-        #   @return [Actions::Message, Actions::Postback, nil] The action object
-        #     associated with this component. `nil` if no action is defined.
+        # == Attributes
         #
-        # @see Line::Message::Builder::Actions::Message
-        # @see Line::Message::Builder::Actions::Postback
-        # @see https://developers.line.biz/en/reference/messaging-api/#action-objects
+        # The following attribute is automatically added to classes that include
+        # this module:
+        #
+        # [action]
+        #   The action object associated with this component. Returns an
+        #   Actions::Message, Actions::Postback, or +nil+ if no action is defined.
+        #
+        # See also:
+        # - Line::Message::Builder::Actions::Message
+        # - Line::Message::Builder::Actions::Postback
+        # - Line::Message::Builder::Actions::Uri
+        # - https://developers.line.biz/en/reference/messaging-api/#action-objects
         module Actionable
-          # @!visibility private
-          # Automatically adds an `attr_reader :action` to the class that includes
-          # this module.
-          # @param base [Class] The class including this module.
-          def self.included(base)
+          def self.included(base) # :nodoc:
             base.attr_reader :action
           end
 
           # Defines a message action for the component.
-          # When the component is tapped, a message with the given `text` is sent
+          # When the component is tapped, a message with the given text is sent
           # from the user to the chat.
           #
-          # @param text [String] The text of the message to send.
-          # @param options [Hash] Additional options for the message action,
-          #   such as `:label`. See {Actions::Message#initialize}.
-          # @param block [Proc, nil] An optional block, though not typically used
-          #   directly for message actions here.
-          # @return [Actions::Message] The created message action object.
+          # [text]
+          #   The text of the message to send
+          # [options]
+          #   Additional options for the message action, such as +:label+.
+          #   See Actions::Message
+          #
+          # == Example
           #
-          # @example Setting a message action on a button
           #   button_component.message "Hello User!", label: "Send Greeting"
           def message(text, **options, &)
             @action = Actions::Message.new(text, context: context, **options, &)
           end
 
           # Defines a postback action for the component.
-          # When the component is tapped, a postback event with the given `data`
+          # When the component is tapped, a postback event with the given data
           # is sent to the bot's webhook.
           #
-          # @param data [String] The data payload for the postback event.
-          # @param options [Hash] Additional options for the postback action,
-          #   such as `:label` or `:display_text`. See {Actions::Postback#initialize}.
-          # @param block [Proc, nil] An optional block, though not typically used
-          #   directly for postback actions here.
-          # @return [Actions::Postback] The created postback action object.
+          # [data]
+          #   The data payload for the postback event
+          # [options]
+          #   Additional options for the postback action, such as +:label+ or
+          #   +:display_text+. See Actions::Postback
+          #
+          # == Example
           #
-          # @example Setting a postback action on a button
           #   button_component.postback "action=buy&item_id=123", label: "Buy Item"
           def postback(data, **options, &)
             @action = Actions::Postback.new(data, context: context, **options, &)
           end
+
+          # Defines a URI action for the component.
+          # When the component is tapped, the given URI is opened. No webhook
+          # handling is needed, which makes this the action to use for linking
+          # a component to a web page.
+          #
+          # [uri]
+          #   The URI to open. Schemes +http+, +https+, +line+ and +tel+
+          # [options]
+          #   Additional options for the URI action, such as +:label+ or
+          #   +:alt_uri_desktop+. See Actions::Uri
+          #
+          # == Example
+          #
+          #   button_component.uri "https://example.com", label: "Learn more"
+          def uri(uri, **options, &)
+            @action = Actions::Uri.new(uri, context: context, **options, &)
+          end
         end
       end
     end