Dancer2...Keywords(3)

📦
version 2.2.1 · 10 versions
, in fedora 44

🎀 Dancer2::Manual::Keywords(3) 🎀

User Contributed Perl Documentation — yep, bestie, that's the vibe. This is Dancer2::Manual::Keywords, aka the Dancer2 DSL Keyword Reference. It's giving reference manual, but make it cute.

✨ NAME ✨

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

🌸 VERSION 🌸

version 2.2.1

💖 Dancer2 Keyword Guide 💖

Okay so 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. She's flexible like that.

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

Related Keywords: All HTTP methods. All of them, no cap.

del

Defines a route that responds to HTTP DELETE requests.

When to use: Delete resources. Bye-bye, data.

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

get

Defines a route that responds to HTTP GET requests. Automatically creates a HEAD route. Iconic behavior, honestly.

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. Just a lil update, not a whole rewrite.

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. It's the group-chat name for your 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. It's deprecated, bestie — don't fight it.

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 ✨

Okay bestie, this is where your app talks back to the client. 💅 No cap, these keywords are the main character energy of every response.

content

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

This will crash:
get '/' => sub {
    content 'Hello, world!';
};

But this? This will work just fine, fr fr:

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. The input is expected to be UTF-8 encoded bytes.

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

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. The input should be character strings. The output is UTF-8 encoded bytes.

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

Cookies and sessions? The dynamic duo of "remember me" energy. 🫶

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 ⚙️

The backstage pass to your app's whole vibe. ✨

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 🪝

Hooks are literally the plot twists of your request lifecycle. 👑

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 🎨

Making your HTML look iconic, one render at a time. 💅

template

Renders a view with the provided data.

When to use: Generate HTML or other formats dynamically.

Related Keywords: vars

📝 Logging Keywords 📝

Logs are your bestie when things get chaotic. Keep them cute, keep them clear. ✨

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

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 ✨

Okay bestie, this is the grab-bag section — the little odds and ends that don't fit anywhere else but are still lowkey essential. Let's get into it 💅

dance

Alias to the start keyword.

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

Best Practice: use "to_app" instead, fr fr.

Related Keywords: "to_app"

dirname

Given a path, return the directory name. That's it, that's the whole vibe.

When to use: when you need to extract the directory name given a path. Super handy for path wrangling 🧚

See also: "path"

dsl

Provides access to the DSL (Domain Specific Language) object. It's giving backstage pass 🎀

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

Related Keywords: None. Not a single one. It's independent, it's got main character energy 👑

engine

Given a namespace, return the current engine object. Like, 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. No cap.

When to use: when you want to explicitly return a false value in your application.

Related Keywords: "true"

mime

Provide access to your application's instance of Dancer2::Core::MIME. MIME type management, we love to see it 🌈

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 it does not verify its existence — so don't come for it if the file isn't there, it never promised that 💀

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. Old school, but not in the cute vintage way 🙈

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. This is the moment, this is the one you actually want ✨

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

Related Keywords: "psgi_app", "dance"

"true"

Returns a true value. Slay.

When to use: when you want to explicitly return a true value in your application.

Related Keywords: "false"

👑 AUTHOR 👑

Dancer Core Developers

This software is copyright (c) 2026 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.

And that's a wrap on the whole page, bestie!! 💖 This beauty was brought to you by perl v5.42.3, dated 2026-09-20, and it lives under the name Dancer2...Keywords(3). Go forth and write the most iconic Dancer2 app of your life. Periodt. 🦋🌸

📦 where this page comes from