Release v2.2

Author: arobenko

comms/doc/page_define_prot.dox

@@ -1025,6 +1025,130 @@
 /// };
 /// @endcode
 ///
+/// @section page_define_prot_field_aliases Aliases to Field Names
+/// When the communication protocol evolves and new versions of it are being released,
+/// it may happen that some fields get renamed to give them a different or refined
+/// meaning. Simple change of the name may result in old client code not being
+/// able to compile with new versions of the protocol definition library. To
+/// help with such case the @b COMMS library provides several macros that can generate
+/// alias names for renamed fields.
+///
+/// @subsection page_define_prot_field_aliases_messages Aliases to Field Names Inside Message Definition
+/// The @b COMMS library provides @ref COMMS_MSG_FIELD_ALIAS()
+/// macro, which is expected to be used after @ref COMMS_MSG_FIELDS_ACCESS() one when new
+/// message class is being defined.
+/// As an example let's change the @b value3 from the example in the 
+/// @ref page_define_prot_message_base_field_names section to be @b newValue3.
+/// @code
+/// template <typename TMessage>
+/// class Message1 : public comms::MessageBase<...>
+/// {
+/// public:
+///     // Provide names for the fields
+///     COMMS_MSG_FIELDS_ACCESS(value1, value2, newValue3);
+///     COMMS_MSG_FIELD_ALIAS(value3, newValue3);
+/// };
+/// @endcode
+/// The usage of @ref COMMS_MSG_FIELD_ALIAS() above generates the following convenience access functions:
+/// @code
+/// template <typename TMessage>
+/// class Message1 : public comms::MessageBase<...>
+/// {
+/// public:
+///     // Provide names for the fields
+///     COMMS_MSG_FIELDS_ACCESS(value1, value2, newValue3);
+///     
+///     // Access to "newValue3" via "value3" name
+///     auto field_value3() -> decltype(field_newValue3())
+///     {
+///         return field_newValue3();
+///     }
+///
+///     // Const access to "newValue3" via "value3" name
+///     auto field_value3() const -> decltype(field_newValue3())
+///     {
+///         return field_newValue3();
+///     }
+/// };
+/// @endcode
+/// In this case the old client code that tries to access appropriate field
+/// using @b field_value3() access function will still work after renaming
+/// takes place.
+///
+/// Another common case is when some field (usually @ref comms::field::IntValue 
+/// or @ref comms::field::EnumValue) has a limited range of possible values
+/// and in order to save on some I/O traffic, the developer decides to split
+/// the value storage into multiple small parts and make it a 
+/// @ref comms::field::Bitfield instead. In order to keep old client code compiling
+/// and working the @ref COMMS_MSG_FIELD_ALIAS() may be used:
+/// @code
+/// template <typename TMessage>
+/// class Message1 : public comms::MessageBase<...>
+/// {
+/// public:
+///     // Provide names for the fields
+///     COMMS_MSG_FIELDS_ACCESS(value1, value2, newValue3);
+///     COMMS_MSG_FIELD_ALIAS(value3, newValue3, member1);
+/// };
+/// @endcode
+/// The usage of @ref COMMS_MSG_FIELD_ALIAS() above generates the following convenience access functions:
+/// @code
+/// template <typename TMessage>
+/// class Message1 : public comms::MessageBase<...>
+/// {
+/// public:
+///     // Provide names for the fields
+///     COMMS_MSG_FIELDS_ACCESS(value1, value2, newValue3);
+///     
+///     // Access to "newValue3.member1" via "value3" name
+///     auto field_value3() -> decltype(field_newValue3().field_member1())
+///     {
+///         return field_newValue3().field_member1();
+///     }
+///
+///     // Const access to "newValue3.member1" via "value3" name
+///     auto field_value3() const -> decltype(field_newValue3().field_member1())
+///     {
+///         return field_newValue3().field_member1();
+///     }
+/// };
+/// @endcode
+///
+/// @subsection page_define_prot_field_aliases_bundles Aliases to Field Names Inside Bundle Fields
+/// Similar to defining aliases to message fields, @b COMMS library provides an ability to define
+/// aliases within @ref comms::field::Bundle "bundle" field definition using
+/// @ref COMMS_FIELD_ALIAS() macro.
+/// @code
+/// class MyBundle : public comms::field::Bundle<...>
+/// {
+/// public:
+///     COMMS_FIELD_MEMBERS_ACCESS(member1, member2, member3);
+///     COMMS_FIELD_ALIAS(otherMem1Name, member1);
+///     COMMS_FIELD_ALIAS(otherMem2Name, member2);
+/// };
+/// @endcode
+///
+/// @subsection page_define_prot_field_aliases_interfaces Aliases to Extra Transport Field Names Inside Interface
+/// The @ref page_define_prot_interface class definition may have
+/// @ref page_define_prot_interface_extra_transport. Aliasing between the 
+/// extra transport fields can be defined using @ref COMMS_MSG_TRANSPORT_FIELD_ALIAS()
+/// macro.
+/// @code
+/// template <typename... TOptions>
+/// class Message : public
+///     comms::Message<
+///         comms::option::def::BigEndian,
+///         comms::option::def::MsgIdType<MsgId>,
+///         comms::option::def::ExtraTransportFields<MyExtraTransportFields>,
+///         TOptions...
+///     >
+/// {
+/// public:
+///     COMMS_MSG_TRANSPORT_FIELDS_ACCESS(version, flags);
+///     COMMS_MSG_TRANSPORT_FIELD_ALIAS(otherFlagsName, flags);    
+/// };
+/// @endcode
+///
 /// @section page_define_prot_lenth_verification Extra Compile Time Checks
 /// Quite often it is obvious from the protocol specification what minimal length
 /// of the serialised message contents is expected to be, and if there are not

comms/include/comms/Field.h

@@ -26,6 +26,7 @@
 #include "comms/details/FieldBase.h"
 #include "comms/details/macro_common.h"
 #include "comms/details/fields_access.h"
+#include "comms/details/field_alias.h"
 
 namespace comms
 {
@@ -501,5 +502,13 @@ class Field : public details::FieldBase<TOptions...>
     COMMS_EXPAND(COMMS_DO_FIELD_ACC_FUNC_NOTEMPLATE(__VA_ARGS__))
 #endif // #ifdef FOR_DOXYGEN_DOC_ONLY
 
+/// @brief Generate convinience alias access member functions for other
+///     member fields.
+/// @details Same as @ref COMMS_MSG_FIELDS_ACCESS() but applicable to
+///     @ref comms::field::Bundle field.
+/// @pre The macro @ref COMMS_FIELD_MEMBERS_ACCESS() needs to be used before
+///     @ref COMMS_FIELD_ALIAS() to define convenience access functions.
+#define COMMS_FIELD_ALIAS(f_, ...) COMMS_DO_ALIAS(field_, f_, __VA_ARGS__)
+
 }  // namespace comms
 

comms/include/comms/Message.h

@@ -33,6 +33,7 @@
 #include "comms/details/transport_fields_access.h"
 #include "comms/details/detect.h"
 #include "comms/details/MessageIdTypeRetriever.h"
+#include "comms/details/field_alias.h"
 
 namespace comms
 {
@@ -685,3 +686,101 @@ using MessageIdType =
     } \
     COMMS_EXPAND(COMMS_DO_TRANSPORT_FIELD_ACC_FUNC(TransportFields, transportFields(), __VA_ARGS__))
 
+/// @brief Generate convinience alias access member functions for extra
+///     member transport fields.
+/// @details The @ref COMMS_MSG_TRANSPORT_FIELD_ALIAS() macro generates convenience
+///     access member functions for extra transport fields. Sometimes the fields
+///     may get renamed or moved to be a member of other fields, like
+///     @ref comms::field::Bundle or @ref comms::field::Bitfield. In such
+///     case the compilation of the existing client code (that already
+///     uses published protocol definition) may fail. To avoid such scenarios
+///     and make the transition to newer versions of the protocol easier,
+///     the @ref COMMS_MSG_TRANSPORT_FIELD_ALIAS() macro can be used to create alias
+///     to other fields. For example, let's assume that some common interface class was defined:
+///     like this.
+///     @code
+///     class MyInterface : public public comms::Message<...>
+///     {
+///     public:
+///         COMMS_MSG_TRANSPORT_FIELDS_ACCESS(name1, name2, name3);
+///     };
+///     @endcode
+///     In the future versions of the protocol "name3" was renamed to
+///     "newName3". To keep the existing code (that uses "name3" name)
+///     compiling it is possible to create an alias access function(s)
+///     with:
+///     @code
+///     class MyInterface : public public comms::Message<...>
+///     {
+///     public:
+///         COMMS_MSG_TRANSPORT_FIELDS_ACCESS(name1, name2, newName3);
+///         COMMS_MSG_TRANSPORT_FIELD_ALIAS(name3, newName3);
+///     };
+///     @endcode
+///     The usage of @ref COMMS_MSG_TRANSPORT_FIELD_ALIAS() in the code above is
+///     equivalent to having the following functions defined:
+///     @code
+///     class MyInterface : public public comms::Message<...>
+///     {
+///     public:
+///         ...
+///         auto transportField_name3() -> decltype(transportField_newName3())
+///         {
+///             return transportField_newName3();
+///         }
+///
+///         auto transportField_name3() const -> decltype(transportField_newName3())
+///         {
+///             return transportField_newName3();
+///         }
+///     };
+///     @endcode
+///     Another example would be a replacing a @ref comms::field::IntValue
+///     with @ref comms::field::Bitfield in the future version of the
+///     protocol. It can happen when the developer decides to split
+///     the used storage into multiple values (because the range
+///     of the used/valid values allows so). In order to keep the old client
+///     code compiling, the access to the replaced field needs to be
+///     an alias to the first member of the @ref comms::field::Bitfield.
+///     In this case the usage of @ref COMMS_MSG_TRANSPORT_FIELD_ALIAS() will
+///     look like this:
+///     @code
+///     class MyInterface : public public comms::Message<...>
+///     {
+///     public:
+///         COMMS_MSG_TRANSPORT_FIELDS_ACCESS(name1, name2, newName3);
+///         COMMS_MSG_TRANSPORT_FIELD_ALIAS(name3, newName3, member1);
+///     };
+///     @endcode
+///     The usage of @ref COMMS_MSG_TRANSPORT_FIELD_ALIAS() in the code above is
+///     equivalent to having the following functions defined:
+///     @code
+///     class MyInterface : public public comms::Message<...>
+///     {
+///     public:
+///         ...
+///         auto transportField_name3() -> decltype(transportField_newName3().field_member1())
+///         {
+///             return field_newName3().field_member1();
+///         }
+///
+///         auto transportField_name3() const -> decltype(transportField_newName3().field_member1())
+///         {
+///             return transportField_newName3().field_member1();
+///         }
+///     };
+///     @endcode
+/// @param[in] f_ Alias field name.
+/// @param[in] ... List of fields' names.
+/// @pre The macro @ref COMMS_MSG_TRANSPORT_FIELDS_ACCESS() needs to be used before
+///     @ref COMMS_MSG_TRANSPORT_FIELD_ALIAS() to define convenience access functions.
+/// @related comms::Message
+/// @see @ref COMMS_MSG_TRANSPORT_FIELD_ALIAS_NOTEMPLATE()
+#define COMMS_MSG_TRANSPORT_FIELD_ALIAS(f_, ...) COMMS_EXPAND(COMMS_DO_ALIAS(transportField_, f_, __VA_ARGS__))
+
+/// @brief Generate convinience alias access member functions for extra
+///     member transport fields in non template interface classes.
+/// @details Similar to @ref COMMS_MSG_TRANSPORT_FIELD_ALIAS, but
+///     needs to be used in @b non-template interface class to
+///     allow compilation with gcc-4.8
+#define COMMS_MSG_TRANSPORT_FIELD_ALIAS_NOTEMPLATE(f_, ...) COMMS_EXPAND(COMMS_DO_ALIAS_NOTEMPLATE(transportField_, f_, __VA_ARGS__))

comms/include/comms/MessageBase.h

@@ -20,10 +20,11 @@
 
 #pragma once
 
-#include "details/MessageImplBuilder.h"
-#include "details/macro_common.h"
-#include "details/fields_access.h"
-#include "details/detect.h"
+#include "comms/details/MessageImplBuilder.h"
+#include "comms/details/macro_common.h"
+#include "comms/details/fields_access.h"
+#include "comms/details/detect.h"
+#include "comms/details/field_alias.h"
 
 namespace comms
 {
@@ -934,3 +935,94 @@ constexpr bool isMessageBase()
         return val; \
     } \
     COMMS_EXPAND(COMMS_DO_FIELD_ACC_FUNC(AllFields, fields(), __VA_ARGS__))
+
+/// @brief Generate convinience alias access member functions for other
+///     member fields.
+/// @details The @ref COMMS_MSG_FIELDS_ACCESS() macro generates convenience
+///     access member functions for member fields. Sometimes the fields
+///     may get renamed or moved to be a member of other fields, like
+///     @ref comms::field::Bundle or @ref comms::field::Bitfield. In such
+///     case the compilation of the existing client code (that already
+///     uses published protocol definition) may fail. To avoid such scenarios
+///     and make the transition to newer versions of the protocol easier,
+///     the @ref COMMS_MSG_FIELD_ALIAS() macro can be used to create alias
+///     to other fields. For example, let's assume that some message class was defined:
+///     like this.
+///     @code
+///     class Message1 : public comms::MessageBase<...>
+///     {
+///     public:
+///         COMMS_MSG_FIELDS_ACCESS(name1, name2, name3);
+///     };
+///     @endcode
+///     In the future versions of the protocol "name3" was renamed to
+///     "newName3". To keep the existing code (that uses "name3" name)
+///     compiling it is possible to create an alias access function(s)
+///     with:
+///     @code
+///     class Message1 : public comms::MessageBase<...>
+///     {
+///     public:
+///         COMMS_MSG_FIELDS_ACCESS(name1, name2, newName3);
+///         COMMS_MSG_FIELD_ALIAS(name3, newName3);
+///     };
+///     @endcode
+///     The usage of @ref COMMS_MSG_FIELD_ALIAS() in the code above is
+///     equivalent to having the following functions defined:
+///     @code
+///     class Message1 : public comms::MessageBase<...>
+///     {
+///     public:
+///         ...
+///         auto field_name3() -> decltype(field_newName3())
+///         {
+///             return field_newName3();
+///         }
+///
+///         auto field_name3() const -> decltype(field_newName3())
+///         {
+///             return field_newName3();
+///         }
+///     };
+///     @endcode
+///     Another example would be a replacing a @ref comms::field::IntValue
+///     with @ref comms::field::Bitfield in the future version of the
+///     protocol. It can happen when the developer decides to split
+///     the used storage into multiple values (because the range
+///     of the used/valid values allows so). In order to keep the old client
+///     code compiling, the access to the replaced field needs to be
+///     an alias to the first member of the @ref comms::field::Bitfield.
+///     In this case the usage of @ref COMMS_MSG_FIELD_ALIAS() will
+///     look like this:
+///     @code
+///     class Message1 : public comms::MessageBase<...>
+///     {
+///     public:
+///         COMMS_MSG_FIELDS_ACCESS(name1, name2, newName3);
+///         COMMS_MSG_FIELD_ALIAS(name3, newName3, member1);
+///     };
+///     @endcode
+///     The usage of @ref COMMS_MSG_FIELD_ALIAS() in the code above is
+///     equivalent to having the following functions defined:
+///     @code
+///     class Message1 : public comms::MessageBase<...>
+///     {
+///     public:
+///         ...
+///         auto field_name3() -> decltype(field_newName3().field_member1())
+///         {
+///             return field_newName3().field_member1();
+///         }
+///
+///         auto field_name3() const -> decltype(field_newName3().field_member1())
+///         {
+///             return field_newName3().field_member1();
+///         }
+///     };
+///     @endcode
+/// @param[in] f_ Alias field name.
+/// @param[in] ... List of fields' names.
+/// @pre The macro @ref COMMS_MSG_FIELDS_ACCESS() needs to be used before
+///     @ref COMMS_MSG_FIELD_ALIAS() to define convenience access functions.
+/// @related comms::MessageBase
+#define COMMS_MSG_FIELD_ALIAS(f_, ...) COMMS_DO_ALIAS(field_, f_, __VA_ARGS__)