Tab Conversion Utility: tabconv

Unified C utility for converting between tabs and spaces in source code files while preserving proper indentation and formatting.

• tabconv: Unified utility with multiple conversion modes (tabs↔spaces)
• Default mode: Convert tabs to spaces (backward compatible with tospaces)
• Tab mode: Convert spaces to tabs with --tabs flag (backward compatible with totabs)

Table of Contents

• Overview
• Utilities
• Features
• Installation
• Usage
• How It Works
• Error Codes
• Testing
• Project Structure
• Limitations
• Contributing
• License
• Documentation

Overview

These utilities are designed to enforce consistent coding conventions by converting between tab characters and spaces. They maintain proper column alignment and handle edge cases like multiple consecutive tabs/spaces and mixed content.

Utilities

tabconv - Unified Tab Conversion Utility

A unified utility that can convert between tabs and spaces with configurable tab width. Maintains proper indentation by tracking column positions and calculating appropriate spacing.

Default mode (tabs→spaces): ./tabconv <tab-width> <file(s)> Tab mode (spaces→tabs): ./tabconv --tabs <tab-width> <file(s)> Help: ./tabconv --help

Key Features:

• Multiple conversion modes: Tabs to spaces (default), spaces to tabs (--tabs), auto-normalise (--normalize)
• Multiple file support: Process multiple files in a single command
• Backward compatibility: Default mode matches tospaces behaviour, --tabs flag matches totabs behaviour
• Command-line options: Standard GNU-style long options (--help, --verbose, etc.)

Features

• Configurable Tab Width: Specify any number of spaces per tab (2, 4, 8, etc.)
• Column Tracking: Maintains current column position for proper spacing calculations
• Safe File Processing: Uses temporary files to avoid data loss
• Error Handling: Comprehensive error checking with descriptive messages
• Minimal Dependencies: Only uses standard C libraries (stdio.h, stdlib.h)

Installation

Compilation

gcc -o tabconv tabconv.c

This will create an executable named tabconv in the current directory.

Using Makefile

Alternatively, you can use the provided Makefile:

make

This will compile the tabconv executable. Additional make targets:

• make test - Build and run the test suite
• make clean - Remove generated files
• make debug - Build with debug symbols
• make release - Build with optimisations
• make install - Install system-wide (requires sudo)

Optional: Install System-wide

sudo cp tabconv /usr/local/bin/

Usage

Basic Syntax

./tabconv [OPTIONS] <tab-width> <file(s)>

Conversion Modes

• Default (tabs→spaces): Convert tabs to spaces (backward compatible with tospaces)
• Tab mode (--tabs): Convert spaces to tabs (backward compatible with totabs)
• Normalise mode (--normalize): Auto-detect and convert to specified style
• Check mode (--check): Verify indentation consistency without modifying files (not yet implemented)

Common Options

• -s, --spaces : Convert tabs to spaces (default)
• -t, --tabs : Convert spaces to tabs
• -n, --normalize : Auto-detect and convert (normalise)
• -c, --check : Check only, don't modify (future)
• -v, --verbose : Show detailed output
• -b, --backup : Create backup copies before modification
• -h, --help : Show help message

Arguments

• <tab-width>: Tab width in spaces (positive integer, e.g., 2, 4, 8)
• <file(s)>: One or more files to process (supports wildcards: *.c *.h)

Examples

Basic Conversion

# Convert tabs to 4 spaces (default mode)
./tabconv 4 file.c

# Convert spaces to tabs (4-space tab width)
./tabconv --tabs 4 file.c

# Convert tabs to 2 spaces
./tabconv 2 script.py

# Convert spaces to tabs with 8-space width
./tabconv --tabs 8 index.html

Multiple Files

# Process all C source files
./tabconv 4 *.c *.h

# Process all Python files with 2-space tabs
./tabconv 2 *.py

# Convert spaces to tabs in multiple files
./tabconv --tabs 4 src/**/*.java

Advanced Usage

# Verbose output showing processing details
./tabconv --verbose 4 file.c

# Create backup before conversion (default mode)
./tabconv --backup 4 file.c

# Create backup with spaces-to-tabs conversion
./tabconv --tabs --backup 4 file.c

# Show help
./tabconv --help

# Default mode (equivalent to old tospaces)
./tabconv 4 file.c

# Tab mode (equivalent to old totabs)
./tabconv --tabs 4 file.c

How It Works

The tool reads files character by character, tracking column positions to maintain proper indentation. It processes each character according to the selected conversion mode and writes the result to a temporary file before replacing the original.

Tabs to spaces: For each tab character, it calculates the spaces needed to reach the next tab stop based on the current column and tab width, then outputs the appropriate number of spaces.

Spaces to tabs: Consecutive spaces are grouped and replaced with tabs where possible, optimising indentation while preserving alignment.

Normalise mode: Analyses the first 100 lines to detect the existing indentation style (tabs, spaces, or mixed), then automatically converts to the specified tab width using the appropriate algorithm.

Temporary files follow the pattern filename.}}{{ and are cleaned up after successful processing.

Error Codes

The program returns the following exit codes:

• 0: Success
• 1: Error (incorrect arguments, file cannot be opened, temporary file creation failed, etc.)

All errors return exit code 1 with a descriptive error message printed to stderr using perror().

Testing

The repository includes comprehensive testing for the unified utility:

• test_suite.c: Complete unit test suite covering tabs→spaces, spaces→tabs, and normalise mode conversions
• test_results.md: Test cases and verification results

Running Tests

To run all tests:

make test

This will compile the tabconv utility and run the full test suite.

Manual Testing Examples

Test tabs→spaces conversion:

# Create a test file with tabs
echo -e "Line1\tTab\nLine2\t\tDoubleTab" > test.txt

# Convert tabs to 4 spaces (default mode)
./tabconv 4 test.txt

# View the result
cat test.txt

Test spaces→tabs conversion:

# Create a test file with spaces
echo -e "Line1    Tab\nLine2        DoubleTab" > test.txt

# Convert spaces to tabs (4-space tab width)
./tabconv --tabs 4 test.txt

# View the result
cat test.txt

Project Structure

.
├── tabconv.c              # Unified tab conversion utility source
├── tabconv                # Compiled executable (tabconv)
├── Makefile            # Build configuration and test runner
├── LICENSE.md          # BSD 3-Clause License
├── FUTURE.md           # Feature suggestions and roadmap
├── test_suite.c        # Comprehensive unit test suite
├── test_results.md     # Test cases and results
└── README.md           # This file

Limitations

• Processes one file at a time
• Maximum filename length: 1024 characters

Contributing

This is a simple educational project. Feel free to fork and modify for your own needs. Potential improvements could include:

• Recursive directory processing
• Check mode implementation (--check flag)
• Additional command-line options

License

This project is licensed under the BSD 3-Clause License. See the LICENSE.md file for details.

Documentation

• Source Code: tabconv.c includes detailed Doxygen-style comments explaining the unified conversion algorithm
• Test Suite: test_suite.c contains comprehensive unit tests covering all conversion modes
• Future Plans: See FUTURE.md for feature suggestions and development roadmap

Author

Vlad Shurupov - Creator and maintainer of the tab conversion utility.