fluent.h File Reference

Go to the source code of this file.

Classes
struct	NYT::TFluentYsonUnwrapper< T >
struct	NYT::TFluentYsonVoid
struct	NYT::TFluentYsonUnwrapper< TFluentYsonVoid >
class	NYT::TFluentYsonBuilder
	This class is actually a namespace for specific fluent adapter classes. More...
class	NYT::TFluentYsonBuilder::TFluentBase< TParent >
	Base class for all fluent adapters. More...
class	NYT::TFluentYsonBuilder::TFluentFragmentBase< TThis, TParent >
	Base class for fluent adapters for fragment of list, map or attributes. More...
class	NYT::TFluentYsonBuilder::TAnyWithoutAttributes< TParent >
	Fluent adapter of a value without attributes. More...
class	NYT::TFluentYsonBuilder::TAny< TParent >
	Fluent adapter of any value. More...
class	NYT::TFluentYsonBuilder::TAttributes< TParent >
	Fluent adapter of attributes fragment (the inside part of attributes). More...
class	NYT::TFluentYsonBuilder::TListType< TParent >
	Fluent adapter of list fragment (the inside part of a list). More...
class	NYT::TFluentYsonBuilder::TMapType< TParent >
	Fluent adapter of map fragment (the inside part of a map). More...
class	NYT::TFluentYsonWriterState
class	NYT::TFluentYsonBuilderState
class	NYT::TFluentYsonHolder< TState >
struct	NYT::TFluentYsonUnwrapper< TFluentYsonHolder< TState > >

Namespaces
namespace	NYT
	Main namespace of YT client.

Typedefs
using	NYT::TFluentAny = TFluentYsonBuilder::TAny<TFluentYsonVoid>
	Builder representing any value.
using	NYT::TFluentList = TFluentYsonBuilder::TListType<TFluentYsonVoid>
	Builder representing the inside of a list (list fragment).
using	NYT::TFluentMap = TFluentYsonBuilder::TMapType<TFluentYsonVoid>
	Builder representing the inside of a map (map fragment).
using	NYT::TFluentAttributes = TFluentYsonBuilder::TAttributes<TFluentYsonVoid>
	Builder representing the inside of attributes.

Functions
template<class TState>
TFluentYsonBuilder::TAny< TFluentYsonHolder< TState > >	NYT::BuildYsonFluentlyWithState (::TIntrusivePtr< TState > state)
TFluentYsonBuilder::TAny< TFluentYsonHolder< TFluentYsonWriterState > >	NYT::BuildYsonStringFluently (::NYson::EYsonFormat format=::NYson::EYsonFormat::Text)
	Create a fluent adapter returning a TString with corresponding YSON when construction is finished.
TFluentYsonBuilder::TAny< TFluentYsonHolder< TFluentYsonBuilderState > >	NYT::BuildYsonNodeFluently ()
	Create a fluent adapter returning a NYT::TNode when construction is finished.

Detailed Description

Adapters for working with NYson::IYsonConsumer in a structured way, with compile-time syntax checks.

The following documentation is copied verbatim from yt/core/ytree/fluent.h.

WHAT IS THIS

Fluent adapters encapsulate invocation of IYsonConsumer methods in a convenient structured manner. Key advantage of fluent-like code is that attempt of building syntactically incorrect YSON structure will result in a compile-time error.

Each fluent object is associated with a context that defines possible YSON tokens that may appear next. For example, TFluentMap is a fluent object that corresponds to a location within YSON map right before a key-value pair or the end of the map.

More precisely, each object that may be obtained by a sequence of fluent method calls has the full history of its enclosing YSON composite types in its single template argument hereinafter referred to as TParent. This allows us not to forget the original context after opening and closing the embedded composite structure.

It is possible to invoke a separate YSON building procedure by calling one of convenience Do* methods. There are two possibilities here: it is possible to delegate invocation context either as a fluent object (like TFluentMap, TFluentList, TFluentAttributes or TFluentAny) or as a raw IYsonConsumer*. The latter is discouraged since it is impossible to check if a given side-built YSON structure fits current fluent context. For example it is possible to call Do() method inside YSON map passing consumer to a procedure that will treat context like it is in a list. Passing typed fluent builder saves you from such a misbehaviour.

TFluentXxx corresponds to an internal class of TXxx without any history hidden in template argument. It allows you to write procedures of form:

void BuildSomeAttributesInYson(TFluentMap fluent) { ... }

without thinking about the exact way how this procedure is nested in other procedures.

An important notation: we will refer to a function whose first argument is TFluentXxx as TFuncXxx.

BRIEF LIST OF AVAILABLE METHODS

Only the most popular methods are covered here. Refer to the code for the rest of them.

TAny:

• Value(T value) -> TParent, serialize value using underlying consumer. T should be such that free function Serialize(NYson::IYsonConsumer*, const T&) is defined;
• BeginMap() -> TFluentMap, open map;
• BeginList() -> TFluentList, open list;
• BeginAttributes() -> TFluentAttributes, open attributes;
• Do(TFuncAny func) -> TAny, delegate invocation to a separate procedure.
• DoIf(bool condition, TFuncAny func) -> TAny, same as Do() but invoke func only if condition is true;
• DoFor(TCollection collection, TFuncAny func) -> TAny, same as Do() but iterate over collection and pass each of its elements as a second argument to func. Instead of passing a collection you may it is possible to pass two iterators as an argument;
• DoMap(TFuncMap func) -> TAny, open a map, delegate invocation to a separate procedure and close map;
• DoMapFor(TCollection collection, TFuncMap func) -> TAny, open a map, iterate over collection and pass each of its elements as a second argument to func and close map;
• DoList(TFuncList func) -> TAny, same as DoMap();
• DoListFor(TCollection collection, TFuncList func) -> TAny; same as DoMapFor().

TFluentMap:

• Item(TStringBuf key) -> TAny, open an element keyed with key;
• EndMap() -> TParent, close map;
• Do(TFuncMap func) -> TFluentMap, same as Do() for TAny;
• DoIf(bool condition, TFuncMap func) -> TFluentMap, same as DoIf() for TAny;
• DoFor(TCollection collection, TFuncMap func) -> TFluentMap, same as DoFor() for TAny.

TFluentList:

• Item() -> TAny, open an new list element;
• EndList() -> TParent, close list;
• Do(TFuncList func) -> TFluentList, same as Do() for TAny;
• DoIf(bool condition, TFuncList func) -> TFluentList, same as DoIf() for TAny;
• DoFor(TCollection collection, TListMap func) -> TFluentList, same as DoFor() for TAny.

TFluentAttributes:

• Item(TStringBuf key) -> TAny, open an element keyed with key.
• EndAttributes() -> TParentWithoutAttributes, close attributes. Note that this method leads to a context that is forces not to have attributes, preventing us from putting attributes twice before an object.
• Do(TFuncAttributes func) -> TFluentAttributes, same as Do() for TAny;
• DoIf(bool condition, TFuncAttributes func) -> TFluentAttributes, same as DoIf() for TAny;
• DoFor(TCollection collection, TListAttributes func) -> TFluentAttributes, same as DoFor() for TAny.