LibSgfcPlusPlus::SgfcPropertyDecoder Class Reference

The SgfcPropertyDecoder class parses the raw strings that SGFC provides for SGF properties and their values, and generates proper objects from those parsing activities. More...

#include <SgfcPropertyDecoder.h>

Public Member Functions
	SgfcPropertyDecoder (const Property *sgfProperty, SgfcGameType gameType, SgfcBoardSize boardSize)
	Initializes a newly constructed SgfcPropertyDecoder object. The object parses the specified SGF property sgfProperty and its values. The SGF property's string value is used to determine the property type. The specified gameType and boardSize are important for interpreting certain game-specific properties and their values, but are ignored for all other properties and their values.
virtual	~SgfcPropertyDecoder ()
	Destroys and cleans up the SgfcPropertyDecoder object.
bool	GetEscapProcessingEnabled () const
	Returns true if escape processing is enabled. Returns false if escape processing is diabled. The default is false.
void	SetEscapeProcessingEnabled (bool escapeProcessingEnabled)
	Enables escape processing if escapeProcessingEnabled is true. Disables escape processing if escapeProcessingEnabled is false.
SgfcPropertyType	GetPropertyType () const
	Returns the SgfcPropertyType value that corresponds to the SGF property with which SgfcPropertyDecoder was constructed. Returns SgfcPropertyType::Unknown for properties that are not defined in the SGF standard.
std::string	GetPropertyName () const
	Returns the raw string name of the SGF property with which SgfcPropertyDecoder was constructed.
std::vector< std::shared_ptr< ISgfcPropertyValue > >	GetPropertyValues () const
	Returns a list with the values of the SGF property with which SgfcPropertyDecoder was constructed.

Static Public Member Functions
static SgfcGameType	GetGameTypeFromNode (const Node *sgfNode)
	Probes the SGF node sgfNode for a property of type SgfcPropertyType::GM and returns an SgfcGameType value that corresponds to the result of the probing.
static SgfcBoardSize	GetBoardSizeFromNode (const Node *sgfNode, SgfcGameType gameType)
	Probes the SGF node sgfNode for a property of type SgfcPropertyType::SZ and returns an SgfcBoardSize value that corresponds to the result of the probing.

Detailed Description

The SgfcPropertyDecoder class parses the raw strings that SGFC provides for SGF properties and their values, and generates proper objects from those parsing activities.

Constructor & Destructor Documentation

SgfcPropertyDecoder()

LibSgfcPlusPlus::SgfcPropertyDecoder::SgfcPropertyDecoder	(	const Property *	sgfProperty,
		SgfcGameType	gameType,
		SgfcBoardSize	boardSize )

Initializes a newly constructed SgfcPropertyDecoder object. The object parses the specified SGF property sgfProperty and its values. The SGF property's string value is used to determine the property type. The specified gameType and boardSize are important for interpreting certain game-specific properties and their values, but are ignored for all other properties and their values.

Exceptions

std::domain_error

Is thrown if something about sgfProperty is not as expected. This exception should never be thrown, but when it is thrown this is an indicator for an interfacing problem with SGFC. The exception is known to be thrown in the following cases: 1) sgfProperty is nullptr. 2) sgfProperty->idstr is nullptr. 3) sgfProperty->value is nullptr.

Member Function Documentation

GetBoardSizeFromNode()

SgfcBoardSize LibSgfcPlusPlus::SgfcPropertyDecoder::GetBoardSizeFromNode ( const Node * sgfNode, SgfcGameType gameType )

static

Probes the SGF node sgfNode for a property of type SgfcPropertyType::SZ and returns an SgfcBoardSize value that corresponds to the result of the probing.

Parameters

sgfNode	The SGF node to be probed. The node should be the root node of a game because SgfcPropertyType::SZ can be expected to be present in that node.
gameType	The game type that should be used in case the property is not present to determine a game-specific default board size.

Return values

SgfcBoardSize	If the property is present and has a valid value. The value is guaranteed not to be SgfcConstants::BoardSizeNone nor SgfcConstants::BoardSizeInvalid.
SgfcConstants::BoardSizeDefaultGo	If the property is not present and gameType is SgfcGameType::Go.
SgfcConstants::BoardSizeDefaultChess	If the property is not present and gameType is SgfcGameType::Chess.
SgfcConstants::BoardSizeNone	If the property is not present and gameType is neither SgfcGameType::Go nor SgfcGameType::Chess.
SgfcConstants::BoardSizeInvalid	If the property is present but its SgfcBoardSize value violates the constraints defined by the SGF standard. See the documentation of SgfcConstants::BoardSizeInvalid for details.

Exceptions

std::domain_error

Is thrown if something about sgfNode is not as expected. This exception should never be thrown, but when it is thrown this is an indicator for an interfacing problem with SGFC. The exception is known to be thrown in the following cases: 1) sgfNode is nullptr. 2) sgfNode contains an SZ property that has no value, or a value that is neither a Number string nor a composed value consisting of two Number strings.

GetEscapProcessingEnabled()

bool LibSgfcPlusPlus::SgfcPropertyDecoder::GetEscapProcessingEnabled

(

)

const

Returns true if escape processing is enabled. Returns false if escape processing is diabled. The default is false.

When escape processing is enabled SgfcPropertyDecoder removes escape characters from SimpleText and Text property values, from Move/Point/Stone property values if the game type is not SgfcGameType::Go, and from values for properties that have SgfcPropertyType::Unknown.

The default for this setting used to be true, but beginning with V2.00 SGFC now removes all escape characters for us. The setting is left in place because programming the escape processing was a substantial amount of work, and it may become necessary to enable it again at some time in the future.

GetGameTypeFromNode()

SgfcGameType LibSgfcPlusPlus::SgfcPropertyDecoder::GetGameTypeFromNode ( const Node * sgfNode )

static

Probes the SGF node sgfNode for a property of type SgfcPropertyType::GM and returns an SgfcGameType value that corresponds to the result of the probing.

Parameters

sgfNode

The SGF node to be probed. The node should be the root node of a game because SgfcPropertyType::GM can be expected to be present in that node.

Return values

SgfcGameType	If the property is present and has a single Number value, and that value is defined in the SGF standard, then the SgfcGameType value that corresponds to the Number value is returned. The value is guaranteed not to be SgfcGameType::Unknown.
SgfcConstants::DefaultGameType	If the property is not present. The value is guaranteed not to be SgfcGameType::Unknown.
SgfcGameType::Unknown	If the property is present and has a single Number value, but that value is not defined in the SGF standard.

Exceptions

std::domain_error

Is thrown if something about sgfNode is not as expected. This exception should never be thrown, but when it is thrown this is an indicator for an interfacing problem with SGFC. The exception is known to be thrown in the following cases: 1) sgfNode is nullptr. 2) sgfNode contains a GM property that has no value, or more than one value, or a single value that is not a Number string, or a composed value.

GetPropertyValues()

std::vector< std::shared_ptr< ISgfcPropertyValue > > LibSgfcPlusPlus::SgfcPropertyDecoder::GetPropertyValues

(

)

const

Returns a list with the values of the SGF property with which SgfcPropertyDecoder was constructed.

If GetPropertyType() returns SgfcPropertyType::Unknown all ISgfcSinglePropertyValue objects contain uninterpreted raw values only and their GetValueType() method returns SgfcPropertyValueType::Unknown. This is because the property is not defined in the SGF standard, so SgfcPropertyDecoder does not know the type the raw values should have.

If GetPropertyType() returns something other than SgfcPropertyType::Unknown, the property is defined in the SGF standard and SgfcPropertyDecoder attempts to convert the raw string values into values of the types required by the property according to the SGF standard. In all cases the GetValueType() method of ISgfcSinglePropertyValue objects returns the value type as defined by the SGF standard. The outcome of the conversion attempt determines the other properties of ISgfcSinglePropertyValue objects:

• If SgfcPropertyDecoder fails to convert the raw string value, the ISgfcSinglePropertyValue objects' HasTypedValue() method returns false and the GetTypeConversionErrorMessage() method returns a message that describes the reason for the conversion failure.
• If SgfcPropertyDecoder succeeds to convert the raw string value, the ISgfcSinglePropertyValue objects' HasTypedValue() method returns true and one of the numerous To...() methods can be used to cast the object to a concrete type.

Exceptions

std::domain_error

Is thrown if something about the SGF property object passed to the constructor is not as expected. This exception should never be thrown, but when it is thrown this is an indicator for an interfacing problem with SGFC. The exception is known to be thrown in the following cases: 1) Any value type is expected, but the SGF property object does not contain a value. 2) A single value type is expected, but the SGF property object also contains a second value. 3) A composed value type is expected, but the SGF property object contains no second value.

Note

This method relies on certain pre-processing performed by SGFC. Notably:

• SGFC is expected to trim leading and trailing whitespace from values that are not SimpleText or Text. Without trimming this method would be unable to recognize Double and Color values.
• In SimpleText values, SGFC is expected to convert whitespace characters other than space to space (i.e. line breaks are not preserved). Due to shortcomings in SGFC's handling of line breaks this method adds its own line break handling, so currently SGFC's line break handling is irrelevant to the implementation of this method. See the next note for details.
• In Text values, SGFC is expected to convert whitespace characters other than line breaks are converted to space (i.e. line breaks are preserved). SGFC is also expected to remove escaped line breaks. Due to shortcomings in SGFC's handling of line breaks this method adds its own line break handling, so currently SGFC's line break handling is irrelevant to the implementation of this method. See the next note for details.
• In SimpleText and Text values, all escape characters are removed.
• In Move values, if the game type is Go and the board size is <= 19x19, SGFC is expected to convert the value "tt" to an empty string. According to the SGF standard an empty string and value "tt" both express a pass move, but in FF4 the "tt" representation is kept only for compatibility with FF3.

This method has its own line break handling for SimpleText and Text values, due to two shortcomings in SGFC: 1) A bug in SGFC: If a SimpleText value is the second value of a composed value then SGFC does not detect and remove hard and soft line breaks in all cases. This method is capable of detecting these cases. 2) SGFC only handles one kind of line break (e.g. LF, CRLF, ...) in SimpleText and Text values: The one that was predetermined at compile time. This method is capable of recognizing and handling all kinds of platform-specific line breaks.

If SgfcPropertyDecoder was constructed with SgfcGameType::Go the decoding process performs the following game logic validation:

• If SgfcPropertyDecoder was constructed with SgfcConstants::BoardSizeNone or SgfcConstants::BoardSizeInvalid, any game-specific property value objects (e.g. ISgfcGoPointPropertyValue) that would normally contain an ISgfcGoPoint do not contain such an object. Instead they contain the raw property value only.
• If SgfcPropertyDecoder was constructed with a valid board size but the property value contains a location that is outside the boundaries of the specified board size, any game-specific property value objects (e.g. ISgfcGoPointPropertyValue) that would normally contain an ISgfcGoPoint do not contain such an object. Instead they contain the raw property value only.

This documentation has to be replicated on the public interface. specifically, the notes regarding the expected pre-processing performed by SGFC must be available as well in the documentation of ISgfcSinglePropertyValue::GetRawValue().

SetEscapeProcessingEnabled()

void LibSgfcPlusPlus::SgfcPropertyDecoder::SetEscapeProcessingEnabled

(

bool

escapeProcessingEnabled

)

Enables escape processing if escapeProcessingEnabled is true. Disables escape processing if escapeProcessingEnabled is false.

See also

GetEscapProcessingEnabled()

---

The documentation for this class was generated from the following files:

• /Users/patrick/dev/libsgfcplusplus/src/parsing/SgfcPropertyDecoder.h
• /Users/patrick/dev/libsgfcplusplus/src/parsing/SgfcPropertyDecoder.cpp