bslfmt_testspecificationgenerator

Detailed Description

Provide a generator for test format specifications.

Outline

• Purpose
• Classes
• Description
  • Language Specification
  • Usage
    • Example: Basic Usage of Generator

Purpose

Provide a generator for test format specifications

Classes

• bslfmt::TestSpecificationGenerator: format specification generator

Description

This component provides a class that generates test specifications containing all possible combinations of standard options to format according to the given instructions. The generator is a state machine, each state of which corresponds to a separate specification.

The set of options can be configured using a special language:

Language Specification

'V' - flag indicating if argument id must be present in format specification. The generator substitutes only the preset zero index (i.e. 0:). 'F' - command indicating if fill characters must be added to the produced specifications. By default two preset characters are used: '*' and '=', but the user might add additional characters using addFillCharacter method. '^' - command indicating if alignment option must be added to the generated specifications. Three standard options are iterated through in sequence: '<', '^' and '>'. '+' - command indicating if sign option must be added to the generated specifications. Three standard options are iterated through in sequence: '+', '-' and ' '. '#' - flag indicating if alternate form option must be present in the generated specifications. '0' - flag indicating if zero option must be present in the generated specifications. 'W' - command indicating if width option must be added to the produced specifications. By default the following values are iterated through: 1, 5, 6 and 10, but the user might add additional values using addWidth method. This command does not add nested width values. 'P' - command indicating if precision option must be added to the produced specifications. By default the following values are iterated through: 0, 5, 6 and 10, but the user might add additional values using addPrecision method. This command does not add nested precision values. '{' - command indicating if nested width option must be added to the produced specifications. By default the following indexes are iterated through: empty, 1, and 2 (i.e. {}, {1} and {2}. Note that due to implementation specifics this command automatically adds non-nested width values (i.e. the default full set looks like (no option), `{}`, `{1}`, `{2}`, `1`, `5`, `6` and `10`. '}' - command indicating if nested precision option must be added to the produced specifications. By default the following indexes are iterated through: empty, 1, and 2 (i.e. `.{}`, `.{1}` and `.{2}`. Note that due to implementation specifics this command automatically adds non-nested precision values (i.e. the default full set looks like (no option), .{}, .{1}, .{2}, .0, .5, .6 and .10. 'L' - flag indicating if locale option must be present in the generated specifications. 's' - command indicating if string presentation type (i.e. s) must be present in the generated specifications. 'i' - command indicating if integer presentation types must be present in the generated specifications. The following standard options are iterated through in sequence: b, B, c, d, o, x and X. 'c' - command indicating if character presentation types must be present in the generated specifications. The following standard options are iterated through in sequence: b, B, c, d, o, x and X. 'b' - command indicating if boolean presentation types must be present in the generated specifications. The following standard options are iterated through in sequence: s, b, B, c, d, o, x and X. 'f' - command indicating if floating-point presentation types must be present in the generated specifications. The following standard options are iterated through in sequence: a, A, e, E, f, F, g and G. 'p' - command indicating if pointer presentation types must be present in the generated specifications. The following standard options are iterated through in sequence: p and P. 'a' - command indicating if all presentation types must be present in the generated specifications. The following standard options are iterated through in sequence: s, b, B, c, d, o, x, X, a, A, e, E, f, F, g, G, p and P.

The default generator instruction is "F^+#0WP{}L". Note that adding a particular command to an instruction does not mean that the corresponding option will be present in every generated specification; a specification with the missing option will also be generated.

The generator produces both valid and invalid strings from the point of view of the standard, which also allows thorough testing of the processing of incorrect input data. But at the same time, it remains possible to iterate only through valid specifications using 'nextValidForParseor 'nextValidForFormat methods.

Usage

This section illustrates intended use of this component.

Example: Basic Usage of Generator

The generator is a state machine, each state of which generates a unique format specification. Depending on the set of instructions, the number of possible states also changes. For simplicity, we will take one parameter, the sign, that takes three possible values: +, - and . Accordingly, we expect that the generator will go through four states, because the default state always comes first, generating an empty specification. First, let's create the generator and configure it:

 typedef bslfmt::TestSpecificationGenerator<char> Generator;
 
 const Generator::Sign POSITIVE = Generator::e_SIGN_POSITIVE;
 const Generator::Sign NEGATIVE = Generator::e_SIGN_NEGATIVE;
 const Generator::Sign SPACE    = Generator::e_SIGN_SPACE;
 
 bslfmt::TestSpecificationGenerator<char> generator;

Note that the instructions are given to the generator in a special language, a description of which can be found in the component documentation:

 generator.setup("+");

You can get information about the current state of the generator using multiple accessors. Since we requested only one option, most of these accessors return false when asked about the presence of a particular option. Note that a request to get the value of an option, if this option is not present in the current state, is undefined behavior:

 assert(true    == generator.isStateValidForParse());
 assert(true    == generator.isStateValidForFormat());
 
 assert(false   == generator.isValueIdOptionPresent());
 assert(false   == generator.isFillCharacterPresent());
 assert(false   == generator.isAlignOptionPresent());
 assert(false   == generator.isSignOptionPresent());
 assert(false   == generator.isHashOptionPresent());
 assert(false   == generator.isZeroOptionPresent());
 assert(false   == generator.isWidthOptionPresent());
 assert(false   == generator.isNestedWidthPresent());
 assert(false   == generator.isPrecisionOptionPresent());
 assert(false   == generator.isNestedPrecisionPresent());
 assert(false   == generator.isLocaleOptionPresent());
 assert(false   == generator.isTypeOptionPresent());

As we have already said, the initial state of the generator generates an empty string. Therefore, even though we added the sign to the instruction, this option is not present in this state. Keep in mind that the absence of an option is always another variant when iterating through the states of the generator. For each state, the generator creates two strings: one that the bsl::format passes to the formatter's parse function, and one that can be passed to the bsl::format function itself:

 assert(""      == generator.spec());
 assert("{:}"   == generator.formatSpec());

Then, let's move on to the next state of the generator. When the generator has iterated over all possible states, the function next will return false, but for now we expect it to return true:

 assert(true == generator.next());

For ease of reading, we will not check all the options each time, but only those that are significant for our example:

 assert(true     == generator.isStateValidForParse());
 assert(true     == generator.isStateValidForFormat());
 assert(true     == generator.isSignOptionPresent());
 assert(POSITIVE == generator.sign());
 assert("+"      == generator.spec());
 assert("{:+}"   == generator.formatSpec());

The function next iterates over all possible states of the generator, including those that generate strings, the processing of which by the corresponding functions will lead to an exception being thrown. Such states can be determined using the functions isStateValidForParse and isStateValidForFormat. Another option can be to skip invalid states using the functions nextValidForParse and nextValidForFormat, respectively:

 assert(true     == generator.nextValidForParse());
 assert(true     == generator.isStateValidForParse());
 assert(true     == generator.isStateValidForFormat());
 assert(true     == generator.isSignOptionPresent());
 assert(NEGATIVE == generator.sign());
 assert("-"      == generator.spec());
 assert("{:-}"   == generator.formatSpec());
 
 assert(true     == generator.nextValidForFormat());
 assert(true     == generator.isStateValidForParse());
 assert(true     == generator.isStateValidForFormat());
 assert(true     == generator.isSignOptionPresent());
 assert(SPACE    == generator.sign());
 assert(" "      == generator.spec());
 assert("{: }"   == generator.formatSpec());

Now, the generator is in its last state, so the next function should returnfalse:

 assert(false == generator.next());

Finally, let's make sure that the generator is back in its initial state and ready to go for the second round:

 assert(""    == generator.spec());
 assert("{:}" == generator.formatSpec());
 assert(true  == generator.next());