From a71c6b976fa79fa3bcd0e61850a1a57071159b28 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Thu, 9 Aug 2012 18:00:13 +0200 Subject: Update user config to use nested tuple keys ct:get_config and ct:require can now use nested tuples to fetch data from user configuration. E.g. ct:get_config({localhost,ip,v4}). This introduces a backwards incompatability with how names are associated with keys when using require/2. E.g. ct:require(a_name,{localhost,ip}) will associate a_name with ip instead of localhost. --- lib/common_test/src/ct.erl | 97 ++++++++++++++++++++++++++-------------------- 1 file changed, 54 insertions(+), 43 deletions(-) (limited to 'lib/common_test/src/ct.erl') diff --git a/lib/common_test/src/ct.erl b/lib/common_test/src/ct.erl index 6373634812..922f794395 100644 --- a/lib/common_test/src/ct.erl +++ b/lib/common_test/src/ct.erl @@ -266,27 +266,34 @@ stop_interactive() -> %%%----------------------------------------------------------------- %%% @spec require(Required) -> ok | {error,Reason} -%%% Required = Key | {Key,SubKeys} +%%% Required = Key | {Key,SubKeys} | {Key,SubKey,SubKeys} %%% Key = atom() %%% SubKeys = SubKey | [SubKey] %%% SubKey = atom() %%% -%%% @doc Check if the required configuration is available. +%%% @doc Check if the required configuration is available. It is possible +%%% to specify arbitrarily deep tuples as Required. Note that it is +%%% only the last element of the tuple which can be a list of SubKeys. %%% -%%%

Example: require the variable myvar:
-%%% ok = ct:require(myvar)

+%%%

Example 1: require the variable myvar:

+%%% 
ok = ct:require(myvar).
%%% %%%

In this case the config file must at least contain:

-%%% 
-%%% {myvar,Value}.
+%%% 
{myvar,Value}.
%%% -%%%

Example: require the variable myvar with -%%% subvariable sub1:
-%%% ok = ct:require({myvar,sub1})

+%%%

Example 2: require the key myvar with +%%% subkeys sub1 and sub2:

+%%% 
ok = ct:require({myvar,[sub1,sub2]}).
%%% %%%

In this case the config file must at least contain:

-%%% 
-%%% {myvar,[{sub1,Value}]}.
+%%% 
{myvar,[{sub1,Value},{sub2,Value}]}.
+%%% +%%%

Example 3: require the key myvar with +%%% subkey sub1 with subsub1:

+%%% 
ok = ct:require({myvar,sub1,sub2}).
+%%% +%%%

In this case the config file must at least contain:

+%%% 
{myvar,[{sub1,[{sub2,Value}]}]}.
%%% %%% @see require/2 %%% @see get_config/1 @@ -298,30 +305,36 @@ require(Required) -> %%%----------------------------------------------------------------- %%% @spec require(Name,Required) -> ok | {error,Reason} %%% Name = atom() -%%% Required = Key | {Key,SubKeys} +%%% Required = Key | {Key,SubKey} | {Key,SubKey,SubKey} +%%% SubKey = Key %%% Key = atom() -%%% SubKeys = SubKey | [SubKey] -%%% SubKey = atom() %%% %%% @doc Check if the required configuration is available, and give it -%%% a name. +%%% a name. The semantics for Required is the same as in +%%% required/1 except that it is not possible to specify a list +%%% of SubKeys. %%% -%%%

If the requested data is available, the main entry will be +%%%

If the requested data is available, the sub entry will be %%% associated with Name so that the value of the element %%% can be read with get_config/1,2 provided -%%% Name instead of the Key.

+%%% Name instead of the whole Required term.

%%% %%%

Example: Require one node with a telnet connection and an -%%% ftp connection. Name the node a:
ok = -%%% ct:require(a,{node,[telnet,ftp]}).
All references -%%% to this node may then use the node name. E.g. you can fetch a -%%% file over ftp like this:
-%%% ok = ct:ftp_get(a,RemoteFile,LocalFile).

+%%% ftp connection. Name the node a: +%%% 
ok = ct:require(a,{machine,node}).
+%%% All references to this node may then use the node name. +%%% E.g. you can fetch a file over ftp like this:

+%%% 
ok = ct:ftp_get(a,RemoteFile,LocalFile).
%%% %%%

For this to work, the config file must at least contain:

-%%% 
-%%% {node,[{telnet,IpAddr},
-%%%        {ftp,IpAddr}]}.
+%%% 
{machine,[{node,[{telnet,IpAddr},{ftp,IpAddr}]}]}.
+%%% +%%% The behaviour of this function changed radically in common_test +%%% 1.6.2. In order too keep some backwards compatability it is still possible +%%% to do:
ct:require(a,{node,[telnet,ftp]}).
+%%% This will associate the name a with the top level node entry. +%%% For this to work, the config file must at least contain:
+%%% {node,[{telnet,IpAddr},{ftp,IpAddr}]}. %%% %%% @see require/1 %%% @see get_config/1 @@ -344,7 +357,7 @@ get_config(Required,Default) -> %%%----------------------------------------------------------------- %%% @spec get_config(Required,Default,Opts) -> ValueOrElement -%%% Required = KeyOrName | {KeyOrName,SubKey} +%%% Required = KeyOrName | {KeyOrName,SubKey} | {KeyOrName,SubKey,SubKey} %%% KeyOrName = atom() %%% SubKey = atom() %%% Default = term() @@ -362,25 +375,25 @@ get_config(Required,Default) -> %%%

Example, given the following config file:

%%% 
 %%% {unix,[{telnet,IpAddr},
-%%%        {username,Username},
-%%%        {password,Password}]}.
-%%%

get_config(unix,Default) -> +%%% {user,[{username,Username}, +%%% {password,Password}]}]}. +%%%

ct:get_config(unix,Default) -> %%% [{telnet,IpAddr}, -%%% {username,Username}, -%%% {password,Password}]
-%%% get_config({unix,telnet},Default) -> IpAddr
-%%% get_config({unix,ftp},Default) -> Default
-%%% get_config(unknownkey,Default) -> Default

+%%% {user, [{username,Username}, +%%% {password,Password}]}]
+%%% ct:get_config({unix,telnet},Default) -> IpAddr
+%%% ct:get_config({unix,user,username},Default) -> Username
+%%% ct:get_config({unix,ftp},Default) -> Default
+%%% ct:get_config(unknownkey,Default) -> Default

%%% %%%

If a config variable key has been associated with a name (by %%% means of require/2 or a require statement), the name %%% may be used instead of the key to read the value:

%%% -%%%

require(myhost,unix) -> ok
-%%% get_config(myhost,Default) -> -%%% [{telnet,IpAddr}, -%%% {username,Username}, -%%% {password,Password}]

+%%%

ct:require(myuser,{unix,user}) -> ok.
+%%% ct:get_config(myuser,Default) -> +%%% [{username,Username}, +%%% {password,Password}]

%%% %%%

If a config variable is defined in multiple files and you want to %%% access all possible values, use the all option. The @@ -390,9 +403,7 @@ get_config(Required,Default) -> %%% %%%

If you want config elements (key-value tuples) returned as result %%% instead of values, use the element option. -%%% The returned elements will then be on the form {KeyOrName,Value}, -%%% or (in case a subkey has been specified) -%%% {{KeyOrName,SubKey},Value}

+%%% The returned elements will then be on the form {Required,Value}

%%% %%% @see get_config/1 %%% @see get_config/2 @@ -403,7 +414,7 @@ get_config(Required,Default,Opts) -> %%%----------------------------------------------------------------- %%% @spec reload_config(Required) -> ValueOrElement -%%% Required = KeyOrName | {KeyOrName,SubKey} +%%% Required = KeyOrName | {KeyOrName,SubKey} | {KeyOrName,SubKey,SubKey} %%% KeyOrName = atom() %%% SubKey = atom() %%% ValueOrElement = term() -- cgit v1.2.3