### JSON Configuration: Full Example

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/README.md

An example demonstrating the complete JSON structure for configuring multiple files associated with a program, including paths, movability, and help text.

```json
{
  "name": "git",
  "files": [
    {
      "path": "$HOME/.gitconfig",
      "movable": true,
      "help": "Move to $XDG_CONFIG_HOME/git/config\n"
    },
    {
      "path": "$HOME/.gitignore",
      "movable": false,
      "help": "Per-repository gitignore - keep in $HOME\n"
    }
  ]
}
```

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

### Example: Expand $HOME/.config

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/shell-script-reference.md

Shows an example of using 'apply_shell_expansion' to substitute the $HOME environment variable in a path. The result is the fully expanded path.

```bash
result=$(apply_shell_expansion "$HOME/.config")
# If HOME=/home/user: returns "/home/user/.config"
```

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

### Preview Workflow Example

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/module-index.md

Illustrates the execution flow for the 'xdgnj prev' command, showing how a program configuration file is loaded and processed.

```text
xdgnj prev programs/FILE.json
  └─ previewProgramFile()
      ├─ readProgram() - Load JSON
      └─ previewProgram()
          ├─ For each file:
          │   └─ previewFile()
          │       └─ logFile()
          │           └─ log()
          │               └─ renderMarkdown()
          └─ exit()
```

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

### Displaying Example File Content

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/README.md

This command uses `cat` to display the content of an example file named `example.md`. It's a basic file viewing operation.

```sh
cat example.md
```

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

### Get Complete File Configuration

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/add-program.md

Guides the user through entering a complete file configuration, including the file path, determining its support level, and editing its help text. Returns a structured File record.

```haskell
getFile :: IO File
```

```haskell
file <- getFile
-- User enters: $HOME/.vimrc
-- User answers support questions: Yes, No, No
-- User edits help in editor
-- Returns: File {path = "$HOME/.vimrc", supportLevel = Supported, help = "..."}
```

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

### Install xdg-ninja using Homebrew

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/README.md

Install xdg-ninja using Homebrew with the --HEAD option to get the latest version from git.

```shell
brew install xdg-ninja --HEAD
```

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

### Manual Installation of xdg-ninja

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/README.md

Clone the repository and run the xdg-ninja.sh script to perform a manual installation and run all default tests.

```shell
git clone https://github.com/b3nj5m1n/xdg-ninja
cd xdg-ninja
./xdg-ninja.sh
```

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

### Install xdg-ninja using Nix

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/README.md

Install xdg-ninja using the Nix package manager by enabling flakes and running the provided command.

```shell
nix run github:b3nj5m1n/xdg-ninja
```

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

### Example Help Text with Markdown and Code

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/configuration.md

Demonstrates how to format help text within a program configuration file, including Markdown for emphasis and code blocks for shell commands.

```markdown
Alias PROGRAM to use a custom configuration location:

```bash
alias PROGRAM=PROGRAM --config "$XDG_CONFIG_HOME"/PROGRAM/config
```
```

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

### Get Help with xdg-ninja Binary

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/README.md

Use the --help flag to display usage information for the compiled binary.

```bash
xdgnj --help
```

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

### Program Configuration JSON Example

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/README.md

Defines the structure of a program configuration file, specifying application name, files, and their movability.

```json
{
  "name": "git",
  "files": [
    {
      "path": "$HOME/.gitconfig",
      "movable": true,
      "help": "XDG is supported, move to $XDG_CONFIG_HOME/git/config"
    }
  ]
}
```

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

### Minimal JSON Configuration Example

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/configuration.md

A basic JSON configuration for a program, specifying its name and a single file path that can be moved.

```json
{
  "name": "program",
  "files": [
    {
      "path": "$HOME/.config",
      "movable": true,
      "help": "Help text"
    }
  ]
}
```

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

### Example xdg-ninja Program Configuration

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/configuration.md

Illustrates a typical JSON configuration file for a program, defining its files and whether they are movable to XDG-compliant locations.

```json
{
  "name": "git",
  "files": [
    {
      "path": "$HOME/.gitconfig",
      "movable": true,
      "help": "XDG is supported out-of-the-box, so we can simply move the file to _$XDG_CONFIG_HOME/git/config_.
"
    },
    {
      "path": "$HOME/.gitk",
      "movable": true,
      "help": "XDG is supported out-of-the-box, so we can simply move the file to _$XDG_CONFIG_HOME/git/gitk_.
"
    },
    {
      "path": "$HOME/.gitignore",
      "movable": false,
      "help": "If your _$HOME_ directory is a git repository - this file is the correct way to ignore files in it.
"
    }
  ]
}
```

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

### Get Markdown Template for Support Level

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/add-program.md

Retrieves pre-filled markdown templates for user-provided help documentation based on the specified support level. Useful for guiding users in writing help text.

```haskell
getTemplate :: SupportLevel -> String
```

```haskell
template <- getTemplate Unsupported
-- Returns: "Currently unsupported.\n\n_Relevant issue:_ ..."

template <- getTemplate Alias
-- Returns alias example template
```

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

### Add New Program Configuration with xdgnj

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/cli-reference.md

Launches an interactive wizard to create a new program configuration file. Guides through adding file paths, support levels, and help text before saving.

```bash
xdgnj add
```

```bash
xdgnj add
# Launches wizard:
# - Enter program name: vim
# - Enter first file path: $HOME/.vimrc
# - Can file be moved? y
# - Environment variables needed? n
# - Alias needed? n
# - (Editor opens for help text)
# - Add another file? n
# - Save? y
# Creates ./programs/vim.json
```

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

### Example: Pattern Matching Check

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/shell-script-reference.md

Illustrates the usage of 'has_pattern'. The first example checks a path with a wildcard, returning 0, while the second checks a literal filename, returning 1.

```bash
has_pattern "$HOME/.config/*"    # Returns 0 (has pattern)
has_pattern "$HOME/.gitconfig"   # Returns 1 (no pattern)
```

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

### File Edit Prompt Example

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/edit-program.md

Illustrates the interactive prompt for editing a specific file, showing the file path and the user's confirmation question.

```text
$HOME/.gitconfig
Edit this file? (y/n) 
```

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

### Displaying Example File Content with Newlines

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/README.md

This command pipes the content of `example.md` to `jq` to display it as a raw JSON string, preserving newline characters. This is useful for seeing how newlines are represented in JSON.

```sh
cat example.md | jq -aRs .
```

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

### Haskell Module Testing Commands

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/module-index.md

Demonstrates the commands used for building and testing the Haskell modules of xdg-ninja. Includes build commands and examples of running core functionalities.

```bash
# Build
stack build  # or: cabal build

# Test
xdgnj add
xdgnj prev programs/git.json
xdgnj edit programs/git.json
xdgnj run
```

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

### Get Help with xdg-ninja Shell Script

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/README.md

Use the --help flag to display usage information for the main shell script.

```bash
./xdg-ninja.sh --help
```

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

### Example: Check if 'glow' command is available

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/shell-script-reference.md

Demonstrates how to use the 'has_command' function to check for the presence of the 'glow' command and print a message if it's available.

```bash
if has_command glow; then
  echo "glow is available"
fi
```

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

### Complex JSON Configuration Example for Vim

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/configuration.md

A detailed JSON configuration for Vim, including multiple file paths and specific instructions for handling XDG compatibility via environment variables.

```json
{
  "name": "vim",
  "files": [
    {
      "path": "$HOME/.vimrc",
      "movable": true,
      "help": "Vim supports XDG through environment variables.\n\nSet the following in your shell configuration:\n\n```bash\nexport VIMINIT='let $MYVIMRC=\"$XDG_CONFIG_HOME/vim/vimrc\" | source $MYVIMRC'\n```\n"
    },
    {
      "path": "$HOME/.vim",
      "movable": true,
      "help": "Move the vim directory to `$XDG_CONFIG_HOME/vim`\n"
    },
    {
      "path": "$HOME/.viminfo",
      "movable": true,
      "help": "Set the viminfo location via environment variable:\n\n```bash\nexport VIMINIT='set viminfo+=n$XDG_STATE_HOME/vim/viminfo' | source ...\n```\n"
    }
  ]
}
```

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

### Example JSON Configuration for Git

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/README.md

This JSON structure defines configuration for the 'git' program, specifying its configuration file path and indicating that it is movable to an XDG-compliant location.

```json
{
    "name": "git",
    "files": [
        {
            "path": "$HOME/.gitconfig",
            "movable": true,
            "help": "Luckily, the XDG spec is supported by git, so we can simply move the file to _$XDG_CONFIG_HOME/git/config_.
"
        }
    ]
}
```

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

### JSON Configuration with Unsupported Files

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/configuration.md

Example of a JSON configuration that includes a file marked as non-movable due to software limitations, along with a movable configuration file.

```json
{
  "name": "example",
  "files": [
    {
      "path": "$HOME/.examplerc",
      "movable": true,
      "help": "Move to $XDG_CONFIG_HOME/example/config"
    },
    {
      "path": "$HOME/.example-legacy",
      "movable": false,
      "help": "This file cannot be moved due to software limitations. See: https://github.com/example/project/issues/123"
    }
  ]
}
```

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

### Editing Header Example

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/edit-program.md

Shows the header displayed when the editing process for a program begins, indicating the program name being edited.

```text
Editing git
```

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

### Set System-wide xdg-ninja Programs Directory

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/configuration.md

Configure the XN_PROGRAMS_DIR environment variable to point to the system-wide installation location of xdg-ninja program configurations.

```bash
export XN_PROGRAMS_DIR=/usr/share/xdg-ninja/programs
```

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

### Add Program API

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/DOCUMENTATION_INDEX.txt

Functions for creating new program configurations, including getting templates, help information, support levels, and file details.

```APIDOC
## Add Program API Reference

This section details the functions used in the interactive wizard for adding new program configurations.

### Functions

- **getTemplate(templateName)**
  - **Description**: Retrieves a program configuration template.
  - **Parameters**:
    - `templateName` (string) - The name of the template to retrieve.
  - **Returns**: `object` - The template configuration.

- **getHelp(topic)**
  - **Description**: Retrieves help information for a specific topic.
  - **Parameters**:
    - `topic` (string) - The topic for which to get help.
  - **Returns**: `string` - The help text.

- **getSupportLevel(program)**
  - **Description**: Determines the support level for a given program.
  - **Parameters**:
    - `program` (Program) - The program object.
  - **Returns**: `SupportLevel` - The determined support level.

- **getFile(fileConfig)**
  - **Description**: Gets details for a file configuration.
  - **Parameters**:
    - `fileConfig` (object) - The file configuration object.
  - **Returns**: `File` - The file details.

- **getFiles(program)**
  - **Description**: Retrieves all file configurations associated with a program.
  - **Parameters**:
    - `program` (Program) - The program object.
  - **Returns**: `Array<File>` - An array of file configurations.

- **getProgram(programConfig)**
  - **Description**: Gets details for a program configuration.
  - **Parameters**:
    - `programConfig` (object) - The program configuration object.
  - **Returns**: `Program` - The program details.

### Interactive Wizard

These functions facilitate an interactive process for creating new program configurations.
```

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

### Shell Script Testing Commands

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/module-index.md

Provides example commands for testing the main shell script of xdg-ninja. These commands cover basic help, verbose output, and skipping successful checks.

```bash
./xdg-ninja.sh --help
./xdg-ninja.sh -v
./xdg-ninja.sh --skip-ok
```

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

### Shell Script Execution Flow Example

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/shell-script-reference.md

Illustrates the typical execution flow of a shell script, including sourcing functions, parsing arguments, checking environment variables, dependency checks, main execution, and exiting with a status code.

```bash
# 1. Source/execute functions
has_command
auto_set_decoder
init_constants

# 2. Parse command-line arguments
SKIP_OK=true
SKIP_UNSUPPORTED=false
for arg in "$@"; do
  --help, -h          → help()
  --skip-ok           → SKIP_OK=true
  --no-skip-ok, -v    → SKIP_OK=false
  --skip-unsupported  → SKIP_UNSUPPORTED=true
done

# 3. Check environment variables and warn if not set
Check: XDG_DATA_HOME, XDG_CONFIG_HOME, XDG_STATE_HOME
       XDG_CACHE_HOME, XDG_RUNTIME_DIR
Display warning messages if not set

# 4. Check jq availability
if ! command -v jq; then
  Print error and exit
fi

# 5. Main execution
check_programs  # Runs all checks

# 6. Exit with count
if [ $FIXABLE -gt 100 ]; then
  exit 101
else
  exit $FIXABLE
fi
```

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

### Test Individual Shell Functions

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/shell-script-reference.md

Provides examples of how to test individual shell script functions after sourcing the script. This includes testing dependency checks, shell expansion, string decoding, and file checks.

```bash
# Source the script
source xdg-ninja.sh

# Test has_command
has_command jq && echo "jq found"

# Test apply_shell_expansion
apply_shell_expansion '$HOME/.config'

# Test decode_string
decode_string 'First line\nSecond line'

# Test with test data
check_file "test" "$HOME/.test" "true" "Test help"
```

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

### Get Support Level

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/edit-program.md

Prompts the user to determine if a file's support level has changed and guides them through selecting a new level if necessary. Uses colored prompts for user interaction.

```Haskell
getSupportLevel :: SupportLevel -> IO SupportLevel
-- Current level is Supported
level <- getSupportLevel Supported
-- If user says "No" → Returns Supported
-- If user says "Yes" and chooses new level → Returns EnvVars (or other)
```

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

### Preview Configuration with xdg-ninja

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/README.md

Use the 'prev' command followed by the configuration file path to preview a program configuration. Refer to api-reference/preview-program.md for details.

```bash
xdgnj prev programs/FILE.json
```

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

### Create New Configuration with Wizard

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/cli-reference.md

Initiate the wizard to create a new program configuration file.

```bash
# Start the wizard
xdgnj add
```

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

### Preview Configuration Changes

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/cli-reference.md

Use the 'prev' command with a configuration file path to preview the result of potential changes.

```bash
# Preview the result
xdgnj prev programs/mynewprogram.json
```

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

### Create Configuration with xdg-ninja

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/README.md

Use the 'add' command to create a new program configuration. Refer to api-reference/add-program.md for details.

```bash
xdgnj add
```

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

### Manually Create Program Configuration

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/configuration.md

Create a new JSON file in the 'programs/' directory for manual configuration. This involves defining the program name and an array of files with their paths, movability, and help text.

```bash
cat > programs/myprogram.json << 'EOF'
{
  "name": "myprogram",
  "files": [
    {
      "path": "$HOME/.myprogramrc",
      "movable": true,
      "help": "Move to $XDG_CONFIG_HOME/myprogram/config"
    }
  ]
}
EOF
```

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

### Create New Configuration with xdgnj

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/README.md

Initiate the interactive process to add a new program configuration. Follow the prompts to define program name, file paths, support levels, and help text.

```bash
xdgnj add
# Follow interactive prompts:
# 1. Enter program name
# 2. Enter file paths
# 3. Answer support level questions
# 4. Edit help text in your editor
# 5. Confirm save
```

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

### Upgrade xdg-ninja using Homebrew

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/README.md

Upgrade xdg-ninja installed via Homebrew by fetching the latest HEAD.

```shell
brew upgrade xdg-ninja --fetch-HEAD
```

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

### Preview Program Configuration with xdgnj

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/cli-reference.md

Previews a program configuration file without making changes. Displays how each file would appear with its associated help text.

```bash
xdgnj prev programs/git.json
# Displays:
# [git]: $HOME/.gitconfig
# XDG is supported out-of-the-box...
# 
# [git]: $HOME/.git-credentials
# XDG is supported out-of-the-box...
```

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

### Prompts API

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/DOCUMENTATION_INDEX.txt

Utilities for interacting with the user, including getting markdown-formatted input and prompting for boolean values.

```APIDOC
## Prompts API Reference

This section covers functions for user interaction and input handling.

### Functions

- **getInputMarkdown(prompt)**
  - **Description**: Prompts the user for input using a markdown formatted prompt.
  - **Parameters**:
    - `prompt` (string) - The markdown formatted prompt message.
  - **Returns**: `string` - The user's input.

- **getProp(propertyName)**
  - **Description**: Retrieves a property value, potentially prompting the user if not found.
  - **Parameters**:
    - `propertyName` (string) - The name of the property to retrieve.
  - **Returns**: `string` - The property value.

- **stringToBool(str)**
  - **Description**: Converts a string representation to a boolean value.
  - **Parameters**:
    - `str` (string) - The string to convert (e.g., 'true', 'false', 'yes', 'no').
  - **Returns**: `boolean` - The boolean representation.

- **promptBool(prompt)**
  - **Description**: Prompts the user for a boolean answer.
  - **Parameters**:
    - `prompt` (string) - The prompt message.
  - **Returns**: `boolean` - The user's boolean answer.
```

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

### getTemplate

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/add-program.md

Retrieves a markdown template for a given support level, used to guide users in writing help documentation.

```APIDOC
## getTemplate

### Description
Returns a markdown template for a given support level. Templates help guide users in writing help documentation.

### Signature
```haskell
getTemplate :: SupportLevel -> String
```

### Parameters
#### Path Parameters
- **supportLevel** (SupportLevel) - Required - Support level to get template for

### Returns
- **String** - Markdown template text

### Example
```haskell
template <- getTemplate Unsupported
-- Returns: "Currently unsupported.\n\n_Relevant issue:_ ..."

template <- getTemplate Alias
-- Returns alias example template
```
```

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

### Preview Configuration with xdgnj

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/README.md

Generate a preview of how a configuration file would appear during a system check. This helps visualize the impact of your settings before applying them.

```bash
xdgnj prev programs/git.json
# See how configuration would appear during checking
```

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

### Preview Configuration with xdgnj

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/configuration.md

Use the 'prev' command with xdgnj to preview a configuration file without opening it for editing. This is useful for quickly checking file contents.

```bash
xdgnj prev programs/git.json
```

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

### Download and make xdgnj executable

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/README.md

Download the prebuilt xdgnj binary for x86_64 Linux systems and make it executable.

```shell
curl -fsSL -o xdgnj https://github.com/b3nj5m1n/xdg-ninja/releases/latest/download/xdgnj
chmod +x xdgnj
```

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

### editProgram

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/edit-program.md

The main entry point for editing program configurations. It loads a configuration file and guides the user through editing each file within the program.

```APIDOC
## editProgram

### Description
Main entry point: loads configuration file and guides user through editing.

### Method
`IO ()`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **filename** (String) - Required - Path to JSON configuration file

### Returns
- **IO ()** - I/O action with side effects

### Description
1. Reads configuration file using `readProgram` from Program module
2. If parse fails:
   - Prints error in red: "Error parsing file {filename}"
   - Returns without changes
3. If successful:
   - Displays cyan header: "Editing {program_name}"
   - Iterates through each file using `editFile`
   - Collects modified files
   - Asks: "Save? (y/n)" (green prompt with red error messages)
   - If Yes: Saves modified Program back to same file
   - If No: Discards changes

### Example:
```haskell
editProgram "./programs/git.json"
-- Reads git.json
-- Displays "Editing git"
-- For each file, asks if user wants to edit
-- Asks to save at end
-- If yes: Overwrites git.json with changes
```

### Error Handling:
- JSON parse error: Displays error message and exits
- File not found: readProgram will fail at OS level

### Source:
haskell/lib/EditProgram.hs:64-76
```

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

### Check Workflow Diagram

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/module-index.md

Outlines the data flow for the check workflow, starting from the shell script, parsing options, and recursively checking files.

```text
xdg-ninja.sh
  ├─ auto_set_decoder() - Find markdown renderer
  ├─ Parse command-line options
  ├─ check_programs()
  │   └─ do_check_programs()
  │       ├─ find *.json files
  │       └─ For each file:
  │           ├─ jq extract fields
  │           └─ check_file()
  │               ├─ retrieve_existing_filename()
  │               ├─ apply_shell_expansion()
  │               └─ log()
  │                   └─ renderMarkdown() via DECODER
  └─ exit(FIXABLE)
```

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

### Display Help Message

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/cli-reference.md

Use the --help or -h flags to display the help message, which explains all available options.

```bash
xdg-ninja.sh --help
xdg-ninja.sh -h
```

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

### Recursively Collect File Entries

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/add-program.md

Collects file entries from the user recursively until they decline to add more. Starts with an empty list of files and accumulates them.

```haskell
getFiles :: [File] -> IO [File]
```

```haskell
files <- getFiles []
-- User adds file 1, asked "Add another?"
-- User adds file 2, asked "Add another?"
-- User says no, returns [File2, File1]
```

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

### Main Wizard Function for Program Configuration

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/add-program.md

Gathers complete program configuration interactively. It displays a banner, prompts for the program name, collects file information using `getFiles`, and returns the complete `Program` record.

```haskell
getProgram :: IO Program
```

```haskell
program <- getProgram
-- Displays wizard header
-- User enters program name: "vim"
-- Displays file instructions
-- User adds files via getFiles
-- Returns: Program {name = "vim", files = [...]}
```

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

### getFile

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/add-program.md

Prompts the user to enter a complete file configuration, including path, support level, and help text.

```APIDOC
## getFile

### Description
Prompts user to enter a complete file configuration. It asks for the file path, determines the support level, retrieves and edits help text, and then constructs and returns the File record.

### Signature
```haskell
getFile :: IO File
```

### Returns
- **IO File** - I/O action returning a File structure

### Example
```haskell
file <- getFile
-- User enters: $HOME/.vimrc
-- User answers support questions: Yes, No, No
-- User edits help in editor
-- Returns: File {path = "$HOME/.vimrc", supportLevel = Supported, help = "..."}
```
```

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

### Build xdg-ninja with Stack

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/README.md

Compile the project using the Stack build tool.

```bash
# With stack
stack build
```

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

### getSupportLevel

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/edit-program.md

Asks whether the support level has changed and prompts for a new level if needed. It guides the user through a decision tree to determine the appropriate support level.

```APIDOC
## getSupportLevel

### Description
Asks whether support level has changed and prompts for new level if needed. Uses a decision tree to determine the new support level if a change is indicated.

### Method
`IO SupportLevel`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **supportLevel** (SupportLevel) - Required - Current support level

### Returns
- **IO SupportLevel** - I/O action returning updated or unchanged support level

### Description
1. Asks: "Has the support level changed? (y/n)"
2. If No: Returns current support level unchanged
3. If Yes: Prompts for new support level using the following decision tree:
   - Asks: "Can the file be moved? (y/n)"
     - If No: Returns `Unsupported`
     - If Yes: Continue
   - Asks: "Do you have to export environment variables? (y/n)"
     - If Yes: Returns `EnvVars`
     - If No: Continue
   - Asks: "Do you have to set an alias? (y/n)"
     - If Yes: Returns `Alias`
     - If No: Returns `Supported`

### Example:
```haskell
-- Current level is Supported
level <- getSupportLevel Supported
-- If user says "No" → Returns Supported
-- If user says "Yes" and chooses new level → Returns EnvVars (or other)
```

### Source:
haskell/lib/EditProgram.hs:30-47
```

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

### previewProgramFile

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/preview-program.md

Reads a program configuration from a specified JSON file and then previews all its associated files. Handles JSON parsing errors by printing a message.

```APIDOC
## previewProgramFile

### Description
Reads a program configuration file (JSON), parses it, and then previews all the files within that configuration using `previewProgram`. It includes error handling for JSON parsing failures.

### Function Signature
```haskell
previewProgramFile :: String -> IO ()
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| filename | String | Yes | Path to program JSON configuration file |

### Request Example
```haskell
previewProgramFile "./programs/git.json"
```

### Response
#### Success Response (IO ())
- **Output:** Side effects to stdout, displaying previews for all files if the JSON is valid. If parsing fails, prints an error message.

#### Error Response
- **On JSON Parse Failure:** Prints "Error." in red bold text.

### Notes
- Integrates with the `xdgnj prev` command.
- Relies on `readProgram` from the Program module for file parsing.
```

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

### Haskell: Get Markdown Input from Editor

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/prompts.md

Prompts the user to edit markdown content in their configured editor. Returns the edited content or an empty string if the editor fails.

```haskell
getInputMarkdown :: String -> IO String
```

```haskell
template = "Edit me:\n\n"
content <- getInputMarkdown template
-- User edits in EDITOR, saves, and exits
-- Returns the edited content
```

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

### previewFile

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/preview-program.md

Logs a single file as if it existed on the filesystem, displaying its potential logging status (WARN or ERR). It simulates the output without modifying any actual files.

```APIDOC
## previewFile

### Description
Logs a single file as if it existed on the filesystem (warning status). This function simulates the output that would be generated by `logFile` with `onFilesystem` set to `True`.

### Function Signature
```haskell
previewFile :: T.Text -> File -> IO ()
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | Text | Yes | Program name |
| file | File | Yes | File configuration to preview |

### Request Example
```haskell
previewFile "git" file1
```

### Response
#### Success Response (IO ())
- **Output:** Side effects to stdout, simulating file logging status (WARN or ERR).

### Response Example
```
[git]: $HOME/.gitconfig
XDG is supported out-of-the-box, so we can simply move the file to...
```

### Notes
- Related to `logFile` from the Output module.
- Simulates file existence for preview purposes.
```

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

### Initialize ANSI Color Constants

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/shell-script-reference.md

Initializes global variables for ANSI escape codes used for text formatting and colors. This function should be called once at the script's start.

```bash
init_constants
```

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

### Read and Preview Program Configuration File

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/preview-program.md

Reads a program configuration from a JSON file and previews all its associated files. If the JSON parsing fails, it prints an error message in red. This function is integrated with the `xdgnj prev` command.

```haskell
previewProgramFile :: String -> IO ()
previewProgramFile "./programs/git.json"
-- If valid: Displays preview of git configuration
-- If invalid JSON: Prints "Error."

previewProgramFile "./programs/vim.json"
-- Displays full preview of vim configuration
```

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

### Get Help Text

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/edit-program.md

Allows users to edit the markdown help text for a file. It opens the user's default editor with the current help text pre-populated for modification.

```Haskell
getHelp :: String -> IO String
newHelp <- getHelp "Old help text"
-- User's editor opens with "Old help text" pre-filled
-- User modifies and saves
-- Returns new content
```

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

### Check System with Verbose Output

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/cli-reference.md

Run xdg-ninja with --no-skip-ok for a detailed output including all files checked.

```bash
# Check with verbose output
./xdg-ninja.sh --no-skip-ok
```

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

### Lint All Program Configurations with xdgnj (Experimental)

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/cli-reference.md

Scans and validates all program configuration files in the programs directory. Reports all validation errors. This command is experimental.

```bash
xdgnj lint
```

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

### Check System with Custom Program Directory

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/cli-reference.md

Specify a custom directory for program configurations using the XN_PROGRAMS_DIR environment variable.

```bash
# Check with custom program directory
XN_PROGRAMS_DIR=./programs ./xdg-ninja.sh
```

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

### Haskell: Get Text Input Property

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/prompts.md

Prompts the user for a text input property, displaying prompt and placeholder text. Returns the input string or an empty string if the user aborts.

```haskell
getProp :: T.Text -> T.Text -> IO String
```

```haskell
name <- getProp "Program name: " ""
-- User types: "vim" and presses Enter
-- Returns "vim"

path <- getProp "Path to file: " "$HOME/."
-- Placeholder "$HOME/." is shown for reference
-- User types final path
```

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

### Add Workflow Diagram

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/module-index.md

Illustrates the data flow for adding a new program, initiated by 'xdgnj add' or the 'add-program' executable, involving user prompts and saving to JSON.

```text
xdgnj add  or  add-program executable
  ├─ saveProgram()
  │   ├─ getProgram()
  │   │   ├─ getProp() - Program name
  │   │   └─ getFiles([])
  │   │       └─ getFile()
  │   │           ├─ getProp() - File path
  │   │           ├─ getSupportLevel()
  │   │           │   └─ promptBool() - Support questions
  │   │           └─ getHelp()
  │   │               └─ getInputMarkdown()
  │   ├─ promptBool() - Save confirmation
  │   └─ save() - Write JSON
  └─ exit()
```

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

### Check All Programs and Their Files

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/shell-script-reference.md

Reads program configurations from JSON files in XN_PROGRAMS_DIR and checks all associated files using `check_file`. Processes output using `jq` and `sed`.

```bash
do_check_programs
```

```bash
find "$XN_PROGRAMS_DIR" -type f -print0 | \
  xargs -0 jq '.files[] as $file | .name, $file.path, $file.movable, $file.help'
```

```bash
sed -e 's/^"//' -e 's/"$//'  # Remove leading and trailing quotes
```

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

### Check Specific Programs with find and xargs

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/cli-reference.md

Use find to locate specific program configuration files and pipe them to xdgnj prev for previewing.

```bash
# Check specific programs
find ./programs -name "git.json" | xargs xdgnj prev
```

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

### Get User-Edited Help Text

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/add-program.md

Opens the user's default editor with a pre-filled markdown template for help text, based on the provided support level. Returns the edited content after the user saves and closes the editor.

```haskell
getHelp :: SupportLevel -> IO String
```

```haskell
help <- getHelp Supported
-- Shows template, user edits in editor, returns edited markdown
```

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

### previewProgram

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/preview-program.md

Previews all files within a given program configuration. It iterates through each file in the program and applies the `previewFile` function to simulate their logging output.

```APIDOC
## previewProgram

### Description
Previews all files in a program configuration by mapping `previewFile` over each file and sequencing the I/O operations. This provides a consolidated preview of all files associated with a program.

### Function Signature
```haskell
previewProgram :: Program -> IO ()
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| program | Program | Yes | Program with files to preview |

### Request Example
```haskell
program <- readProgram "./programs/git.json"
case program of 
  Just p -> previewProgram p
  Nothing -> putStrLn "Error."
```

### Response
#### Success Response (IO ())
- **Output:** Side effects to stdout, displaying previews for all files in the program configuration.
```

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

### Run xdg-ninja with Nix

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/README.md

Run the xdgnj binary using Nix, specifying the desired command and arguments.

```shell
nix run github:b3nj5m1n/xdg-ninja#xdgnj-bin ...
```

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

### Check System Status with xdg-ninja

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/README.md

Run a simple check to identify configuration problems. Use the verbose flag to see all files, or skip unsupported issues.

```bash
# Simple check (default: only show problems)
./xdg-ninja.sh

# Verbose (show all files)
./xdg-ninja.sh -v

# Only show fixable issues
./xdg-ninja.sh --skip-unsupported
```

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

### Main Entry Point to Collect and Save Program Data

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/add-program.md

Initiates the interactive wizard to collect program data and prompts the user to save it. If confirmed, it saves the program configuration to a JSON file.

```haskell
saveProgram :: IO ()
```

```haskell
saveProgram
-- Runs complete wizard
-- User provides all information
-- Asks to confirm save
-- If yes: Saves to ./programs/{name}.json
-- If no: Discards and exits
```

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

### Set Custom Programs Directory

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/shell-script-reference.md

Illustrates how to specify a custom directory for program configurations by exporting the 'XN_PROGRAMS_DIR' environment variable before running the script.

```bash
export XN_PROGRAMS_DIR=/custom/path
./xdg-ninja.sh
```

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

### Run xdgnj Checks

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/cli-reference.md

Scans the programs directory for configuration files and validates them. Logs output for existing files. Exit codes indicate the number of fixable issues.

```bash
xdgnj run
```

```bash
xdgnj run
# Scans all programs and displays results
```

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

### Build xdg-ninja with Cabal

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/README.md

Compile the project using the Cabal build tool.

```bash
# With cabal
cabal build
```

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

### Run xdg-ninja Haskell Binary

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/README.md

Execute the xdg-ninja Haskell binary for various commands like 'add', 'run', or 'prev'.

```bash
# Run the Haskell binary
stack exec xdgnj -- add
stack exec xdgnj -- run
stack exec xdgnj -- prev programs/git.json
```

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

### makeFilename

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/program.md

Constructs a JSON filename for a program configuration by prepending './programs/' and appending '.json' to the given program name.

```APIDOC
## makeFilename

### Description
Constructs a JSON filename from a program name.

### Signature
```haskell
makeFilename :: T.Text -> T.Text
```

### Parameters
#### Path Parameters
- (input) (Text) - Required - Program name

### Returns
- Text - Filename path in the format "./programs/{name}.json"

### Description
Prepends `./programs/` and appends `.json` to the input program name.

### Example
```haskell
makeFilename "git"  -- Returns "./programs/git.json"
makeFilename "bash" -- Returns "./programs/bash.json"
```
```

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

### Preview Program API

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/DOCUMENTATION_INDEX.txt

Utilities for previewing program configurations, including individual files and the overall configuration in a preview mode.

```APIDOC
## Preview Program API Reference

This section covers functions for previewing program configurations.

### Functions

- **previewFile(file)**
  - **Description**: Previews the configuration of a specific file.
  - **Parameters**:
    - `file` (File) - The file object to preview.
  - **Returns**: `void`

- **previewProgram(program)**
  - **Description**: Previews the overall configuration of a program.
  - **Parameters**:
    - `program` (Program) - The program object to preview.
  - **Returns**: `void`

- **previewProgramFile(program, file)**
  - **Description**: Previews the configuration of a specific file within the context of a program.
  - **Parameters**:
    - `program` (Program) - The program object.
    - `file` (File) - The file object.
  - **Returns**: `void`

### Configuration Preview Mode

Details on how to enter and utilize the configuration preview mode are provided.
```

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

### Preview All Files in a Program

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/preview-program.md

Previews all files associated with a given program configuration by mapping `previewFile` over them. This function sequences the I/O operations for displaying each file's preview.

```haskell
previewProgram :: Program -> IO ()
program <- readProgram "./programs/git.json"
case program of
  Just p -> previewProgram p
    -- Displays preview of all files in git.json
  Nothing -> putStrLn "Error."
```

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

### Read Program Config and Check Files

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/checks.md

Reads a program configuration file, parses it as JSON, and then checks all its associated files using checkProgram. It prints an error message and returns an empty list if parsing fails, always operating in non-verbose mode.

```haskell
checkProgramFile :: String -> IO [Result]
```

```haskell
results <- checkProgramFile "./programs/git.json"
-- Successfully parsed and checked: [Result]
-- Or JSON error: [] and error message printed

results <- checkProgramFile "./programs/nonexistent.json"
-- File not found error or parse error
```

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

### Run xdgnj Executable

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/configuration.md

Execute the xdgnj command with the 'run' argument to check all program configurations in the default programs directory.

```bash
xdgnj run
```

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

### Schedule Weekly System Check with Cron

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/cli-reference.md

Set up a cron job to automatically run xdg-ninja weekly, logging the output to a file.

```bash
# Check system weekly
0 0 * * 0 cd ~/xdg-ninja && ./xdg-ninja.sh --skip-ok >> ~/.xdg-ninja.log
```

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

### Lint Program Configuration with xdgnj (Experimental)

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/cli-reference.md

Validates a specific program configuration file for JSON syntax errors. This command is experimental and not fully implemented.

```bash
xdgnj lintp <program>
```

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

### Add New Rendering Backend

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/shell-script-reference.md

Shows how to extend the script's functionality by adding a new rendering backend. This involves modifying the 'auto_set_decoder' function to check for a custom renderer command.

```bash
elif has_command myrenderer; then
    DECODER="myrenderer -format markdown"
fi
```

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

### Run All Checks

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/cli-reference.md

Execute xdg-ninja to check all configured programs for XDG compliance.

```bash
# Check all programs
xdgnj run
```

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

### Edit Configuration with xdg-ninja

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/README.md

Use the 'edit' command followed by the configuration file path to edit an existing program configuration. Refer to api-reference/edit-program.md for details.

```bash
xdgnj edit programs/FILE.json
```

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

### getHelp

Source: https://github.com/b3nj5m1n/xdg-ninja/blob/main/_autodocs/api-reference/edit-program.md

Prompts the user to edit the help markdown text for a file. It opens the user's default editor with the current help text pre-populated.

```APIDOC
## getHelp

### Description
Prompts user to edit help markdown text.

### Method
`IO String`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **currentHelp** (String) - Required - Current help text

### Returns
- **IO String** - I/O action returning edited help text

### Description
- Calls `getInputMarkdown` from Prompts module with current help as template
- Opens user's editor with existing help pre-populated
- Returns the user's edited content
- Allows complete rewriting of help text

### Example:
```haskell
newHelp <- getHelp "Old help text"
-- User's editor opens with "Old help text" pre-filled
-- User modifies and saves
-- Returns new content
```

### Source:
haskell/lib/EditProgram.hs:50-51
```