From: Francis Dupont Date: Fri, 21 Sep 2018 23:29:59 +0000 (+0200) Subject: [65-libyang-option-data] Moved syntax comments - capitalized YANG X-Git-Tag: 65-libyang-option-data_before_rebase~5 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7a36a3b36e99cc685380ea6bdba1f8cd7413a050;p=thirdparty%2Fkea.git [65-libyang-option-data] Moved syntax comments - capitalized YANG --- 7a36a3b36e99cc685380ea6bdba1f8cd7413a050 diff --cc src/lib/yang/adaptor.h index 0000000000,31ac5fd465..fa1bbd6884 mode 000000,100644..100644 --- a/src/lib/yang/adaptor.h +++ b/src/lib/yang/adaptor.h @@@ -1,0 -1,133 +1,133 @@@ + // Copyright (C) 2018 Internet Systems Consortium, Inc. ("ISC") + // + // This Source Code Form is subject to the terms of the Mozilla Public + // License, v. 2.0. If a copy of the MPL was not distributed with this + // file, You can obtain one at http://mozilla.org/MPL/2.0/. + + #ifndef ISC_ADAPTOR_H + #define ISC_ADAPTOR_H 1 + + #include + #include + + namespace isc { + namespace yang { + + /// @brief Missing key error. + class MissingKey : public isc::Exception { + public: + MissingKey(const char* file, size_t line, const char* what) : + isc::Exception(file, line, what) + {} + }; + -/// @brief JSON adaptor between canonical Kea and Yang models. ++/// @brief JSON adaptor between canonical Kea and YANG models. + /// + /// An adaptor slightly modifies a JSON configuration between canonical Kea -/// what required or rendered by a Yang model, e.g. moving a parameter ++/// what required or rendered by a YANG model, e.g. moving a parameter + /// to/from a parent. + /// The basic adaptor provides a set of tools. + class Adaptor { + public: + + /// @brief Constructor. + Adaptor(); + + /// @brief Destructor. + virtual ~Adaptor(); + + /// @brief Get user context. + /// + /// Get user-context and/or comment and return it with the comment + /// if exists moved inside the user-context (without checking if + /// there is already a comment as it should never be the case). + /// + /// This behavior is used to handle comments. For historical purposes + /// Kea allows to define comments in some scopes. Once the user-context + /// has been introduced, the comment (as a separate text field) + /// disappeared and was moved to comment key within user-context. + /// Nevertheless, the old syntax is still supported. + static isc::data::ConstElementPtr + getContext(isc::data::ConstElementPtr parent); + + /// @brief Moves a parameter from parent to a list of children. + /// + /// Move a parameter from the parent to each item in a list. + /// If the parameter exists in a child, it is skipped for this + /// particular child, not overridden. + /// + /// @param name The parameter name. + /// @param parent The parent element. + /// @param list The children list. + static void fromParent(const std::string& name, + isc::data::ConstElementPtr parent, + isc::data::ConstElementPtr list); + + /// @brief Moves a parameter to a parent. + /// + /// Move a parameter from children to the parent. All children + /// on the list must have the parameter specified and it has to have + /// the same value. + /// + /// @param name The parameter name. + /// @param parent The parent element. + /// @param list The children list. + static void toParent(const std::string& name, + isc::data::ElementPtr parent, + isc::data::ConstElementPtr list); + + /// @brief Modify a configuration in its JSON element format. + /// + /// Smart merging tool, e.g. completing a from yang configuration. + /// + /// A modification is a path and actions: + /// - path item can be: + /// * a string: current scope is a map, go down following the string + /// as a key. + /// * a number: current scope is a list, go down the number as an index. + /// * special value -1: current scope is a list, apply to all items. + /// * map { "": }: current scope is a list, go down to + /// the item using the key / value pair. + /// - an action can be: insert, replace or delete: + /// * insert adds a value at a key: + /// . in a map the key is the new entry key + /// . in a list an integer key is the new element index + /// . in a list a map key is the key / value pair the to-be-modified + /// element contains + /// * replace adds or replaces if it already exists a value at + /// an entry key in a map. + /// * delete removes a value designed by a key + /// + /// For instance to add a control-socket entry in a configuration + /// from a generic (vs Kea) model: + /// @code + /// path := [ ] + /// actions := [ { + /// "action": "insert", + /// "key": "Dhcp4", + /// "value": + /// { + /// "control-socket": + /// { + /// "socket-type": "unix", + /// "socket-name": "/tmp/kea4-ctrl-socket" + /// } + /// } + /// } + /// @endcode + /// + /// @param path The search list to follow down to the place to + /// apply the action list. + /// @param actions The action list + /// @param config The configuration (JSON map) to modify. + /// @note modify does not throw but returns on unexpected conditions. + static void modify(isc::data::ConstElementPtr path, + isc::data::ConstElementPtr actions, + isc::data::ElementPtr config); + + }; + + }; // end of namespace isc::yang + }; // end of namespace isc + + #endif // ISC_ADAPTOR_H diff --cc src/lib/yang/translator.h index ec79611dba,ec79611dba..866d66f040 --- a/src/lib/yang/translator.h +++ b/src/lib/yang/translator.h @@@ -15,7 -15,7 +15,7 @@@ namespace isc { namespace yang { --/// @brief Between Yang and JSON translator class for basic values. ++/// @brief Between YANG and JSON translator class for basic values. class TranslatorBasic { public: @@@ -27,7 -27,7 +27,7 @@@ /// @brief Destructor. virtual ~TranslatorBasic(); -- /// @brief Translate basic value from Yang to JSON. ++ /// @brief Translate basic value from YANG to JSON. /// /// @note Please don't use this outside tests. /// @@@ -36,7 -36,7 +36,7 @@@ /// @throw NotImplemented when the value type is not supported. static isc::data::ElementPtr value(S_Val s_val); -- /// @brief Get and translate basic value from Yang to JSON. ++ /// @brief Get and translate basic value from YANG to JSON. /// /// @note Should be const as it is read only... /// @@@ -47,14 -47,14 +47,14 @@@ /// @throw NotImplemented when the value type is not supported. isc::data::ElementPtr getItem(const std::string& xpath); -- /// @brief Get and translate a list of basic values from Yang to JSON. ++ /// @brief Get and translate a list of basic values from YANG to JSON. /// /// @param xpath The xpath of the list of basic values. /// @return The ListElement representing the leaf-list at xpath or /// null when not found. isc::data::ElementPtr getItems(const std::string& xpath); -- /// @brief Translate basic value from JSON to Yang. ++ /// @brief Translate basic value from JSON to YANG. /// /// @note Please don't use this outside tests. /// @@@ -62,7 -62,7 +62,7 @@@ /// @param type The sysrepo type. static S_Val value(isc::data::ConstElementPtr elem, sr_type_t type); -- /// @brief Translate and set basic value from JSON to Yang. ++ /// @brief Translate and set basic value from JSON to YANG. /// /// @param xpath The xpath of the basic value. /// @param elem The JSON element. @@@ -70,20 -70,20 +70,20 @@@ void setItem(const std::string& xpath, isc::data::ConstElementPtr elem, sr_type_t type); -- /// @brief Delete basic value from Yang. ++ /// @brief Delete basic value from YANG. /// /// @param xpath The xpath of the basic value. void delItem(const std::string& xpath); /// List iterator methods keeping the session private. -- /// @brief Get iterator over a Yang list. ++ /// @brief Get iterator over a YANG list. /// /// @param xpath The xpath of the list. /// @return An S_Iter_Value pointer. Null is the list does not exist. S_Iter_Value getIter(const std::string& xpath); -- /// @brief Get xpath of the next Yang list item. ++ /// @brief Get xpath of the next YANG list item. /// /// @param iter The iterator pointing to the previous element /// @return The xpath of the next element. Empty string when at the end of the list. diff --cc src/lib/yang/translator_option_data.h index 3600a80611,3600a80611..fdd3c88135 --- a/src/lib/yang/translator_option_data.h +++ b/src/lib/yang/translator_option_data.h @@@ -13,7 -13,7 +13,35 @@@ namespace isc { namespace yang { --// @brief Between Yang and JSON translator class for the option data. ++// @brief A translator class for converting an option data between ++// YANG and JSON. ++// ++// Currently supports on kea-dhcp[46]-server, not yet ietf-dhcpv6-server. ++// ++// JSON syntax for Kea DHCP with command channel is: ++// @code ++// { ++// "code": , ++// "name": , ++// "space": , ++// "csv-format": , ++// "data": , ++// "always-send": , ++// "user-context": { }, ++// "comment": "" ++// } ++// @endcode ++// ++// YANG syntax for kea-dhcp[46] with code and space as keys is: ++// @code ++// +--rw name? string ++// +--rw data? string ++// +--rw code uint8 / uint16 ++// +--rw space string ++// +--rw csv-format? string ++// +--rw always-send? boolean ++// +--rw user-context? string ++// @endcode class TranslatorOptionData : virtual public TranslatorBasic { public: @@@ -26,28 -26,28 +54,15 @@@ /// @brief Destructor. virtual ~TranslatorOptionData(); -- /// @brief Get and translate an option data from Yang to JSON. ++ /// @brief Get and translate an option data from YANG to JSON. /// -- /// JSON syntax for Kea DHCP with command channel is: -- /// @code -- /// { -- /// "code": , -- /// "name": , -- /// "space": , -- /// "csv-format": , -- /// "data": , -- /// "always-send": , -- /// "user-context": { }, -- /// "comment": "" -- /// } -- /// @endcode /// /// @param xpath The xpath of the option data. /// @return JSON representation of the option data. /// @throw SysrepoError when sysrepo raises an error. isc::data::ElementPtr getOptionData(const std::string& xpath); -- /// @brief Translate and set option data from JSON to Yang. ++ /// @brief Translate and set option data from JSON to YANG. /// /// @param xpath The xpath of the option data. /// @param elem The JSON element. @@@ -64,17 -64,17 +79,6 @@@ protected /// @brief setOptionData for kea-dhcp[46]. /// -- /// Yang syntax for kea-dhcp[46] with code and space as keys is: -- /// @code -- /// +--rw name? string -- /// +--rw data? string -- /// +--rw code uint8 / uint16 -- /// +--rw space string -- /// +--rw csv-format? string -- /// +--rw always-send? boolean -- /// +--rw user-context? string -- /// @endcode -- /// /// @param xpath The xpath of the option data. /// @param elem The JSON element. void setOptionDataKea(const std::string& xpath, @@@ -84,7 -84,7 +88,13 @@@ std::string model_; }; --// @brief Between Yang and JSON translator class for option data list. ++// @brief A translator class for converting an option data list between ++// YANG and JSON. ++// ++// Currently supports on kea-dhcp[46]-server, not yet ietf-dhcpv6-server. ++// ++// YANG syntax is a option-data list keyed by code and space. ++// class TranslatorOptionDataList : virtual public TranslatorOptionData { public: @@@ -97,13 -97,13 +107,13 @@@ /// @brief Destructor. virtual ~TranslatorOptionDataList(); -- /// @brief Get and translate option data list from Yang to JSON. ++ /// @brief Get and translate option data list from YANG to JSON. /// /// @param xpath The xpath of the option data list. /// @throw SysrepoError when sysrepo raises an error. isc::data::ConstElementPtr getOptionDataList(const std::string& xpath); -- /// @brief Translate and set option data list from JSON to Yang. ++ /// @brief Translate and set option data list from JSON to YANG. /// /// @param xpath The xpath of the option data list. /// @param elem The JSON element. @@@ -119,8 -119,8 +129,6 @@@ protected /// @brief setOptionDataList for kea-dhcp[46]. /// -- /// Yang syntax is a option-data list keyed by code and space. -- /// /// @param xpath The xpath of the option data list. /// @param elem The JSON element. void setOptionDataListKea(const std::string& xpath, diff --cc src/lib/yang/yang.dox index da9de2b373,93c88397cb..ea4bbb3d36 --- a/src/lib/yang/yang.dox +++ b/src/lib/yang/yang.dox @@@ -5,13 -5,13 +5,13 @@@ // file, You can obtain one at http://mozilla.org/MPL/2.0/. /** -- @page libyang libkea-yang - Kea Yang Utilities Library ++ @page libyang libkea-yang - Kea YANG Utilities Library The libkea-yang library was developed to handle base YANG operations, such are retrieving YANG schema and configuration and translating data between YANG syntax and JSON that is understandable by Kea. --@section yangTranslator Translator between Yang and JSON ++@section yangTranslator Translator between YANG and JSON An essential concept is the idea of translator. It is a primitive that is able to convert certain data structure between YANG and JSON. It is envisaged @@@ -33,12 -33,12 +33,12 @@@ is responsible for maintaining a connec the basic / base class and recursively of translators for embedded parts. @c isc::yang::TranslatorBasic provides some methods: -- - getItem() gets and translates basic value from Yang to JSON -- - getItems() gets and translates a leaf-list from Yang to JSON ++ - getItem() gets and translates basic value from YANG to JSON ++ - getItems() gets and translates a leaf-list from YANG to JSON (for a list please use an iterator) -- - setItem() translates and sets a basic value from JSON to Yang ++ - setItem() translates and sets a basic value from JSON to YANG - delItem() deletes a value -- - getIter() gets an iterator over a Yang list ++ - getIter() gets an iterator over a YANG list - getNext() returns the xpath of the next item @section yangTranslatorPool Pool translator @@@ -62,6 -62,16 +62,16 @@@ Note pools show two shortcomings in IET The new thing here is the use of adaptors to move timers from subnets to pools and back. + @section yangAdaptor Adapting JSON configuration + + Adaptors are tools which adapts JSON complete or partial configuration -before translation to Yang to ease this translation or after translation -from Yang to follow the Kea syntax, for instance by adding static ++before translation to YANG to ease this translation or after translation ++from YANG to follow the Kea syntax, for instance by adding static + components which are not in the model. + + Methods provided by adaptors are class methods (i.e. declared static). + Specific adaptors are derived from the isc::yang::Adaptor base class. + @page unitTestsSysrepo Running unit-tests with Sysrepo To run YANG/NETCONF/Sysrepo tests you obviously need to compile Kea with