Update notes

Update the notes in tc_config.h
This commit is contained in:
Douwanna 2020-05-24 01:25:18 +08:00 committed by GitHub
parent 344764f48f
commit e2fc261aec
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -29,26 +29,31 @@ namespace tars
/** /**
* @file tc_config.h * @file tc_config.h
* @brief . * @brief .
* @brief Config File Reading Class
*/ */
///////////////////////////////////////////////// /////////////////////////////////////////////////
/** /**
* *
* Field Separator
*/ */
const char TC_CONFIG_DOMAIN_SEP = '/'; const char TC_CONFIG_DOMAIN_SEP = '/';
/** /**
* *
* Parameter Start Character
*/ */
const char TC_CONFIG_PARAM_BEGIN = '<'; const char TC_CONFIG_PARAM_BEGIN = '<';
/** /**
* *
* Parameter Ender Character
*/ */
const char TC_CONFIG_PARAM_END = '>'; const char TC_CONFIG_PARAM_END = '>';
/** /**
* @brief . * @brief .
* @brief Config File Exception Class
*/ */
struct TC_Config_Exception : public TC_Exception struct TC_Config_Exception : public TC_Exception
{ {
@ -59,6 +64,7 @@ struct TC_Config_Exception : public TC_Exception
/** /**
* @brief * @brief
* @brief No Config File Error
*/ */
struct TC_ConfigNoParam_Exception : public TC_Exception struct TC_ConfigNoParam_Exception : public TC_Exception
{ {
@ -69,6 +75,7 @@ struct TC_ConfigNoParam_Exception : public TC_Exception
/** /**
* @brief . * @brief .
* @brief Class that defines the domain in the configuration file
*/ */
class TC_ConfigDomain class TC_ConfigDomain
{ {
@ -77,27 +84,34 @@ public:
/** /**
* @brief . * @brief .
* @brief Constructor
* *
* @param sLine * @param sLine
* @param sLine Refers to a line in the configuration file, read by line
*/ */
TC_ConfigDomain(const string &sLine); TC_ConfigDomain(const string &sLine);
/** /**
* @brief . * @brief .
* @brief Destructor
*/ */
~TC_ConfigDomain(); ~TC_ConfigDomain();
/** /**
* @brief . * @brief .
* @brief Copy
* *
* @param tcd TC_ConfigDomain对象 * @param tcd TC_ConfigDomain对象
* @param tcd a TC_ConfigDomain object, refers to a domain of the configuration file
*/ */
TC_ConfigDomain(const TC_ConfigDomain &tcd); TC_ConfigDomain(const TC_ConfigDomain &tcd);
/** /**
* @brief . * @brief .
* @brief Assignment
* *
* @param tcd TC_ConfigDomain对象 * @param tcd TC_ConfigDomain对象
* @param tcd a TC_ConfigDomain object, refers to a domain of the configuration file
*/ */
TC_ConfigDomain& operator=(const TC_ConfigDomain &tcd); TC_ConfigDomain& operator=(const TC_ConfigDomain &tcd);
@ -110,42 +124,63 @@ public:
/** /**
* @brief domain * @brief domain
* @brief Parse a domain
* "/Main/Domain<Name>"path进行解析 * "/Main/Domain<Name>"path进行解析
* DomainPath _domains和路径中对应的配置项_param. * DomainPath _domains和路径中对应的配置项_param.
* *
* Parsing a path like'/Main/Domain<Name>'results in a DomainPath type,
* including the path'_domains' and the corresponding configuration item in the path '_param'
*
* @param path * @param path
* @param path A processed string must meet certain requirements
* @param bWithParam "/Main/Domain<Name>"bWithParam为ture * @param bWithParam "/Main/Domain<Name>"bWithParam为ture
* "/Main/Domain"bWithParam为false * "/Main/Domain"bWithParam为false
* @param bWithParam bool: true, when'/Main/Domain<Name>';
* false, when'/Main/Domain'
* @return DomainPath DomainPath对象 * @return DomainPath DomainPath对象
* @return DomainPath A DomainPath object that resolves domain names and parameters in a domain
*/ */
static DomainPath parseDomainName(const string& path, bool bWithParam); static DomainPath parseDomainName(const string& path, bool bWithParam);
/** /**
* @brief * @brief
* @brief Add Subdomain Name
* name是子域的名字"/Main/Domain" * name是子域的名字"/Main/Domain"
* name为subDomain的子域,"/Main/Domain/subDomain" * name为subDomain的子域,"/Main/Domain/subDomain"
* Add a subdomain, and 'name' is its name, such as "/Main/Domain"
* Add an other subdomain which named 'subDomain', such as "/Main/Domain/subDomain"
*
* *
* @param name * @param name
* @param name subdomain name
* @return TC_ConfigDomain* * @return TC_ConfigDomain*
* @return TC_ConfigDomain* the pointer which points to the subdomain
* @throws TC_Config_Exception * @throws TC_Config_Exception
*/ */
TC_ConfigDomain* addSubDomain(const string& name); TC_ConfigDomain* addSubDomain(const string& name);
/** /**
* @brief Sub Domain. * @brief Sub Domain.
* @brief Recursive search subdomain Sub Domain.
* *
* @param itBegin _domains的顶部 * @param itBegin _domains的顶部
* @param itBegin iterator, point to the button of the _domain
* @param itEnd _domains的底部 * @param itEnd _domains的底部
* @param itBegin iterator, point to the button of the _domain
* @return TC_ConfigDomain* * @return TC_ConfigDomain*
* @return TC_ConfigDomain* a point point to the target subdomain
*/ */
TC_ConfigDomain *getSubTcConfigDomain(vector<string>::const_iterator itBegin, vector<string>::const_iterator itEnd); TC_ConfigDomain *getSubTcConfigDomain(vector<string>::const_iterator itBegin, vector<string>::const_iterator itEnd);
const TC_ConfigDomain *getSubTcConfigDomain(vector<string>::const_iterator itBegin, vector<string>::const_iterator itEnd) const; const TC_ConfigDomain *getSubTcConfigDomain(vector<string>::const_iterator itBegin, vector<string>::const_iterator itEnd) const;
/** /**
* @brief Get Param Value /. * @brief Get Param Value /.
* @brief Get Param Value Get parameter/value pairs.
* *
* @param sName * @param sName
* @param sName Configuration Item Name
* @return * @return
* @return the value of the configration item
*/ */
string getParamValue(const string &sName) const; string getParamValue(const string &sName) const;
@ -153,7 +188,10 @@ public:
* @brief Get Param Map map * @brief Get Param Map map
* map是参数/, * map是参数/,
* eg. SyncThreadNum = 2 * eg. SyncThreadNum = 2
* Map is a parameter/value pair, a key-value pair corresponding to the value of the configuration item and the configuration item,
* eg. SyncThreadNum = 2
* @return map * @return map
* @return a map of parameters and their corresponding values in a domain
*/ */
const map<string, string>& getParamMap() const { return _param; } const map<string, string>& getParamMap() const { return _param; }
@ -168,12 +206,14 @@ public:
* @brief Set Param Value /. * @brief Set Param Value /.
* *
* @param sLine * @param sLine
* @param sLine line
* @return * @return
*/ */
void setParamValue(const string &sLine); void setParamValue(const string &sLine);
/** /**
* @brief key里没有的配置项添加到最后 * @brief key里没有的配置项添加到最后
* @brief Insert a parameter to add a configuration item that is not in the key to the last
* *
* @param map * @param map
*/ */
@ -183,53 +223,68 @@ public:
* @brief Destroy . * @brief Destroy .
* *
* @return * @return
* @return void
*/ */
void destroy(); void destroy();
/** /**
* @brief Get Name * @brief Get Name
* @brief Get Name Get Domain Name
* @return * @return
* @return the domain name
*/ */
string getName() const; string getName() const;
/** /**
* @brief * @brief
* @brief Set Domain Name
* *
* @param * @param
* @param name domain name
*/ */
void setName(const string& name); void setName(const string& name);
/** /**
* @brief key * @brief key
* @brief Get keys in the order they appear in the file
* *
* @return vector<string>key的vector * @return vector<string>key的vector
* @return the vector which stores keys in vector<string>
*/ */
vector<string> getKey() const; vector<string> getKey() const;
/** /**
* @brief line * @brief line
* @brief Get 'line' in the order they appear in the file
* *
* @return vector<string>key的vector * @return vector<string>key的vector
* @return the vector which stores keys in vector<string>
*/ */
vector<string> getLine() const; vector<string> getLine() const;
/** /**
* @brief Domain * @brief Domain
* @brief Get subdomains in the order they appear in the file
* *
* @return vector<string>vector * @return vector<string>vector
* @return the vector which stores keys in vector<string>
*/ */
vector<string> getSubDomain() const; vector<string> getSubDomain() const;
/** /**
* @brief . * @brief .
* @brief Convert to the string format of the configuration file.
* *
* @param i tab的层数 * @param i tab的层数
* @param i number of layers of 'tab'
* @return string类型配置字符串 * @return string类型配置字符串
* @return string type configuration string
*/ */
string tostr(int i) const; string tostr(int i) const;
/** /**
* @brief . * @brief .
* @brief Clone.
* *
* @return TC_ConfigDomain* * @return TC_ConfigDomain*
*/ */
@ -240,6 +295,7 @@ public:
/** /**
* @brief . * @brief .
* @brief Escape.
* *
* @param name * @param name
* @return string * @return string
@ -248,6 +304,7 @@ public:
/** /**
* @brief . * @brief .
* @brief Direction escaping
* *
* @param s * @param s
* @return string * @return string
@ -256,10 +313,14 @@ public:
/** /**
* @brief / * @brief /
* @brief Set param/key pairs
* *
* @param sName * @param sName
* @param sName the name of the configuration item
* @param sValue * @param sValue
* @param sValue the value of the configuration item
* @return * @return
* @return void
*/ */
void setParamValue(const string &sName, const string &sValue); void setParamValue(const string &sName, const string &sValue);
@ -267,51 +328,66 @@ protected:
/** /**
* *
* Domain Name
*/ */
string _name; string _name;
/** /**
* name/value对 * name/value对
* name/value pair, the name and value of the configuration item
*/ */
map<string, string> _param; map<string, string> _param;
/** /**
* key也就是配置项的插入顺序 * key也就是配置项的插入顺序
* key, the insertion order of configuration items
*/ */
vector<string> _key; vector<string> _key;
/** /**
* *
* Subdomain
*/ */
map<string, TC_ConfigDomain*> _subdomain; map<string, TC_ConfigDomain*> _subdomain;
/** /**
* *
* the insertion order of the domain
*/ */
vector<string> _domain; vector<string> _domain;
/** /**
* *
* Configuration list for the whole row
*/ */
vector<string> _line; vector<string> _line;
}; };
/** /**
* @brief wbl模式. * @brief wbl模式.
* @brief Define the class of the profile (compatible with WBL mode).
* string中解析配置文件 * string中解析配置文件
* Support parsing configuration files from strings;
* *
* Support the generation of configuration files;
* *
* Parse error and throw exception;
* [] * []
* Use [] to get the configuration and throw an exception if there is no configuration;
* get获取配置 * get获取配置
* Use 'get' to get the configuration, and return null if it doesn't exist
* 线insert域等函数非线程安全 * 线insert域等函数非线程安全
* Reading configuration files is thread-safe, functions such as insert fields are not thread-safe;
* *
* For example:
* <Main> * <Main>
* <Domain> * <Domain>
@ -323,8 +399,11 @@ protected:
* </Main> * </Main>
* :conf["/Main/Domain<Name>"] Map: * :conf["/Main/Domain<Name>"] Map:
* getDomainMap("/Main/Domain", m); m得到Name/Value对 * Get parameter: conf ["/Main/Domain<Name>"] Get domain Map:
* getDomainMap("/Main/Domain", m); m得到Name/Value对
* getDomainMap("/Main/Domain", m); 'm' can get the Name/Value pair
* Vector: getDomainVector("/Main", v); v得到Domain列表 * Vector: getDomainVector("/Main", v); v得到Domain列表
* Get Domain Vector: getDomainVector ('/Main', v); 'v' can get a list of Domains to increase the number of the value pairs under the domain or domain
*/ */
class TC_Config class TC_Config
@ -333,11 +412,13 @@ public:
/** /**
* @brief * @brief
* @brief Constructor
*/ */
TC_Config(); TC_Config();
/** /**
* @brief . * @brief .
* @brief Copy
* *
* @param tc为TC_Config类型 * @param tc为TC_Config类型
*/ */
@ -345,6 +426,7 @@ public:
/** /**
* @brief . * @brief .
* @brief Assignment
* *
* @param tcd * @param tcd
* @return TC_Config& * @return TC_Config&
@ -353,18 +435,24 @@ public:
/** /**
* @brief . * @brief .
* @brief Parse the file.
* *
* fileName对应的文件转化为输入流后调用parse对其进行解析 * fileName对应的文件转化为输入流后调用parse对其进行解析
* Convert the file corresponding to fileName into an input stream and call parse to parse it.
* @param sFileName : * @param sFileName :
* @param sFileName file name
* @return * @return
* @return void
* @throws TC_Config_Exception * @throws TC_Config_Exception
*/ */
void parseFile(const string& sFileName); void parseFile(const string& sFileName);
/** /**
* @brief . * @brief .
* @brief Parse string
* *
* string parse对其进行解析 * string parse对其进行解析
* Convert string type to input stream and call parse to parse it
* @return void * @return void
* @throws TC_Config_Exception * @throws TC_Config_Exception
*/ */
@ -373,8 +461,12 @@ public:
/** /**
* @brief , * @brief ,
* /Main/Domain<Param>/Main/Domain下的配置项名字为Param的值 * /Main/Domain<Param>/Main/Domain下的配置项名字为Param的值
* @brief Get value.
* If no exception is thrown, for strings of which type like /Main/Domain<Param>, get the value of the configuration item named 'Param' under the domain '/Main/Domain'
* @param sName ,: /Main/Domain<Param> * @param sName ,: /Main/Domain<Param>
* @param sName param name, like: /Main/Domain<Param>
* @return * @return
* @return the value of the configuration file
* @throws TC_Config_Exception * @throws TC_Config_Exception
*/ */
string operator[](const string &sName) const; string operator[](const string &sName) const;
@ -382,82 +474,119 @@ public:
/** /**
* @brief , ,. * @brief , ,.
* /Main/Domain<Param>/Main/Domain下的配置项名字为Param的值 * /Main/Domain<Param>/Main/Domain下的配置项名字为Param的值
* @brief Get value. Note that if no exception is thrown, an empty string is returned.
* For strings of type like'/main/domain<param>', get the value of the configuration item named 'Param' under the domain '/Main/Domain'
* @param sName , : /Main/Domain<Param> * @param sName , : /Main/Domain<Param>
* @param sName param name, like: /Main/Domain<Param>
* @return * @return
* @return the value of the configuration file
*/ */
string get(const string &sName, const string &sDefault="") const; string get(const string &sName, const string &sDefault="") const;
/** /**
* @brief . * @brief .
* @brief Set Value
* @param sName , : /Main/Domain<Param> * @param sName , : /Main/Domain<Param>
* @param sName param name, like: /Main/Domain<Param>
*/ */
void set(const string &sName, const string &value); void set(const string &sName, const string &value);
/** /**
* @brief GetDomainParamMap获取域下面的参数值对. * @brief GetDomainParamMap获取域下面的参数值对.
* @brief GetDomainParamMap Get the parameter-value pair under the domain
* *
* @param path , , : /Main/Domain * @param path , , : /Main/Domain
* @param path domain name, domain identifier, such as: '/Main/Domain'
* @param m map<string, string>map列表 * @param m map<string, string>map列表
* @param m map<string, string> type, the map list in the domain
* @return bool, * @return bool,
* @return bool, return the parameter-value pair under the domain
*/ */
bool getDomainMap(const string &path, map<string, string> &m) const; bool getDomainMap(const string &path, map<string, string> &m) const;
/** /**
* @brief ,map. * @brief ,map.
* @brief Get the parameter value pair under the domain. If it is not saved, an empty map will be returned.
* *
* @param path , , : /Main/Domain * @param path , , : /Main/Domain
* @param path domain name, domain identifier, such as: '/Main/Domain'
* @return map<string,string>, * @return map<string,string>,
* @return bool, return the parameter-value pair under the domain
*/ */
map<string, string> getDomainMap(const string &path) const; map<string, string> getDomainMap(const string &path) const;
/** /**
* @brief key, * @brief key,
* @brief Get all the keys under the domain and return them in line order
* @param path , , : /Main/Domain * @param path , , : /Main/Domain
* @param path domain name, domain identifier, such as: '/Main/Domain'
* @return vector<string>key * @return vector<string>key
* @return vector<string>All keys under a certain ID
*/ */
vector<string> getDomainKey(const string &path) const; vector<string> getDomainKey(const string &path) const;
/** /**
* @brief , * @brief ,
* getDomainKey只能获取到key,"=" * getDomainKey只能获取到key,"="
* @brief Get all non domain lines under the domain, and return them in line order of the file
* The difference is that this interface getDomainKey, which can only get the key, also returns the whole line for the configuration with "=".
* @param path , , : /Main/Domain * @param path , , : /Main/Domain
* @param path domain name, domain identifier, such as: '/Main/Domain'
* @return vector<string> * @return vector<string>
* @return vector<string>All non domain lines under a certain ID
*/ */
vector<string> getDomainLine(const string &path) const; vector<string> getDomainLine(const string &path) const;
/** /**
* @brief getDomainMap . * @brief getDomainMap .
* *
*
* @param path , , : /Main/Domain * @param path , , : /Main/Domain
* @param v * @param path domain name, domain identifier, such as: '/Main/Domain'
* @param vector<string> * @param v vector<string>
* @param v the target subdomian namethe domain name under vector<string>
* @return truefalse * @return truefalse
* @return bool: true, successful , false, failed
*/ */
bool getDomainVector(const string &path, vector<string> &v) const; bool getDomainVector(const string &path, vector<string> &v) const;
/** /**
* @brief , * @brief ,
* vector按照在文件中的顺序返回 * vector按照在文件中的顺序返回
* @brief Get the subdomain under the domain
* @param path , , : /Main/Domain * @param path , , : /Main/Domain
* @param path domain name, domain identifier, such as: '/Main/Domain'
* @return vector<string> * @return vector<string>
* @return vector<string> the subdomain under the target domain
*/ */
vector<string> getDomainVector(const string &path) const; vector<string> getDomainVector(const string &path) const;
/** /**
* @brief . * @brief .
* @brief Whether the domain exists or not.
* *
* @param path , , : /Main/Domain * @param path , , : /Main/Domain
* @param path domain name, domain identifier, such as: '/Main/Domain'
* @return truefalse * @return truefalse
* @return If the domain does exist, return true, else return false.
*/ */
bool hasDomainVector(const string &path) const; bool hasDomainVector(const string &path) const;
/** /**
* @brief , sAddDomain域, * @brief , sAddDomain域,
* *
* @brief
Add domain. Add a domain under the current domain. If the sadddomain domain already exists, it is considered to be successful.
* @param sCurDomain , :/Main/Domain * @param sCurDomain , :/Main/Domain
* @param sCurDomain domain identifier, such as: '/Main/Domain'
* @param sAddDomain : : sCurDomain * @param sAddDomain : : sCurDomain
* @param sAddDomain the name of the domain which need to be added: like: sCurDomain
* @param bCreate sCurDomain域不存在的情况下, * @param bCreate sCurDomain域不存在的情况下,
* @param bCreate When the domain sCurDomain does not exist, determine wheter it needs to be created automatically.
* @return 0-, 1-sCurDomain不存在 * @return 0-, 1-sCurDomain不存在
* @return 0 - add successfull, 1 - sCurDomain doesn't exist.
*/ */
int insertDomain(const string &sCurDomain, const string &sAddDomain, bool bCreate); int insertDomain(const string &sCurDomain, const string &sAddDomain, bool bCreate);
@ -465,25 +594,34 @@ public:
/** /**
* @brief , * @brief ,
* , () * , ()
* @brief Add parameter, i.e. configuration item. Add configuration item parameter under the current domain. If there are already related parameters, ignore (do not replace).
* @param sCurDomain , :/Main/Domain * @param sCurDomain , :/Main/Domain
* @param sCurDomain domain identifier, such as: '/Main/Domain'
* @param m map类型 * @param m map类型
* @param m map type, save parameter-value pairs
* @param bCreate sCurDomain域不存在的情况下, * @param bCreate sCurDomain域不存在的情况下,
* @param bCreate When the domain sCurDomain does not exist, determine wheter it needs to be created automatically.
* @return 0: , 1:sCurDomain不存在 * @return 0: , 1:sCurDomain不存在
* @return 0 - add successfull, 1 - sCurDomain doesn't exist.
*/ */
int insertDomainParam(const string &sCurDomain, const map<string, string> &m, bool bCreate); int insertDomainParam(const string &sCurDomain, const map<string, string> &m, bool bCreate);
/** /**
* @brief . * @brief .
* @brief Merge profile to current profile
* *
* @param cf * @param cf
* @param bUpdate true-, false- * @param bUpdate true-, false-
* @param bUpdate true - update the conflict item to this configuration, false - don't update the conflict item
*/ */
void joinConfig(const TC_Config &cf, bool bUpdate); void joinConfig(const TC_Config &cf, bool bUpdate);
/** /**
* @brief . * @brief .
* @brief convert to the string format of the configuration file
* *
* @return * @return
* @return the configuration string
*/ */
string tostr() const; string tostr() const;
@ -491,7 +629,10 @@ protected:
/** /**
* @brief Parse输入流 * @brief Parse输入流
* TC_ConfigDomain装入stack中 * TC_ConfigDomain装入stack中
* @brief Parse Input Stream
* Finally, the input stream is parsed into a TC_ ConfigDomain and is loaded into the stack.
* @param * @param
* @param the input stream, parsed by line
* @throws TC_Config_Exception * @throws TC_Config_Exception
* @return * @return
*/ */
@ -499,9 +640,12 @@ protected:
/** /**
* @brief create New Domain . * @brief create New Domain .
* @brief Create New subdomain
* *
* @param sName * @param sName
* @param sName domain name
* @return * @return
* @return Pointer to the newly generated subfield
* @throws TC_Config_Exception * @throws TC_Config_Exception
*/ */
TC_ConfigDomain *newTcConfigDomain(const string& sName); TC_ConfigDomain *newTcConfigDomain(const string& sName);
@ -510,6 +654,7 @@ protected:
* @brief Search Domain . * @brief Search Domain .
* *
* @param sDomainName , * @param sDomainName ,
* @param sDomainName param name, support the subdomain search
* @return value * @return value
*/ */
TC_ConfigDomain *searchTcConfigDomain(const vector<string>& domains); TC_ConfigDomain *searchTcConfigDomain(const vector<string>& domains);
@ -519,6 +664,7 @@ protected:
/** /**
* domain * domain
* the root domain
*/ */
TC_ConfigDomain _root; TC_ConfigDomain _root;
}; };