File: Keywords.pod

package info (click to toggle)
libdancer2-perl 2.0.1-1
links: PTS, VCS
area: main
in suites: forky, sid
size: 2,768 kB
sloc: perl: 8,671; sql: 14; makefile: 8
file content (803 lines) | stat: -rw-r--r-- 21,346 bytes
# ABSTRACT: Dancer2 DSL Keyword Reference
package Dancer2::Manual::Keywords;

__END__

=pod

=encoding UTF-8

=head1 NAME

Dancer2::Manual::Keywords - Dancer2 DSL Keyword Reference

=head1 VERSION

version 2.0.1

=head1 Dancer2 Keyword Guide

This guide categorizes all Dancer2 keywords with descriptions, usage
guidance, and relationships with other keywords. Each entry links to the
relevant section in the L<Dancer2 Manual|Dancer2::Manual>.

=head1 Routing Keywords

=head2 L<any|Dancer2::Manual/"HTTP Methods: Visitor Actions">

Defines a route that responds to any HTTP method.

B<When to use>: Handle routes that accept multiple methods (e.g., C<GET>
and C<POST>).

B<Related Keywords>: All HTTP methods.

=head2 L<del|Dancer2::Manual/"HTTP Methods: Visitor Actions">

Defines a route that responds to HTTP C<DELETE> requests.

B<When to use>: Delete resources.

B<Related Keywords>: L</get>, L</post>, L</put>, L</patch>, L</options>, L</any>

=head2 L<get|Dancer2::Manual/get>

Defines a route that responds to HTTP C<GET> requests. Automatically
creates a C<HEAD> route.

B<When to use>: Fetch static resources or perform read-only actions.

B<Related Keywords>: L</post>, L</put>, L</del>, L</patch>, L</options>, L</any>

=head2 L<options|Dancer2::Manual/"HTTP Methods: Visitor Actions">

Defines a route that responds to HTTP C<OPTIONS> requests.

B<When to use>: Check available HTTP methods for a resource.

B<Related Keywords>: All HTTP methods.

=head2 L<patch|Dancer2::Manual/"HTTP Methods: Visitor Actions">

Defines a route that responds to HTTP C<PATCH> requests, often for partial
updates.

B<When to use>: Partially update existing resources.

B<Related Keywords>: L</get>, L</post>, L</put>, L</del>, L</options>, L</any>

=head2 L<post|Dancer2::Manual/post>

Defines a route that responds to HTTP C<POST> requests, typically for form
submissions or resource creation.

B<When to use>: Submit forms, upload files, or create resources.

B<Related Keywords>: L</get>, L</put>, L</del>, L</patch>, L</options>, L</any>

=head2 L<prefix|Dancer2::Manual/"Organizing routes and growing your app using prefix">

Defines a common path prefix for grouped routes.

B<When to use>: Organize routes logically under a shared prefix.

B<Related Keywords>: All HTTP methods.

=head2 L<put|Dancer2::Manual/"HTTP Methods: Visitor Actions">

Defines a route that responds to HTTP C<PUT> requests, often for updating
resources.

B<When to use>: Update existing resources in an idempotent way.

B<Related Keywords>: L</get>, L</post>, L</del>, L</patch>, L</options>, L</any>

=head2 L<splat|Dancer2::Manual/"Wildcard Route Parameters">

Retrieves a list value captured by a wildcard parameter in routes.

B<When to use>: Use with wildcard routes to capture arbitrary path segments.

B<Related Keywords>: L</captures>

=head1 URL and Route Helper Keywords

=head2 L<uri_for|Dancer2::Manual/uri_for>

Constructs a URI for a given path and query parameters.

B<When to use>: Generate URLs for links and redirects.

B<Related Keywords>: L</uri_for_route>

=head2 L<uri_for_route|Dancer2::Manual/uri_for_route>

Constructs a URI for a named route.

B<When to use>: Generate URLs based on route names and parameters.

B<Best Practice>: Use L</uri_for_route> with named routes to ensure
consistency even if route paths change.

B<Related Keywords>: L</uri_for>

=head1 Request Handling Keywords

=head2 L<body_parameters|Dancer2::Manual/body_parameters>

Retrieves parameters specifically from the request body.

B<When to use>: Handle C<POST> or C<PUT> data.

B<Related Keywords>: L</query_parameters>, L</route_parameters>, L</params>.

=head2 L<captures|Dancer2::Manual/"Regex Route Matching">

Accesses all regex capture groups from a route pattern.

B<When to use>: Extract parts of a URL matched by a regex route.

B<Related Keywords>: L</splat>

=head2 context

Deprecated. Use L</app> instead.

B<See also>: L</app>

=head2 L<param|Dancer2::Manual/"param and params (Not Recommended)">

Retrieves a parameter from the request (query, body, or route parameters).

B<When to use>: Not recommended. Use L</query_parameters>, L</body_parameters>,
or L</route_parameters> for clarity.

B<Best Practice>: Avoid using L</param> in new code to prevent confusion
between parameter sources. Instead, use more specific keywords.

B<Related Keywords>: L</params>, L</query_parameters>, L</body_parameters>, L</route_parameters>

=head2 L<params|Dancer2::Manual/"param and params (Not Recommended)">

Returns all parameters from the request as a hash reference.

B<When to use>: Retrieve all request parameters at once.

B<Best Practice>: Prefer specific keywords like L</query_parameters> for
clarity in code.

B<Related Keywords>: L</param>, L</query_parameters>, L</body_parameters>, L</route_parameters>

=head2 L<query_parameters|Dancer2::Manual/query_parameters>

Retrieves parameters specifically from the query string.

B<When to use>: Handle parameters in the query string (e.g., for searches).

B<Related Keywords>: L</body_parameters>, L</route_parameters>, L</params>

=head2 L<request|Dancer2::Core::Request>

Provides access to the current HTTP request object.

B<When to use>: Get details about the incoming request (headers, method,
path).

B<Related Keywords>: L</response>, L</params>, L</header>

=head2 request_data

Retrieves the raw data from the request body. If a serializer is set,
data will be automatically deserialized.

B<When to use>: Access the unprocessed body content of the request, especially
when dealing with custom or non-standard payloads.

B<Related Keywords>: L</request>, L</body_parameters>, L</params>

=head2 L<request_header|Dancer2::Manual/request_header>

Fetches the value of a specific header from the incoming request.

B<When to use>: Obtain information from request headers, such as 'User-Agent'
or 'Authorization'.

B<Related Keywords>: L</headers>, L</response_header>

=head2 L<route_parameters|Dancer2::Manual/route_parameters>

Retrieves parameters from the route pattern.

B<When to use>: Handle named or wildcard route parameters.

B<Related Keywords>: L</query_parameters>, L</body_parameters>, L</params>

=head2 L<upload|Dancer2::Manual/upload>

Uploads a file and makes it accessible as a L<Dancer2::Core::Request::Upload>
object.

If you named multiple files with the same name, C<upload> keyword returns
an array of L<Dancer2::Core::Request::Upload> objects:

    post '/some/route' => sub {
        my ($file1, $file2) = upload('files_input');
        # $file1 and $file2 are Dancer2::Core::Request::Upload objects
    };

You can also access the raw hashref of parsed uploads via the current request object:

    post '/some/route' => sub {
        my $all_uploads = request->uploads;
        # $all_uploads->{'file_input_foo'} is a Dancer2::Core::Request::Upload object
        # $all_uploads->{'files_input'} is an arrayref of Dancer2::Core::Request::Upload objects
    };

B<When to use>: To handle file uploads from client requests.

B<Related Keywords>: L</uploads>, L</request>

=head1 Response Handling Keywords

=head2 L<content|Dancer2::Manual/"content">

Sets the content of the response. This B<only> works within a delayed
response.

This will crash:

    get '/' => sub {
        content 'Hello, world!';
    };

But this will work just fine:

    get '/' => sub {
        delayed {
            content 'Hello, world!';
        };
    };

B<When to use>: Directly set content of an asynchronous response.

B<Related Keywords>: L</response>

=head2 L<content_type|Dancer2::Manual/"Manually Adjusting MIME Settings">

Sets the C<Content-Type> header of the response.

B<When to use>: Specify the MIME type of the response.

B<Related Keywords>: L</header>

=head2 L<decode_json|Dancer2::Manual/decode_json>

Deserializes a JSON string to a Perl data structure. Does not trigger
serialization hooks.

B<When to use>: When you need to translate incoming JSON to a Perl hashref.

B<Related Keywords>: L</encode_json>, L</from_json>

=head2 L<delayed|Dancer2::Manual/delayed>

Initiates an asynchronous response. Requires a Plack/PSGI server capable
of serving requests asynchronously.

B<When to use>: When starting an asynchronous reponse.

B<Related Keywords>: L</done>, L</flush>

=head2 L<done|Dancer2::Manual/done>

Finalizes an asynchronous repsonse and closes the connection. Can only
be run within the streaming response callback.

B<When to use>: When finishing delivery of data asynchronously.

B<See also>: L</delayed>, L</flush>

=head2 L<encode_json|Dancer2::Manual/encode_json>

Serializes a data structure to a UTF-8 encoded binary JSON string. Calling
this keyword will not trigger the application's serializer hooks.

B<When to use>: When needing to translate a Perl data structure to JSON.

B<See also>: L</decode_json>, L</to_json>

=head2 L<flush|Dancer2::Manual/flush>

Flushes content headers when streaming a response. This is necessary when
C<content> is called multiple times.

B<When to use>: When streaming large amounts of data (such as video)
asynchronously.

B<See also>: L</delayed>, L</done>

=head2 L<forward|Dancer2::Manual/forward>

Forwards the request to another route handler.

B<When to use>: Internally redirect to another route within the app.

B<Related Keywords>: L</pass>

=head2 L<from_dumper|Dancer2::Manual/from_dumper>

Deserializes a L<Data::Dumper> structure.

B<When to use>: When you need to turn a L<Data::Dumper> structure into a
Perl hashref.

B<See also>: L</to_dumper>, L</from_json>

=head2 L<from_json|Dancer2::Manual/from_json>

Deserializes a JSON string into a Perl data structure. Does not account
for UTF-8 characters.

B<When to use>: Decode JSON data from the client. L</decode_json> is likely
what you want.

B<Related Keywords>: L</to_json>

=head2 L<from_yaml|Dancer2::Manual/from_yaml>

Deserializes a YAML structure.

B<When to use>: When you need to turn YAML into a Perl hashref.

B<See also>: L</to_yaml>, L</from_json>

=head2 L<halt|Dancer2::Manual/halt>

Halts request processing and sends a response immediately.

B<When to use>: Stop processing and return a response early.

B<Best Practice>: Combine L</halt> with L</status> to ensure appropriate
HTTP response codes are sent.

B<Related Keywords>: L</status>, L</send_error>

=head2 C<header>

Deprecated. Use L</response_header> instead.

B<Related Keywords>: L</response_header>.

=head2 C<headers>

Deprecated. Use L</response_headers> instead.

B<Related Keywords>: L</response_headers>.

=head2 L<pass|Dancer2::Manual/pass>

Passes control to the next matching route.

B<When to use>: Skip the current route and try the next one.

B<Related Keywords>: L</forward>

=head2 C<push_header>

Deprecated. Use L</push_response_header> instead.

B<When to use>: Don't. Use L</push_response_header>.

B<Related Keywords>: L</push_response_header>.

=head2 L<push_response_header|Dancer2::Manual/"Adding Additional Response Headers">

Adds a new value to an existing response header without replacing its current value.

B<When to use>: Append additional values to headers like 'Set-Cookie' or 'X-Forwarded-For'.

B<See also>: L</response_header>, L</response_headers>

=head2 L<redirect|Dancer2::Manual/redirect>

Redirects the client to a different location.

B<When to use>: Redirect users to another route or external URL.

B<Related Keywords>: L</status>

=head2 L<response|Dancer2::Core::Response>

Provides access to the current response object.

B<When to use>: Manipulate the outgoing response (headers, status, content).

B<Related Keywords>: L</request>, L</header>, L</content>

=head2 L<response_header|Dancer2::Manual/"Adding Additional Response Headers">

Sets or retrieves a specific header in the outgoing response.

B<When to use>: Modify or access response headers before sending them to the client.

B<Related Keywords>: L</header>, L</response_headers>

=head2 L<response_headers|Dancer2::Manual/"Adding Additional Response Headers">

Returns a hash reference of all headers set in the response.

B<When to use>: Inspect or manipulate multiple response headers simultaneously.

B<Related Keywords>: L</response_header>, L</header>

=head2 L<send_as|Dancer2::Manual/send_as>

Manually serializes and sends the response in a specific format.

B<When to use>: Control response serialization explicitly.

B<Related Keywords>: C<encode_json>, C<decode_json>.

=head2 L<send_error|Dancer2::Manual/send_error>

Immediately halts processing and sends an error response with a specific
status code.

B<When to use>: To send a custom error response.

B<Related Keywords>: L</halt>, L</status>

=head2 L<send_file|Dancer2::Manual/"Sending Static Files from a Route Handler">

Sends a file to the client.

B<When to use>: Send files from disk or in-memory data as a file.

B<Related Keywords>: L</send_as>

=head2 L<status|Dancer2::Manual/status>

Sets the HTTP status code for the response.

B<When to use>: Specify response codes (e.g., 200, 404).

B<Best Practice>: Combine L</status> with L</halt> for clearer error handling
when sending error responses.

B<Related Keywords>: L</halt>, L</send_error>

=head2 L<to_dumper|Dancer2::Manual/to_dumper>

Serializes a Perl data structure into a string using Data::Dumper.

B<When to use>: Convert complex data structures into a readable string format for debugging.

B<Related Keywords>: L</from_dumper>, L</to_yaml>, L</to_json>

=head2 L<to_json|Dancer2::Manual/to_json>

Serializes a Perl data structure to JSON. Does not account or UTF-8
characters.

B<When to use>: Encode data to JSON format.

B<Related Keywords>: L</from_json>, L</send_as>

=head2 L<to_yaml|Dancer2::Manua/#to_yaml>

Serializes a Perl data structure into a YAML string.

B<When to use>: Convert data structures into YAML format.

B<Related Keywords>: L</from_yaml>, L</to_json>, L</to_dumper>

=head1 Session and Cookie Keywords

=head2 L<cookie|Dancer2::Manual/"Setting and Updating Cookies">

Retrieves the value of a specific cookie from the request.

B<When to use>: Access individual cookies.

B<Related Keywords>: L</cookies>, L</session>

=head2 L<cookies|Dancer2::Manual/"Retrieving Cookies">

Retrieves all cookies from the request as a hash reference.

B<When to use>: Inspect or manage multiple cookies.

B<Related Keywords>: L</cookie>

=head2 L<session|Dancer2::Manual/session>

Stores, retrieves, or removes data from the session.

B<When to use>: Persist user-specific data between requests.

B<Related Keywords>: L</cookie>, L</cookies>

=head1 Application Configuration Keywords

=head2 L<app|Dancer2::Manual/"Accessing the Application Object">

Returns an instance of the app. App is a L<Dancer2::Core::App>.

B<When to use>: When calling methods only available via the application object.

B<See also>: L</dancer_app>

=head2 L<config|Dancer2::Manual/config>

Retrieves the entire application configuration as a hash reference.

B<When to use>: Access or inspect all configuration settings.

B<Related Keywords>: L</set>, L</setting>

=head2 C<dancer_app>

Alias for L</app>.

B<Best Practice>: Use L</app> instead.

B<Related Keywords>: L</app>

=head2 L<dancer_version|Dancer2::Manual/dancer_version>

Retrieve full version number of installed Dancer2.

B<When to use>: To help manage compatability and feature usage in your
applications.

B<See also>: L</dancer_major_version>

=head2 L<dancer_major_version|Dancer2::Manual/dancer_major_version>

Retrieves major version number of Dancer2.

B<When to use>: To help manage compatability and feature usage in your
applications.

B<See also>: L</dancer_version>

=head2 L<prepare_app|Dancer2::Manual/prepare_app>

Function to help initialize and configure your Dancer2 app.

B<When to use>: When you need to run initialization or setup code once at
the start of your application.

B<See also>: L</to_app>

=head2 C<runner>

Provides access to the Dancer2 runner object, which manages the application's execution.

B<When to use>: Control or inspect the application's runtime environment.

B<Related Keywords>: L</app>, L</config>

=head2 L<set|Dancer2::Manual/set>

Sets a configuration value for the application.

B<When to use>: Change configuration dynamically at runtime.

B<Related Keywords>: L</setting>, L</config>

=head2 L<setting|Dancer2::Manual/setting>

Retrieves a configuration value.

B<When to use>: Access app configuration values.

B<Related Keywords>: L</set>, L</config>

=head2 C<start>

Initiates the Dancer2 application; typically called internally.

B<When to use>: Rarely used directly; see L</to_app> instead.

B<Related Keywords>: L</dance>, L</psgi_app>

=head2 L<var|Dancer2::Manual/var>

Sets a variable in the application context.

B<When to use>: Store temporary data accessible in routes and templates.

B<Related Keywords>: L</vars>

=head2 L<vars|Dancer2::Manual/vars>

Retrieves the application context variables.

B<When to use>: Access data stored with L</var>.

B<Related Keywords>: L</var>

=head1 Hooks

=head2 L<hook|Dancer2::Manual/Hooks>

Declares a hook to run custom code at specific stages in the request/response lifecycle.

B<When to use>: Modify requests or responses, or perform actions at predefined lifecycle points.

B<Related Keywords>: L</var>, L</vars>

=head1 Template Keywords

=head2 L<template|Dancer2::Manual/template>

Renders a view with the provided data.

B<When to use>: Generate HTML or other formats dynamically.

B<Related Keywords>: L</vars>

=head1 Logging Keywords

=head2 L<debug|Dancer2::Manual/debug>

Logs a message at the debug level.

B<When to use>: Detailed debugging and diagnostic messages.

B<Best Practice>: Use appropriate logging levels to maintain clear and actionable logs.

B<Related Keywords>: L</info>, L</warning>, L</error>, L</log>

=head2 L<error|Dancer2::Manual/error>

Logs a message at the error level.

B<When to use>: Log errors that need immediate attention.

B<Best Practice>: Use appropriate logging levels to maintain clear and actionable logs.

B<Related Keywords>: L</debug>, L</info>, L</warning>, L</log>

=head2 L<info|Dancer2::Manual/info>

Logs a message at the info level.

B<When to use>: General informational messages.

B<Best Practice>: Use appropriate logging levels to maintain clear and actionable logs.

B<Related Keywords>: L</debug>, L</warning>, L</error>, L</log>

=head2 L<log|Dancer2::Manual/log>

Logs a message at a specified level.

B<When to use>: Log messages with custom or dynamic levels.

B<Related Keywords>: L</debug>, L</info>, L</warning>, L</error>

=head2 L<logger|Dancer2::Manual/Logging>

Provides access to the logger object.

B<When to use>: Advanced logging scenarios.

B<Related Keywords>: L</log>, L</debug>, L</info>, L</warning>, L</error>

=head2 L<warning|Dancer2::Manual/warning>

Logs a message at the warning level.

B<When to use>: Logging non-critical issues that may need attention.

B<Best Practice>: Use appropriate logging levels to maintain clear and actionable logs.

B<Related Keywords>: L</debug>, L</info>, L</error>, L</log>

=head1 Miscellaneous Keywords

=head2 dance

Alias to the L<start> keyword.

B<Note>: This keyword has been superseded by L</to_app>.

B<Best Practice>: Use L</to_app> instead.

B<Related Keywords>: L</to_app>

=head2 dirname

Given a path, return the directory name.

B<When to use>: When you need to extract the directory name given a path.

B<See also>: L</path>

=head2 dsl

Provides access to the DSL (Domain Specific Language) object.

B<When to use>: When writing plugins or extending Dancer2's capabilities.

B<Related Keywords>: None.

=head2 engine

Given a namespace, return the current engine object. For example:

    my $template_engine = engine 'template';

B<When to use>: When you need to manually interact with one of the
underlying engines in Dancer2.

B<See also>: L</template>, L</session>, L</logger>

=head2 C<false>

Returns a false value.

B<When to use>: Explicitly return a false value in your application.

B<Related Keywords>: L</true>

=head2 mime

Provide access to your application's instance of L<Dancer2::Core::MIME>.

B<When to use>: When querying or changing your application's MIME settings.

B<See also>: L</send_file>

=head2 path

Concatenates multiple paths together without worrying about the underlying
operating system. It cleans the path aesthetically, but does not verify its
existence.

B<When to use>: When you need to generate a filesystem path within your
application.

B<See also>: L</dirname>

=head2 psgi_app

Provides the same functionality as L</to_app>, but uses the deprecated
Dispatcher engine.

B<Note>: This keyword has been superseded by L</to_app>.

B<Best Practice>: Use L</to_app> instead.

B<See also>: L<to_app|#to_app>.

=head2 L<to_app|Dancer2::Manual/to_app>

Returns the PSGI application code reference for the current Dancer2 app.

B<When to use>: Integrate the Dancer2 application with other PSGI-compatible frameworks or servers.

B<Related Keywords>: L</psgi_app>, L</dance>

=head2 C<true>

Returns a true value.

B<When to use>: Explicitly return a true value in your application.

B<Related Keywords>: L</false>

=head1 AUTHOR

Dancer Core Developers

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Alexis Sukrieh.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut