A type-safe implementation of printf-style string formatting for PureScript, providing compile-time format string checking and type inference.

Installation

spago install printf

Features

• Type-safe format strings checked at compile time
• Support for integers, floats, and strings
• Width and alignment control
• Custom padding characters
• Decimal precision for floating point numbers
• Sign control for numeric values
• Multiple format specifiers in a single string
• Escaped percent signs

Usage

import Text.Printf (printf)
import Type.Proxy (Proxy(..))
-- Basic usage
printf (Proxy :: Proxy "Hello, %s!") "world"
-- => "Hello, world!"
printf (Proxy :: Proxy "Number: %d") 42
-- => "Number: 42"
printf (Proxy :: Proxy "Pi: %.2f") 3.14159
-- => "Pi: 3.14"

Format Specifiers

The module supports the following format specifiers:

Format String Syntax

Format specifiers follow this strict pattern:

%[flags][width][.precision]specifier

⚠️ Important: Flag Order Requirements

Flags must appear in the following strict order (when multiple flags are used):

1. + (sign flag)
2. - (alignment flag)
3. Padding specification ('c or 0)

Valid examples:

"%+'_10d"   -- Correct: + then ' for padding
"%-'_10d"   -- Correct: - then ' for padding
"%+-'_10d"  -- Correct: + then - then padding

Invalid examples:

"%'_+10d"   -- Invalid: padding before +
"%-+10d"    -- Invalid: - before +
"%0-10d"    -- Invalid: 0 before -

Integer (%d)

• %d - Basic integer formatting
• %5d - Width specification (right-aligned)
• %-5d - Left-aligned width specification
• %05d - Zero-padded width specification
• %+d - Show sign for positive numbers
• %'_5d - Custom padding character

printf (Proxy :: Proxy "%5d") 42
-- => "   42"
printf (Proxy :: Proxy "%05d") 42
-- => "00042"
printf (Proxy :: Proxy "%-5d") 42
-- => "42   "
printf (Proxy :: Proxy "%+d") 42
-- => "+42"
printf (Proxy :: Proxy "%'_5d") 42
-- => "__42"
-- Complex examples with multiple flags
printf (Proxy :: Proxy "%+'_5d") 42
-- => "__+42"
printf (Proxy :: Proxy "%+-5d") 42
-- => "+42  "

Float (%f)

• %f - Basic float formatting
• %.2f - Precision specification
• %8.2f - Width and precision
• %+f - Show sign for positive numbers
• %-8.2f - Left-aligned with precision

printf (Proxy :: Proxy "%.2f") 3.14159
-- => "3.14"
printf (Proxy :: Proxy "%8.2f") 3.14159
-- => "    3.14"
printf (Proxy :: Proxy "%+.2f") 3.14159
-- => "+3.14"
-- Complex examples with multiple flags
printf (Proxy :: Proxy "%+'_8.2f") 3.14159
-- => "__+3.14"
printf (Proxy :: Proxy "%+-8.2f") 3.14159
-- => "+3.14  "

String (%s)

• %s - Basic string formatting
• %10s - Width specification (right-aligned)
• %-10s - Left-aligned width specification
• %'_10s - Custom padding character

printf (Proxy :: Proxy "%10s") "test"
-- => "      test"
printf (Proxy :: Proxy "%-10s") "test"
-- => "test      "
printf (Proxy :: Proxy "%'_10s") "test"
-- => "______test"

Escaping

Use %% to output a literal percent sign:

printf (Proxy :: Proxy "100%% complete")
-- => "100% complete"

Flag Details

Sign Flag (+)

• Must be the first flag if used
• Applies to numeric types only (d, f)
• Forces display of + for positive numbers

Alignment Flag (-)

• Must come after sign flag (+) if present
• Can be first flag if no sign flag is used
• Left-aligns the output in the specified width

Padding Flag ('c or 0)

• Must come after sign and alignment flags
• 'c allows any character for padding
• 0 is a special case for zero-padding numbers
• Cannot use both 'c and 0

Width and Precision

• Come after all flags
• Width is a positive integer
• Precision starts with . followed by a positive integer
• Only applicable to floating point numbers

Compile-Time Safety

The format string is checked at compile time, ensuring that:

1. The format string is valid
2. Flags are in the correct order
3. The correct number and types of arguments are provided
4. The format specifiers match their corresponding argument types

Examples

-- Multiple formatters
printf (Proxy :: Proxy "Name: %s, Age: %d") "Alice" 30
-- => "Name: Alice, Age: 30"
-- Complex formatting with correct flag order
printf (Proxy :: Proxy "%+'_10.2f") 3.14159
-- => "_____+3.14"
-- Multiple format specifiers with different flags
printf (Proxy :: Proxy "%+d: %-10s") 42 "test"
-- => "+42: test      "

Testing

To run the test suite:

spago test

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

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

Acknowledgments

This implementation is inspired by Haskell's printf and purescript-safe-printf.