Dancer2::Manual::Keywords(3)

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

VERSION
version 2.0.1

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.