NAME

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

VERSION

version 2.0.0

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 Dancer2 Manual.

Routing Keywords

any

Defines a route that responds to any HTTP method.

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

Related Keywords: All HTTP methods.

del

Defines a route that responds to HTTP DELETE requests.

When to use: Delete resources.

Related Keywords: "get", "post", "put", "patch", "options", "any"

get

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

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

Related Keywords: "post", "put", "del", "patch", "options", "any"

options

Defines a route that responds to HTTP OPTIONS requests.

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

Related Keywords: All HTTP methods.

patch

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

When to use: Partially update existing resources.

Related Keywords: "get", "post", "put", "del", "options", "any"

post

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

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

Related Keywords: "get", "put", "del", "patch", "options", "any"

prefix

Defines a common path prefix for grouped routes.

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

Related Keywords: All HTTP methods.

put

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

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

Related Keywords: "get", "post", "del", "patch", "options", "any"

splat

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

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

Related Keywords: "captures"

URL and Route Helper Keywords

uri_for

Constructs a URI for a given path and query parameters.

When to use: Generate URLs for links and redirects.

Related Keywords: "uri_for_route"

uri_for_route

Constructs a URI for a named route.

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

Best Practice: Use "uri_for_route" with named routes to ensure consistency even if route paths change.

Related Keywords: "uri_for"

Request Handling Keywords

body_parameters

Retrieves parameters specifically from the request body.

When to use: Handle POST or PUT data.

Related Keywords: "query_parameters", "route_parameters", "params".

captures

Accesses all regex capture groups from a route pattern.

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

Related Keywords: "splat"

context

Deprecated. Use "app" instead.

See also: "app"

param

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

When to use: Not recommended. Use "query_parameters", "body_parameters", or "route_parameters" for clarity.

Best Practice: Avoid using "param" in new code to prevent confusion between parameter sources. Instead, use more specific keywords.

Related Keywords: "params", "query_parameters", "body_parameters", "route_parameters"

params

Returns all parameters from the request as a hash reference.

When to use: Retrieve all request parameters at once.

Best Practice: Prefer specific keywords like "query_parameters" for clarity in code.

Related Keywords: "param", "query_parameters", "body_parameters", "route_parameters"

query_parameters

Retrieves parameters specifically from the query string.

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

Related Keywords: "body_parameters", "route_parameters", "params"

request

Provides access to the current HTTP request object.

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

Related Keywords: "response", "params", "header"

request_data

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

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

Related Keywords: "request", "body_parameters", "params"

request_header

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

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

Related Keywords: "headers", "response_header"

route_parameters

Retrieves parameters from the route pattern.

When to use: Handle named or wildcard route parameters.

Related Keywords: "query_parameters", "body_parameters", "params"

upload

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

If you named multiple files with the same name, upload keyword returns an array of 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
};

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

Related Keywords: "uploads", "request"

Response Handling Keywords

content

Sets the content of the response. This 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!';
    };
};

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

Related Keywords: "response"

content_type

Sets the Content-Type header of the response.

When to use: Specify the MIME type of the response.

Related Keywords: "header"

decode_json

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

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

Related Keywords: "encode_json", "from_json"

delayed

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

When to use: When starting an asynchronous reponse.

Related Keywords: "done", "flush"

done

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

When to use: When finishing delivery of data asynchronously.

See also: "delayed", "flush"

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.

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

See also: "decode_json", "to_json"

flush

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

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

See also: "delayed", "done"

forward

Forwards the request to another route handler.

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

Related Keywords: "pass"

from_dumper

Deserializes a Data::Dumper structure.

When to use: When you need to turn a Data::Dumper structure into a Perl hashref.

See also: "to_dumper", "from_json"

from_json

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

When to use: Decode JSON data from the client. "decode_json" is likely what you want.

Related Keywords: "to_json"

from_yaml

Deserializes a YAML structure.

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

See also: "to_yaml", "from_json"

halt

Halts request processing and sends a response immediately.

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

Best Practice: Combine "halt" with "status" to ensure appropriate HTTP response codes are sent.

Related Keywords: "status", "send_error"

header

Deprecated. Use "response_header" instead.

Related Keywords: "response_header".

headers

Deprecated. Use "response_headers" instead.

Related Keywords: "response_headers".

pass

Passes control to the next matching route.

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

Related Keywords: "forward"

push_header

Deprecated. Use "push_response_header" instead.

When to use: Don't. Use "push_response_header".

Related Keywords: "push_response_header".

push_response_header

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

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

See also: "response_header", "response_headers"

redirect

Redirects the client to a different location.

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

Related Keywords: "status"

response

Provides access to the current response object.

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

Related Keywords: "request", "header", "content"

response_header

Sets or retrieves a specific header in the outgoing response.

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

Related Keywords: "header", "response_headers"

response_headers

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

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

Related Keywords: "response_header", "header"

send_as

Manually serializes and sends the response in a specific format.

When to use: Control response serialization explicitly.

Related Keywords: encode_json, decode_json.

send_error

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

When to use: To send a custom error response.

Related Keywords: "halt", "status"

send_file

Sends a file to the client.

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

Related Keywords: "send_as"

status

Sets the HTTP status code for the response.

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

Best Practice: Combine "status" with "halt" for clearer error handling when sending error responses.

Related Keywords: "halt", "send_error"

to_dumper

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

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

Related Keywords: "from_dumper", "to_yaml", "to_json"

to_json

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

When to use: Encode data to JSON format.

Related Keywords: "from_json", "send_as"

to_yaml

Serializes a Perl data structure into a YAML string.

When to use: Convert data structures into YAML format.

Related Keywords: "from_yaml", "to_json", "to_dumper"

Session and Cookie Keywords

cookie

Retrieves the value of a specific cookie from the request.

When to use: Access individual cookies.

Related Keywords: "cookies", "session"

cookies

Retrieves all cookies from the request as a hash reference.

When to use: Inspect or manage multiple cookies.

Related Keywords: "cookie"

session

Stores, retrieves, or removes data from the session.

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

Related Keywords: "cookie", "cookies"

Application Configuration Keywords

app

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

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

See also: "dancer_app"

config

Retrieves the entire application configuration as a hash reference.

When to use: Access or inspect all configuration settings.

Related Keywords: "set", "setting"

dancer_app

Alias for "app".

Best Practice: Use "app" instead.

Related Keywords: "app"

dancer_version

Retrieve full version number of installed Dancer2.

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

See also: "dancer_major_version"

dancer_major_version

Retrieves major version number of Dancer2.

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

See also: "dancer_version"

prepare_app

Function to help initialize and configure your Dancer2 app.

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

See also: "to_app"

runner

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

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

Related Keywords: "app", "config"

set

Sets a configuration value for the application.

When to use: Change configuration dynamically at runtime.

Related Keywords: "setting", "config"

setting

Retrieves a configuration value.

When to use: Access app configuration values.

Related Keywords: "set", "config"

start

Initiates the Dancer2 application; typically called internally.

When to use: Rarely used directly; see "to_app" instead.

Related Keywords: "dance", "psgi_app"

var

Sets a variable in the application context.

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

Related Keywords: "vars"

vars

Retrieves the application context variables.

When to use: Access data stored with "var".

Related Keywords: "var"

Hooks

hook

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

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

Related Keywords: "var", "vars"

Template Keywords

template

Renders a view with the provided data.

When to use: Generate HTML or other formats dynamically.

Related Keywords: "vars"

Logging Keywords

debug

Logs a message at the debug level.

When to use: Detailed debugging and diagnostic messages.

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

Related Keywords: "info", "warning", "error", "log"

error

Logs a message at the error level.

When to use: Log errors that need immediate attention.

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

Related Keywords: "debug", "info", "warning", "log"

info

Logs a message at the info level.

When to use: General informational messages.

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

Related Keywords: "debug", "warning", "error", "log"

log

Logs a message at a specified level.

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

Related Keywords: "debug", "info", "warning", "error"

logger

Provides access to the logger object.

When to use: Advanced logging scenarios.

Related Keywords: "log", "debug", "info", "warning", "error"

warning

Logs a message at the warning level.

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

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

Related Keywords: "debug", "info", "error", "log"

Miscellaneous Keywords

dance

Alias to the start keyword.

Note: This keyword has been superseded by "to_app".

Best Practice: Use "to_app" instead.

Related Keywords: "to_app"

dirname

Given a path, return the directory name.

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

See also: "path"

dsl

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

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

Related Keywords: None.

engine

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

my $template_engine = engine 'template';

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

See also: "template", "session", "logger"

false

Returns a false value.

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

Related Keywords: "true"

mime

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

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

See also: "send_file"

path

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

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

See also: "dirname"

psgi_app

Provides the same functionality as "to_app", but uses the deprecated Dispatcher engine.

Note: This keyword has been superseded by "to_app".

Best Practice: Use "to_app" instead.

See also: to_app.

to_app

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

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

Related Keywords: "psgi_app", "dance"

true

Returns a true value.

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

Related Keywords: "false"

AUTHOR

Dancer Core Developers

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.

cpanm Dancer2

perl -MCPAN -e shell
install Dancer2