# Util

## Overview

The `util` package appears to provide small shared helpers that simplify console input handling for the rest of the application. In this module, that responsibility is concentrated in [`InputUtils`](util/InputUtils.java:5), which wraps a single shared `Scanner` over standard input and exposes convenience methods for reading trimmed text and validated integers.

This module exists to keep input parsing logic in one place instead of repeating prompt, validation, and newline-handling code throughout the codebase. That makes console-based flows easier to read and reduces the chance of subtle input bugs.

## Key Classes and Interfaces

### `InputUtils`

[`InputUtils`](util/InputUtils.java:5) is a small static utility class for interactive command-line input. It is not stateful in the application-domain sense, but it does maintain one shared `Scanner` instance bound to `System.in` for the lifetime of the process.

Its role is straightforward:
- display prompts to the user,
- normalize string input by trimming whitespace,
- validate integer input before parsing,
- and provide a cleanup hook for closing the shared scanner.

Because the methods are static, callers do not instantiate this class. It is designed as a cross-cutting helper rather than a domain object.

#### `readLine(String prompt)`

[`InputUtils.readLine(String prompt)`](util/InputUtils.java:8) prints the provided prompt and returns the next line of input as a trimmed `String`.

- **Parameter:** `prompt` — text written directly to standard output before reading.
- **Returns:** the user's next line, with leading and trailing whitespace removed.
- **Behavior:** uses `scanner.nextLine()` and immediately calls `.trim()` on the result.

This method is useful when the caller wants simple free-form text input without preserving surrounding whitespace.

#### `readInt(String prompt)`

[`InputUtils.readInt(String prompt)`](util/InputUtils.java:13) prints a prompt, then keeps asking until the user enters a valid integer.

- **Parameter:** `prompt` — text written before the first read attempt.
- **Returns:** the parsed integer value.
- **Behavior:**
  - checks `scanner.hasNextInt()` before parsing,
  - discards invalid input by consuming a full line with `scanner.nextLine()`,
  - prints `Please enter a number: ` after each invalid attempt,
  - reads the integer with `scanner.nextInt()`,
  - then consumes the trailing newline with another `scanner.nextLine()`.

The extra newline consumption is important because `nextInt()` leaves the end-of-line token in the buffer. Without that cleanup, later line-based reads could behave unexpectedly.

#### `close()`

[`InputUtils.close()`](util/InputUtils.java:24) closes the shared scanner.

- **Parameter:** none.
- **Returns:** nothing.
- **Behavior:** directly closes the static `Scanner` instance.

Because the scanner wraps `System.in`, closing it usually means no further console input should be expected after this call. Callers should use it only when the application is done reading input.

## How It Works

A typical console interaction through this module looks like this:

1. The caller invokes `readLine(prompt)` or `readInt(prompt)`.
2. `InputUtils` prints the prompt immediately to standard output.
3. For text input, the next line is read and trimmed.
4. For integer input, the method loops until `Scanner.hasNextInt()` reports a valid number.
5. Once valid input is available, the method consumes it and clears the remaining newline token.
6. When input is no longer needed, the caller can invoke `close()` to release the scanner.

The design is intentionally minimal: there is no buffering layer, no exception translation, and no abstraction over the console beyond a shared helper around `Scanner`.

### Relationship diagram

```mermaid
flowchart LR
    UtilModule["Util"] --> InputUtils["InputUtils"]
    InputUtils --> ReadLine["readLine(prompt)"]
    InputUtils --> ReadInt["readInt(prompt)"]
    InputUtils --> Close["close()"]
```

## Data Model

This module does not define application data models, entities, or DTOs. Its only notable state is the private static [`Scanner`](util/InputUtils.java:5) used to read from `System.in`.

That scanner is shared across all calls, which means the class behaves like a singleton-style input gateway rather than a per-request object.

## Dependencies and Integration

`InputUtils` currently depends only on the Java standard library:
- [`java.util.Scanner`](util/InputUtils.java:3)
- `System.in` and `System.out` for console interaction

No other package dependencies were resolved for this module, and no cross-module relationships were detected in the index.

In practice, this module sits at the boundary between the application and the user’s terminal. Other code can call these helpers whenever it needs simple interactive input without duplicating prompt and validation logic.

## Notes for Developers

- `readLine(...)` trims whitespace, so it should not be used when leading or trailing spaces are meaningful.
- `readInt(...)` discards invalid tokens until a valid integer is entered, which makes it friendly for user input but unsuitable when you need to preserve raw input for later inspection.
- The class uses one shared `Scanner` over `System.in`. Be careful about closing it too early, because that can prevent any further console reads.
- The `readInt(...)` implementation deliberately consumes the leftover newline after parsing. If you add new input helpers, keep newline handling consistent with this behavior.
- Because all methods are static, this utility is easy to use from anywhere, but it also makes testing and replacement harder if the input strategy ever becomes more complex.