String-Sprintf

The String::Sprintf Perl module

https://github.com/briandfoy/string-sprintf

Keywords

Repository

The String::Sprintf Perl module

README

INSTALLATION

You should be able to use this set of instructions to install the module:

perl Makefile.PL
make
make test
make install

If you are on a windows box you should use 'nmake' rather than 'make'.

If you don't have (n)make then you can install the module manually by simply
copying the contents of the 'lib' subdirectory from the archive, into a
directory that is in @INC, for example the subdirectory site/lib, somewhere
in the perl file tree. Run this one-liner to see your default options.

  perl -le "print for @INC"

Alternatively, put it in a place that you add to @INC yourself, using
"use lib", the command line switch "-I", or the environment variable
"PERL5LIB".

You can manually run the tests, before installation, by running the following
command line for each test file in the subdirectory "t", from the directory
that contains the Makefile.PL:

  perl -Ilib t/001_load.t


What follows, is a text only rendering of the docs.
NAME
    String::Sprintf - Custom overloading of sprintf

SYNOPSIS
        use String::Sprintf;
        my $f = String::Sprintf->formatter(
          N => sub {
            my($width, $value, $values, $letter) = @_;
            return commify(sprintf "%${width}f", $value);
          }
        );

        my $out = $f->sprintf('(%10.2N, %10.2N)', 12345678.901, 87654.321);
        print "Formatted result: $out\n";

        sub commify {
            my $n = shift;
            $n =~ s/(\.\d+)|(?<=\d)(?=(?:\d\d\d)+\b)/$1 || ','/ge;
            return $n;
        }

DESCRIPTION
    How often has it happened that you wished for a format that (s)printf
    just doesn't support? Have you ever wished you could overload sprintf
    with custom formats? Well, I know I have. And this module provides a way
    to do just that.

USAGE
    So what is a formatter? Think of it as a "thing" that contains custom
    settings and behaviour for sprintf. Any formatting style that you don't
    set ("overload") falls back to the built-in keyword sprintf.

    You can make a minimal formatter that behaves just like sprintf (and
    that is actually using sprintf internally) with:

      # nothing custom, all default:
      my $default = String::Sprintf->formatter();
      print $default->sprintf("%%%02X\n", 35);
      # which produces the same result as:
      print sprintf("%%%02X\n", 35);   # built-in

    Because of the explicit use of these formatters, you can, of course, use
    several different formatters at the same time, even in the same
    expression. That is why it's better that it doesn't actually *really*
    overload the built-in sprintf. Plus, it was far easier to implement this
    way.

    The syntax used is OO Perl, though I don't really consider this as an
    object oriented module.

METHODS
  class method:
   formatter( 'A' => \&formatter_A, 'B' => \&formatter_B, ... )
    A constructor. This returns a formatter object that holds custom
    formatting definitions, each associated with a letter, for its method
    "sprintf". Its arguments consist of hash-like pairs of each a formatting
    letter (case sensitive) and a sub ref that is used for callbacks, and
    that is expected to return the formatted substring.

  callback API
    A callback is supposed to behave like this:

      sub callback {
          my($width, $value, $values, $letter) = @_;
          ...
          return $formatted_string;
      }

   Arguments: my($width, $value, $values, $letter) = @_;
    There are 4 arguments passed to the callback functions, in order of
    descending importance. So the more commonly used parameters come first -
    and yes, that's my mnemonic. They are:

   $width
    The part that got put between the '%' and the letter.

   $value
    The current value from the arguments list, the one you're supposed to
    format.

   $values = \@value
    An array ref containing the whole list of all passed arguments, in case
    you want to support positional indexed values by default, as is done in
    strftime

   $letter
    The letter that caused the callback to be invoked. This is only provided
    for the cases where you use a common callback sub, for more than one
    letter, so you can still distinguish between them.

   return value: a string
    The return value in scalar context of this sub is inserted into the
    final, composed result, as a string.

  instance method:
   sprintf($formatstring, $value1, $value2, ...)
    This method inserts the values you pass to it into the formatting
    string, and returns the constructed string. Just like the built-in
    sprintf does.

    If you're using formatting letters that are *not* provided when you
    built the formatter, then it will fall back to the native formatter:
    "sprintf" in perlfunc. So you need only to provide formatters for which
    you're not happy with the built-ins.

EXPORTS
    Nothing. What did you expect?

TODO
    Support for overloading strftime is planned for the next release (soon),
    and proper support for position indexed values, like "%2$03X", is next
    (also soon).

SEE ALSO
    "sprintf" in perlfunc, sprintf(3), "strftime" in POSIX

BUGS
    You tell me...?

SUPPORT
    Poke me at Perlmonks (username "bart" - I'm often hanging around in the
    Chatterbox), or mail me.

AUTHOR
        Bart Lateur
        CPAN ID: BARTL
        Me at home, eating a hotdog
        bart.lateur@pandora.be
        L
        L

COPYRIGHT
    (c) Bart Lateur 2006.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    My personal terms are like this: you can do whatever you want with this
    software: bundle it with any software, be it for free, released under
    the GPL, or commercial; you may redistribute it by itself, fix bugs, add
    features, and redistribute the modified copy. I would appreciate being
    informed in case you do the latter.

    What you may not do, is sell the software, as a standalone product.

NAME
    String::Sprintf - Custom overloading of sprintf

SYNOPSIS
        use String::Sprintf;
        my $f = String::Sprintf->formatter(
          N => sub {
            my($width, $value, $values, $letter) = @_;
            return commify(sprintf "%${width}f", $value);
          }
        );

        my $out = $f->sprintf('(%10.2N, %10.2N)', 12345678.901, 87654.321);
        print "Formatted result: $out\n";

        sub commify {
            my $n = shift;
            $n =~ s/(\.\d+)|(?<=\d)(?=(?:\d\d\d)+\b)/$1 || ','/ge;
            return $n;
        }

DESCRIPTION
    How often has it happened that you wished for a format that (s)printf
    just doesn't support? Have you ever wished you could overload sprintf
    with custom formats? Well, I know I have. And this module provides a way
    to do just that.

USAGE
    So what is a formatter? Think of it as a "thing" that contains custom
    settings and behaviour for sprintf. Any formatting style that you don't
    set ("overload") falls back to the built-in keyword sprintf.

    You can make a minimal formatter that behaves just like sprintf (and
    that is actually using sprintf internally) with:

      # nothing custom, all default:
      my $default = String::Sprintf->formatter();
      print $default->sprintf("%%%02X\n", 35);
      # which produces the same result as:
      print sprintf("%%%02X\n", 35);   # built-in

    Because of the explicit use of these formatters, you can, of course, use
    several different formatters at the same time, even in the same
    expression. That is why it's better that it doesn't actually *really*
    overload the built-in sprintf. Plus, it was far easier to implement this
    way.

    The syntax used is OO Perl, though I don't really consider this as an
    object oriented module.

METHODS
  class method:
   formatter( 'A' => \&formatter_A, 'B' => \&formatter_B, ... )
    A constructor. This returns a formatter object that holds custom
    formatting definitions, each associated with a letter, for its method
    "sprintf". Its arguments consist of hash-like pairs of each a formatting
    letter (case sensitive) and a sub ref that is used for callbacks, and
    that is expected to return the formatted substring.

  callback API
    A callback is supposed to behave like this:

      sub callback {
          my($width, $value, $values, $letter) = @_;
          ...
          return $formatted_string;
      }

   Arguments: my($width, $value, $values, $letter) = @_;
    There are 4 arguments passed to the callback functions, in order of
    descending importance. So the more commonly used parameters come first -
    and yes, that's my mnemonic. They are:

   $width
    The part that got put between the '%' and the letter.

   $value
    The current value from the arguments list, the one you're supposed to
    format.

   $values = \@value
    An array ref containing the whole list of all passed arguments, in case
    you want to support positional indexed values by default, as is done in
    strftime

   $letter
    The letter that caused the callback to be invoked. This is only provided
    for the cases where you use a common callback sub, for more than one
    letter, so you can still distinguish between them.

   return value: a string
    The return value in scalar context of this sub is inserted into the
    final, composed result, as a string.

  instance method:
   sprintf($formatstring, $value1, $value2, ...)
    This method inserts the values you pass to it into the formatting
    string, and returns the constructed string. Just like the built-in
    sprintf does.

    If you're using formatting letters that are *not* provided when you
    built the formatter, then it will fall back to the native formatter:
    "sprintf" in perlfunc. So you need only to provide formatters for which
    you're not happy with the built-ins.

EXPORTS
    Nothing. What did you expect?

TODO
    Support for overloading strftime is planned for the next release (soon),
    and proper support for position indexed values, like "%2$03X", is next
    (also soon).

SEE ALSO
    "sprintf" in perlfunc, sprintf(3), "strftime" in POSIX

BUGS
    You tell me...?

SUPPORT
    Poke me at Perlmonks (username "bart" - I'm often hanging around in the
    Chatterbox), or mail me.

AUTHOR
        Bart Lateur
        CPAN ID: BARTL
        Me at home, eating a hotdog
        bart.lateur@pandora.be
        L
        L

COPYRIGHT
    (c) Bart Lateur 2006.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    My personal terms are like this: you can do whatever you want with this
    software: bundle it with any software, be it for free, released under
    the GPL, or commercial; you may redistribute it by itself, fix bugs, add
    features, and redistribute the modified copy. I would appreciate being
    informed in case you do the latter.

    What you may not do, is sell the software, as a standalone product.

NAME
    String::Sprintf - Custom overloading of sprintf

SYNOPSIS
        use String::Sprintf;
        my $f = String::Sprintf->formatter(
          N => sub {
            my($width, $value, $values, $letter) = @_;
            return commify(sprintf "%${width}f", $value);
          }
        );

        my $out = $f->sprintf('(%10.2N, %10.2N)', 12345678.901, 87654.321);
        print "Formatted result: $out\n";

        sub commify {
            my $n = shift;
            $n =~ s/(\.\d+)|(?<=\d)(?=(?:\d\d\d)+\b)/$1 || ','/ge;
            return $n;
        }

DESCRIPTION
    How often has it happened that you wished for a format that (s)printf
    just doesn't support? Have you ever wished you could overload sprintf
    with custom formats? Well, I know I have. And this module provides a way
    to do just that.

USAGE
    So what is a formatter? Think of it as a "thing" that contains custom
    settings and behaviour for sprintf. Any formatting style that you don't
    set ("overload") falls back to the built-in keyword sprintf.

    You can make a minimal formatter that behaves just like sprintf (and
    that is actually using sprintf internally) with:

      # nothing custom, all default:
      my $default = String::Sprintf->formatter();
      print $default->sprintf("%%%02X\n", 35);
      # which produces the same result as:
      print sprintf("%%%02X\n", 35);   # built-in

    Because of the explicit use of these formatters, you can, of course, use
    several different formatters at the same time, even in the same
    expression. That is why it's better that it doesn't actually *really*
    overload the built-in sprintf. Plus, it was far easier to implement this
    way.

    The syntax used is OO Perl, though I don't really consider this as an
    object oriented module. For example, I foresee no reason for
    subclassing.

METHODS
  class method:
   formatter( 'A' => \&formatter_A, 'B' => \&formatter_B, ... )
    A constructor. This returns a formatter object that holds custom
    formatting definitions, each associated with a letter, for its method
    "sprintf". Its arguments consist of hash-like pairs of each a formatting
    letter (case sensitive) and a sub ref that is used for callbacks, and
    that is expected to return the formatted substring.

  callback API
    A callback is supposed to behave like this:

      sub callback {
          my($width, $value, $values, $letter) = @_;
          ...
          return $formatted_string;
      }

   Arguments: my($width, $value, $values, $letter) = @_;
    There are 4 arguments passed to the callback functions, in order of
    descending importance. So the more commonly used parameters come first -
    and yes, that's my mnemonic. They are:

   $width
    The part that got put between the '%' and the letter.

   $value
    The current value from the arguments list, the one you're supposed to
    format.

   $values = \@value
    An array ref containing the whole list of all passed arguments, in case
    you want to support positional indexed values by default, as is done in
    strftime

   $letter
    The letter that caused the callback to be invoked. This is only provided
    for the cases where you use a common callback sub, for more than one
    letter, so you can still distinguish between them.

   return value: a string
    The return value in scalar context of this sub is inserted into the
    final, composed result, as a string.

  instance method:
   sprintf($formatstring, $value1, $value2, ...)
    This method inserts the values you pass to it into the formatting
    string, and returns the constructed string. Just like the built-in
    sprintf does.

    If you're using formatting letters that are *not* provided when you
    built the formatter, then it will fall back to the native formatter:
    "sprintf" in perlfunc. So you need only to provide formatters for which
    you're not happy with the built-ins.

EXPORTS
    Nothing. What did you expect?

TODO
    Support for overloading strftime is planned for the next release (soon),
    and proper support for position indexed values, like "%2$03X", is next
    (also soon).

SEE ALSO
    "sprintf" in perlfunc, sprintf(3), "strftime" in POSIX

BUGS
    You tell me...?

SUPPORT
    Poke me at Perlmonks (username "bart" - I'm often hanging around in the
    Chatterbox), or mail me.

AUTHOR
        Bart Lateur
        CPAN ID: BARTL
        Me at home, eating a hotdog
        bart.lateur@pandora.be
        L
        L

COPYRIGHT
    (c) Bart Lateur 2006.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    My personal terms are like this: you can do whatever you want with this
    software: bundle it with any software, be it for free, released under
    the GPL, or commercial; you may redistribute it by itself, fix bugs, add
    features, and redistribute the modified copy. I would appreciate being
    informed in case you do the latter.

    What you may not do, is sell the software, as a standalone product.

NAME
    String::Sprintf - Custom overloading of sprintf

SYNOPSIS
        use String::Sprintf;
        my $f = String::Sprintf->formatter(
          N => sub {
            my($width, $value, $values, $letter) = @_;
            return commify(sprintf "%${width}f", $value);
          }
        );

        my $out = $f->sprintf('(%10.2N, %10.2N)', 12345678.901, 87654.321);
        print "Formatted result: $out\n";

        sub commify {
            my $n = shift;
            $n =~ s/(\.\d+)|(?<=\d)(?=(?:\d\d\d)+\b)/$1 || ','/ge;
            return $n;
        }

DESCRIPTION
    How often has it happened that you wished for a format that (s)printf
    just doesn't support? Have you ever wished you could overload sprintf
    with custom formats? Well, I know I have. And this module provides a way
    to do just that.

USAGE
    So what is a formatter? Think of it as a "thing" that contains custom
    settings and behaviour for sprintf. Any formatting style that you don't
    set ("overload") falls back to the built-in keyword sprintf.

    You can make a minimal formatter that behaves just like sprintf (and
    that is actually using sprintf internally) with:

      # nothing custom, all default:
      my $default = String::Sprintf->formatter();
      print $default->sprintf("%%%02X\n", 35);
      # which produces the same result as:
      print sprintf("%%%02X\n", 35);   # built-in

    Because of the explicit use of these formatters, you can, of course, use
    several different formatters at the same time, even in the same
    expression. That is why it's better that it doesn't actually *really*
    overload the built-in sprintf. Plus, it was far easier to implement this
    way.

    The syntax used is OO Perl, though I don't really consider this as an
    object oriented module. For example, I foresee no reason for
    subclassing.

METHODS
  class method:
   formatter( 'A' => \&formatter_A, 'B' => \&formatter_B, ... )
    A constructor. This returns a formatter object that holds custom
    formatting definitions, each associated with a letter, for its method
    "sprintf". Its arguments consist of hash-like pairs of each a formatting
    letter (case sensitive) and a sub ref that is used for callbacks, and
    that is expected to return the formatted substring.

  callback API
    A callback is supposed to behave like this:

      sub callback {
          my($width, $value, $values, $letter) = @_;
          ...
          return $formatted_string;
      }

   Arguments: my($width, $value, $values, $letter) = @_;
    There are 4 arguments passed to the callback functions, in order of
    descending importance. So the more commonly used parameters come first -
    and yes, that's my mnemonic. They are:

   $width
    The part that got put between the '%' and the letter.

   $value
    The current value from the arguments list, the one you're supposed to
    format.

   $values = \@value
    An array ref containing the whole list of all passed arguments, in case
    you want to support positional indexed values by default, as is done in
    strftime

   $letter
    The letter that caused the callback to be invoked. This is only provided
    for the cases where you use a common callback sub, for more than one
    letter, so you can still distinguish between them.

   return value: a string
    The return value in scalar context of this sub is inserted into the
    final, composed result, as a string.

  instance method:
   sprintf($formatstring, $value1, $value2, ...)
    This method inserts the values you pass to it into the formatting
    string, and returns the constructed string. Just like the built-in
    sprintf does.

    If you're using formatting letters that are *not* provided when you
    built the formatter, then it will fall back to the native formatter:
    "sprintf" in perlfunc. So you need only to provide formatters for which
    you're not happy with the built-ins.

EXPORTS
    Nothing. What did you expect?

TODO
    Support for overloading strftime is planned for the next release (soon),
    and proper support for position indexed values, like "%2$03X", is next
    (also soon).

SEE ALSO
    "sprintf" in perlfunc, sprintf(3), "strftime" in POSIX

BUGS
    You tell me...?

SUPPORT
    Poke me at Perlmonks (username "bart" - I'm often hanging around in the
    Chatterbox), or mail me.

AUTHOR
        Bart Lateur
        CPAN ID: BARTL
        Me at home, eating a hotdog
        bart.lateur@pandora.be
        L
        L

COPYRIGHT
    (c) Bart Lateur 2006.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    My personal terms are like this: you can do whatever you want with this
    software: bundle it with any software, be it for free, released under
    the GPL, or commercial; you may redistribute it by itself, fix bugs, add
    features, and redistribute the modified copy. I would appreciate being
    informed in case you do the latter.

    What you may not do, is sell the software, as a standalone product.

NAME
    String::Sprintf - Custom overloading of sprintf

SYNOPSIS
        use String::Sprintf;
        my $f = String::Sprintf->formatter(
          N => sub {
            my($width, $value, $values, $letter) = @_;
            return commify(sprintf "%${width}f", $value);
          }
        );

        my $out = $f->sprintf('(%10.2N, %10.2N)', 12345678.901, 87654.321);
        print "Formatted result: $out\n";

        sub commify {
            my $n = shift;
            $n =~ s/(\.\d+)|(?<=\d)(?=(?:\d\d\d)+\b)/$1 || ','/ge;
            return $n;
        }

DESCRIPTION
    How often has it happened that you wished for a format that (s)printf
    just doesn't support? Have you ever wished you could overload sprintf
    with custom formats? Well, I know I have. And this module provides a way
    to do just that.

USAGE
    So what is a formatter? Think of it as a "thing" that contains custom
    settings and behaviour for sprintf. Any formatting style that you don't
    set ("overload") falls back to the built-in keyword sprintf.

    You can make a minimal formatter that behaves just like sprintf (and
    that is actually using sprintf internally) with:

      # nothing custom, all default:
      my $default = String::Sprintf->formatter();
      print $default->sprintf("%%%02X\n", 35);
      # which produces the same result as:
      print sprintf("%%%02X\n", 35);   # built-in

    Because of the explicit use of these formatters, you can, of course, use
    several different formatters at the same time, even in the same
    expression. That is why it's better that it doesn't actually *really*
    overload the built-in sprintf. Plus, it was far easier to implement this
    way.

    The syntax used is OO Perl, though I don't really consider this as an
    object oriented module. For example, I foresee no reason for
    subclassing, and all formatters behave differently. That's what they're
    for.

METHODS
  class method:
   formatter( 'A' => \&formatter_A, 'B' => \&formatter_B, ... )
    A constructor. This returns a formatter object that holds custom
    formatting definitions, each associated with a letter, for its method
    "sprintf". Its arguments consist of hash-like pairs of each a formatting
    letter (case sensitive) and a sub ref that is used for callbacks, and
    that is expected to return the formatted substring.

  callback API
    A callback is supposed to behave like this:

      sub callback {
          my($width, $value, $values, $letter) = @_;
          ...
          return $formatted_string;
      }

   Arguments: my($width, $value, $values, $letter) = @_;
    There are 4 arguments passed to the callback functions, in order of
    descending importance. So the more commonly used parameters come first -
    and yes, that's my mnemonic. They are:

   $width
    The part that got put between the '%' and the letter.

   $value
    The current value from the arguments list, the one you're supposed to
    format.

   $values = \@value
    An array ref containing the whole list of all passed arguments, in case
    you want to support positional indexed values by default, as is done in
    strftime

   $letter
    The letter that caused the callback to be invoked. This is only provided
    for the cases where you use a common callback sub, for more than one
    letter, so you can still distinguish between them.

   return value: a string
    The return value in scalar context of this sub is inserted into the
    final, composed result, as a string.

  instance method:
   sprintf($formatstring, $value1, $value2, ...)
    This method inserts the values you pass to it into the formatting
    string, and returns the constructed string. Just like the built-in
    sprintf does.

    If you're using formatting letters that are *not* provided when you
    built the formatter, then it will fall back to the native formatter:
    "sprintf" in perlfunc. So you need only to provide formatters for which
    you're not happy with the built-ins.

EXPORTS
    Nothing. What did you expect?

TODO
    Support for overloading strftime is planned for the next release (soon),
    and proper support for position indexed values, like "%2$03X", is next
    (also soon).

SEE ALSO
    "sprintf" in perlfunc, sprintf(3), "strftime" in POSIX

BUGS
    You tell me...?

SUPPORT
    Poke me at Perlmonks (username "bart" - I'm often hanging around in the
    Chatterbox), or mail me.

AUTHOR
        Bart Lateur
        CPAN ID: BARTL
        Me at home, eating a hotdog
        bart.lateur@pandora.be
        L
        L

COPYRIGHT
    (c) Bart Lateur 2006.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    My personal terms are like this: you can do whatever you want with this
    software: bundle it with any software, be it for free, released under
    the GPL, or commercial; you may redistribute it by itself, fix bugs, add
    features, and redistribute the modified copy. I would appreciate being
    informed in case you do the latter.

    What you may not do, is sell the software, as a standalone product.

NAME
    String::Sprintf - Custom overloading of sprintf

SYNOPSIS
        use String::Sprintf;
        my $f = String::Sprintf->formatter(
          N => sub {
            my($width, $value, $values, $letter) = @_;
            return commify(sprintf "%${width}f", $value);
          }
        );

        my $out = $f->sprintf('(%10.2N, %10.2N)', 12345678.901, 87654.321);
        print "Formatted result: $out\n";

        sub commify {
            my $n = shift;
            $n =~ s/(\.\d+)|(?<=\d)(?=(?:\d\d\d)+\b)/$1 || ','/ge;
            return $n;
        }

DESCRIPTION
    How often has it happened that you wished for a format that (s)printf
    just doesn't support? Have you ever wished you could overload sprintf
    with custom formats? Well, I know I have. And this module provides a way
    to do just that.

USAGE
    So what is a formatter? Think of it as a "thing" that contains custom
    settings and behaviour for sprintf. Any formatting style that you don't
    set ("overload") falls back to the built-in keyword sprintf.

    You can make a minimal formatter that behaves just like sprintf (and
    that is actually using sprintf internally) with:

      # nothing custom, all default:
      my $default = String::Sprintf->formatter();
      print $default->sprintf("%%%02X\n", 35);
      # which produces the same result as:
      print sprintf("%%%02X\n", 35);   # built-in

    Because of the explicit use of these formatters, you can, of course, use
    several different formatters at the same time, even in the same
    expression. That is why it's better that it doesn't actually *really*
    overload the built-in sprintf. Plus, it was far easier to implement this
    way.

    The syntax used is OO Perl, though I don't really consider this as an
    object oriented module. For example, I foresee no reason for
    subclassing, and all formatters behave differently. That's what they're
    for.

METHODS
  class method:
   formatter( 'A' => \&formatter_A, 'B' => \&formatter_B, ... )
    A constructor. This returns a formatter object that holds custom
    formatting definitions, each associated with a letter, for its method
    "sprintf". Its arguments consist of hash-like pairs of each a formatting
    letter (case sensitive) and a sub ref that is used for callbacks, and
    that is expected to return the formatted substring.

  callback API
    A callback is supposed to behave like this:

      sub callback {
          my($width, $value, $values, $letter) = @_;
          ...
          return $formatted_string;
      }

   Arguments: my($width, $value, $values, $letter) = @_;
    There are 4 arguments passed to the callback functions, in order of
    descending importance. So the more commonly used parameters come first -
    and yes, that's my mnemonic. They are:

   $width
    The part that got put between the '%' and the letter.

   $value
    The current value from the arguments list, the one you're supposed to
    format.

   $values = \@value
    An array ref containing the whole list of all passed arguments, in case
    you want to support positional indexed values by default, as is done in
    strftime

   $letter
    The letter that caused the callback to be invoked. This is only provided
    for the cases where you use a common callback sub, for more than one
    letter, so you can still distinguish between them.

   return value: a string
    The return value in scalar context of this sub is inserted into the
    final, composed result, as a string.

  instance method:
   sprintf($formatstring, $value1, $value2, ...)
    This method inserts the values you pass to it into the formatting
    string, and returns the constructed string. Just like the built-in
    sprintf does.

    If you're using formatting letters that are *not* provided when you
    built the formatter, then it will fall back to the native formatter:
    "sprintf" in perlfunc. So you need only to provide formatters for which
    you're not happy with the built-ins.

EXPORTS
    Nothing. What did you expect?

TODO
    Support for overloading strftime is planned for the next release (soon),
    and proper support for position indexed values, like "%2$03X", is next
    (also soon).

SEE ALSO
    "sprintf" in perlfunc, sprintf(3), "strftime" in POSIX

BUGS
    You tell me...?

SUPPORT
    Poke me at Perlmonks (username "bart" - I'm often hanging around in the
    Chatterbox), or mail me.

AUTHOR
        Bart Lateur
        CPAN ID: BARTL
        Me at home, eating a hotdog
        bart.lateur@pandora.be
        L
        L

COPYRIGHT
    (c) Bart Lateur 2006.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    My personal terms are like this: you can do whatever you want with this
    software: bundle it with any software, be it for free, released under
    the GPL, or commercial; you may redistribute it by itself, fix bugs, add
    features, and redistribute the modified copy. I would appreciate being
    informed in case you do the latter.

    What you may not do, is sell the software, as a standalone product.

NAME
    String::Sprintf - Custom overloading of sprintf

SYNOPSIS
        use String::Sprintf;
        my $f = String::Sprintf->formatter(
          N => sub {
            my($width, $value, $values, $letter) = @_;
            return commify(sprintf "%${width}f", $value);
          }
        );

        my $out = $f->sprintf('(%10.2N, %10.2N)', 12345678.901, 87654.321);
        print "Formatted result: $out\n";

        sub commify {
            my $n = shift;
            $n =~ s/(\.\d+)|(?<=\d)(?=(?:\d\d\d)+\b)/$1 || ','/ge;
            return $n;
        }

DESCRIPTION
    How often has it happened that you wished for a format that (s)printf
    just doesn't support? Have you ever wished you could overload sprintf
    with custom formats? Well, I know I have. And this module provides a way
    to do just that.

USAGE
    So what is a formatter? Think of it as a "thing" that contains custom
    settings and behaviour for sprintf. Any formatting style that you don't
    set ("overload") falls back to the built-in keyword sprintf.

    You can make a minimal formatter that behaves just like sprintf (and
    that is actually using sprintf internally) with:

      # nothing custom, all default:
      my $default = String::Sprintf->formatter();
      print $default->sprintf("%%%02X\n", 35);
      # which produces the same result as:
      print sprintf("%%%02X\n", 35);   # built-in

    Because of the explicit use of these formatters, you can, of course, use
    several different formatters at the same time, even in the same
    expression. That is why it's better that it doesn't actually *really*
    overload the built-in sprintf. Plus, it was far easier to implement this
    way.

    The syntax used is OO Perl, though I don't really consider this as an
    object oriented module. For example, I foresee no reason for
    subclassing, and all formatters behave differently. That's what they're
    for.

METHODS
  class method:
   formatter( 'A' => \&formatter_A, 'B' => \&formatter_B, ... )
    A constructor. This returns a formatter object that holds custom
    formatting definitions, each associated with a letter, for its method
    "sprintf". Its arguments consist of hash-like pairs of each a formatting
    letter (case sensitive) and a sub ref that is used for callbacks, and
    that is expected to return the formatted substring.

  callback API
    A callback is supposed to behave like this:

      sub callback {
          my($width, $value, $values, $letter) = @_;
          ...
          return $formatted_string;
      }

   Arguments: my($width, $value, $values, $letter) = @_;
    There are 4 arguments passed to the callback functions, in order of
    descending importance. So the more commonly used parameters come first -
    and yes, that's my mnemonic. They are:

   $width
    The part that got put between the '%' and the letter.

   $value
    The current value from the arguments list, the one you're supposed to
    format.

   $values = \@value
    An array ref containing the whole list of all passed arguments, in case
    you want to support positional indexed values by default, as is done in
    strftime

   $letter
    The letter that caused the callback to be invoked. This is only provided
    for the cases where you use a common callback sub, for more than one
    letter, so you can still distinguish between them.

   return value: a string
    The return value in scalar context of this sub is inserted into the
    final, composed result, as a string.

  instance method:
   sprintf($formatstring, $value1, $value2, ...)
    This method inserts the values you pass to it into the formatting
    string, and returns the constructed string. Just like the built-in
    sprintf does.

    If you're using formatting letters that are *not* provided when you
    built the formatter, then it will fall back to the native formatter:
    "sprintf" in perlfunc. So you need only to provide formatters for which
    you're not happy with the built-ins.

EXPORTS
    Nothing. What did you expect?

TODO
    Support for overloading strftime is planned for the next release (soon),
    and proper support for position indexed values, like "%2$03X", is next
    (also soon).

SEE ALSO
    "sprintf" in perlfunc, sprintf(3), "strftime" in POSIX

BUGS
    You tell me...?

SUPPORT
    Poke me at Perlmonks (username "bart" - I'm often hanging around in the
    Chatterbox), or mail me.

AUTHOR
        Bart Lateur
        CPAN ID: BARTL
        Me at home, eating a hotdog
        bart.lateur@pandora.be
        L
        L

COPYRIGHT
    (c) Bart Lateur 2006.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    My personal terms are like this: you can do whatever you want with this
    software: bundle it with any software, be it for free, released under
    the GPL, or commercial; you may redistribute it by itself, fix bugs, add
    features, and redistribute the modified copy. I would appreciate being
    informed in case you do the latter.

    What you may not do, is sell the software, as a standalone product.

Owner

Citation (CITATION.cff)

# This CITATION.cff file was generated with /Users/brian/bin/bmt
# Fri Jan 28 01:19:39 2022

abstract: String::Sprintf - Custom overloading of sprintf
authors:
- alias: briandfoy
  family-names: foy
  given-names: brian d
  orcid: 0000-0002-0283-8283
  email: briandfoy@pobox.com
- family-names: Lateur
  given-names: Bart
  email: bart.lateur@pandora.be
preferred-citation:
   type: software
   title: The String::Sprintf Perl module
   authors:
   - family-names: Lateur
     given-names: Bart
cff-version: 1.2.0
date-released: 2022-01-27
license: perl_5
license-url: https://github.com/briandfoy/string-sprintf/LICENSE
message: The GitHub page for this module provides formatted citations
repository-code: https://github.com/briandfoy/string-sprintf
title: The String::Sprintf Perl module
type: software
version: dev-1

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 7 months ago

Packages