cz.auderis.test.support

Class NaturalDescriptionJoiner

java.lang.Object

cz.auderis.test.support.NaturalDescriptionJoiner

All Implemented Interfaces:

org.hamcrest.SelfDescribing

public class NaturalDescriptionJoiner
extends java.lang.Object
implements org.hamcrest.SelfDescribing

Versatile utility class that merges chunks of text, surrounding them with optional prefixes and suffixes and putting appropriate separators between entries. The class is intended to be used with Hamcrest matchers, simplifying the task of building a description of more complex matchers and their mismatching values.

The general structure of output is following:

result ::= [Prefix] Item₁ NS Item₂ NS ... Item_n-1 LS Item_n [Suffix]

where Prefix is an optional main description prefix, Suffix is an optional main description suffix, NS is "normal separator" string and LS is "last separator" string. Additionally, each item has the following structure:

Item_k :== [Prefix_k] Value_k [Suffix_k]

This means that each description item may individually have its optional prefix and suffix.

Details

Joiner items

A joiner item can have one of two forms, described in the following table:

Item type	Usage	Redundant when
plain value V	description of items	V == null
pair of value V and its associated matcher M	description of mismatches	M == null || M.matches(V)

Joiner items that are deemed redundant are not sent to output.

Text chunks

Practically all text parts (prefixes, suffixes, separators, description item values etc.) have type java.lang.Object. Typically they are strings or other implementations of java.lang.CharSequence, but the general object type allows lazy evaluation. If a text chunk object implements java.util.concurrent.Callable interface, it is invoked during description rendering and the returned value is re-evaluated (i.e. if a Callable C1 returns a reference to another Callable C2, there will be two invocations of Callable.call():

 C2 = C1.call();
 Result = C2.call();
 

Constructor Summary

Constructors

Constructor and Description
NaturalDescriptionJoiner() Constructs a description joiner with default settings: prefix and suffix are undefined, normal separator is a string consisting of comma+space characters and the last separator is the word "and" surrounded by a single space on both ends.
NaturalDescriptionJoiner(java.lang.Object separator) Constructs a simple description joiner without prefix and suffix, where identical string is used both as "normal" as well as the "last" separator.
NaturalDescriptionJoiner(java.lang.Object normalSeparator, java.lang.Object lastSeparator) Constructs a simple description joiner without prefix and suffix.
NaturalDescriptionJoiner(java.lang.Object prefix, java.lang.Object normalSeparator, java.lang.Object lastSeparator, java.lang.Object suffix) Constructs a description joiner with a prefix, suffix and both normal and last separators.

Method Summary

Modifier and Type	Method and Description
NaturalDescriptionJoiner	add(java.lang.Object value)
NaturalDescriptionJoiner	add(java.lang.Object valuePrefix, java.lang.Object value)
NaturalDescriptionJoiner	add(java.lang.Object valuePrefix, java.lang.Object value, java.lang.Object valueSuffix) Adds a new description item, allowing to specify an optional prefix and suffix.
<T> NaturalDescriptionJoiner	add(java.lang.Object valuePrefix, T value, java.lang.Object valueSuffix, DescriptionProvider<? super T> valueDescriber)
<T> NaturalDescriptionJoiner	addMismatch(org.hamcrest.Matcher<? super T> valueMatcher, T value)
<T> NaturalDescriptionJoiner	addMismatch(java.lang.Object valuePrefix, org.hamcrest.Matcher<? super T> valueMatcher, T value)
<T> NaturalDescriptionJoiner	addMismatch(java.lang.Object valuePrefix, org.hamcrest.Matcher<? super T> valueMatcher, T value, java.lang.Object valueSuffix)
<T> NaturalDescriptionJoiner	addMismatch(java.lang.Object valuePrefix, org.hamcrest.Matcher<? super T> valueMatcher, T value, java.lang.Object valueSuffix, MismatchDescriptionProvider<? super T> mismatchDescriber)
void	appendTo(java.lang.StringBuilder sb) Appends prepared description to a provided StringBuilder.
void	describeTo(org.hamcrest.Description desc) Appends description of accumulated items to the provided Description.
boolean	isEmpty() Indicates whether a list of accumulated items is empty or all items are redundant.
boolean	isUsePrefixWhenEmpty() Indicates whether a prefix string is prepended even when the main part of the output is empty.
boolean	isUseSuffixWhenEmpty() Indicates whether a suffix string is appended even when the main part of the output is empty.
void	setUsePrefixWhenEmpty(boolean usePrefixWhenEmpty) Modifies the flag that controls whether a prefix is prepended even when the main part of the output is empty.
void	setUseSuffixWhenEmpty(boolean useSuffixWhenEmpty) Modifies the flag that controls whether a suffix is prepended even when the main part of the output is empty.
NaturalDescriptionJoiner	withDescriptionContext(java.lang.Object newContext) Defines a context, which is an arbitrary object, for the current use of this Joiner instance.
NaturalDescriptionJoiner	withDescriptionContextReceiver(ContextAwareDescriptionProvider receiver) Certain application types can not or do not want their description providers to implement ContextAwareDescriptionProvider interface.
NaturalDescriptionJoiner	withLastSeparator(java.lang.Object lastSep) Modifies last separator (i.e.
NaturalDescriptionJoiner	withNormalSeparator(java.lang.Object normalSep) Modifies normal separator (i.e.
NaturalDescriptionJoiner	withoutPrefixWhenEmpty() Using fluent style, resets the flag that controls whether a prefix is prepended even when the main part of the output is empty to false.
NaturalDescriptionJoiner	withoutSuffixWhenEmpty() Using fluent style, resets the flag that controls whether a suffix is appended even when the main part of the output is empty to false.
NaturalDescriptionJoiner	withPrefix(java.lang.Object prefix) Modifies the main prefix in fluent style.
NaturalDescriptionJoiner	withPrefixWhenEmpty() Using fluent style, sets the flag that controls whether a prefix is prepended even when the main part of the output is empty to true.
NaturalDescriptionJoiner	withSuffix(java.lang.Object suffix) Modifies the main suffix in fluent style.
NaturalDescriptionJoiner	withSuffixWhenEmpty() Using fluent style, sets the flag that controls whether a suffix is appended even when the main part of the output is empty to true.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NaturalDescriptionJoiner

public NaturalDescriptionJoiner(java.lang.Object prefix,
                                java.lang.Object normalSeparator,
                                java.lang.Object lastSeparator,
                                java.lang.Object suffix)

Constructs a description joiner with a prefix, suffix and both normal and last separators.

Parameters:

prefix - prefix placed at the start of output (optional, may be null)

normalSeparator - normal separator (null is equivalent to an empty string)

lastSeparator - separator placed between last two items (null is equivalent to an empty string)

suffix - suffix appended to the end of output (optional, may be null)

NaturalDescriptionJoiner

public NaturalDescriptionJoiner()

Constructs a description joiner with default settings: prefix and suffix are undefined, normal separator is a string consisting of comma+space characters and the last separator is the word "and" surrounded by a single space on both ends.

Equivalent: new NaturalDescriptionJoiner(null, ", ", " and ", null)

See Also:

NaturalDescriptionJoiner(Object, Object, Object, Object)

NaturalDescriptionJoiner

public NaturalDescriptionJoiner(java.lang.Object separator)

Constructs a simple description joiner without prefix and suffix, where identical string is used both as "normal" as well as the "last" separator.

Equivalent: new NaturalDescriptionJoiner(null, separator, separator, null)

Parameters:

separator - string that is placed between items (null is equivalent to an empty string)

See Also:

NaturalDescriptionJoiner(Object, Object, Object, Object)

NaturalDescriptionJoiner

public NaturalDescriptionJoiner(java.lang.Object normalSeparator,
                                java.lang.Object lastSeparator)

Constructs a simple description joiner without prefix and suffix.

Equivalent: new NaturalDescriptionJoiner(null, normalSeparator, lastSeparator, null)

Parameters:

normalSeparator - normal separator (null is equivalent to an empty string)

lastSeparator - separator placed between last two items (null is equivalent to an empty string)

See Also:

NaturalDescriptionJoiner(Object, Object, Object, Object)

Method Detail

withPrefix

public NaturalDescriptionJoiner withPrefix(java.lang.Object prefix)

Modifies the main prefix in fluent style.

Parameters:

prefix - new description prefix

Returns:

this joiner

withSuffix

public NaturalDescriptionJoiner withSuffix(java.lang.Object suffix)

Modifies the main suffix in fluent style.

Parameters:

suffix - new description suffix

Returns:

this joiner

withNormalSeparator

public NaturalDescriptionJoiner withNormalSeparator(java.lang.Object normalSep)

Modifies normal separator (i.e. the separator put between items with the exception of the last two items) in fluent style.

Parameters:

normalSep - new normal separator (null is equivalent to an empty string)

Returns:

this joiner

withLastSeparator

public NaturalDescriptionJoiner withLastSeparator(java.lang.Object lastSep)

Modifies last separator (i.e. the separator put between the last two items) in fluent style.

Parameters:

lastSep - new last separator (null is equivalent to an empty string)

Returns:

this joiner

withDescriptionContext

public NaturalDescriptionJoiner withDescriptionContext(java.lang.Object newContext)

Defines a context, which is an arbitrary object, for the current use of this Joiner instance. This context is fed into a description context receiver (if one is set) and to any description provider implementing this interface. The context is transferred immediately before invocation of a description provider.

Parameters:

newContext - an object that contains application-defined context

Returns:

this joiner

withDescriptionContextReceiver

public NaturalDescriptionJoiner withDescriptionContextReceiver(ContextAwareDescriptionProvider receiver)

Certain application types can not or do not want their description providers to implement ContextAwareDescriptionProvider interface. As an alternative, a separate instance of that interface can be registered by this method. The receiver is then informed about the current context before any description provider is invoked.

Parameters:

receiver - implementation of ContextAwareDescriptionProvider that receives notifications about current description context immediately before a description provider is invoked

Returns:

this joiner

isUsePrefixWhenEmpty

public boolean isUsePrefixWhenEmpty()

Indicates whether a prefix string is prepended even when the main part of the output is empty. By default the flag is false.

Returns:

true when the prefix is sent to output even when the main output part is empty

setUsePrefixWhenEmpty

public void setUsePrefixWhenEmpty(boolean usePrefixWhenEmpty)

Modifies the flag that controls whether a prefix is prepended even when the main part of the output is empty.

Parameters:

usePrefixWhenEmpty - new flag value

withPrefixWhenEmpty

public NaturalDescriptionJoiner withPrefixWhenEmpty()

Using fluent style, sets the flag that controls whether a prefix is prepended even when the main part of the output is empty to true.

Returns:

this joiner

See Also:

setUsePrefixWhenEmpty(boolean)

withoutPrefixWhenEmpty

public NaturalDescriptionJoiner withoutPrefixWhenEmpty()

Using fluent style, resets the flag that controls whether a prefix is prepended even when the main part of the output is empty to false.

Returns:

this joiner

See Also:

setUsePrefixWhenEmpty(boolean)

isUseSuffixWhenEmpty

public boolean isUseSuffixWhenEmpty()

Indicates whether a suffix string is appended even when the main part of the output is empty. By default the flag is false.

Returns:

true when the suffix is sent to output even when the main output part is empty

setUseSuffixWhenEmpty

public void setUseSuffixWhenEmpty(boolean useSuffixWhenEmpty)

Modifies the flag that controls whether a suffix is prepended even when the main part of the output is empty.

Parameters:

useSuffixWhenEmpty - new flag value

withSuffixWhenEmpty

public NaturalDescriptionJoiner withSuffixWhenEmpty()

Using fluent style, sets the flag that controls whether a suffix is appended even when the main part of the output is empty to true.

Returns:

this joiner

See Also:

setUseSuffixWhenEmpty(boolean)

withoutSuffixWhenEmpty

public NaturalDescriptionJoiner withoutSuffixWhenEmpty()

Using fluent style, resets the flag that controls whether a suffix is appended even when the main part of the output is empty to false.

Returns:

this joiner

See Also:

setUseSuffixWhenEmpty(boolean)

isEmpty

public boolean isEmpty()

Indicates whether a list of accumulated items is empty or all items are redundant. (See definition of redundant items in the class JavaDoc.)

Returns:

false when the joiner contains one or more non-redundant items

add

public NaturalDescriptionJoiner add(java.lang.Object valuePrefix,
                                    java.lang.Object value,
                                    java.lang.Object valueSuffix)

Adds a new description item, allowing to specify an optional prefix and suffix. Apart from strings and other character sequences, prefix and suffix can have following types:

Type	Processing
null	omitted from output
CharSequence	normally appended to output
SelfDescribing	appended to output by means of calling its SelfDescribing.describeTo(Description) method

Parameters:

valuePrefix - optional text chunk that will be prepended immediately before value

value - value to be appended to output

valueSuffix - optional text chunk that will be appended immediately after value

Returns:

this joiner

add

public NaturalDescriptionJoiner add(java.lang.Object valuePrefix,
                                    java.lang.Object value)

add

public NaturalDescriptionJoiner add(java.lang.Object value)

add

public <T> NaturalDescriptionJoiner add(java.lang.Object valuePrefix,
                                        T value,
                                        java.lang.Object valueSuffix,
                                        DescriptionProvider<? super T> valueDescriber)

addMismatch

public <T> NaturalDescriptionJoiner addMismatch(java.lang.Object valuePrefix,
                                                org.hamcrest.Matcher<? super T> valueMatcher,
                                                T value,
                                                java.lang.Object valueSuffix)

addMismatch

public <T> NaturalDescriptionJoiner addMismatch(java.lang.Object valuePrefix,
                                                org.hamcrest.Matcher<? super T> valueMatcher,
                                                T value)

addMismatch

public <T> NaturalDescriptionJoiner addMismatch(org.hamcrest.Matcher<? super T> valueMatcher,
                                                T value)

addMismatch

public <T> NaturalDescriptionJoiner addMismatch(java.lang.Object valuePrefix,
                                                org.hamcrest.Matcher<? super T> valueMatcher,
                                                T value,
                                                java.lang.Object valueSuffix,
                                                MismatchDescriptionProvider<? super T> mismatchDescriber)

describeTo

public void describeTo(org.hamcrest.Description desc)

Appends description of accumulated items to the provided Description. When this argument is null, no operation is performed.

Specified by:

describeTo in interface org.hamcrest.SelfDescribing

Parameters:

desc - Description instance

appendTo

public void appendTo(java.lang.StringBuilder sb)

Appends prepared description to a provided StringBuilder.

Parameters:

sb - StringBuilder reference