json-config-loader

name	json-config-loader
version	1.0.0
description	Configuration file parsing patterns for bash scripts (INI, key=value, JSON)
author	workspace-hub
category	bash
tags	["bash","config","json","yaml","parsing","jq","configuration"]
platforms	["linux","macos"]

JSON & Config Loader

Patterns for loading, parsing, and generating configuration files in bash scripts. Supports key=value files, JSON with jq, and associative array management. Extracted from workspace-hub's configuration scripts.

When to Use This Skill

✅ Use when:

• Loading configuration from files into bash scripts
• Parsing key=value or INI-style configuration files
• Working with JSON data using jq
• Generating JSON reports from bash
• Managing configuration with associative arrays

❌ Avoid when:

• Complex nested configuration (consider Python instead)
• Real-time configuration changes (use a daemon)
• Configuration with complex validation rules

Core Capabilities

1. Key=Value Configuration Parsing

Parse simple key=value configuration files:

#!/bin/bash
# ABOUTME: Parse key=value configuration files
# ABOUTME: Supports comments, empty lines, and quoted values

CONFIG_FILE="${1:-config.conf}"

# Declare associative array for config
declare -A CONFIG

# Parse configuration file
parse_config() {
    local file="$1"

    if [[ ! -f "$file" ]]; then
        echo "Error: Config file not found: $file" >&2
        return 1
    fi

    while IFS= read -r line || [[ -n "$line" ]]; do
        # Skip comments and empty lines
        [[ "$line" =~ ^[[:space:]]*# ]] && continue
        [[ -z "${line// /}" ]] && continue

        # Parse key=value pairs
        if [[ "$line" =~ ^([^=]+)=(.*)$ ]]; then
            local key="${BASH_REMATCH[1]}"
            local value="${BASH_REMATCH[2]}"

            # Trim whitespace
            key="${key#"${key%%[![:space:]]*}"}"
            key=
            value=
            value=

            
             [[  =~ ^\"(.*)\"$ ]] || [[  =~ ^\'(.*)\'$ ]]; 
                value=
            

            CONFIG[]=
        
     < 
}


() {
     key=
     default=

     
}


() {
     key=
    [[ -v CONFIG[] ]]
}


parse_config 


 
 

 has_config ; 
     

2. JSON Configuration with jq

Load and manipulate JSON configuration:

#!/bin/bash
# ABOUTME: JSON configuration loading with jq
# ABOUTME: Provides safe defaults and nested value access

# Check jq dependency
check_jq() {
    if ! command -v jq &> /dev/null; then
        echo "Error: jq is required but not installed" >&2
        echo "Install with: apt install jq (Ubuntu) or brew install jq (Mac)" >&2
        exit 1
    fi
}

# Load JSON config file
load_json_config() {
    local file="$1"

    if [[ ! -f "$file" ]]; then
        echo "{}"
        return 1
    fi

    # Validate JSON
    if ! jq empty "$file" 2>/dev/null; then
        echo "Error: Invalid JSON in $file" >&2
        echo "{}"
        return 1
    fi

    cat "$file"
}

# Get value from JSON with default
json_get() {
    local json="$1"
    local path=
     default=

     value
    value=$(  | jq -r  2>/dev/null)

     [[ -z  ||  ==  ]]; 
         
    
         
    
}


() {
     json=
     path=

      | jq -r  2>/dev/null
}


() {
     json=
     path=

     result
    result=$(  | jq -e  2>/dev/null)
    [[  ==  ]]
}


check_jq

CONFIG_JSON=$(load_json_config )


DB_HOST=$(json_get   )
DB_PORT=$(json_get   )
DEBUG=$(json_get   )

 
 


 
 IFS=  -r feature; 
     
 < <(json_get_array  )

3. JSON Report Generation

Generate structured JSON reports:

#!/bin/bash
# ABOUTME: Generate JSON reports from bash data
# ABOUTME: Uses jq for proper JSON encoding and structure

# Generate simple JSON object
generate_json_object() {
    local -n data=$1  # Nameref to associative array

    local json="{}"

    for key in "${!data[@]}"; do
        local value="${data[$key]}"
        json=$(echo "$json" | jq --arg k "$key" --arg v "$value" '. + {($k): $v}')
    done

    echo "$json"
}

# Generate JSON report with structure
generate_report() {
    local status="$1"
    local total="$2"
    local errors="$3"
    local warnings="$4"

    jq -n \
        --arg status "$status" \
        --arg timestamp "$(date -Iseconds)" \
        --arg run_id "$(date +%Y%m%d-%H%M%S)" \
        --argjson total  \
        --argjson errors  \
        --argjson warnings  \
        
}


() {
     report=
    
     items=()

    
     items_json=
     item  ; 
        items_json=$(  | jq --arg i  )
    

      | jq --argjson items  
}


() {
     report=
     file=

     -p 
      | jq  > 

     
}


report=$(generate_report  100 5 10)
report=$(add_report_items    )
save_report  

4. Multi-Section INI Parsing

Parse INI-style files with sections:

#!/bin/bash
# ABOUTME: Parse INI-style configuration with sections
# ABOUTME: Supports [section] headers and section.key access

declare -A INI_CONFIG
declare -a INI_SECTIONS=()

parse_ini() {
    local file="$1"
    local current_section="default"

    if [[ ! -f "$file" ]]; then
        echo "Error: INI file not found: $file" >&2
        return 1
    fi

    INI_SECTIONS=("default")

    while IFS= read -r line || [[ -n "$line" ]]; do
        # Skip comments and empty lines
        [[ "$line" =~ ^[[:space:]]*[#\;] ]] && continue
        [[ -z "${line// /}" ]] && continue

        # Section header
        if [[ "$line" =~ ^\[([^\]]+)\] ]]; then
            current_section="${BASH_REMATCH[1]}"
            INI_SECTIONS+=("$current_section")
            continue
        fi

        # Key=value within section
        if [[ "$line" =~ ^([^=]+)=(.*)$ ]]; 
             key=
             value=

            
            key=
            key=
            value=
            value=

            
            INI_CONFIG[]=
        
     < 
}


() {
     section=
     key=
     default=

     
}


() {
     section=
     prefix=

     key  ; 
         [[  == * ]]; 
             
        
    
}


() {
       |  -u
}


parse_ini 


DB_HOST=$(ini_get   )
DB_PORT=$(ini_get   )
LOG_LEVEL=$(ini_get   )

 
 


 
 key  $(ini_section_keys ); 
     

5. Environment Variable Configuration

Load configuration with environment variable overrides:

#!/bin/bash
# ABOUTME: Configuration with environment variable overrides
# ABOUTME: File config < Environment variable precedence

declare -A APP_CONFIG

# Load config with env override support
load_config_with_env() {
    local file="$1"
    local prefix="${2:-APP_}"  # Environment variable prefix

    # First load from file
    if [[ -f "$file" ]]; then
        while IFS= read -r line || [[ -n "$line" ]]; do
            [[ "$line" =~ ^[[:space:]]*# ]] && continue
            [[ -z "${line// /}" ]] && continue

            if [[ "$line" =~ ^([^=]+)=(.*)$ ]]; then
                local key="${BASH_REMATCH[1]}"
                local value="${BASH_REMATCH[2]}"

                key="${key#"${key%%[![:space:]]*}"}"
                key="${key%"${key##*[![:space:]]}"}"

                APP_CONFIG["$key"]="$value"
            
         < 
    

    
     key  ; 
         env_key=  
        env_key=          

         [[ -v  ]]; 
            APP_CONFIG[]=
        
    
}


() {
     missing=()

     key  ; 
         [[ -z  ]]; 
            missing+=()
        
    

     [[  -gt 0 ]]; 
          >&2
           >&2
         1
    

     0
}


() {
     key=
     default=
     
}

() {
     key=
     default=
     value=

     [[  =~ ^-?[0-9]+$ ]]; 
         
    
         
    
}

() {
     key=
     default=
     value=

      
        ||1|on)   ;;
        |no|0|off)   ;;
        *)   ;;
    
}


load_config_with_env  


require_config   ||  1


PORT=$(config_int  8080)
DEBUG=$(config_bool  )
API_KEY=$(config_string )

 

6. YAML Configuration (via yq)

Parse YAML files when yq is available:

#!/bin/bash
# ABOUTME: YAML configuration parsing with yq
# ABOUTME: Falls back to jq for JSON subset of YAML

# Check for yaml parser
get_yaml_parser() {
    if command -v yq &> /dev/null; then
        echo "yq"
    elif command -v jq &> /dev/null; then
        echo "jq"  # Can parse YAML's JSON subset
    else
        echo "none"
    fi
}

# Load YAML config
load_yaml_config() {
    local file="$1"
    local parser
    parser=$(get_yaml_parser)

    if [[ ! -f "$file" ]]; then
        echo "{}"
        return 1
    fi

    case "$parser" in
        yq)
            yq -o=json "$file" 2>/dev/null || echo "{}"
            ;;
        jq)
            # Try to parse as JSON (YAML subset)
            jq '.' "$file" 2>/dev/null || echo "{}"
            ;;
        *)
              >&2
             
             1
            ;;
    
}


() {
     file=
     path=
     default=

     parser
    parser=$(get_yaml_parser)

     value
      
        yq)
            value=$(yq -r   2>/dev/null)
            ;;
        jq)
            value=$(jq -r   2>/dev/null)
            ;;
        *)
            value=
            ;;
    

     [[ -z  ||  ==  ]]; 
         
    
         
    
}


CONFIG_FILE=


CONFIG_JSON=$(load_yaml_config )


DB_HOST=$(yaml_get   )
DB_PORT=$(yaml_get   )

 

Complete Example: Config Manager

Full configuration management with multiple formats:

#!/bin/bash
# ABOUTME: Universal configuration manager
# ABOUTME: Supports key=value, JSON, and environment overrides

set -e

# ─────────────────────────────────────────────────────────────────
# Configuration Storage
# ─────────────────────────────────────────────────────────────────

declare -A CONFIG
CONFIG_FILE=""
CONFIG_FORMAT=""

# ─────────────────────────────────────────────────────────────────
# Format Detection
# ─────────────────────────────────────────────────────────────────

detect_format() {
    local file="$1"

    case "${file##*.}" in
        json) echo "json" ;;
        yaml|yml) echo "yaml" ;;
        ini) echo "ini" ;;
        *) echo "keyvalue" ;;
    esac
}

# ─────────────────────────────────────────────────────────────────
# Loaders
# ─────────────────────────────────────────────────────────────────

load_keyvalue() {
    local file="$1"

    while IFS= read -r line || [[ -n "$line" ]]; do
        [[ "$line" =~ ^[[:space:]]*# ]] && 
        [[ -z  ]] && 

         [[  =~ ^([^=]+)=(.*)$ ]]; 
             key=
             value=
            value=
            CONFIG[]=
        
     < 
}

() {
     file=

     !  -v jq &> /dev/null; 
          >&2
         1
    

    
     IFS=  -r key value; 
        CONFIG[]=
     < <(jq -r   2>/dev/null)
}





() {
     file=
     env_prefix=

     [[ ! -f  ]]; 
          >&2
         1
    

    CONFIG=()
    CONFIG_FILE=
    CONFIG_FORMAT=$(detect_format )

      
        json) load_json  ;;
        *) load_keyvalue  ;;
    

    
     [[ -n  ]]; 
         key  ; 
             env_key=
            env_key=
            env_key=

             [[ -v  ]]; 
                CONFIG[]=
            
        
    

     
}

() {
     key=
     default=
     
}

() {
     key=
     value=
    CONFIG[]=
}

() {
    [[ -v CONFIG[] ]]
}

() {
       | 
}

() {
     
     key  $(config_keys); 
         
    
}

() {
     json=

     key  ; 
        json=$(  | jq --arg k  --arg v  )
    

      | jq 
}





() {
     missing=()

     key  ; 
         ! config_has  || [[ -z  ]]; 
            missing+=()
        
    

     [[  -gt 0 ]]; 
          >&2
           >&2
         1
    
}

() {
     key=
     value
    value=$(config_get )

     [[ -n  && !  =~ ^-?[0-9]+$ ]]; 
          >&2
         1
    
}

() {
     key=
     value
    value=$(config_get )

     [[ -n  && !  =~ ^https?:// ]]; 
          >&2
         1
    
}





 [[  ==  ]]; 
    
    config_load  

    
    config_require   ||  1

    
    config_validate_int  ||  1
    config_validate_url  ||  1

    
     
     

    
     
    config_dump

Best Practices

1. Always Provide Defaults

value=$(config_get "key" "default_value")

2. Validate Early

config_require "api_key" "database_url" || exit 1

3. Use Environment Overrides for Secrets

# Don't store secrets in files
API_KEY="${API_KEY:-$(config_get 'api_key')}"

4. Validate JSON with jq

if ! jq empty "$file" 2>/dev/null; then
    echo "Invalid JSON" >&2
    exit 1
fi

5. Handle Missing Files Gracefully

if [[ -f "$config_file" ]]; then
    load_config "$config_file"
else
    echo "Warning: Config not found, using defaults" >&2
fi

Resources

• jq Manual
• yq Documentation
• Bash Associative Arrays

---

Version History

• 1.0.0 (2026-01-14): Initial release - extracted from workspace-hub configuration scripts