<commit_before>== Parameterized Steps

Step methods can have parameters. Parameters are formatted in reports by using the String.valueOf method, applied to the arguments. The formatted arguments are added to the end of the step description.

[source,java]
----
given().the_ingredient( "flour" ); // Given the ingredient flour
given().multiple_arguments( 5, 6 ); // Given multiple arguments 5 6
----

=== Parameters within a sentence

To place parameters within a sentence instead the end of the sentence you can use the $ character.

[source,java]
----
given().$_eggs( 5 );
----
In the generated report `$` is replaced with the corresponding formatted parameter. So the generated report will look as follows:

----
Given 5 eggs
----

If there are more parameters than `$` characters, the remaining parameters are added to the end of the sentence.

If a `$` should not be treated as a placeholder for a parameter, but printed verbatim, you can write `$$`, which will appear as a single `$` in the report.

=== Custom Annotations

The `@As` annotation can be used to override the shown sentence. To reference arguments you can use the three different interoperable options which apply to every description in JGiven. For more examples look up https://github.com/TNG/JGiven/blob/master/jgiven-core/src/test/java/com/tngtech/jgiven/report/model/StepFormatterTest.java[JGiven StepFormatter Tests]

Use `$` to access the arguments in natural order.

[source,java]
----
@As ( "the $ fresh eggs and the $ cooked rice bowls" )
public SELF $_eggs_and_$_rice_bowls( int eggs, int riceBowls ) { ... }
----

Or enumerate them `$1, $2, ...` to have a direct reference:
[source,java]
----
@As ( "the $1 fresh eggs and the $2 cooked rice bowls" )
public SELF $_eggs_and_$_rice_bowls( int eggs, int riceBowls ) { ... }
----

Or reference them via the argument names:
[source,java]
----
@As ( "the $eggs fresh eggs and the $riceBowls cooked rice bowls" )
public SELF $_eggs_and_$_rice_bowls( int eggs, int riceBowls ) { ... }
----

The call to `given()._$_eggs_and__$_rice_bowls(5, 2)` will be shown as:

----
Given the 2 cooked rice bowls and the 5 fresh eggs
----



=== Extended Description

An extended description is shown if you hover above the step as tooltip, but hidden by default.

[source,java]
----
@ExtendedDescription ( "The $2 rice bowls were very delicious" )
public SELF $_eggs_and_$_rice_bowls( int eggs, int riceBowls ) { ... }
----

The call to `given()._$_eggs_and__$_rice_bowls(5, 2)` will still be shown as:

----
Given 5 eggs and 2 rice bowls
----

=== Parameter Formatting

Sometimes the `toString()` representation of a parameter object does not fit well into the report. In these cases you have three possibilities:

. Change the `toString()` implementation. This is often not possible or not desired, because it requires the modification of production code. However, sometimes this is appropriate.
. Provide a wrapper class for the parameter object that provides a different `toString()` method. This is useful for parameter objects that you use very often.
. Change the formatting of the parameter by using special JGiven annotations. This can be used in all other cases and also to change the formatting of primitive types.

=== The @Format annotation

The default formatting of a parameter can be overridden by using the `@Format` annotation. It takes as a parameter a class that implements the `ArgumentFormatter` interface. In addition, an optional array of arguments can be given to configure the customer formatter. For example, the built-in `BooleanFormatter` can be used to format `boolean` values:

[source,java]
----
public SELF the_machine_is_$(
    @Format( value = BooleanFormatter.class, args = { "on", "off" } ) boolean onOrOff ) {
    ...
}
----

In this case, `true` values will be formatted as `on` and `false` as `off`.

=== Custom formatting annotations

As using the `@Format` annotation is often cumbersome, especially if the same formatter is used in multiple places, one can define and use custom formatting annotations instead.

An example is the pre-defined `@Quoted` annotation, which surrounds parameters with quotation marks. The annotation is defined as follows:
[source,java]
----
@Format( value = PrintfFormatter.class, args = "\"%s\"" )
@Retention( RetentionPolicy.RUNTIME )
@Target( { ElementType.PARAMETER, ElementType.ANNOTATION_TYPE } )
public @interface Quoted {}
----
As you can see, the annotation itself is annotated with the `@Format` annotation as described above, which will be applied to all parameters that are annotated with `@Quoted`.

==== Example

[source,java]
----
public SELF the_message_$_is_printed_to_the_console( @Quoted message ) { ... }
----

When invoked as


[source,java]
----
then().the_message_$_is_printed_to_the_console( "Hello World" );
----
Then this will result in the report as:


--
Then the message "Hello World" is printed to the console
--

==== The @AnnotationFormat annotation
Another pre-defined annotation is the `@Formatf` annotation which uses the `@AnnotationFormat` annotation to specify the formatter. Formatters of this kind implement the `AnnotationArgumentFormatter` interface. This allows for very flexible formatters that can take the concrete arguments of the annotation into account.

[source,java]
----
@AnnotationFormat( value = PrintfAnnotationFormatter.class )
@Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.PARAMETER )
public @interface Formatf {
    String value() default "%s";
}
----

=== The @POJOFormat annotation

When step parameter is a POJO, it may sometimes be useful to get a string representation using part or all of the fields composing this POJO.

The `@POJOFormat` fulfills this need while providing a way to format fields values following customizable field formats.

Given the following POJO :


[source,java]
----
class CoffeeWithPrice {
   String name;
   double price_in_EUR;
   CoffeeWithPrice(String name, double priceInEur) {
      this.name = name;
      this.price_in_EUR = priceInEur;
   }
}
----


Then you can define a step method as follows:

[source,java]
----
public SELF the_coffee_price_$_is_registered( @POJOFormat(fieldsFormat = {
                    @NamedFormat( name = "name", customFormatAnnotation = Quoted.class),
                    @NamedFormat( name = "price_in_EUR", format = @Format( value = PrintfFormatter.class, args = "%s EUR" ) )
                } ) CoffeeWithPrice price ) {
  ...
}
----
where `@NamedFormat` associates a format (classic `@Format` or any custom format annotation) to a field by its name.

Finally, the step method can be called with an argument :


[source,java]
----
given().the_coffee_price_$_is_registered(new CoffeeWithPrice("Espresso", 2.0));
----


Then the report will look as follows:
[source,java]
----
Given the coffee price ["Espresso",2.0 EUR] is registered
----

For additional options, see the http://jgiven.org/javadoc/com/tngtech/jgiven/annotation/POJOFormat.html[JavaDoc documentation of the `@POJOFormat` annotation]<commit_msg>Fix typo in user guide #359<commit_after>== Parameterized Steps

Step methods can have parameters. Parameters are formatted in reports by using the String.valueOf method, applied to the arguments. The formatted arguments are added to the end of the step description.

[source,java]
----
given().the_ingredient( "flour" ); // Given the ingredient flour
given().multiple_arguments( 5, 6 ); // Given multiple arguments 5 6
----

=== Parameters within a sentence

To place parameters within a sentence instead the end of the sentence you can use the $ character.

[source,java]
----
given().$_eggs( 5 );
----
In the generated report `$` is replaced with the corresponding formatted parameter. So the generated report will look as follows:

----
Given 5 eggs
----

If there are more parameters than `$` characters, the remaining parameters are added to the end of the sentence.

If a `$` should not be treated as a placeholder for a parameter, but printed verbatim, you can write `$$`, which will appear as a single `$` in the report.

=== Custom Annotations

The `@As` annotation can be used to override the shown sentence. To reference arguments you can use the three different interoperable options which apply to every description in JGiven. For more examples look up https://github.com/TNG/JGiven/blob/master/jgiven-core/src/test/java/com/tngtech/jgiven/report/model/StepFormatterTest.java[JGiven StepFormatter Tests]

Use `$` to access the arguments in natural order.

[source,java]
----
@As ( "the $ fresh eggs and the $ cooked rice bowls" )
public SELF $_eggs_and_$_rice_bowls( int eggs, int riceBowls ) { ... }
----

Or enumerate them `$1, $2, ...` to have a direct reference:
[source,java]
----
@As ( "the $1 fresh eggs and the $2 cooked rice bowls" )
public SELF $_eggs_and_$_rice_bowls( int eggs, int riceBowls ) { ... }
----

Or reference them via the argument names:
[source,java]
----
@As ( "the $eggs fresh eggs and the $riceBowls cooked rice bowls" )
public SELF $_eggs_and_$_rice_bowls( int eggs, int riceBowls ) { ... }
----

The call to `given()._$_eggs_and__$_rice_bowls(5, 2)` will be shown as:

----
Given the 2 cooked rice bowls and the 5 fresh eggs
----



=== Extended Description

An extended description is shown if you hover above the step as tooltip, but hidden by default.

[source,java]
----
@ExtendedDescription ( "The $2 rice bowls were very delicious" )
public SELF $_eggs_and_$_rice_bowls( int eggs, int riceBowls ) { ... }
----

The call to `given()._$_eggs_and__$_rice_bowls(5, 2)` will still be shown as:

----
Given 5 eggs and 2 rice bowls
----

=== Parameter Formatting

Sometimes the `toString()` representation of a parameter object does not fit well into the report. In these cases you have three possibilities:

. Change the `toString()` implementation. This is often not possible or not desired, because it requires the modification of production code. However, sometimes this is appropriate.
. Provide a wrapper class for the parameter object that provides a different `toString()` method. This is useful for parameter objects that you use very often.
. Change the formatting of the parameter by using special JGiven annotations. This can be used in all other cases and also to change the formatting of primitive types.

=== The @Format annotation

The default formatting of a parameter can be overridden by using the `@Format` annotation. It takes as a parameter a class that implements the `ArgumentFormatter` interface. In addition, an optional array of arguments can be given to configure the customer formatter. For example, the built-in `BooleanFormatter` can be used to format `boolean` values:

[source,java]
----
public SELF the_machine_is_$(
    @Format( value = BooleanFormatter.class, args = { "on", "off" } ) boolean onOrOff ) {
    ...
}
----

In this case, `true` values will be formatted as `on` and `false` as `off`.

=== Custom formatting annotations

As using the `@Format` annotation is often cumbersome, especially if the same formatter is used in multiple places, one can define and use custom formatting annotations instead.

An example is the pre-defined `@Quoted` annotation, which surrounds parameters with quotation marks. The annotation is defined as follows:
[source,java]
----
@Format( value = PrintfFormatter.class, args = "\"%s\"" )
@Retention( RetentionPolicy.RUNTIME )
@Target( { ElementType.PARAMETER, ElementType.ANNOTATION_TYPE } )
public @interface Quoted {}
----
As you can see, the annotation itself is annotated with the `@Format` annotation as described above, which will be applied to all parameters that are annotated with `@Quoted`.

==== Example

[source,java]
----
public SELF the_message_$_is_printed_to_the_console( @Quoted message ) { ... }
----

When invoked as


[source,java]
----
then().the_message_$_is_printed_to_the_console( "Hello World" );
----
Then this will result in the report as:


--
Then the message "Hello World" is printed to the console
--

==== The @AnnotationFormat annotation
Another pre-defined annotation is the `@Formatf` annotation which uses the `@AnnotationFormat` annotation to specify the formatter. Formatters of this kind implement the `AnnotationArgumentFormatter` interface. This allows for very flexible formatters that can take the concrete arguments of the annotation into account.

[source,java]
----
@AnnotationFormat( value = PrintfAnnotationFormatter.class )
@Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.PARAMETER )
public @interface Formatf {
    String value() default "%s";
}
----

=== The @POJOFormat annotation

When step parameter is a POJO, it may sometimes be useful to get a string representation using part or all of the fields composing this POJO.

The `@POJOFormat` fulfills this need while providing a way to format fields values following customizable field formats.

Given the following POJO :


[source,java]
----
class CoffeeWithPrice {
   String name;
   double price_in_EUR;
   CoffeeWithPrice(String name, double priceInEur) {
      this.name = name;
      this.price_in_EUR = priceInEur;
   }
}
----


Then you can define a step method as follows:

[source,java]
----
public SELF the_coffee_price_$_is_registered( @POJOFormat(fieldFormats = {
                    @NamedFormat( name = "name", customFormatAnnotation = Quoted.class),
                    @NamedFormat( name = "price_in_EUR", format = @Format( value = PrintfFormatter.class, args = "%s EUR" ) )
                } ) CoffeeWithPrice price ) {
  ...
}
----
where `@NamedFormat` associates a format (classic `@Format` or any custom format annotation) to a field by its name.

Finally, the step method can be called with an argument :


[source,java]
----
given().the_coffee_price_$_is_registered(new CoffeeWithPrice("Espresso", 2.0));
----


Then the report will look as follows:
[source,java]
----
Given the coffee price ["Espresso",2.0 EUR] is registered
----

For additional options, see the http://jgiven.org/javadoc/com/tngtech/jgiven/annotation/POJOFormat.html[JavaDoc documentation of the `@POJOFormat` annotation]
{'fraction_non_alphanumeric': 0.10133503763669933, 'fraction_numerical': 0.00347961937224826, 'mean_word_length': 3.9833687190375087, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7562496', 'n_tokens_mistral': 4052, 'n_tokens_neox': 3833, 'n_words': 1708}