### Creating a Route in Athena Framework

Source: https://athenaframework.org/getting_started/routing

Demonstrates how to define routes using annotations (e.g., @[ARTA::Get("/")]) and the macro DSL (get "/") within controller classes in the Athena Framework. It shows a basic "Hello World" example for handling GET requests.

```crystal
require "athena"

# Define a controller
class ExampleController < ATH::Controller
  # Define an action to handle the related route
  @[ARTA::Get("/")]
  def index : String
    "Hello World"
  end

  # The macro DSL can also be used
  get "/" do
    "Hello World"
  end
end

# Run the server
ATH.run

# GET / # => Hello World

```

--------------------------------

### Progress Bar Usage Example

Source: https://athenaframework.org/Console/Helper/ProgressBar

Demonstrates how to create and use the ProgressBar helper to display progress for a task. It shows initializing the bar, starting it, and advancing it incrementally.

```Ruby
# Create a new progress bar with 50 required units for completion.
progress_bar = ACON::Helper::ProgressBar.new output, 50

# Start and display the progress bar.
progress_bar.start

50.times do
  # Do work

  # Advance the progress bar by 1 unit.
  progress_bar.advance

  # Or advance by more than a single unit.
  # progress_bar.advance 3
end
```

--------------------------------

### Athena Framework Controller Setup

Source: https://athenaframework.org/Framework/Controller

Demonstrates the basic setup for an Athena controller, including required libraries and the application of route annotations to a controller class for path prefixing.

```ruby
require "athena"
require "mime"

# The `ARTA::Route` annotation can also be applied to a controller class.
# This can be useful for applying a common path prefix, defaults, requirements,

```

--------------------------------

### Athena Controller Link Example

Source: https://athenaframework.org/Framework/Controller

Example demonstrating how to define a generic link route with path parameters and type constraints using the `link` DSL macro in an Athena Controller.

```Crystal
class ExampleController < ATH::Controller
  link "values/{value1<\\d+>}/{value2<\\d+\\.\\d+>}", value1 : Int32, value2 : Float64 do
    "Value1: #{value1} - Value2: #{value2}"
  end
end
```

--------------------------------

### Athena Controller POST Example

Source: https://athenaframework.org/Framework/Controller

Example demonstrating how to define a POST route for handling values with specific type constraints using the `post` DSL macro in an Athena Controller.

```Crystal
class ExampleController < ATH::Controller
  post "values/{value1<\\d+>}/{value2<\\d+\\.\\d+>}", value1 : Int32, value2 : Float64 do
    "Value1: #{value1} - Value2: #{value2}"
  end
end
```

--------------------------------

### Install Athena Framework Component (Crystal)

Source: https://athenaframework.org/getting_started

This snippet shows how to add the Athena framework component to your Crystal project's `shard.yml` file. It specifies the GitHub repository and version constraint for the framework. After adding this, run `shards install` to fetch the dependencies.

```Crystal
dependencies:
  athena:
    github: athena-framework/framework
    version: ~> 0.20.0

```

--------------------------------

### Athena CLI Command Lifecycle Methods

Source: https://athenaframework.org/Console/Command

Illustrates the command lifecycle in Athena, showing how to implement optional `#setup` and `#interact` methods before the mandatory `#execute` method. These methods allow for state setup and user interaction for missing arguments.

```Crystal
@[ACONA::AsCommand("app:create-user")]
class CreateUserCommand < ACON::Command
  protected def configure : Nil
    # ... configuration ...
  end

  protected def setup(input : ACON::Input::Interface, output : ACON::Output::Interface) : Nil
    # Setup state based on input data.
    # ...
  end

  protected def interact(input : ACON::Input::Interface, output : ACON::Output::Interface) : Nil
    # Interact with the user for missing arguments/options.
    # ...
  end

  protected def execute(input : ACON::Input::Interface, output : ACON::Output::Interface) : ACON::Command::Status
    # Contains the business logic for the command.
    # ...

    # Indicates the command executed successfully.
    ACON::Command::Status::SUCCESS
  end
end
```

--------------------------------

### HTTP GET Endpoint Example

Source: https://athenaframework.org/Framework/Controller

Illustrates a basic HTTP GET request to an endpoint and its expected output, demonstrating how a controller action might respond.

```APIDOC
GET /Fred
# Expected Output:
# Greetings, Fred!
```

--------------------------------

### Athena Controller Render Template Example

Source: https://athenaframework.org/Framework/Controller

Example showing how to use the `render` method to display an ECR template within an Athena Controller action. It defines a GET route that calls `render` with a template file.

```Crystal
# greeting.ecr
Greetings, <%= name %>!

# example_controller.cr
class ExampleController < ATH::Controller
  @[ARTA::Get("/{name}")]
  def greet(name : String) : ATH::Response
    render "greeting.ecr"
  end
end

ATH.run
```

--------------------------------

### Basic HTTP Server Setup with Routing Handler

Source: https://athenaframework.org/Routing/RoutingHandler

Demonstrates the fundamental setup of an HTTP server in the Athena Framework, integrating a compiled routing handler to manage incoming requests.

```crystal
server = HTTP::Server.new([
  handler.compile,
])

address = server.bind_tcp 8080
puts "Listening on http://#{address}"
server.listen
```

--------------------------------

### Retrieve Header Name Example

Source: https://athenaframework.org/Framework/Request/ProxyHeader

Demonstrates how to get the string representation of a proxy header using the `#header` method.

```Ruby
puts ATH::Request::ProxyHeader::FORWARDED_PROTO.header
# Expected output: x-forwarded-proto
```

--------------------------------

### Athena Framework Log Output Example

Source: https://athenaframework.org/getting_started/error_handling

Demonstrates typical log messages generated by the Athena Framework, including server startup, route matching, and uncaught exceptions with stack traces. This shows the default log format and information captured.

```text
2022-01-08T20:44:18.134423Z   INFO - athena.routing: Server has started and is listening at http://0.0.0.0:3000
2022-01-08T20:44:19.773376Z   INFO - athena.routing: Matched route 'example_controller_divide' -- route: "example_controller_divide", route_parameters: {"_route" => "example_controller_divide", "_controller" => "ExampleController#divide", "num1" => "10", "num2" => "0"}, request_uri: "/divide/10/0", method: "GET"
2022-01-08T20:44:19.892748Z  ERROR - athena.routing: Uncaught exception #<DivisionByZeroError:Division by 0> at /usr/lib/crystal/int.cr:141:7 in 'check_div_argument'
Division by 0 (DivisionByZeroError)
  from /usr/lib/crystal/int.cr:141:7 in 'check_div_argument'
  from /usr/lib/crystal/int.cr:105:5 in '//'
  from src/components/framework/src/athena.cr:206:5 in 'divide'
  from src/components/framework/src/ext/routing/annotation_route_loader.cr:8:5 in '->'
  from /usr/lib/crystal/primitives.cr:266:3 in 'execute'
  from src/components/framework/src/route_handler.cr:76:16 in 'handle_raw'
  from src/components/framework/src/route_handler.cr:19:5 in 'handle'
  from src/components/framework/src/athena.cr:161:27 in '->'
  from /usr/lib/crystal/primitives.cr:266:3 in 'process'
  from /usr/lib/crystal/http/server.cr:515:5 in 'handle_client'
  from /usr/lib/crystal/http/server.cr:468:13 in '->'
  from /usr/lib/crystal/primitives.cr:266:3 in 'run'
  from /usr/lib/crystal/fiber.cr:98:34 in '->'
  from ???

2022-01-08T20:45:10.803001Z   INFO - athena.routing: Matched route 'example_controller_divide_rescued' -- route: "example_controller_divide_rescued", route_parameters: {"_route" => "example_controller_divide_rescued", "_controller" => "ExampleController#divide_rescued", "num1" => "10", "num2" => "0"}, request_uri: "/divide_rescued/10/0", method: "GET"
2022-01-08T20:45:10.923945Z   WARN - athena.routing: Uncaught exception #<Athena::Framework::Exception::BadRequest:Invalid num2:  Cannot divide by zero> at src/components/framework/src/athena.cr:215:5 in 'divide_rescued'
Invalid num2:  Cannot divide by zero (Athena::Framework::Exception::BadRequest)
  from src/components/framework/src/athena.cr:215:5 in 'divide_rescued'
  from src/components/framework/src/ext/routing/annotation_route_loader.cr:8:5 in '->'
  from /usr/lib/crystal/primitives.cr:266:3 in 'execute'
  from src/components/framework/src/route_handler.cr:76:16 in 'handle_raw'
  from src/components/framework/src/route_handler.cr:19:5 in 'handle'
  from src/components/framework/src/athena.cr:161:27 in '->'
  from /usr/lib/crystal/primitives.cr:266:3 in 'process'
  from /usr/lib/crystal/http/server.cr:515:5 in 'handle_client'
  from /usr/lib/crystal/http/server.cr:468:13 in '->'
  from /usr/lib/crystal/primitives.cr:266:3 in 'run'
  from /usr/lib/crystal/fiber.cr:98:34 in '->'
  from ???

2022-01-08T20:45:14.132652Z   INFO - athena.routing: Matched route 'example_controller_divide_rescued' -- route: "example_controller_divide_rescued", route_parameters: {"_route" => "example_controller_divide_rescued", "_controller" => "ExampleController#divide_rescued", "num1" => "10", "num2" => "10"}, request_uri: "/divide_rescued/10/10", method: "GET"

```

--------------------------------

### Example Controller with API Endpoint

Source: https://athenaframework.org/getting_started/routing

Defines an example controller inheriting from ATH::Controller. It exposes a GET endpoint '/users' using the ARTA routing mechanism, returning a list of User objects with a custom HTTP status.

```Ruby
class ExampleController < ATH::Controller
  @[ARTA::Get("/users")]
  def get_users : ATH::View(Array(User))
    self.view([
      User.new(1, "Jim", "[email\u00a0protected]"),
      User.new(2, "Bob", "[email\u00a0protected]"),
      User.new(3, "Sally", "[email\u00a0protected]"),
    ], status: :im_a_teapot)
  end
end
```

--------------------------------

### Basic Table Rendering Example

Source: https://athenaframework.org/Console/Helper/Table

Demonstrates the common usage pattern for creating and rendering a table with headers and multiple data rows using the Athena::Console::Helper::Table class. It shows how to instantiate the table, set headers, populate rows, and finally render the table to the output interface.

```ruby
@[ACONA::AsCommand("table")]
class TableCommand < ACON::Command
  protected def execute(input : ACON::Input::Interface, output : ACON::Output::Interface) : ACON::Command::Status
    ACON::Helper::Table.new(output)
      .headers("ISBN", "Title", "Author")
      .rows([
        ["99921-58-10-7", "Divine Comedy", "Dante Alighieri"],
        ["9971-5-0210-0", "A Tale of Two Cities", "Charles Dickens"],
        ["960-425-059-0", "The Lord of the Rings", "J. R. R. Tolkien"],
        ["80-902734-1-6", "And Then There Were None", "Agatha Christie"],
      ])
      .render

    ACON::Command::Status::SUCCESS
  end
end

```

--------------------------------

### Example Controller Test

Source: https://athenaframework.org/Framework/Spec/Expectations/HTTP

Demonstrates how to use the `assert_response_is_successful` method within a controller test case. It makes a GET request to the root path and then asserts that the response indicates success.

```crystal
struct ExampleControllerTest < ATH::Spec::APITestCase
  def test_root : Nil
    self.get "/"

    self.assert_response_is_successful
  end
end
```

--------------------------------

### Create and Register Commands with Athena Console Application

Source: https://athenaframework.org/Console

Shows how to instantiate an `ACON::Application`, register custom commands, and register commands using blocks. It covers the core setup for a CLI application.

```crystal
# Create an ACON::Application, passing it the name of your CLI.
# Optionally accepts a second argument representing the version of the application.
application = ACON::Application.new "My CLI"

# Register commands using the `#add` method
application.add CreateUserCommand.new

# Or register a block as a command directly
application.register "foo" do |input, output, cmd|
  # Do stuff

  ACON::Command::Status::Success
end

# Run the application.
# By default this uses STDIN and STDOUT for its input and output.
application.run
```

--------------------------------

### Athena::Dotenv API Reference

Source: https://athenaframework.org/Dotenv/top_level

Provides a comprehensive overview of the Athena::Dotenv class methods, including constructors and instance methods, detailing their parameters, functionality, and potential exceptions.

```APIDOC
class `Athena::Dotenv` inherits `Reference`

  # Constructors
  # .load(path,*)
  #   Loads environment variables from the specified file path(s).
  #   Accepts one or more file paths.
  #   Raises Athena::Dotenv::Exception::Path if a file is not found or readable.
  
  # .new(env_key)
  #   Initializes a new Athena::Dotenv instance.
  #   env_key: The key to identify the current environment (e.g., 'APP_ENV').
  
  # Methods
  # #load(*)
  #   Loads environment variables from the specified file path(s) into the current process's ENV.
  #   Accepts one or more file paths.
  #   Raises Athena::Dotenv::Exception::Path if a file is not found or readable.
  #
  # #load_environment(path, env_key, default_environment, test_environments, override_existing_vars)
  #   Loads environment variables based on the application's environment.
  #   It typically loads .env, .env.local, and .env.$APP_ENV.local or .env.$APP_ENV.
  #   path: The base path for .env files.
  #   env_key: The environment variable key (e.g., 'APP_ENV').
  #   default_environment: The default environment if APP_ENV is not set.
  #   test_environments: An array of environments considered as 'test'.
  #   override_existing_vars: Boolean to indicate if existing ENV vars should be overridden.
  #
  # #overload(*)
  #   Similar to #load, but explicitly overrides existing environment variables.
  #   Accepts one or more file paths.
  #   Raises Athena::Dotenv::Exception::Path if a file is not found or readable.
  #
  # #parse(data, path)
  #   Parses a string of environment variable data.
  #   data: The string content to parse.
  #   path: The path associated with the data for error reporting.
  #   Returns a hash of parsed key-value pairs.
  #   Raises Athena::Dotenv::Exception::Format for parsing errors.
  #
  # #populate(values, override_existing_vars)
  #   Populates the process's ENV with provided key-value pairs.
  #   values: A hash of environment variables to set.
  #   override_existing_vars: Boolean to indicate if existing ENV vars should be overridden.
  #
  # Constants
  # VERSION
  #   The current version of the athena-dotenv gem.
  #
  # Exceptions:
  #   Athena::Dotenv::Exception::Format: Raised for syntax or parsing errors.
  #   Athena::Dotenv::Exception::Logic: Raised for logical errors during operation.
  #   Athena::Dotenv::Exception::Path: Raised when a file path is invalid or inaccessible.

```

--------------------------------

### Example Usage of Athena::Console::Loader::Factory

Source: https://athenaframework.org/Console/Loader/Factory

Demonstrates how to instantiate and configure the `Athena::Console::Loader::Factory` with custom commands for an application.

```Ruby
application = MyCustomApplication.new "My CLI"

application.command_loader = Athena::Console::Loader::Factory.new({
  "command1"        => Proc(ACON::Command).new { Command1.new },
  "app:create-user" => Proc(ACON::Command).new { CreateUserCommand.new },
})

application.run

```

--------------------------------

### Install Athena Validator

Source: https://athenaframework.org/Validator

Add the Athena Validator dependency to your `shard.yml` file to install the component using the `shards install` command.

```yaml
dependencies:
  athena-validator:
    github: athena-framework/validator
    version: ~> 0.4.0

```

--------------------------------

### Install Athena Image Size Component

Source: https://athenaframework.org/ImageSize

Instructions to install the Athena Image Size component by adding it to your `shard.yml` file and running `shards install`.

```yaml
dependencies:
  athena-image_size:
    github: athena-framework/image-size
    version: ~> 0.1.0

```

--------------------------------

### Athena CLI Help Output

Source: https://athenaframework.org/why_athena

Example output from the Athena Framework's CLI help command, listing available commands and options. This demonstrates the structure and discoverability of CLI tools built with the framework.

```APIDOC
$ ./bin/console
Athena 0.18.0

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  help                    Display help for a command
  list                    List commands
 app
  app:create-user
 debug
  debug:event-dispatcher  Display configured listeners for an application
  debug:router            Display current routes for an application
  debug:router:match      Simulate a path match to see which route, if any, would handle it
```

--------------------------------

### Install Athena Routing Component

Source: https://athenaframework.org/Routing

Instructions for adding the Athena Routing component to your project's `shard.yml` file and installing it using the `shards install` command.

```YAML
dependencies:
  athena-routing:
    github: athena-framework/routing
    version: ~> 0.1.0

```

--------------------------------

### Athena Framework Console Application

Source: https://athenaframework.org/Framework/Commands

Documentation for the Console component, including application setup and compiler passes for registering commands.

```APIDOC
Console:
  Application: Core console application class.
  CompilerPasses:
    RegisterCommands: Compiler pass for registering console commands.
```

--------------------------------

### Install Athena Mercure Component

Source: https://athenaframework.org/Mercure

This snippet shows how to add the Athena Mercure component as a dependency to your `shard.yml` file. After adding the dependency, run `shards install` to fetch and install the component.

```YAML
dependencies:
  athena-mercure:
    github: athena-framework/mercure
    version: ~> 0.1.0

```

--------------------------------

### Install Athena Dependency Injection

Source: https://athenaframework.org/DependencyInjection

Instructions for adding the Athena Dependency Injection component to your Crystal project's shard.yml file and installing it using the 'shards install' command.

```yaml
dependencies:
  athena-dependency_injection:
    github: athena-framework/dependency-injection
    version: ~> 0.4.0

```

--------------------------------

### Athena Framework Console API

Source: https://athenaframework.org/Framework/View/FormatNegotiator

API documentation for the Console component, covering application setup and command registration.

```APIDOC
Console:
  Application:
    Description: Represents the Console Application.
  CompilerPasses:
    RegisterCommands:
      Description: Compiler pass for registering console commands.
```

--------------------------------

### Install Athena::Clock Component (Crystal)

Source: https://athenaframework.org/Clock

Describes how to add the `athena-clock` component to your `shard.yml` file and install it using `shards install`. This is the standard method for managing dependencies in Crystal projects.

```yaml
dependencies:
  athena-clock:
    github: athena-framework/clock
    version: ~> 0.2.0
```

--------------------------------

### Install Athena::Negotiation Component

Source: https://athenaframework.org/Negotiation

Instructions for installing the Athena::Negotiation component by adding it as a dependency to your Crystal project's `shard.yml` file and running `shards install`. This component has no external dependencies.

```yaml
dependencies:
  athena-negotiation:
    github: athena-framework/negotiation
    version: ~> 0.2.0
```

--------------------------------

### Basic Usage Example

Source: https://athenaframework.org/Console/Style/Athena

Demonstrates how to instantiate the Athena style class and use its title formatting method.

```Crystal
protected def execute(input : ACON::Input::Interface, output : ACON::Output::Interface) : ACON::Command::Status
  style = ACON::Style::Athena.new input, output

  style.title "Some Fancy Title"

  # ...

  ACON::Command::Status::SUCCESS
end
```

--------------------------------

### NotEqualTo Constraint Usage Example

Source: https://athenaframework.org/Validator/Constraints/NotEqualTo

Demonstrates how to use the NotEqualTo constraint in Ruby with an example User class.

```Ruby
class User
  include AVD::Validatable

  def initialize(@name : String); end

  @[Assert::NotEqualTo("John Doe")]
  property name : String
end

```

--------------------------------

### Simple Webapp Routing with ART::RoutingHandler

Source: https://athenaframework.org/Routing

Sets up a basic web application using Crystal's HTTP::Server and the ART::RoutingHandler for routing. It shows how to add routes with specific HTTP methods and parameter matching, and how to compile the handler for the server.

```Crystal
handler = ART::RoutingHandler.new

# The `methods` property can be used to limit the route to a particular HTTP method.
handler.add "new_article", ART::Route.new("/article", methods: "post") do |ctx|
  pp ctx.request.body.try &.gets_to_end
end

# The match parameters from the route are passed to the callback as a `Hash(String, String?)`.
handler.add "article", ART::Route.new("/article/{id<\\d+>}", methods: "get") do |ctx, params|
  pp params # => {"_route" => "article", "id" => "10"}
end

# Call the `#compile` method when providing the handler to the handler array.
server = HTTP::Server.new([
  handler.compile,
])

address = server.bind_tcp 8080
puts "Listening on http://#{address}"
server.listen
```

--------------------------------

### Install Event Dispatcher Component

Source: https://athenaframework.org/EventDispatcher

Add the athena-event_dispatcher component to your `shard.yml` file and run `shards install` to include it in your Crystal project.

```YAML
dependencies:
  athena-event_dispatcher:
    github: athena-framework/event-dispatcher
    version: ~> 0.3.0

```

--------------------------------

### Example: Initialize Image from File Path

Source: https://athenaframework.org/ImageSize/Image

Demonstrates how to use the `.from_file_path` constructor to load image information from a file and displays the resulting `Athena::ImageSize::Image` object.

```crystal
pp AIS::Image.from_file_path "spec/images/jpeg/436x429_8_3.jpeg" # =>
# Athena::ImageSize::Image(
# @bits=8,
# @channels=3,
# @format=JPEG,
# @height=429,
# @width=436)

```

--------------------------------

### ExpirationChecker Example

Source: https://athenaframework.org/Clock/Native

An example class `ExpirationChecker` demonstrating how to use an `Athena::Clock::Interface` to check if an item has expired based on the current time.

```Crystal
class ExpirationChecker
  def initialize(@clock : Athena::Clock::Interface); end

  def expired?(valid_until : Time) : Bool
    @clock.now > valid_until
  end
end
```

--------------------------------

### Define and Add Routes with Athena::Routing::RoutingHandler

Source: https://athenaframework.org/Routing/RoutingHandler

Demonstrates how to initialize the RoutingHandler and add routes with specific HTTP methods and parameter matching. It shows how route parameters are passed to the callback context.

```crystal
handler = ART::RoutingHandler.new

# The `methods` property can be used to limit the route to a particular HTTP method.
handler.add "new_article", ART::Route.new("/article", methods: "post") do |ctx|
  pp ctx.request.body.try &.gets_to_end
end

# The match parameters from the route are passed to the callback as a `Hash(String, String?)
handler.add "article", ART::Route.new("/article/{id<\\d+>}", methods: "get") do |ctx, params|
  pp params # => {"_route" => "article", "id" => "10"}
end
```