bash-ini-parser

Bash INI Parser

Build License Last Commit Stars Issues

A robust shell script library for parsing and manipulating INI configuration files in Bash.

Features

Installation

Simply include the lib_ini.sh script in your project and source it in your shell scripts:

source /path/to/lib_ini.sh

Basic Usage

#!/bin/bash
source ./lib_ini.sh

# Create a new INI file with sections and keys
CONFIG_FILE="config.ini"
ini_add_section "$CONFIG_FILE" "app"
ini_write "$CONFIG_FILE" "app" "name" "My Application"
ini_write "$CONFIG_FILE" "app" "version" "1.0.0"

# Read values
app_name=$(ini_read "$CONFIG_FILE" "app" "name")
echo "App name: $app_name"

# List sections and keys
echo "Available sections:"
ini_list_sections "$CONFIG_FILE" | while read section; do
    echo "- $section"
    echo "  Keys:"
    ini_list_keys "$CONFIG_FILE" "$section" | while read key; do
        value=$(ini_read "$CONFIG_FILE" "$section" "$key")
        echo "  - $key = $value"
    done
done

# Remove a key
ini_remove_key "$CONFIG_FILE" "app" "name"

# Remove a section
ini_remove_section "$CONFIG_FILE" "app"

Advanced Features

Array Support

# Write array values
ini_write_array "$CONFIG_FILE" "app" "supported_formats" "jpg" "png" "gif"

# Read array values
formats=$(ini_read_array "$CONFIG_FILE" "app" "supported_formats")
for format in $formats; do
    echo "Format: $format"
done

Default Values

# Get a value or use a default if not found
timeout=$(ini_get_or_default "$CONFIG_FILE" "app" "timeout" "30")

Environment Variables Export

# Export all INI values to environment variables with a prefix
ini_to_env "$CONFIG_FILE" "CFG"
echo "App name from env: $CFG_app_name"

# Export only one section
ini_to_env "$CONFIG_FILE" "CFG" "database"

File Import

# Import all values from one INI file to another
ini_import "defaults.ini" "config.ini"

# Import only specific sections
ini_import "defaults.ini" "config.ini" "section1" "section2"

Key Existence Check

if ini_key_exists "config.ini" "app" "version"; then
    echo "The key exists"
fi

File Validation

# Validate the structure of an INI file
if ini_validate "config.ini"; then
    echo "File is valid"
else
    echo "File has errors"
fi

Get All Keys from a Section

# Get all key=value pairs from a section at once
ini_get_all "config.ini" "app"
# Output:
# name=My Application
# version=1.0.0
# debug=true

Rename Sections and Keys

# Rename a section
ini_rename_section "config.ini" "old_section" "new_section"

# Rename a key within a section
ini_rename_key "config.ini" "app" "old_key" "new_key"

Format INI Files

# Format file with indentation and sorted keys
ini_format "config.ini" 2 1
# Parameters: file, indent_spaces, sort_keys (0=no, 1=yes)

# Basic formatting (no indentation, no sorting)
ini_format "config.ini"

Batch Write Operations

# Write multiple key-value pairs at once
ini_batch_write "config.ini" "app" \
    "name=MyApp" \
    "version=1.0" \
    "debug=true" \
    "timeout=30"

Merge INI Files

# Merge source.ini into target.ini with overwrite strategy
ini_merge "source.ini" "target.ini" "overwrite"

# Available strategies:
# - "overwrite": Replace existing values with source values
# - "skip": Keep existing values, only add new keys
# - "merge": Append source values to existing values (comma-separated)

# Merge only specific sections
ini_merge "source.ini" "target.ini" "overwrite" "section1" "section2"

Export to JSON and YAML

# Export to JSON (compact format)
ini_to_json "config.ini" 0

# Export to JSON (pretty format with indentation)
ini_to_json "config.ini" 1

# Export to YAML (default 2-space indent)
ini_to_yaml "config.ini"

# Export to YAML (custom indent)
ini_to_yaml "config.ini" 4

Configuration Options

The library’s behavior can be customized by setting these variables either directly in your script after sourcing the library or as environment variables before sourcing the library:

# Method 1: Set in your script after sourcing
source ./lib_ini.sh
INI_DEBUG=1

# Method 2: Set as environment variables before sourcing
export INI_DEBUG=1
source ./lib_ini.sh

Available configuration options:

# Enable debug mode to see detailed operations
INI_DEBUG=1

# Enable strict validation of section and key names
INI_STRICT=1

# Allow empty values
INI_ALLOW_EMPTY_VALUES=1

# Allow spaces in section and key names
INI_ALLOW_SPACES_IN_NAMES=1

Library Enhancements

Security Improvements

Core Function Enhancements

File Operations

Reading and Writing

Utility Functions

Advanced Functions

Advanced Usage Examples

Working with Multiple Files

# Import default settings, then override with user settings
ini_import "defaults.ini" "config.ini"
ini_import "user_prefs.ini" "config.ini"

# Copy specific sections between files
ini_import "source.ini" "target.ini" "section1" "section2"

Integration with Database Scripts

# Load database configuration into environment variables
ini_to_env "database.ini" "DB"

# Use in database commands
mysql -h "$DB_mysql_host" -u "$DB_mysql_user" -p"$DB_mysql_password" "$DB_mysql_database"

Array Manipulation

# Store a list of roles in an array
ini_write_array "config.ini" "permissions" "roles" "admin" "user" "guest"

# Read and process array values
roles=$(ini_read_array "config.ini" "permissions" "roles")
for role in $roles; do
    echo "Processing role: $role"
    # Additional processing...
done

Examples

Check the examples directory for complete usage examples:

Testing

Run the comprehensive test suite:

make test

The test suite includes:

Total: 146 tests covering all library functionality.

License

This project is licensed under the BSD License, a permissive free software license with minimal restrictions on the use and distribution of covered software.

Author

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

This site is open source. Improve this page.