3.9. kink/FORMAT

The mod provides str formatting via FORMAT.format.

Example:

:FORMAT.require_from('kink/')
:Str <- FORMAT.format('Addr=0x{%06x} Val={}'){(:F)
  F.args(0xfe10 42)
}
stdout.print_line(Str)
# => Addr=0x00fe10 Val=42

Usually FORMAT.format is used via Str.format. For example, the program above can be rewritten as follows:

stdout.print_line('Addr=0x{%06x} Val={}'.format(0xfe10 42))
# => Addr=0x00fe10 Val=42

FORMAT.format calls .show(...[$show_config]) method of each arg to generate a str which is filled in a placeholder.

3.9.1. FORMAT.format(Template $config)

FORMAT.format generates a str which is formatted according to the Template.

Preconditions:

• Template must be a str which suffices the syntax described below

• $config must be a fun which takes a format_conf val

The Template can contain placeholders delimited by braces "{" and "}". FORMAT.format invokes .show(...[$show_config]) method of the arg corresponding to each placeholder, and emplaces the result str in the placeholder.

There are following variants of placeholders.

• "{}": takes a positional argument, with an empty str "" as the spec.

• "{%xxx}": takes a positional argument, with the spec "xxx".

• "{Foo}": takes a named argument with the name "Foo", with an empty str "" as the spec.

• "{Foo%xxx}": takes a named argument with the name "Foo", with the spec "xxx".

The name str must not contain "{", "}" and "%".

The spec str is passed to Show_conf.spec(Spec) method. The spec str must not contain "{" or "}".

If you want to include literal "{" and "}" in Template, escape them as "{{" and "}}".

Example:

:FORMAT.require_from('kink/')
:Str <- FORMAT.format('foo{{ {} }}'){(:F)
  F.args(42)
}
stdout.print_line(Str)
# => foo{ 42 }

You can specify a locale by calling Format_conf.locale(Locale_name) method. If you do so, the locale name is passed to Show_conf.locale(Locale_name) method, before calling Show_conf.spec method.

Example:

:FORMAT.require_from('kink/')
:Str <- FORMAT.format('Id: {%04d}, Name: {}, Elevation: {%,d} meters'){(:F)
  F.args(12 'Mount Fuji' 3776.24)
}
stdout.print_line(Str)
# => Id: 0012, Name: Mount Fuji, Elevation: 3,776.24 meters

With locale:

:FORMAT.require_from('kink/')
:Str <- FORMAT.format('Id: {%04d}, Name: {}, Elevation: {%,d} meters'){(:F)
  F.locale('da-DK')
  F.args(12 'Mount Fuji' 3776.24)
}
stdout.print_line(Str)
# => Id: 0012, Name: Mount Fuji, Elevation: 3.776,24 meters

Using named args:

:FORMAT.require_from('kink/')
:Str <- FORMAT.format('Id: {Id%04d}, Name: {Name}, Elevation: {Elevation%,d} meters'){(:F)
  F.locale('da-DK')
  F.named_args(
    'Id' 12
    'Name' 'Mount Fuji'
    'Elevation' 3776.24
  )
}
stdout.print_line(Str)
# => Id: 0012, Name: Mount Fuji, Elevation: 3.776,24 meters

3.9.2. type format_conf

A format_conf is a conf val of FORMAT.format fun.

Format_conf.args(... Pos_args)

Format_conf.args specifies positional args.

Preconditions:

• The number of args must be equal to the unnamed placeholders

• Each arg must support .show(...[$show_config]) method

Format_conf.named_args(Name1 Arg1 Name2 Arg2 ,,,)

Format_conf.named_args specifies named args.

Preconditions:

• Name1, Name2 ,,, must be strs

• Arg1, Arg2 ,,, must support .show(...[$show_config]) method

• The set of Name1, Name2 ,,, must be a superset of the names of the named arguments in the Template

Format_conf.locale(Locale_name)

Format_conf.locale specifies the locale name.

Precondition:

• Locale_name must be a str

3.9.3. type show_conf

A show_conf is a conf val type of .show(...[$show_config]) methods.

.show method is expected to return a str which represents the receiver. In contrast to .repr method, which is used for debugging, The result of .show method is intended to be used in UI messages.

Usually, .show methods are called from FORMAT.format. See FORMAT.format for details.

Example usage:

:Shown <- 3776.24.show{(:S)
  S.locale('da-DK')
  S.spec(',d')
}
stdout.print_line(Shown.repr) # => "3.776,24"

An implementation of show_conf type can also implement extra methods such as Num_show_conf.radix and .pad_zero.

For example:

:Shown <- 255.show{(:S)
  S.radix(16)
  S.pad_zero(4)
}
stdout.print_line(Shown.repr) # => "00ff"

Show_conf.locale(Locale_name)

Show_conf.locale specifies the locale which is used to generate the result of .show method.

Precondition:

• Locale_name must be a str

Show_conf.spec(Spec)

Show_conf.spec specifies how the val is converted to a str.

The syntax of the Spec str varies among .show method implementations.