purescript-printf

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

spago install printf

• 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

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"

The module supports the following format specifiers:

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 -

• %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  "

• %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  "

• %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"

Use %% to output a literal percent sign:

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

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

• 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

• 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

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

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

-- 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      "

To run the test suite:

spago test

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

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

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