diff options
76 files changed, 2290 insertions, 1657 deletions
diff --git a/aclocal.m4 b/aclocal.m4 index 339a15a2bb..a76594d86f 100644 --- a/aclocal.m4 +++ b/aclocal.m4 @@ -59,6 +59,7 @@ AC_ARG_VAR(erl_xcomp_isysroot, [Absolute cross system root include path (only us dnl Cross compilation variables AC_ARG_VAR(erl_xcomp_bigendian, [big endian system: yes|no (only used when cross compiling)]) +AC_ARG_VAR(erl_xcomp_double_middle_endian, [double-middle-endian system: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_clock_gettime_correction, [clock_gettime() can be used for time correction: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_nptl, [have Native POSIX Thread Library: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_usable_sigusrx, [SIGUSR1 and SIGUSR2 can be used: yes|no (only used when cross compiling)]) @@ -606,6 +607,103 @@ ifelse([$5], , , [$5 fi ]) +dnl ---------------------------------------------------------------------- +dnl +dnl AC_DOUBLE_MIDDLE_ENDIAN +dnl +dnl Checks whether doubles are represented in "middle-endian" format. +dnl Sets ac_cv_double_middle_endian={no,yes,unknown} accordingly, +dnl as well as DOUBLE_MIDDLE_ENDIAN. +dnl +dnl + +AC_DEFUN([AC_C_DOUBLE_MIDDLE_ENDIAN], +[AC_CACHE_CHECK(whether double word ordering is middle-endian, ac_cv_c_double_middle_endian, +[# It does not; compile a test program. +AC_RUN_IFELSE( +[AC_LANG_SOURCE([[#include <stdlib.h> + +int +main(void) +{ + int i = 0; + int zero = 0; + int bigendian; + int zero_index = 0; + + union + { + long int l; + char c[sizeof (long int)]; + } u; + + /* we'll use the one with 32-bit words */ + union + { + double d; + unsigned int c[2]; + } vint; + + union + { + double d; + unsigned long c[2]; + } vlong; + + union + { + double d; + unsigned short c[2]; + } vshort; + + + /* Are we little or big endian? From Harbison&Steele. */ + u.l = 1; + bigendian = (u.c[sizeof (long int) - 1] == 1); + + zero_index = bigendian ? 1 : 0; + + vint.d = 1.0; + vlong.d = 1.0; + vshort.d = 1.0; + + if (sizeof(unsigned int) == 4) + { + if (vint.c[zero_index] != 0) + zero = 1; + } + else if (sizeof(unsigned long) == 4) + { + if (vlong.c[zero_index] != 0) + zero = 1; + } + else if (sizeof(unsigned short) == 4) + { + if (vshort.c[zero_index] != 0) + zero = 1; + } + + exit (zero); +} +]])], + [ac_cv_c_double_middle_endian=no], + [ac_cv_c_double_middle_endian=yes], + [ac_cv_c_double_middle=unknown])]) +case $ac_cv_c_double_middle_endian in + yes) + m4_default([$1], + [AC_DEFINE([DOUBLE_MIDDLE_ENDIAN], 1, + [Define to 1 if your processor stores the words in a double in + middle-endian format (like some ARMs).])]) ;; + no) + $2 ;; + *) + m4_default([$3], + [AC_MSG_WARN([unknown double endianness +presetting ac_cv_c_double_middle_endian=no (or yes) will help])]) ;; +esac +])# AC_C_DOUBLE_MIDDLE_ENDIAN + dnl ---------------------------------------------------------------------- dnl @@ -1337,6 +1435,14 @@ if test "$ac_cv_c_bigendian" = "yes"; then AC_DEFINE(ETHR_BIGENDIAN, 1, [Define if bigendian]) fi +case X$erl_xcomp_double_middle_endian in + X) ;; + Xyes|Xno|Xunknown) ac_cv_c_double_middle_endian=$erl_xcomp_double_middle_endian;; + *) AC_MSG_ERROR([Bad erl_xcomp_double_middle_endian value: $erl_xcomp_double_middle_endian]);; +esac + +AC_C_DOUBLE_MIDDLE_ENDIAN + AC_ARG_ENABLE(native-ethr-impls, AS_HELP_STRING([--disable-native-ethr-impls], [disable native ethread implementations]), diff --git a/erts/aclocal.m4 b/erts/aclocal.m4 index 339a15a2bb..a76594d86f 100644 --- a/erts/aclocal.m4 +++ b/erts/aclocal.m4 @@ -59,6 +59,7 @@ AC_ARG_VAR(erl_xcomp_isysroot, [Absolute cross system root include path (only us dnl Cross compilation variables AC_ARG_VAR(erl_xcomp_bigendian, [big endian system: yes|no (only used when cross compiling)]) +AC_ARG_VAR(erl_xcomp_double_middle_endian, [double-middle-endian system: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_clock_gettime_correction, [clock_gettime() can be used for time correction: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_nptl, [have Native POSIX Thread Library: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_usable_sigusrx, [SIGUSR1 and SIGUSR2 can be used: yes|no (only used when cross compiling)]) @@ -606,6 +607,103 @@ ifelse([$5], , , [$5 fi ]) +dnl ---------------------------------------------------------------------- +dnl +dnl AC_DOUBLE_MIDDLE_ENDIAN +dnl +dnl Checks whether doubles are represented in "middle-endian" format. +dnl Sets ac_cv_double_middle_endian={no,yes,unknown} accordingly, +dnl as well as DOUBLE_MIDDLE_ENDIAN. +dnl +dnl + +AC_DEFUN([AC_C_DOUBLE_MIDDLE_ENDIAN], +[AC_CACHE_CHECK(whether double word ordering is middle-endian, ac_cv_c_double_middle_endian, +[# It does not; compile a test program. +AC_RUN_IFELSE( +[AC_LANG_SOURCE([[#include <stdlib.h> + +int +main(void) +{ + int i = 0; + int zero = 0; + int bigendian; + int zero_index = 0; + + union + { + long int l; + char c[sizeof (long int)]; + } u; + + /* we'll use the one with 32-bit words */ + union + { + double d; + unsigned int c[2]; + } vint; + + union + { + double d; + unsigned long c[2]; + } vlong; + + union + { + double d; + unsigned short c[2]; + } vshort; + + + /* Are we little or big endian? From Harbison&Steele. */ + u.l = 1; + bigendian = (u.c[sizeof (long int) - 1] == 1); + + zero_index = bigendian ? 1 : 0; + + vint.d = 1.0; + vlong.d = 1.0; + vshort.d = 1.0; + + if (sizeof(unsigned int) == 4) + { + if (vint.c[zero_index] != 0) + zero = 1; + } + else if (sizeof(unsigned long) == 4) + { + if (vlong.c[zero_index] != 0) + zero = 1; + } + else if (sizeof(unsigned short) == 4) + { + if (vshort.c[zero_index] != 0) + zero = 1; + } + + exit (zero); +} +]])], + [ac_cv_c_double_middle_endian=no], + [ac_cv_c_double_middle_endian=yes], + [ac_cv_c_double_middle=unknown])]) +case $ac_cv_c_double_middle_endian in + yes) + m4_default([$1], + [AC_DEFINE([DOUBLE_MIDDLE_ENDIAN], 1, + [Define to 1 if your processor stores the words in a double in + middle-endian format (like some ARMs).])]) ;; + no) + $2 ;; + *) + m4_default([$3], + [AC_MSG_WARN([unknown double endianness +presetting ac_cv_c_double_middle_endian=no (or yes) will help])]) ;; +esac +])# AC_C_DOUBLE_MIDDLE_ENDIAN + dnl ---------------------------------------------------------------------- dnl @@ -1337,6 +1435,14 @@ if test "$ac_cv_c_bigendian" = "yes"; then AC_DEFINE(ETHR_BIGENDIAN, 1, [Define if bigendian]) fi +case X$erl_xcomp_double_middle_endian in + X) ;; + Xyes|Xno|Xunknown) ac_cv_c_double_middle_endian=$erl_xcomp_double_middle_endian;; + *) AC_MSG_ERROR([Bad erl_xcomp_double_middle_endian value: $erl_xcomp_double_middle_endian]);; +esac + +AC_C_DOUBLE_MIDDLE_ENDIAN + AC_ARG_ENABLE(native-ethr-impls, AS_HELP_STRING([--disable-native-ethr-impls], [disable native ethread implementations]), diff --git a/erts/configure.in b/erts/configure.in index b3289bf84c..281f61f86e 100644 --- a/erts/configure.in +++ b/erts/configure.in @@ -1730,6 +1730,7 @@ case X$erl_xcomp_bigendian in esac AC_C_BIGENDIAN +AC_C_DOUBLE_MIDDLE_ENDIAN dnl fdatasync syscall (Unix only) AC_CHECK_FUNCS([fdatasync]) @@ -1943,6 +1944,64 @@ AC_CHECK_FUNCS([openpty]) AC_CHECK_HEADERS(net/if_dl.h ifaddrs.h netpacket/packet.h) AC_CHECK_FUNCS([getifaddrs]) +dnl Checks for variables in6addr_any and in6addr_loopback, +dnl +dnl They normally declared by netinet/in.h, according to POSIX, +dnl but not on Windows 7 (Windows SDK 7.1). I would have liked +dnl to just write AC_CHECK_DECL([in6addr_any], ...) but if doing so, +dnl the configure check fails erroneously on Linux with the error +dnl "cannot convert to a pointer type", on a line looking like +dnl "char *p = (char *) in6addr_any;", so work around that +dnl with some more code. +AC_CACHE_CHECK( + [whether in6addr_any is declared], + [erts_cv_have_in6addr_any], + [AC_LINK_IFELSE( + [AC_LANG_PROGRAM( + [[ + #include <sys/types.h> + #include <sys/socket.h> + #include <netinet/in.h> + ]], + [[printf("%d", in6addr_any.s6_addr[16]);]] + )], + [erts_cv_have_in6addr_any=yes], + [erts_cv_have_in6addr_any=no] + )] +) + +case "$erts_cv_have_in6addr_any" in + yes) + AC_DEFINE([HAVE_IN6ADDR_ANY], [1], + [Define to 1 if you have the variable in6addr_any declared.]) +esac + +AC_CACHE_CHECK( + [whether in6addr_loopback is declared], + [erts_cv_have_in6addr_loopback], + [AC_LINK_IFELSE( + [AC_LANG_PROGRAM( + [[ + #include <sys/types.h> + #include <sys/socket.h> + #include <netinet/in.h> + ]], + [[printf("%d", in6addr_loopback.s6_addr[16]);]] + )], + [erts_cv_have_in6addr_loopback=yes], + [erts_cv_have_in6addr_loopback=no] + )] +) + +case "$erts_cv_have_in6addr_loopback" in + yes) + AC_DEFINE([HAVE_IN6ADDR_LOOPBACK], [1], + [Define to 1 if you have the variable in6addr_loopback declared.]) +esac + +AC_CHECK_DECLS([IN6ADDR_ANY_INIT, IN6ADDR_LOOPBACK_INIT], [], [], + [#include <netinet/in.h>]) + dnl ---------------------------------------------------------------------- dnl Checks for features/quirks in the system that affects Erlang. dnl ---------------------------------------------------------------------- diff --git a/erts/emulator/beam/erl_bits.c b/erts/emulator/beam/erl_bits.c index 6f7309f493..b7c82935ff 100644 --- a/erts/emulator/beam/erl_bits.c +++ b/erts/emulator/beam/erl_bits.c @@ -1005,8 +1005,13 @@ erts_new_bs_put_float(Process *c_p, Eterm arg, Uint num_bits, int flags) if (is_float(arg)) { FloatDef *fdp = (FloatDef*)(float_val(arg) + 1); +#ifdef DOUBLE_MIDDLE_ENDIAN + a = fdp->fw[1]; + b = fdp->fw[0]; +#else a = fdp->fw[0]; b = fdp->fw[1]; +#endif } else if (is_small(arg)) { u.f64 = (double) signed_val(arg); a = u.i32[0]; @@ -1015,8 +1020,13 @@ erts_new_bs_put_float(Process *c_p, Eterm arg, Uint num_bits, int flags) if (big_to_double(arg, &u.f64) < 0) { return 0; } +#ifdef DOUBLE_MIDDLE_ENDIAN + a = u.i32[1]; + b = u.i32[0]; +#else a = u.i32[0]; b = u.i32[1]; +#endif } else { return 0; } diff --git a/erts/emulator/drivers/common/inet_drv.c b/erts/emulator/drivers/common/inet_drv.c index 76a9b55179..8f4fff0f40 100644 --- a/erts/emulator/drivers/common/inet_drv.c +++ b/erts/emulator/drivers/common/inet_drv.c @@ -1228,6 +1228,27 @@ struct erl_drv_entry inet_driver_entry = NULL, }; +#if HAVE_IN6 +# if ! defined(HAVE_IN6ADDR_ANY) || ! HAVE_IN6ADDR_ANY +# if HAVE_DECL_IN6ADDR_ANY_INIT +static const struct in6_addr in6addr_any = { { IN6ADDR_ANY_INIT } }; +# else +static const struct in6_addr in6addr_any = + { { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } } }; +# endif /* HAVE_IN6ADDR_ANY_INIT */ +# endif /* ! HAVE_DECL_IN6ADDR_ANY */ + +# if ! defined(HAVE_IN6ADDR_LOOPBACK) || ! HAVE_IN6ADDR_LOOPBACK +# if HAVE_DECL_IN6ADDR_LOOPBACK_INIT +static const struct in6_addr in6addr_loopback = + { { IN6ADDR_LOOPBACK_INIT } }; +# else +static const struct in6_addr in6addr_loopback = + { { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1 } } }; +# endif /* HAVE_IN6ADDR_LOOPBACk_INIT */ +# endif /* ! HAVE_DECL_IN6ADDR_LOOPBACK */ +#endif /* HAVE_IN6 */ + /* XXX: is this a driver interface function ??? */ void erl_exit(int n, char*, ...); @@ -3706,6 +3727,9 @@ static char* inet_set_address(int family, inet_address* dst, if ((family == AF_INET) && (*len >= 2+4)) { sys_memzero((char*)dst, sizeof(struct sockaddr_in)); port = get_int16(src); +#ifndef NO_SA_LEN + dst->sai.sin_len = sizeof(struct sockaddr_in); +#endif dst->sai.sin_family = family; dst->sai.sin_port = sock_htons(port); sys_memcpy(&dst->sai.sin_addr, src+2, 4); @@ -3716,6 +3740,9 @@ static char* inet_set_address(int family, inet_address* dst, else if ((family == AF_INET6) && (*len >= 2+16)) { sys_memzero((char*)dst, sizeof(struct sockaddr_in6)); port = get_int16(src); +#ifndef NO_SA_LEN + dst->sai6.sin6_len = sizeof(struct sockaddr_in6); +#endif dst->sai6.sin6_family = family; dst->sai6.sin6_port = sock_htons(port); dst->sai6.sin6_flowinfo = 0; /* XXX this may be set as well ?? */ @@ -3726,7 +3753,7 @@ static char* inet_set_address(int family, inet_address* dst, #endif return NULL; } -#ifdef HAVE_SCTP + /* ** Set an inaddr structure, address family comes from source data, ** or from argument if source data specifies constant address. @@ -3770,6 +3797,9 @@ static char *inet_set_faddress(int family, inet_address* dst, return NULL; } sys_memzero((char*)dst, sizeof(struct sockaddr_in)); +#ifndef NO_SA_LEN + dst->sai.sin_len = sizeof(struct sockaddr_in6); +#endif dst->sai.sin_family = family; dst->sai.sin_port = sock_htons(port); dst->sai.sin_addr.s_addr = addr.s_addr; @@ -3789,6 +3819,9 @@ static char *inet_set_faddress(int family, inet_address* dst, return NULL; } sys_memzero((char*)dst, sizeof(struct sockaddr_in6)); +#ifndef NO_SA_LEN + dst->sai6.sin6_len = sizeof(struct sockaddr_in6); +#endif dst->sai6.sin6_family = family; dst->sai6.sin6_port = sock_htons(port); dst->sai6.sin6_flowinfo = 0; /* XXX this may be set as well ?? */ @@ -3806,7 +3839,7 @@ static char *inet_set_faddress(int family, inet_address* dst, } return inet_set_address(family, dst, src, len); } -#endif /* HAVE_SCTP */ + /* Get a inaddr structure ** src = inaddr structure @@ -7771,7 +7804,7 @@ static ErlDrvSSizeT inet_ctl(inet_descriptor* desc, int cmd, char* buf, if (desc->state != INET_STATE_OPEN) return ctl_xerror(EXBADPORT, rbuf, rsize); - if (inet_set_address(desc->sfamily, &local, buf, &len) == NULL) + if (inet_set_faddress(desc->sfamily, &local, buf, &len) == NULL) return ctl_error(EINVAL, rbuf, rsize); if (IS_SOCKET_ERROR(sock_bind(desc->s,(struct sockaddr*) &local, len))) @@ -10136,12 +10169,13 @@ static ErlDrvSSizeT packet_inet_ctl(ErlDrvData e, unsigned int cmd, char* buf, case SCTP_REQ_BINDX: { /* Multi-homing bind for SCTP: */ - /* Construct the list of addresses we bind to. The curr limit is - 256 addrs. Buff structure: Flags(1), ListItem,...: + /* Add additional addresses by calling sctp_bindx with one address + at a time, since this is what some OSes promise will work. + Buff structure: Flags(1), ListItem,...: */ - struct sockaddr addrs[256]; + inet_address addr; char* curr; - int add_flag, n, rflag; + int add_flag, rflag; if (!IS_SCTP(desc)) return ctl_xerror(EXBADPORT, rbuf, rsize); @@ -10150,27 +10184,22 @@ static ErlDrvSSizeT packet_inet_ctl(ErlDrvData e, unsigned int cmd, char* buf, add_flag = get_int8(curr); curr++; - for(n=0; n < 256 && curr < buf+len; n++) + /* Make the real flags: */ + rflag = add_flag ? SCTP_BINDX_ADD_ADDR : SCTP_BINDX_REM_ADDR; + + while (curr < buf+len) { - /* List item format: Port(2), IP(4|16) -- compatible with - "inet_set_address": */ - inet_address tmp; + /* List item format: see "inet_set_faddress": */ ErlDrvSizeT alen = buf + len - curr; - curr = inet_set_address(desc->sfamily, &tmp, curr, &alen); + curr = inet_set_faddress(desc->sfamily, &addr, curr, &alen); if (curr == NULL) return ctl_error(EINVAL, rbuf, rsize); - /* Now: we need to squeeze "tmp" into the size of "sockaddr", - which is smaller than "tmp" for IPv6 (extra IN6 info will - be cut off): */ - memcpy(addrs + n, &tmp, sizeof(struct sockaddr)); + /* Invoke the call: */ + if (p_sctp_bindx(desc->s, (struct sockaddr *)&addr, 1, + rflag) < 0) + return ctl_error(sock_errno(), rbuf, rsize); } - /* Make the real flags: */ - rflag = add_flag ? SCTP_BINDX_ADD_ADDR : SCTP_BINDX_REM_ADDR; - - /* Invoke the call: */ - if (p_sctp_bindx(desc->s, addrs, n, rflag) < 0) - return ctl_error(sock_errno(), rbuf, rsize); desc->state = INET_STATE_BOUND; diff --git a/erts/emulator/test/float_SUITE.erl b/erts/emulator/test/float_SUITE.erl index 8e6923ce9f..abe01bf5ec 100644 --- a/erts/emulator/test/float_SUITE.erl +++ b/erts/emulator/test/float_SUITE.erl @@ -25,7 +25,7 @@ init_per_group/2,end_per_group/2, init_per_testcase/2,end_per_testcase/2, fpe/1,fp_drv/1,fp_drv_thread/1,denormalized/1,match/1, - bad_float_unpack/1,cmp_zero/1, cmp_integer/1, cmp_bignum/1]). + bad_float_unpack/1, write/1, cmp_zero/1, cmp_integer/1, cmp_bignum/1]). -export([otp_7178/1]). -export([hidden_inf/1]). @@ -42,7 +42,7 @@ suite() -> [{ct_hooks,[ts_install_cth]}]. all() -> [fpe, fp_drv, fp_drv_thread, otp_7178, denormalized, - match, bad_float_unpack, {group, comparison} + match, bad_float_unpack, write, {group, comparison} ,hidden_inf ]. @@ -190,6 +190,11 @@ bad_float_unpack(Config) when is_list(Config) -> bad_float_unpack_match(<<F:64/float>>) -> F; bad_float_unpack_match(<<I:64/integer-signed>>) -> I. +%% Exposes endianness issues. + +write(Config) when is_list(Config) -> + "1.0" = io_lib:write(1.0). + cmp_zero(_Config) -> cmp(0.5e-323,0). diff --git a/erts/emulator/utils/make_preload b/erts/emulator/utils/make_preload index 13019d4062..4e329b24f8 100755 --- a/erts/emulator/utils/make_preload +++ b/erts/emulator/utils/make_preload @@ -87,6 +87,7 @@ foreach $file (@ARGV) { my $comment = ''; open(FILE, $file) or error("failed to read $file: $!"); + binmode(FILE); $_ = <FILE>; $_ = beam_strip($_); close(FILE); diff --git a/erts/etc/common/erlc.c b/erts/etc/common/erlc.c index 0223cc5274..9f05213c95 100644 --- a/erts/etc/common/erlc.c +++ b/erts/etc/common/erlc.c @@ -335,7 +335,7 @@ main(int argc, char** argv) /* Push the following options: * o makedep_phony */ - buf = strsave("makedep_add_missing"); + buf = strsave("makedep_phony"); PUSH2("@option", buf); break; default: diff --git a/erts/preloaded/ebin/prim_inet.beam b/erts/preloaded/ebin/prim_inet.beam Binary files differindex b2f3ab6c5b..ad49f5e892 100644 --- a/erts/preloaded/ebin/prim_inet.beam +++ b/erts/preloaded/ebin/prim_inet.beam diff --git a/erts/preloaded/src/prim_inet.erl b/erts/preloaded/src/prim_inet.erl index 846ae97ed2..91fcd3ac82 100644 --- a/erts/preloaded/src/prim_inet.erl +++ b/erts/preloaded/src/prim_inet.erl @@ -184,7 +184,7 @@ close_pend_loop(S, N) -> %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% bind(S,IP,Port) when is_port(S), is_integer(Port), Port >= 0, Port =< 65535 -> - case ctl_cmd(S,?INET_REQ_BIND,[?int16(Port),ip_to_bytes(IP)]) of + case ctl_cmd(S,?INET_REQ_BIND,enc_value(set, addr, {IP,Port})) of {ok, [P1,P0]} -> {ok, ?u16(P1, P0)}; {error,_}=Error -> Error end; @@ -206,10 +206,10 @@ bindx(S, AddFlag, Addrs) -> case getprotocol(S) of sctp -> %% Really multi-homed "bindx". Stringified args: - %% [AddFlag, (Port, IP)+]: + %% [AddFlag, (AddrBytes see enc_value_2(addr,X))+]: Args = [?int8(AddFlag)| - [[?int16(Port)|ip_to_bytes(IP)] || + [enc_value(set, addr, {IP,Port}) || {IP, Port} <- Addrs]], case ctl_cmd(S, ?SCTP_REQ_BINDX, Args) of {ok,_} -> {ok, S}; diff --git a/lib/common_test/doc/src/common_test_app.xml b/lib/common_test/doc/src/common_test_app.xml index 6babdb93af..a0fa45c71f 100644 --- a/lib/common_test/doc/src/common_test_app.xml +++ b/lib/common_test/doc/src/common_test_app.xml @@ -99,11 +99,11 @@ be executed by Common Test. A test case is represented by an atom, the name of the test case function. A test case group is represented by a <c>group</c> tuple, where <c>GroupName</c>, - an atom, is the name of the group (defined in <c>groups/0</c>). + an atom, is the name of the group (defined in <c><seealso marker="#Module:groups-0">groups/0</seealso></c>). Execution properties for groups may also be specified, both for a top level group and for any of its sub-groups. Group execution properties specified here, will override - properties in the group definition (see <c>groups/0</c>). + properties in the group definition (see <c><seealso marker="#Module:groups-0">groups/0</seealso></c>). (With value <c>default</c>, the group definition properties will be used).</p> @@ -162,7 +162,7 @@ <v> Func = atom()</v> <v> Args = list()</v> <v> Fun = fun()</v> - <v> Required = Key | {Key,SubKeys}</v> + <v> Required = Key | {Key,SubKeys} | {Key,SubKey} | {Key,SubKey,SubKeys}</v> <v> Key = atom()</v> <v> SubKeys = SubKey | [SubKey]</v> <v> SubKey = atom()</v> @@ -184,8 +184,8 @@ test cases in the suite).</p> <p>The <c>timetrap</c> tag sets the maximum time each - test case is allowed to execute (including <c>init_per_testcase/2</c> - and <c>end_per_testcase/2</c>). If the timetrap time is + test case is allowed to execute (including <c><seealso marker="#Module:init_per_testcase-2">init_per_testcase/2</seealso></c> + and <c><seealso marker="#Module:end_per_testcase-2">end_per_testcase/2</seealso></c>). If the timetrap time is exceeded, the test case fails with reason <c>timetrap_timeout</c>. A <c>TimeFunc</c> function can be used to set a new timetrap by returning a <c>TimeVal</c>. It may also be @@ -201,11 +201,11 @@ in any of the configuration files, all test cases are skipped. For more information about the 'require' functionality, see the reference manual for the function - <c>ct:require/[1,2]</c>.</p> + <c><seealso marker="ct#require-1">ct:require/1/2</seealso></c>.</p> <p>With <c>userdata</c>, it is possible for the user to specify arbitrary test suite related information which can be - read by calling <c>ct:userdata/2</c>.</p> + read by calling <c><seealso marker="ct#userdata-2">ct:userdata/2</seealso></c>.</p> <p>The <c>ct_hooks</c> tag specifies which <seealso marker="ct_hooks_chapter">Common Test Hooks</seealso> @@ -264,7 +264,7 @@ <p>This function is called as the last test case in the suite. It is meant to be used for cleaning up after - <c>init_per_suite/1</c>. + <c><seealso marker="#Module:init_per_suite-1">init_per_suite/1</seealso></c>. For information on <c>save_config</c>, please see <seealso marker="dependencies_chapter#save_config">Dependencies between Test Cases and Suites</seealso> in the User's Guide.</p> @@ -289,7 +289,7 @@ <v> Func = atom()</v> <v> Args = list()</v> <v> Fun = fun()</v> - <v> Required = Key | {Key,SubKeys}</v> + <v> Required = Key | {Key,SubKeys} | {Key,Subkey} | {Key,Subkey,SubKeys}</v> <v> Key = atom()</v> <v> SubKeys = SubKey | [SubKey]</v> <v> SubKey = atom()</v> @@ -309,13 +309,14 @@ <p>This is the test case group info function. It is supposed to return a list of tagged tuples that specify various properties related to the execution of a test case group (i.e. its test cases - and sub-groups). Properties set by <c>groups/1</c> override + and sub-groups). Properties set by + <c><seealso marker="#Module:group-1">group/1</seealso></c> override properties with the same key that have been previously set by - <c>suite/0</c>.</p> + <c><seealso marker="#Module:suite-0">suite/0</seealso></c>.</p> <p>The <c>timetrap</c> tag sets the maximum time each - test case is allowed to execute (including <c>init_per_testcase/2</c> - and <c>end_per_testcase/2</c>). If the timetrap time is + test case is allowed to execute (including <c><seealso marker="#Module:init_per_testcase-2">init_per_testcase/2</seealso></c> + and <c><seealso marker="#Module:end_per_testcase-2">end_per_testcase/2</seealso></c>). If the timetrap time is exceeded, the test case fails with reason <c>timetrap_timeout</c>. A <c>TimeFunc</c> function can be used to set a new timetrap by returning a <c>TimeVal</c>. It may also be @@ -330,11 +331,11 @@ in any of the configuration files, all test cases in this group are skipped. For more information about the 'require' functionality, see the reference manual for the function - <c>ct:require/[1,2]</c>.</p> + <c><seealso marker="ct#require-1">ct:require/1/2</seealso></c>.</p> <p>With <c>userdata</c>, it is possible for the user to specify arbitrary test case group related information which can be - read by calling <c>ct:userdata/2</c>.</p> + read by calling <c><seealso marker="ct#userdata-2">ct:userdata/2</seealso></c>.</p> <p>The <c>ct_hooks</c> tag specifies which <seealso marker="ct_hooks_chapter">Common Test Hooks</seealso> @@ -367,7 +368,7 @@ test case group. It typically contains initializations which are common for all test cases and sub-groups in the group, and which shall only be performed once. <c>GroupName</c> is the name of the - group, as specified in the group definition (see <c>groups/0</c>). The + group, as specified in the group definition (see <c><seealso marker="#Module:groups-0">groups/0</seealso></c>). The <c>Config</c> parameter is the configuration data which can be modified here. The return value of this function is given as <c>Config</c> to all test cases and sub-groups in the group. If <c>{skip,Reason}</c> @@ -396,10 +397,10 @@ <p> OPTIONAL </p> <p>This function is called after the execution of a test case group is finished. - It is meant to be used for cleaning up after <c>init_per_group/2</c>. + It is meant to be used for cleaning up after <c><seealso marker="#Module:init_per_group-2">init_per_group/2</seealso></c>. By means of <c>{return_group_result,Status}</c>, it is possible to return a status value for a nested sub-group. The status can be retrieved in - <c>end_per_group/2</c> for the group on the level above. The status will also + <c><seealso marker="#Module:end_per_group-2">end_per_group/2</seealso></c> for the group on the level above. The status will also be used by Common Test for deciding if execution of a group should proceed in case the property <c>sequence</c> or <c>repeat_until_*</c> is set.</p> @@ -450,7 +451,7 @@ <p> OPTIONAL </p> <p> This function is called after each test case, and can be used - to clean up after <c>init_per_testcase/2</c> and the test case. + to clean up after <c><seealso marker="#Module:init_per_testcase-2">init_per_testcase/2</seealso></c> and the test case. Any return value (besides <c>{fail,Reason}</c> and <c>{save_config,SaveConfig}</c>) is ignored. By returning <c>{fail,Reason}</c>, <c>TestCase</c> will be marked as failed (even though it was actually successful in the sense that it returned @@ -476,7 +477,7 @@ <v> Func = atom()</v> <v> Args = list()</v> <v> Fun = fun()</v> - <v> Required = Key | {Key,SubKeys}</v> + <v> Required = Key | {Key,SubKeys} | {Key,Subkey} | {Key,Subkey,SubKeys}</v> <v> Key = atom()</v> <v> SubKeys = SubKey | [SubKey]</v> <v> SubKey = atom()</v> @@ -492,15 +493,15 @@ <p>This is the test case info function. It is supposed to return a list of tagged tuples that specify various properties related to the execution of this particular test case. - Properties set by <c>Testcase/0</c> override + Properties set by <c><seealso marker="#Module:Testcase-0">Testcase/0</seealso></c> override properties that have been previously set for the test case - by <c>group/1</c> or <c>suite/0</c>.</p> + by <c><seealso marker="#Module:group-1">group/1</seealso></c> or <c><seealso marker="#Module:suite-0">suite/0</seealso></c>.</p> <p>The <c>timetrap</c> tag sets the maximum time the test case is allowed to execute. If the timetrap time is exceeded, the test case fails with reason - <c>timetrap_timeout</c>. <c>init_per_testcase/2</c> - and <c>end_per_testcase/2</c> are included in the + <c>timetrap_timeout</c>. <c><seealso marker="#Module:init_per_testcase-2">init_per_testcase/2</seealso></c> + and <c><seealso marker="#Module:end_per_testcase-2">end_per_testcase/2</seealso></c> are included in the timetrap time. A <c>TimeFunc</c> function can be used to set a new timetrap by returning a <c>TimeVal</c>. It may also be used to trigger a timetrap timeout by, at some point, returning a @@ -514,15 +515,15 @@ configuration files, the test case is skipped. For more information about the 'require' functionality, see the reference manual for the function - <c>ct:require/[1,2]</c>.</p> + <c><seealso marker="ct#require-1">ct:require/1/2</seealso></c>.</p> <p>If <c>timetrap</c> and/or <c>require</c> is not set, the - default values specified by <c>suite/0</c> (or - <c>group/1</c>) will be used.</p> + default values specified by <c><seealso marker="#Module:suite-0">suite/0</seealso></c> (or + <c><seealso marker="#Module:group-1">group/1</seealso></c>) will be used.</p> <p>With <c>userdata</c>, it is possible for the user to specify arbitrary test case related information which can be - read by calling <c>ct:userdata/3</c>.</p> + read by calling <c><seealso marker="ct#userdata-3">ct:userdata/3</seealso></c>.</p> <p>Other tuples than the ones defined will simply be ignored.</p> @@ -550,7 +551,7 @@ <p>This is the implementation of a test case. Here you must call the functions you want to test, and do whatever you need to check the result. If something fails, make sure the - function causes a runtime error, or call <c>ct:fail/1/2</c> + function causes a runtime error, or call <c><seealso marker="ct#fail-1">ct:fail/1/2</seealso></c> (which also causes the test case process to terminate).</p> <p>Elements from the <c>Config</c> list can e.g. be read diff --git a/lib/common_test/doc/src/config_file_chapter.xml b/lib/common_test/doc/src/config_file_chapter.xml index 6a860bb58b..e843ed3ba4 100644 --- a/lib/common_test/doc/src/config_file_chapter.xml +++ b/lib/common_test/doc/src/config_file_chapter.xml @@ -78,7 +78,7 @@ test is skipped (unless a default value has been specified, see the <seealso marker="write_test_chapter#info_function">test case info function</seealso> chapter for details). There is also a function - <c>ct:require/[1,2]</c> which can be called from a test case + <c><seealso marker="ct#require-1">ct:require/1/2</seealso></c> which can be called from a test case in order to check if a specific variable is available. The return value from this function must be checked explicitly and appropriate action be taken depending on the result (e.g. to skip the test case @@ -88,7 +88,7 @@ info-list should look like this: <c>{require,CfgVarName}</c> or <c>{require,AliasName,CfgVarName}</c>. The arguments <c>AliasName</c> and <c>CfgVarName</c> are the same as the - arguments to <c>ct:require/[1,2]</c> which are described in the + arguments to <c><seealso marker="ct#require-1">ct:require/1/2</seealso></c> which are described in the reference manual for <seealso marker="ct">ct</seealso>. <c>AliasName</c> becomes an alias for the configuration variable, and can be used as reference to the configuration data value. @@ -101,7 +101,8 @@ (or test case) and improve readability.</item> </list> <p>To read the value of a config variable, use the function - <c>get_config/[1,2,3]</c> which is also described in the reference + <c><seealso marker="ct#get_config-1">get_config/1/2/3</seealso></c> + which is also described in the reference manual for <seealso marker="ct">ct</seealso>.</p> <p>Example:</p> <pre> @@ -118,7 +119,7 @@ <section> <title>Using configuration variables defined in multiple files</title> <p>If a configuration variable is defined in multiple files and you - want to access all possible values, you may use the <c>ct:get_config/3</c> + want to access all possible values, you may use the <c><seealso marker="ct#get_config-3">ct:get_config/3</seealso></c> function and specify <c>all</c> in the options list. The values will then be returned in a list and the order of the elements corresponds to the order that the config files were specified at startup. Please see @@ -130,7 +131,7 @@ <marker id="encrypted_config_files"></marker> <p>It is possible to encrypt configuration files containing sensitive data if these files must be stored in open and shared directories.</p> - <p>Call <c>ct:encrypt_config_file/[2,3]</c> to have Common Test encrypt a + <p>Call <c><seealso marker="ct#encrypt_config_file-2">ct:encrypt_config_file/2/3</seealso></c> to have Common Test encrypt a specified file using the DES3 function in the OTP <c>crypto</c> application. The encrypted file can then be used as a regular configuration file, in combination with other encrypted files or normal text files. The key @@ -139,7 +140,7 @@ <c>decrypt_file</c> flag/option, or a key file in a predefined location.</p> <p>Common Test also provides decryption functions, - <c>ct:decrypt_config_file/[2,3]</c>, for recreating the original text + <c><seealso marker="ct#decrypt_config_file-2">ct:decrypt_config_file/2/3</seealso></c>, for recreating the original text files.</p> <p>Please see the <seealso marker="ct">ct</seealso> reference manual for @@ -149,8 +150,8 @@ <section> <title>Opening connections by using configuration data</title> <p>There are two different methods for opening a connection - by means of the support functions in e.g. <c>ct_ssh</c>, <c>ct_ftp</c>, - and <c>ct_telnet</c>:</p> + by means of the support functions in e.g. <c><seealso marker="ct_ssh">ct_ssh</seealso></c>, <c><seealso marker="ct_ftp">ct_ftp</seealso></c>, + and <c><seealso marker="ct_telnet">ct_telnet</seealso></c>:</p> <list> <item>Using a configuration target name (an alias) as reference.</item> <item>Using the configuration variable as reference.</item> @@ -295,7 +296,7 @@ <pre> [{ftp_host, [{ftp, "targethost"}, {username, "tester"}, {password, "letmein"}]}, - {lm_directory, "/test/loadmodules"}]</pre> + {lm_directory, "/test/loadmodules"}]</pre> </section> diff --git a/lib/common_test/doc/src/cover_chapter.xml b/lib/common_test/doc/src/cover_chapter.xml index b7162cb542..fc609ee137 100644 --- a/lib/common_test/doc/src/cover_chapter.xml +++ b/lib/common_test/doc/src/cover_chapter.xml @@ -100,7 +100,7 @@ <p><c>$ ct_run -dir $TESTOBJS/db -cover $TESTOBJS/db/config/db.coverspec</c></p> <p>You may also pass the cover specification file name in a - call to <c>ct:run_test/1</c>, by adding a <c>{cover,CoverSpec}</c> + call to <c><seealso marker="ct#run_test-1">ct:run_test/1</seealso></c>, by adding a <c>{cover,CoverSpec}</c> tuple to the <c>Opts</c> argument. Also, you can of course enable code coverage in your test specifications (read more in the chapter about diff --git a/lib/common_test/doc/src/ct_hooks_chapter.xml b/lib/common_test/doc/src/ct_hooks_chapter.xml index 014507c886..c938851e0e 100644 --- a/lib/common_test/doc/src/ct_hooks_chapter.xml +++ b/lib/common_test/doc/src/ct_hooks_chapter.xml @@ -192,12 +192,12 @@ <section> <title>External configuration data and Logging</title> <p>It's possible in the CTH to read configuration data values - by calling <c>ct:get_config/1/2/3</c> (as explained in the + by calling <c><seealso marker="ct#get_config-1">ct:get_config/1/2/3</seealso></c> (as explained in the <seealso marker="config_file_chapter#require_config_data"> External configuration data</seealso> chapter). The config variables in question must, as always, first have been <c>required</c> by means of a suite-, group-, or test case info function, - or the <c>ct:require/1/2</c> function. Note that the latter can also be used + or the <c><seealso marker="ct#require-1">ct:require/1/2</seealso></c> function. Note that the latter can also be used in CT hook functions.</p> <p>The CT hook functions may call any of the logging functions available in the <c>ct</c> interface to print information to the log files, or to diff --git a/lib/common_test/doc/src/ct_run.xml b/lib/common_test/doc/src/ct_run.xml index df1defa664..8061c840b0 100644 --- a/lib/common_test/doc/src/ct_run.xml +++ b/lib/common_test/doc/src/ct_run.xml @@ -46,7 +46,7 @@ particular mode.</p> <p>There is an interface function that corresponds to this program, - called <c>ct:run_test/1</c>, for starting Common Test from the Erlang + called <c><seealso marker="ct#run_test-1">ct:run_test/1</seealso></c>, for starting Common Test from the Erlang shell (or an Erlang program). Please see the <c>ct</c> man page for details.</p> diff --git a/lib/common_test/doc/src/event_handler_chapter.xml b/lib/common_test/doc/src/event_handler_chapter.xml index a5886b9687..b95a18e47e 100644 --- a/lib/common_test/doc/src/event_handler_chapter.xml +++ b/lib/common_test/doc/src/event_handler_chapter.xml @@ -64,7 +64,7 @@ <marker id="usage"></marker> <title>Usage</title> <p>Event handlers may be installed by means of an <c>event_handler</c> - start flag (<c>ct_run</c>) or option (<c>ct:run_test/1</c>), where the + start flag (<c>ct_run</c>) or option (<c><seealso marker="ct#run_test-1">ct:run_test/1</seealso></c>), where the argument specifies the names of one or more event handler modules. Example:</p> <p><c>$ ct_run -suite test/my_SUITE -event_handler handlers/my_evh1 @@ -78,7 +78,7 @@ example).</p> <p>An event_handler tuple in the argument <c>Opts</c> has the following - definition (see also <c>ct:run_test/1</c> in the reference manual):</p> + definition (see also <c><seealso marker="ct#run_test-1">ct:run_test/1</seealso></c> in the reference manual):</p> <pre> {event_handler,EventHandlers} @@ -205,7 +205,7 @@ {error,{RunTimeError,StackTrace}} | {timetrap_timeout,integer()} | {failed,{Suite,end_per_testcase,FailInfo}}</c>, reason for failure.</p> - <p><c>RequireInfo = {not_available,atom()}</c>, why require has failed.</p> + <p><c>RequireInfo = {not_available,atom() | tuple()}</c>, why require has failed.</p> <p><c>FailInfo = {timetrap_timeout,integer()} | {RunTimeError,StackTrace} | UserTerm</c>, @@ -233,7 +233,7 @@ reason for auto skipping <c>Func</c>.</p> <p><c>FailReason = {Suite,ConfigFunc,FailInfo}} | {Suite,FailedCaseInSequence}</c>, reason for failure.</p> - <p><c>RequireInfo = {not_available,atom()}</c>, why require has failed.</p> + <p><c>RequireInfo = {not_available,atom() | tuple()}</c>, why require has failed.</p> <p><c>ConfigFunc = init_per_suite | init_per_group</c></p> <p><c>FailInfo = {timetrap_timeout,integer()} | {RunTimeError,StackTrace} | @@ -308,7 +308,7 @@ manager can look like.</p> <note><p>To ensure that printouts to standard out (or printouts made with - <c>ct:log/2/3</c> or <c>ct:pal/2/3</c>) get written to the test case log + <c><seealso marker="ct#log-2">ct:log/2/3</seealso></c> or <c><seealso marker="ct:pal-2">ct:pal/2/3</seealso></c>) get written to the test case log file, and not to the Common Test framework log, you can syncronize with the Common Test server by matching on the <c>tc_start</c> and <c>tc_done</c> events. In the period between these events, all IO gets directed to the diff --git a/lib/common_test/doc/src/getting_started_chapter.xml b/lib/common_test/doc/src/getting_started_chapter.xml index 039578dd2e..891cbc49f3 100644 --- a/lib/common_test/doc/src/getting_started_chapter.xml +++ b/lib/common_test/doc/src/getting_started_chapter.xml @@ -90,7 +90,7 @@ <p>As you can understand from the illustration above, Common Test requires that a test case generates a runtime error to indicate failure (e.g. by causing a bad match error or by calling <c>exit/1</c>, preferrably - through the <c>ct:fail/1,2</c> help function). A succesful execution is + through the <c><seealso marker="ct#fail-1">ct:fail/1,2</seealso></c> help function). A succesful execution is indicated by means of a normal return from the test case function. </p> </section> diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml index bc0af63790..058b27d622 100644 --- a/lib/common_test/doc/src/run_test_chapter.xml +++ b/lib/common_test/doc/src/run_test_chapter.xml @@ -242,12 +242,12 @@ <p>Common Test provides an Erlang API for running tests. The main (and most flexible) function for specifying and executing tests is called - <c>ct:run_test/1</c>. This function takes the same start parameters as + <c><seealso marker="ct#run_test-1">ct:run_test/1</seealso></c>. This function takes the same start parameters as the <c>ct_run</c> program described above, only the flags are instead given as options in a list of key-value tuples. E.g. a test specified with <c>ct_run</c> like:</p> <p><c>$ ct_run -suite ./my_SUITE -logdir ./results</c></p> - <p>is with <c>ct:run_test/1</c> specified as:</p> + <p>is with <c><seealso marker="ct#run_test-1">ct:run_test/1</seealso></c> specified as:</p> <p><c>1> ct:run_test([{suite,"./my_SUITE"},{logdir,"./results"}]).</c></p> <p>For detailed documentation, please see the <c>ct</c> manual page.</p> </section> @@ -266,9 +266,9 @@ for trying out various operations during test suite development.</p> <p>To invoke the interactive shell mode, you can start an Erlang shell - manually and call <c>ct:install/1</c> to install any configuration + manually and call <c><seealso marker="ct#install-1">ct:install/1</seealso></c> to install any configuration data you might need (use <c>[]</c> as argument otherwise), then - call <c>ct:start_interactive/0</c> to start Common Test. If you use + call <c><seealso marker="ct#start_interactive-0">ct:start_interactive/0</seealso></c> to start Common Test. If you use the <c>ct_run</c> program, you may start the Erlang shell and Common Test in the same go by using the <c>-shell</c> and, optionally, the <c>-config</c> and/or <c>-userconfig</c> flag. Examples: @@ -287,7 +287,8 @@ <p>If any functions using "required config data" (e.g. ct_telnet or ct_ftp functions) are to be called from the erlang shell, config - data must first be required with <c>ct:require/[1,2]</c>. This is + data must first be required with <c><seealso marker="ct#require-1"> + ct:require/1/2</seealso></c>. This is equivalent to a <c>require</c> statement in the <seealso marker="write_test_chapter#suite">Test Suite Info Function</seealso> or in the <seealso @@ -314,11 +315,11 @@ is not supported.</p> <p>If you wish to exit the interactive mode (e.g. to start an - automated test run with <c>ct:run_test/1</c>), call the function - <c>ct:stop_interactive/0</c>. This shuts down the + automated test run with <c><seealso marker="ct#run_test-1">ct:run_test/1</seealso></c>), call the function + <c><seealso marker="ct#stop_interactive-0">ct:stop_interactive/0</seealso></c>. This shuts down the running <c>ct</c> application. Associations between configuration names and data created with <c>require</c> are - consequently deleted. <c>ct:start_interactive/0</c> will get you + consequently deleted. <c><seealso marker="ct#start_interactive-0">ct:start_interactive/0</seealso></c> will get you back into interactive mode, but the previous state is not restored.</p> </section> @@ -326,7 +327,7 @@ <title>Step by step execution of test cases with the Erlang Debugger</title> <p>By means of <c>ct_run -step [opts]</c>, or by passing the - <c>{step,Opts}</c> option to <c>ct:run_test/1</c>, it is possible + <c>{step,Opts}</c> option to <c><seealso marker="ct#run_test-1">ct:run_test/1</seealso></c>, it is possible to get the Erlang Debugger started automatically and use its graphical interface to investigate the state of the current test case and to execute it step by step and/or set execution breakpoints.</p> @@ -586,7 +587,7 @@ <c>ct_run</c>. This forces Common Test to ignore unrecognizable terms. Note that in this mode, Common Test is not able to check the specification for errors as efficiently as if the scanner runs in default mode. - If <c>ct:run_test/1</c> is used for starting the tests, the relaxed scanner + If <c><seealso marker="ct#run_test-1">ct:run_test/1</seealso></c> is used for starting the tests, the relaxed scanner mode is enabled by means of the tuple: <c>{allow_user_terms,true}</c></p> </section> @@ -943,7 +944,7 @@ <p>The <c>-silent_connections</c> tag (or <c>silent_connections</c> tagged tuple in the call to - <c>ct:run_test/1</c>) overrides any settings in the test + <c><seealso marker="ct#run_test-1">ct:run_test/1</seealso></c>) overrides any settings in the test suite.</p> <p>Note that in the current Common Test version, the diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml index 7b7e7af8ea..1fae50577e 100644 --- a/lib/common_test/doc/src/write_test_chapter.xml +++ b/lib/common_test/doc/src/write_test_chapter.xml @@ -173,7 +173,7 @@ </p> <p>The <c>end_per_testcase/2</c> function is called even after a - test case terminates due to a call to <c>ct:abort_current_testcase/1</c>, + test case terminates due to a call to <c><seealso marker="ct#abort_current_testcase-1">ct:abort_current_testcase/1</seealso></c>, or after a timetrap timeout. However, <c>end_per_testcase</c> will then execute on a different process than the test case function, and in this situation, <c>end_per_testcase</c> will @@ -243,7 +243,8 @@ <note><p>The test case function argument <c>Config</c> should not be confused with the information that can be retrieved from - configuration files (using ct:get_config/[1,2]). The Config argument + configuration files (using <c><seealso marker="ct#get_config-1"> + ct:get_config/1/2</seealso></c>). The Config argument should be used for runtime configuration of the test suite and the test cases, while configuration files should typically contain data related to the SUT. These two types of configuration data are handled @@ -302,7 +303,7 @@ <item> <p> Use this to specify arbitrary data related to the testcase. This - data can be retrieved at any time using the <c>ct:userdata/3</c> + data can be retrieved at any time using the <c><seealso marker="ct#userdata-3">ct:userdata/3</seealso></c> utility function. </p> </item> @@ -338,7 +339,8 @@ <pre> testcase2() -> - [{require, unix_telnet, {unix, [telnet, username, password]}}, + [{require, unix_telnet, unix}, + {require, {unix, [telnet, username, password]}}, {default_config, unix, [{telnet, "my_telnet_host"}, {username, "aladdin"}, {password, "sesame"}]}}].</pre> @@ -346,7 +348,8 @@ </taglist> <p>See the <seealso marker="config_file_chapter#require_config_data">Config files</seealso> - chapter and the <c>ct:require/[1,2]</c> function in the + chapter and the <c><seealso marker="ct#require-1"> + ct:require/1/2</seealso></c> function in the <seealso marker="ct">ct</seealso> reference manual for more information about <c>require</c>.</p> @@ -823,7 +826,7 @@ Common Test to create one dedicated private directory per test case and execution instead. This is accomplished by means of the flag/option: <c>create_priv_dir</c> (to be used with the - <c>ct_run</c> program, the <c>ct:run_test/1</c> function, or + <c>ct_run</c> program, the <c><seealso marker="ct#run_test-1">ct:run_test/1</seealso></c> function, or as test specification term). There are three possible values for this option: <list> @@ -839,7 +842,7 @@ become very inefficient for test runs with many test cases and/or repetitions. Therefore, in case the manual version is instead used, the test case must tell Common Test to create priv_dir when it needs it. - It does this by calling the function <c>ct:make_priv_dir/0</c>. + It does this by calling the function <c><seealso marker="ct#make_priv_dir-0">ct:make_priv_dir/0</seealso></c>. </p> <note><p>You should not depend on current working directory for @@ -887,7 +890,7 @@ <p>It is also possible to dynamically set/reset a timetrap during the excution of a test case, or configuration function. This is done by calling - <c>ct:timetrap/1</c>. This function cancels the current timetrap + <c><seealso marker="ct#timetrap-1">ct:timetrap/1</seealso></c>. This function cancels the current timetrap and starts a new one (that stays active until timeout, or end of the current function).</p> @@ -900,12 +903,12 @@ <p>If a test case needs to suspend itself for a time that also gets multipled by <c>multiply_timetraps</c> (and possibly also scaled up if - <c>scale_timetraps</c> is enabled), the function <c>ct:sleep/1</c> + <c>scale_timetraps</c> is enabled), the function <c><seealso marker="ct#sleep-1">ct:sleep/1</seealso></c> may be used (instead of e.g. <c>timer:sleep/1</c>).</p> <p>A function (<c>fun/0</c> or <c>MFA</c>) may be specified as timetrap value in the suite-, group- and test case info function, as - well as argument to the <c>ct:timetrap/1</c> function. Examples:</p> + well as argument to the <c><seealso marker="ct#timetrap-1">ct:timetrap/1</seealso></c> function. Examples:</p> <p><c>{timetrap,{my_test_utils,timetrap,[?MODULE,system_start]}}</c></p> <p><c>ct:timetrap(fun() -> my_timetrap(TestCaseName, Config) end)</c></p> diff --git a/lib/common_test/src/ct.erl b/lib/common_test/src/ct.erl index 8d4721ab63..e369c9f4ef 100644 --- a/lib/common_test/src/ct.erl +++ b/lib/common_test/src/ct.erl @@ -274,27 +274,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 <c>Required</c>. Note that it is +%%% only the last element of the tuple which can be a list of <c>SubKey</c>s. %%% -%%% <p>Example: require the variable <code>myvar</code>:<br/> -%%% <code>ok = ct:require(myvar)</code></p> +%%% <p>Example 1: require the variable <code>myvar</code>:</p> +%%% <pre>ok = ct:require(myvar).</pre> %%% %%% <p>In this case the config file must at least contain:</p> -%%% <pre> -%%% {myvar,Value}.</pre> +%%% <pre>{myvar,Value}.</pre> %%% -%%% <p>Example: require the variable <code>myvar</code> with -%%% subvariable <code>sub1</code>:<br/> -%%% <code>ok = ct:require({myvar,sub1})</code></p> +%%% <p>Example 2: require the key <code>myvar</code> with +%%% subkeys <code>sub1</code> and <code>sub2</code>:</p> +%%% <pre>ok = ct:require({myvar,[sub1,sub2]}).</pre> %%% %%% <p>In this case the config file must at least contain:</p> -%%% <pre> -%%% {myvar,[{sub1,Value}]}.</pre> +%%% <pre>{myvar,[{sub1,Value},{sub2,Value}]}.</pre> +%%% +%%% <p>Example 3: require the key <code>myvar</code> with +%%% subkey <code>sub1</code> with <code>subsub1</code>:</p> +%%% <pre>ok = ct:require({myvar,sub1,sub2}).</pre> +%%% +%%% <p>In this case the config file must at least contain:</p> +%%% <pre>{myvar,[{sub1,[{sub2,Value}]}]}.</pre> %%% %%% @see require/2 %%% @see get_config/1 @@ -306,30 +313,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 <c>Required</c> is the same as in +%%% <c>required/1</c> except that it is not possible to specify a list +%%% of <c>SubKey</c>s. %%% -%%% <p>If the requested data is available, the main entry will be +%%% <p>If the requested data is available, the sub entry will be %%% associated with <code>Name</code> so that the value of the element %%% can be read with <code>get_config/1,2</code> provided -%%% <code>Name</code> instead of the <code>Key</code>.</p> +%%% <code>Name</code> instead of the whole <code>Required</code> term.</p> %%% %%% <p>Example: Require one node with a telnet connection and an -%%% ftp connection. Name the node <code>a</code>:<br/> <code>ok = -%%% ct:require(a,{node,[telnet,ftp]}).</code><br/> All references -%%% to this node may then use the node name. E.g. you can fetch a -%%% file over ftp like this:<br/> -%%% <code>ok = ct:ftp_get(a,RemoteFile,LocalFile).</code></p> +%%% ftp connection. Name the node <code>a</code>: +%%% <pre>ok = ct:require(a,{machine,node}).</pre> +%%% All references to this node may then use the node name. +%%% E.g. you can fetch a file over ftp like this:</p> +%%% <pre>ok = ct:ftp_get(a,RemoteFile,LocalFile).</pre> %%% %%% <p>For this to work, the config file must at least contain:</p> -%%% <pre> -%%% {node,[{telnet,IpAddr}, -%%% {ftp,IpAddr}]}.</pre> +%%% <pre>{machine,[{node,[{telnet,IpAddr},{ftp,IpAddr}]}]}.</pre> +%%% +%%% <note>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: <br/><c>ct:require(a,{node,[telnet,ftp]}).</c><br/> +%%% This will associate the name <c>a</c> with the top level <c>node</c> entry. +%%% For this to work, the config file must at least contain:<br/> +%%% <c>{node,[{telnet,IpAddr},{ftp,IpAddr}]}.</c></note> %%% %%% @see require/1 %%% @see get_config/1 @@ -352,7 +365,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() @@ -370,25 +383,25 @@ get_config(Required,Default) -> %%% <p>Example, given the following config file:</p> %%% <pre> %%% {unix,[{telnet,IpAddr}, -%%% {username,Username}, -%%% {password,Password}]}.</pre> -%%% <p><code>get_config(unix,Default) -> +%%% {user,[{username,Username}, +%%% {password,Password}]}]}.</pre> +%%% <p><code>ct:get_config(unix,Default) -> %%% [{telnet,IpAddr}, -%%% {username,Username}, -%%% {password,Password}]</code><br/> -%%% <code>get_config({unix,telnet},Default) -> IpAddr</code><br/> -%%% <code>get_config({unix,ftp},Default) -> Default</code><br/> -%%% <code>get_config(unknownkey,Default) -> Default</code></p> +%%% {user, [{username,Username}, +%%% {password,Password}]}]</code><br/> +%%% <code>ct:get_config({unix,telnet},Default) -> IpAddr</code><br/> +%%% <code>ct:get_config({unix,user,username},Default) -> Username</code><br/> +%%% <code>ct:get_config({unix,ftp},Default) -> Default</code><br/> +%%% <code>ct:get_config(unknownkey,Default) -> Default</code></p> %%% %%% <p>If a config variable key has been associated with a name (by %%% means of <code>require/2</code> or a require statement), the name %%% may be used instead of the key to read the value:</p> %%% -%%% <p><code>require(myhost,unix) -> ok</code><br/> -%%% <code>get_config(myhost,Default) -> -%%% [{telnet,IpAddr}, -%%% {username,Username}, -%%% {password,Password}]</code></p> +%%% <p><code>ct:require(myuser,{unix,user}) -> ok.</code><br/> +%%% <code>ct:get_config(myuser,Default) -> +%%% [{username,Username}, +%%% {password,Password}]</code></p> %%% %%% <p>If a config variable is defined in multiple files and you want to %%% access all possible values, use the <code>all</code> option. The @@ -398,9 +411,7 @@ get_config(Required,Default) -> %%% %%% <p>If you want config elements (key-value tuples) returned as result %%% instead of values, use the <code>element</code> option. -%%% The returned elements will then be on the form <code>{KeyOrName,Value}</code>, -%%% or (in case a subkey has been specified) -%%% <code>{{KeyOrName,SubKey},Value}</code></p> +%%% The returned elements will then be on the form <code>{Required,Value}</code></p> %%% %%% @see get_config/1 %%% @see get_config/2 @@ -411,7 +422,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() diff --git a/lib/common_test/src/ct_config.erl b/lib/common_test/src/ct_config.erl index c585fe0995..463b7d180c 100644 --- a/lib/common_test/src/ct_config.erl +++ b/lib/common_test/src/ct_config.erl @@ -122,8 +122,8 @@ return({To,Ref},Result) -> loop(StartDir) -> receive - {{require,Name,Tag,SubTags},From} -> - Result = do_require(Name,Tag,SubTags), + {{require,Name,Key},From} -> + Result = do_require(Name,Key), return(From,Result), loop(StartDir); {{set_default_config,{Config,Scope}},From} -> @@ -168,16 +168,19 @@ reload_config(KeyOrName) -> call({reload_config, KeyOrName}). process_default_configs(Opts) -> - case lists:keysearch(config, 1, Opts) of - {value,{_,Files=[File|_]}} when is_list(File) -> - Files; - {value,{_,File=[C|_]}} when is_integer(C) -> - [File]; - {value,{_,[]}} -> - []; - false -> - [] - end. + lists:flatmap(fun({config,[_|_] = FileOrFiles}) -> + case {io_lib:printable_list(FileOrFiles), + io_lib:printable_list(hd(FileOrFiles))} of + {true,true} -> + FileOrFiles; + {true,false} -> + [FileOrFiles]; + _ -> + [] + end; + (_) -> + [] + end,Opts). process_user_configs(Opts, Acc) -> case lists:keytake(userconfig, 1, Opts) of @@ -319,75 +322,58 @@ get_config(KeyOrName,Default) -> get_config(KeyOrName,Default,[]). get_config(KeyOrName,Default,Opts) when is_atom(KeyOrName) -> - case lookup_config(KeyOrName) of - [] -> - Default; - [{_Ref,Val}|_] = Vals -> - case {lists:member(all,Opts),lists:member(element,Opts)} of - {true,true} -> - [{KeyOrName,V} || {_R,V} <- lists:sort(Vals)]; - {true,false} -> - [V || {_R,V} <- lists:sort(Vals)]; - {false,true} -> - {KeyOrName,Val}; - {false,false} -> - Val - end + case get_config({KeyOrName}, Default, Opts) of + %% If only an atom is given, then we need to unwrap the + %% key if it is returned + {{KeyOrName}, Val} -> + {KeyOrName, Val}; + [{{KeyOrName}, _Val}|_] = Res -> + [{K, Val} || {{K},Val} <- Res, K == KeyOrName]; + Else -> + Else end; -get_config({KeyOrName,SubKey},Default,Opts) -> - case lookup_config(KeyOrName) of +%% This useage of get_config is only used by internal ct functions +%% and may change at any time +get_config({DeepKey,SubKey}, Default, Opts) when is_tuple(DeepKey) -> + get_config(erlang:append_element(DeepKey, SubKey), Default, Opts); +get_config(KeyOrName,Default,Opts) when is_tuple(KeyOrName) -> + case lookup_config(element(1,KeyOrName)) of [] -> - Default; + format_value([Default],KeyOrName,Opts); Vals -> - Vals1 = case [Val || {_Ref,Val} <- lists:sort(Vals)] of - Result=[L|_] when is_list(L) -> - case L of - [{_,_}|_] -> - Result; - _ -> - [] - end; - _ -> - [] - end, - case get_subconfig([SubKey],Vals1,[],Opts) of - {ok,[{_,SubVal}|_]=SubVals} -> - case {lists:member(all,Opts),lists:member(element,Opts)} of - {true,true} -> - [{{KeyOrName,SubKey},Val} || {_,Val} <- SubVals]; - {true,false} -> - [Val || {_SubKey,Val} <- SubVals]; - {false,true} -> - {{KeyOrName,SubKey},SubVal}; - {false,false} -> - SubVal - end; - _ -> - Default - end + NewVals = + lists:map( + fun({Val}) -> + get_config(tl(tuple_to_list(KeyOrName)), + Val,Default,Opts) + end,Vals), + format_value(NewVals,KeyOrName,Opts) end. -get_subconfig(SubKeys,Values) -> - get_subconfig(SubKeys,Values,[],[]). - -get_subconfig(SubKeys,[Value|Rest],Mapped,Opts) -> - case do_get_config(SubKeys,Value,[]) of - {ok,SubMapped} -> - case lists:member(all,Opts) of - true -> - get_subconfig(SubKeys,Rest,Mapped++SubMapped,Opts); - false -> - {ok,SubMapped} - end; - _Error -> - get_subconfig(SubKeys,Rest,Mapped,Opts) +get_config([],Vals,_Default,_Opts) -> + Vals; +get_config([[]],Vals,Default,Opts) -> + get_config([],Vals,Default,Opts); +%% This case is used by {require,{unix,[port,host]}} functionality +get_config([SubKeys], Vals, Default, _Opts) when is_list(SubKeys) -> + case do_get_config(SubKeys, Vals, []) of + {ok, SubVals} -> + [SubVal || {_,SubVal} <- SubVals]; + + _ -> + Default end; -get_subconfig(SubKeys,[],[],_) -> - {error,{not_available,SubKeys}}; -get_subconfig(_SubKeys,[],Mapped,_) -> - {ok,Mapped}. +get_config([Key|Rest], Vals, Default, Opts) -> + case do_get_config([Key], Vals, []) of + {ok, [{Key,NewVals}]} -> + get_config(Rest, NewVals, Default, Opts); + _ -> + Default + end. +do_get_config([Key|_], Available, _Mapped) when not is_list(Available) -> + {error,{not_available,Key}}; do_get_config([Key|Required],Available,Mapped) -> case lists:keysearch(Key,1,Available) of {value,{Key,Value}} -> @@ -403,8 +389,7 @@ do_get_config([],_Available,Mapped) -> get_all_config() -> ets:select(?attr_table,[{#ct_conf{name='$1',key='$2',value='$3', default='$4',_='_'}, - [], - [{{'$1','$2','$3','$4'}}]}]). + [],[{{'$1','$2','$3','$4'}}]}]). lookup_config(KeyOrName) -> case lookup_name(KeyOrName) of @@ -415,13 +400,23 @@ lookup_config(KeyOrName) -> end. lookup_name(Name) -> - ets:select(?attr_table,[{#ct_conf{ref='$1',value='$2',name=Name,_='_'}, - [], - [{{'$1','$2'}}]}]). + ets:select(?attr_table,[{#ct_conf{value='$1',name=Name,_='_'}, + [],[{{'$1'}}]}]). lookup_key(Key) -> - ets:select(?attr_table,[{#ct_conf{key=Key,ref='$1',value='$2',name='_UNDEF',_='_'}, - [], - [{{'$1','$2'}}]}]). + ets:select(?attr_table,[{#ct_conf{key=Key,value='$1',name='_UNDEF',_='_'}, + [],[{{'$1'}}]}]). + +format_value([SubVal|_] = SubVals, KeyOrName, Opts) -> + case {lists:member(all,Opts),lists:member(element,Opts)} of + {true,true} -> + [{KeyOrName,Val} || Val <- SubVals]; + {true,false} -> + [Val || Val <- SubVals]; + {false,true} -> + {KeyOrName,SubVal}; + {false,false} -> + SubVal + end. lookup_handler_for_config({Key, _Subkey}) -> lookup_handler_for_config(Key); @@ -475,65 +470,78 @@ release_allocated([H|T]) -> release_allocated([]) -> ok. -allocate(Name,Key,SubKeys) -> - case ets:match_object(?attr_table,#ct_conf{key=Key,name='_UNDEF',_='_'}) of - [] -> +allocate(Name,Key) -> + Ref = make_ref(), + case get_config(Key,Ref,[all,element]) of + [{_,Ref}] -> {error,{not_available,Key}}; - Available -> - case allocate_subconfig(Name,SubKeys,Available,false) of - ok -> - ok; - Error -> - Error - end + Configs -> + associate(Name,Key,Configs), + ok end. -allocate_subconfig(Name,SubKeys,[C=#ct_conf{value=Value}|Rest],Found) -> - case do_get_config(SubKeys,Value,[]) of - {ok,_SubMapped} -> - ets:insert(?attr_table,C#ct_conf{name=Name}), - allocate_subconfig(Name,SubKeys,Rest,true); - _Error -> - allocate_subconfig(Name,SubKeys,Rest,Found) - end; -allocate_subconfig(_Name,_SubKeys,[],true) -> + +associate('_UNDEF',_Key,_Configs) -> ok; -allocate_subconfig(_Name,SubKeys,[],false) -> - {error,{not_available,SubKeys}}. +associate(Name,{Key,SubKeys},Configs) when is_atom(Key), is_list(SubKeys) -> + associate_int(Name,Configs,"true"); +associate(Name,_Key,Configs) -> + associate_int(Name,Configs,os:getenv("COMMON_TEST_ALIAS_TOP")). + +associate_int(Name,Configs,"true") -> + lists:map(fun({K,_Config}) -> + Cs = ets:match_object( + ?attr_table, + #ct_conf{key=element(1,K), + name='_UNDEF',_='_'}), + [ets:insert(?attr_table,C#ct_conf{name=Name}) + || C <- Cs] + end,Configs); +associate_int(Name,Configs,_) -> + lists:map(fun({K,Config}) -> + Key = if is_tuple(K) -> element(1,K); + is_atom(K) -> K + end, + + Cs = ets:match_object( + ?attr_table, + #ct_conf{key=Key, + name='_UNDEF',_='_'}), + [ets:insert(?attr_table,C#ct_conf{name=Name, + value=Config}) + || C <- Cs] + end,Configs). + + delete_config(Default) -> ets:match_delete(?attr_table,#ct_conf{default=Default,_='_'}), ok. -require(Key) when is_atom(Key) -> - require({Key,[]}); -require({Key,SubKeys}) when is_atom(Key) -> - allocate('_UNDEF',Key,to_list(SubKeys)); +require(Key) when is_atom(Key); is_tuple(Key) -> + allocate('_UNDEF',Key); require(Key) -> {error,{invalid,Key}}. -require(Name,Key) when is_atom(Key) -> - require(Name,{Key,[]}); -require(Name,{Key,SubKeys}) when is_atom(Name), is_atom(Key) -> - call({require,Name,Key,to_list(SubKeys)}); +require(Name,Key) when is_atom(Name),is_atom(Key) orelse is_tuple(Key) -> + call({require,Name,Key}); require(Name,Keys) -> {error,{invalid,{Name,Keys}}}. -to_list(X) when is_list(X) -> X; -to_list(X) -> [X]. - -do_require(Name,Key,SubKeys) when is_list(SubKeys) -> +do_require(Name,Key) -> case get_key_from_name(Name) of {error,_} -> - allocate(Name,Key,SubKeys); + allocate(Name,Key); {ok,Key} -> %% already allocated - check that it has all required subkeys - Vals = [Val || {_Ref,Val} <- lookup_name(Name)], - case get_subconfig(SubKeys,Vals) of - {ok,_SubMapped} -> - ok; - Error -> - Error + R = make_ref(), + case get_config(Key,R,[]) of + R -> + {error,{not_available,Key}}; + {error,_} = Error -> + Error; + _Error -> + ok end; {ok,OtherKey} -> {error,{name_in_use,Name,OtherKey}} diff --git a/lib/common_test/src/ct_ftp.erl b/lib/common_test/src/ct_ftp.erl index 5db73066a3..723715c986 100644 --- a/lib/common_test/src/ct_ftp.erl +++ b/lib/common_test/src/ct_ftp.erl @@ -66,6 +66,7 @@ %%% {unix,[{ftp,IpAddr}, %%% {username,Username}, %%% {password,Password}]}.</pre> +%%% @see ct:require/2 put(KeyOrName,LocalFile,RemoteFile) -> Fun = fun(Ftp) -> send(Ftp,LocalFile,RemoteFile) end, open_and_do(KeyOrName,Fun). @@ -85,6 +86,7 @@ put(KeyOrName,LocalFile,RemoteFile) -> %%% %%% <p>The config file must be as for put/3.</p> %%% @see put/3 +%%% @see ct:require/2 get(KeyOrName,RemoteFile,LocalFile) -> Fun = fun(Ftp) -> recv(Ftp,RemoteFile,LocalFile) end, open_and_do(KeyOrName,Fun). @@ -105,6 +107,10 @@ get(KeyOrName,RemoteFile,LocalFile) -> %%% simply use <code>Key</code>, the configuration variable name, to %%% specify the target. Note that a connection that has no associated target %%% name can only be closed with the handle value.</p> +%%% +%%% <p>See <c>ct:require/2</c> for how to create a new <c>Name</c></p> +%%% +%%% @see ct:require/2 open(KeyOrName) -> case ct_util:get_key_from_name(KeyOrName) of {ok,node} -> diff --git a/lib/common_test/src/ct_hooks.erl b/lib/common_test/src/ct_hooks.erl index d0432b604d..1bcc63738e 100644 --- a/lib/common_test/src/ct_hooks.erl +++ b/lib/common_test/src/ct_hooks.erl @@ -48,7 +48,7 @@ %% @doc Called before any suites are started -spec init(State :: term()) -> ok | - {error, Reason :: term()}. + {fail, Reason :: term()}. init(Opts) -> call(get_new_hooks(Opts, undefined) ++ get_builtin_hooks(Opts), ok, init, []). diff --git a/lib/common_test/src/ct_netconfc.erl b/lib/common_test/src/ct_netconfc.erl index d9c4a962dc..52fe9599ce 100644 --- a/lib/common_test/src/ct_netconfc.erl +++ b/lib/common_test/src/ct_netconfc.erl @@ -408,6 +408,7 @@ open(Options) -> %% server. It is not used for any other purposes during the lifetime %% of the connection. %% +%% @see ct:require/2 %% @end %%---------------------------------------------------------------------- open(KeyOrName, ExtraOpts) -> @@ -1074,12 +1075,18 @@ handle_msg({get_event_streams=Op,Streams,Timeout}, From, State) -> handle_msg({ssh_cm, _CM, {data, _Ch, _Type, Data}}, State) -> handle_data(Data, State); -handle_msg({ssh_cm, _CM, {closed,_Ch}}, State) -> - %% This will happen if the server terminates the connection, as in - %% kill-session (or if ssh:close is called from somewhere +handle_msg({ssh_cm, _CM, _SshCloseMsg}, State) -> + %% _SshCloseMsg can probably be one of + %% {eof,Ch} + %% {exit_status,Ch,Status} + %% {exit_signal,Ch,ExitSignal,ErrorMsg,LanguageString} + %% {signal,Ch,Signal} + + %% This might e.g. happen if the server terminates the connection, + %% as in kill-session (or if ssh:close is called from somewhere %% unexpected). - %%! Log this?? - i.e. as server closing the connection + %%! Log this?? %%! Currently the log will say that the client closed the %%! connection - due to terminate/2 diff --git a/lib/common_test/src/ct_run.erl b/lib/common_test/src/ct_run.erl index a202ca15e2..faf5786a54 100644 --- a/lib/common_test/src/ct_run.erl +++ b/lib/common_test/src/ct_run.erl @@ -70,7 +70,7 @@ enable_builtin_hooks, include = [], auto_compile, - silent_connections, + silent_connections = [], stylesheet, multiply_timetraps = 1, scale_timetraps = false, @@ -304,9 +304,9 @@ script_start1(Parent, Args) -> %% silent connections SilentConns = get_start_opt(silent_connections, - fun(["all"]) -> []; + fun(["all"]) -> [all]; (Conns) -> [list_to_atom(Conn) || Conn <- Conns] - end, Args), + end, [], Args), %% stylesheet Stylesheet = get_start_opt(stylesheet, fun([SS]) -> ?abs(SS) end, Args), @@ -401,6 +401,9 @@ script_start2(StartOpts = #opts{vts = undefined, AllVerbosity = merge_keyvals([StartOpts#opts.verbosity, SpecStartOpts#opts.verbosity]), + AllSilentConns = + merge_vals([StartOpts#opts.silent_connections, + SpecStartOpts#opts.silent_connections]), Cover = choose_val(StartOpts#opts.cover, SpecStartOpts#opts.cover), @@ -467,6 +470,7 @@ script_start2(StartOpts = #opts{vts = undefined, logopts = AllLogOpts, basic_html = BasicHtml, verbosity = AllVerbosity, + silent_connections = AllSilentConns, config = SpecStartOpts#opts.config, event_handlers = AllEvHs, ct_hooks = AllCTHooks, @@ -914,9 +918,9 @@ run_test2(StartOpts) -> %% silent connections SilentConns = get_start_opt(silent_connections, - fun(all) -> []; + fun(all) -> [all]; (Conns) -> Conns - end, StartOpts), + end, [], StartOpts), %% stylesheet Stylesheet = get_start_opt(stylesheet, fun(SS) -> ?abs(SS) end, @@ -1043,6 +1047,8 @@ run_spec_file(Relaxed, SpecOpts#opts.stylesheet), AllVerbosity = merge_keyvals([Opts#opts.verbosity, SpecOpts#opts.verbosity]), + AllSilentConns = merge_vals([Opts#opts.silent_connections, + SpecOpts#opts.silent_connections]), AllConfig = merge_vals([CfgFiles, SpecOpts#opts.config]), Cover = choose_val(Opts#opts.cover, SpecOpts#opts.cover), @@ -1091,6 +1097,7 @@ run_spec_file(Relaxed, stylesheet = Stylesheet, basic_html = BasicHtml, verbosity = AllVerbosity, + silent_connections = AllSilentConns, config = AllConfig, event_handlers = AllEvHs, auto_compile = AutoCompile, @@ -1354,6 +1361,7 @@ get_data_for_node(#testspec{label = Labels, basic_html = BHs, stylesheet = SSs, verbosity = VLvls, + silent_connections = SilentConnsList, cover = CoverFs, config = Cfgs, userconfig = UsrCfgs, @@ -1381,6 +1389,10 @@ get_data_for_node(#testspec{label = Labels, undefined -> []; Lvls -> Lvls end, + SilentConns = case proplists:get_value(Node, SilentConnsList) of + undefined -> []; + SCs -> SCs + end, Cover = proplists:get_value(Node, CoverFs), MT = proplists:get_value(Node, MTs), ST = proplists:get_value(Node, STs), @@ -1398,6 +1410,7 @@ get_data_for_node(#testspec{label = Labels, basic_html = BasicHtml, stylesheet = Stylesheet, verbosity = Verbosity, + silent_connections = SilentConns, cover = Cover, config = ConfigFiles, event_handlers = EvHandlers, @@ -1632,13 +1645,16 @@ compile_and_run(Tests, Skip, Opts, Args) -> %% enable silent connections case Opts#opts.silent_connections of [] -> - Conns = ct_util:override_silence_all_connections(), - ct_logs:log("Silent connections", "~p", [Conns]); - Conns when is_list(Conns) -> - ct_util:override_silence_connections(Conns), - ct_logs:log("Silent connections", "~p", [Conns]); - _ -> - ok + ok; + Conns -> + case lists:member(all, Conns) of + true -> + Conns1 = ct_util:override_silence_all_connections(), + ct_logs:log("Silent connections", "~p", [Conns1]); + false -> + ct_util:override_silence_connections(Conns), + ct_logs:log("Silent connections", "~p", [Conns]) + end end, log_ts_names(Opts#opts.testspecs), TestSuites = suite_tuples(Tests), diff --git a/lib/common_test/src/ct_ssh.erl b/lib/common_test/src/ct_ssh.erl index 09cd4ef02a..d0d94e1e6e 100644 --- a/lib/common_test/src/ct_ssh.erl +++ b/lib/common_test/src/ct_ssh.erl @@ -133,10 +133,11 @@ connect(KeyOrName, ExtraOpts) when is_list(ExtraOpts) -> %%% is used to identify the connection, this name may %%% be used as connection reference for subsequent calls. %%% It's only possible to have one open connection at a time -%%% associated with <code>Name</code>. If <code>Key</code> is +%%% associated with <code>Name</code>. If <code>Key</code> is %%% used, the returned handle must be used for subsequent calls %%% (multiple connections may be opened using the config -%%% data specified by <code>Key</code>).</p> +%%% data specified by <code>Key</code>). See <c>ct:require/2</c> +%%% for how to create a new <c>Name</c></p> %%% %%% <p><code>ConnType</code> will always override the type %%% specified in the address tuple in the configuration data (and @@ -152,6 +153,8 @@ connect(KeyOrName, ExtraOpts) when is_list(ExtraOpts) -> %%% The extra options will override any existing options with the %%% same key in the config data. For details on valid SSH %%% options, see the documentation for the OTP ssh application.</p> +%%% +%%% @see ct:require/2 connect(KeyOrName, ConnType, ExtraOpts) -> case ct:get_config(KeyOrName) of undefined -> diff --git a/lib/common_test/src/ct_telnet.erl b/lib/common_test/src/ct_telnet.erl index f4a551e3ff..e37a657617 100644 --- a/lib/common_test/src/ct_telnet.erl +++ b/lib/common_test/src/ct_telnet.erl @@ -155,6 +155,8 @@ open(KeyOrName,ConnType,TargetMod) -> %%% <p><code>TargetMod</code> is a module which exports the functions %%% <code>connect(Ip,Port,KeepAlive,Extra)</code> and <code>get_prompt_regexp()</code> %%% for the given <code>TargetType</code> (e.g. <code>unix_telnet</code>).</p> +%%% +%%% @see ct:require/2 open(KeyOrName,ConnType,TargetMod,Extra) -> case ct:get_config({KeyOrName,ConnType}) of undefined -> diff --git a/lib/common_test/src/ct_testspec.erl b/lib/common_test/src/ct_testspec.erl index 7759aca16b..de63ac3b75 100644 --- a/lib/common_test/src/ct_testspec.erl +++ b/lib/common_test/src/ct_testspec.erl @@ -940,6 +940,12 @@ handle_data(verbosity,Node,VLvls,_Spec) when is_list(VLvls) -> VLvls1 = lists:map(fun(VLvl = {_Cat,_Lvl}) -> VLvl; (Lvl) -> {'$unspecified',Lvl} end, VLvls), [{Node,VLvls1}]; +handle_data(silent_connections,Node,all,_Spec) -> + [{Node,[all]}]; +handle_data(silent_connections,Node,Conn,_Spec) when is_atom(Conn) -> + [{Node,[Conn]}]; +handle_data(silent_connections,Node,Conns,_Spec) -> + [{Node,Conns}]; handle_data(_Tag,Node,Data,_Spec) -> [{Node,Data}]. @@ -947,10 +953,10 @@ handle_data(_Tag,Node,Data,_Spec) -> should_be_added(Tag,Node,_Data,Spec) -> if %% list terms *without* possible duplicates here - Tag == logdir; Tag == logopts; - Tag == basic_html; Tag == label; + Tag == logdir; Tag == logopts; + Tag == basic_html; Tag == label; Tag == auto_compile; Tag == stylesheet; - Tag == verbosity -> + Tag == verbosity; Tag == silent_connections -> lists:keymember(ref2node(Node,Spec#testspec.nodes),1, read_field(Spec,Tag)) == false; %% for terms *with* possible duplicates @@ -1267,6 +1273,8 @@ valid_terms() -> {basic_html,3}, {verbosity,2}, {verbosity,3}, + {silent_connections,2}, + {silent_connections,3}, {label,2}, {label,3}, {event_handler,2}, diff --git a/lib/common_test/src/ct_util.hrl b/lib/common_test/src/ct_util.hrl index 7015014441..7b08e78433 100644 --- a/lib/common_test/src/ct_util.hrl +++ b/lib/common_test/src/ct_util.hrl @@ -36,6 +36,7 @@ logopts=[], basic_html=[], verbosity=[], + silent_connections=[], cover=[], config=[], userconfig=[], diff --git a/lib/common_test/test/ct_config_SUITE.erl b/lib/common_test/test/ct_config_SUITE.erl index 18218bee47..83b8c00458 100644 --- a/lib/common_test/test/ct_config_SUITE.erl +++ b/lib/common_test/test/ct_config_SUITE.erl @@ -88,7 +88,8 @@ require(Config) when is_list(Config) -> DataDir = ?config(data_dir, Config), run_test(config_static_SUITE, Config, - {config, filename:join(DataDir, "config/config.txt")}, + [{config, filename:join(DataDir, "config/shadow.txt")}, + {config, filename:join(DataDir, "config/config.txt")}], ["config_static_SUITE"]). install_config(Config) when is_list(Config) -> @@ -106,7 +107,8 @@ userconfig_static(Config) when is_list(Config) -> DataDir = ?config(data_dir, Config), run_test(config_static_SUITE, Config, - {userconfig, {ct_config_xml, filename:join(DataDir, "config/config.xml")}}, + [{userconfig, {ct_config_xml, filename:join(DataDir, "config/config.xml")}}, + {config, filename:join(DataDir, "config/shadow.txt")}], ["config_static_SUITE"]). userconfig_dynamic(Config) when is_list(Config) -> @@ -121,7 +123,8 @@ testspec_legacy(Config) when is_list(Config) -> make_spec(DataDir, ConfigDir, "spec_legacy.spec", [config_static_SUITE], - [{config, filename:join(DataDir, "config/config.txt")}]), + [{config, filename:join(DataDir, "config/shadow.txt")}, + {config, filename:join(DataDir, "config/config.txt")}]), run_test(config_static_SUITE, Config, {spec, filename:join(ConfigDir, "spec_legacy.spec")}, @@ -134,7 +137,8 @@ testspec_static(Config) when is_list(Config) -> make_spec(DataDir, ConfigDir, "spec_static.spec", [config_static_SUITE], - [{userconfig, {ct_config_xml, filename:join(DataDir, "config/config.xml")}}]), + [{userconfig, {ct_config_xml, filename:join(DataDir, "config/config.xml")}}, + {config, filename:join(DataDir, "config/shadow.txt")}]), run_test(config_static_SUITE, Config, {spec, filename:join(ConfigDir, "spec_static.spec")}, @@ -179,13 +183,15 @@ run_test(Name, Config, CTConfig, SuiteNames)-> ExpEvents = events_to_check(Name), ok = ct_test_support:verify_events(ExpEvents, TestEvents, Config). -setup_env(Test, Config, CTConfig) -> +setup_env(Test, Config, CTConfig) when is_list(CTConfig) -> Opts0 = ct_test_support:get_opts(Config), Level = ?config(trace_level, Config), EvHArgs = [{cbm,ct_test_support},{trace_level,Level}], - Opts = Opts0 ++ [Test,{event_handler,{?eh,EvHArgs}}, CTConfig], + Opts = Opts0 ++ [Test,{event_handler,{?eh,EvHArgs}} | CTConfig], ERPid = ct_test_support:start_event_receiver(Config), - {Opts,ERPid}. + {Opts,ERPid}; +setup_env(Test, Config, CTConfig) -> + setup_env(Test, Config, [CTConfig]). reformat_events(Events, EH) -> ct_test_support:reformat(Events, EH). @@ -202,40 +208,49 @@ events_to_check(_, 0) -> events_to_check(Test, N) -> expected_events(Test) ++ events_to_check(Test, N-1). +-define(ok(Name,Suite,Stat),{?eh,tc_start,{Suite,Name}}, + {?eh,tc_done,{Suite,Name,ok}}, + {?eh,test_stats,Stat}). +-define(nok(Name,Suite,Reason,Stat),{?eh,tc_start,{Suite,Name}}, + {?eh,tc_done,{Suite,Name,Reason}}, + {?eh,test_stats,Stat}). + +-define(sok(Name,Stat),?ok(Name,config_static_SUITE,Stat)). +-define(snok(Name,Reason,Stat),?nok(Name,config_static_SUITE,Reason,Stat)). + +-define(dok(Name,Stat),?ok(Name,config_dynamic_SUITE,Stat)). +-define(dnok(Name,Reason,Stat),?nok(Name,config_dynamic_SUITE,Reason,Stat)). + expected_events(config_static_SUITE)-> [ {?eh,start_logging,{'DEF','RUNDIR'}}, {?eh,test_start,{'DEF',{'START_TIME','LOGDIR'}}}, - {?eh,start_info,{1,1,8}}, + {?eh,start_info,{1,1,'_'}}, {?eh,tc_start,{config_static_SUITE,init_per_suite}}, {?eh,tc_done,{config_static_SUITE,init_per_suite,ok}}, - {?eh,tc_start,{config_static_SUITE,test_get_config_simple}}, - {?eh,tc_done,{config_static_SUITE,test_get_config_simple,ok}}, - {?eh,test_stats,{1,0,{0,0}}}, - {?eh,tc_start,{config_static_SUITE,test_get_config_nested}}, - {?eh,tc_done,{config_static_SUITE,test_get_config_nested,ok}}, - {?eh,test_stats,{2,0,{0,0}}}, - {?eh,tc_start,{config_static_SUITE,test_default_suitewide}}, - {?eh,tc_done,{config_static_SUITE,test_default_suitewide,ok}}, - {?eh,test_stats,{3,0,{0,0}}}, - {?eh,tc_start,{config_static_SUITE,test_config_name_already_in_use1}}, - {?eh,tc_done, - {config_static_SUITE,test_config_name_already_in_use1,{skipped,{config_name_already_in_use,[x1]}}}}, - {?eh,test_stats,{3,0,{1,0}}}, - {?eh,tc_start,{config_static_SUITE,test_default_tclocal}}, - {?eh,tc_done,{config_static_SUITE,test_default_tclocal,ok}}, - {?eh,test_stats,{4,0,{1,0}}}, - {?eh,tc_start,{config_static_SUITE,test_config_name_already_in_use2}}, - {?eh,tc_done, - {config_static_SUITE,test_config_name_already_in_use2, - {skipped,{config_name_already_in_use,[alias,x1]}}}}, - {?eh,test_stats,{4,0,{2,0}}}, - {?eh,tc_start,{config_static_SUITE,test_alias_tclocal}}, - {?eh,tc_done,{config_static_SUITE,test_alias_tclocal,ok}}, - {?eh,test_stats,{5,0,{2,0}}}, - {?eh,tc_start,{config_static_SUITE,test_get_config_undefined}}, - {?eh,tc_done,{config_static_SUITE,test_get_config_undefined,ok}}, - {?eh,test_stats,{6,0,{2,0}}}, + ?sok(test_get_config_simple,{1,0,{0,0}}), + ?sok(test_get_config_nested,{2,0,{0,0}}), + ?sok(test_get_config_deep_nested,{3,0,{0,0}}), + ?sok(test_default_suitewide,{4,0,{0,0}}), + ?snok(test_config_name_already_in_use1, + {skipped,{config_name_already_in_use,[x1]}},{4,0,{1,0}}), + ?sok(test_default_tclocal,{5,0,{1,0}}), + ?snok(test_config_name_already_in_use2, + {skipped,{config_name_already_in_use,[alias,x1]}},{5,0,{2,0}}), + ?sok(test_alias_tclocal,{6,0,{2,0}}), + ?sok(test_get_config_undefined,{7,0,{2,0}}), + ?sok(test_require_subvals,{8,0,{2,0}}), + ?snok(test_require_subvals2, + {skipped,{require_failed, + {not_available,{gen_cfg,[a,b,c,d]}}}},{8,0,{2,1}}), + ?sok(test_require_deep_config,{9,0,{2,1}}), + ?sok(test_shadow_all,{10,0,{2,1}}), + ?sok(test_element,{11,0,{2,1}}), + ?sok(test_shadow_all_element,{12,0,{2,1}}), + ?sok(test_internal_deep,{13,0,{2,1}}), + ?sok(test_alias_tclocal_nested,{14,0,{2,1}}), + ?sok(test_alias_tclocal_nested_backward_compat,{15,0,{2,1}}), + ?sok(test_alias_tclocal_nested_backward_compat_subvals,{16,0,{2,1}}), {?eh,tc_start,{config_static_SUITE,end_per_suite}}, {?eh,tc_done,{config_static_SUITE,end_per_suite,ok}}, {?eh,test_done,{'DEF','STOP_TIME'}}, @@ -246,29 +261,14 @@ expected_events(config_dynamic_SUITE)-> [ {?eh,start_logging,{'DEF','RUNDIR'}}, {?eh,test_start,{'DEF',{'START_TIME','LOGDIR'}}}, - {?eh,start_info,{1,1,5}}, + {?eh,start_info,{1,1,'_'}}, {?eh,tc_start,{config_dynamic_SUITE,init_per_suite}}, {?eh,tc_done,{config_dynamic_SUITE,init_per_suite,ok}}, - {?eh,tc_start,{config_dynamic_SUITE,test_get_known_variable}}, - {?eh,tc_done, - {config_dynamic_SUITE,test_get_known_variable,ok}}, - {?eh,test_stats,{1,0,{0,0}}}, - {?eh,tc_start,{config_dynamic_SUITE,test_localtime_update}}, - {?eh,tc_done,{config_dynamic_SUITE,test_localtime_update,ok}}, - {?eh,test_stats,{2,0,{0,0}}}, - {?eh,tc_start,{config_dynamic_SUITE,test_server_pid}}, - {?eh,tc_done,{config_dynamic_SUITE,test_server_pid,ok}}, - {?eh,test_stats,{3,0,{0,0}}}, - {?eh,tc_start, - {config_dynamic_SUITE,test_disappearable_variable}}, - {?eh,tc_done, - {config_dynamic_SUITE,test_disappearable_variable,ok}}, - {?eh,test_stats,{4,0,{0,0}}}, - {?eh,tc_start, - {config_dynamic_SUITE,test_disappearable_variable_alias}}, - {?eh,tc_done, - {config_dynamic_SUITE,test_disappearable_variable_alias,ok}}, - {?eh,test_stats,{5,0,{0,0}}}, + ?dok(test_get_known_variable,{1,0,{0,0}}), + ?dok(test_localtime_update,{2,0,{0,0}}), + ?dok(test_server_pid,{3,0,{0,0}}), + ?dok(test_disappearable_variable,{4,0,{0,0}}), + ?dok(test_disappearable_variable_alias,{5,0,{0,0}}), {?eh,tc_start,{config_dynamic_SUITE,end_per_suite}}, {?eh,tc_done,{config_dynamic_SUITE,end_per_suite,ok}}, {?eh,test_done,{'DEF','STOP_TIME'}}, diff --git a/lib/common_test/test/ct_config_SUITE_data/config/config.txt b/lib/common_test/test/ct_config_SUITE_data/config/config.txt index fcbffcd7f3..e4bcc5ba6b 100644 --- a/lib/common_test/test/ct_config_SUITE_data/config/config.txt +++ b/lib/common_test/test/ct_config_SUITE_data/config/config.txt @@ -2,7 +2,8 @@ {gen_cfg, [ {a,a_value}, - {b,b_value} + {b,b_value}, + {c,[{d,d_value}]} ]}. {gen_cfg2, [ diff --git a/lib/common_test/test/ct_config_SUITE_data/config/config.xml b/lib/common_test/test/ct_config_SUITE_data/config/config.xml index 0a3e5f2e31..8eeff1482f 100644 --- a/lib/common_test/test/ct_config_SUITE_data/config/config.xml +++ b/lib/common_test/test/ct_config_SUITE_data/config/config.xml @@ -3,6 +3,7 @@ <gen_cfg> <a>a_value</a> <b>b_value</b> + <c><d>d_value</d></c> </gen_cfg> <gen_cfg2> <c>"Hello, world!"</c> diff --git a/lib/common_test/test/ct_config_SUITE_data/config/shadow.txt b/lib/common_test/test/ct_config_SUITE_data/config/shadow.txt new file mode 100644 index 0000000000..865bf9255a --- /dev/null +++ b/lib/common_test/test/ct_config_SUITE_data/config/shadow.txt @@ -0,0 +1,12 @@ +{x, suite}. +{gen_cfg3, + [ + {l, + [ + {m, + [ + {n, "n"}, + {o, 'o'} + ]} + ]} + ]}. diff --git a/lib/common_test/test/ct_config_SUITE_data/config/test/config_static_SUITE.erl b/lib/common_test/test/ct_config_SUITE_data/config/test/config_static_SUITE.erl index 8751a2e8f3..d7119d7fde 100644 --- a/lib/common_test/test/ct_config_SUITE_data/config/test/config_static_SUITE.erl +++ b/lib/common_test/test/ct_config_SUITE_data/config/test/config_static_SUITE.erl @@ -46,7 +46,7 @@ suite() -> {require, gen_cfg3}, {require, alias, gen_cfg}, %% x1 default value - {x1, {x,suite}} + {default_config, x1, {x,suite}} ]. init_per_suite(Config) -> @@ -55,14 +55,24 @@ init_per_suite(Config) -> end_per_suite(_) -> ok. -all() -> [test_get_config_simple, test_get_config_nested, test_default_suitewide, +all() -> [test_get_config_simple, test_get_config_nested, + test_get_config_deep_nested, test_default_suitewide, test_config_name_already_in_use1, test_default_tclocal, test_config_name_already_in_use2, test_alias_tclocal, - test_get_config_undefined]. - -init_per_testcase(_, Config) -> + test_get_config_undefined, + test_require_subvals,test_require_subvals2,test_require_deep_config, + test_shadow_all,test_element,test_shadow_all_element, + test_internal_deep, test_alias_tclocal_nested, + test_alias_tclocal_nested_backward_compat, + test_alias_tclocal_nested_backward_compat_subvals +]. + +init_per_testcase(_,Config) -> Config. +end_per_testcase(test_alias_tclocal_nested_backward_compat, _) -> + os:putenv("COMMON_TEST_ALIAS_TOP",""), + ok; end_per_testcase(_, _) -> ok. @@ -76,6 +86,11 @@ test_get_config_nested(_)-> a_value = ct:get_config({gen_cfg, a}), ok. +%% test getting a deep nested value +test_get_config_deep_nested(_)-> + d_value = ct:get_config({gen_cfg, c, d}), + ok. + %% test suite-wide default value test_default_suitewide(_)-> suite = ct:get_config(x1), @@ -112,12 +127,73 @@ test_config_name_already_in_use2(_) -> %% test aliases test_alias_tclocal() -> [{require,newalias,gen_cfg}]. -test_alias_tclocal(_) -> - A = [{a,a_value},{b,b_value}] = ct:get_config(newalias), +test_alias_tclocal(C) when is_list(C) -> + test_alias_tclocal(newalias); +test_alias_tclocal(Alias) when is_atom(Alias) -> + A = [{a,a_value},{b,b_value},{c,[{d,d_value}]}] = ct:get_config(Alias), A = ct:get_config(gen_cfg), + B = b_value = ct:get_config({Alias,b}), + B = ct:get_config({gen_cfg,b}), + ok. + +%% test nested aliases +test_alias_tclocal_nested() -> + [{require,newalias2,{gen_cfg,c}}]. +test_alias_tclocal_nested(_) -> + A = [{d,d_value}] = ct:get_config(newalias2), + A = ct:get_config({gen_cfg,c}), + B = d_value = ct:get_config({newalias2,d}), + B = ct:get_config({gen_cfg,c,d}), ok. +%% test nested aliases backward compat option +test_alias_tclocal_nested_backward_compat() -> + os:putenv("COMMON_TEST_ALIAS_TOP","true"), + [{require,newalias3,{gen_cfg,c}}]. +test_alias_tclocal_nested_backward_compat(_) -> + test_alias_tclocal(newalias3). + +%% test nested aliases backward compat option +test_alias_tclocal_nested_backward_compat_subvals() -> + [{require,newalias4,{gen_cfg,[c]}}]. +test_alias_tclocal_nested_backward_compat_subvals(_) -> + test_alias_tclocal(newalias4). + %% test for getting undefined variables test_get_config_undefined(_) -> undefined = ct:get_config(y1), ok. + +test_require_subvals() -> + [{require, {gen_cfg,[a,b,c]}}]. +test_require_subvals(_) -> + ok. + +test_require_subvals2() -> + [{require, {gen_cfg,[a,b,c,d]}}]. +test_require_subvals2(_) -> + ct:fail("Test should've been skipped, you shouldn't see this!"), + ok. + +test_require_deep_config() -> + [{require, {gen_cfg3, m, n}}]. +test_require_deep_config(_) -> + ok. + + +test_shadow_all(_) -> + ["n","N"] = ct:get_config({gen_cfg3,l, m, n}, [], [all]). + +test_element(_) -> + {{gen_cfg3,l, m, n},"n"} = ct:get_config({gen_cfg3,l, m, n}, [], [element]). + +test_shadow_all_element(_) -> + [{{gen_cfg3,l, m, n},"n"},{{gen_cfg3,l, m, n},"N"}] = + ct:get_config({gen_cfg3,l, m, n}, [], [all,element]). + +%% The tests below are needed to verify that things like ct:telnet can use +%% nested configs +test_internal_deep(_) -> + "n" = ct:get_config({{gen_cfg3,l,m},n}), + a_value = ct:get_config({{gen_cfg},a}), + undefined = ct:get_config({{gen_cfg3,l,m},p}). diff --git a/lib/common_test/test/ct_testspec_2_SUITE.erl b/lib/common_test/test/ct_testspec_2_SUITE.erl index 93f3520f95..681387c745 100644 --- a/lib/common_test/test/ct_testspec_2_SUITE.erl +++ b/lib/common_test/test/ct_testspec_2_SUITE.erl @@ -79,6 +79,10 @@ all() -> %% {logopts,3} %% {basic_html,2} %% {basic_html,3} +%% {verbosity,2} +%% {verbosity,3} +%% {silent_connections,2} +%% {silent_connections,3} %% {label,2} %% {label,3} %% {event_handler,2} @@ -533,6 +537,9 @@ misc_config_terms(_Config) -> {basic_html,n1@h1,false}, {basic_html,n2@h2,true}, + {silent_connections,n1@h1,all}, + {silent_connections,n2@h2,[ssh]}, + {enable_builtin_hooks,false}, {noinput,true}, @@ -571,6 +578,7 @@ misc_config_terms(_Config) -> Verify = #testspec{spec_dir = SpecDir, nodes = [{undefined,Node},{x,n1@h1},{y,n2@h2}], basic_html = [{Node,true},{n1@h1,false},{n2@h2,true}], + silent_connections = [{n1@h1,[all]},{n2@h2,[ssh]}], config = [{Node,CfgA}, {n1@h1,CfgA}, {n2@h2,CfgA}, diff --git a/lib/common_test/vsn.mk b/lib/common_test/vsn.mk index b94f7f7593..877aa775fd 100644 --- a/lib/common_test/vsn.mk +++ b/lib/common_test/vsn.mk @@ -1 +1 @@ -COMMON_TEST_VSN = 1.6.1 +COMMON_TEST_VSN = 1.6.2 diff --git a/lib/compiler/test/compile_SUITE.erl b/lib/compiler/test/compile_SUITE.erl index da53a6ba9c..2cd75944f4 100644 --- a/lib/compiler/test/compile_SUITE.erl +++ b/lib/compiler/test/compile_SUITE.erl @@ -242,6 +242,12 @@ makedep(Config) when is_list(Config) -> [makedep,{makedep_output,Target}|IncludeOptions]), ?line {ok,Mf6} = file:read_file(Target), ?line BasicMf2 = makedep_canonicalize_result(Mf6, DataDir), + %% Rule with creating phony target. + ?line PhonyMfName = SimpleRootname ++ "-phony.mk", + ?line {ok,PhonyMf} = file:read_file(PhonyMfName), + ?line {ok,_,Mf7} = compile:file(Simple, + [binary,makedep,makedep_phony|IncludeOptions]), + ?line PhonyMf = makedep_canonicalize_result(Mf7, DataDir), ?line ok = file:delete(Target), ?line ok = file:del_dir(filename:dirname(Target)), diff --git a/lib/compiler/test/compile_SUITE_data/simple-phony.mk b/lib/compiler/test/compile_SUITE_data/simple-phony.mk new file mode 100644 index 0000000000..c84bcedd2a --- /dev/null +++ b/lib/compiler/test/compile_SUITE_data/simple-phony.mk @@ -0,0 +1,3 @@ +simple.beam: $(srcdir)/simple.erl $(srcdir)/include/simple.hrl + +$(srcdir)/include/simple.hrl: diff --git a/lib/erl_interface/aclocal.m4 b/lib/erl_interface/aclocal.m4 index 339a15a2bb..a76594d86f 100644 --- a/lib/erl_interface/aclocal.m4 +++ b/lib/erl_interface/aclocal.m4 @@ -59,6 +59,7 @@ AC_ARG_VAR(erl_xcomp_isysroot, [Absolute cross system root include path (only us dnl Cross compilation variables AC_ARG_VAR(erl_xcomp_bigendian, [big endian system: yes|no (only used when cross compiling)]) +AC_ARG_VAR(erl_xcomp_double_middle_endian, [double-middle-endian system: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_clock_gettime_correction, [clock_gettime() can be used for time correction: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_nptl, [have Native POSIX Thread Library: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_usable_sigusrx, [SIGUSR1 and SIGUSR2 can be used: yes|no (only used when cross compiling)]) @@ -606,6 +607,103 @@ ifelse([$5], , , [$5 fi ]) +dnl ---------------------------------------------------------------------- +dnl +dnl AC_DOUBLE_MIDDLE_ENDIAN +dnl +dnl Checks whether doubles are represented in "middle-endian" format. +dnl Sets ac_cv_double_middle_endian={no,yes,unknown} accordingly, +dnl as well as DOUBLE_MIDDLE_ENDIAN. +dnl +dnl + +AC_DEFUN([AC_C_DOUBLE_MIDDLE_ENDIAN], +[AC_CACHE_CHECK(whether double word ordering is middle-endian, ac_cv_c_double_middle_endian, +[# It does not; compile a test program. +AC_RUN_IFELSE( +[AC_LANG_SOURCE([[#include <stdlib.h> + +int +main(void) +{ + int i = 0; + int zero = 0; + int bigendian; + int zero_index = 0; + + union + { + long int l; + char c[sizeof (long int)]; + } u; + + /* we'll use the one with 32-bit words */ + union + { + double d; + unsigned int c[2]; + } vint; + + union + { + double d; + unsigned long c[2]; + } vlong; + + union + { + double d; + unsigned short c[2]; + } vshort; + + + /* Are we little or big endian? From Harbison&Steele. */ + u.l = 1; + bigendian = (u.c[sizeof (long int) - 1] == 1); + + zero_index = bigendian ? 1 : 0; + + vint.d = 1.0; + vlong.d = 1.0; + vshort.d = 1.0; + + if (sizeof(unsigned int) == 4) + { + if (vint.c[zero_index] != 0) + zero = 1; + } + else if (sizeof(unsigned long) == 4) + { + if (vlong.c[zero_index] != 0) + zero = 1; + } + else if (sizeof(unsigned short) == 4) + { + if (vshort.c[zero_index] != 0) + zero = 1; + } + + exit (zero); +} +]])], + [ac_cv_c_double_middle_endian=no], + [ac_cv_c_double_middle_endian=yes], + [ac_cv_c_double_middle=unknown])]) +case $ac_cv_c_double_middle_endian in + yes) + m4_default([$1], + [AC_DEFINE([DOUBLE_MIDDLE_ENDIAN], 1, + [Define to 1 if your processor stores the words in a double in + middle-endian format (like some ARMs).])]) ;; + no) + $2 ;; + *) + m4_default([$3], + [AC_MSG_WARN([unknown double endianness +presetting ac_cv_c_double_middle_endian=no (or yes) will help])]) ;; +esac +])# AC_C_DOUBLE_MIDDLE_ENDIAN + dnl ---------------------------------------------------------------------- dnl @@ -1337,6 +1435,14 @@ if test "$ac_cv_c_bigendian" = "yes"; then AC_DEFINE(ETHR_BIGENDIAN, 1, [Define if bigendian]) fi +case X$erl_xcomp_double_middle_endian in + X) ;; + Xyes|Xno|Xunknown) ac_cv_c_double_middle_endian=$erl_xcomp_double_middle_endian;; + *) AC_MSG_ERROR([Bad erl_xcomp_double_middle_endian value: $erl_xcomp_double_middle_endian]);; +esac + +AC_C_DOUBLE_MIDDLE_ENDIAN + AC_ARG_ENABLE(native-ethr-impls, AS_HELP_STRING([--disable-native-ethr-impls], [disable native ethread implementations]), diff --git a/lib/kernel/src/inet.erl b/lib/kernel/src/inet.erl index 0bb5444dbb..1a03424f88 100644 --- a/lib/kernel/src/inet.erl +++ b/lib/kernel/src/inet.erl @@ -763,8 +763,12 @@ sctp_opt([Opt|Opts], Mod, R, As) -> {Name,Val} -> sctp_opt (Opts, Mod, R, As, Name, Val); _ -> {error,badarg} end; -sctp_opt([], _Mod, R, _SockOpts) -> - {ok, R}. +sctp_opt([], _Mod, #sctp_opts{ifaddr=IfAddr}=R, _SockOpts) -> + if is_list(IfAddr) -> + {ok, R#sctp_opts{ifaddr=lists:reverse(IfAddr)}}; + true -> + {ok, R} + end. sctp_opt(Opts, Mod, R, As, Name, Val) -> case add_opt(Name, Val, R#sctp_opts.opts, As) of @@ -1015,11 +1019,7 @@ open(Fd, Addr, Port, Opts, Protocol, Family, Type, Module) when Fd < 0 -> case prim_inet:setopts(S, Opts) of ok -> case if is_list(Addr) -> - prim_inet:bind(S, add, - [case A of - {_,_} -> A; - _ -> {A,Port} - end || A <- Addr]); + bindx(S, Addr, Port); true -> prim_inet:bind(S, Addr, Port) end of @@ -1040,6 +1040,34 @@ open(Fd, Addr, Port, Opts, Protocol, Family, Type, Module) when Fd < 0 -> open(Fd, _Addr, _Port, Opts, Protocol, Family, Type, Module) -> fdopen(Fd, Opts, Protocol, Family, Type, Module). +bindx(S, [Addr], Port0) -> + {IP, Port} = set_bindx_port(Addr, Port0), + prim_inet:bind(S, IP, Port); +bindx(S, Addrs, Port0) -> + [{IP, Port} | Rest] = [set_bindx_port(Addr, Port0) || Addr <- Addrs], + case prim_inet:bind(S, IP, Port) of + {ok, AssignedPort} when Port =:= 0 -> + %% On newer Linux kernels, Solaris and FreeBSD, calling + %% bindx with port 0 is ok, but on SuSE 10, it results in einval + Rest2 = [change_bindx_0_port(Addr, AssignedPort) || Addr <- Rest], + prim_inet:bind(S, add, Rest2); + {ok, _} -> + prim_inet:bind(S, add, Rest); + Error -> + Error + end. + +set_bindx_port({_IP, _Port}=Addr, _OtherPort) -> + Addr; +set_bindx_port(IP, Port) -> + {IP, Port}. + +change_bindx_0_port({IP, 0}, AssignedPort) -> + {IP, AssignedPort}; +change_bindx_0_port({_IP, _Port}=Addr, _AssignedPort) -> + Addr. + + -spec fdopen(Fd :: non_neg_integer(), Opts :: [socket_setopt()], Protocol :: socket_protocol(), diff --git a/lib/kernel/test/gen_sctp_SUITE.erl b/lib/kernel/test/gen_sctp_SUITE.erl index 8f490b6643..f4bf6e719e 100644 --- a/lib/kernel/test/gen_sctp_SUITE.erl +++ b/lib/kernel/test/gen_sctp_SUITE.erl @@ -31,14 +31,22 @@ [basic/1, api_open_close/1,api_listen/1,api_connect_init/1,api_opts/1, xfer_min/1,xfer_active/1,def_sndrcvinfo/1,implicit_inet6/1, - basic_stream/1, xfer_stream_min/1, peeloff/1, buffers/1]). + basic_stream/1, xfer_stream_min/1, peeloff/1, buffers/1, + open_multihoming_ipv4_socket/1, + open_unihoming_ipv6_socket/1, + open_multihoming_ipv6_socket/1, + open_multihoming_ipv4_and_ipv6_socket/1]). suite() -> [{ct_hooks,[ts_install_cth]}]. all() -> [basic, api_open_close, api_listen, api_connect_init, api_opts, xfer_min, xfer_active, def_sndrcvinfo, implicit_inet6, - basic_stream, xfer_stream_min, peeloff, buffers]. + basic_stream, xfer_stream_min, peeloff, buffers, + open_multihoming_ipv4_socket, + open_unihoming_ipv6_socket, + open_multihoming_ipv6_socket, + open_multihoming_ipv4_and_ipv6_socket]. groups() -> []. @@ -1105,6 +1113,192 @@ mk_data(N, Bytes, Bin) when N < Bytes -> mk_data(_, _, Bin) -> Bin. + + +open_multihoming_ipv4_socket(doc) -> + "Test opening a multihoming ipv4 socket"; +open_multihoming_ipv4_socket(suite) -> + []; +open_multihoming_ipv4_socket(Config) when is_list(Config) -> + ?line case get_addrs_by_family(inet, 2) of + {ok, [Addr1, Addr2]} -> + ?line do_open_and_connect([Addr1, Addr2], Addr1); + {error, Reason} -> + {skip, Reason} + end. + +open_unihoming_ipv6_socket(doc) -> + %% This test is mostly aimed to indicate + %% whether host has a non-working ipv6 setup + "Test opening a unihoming (non-multihoming) ipv6 socket"; +open_unihoming_ipv6_socket(suite) -> + []; +open_unihoming_ipv6_socket(Config) when is_list(Config) -> + ?line case get_addrs_by_family(inet6, 1) of + {ok, [Addr]} -> + ?line do_open_and_connect([Addr], Addr); + {error, Reason} -> + {skip, Reason} + end. + + +open_multihoming_ipv6_socket(doc) -> + "Test opening a multihoming ipv6 socket"; +open_multihoming_ipv6_socket(suite) -> + []; +open_multihoming_ipv6_socket(Config) when is_list(Config) -> + ?line case get_addrs_by_family(inet6, 2) of + {ok, [Addr1, Addr2]} -> + ?line do_open_and_connect([Addr1, Addr2], Addr1); + {error, Reason} -> + {skip, Reason} + end. + +open_multihoming_ipv4_and_ipv6_socket(doc) -> + "Test opening a multihoming ipv6 socket with ipv4 and ipv6 addresses"; +open_multihoming_ipv4_and_ipv6_socket(suite) -> + []; +open_multihoming_ipv4_and_ipv6_socket(Config) when is_list(Config) -> + ?line case get_addrs_by_family(inet_and_inet6, 2) of + {ok, [[InetAddr1, InetAddr2], [Inet6Addr1, Inet6Addr2]]} -> + %% Connect to the first address to test bind + ?line do_open_and_connect([InetAddr1, Inet6Addr1, InetAddr2], + InetAddr1), + ?line do_open_and_connect([Inet6Addr1, InetAddr1], + Inet6Addr1), + + %% Connect an address, not the first, + %% to test sctp_bindx + ?line do_open_and_connect([Inet6Addr1, Inet6Addr2, InetAddr1], + Inet6Addr2), + ?line do_open_and_connect([Inet6Addr1, Inet6Addr2, InetAddr1], + InetAddr1); + {error, Reason} -> + {skip, Reason} + end. + + +get_addrs_by_family(Family, NumAddrs) -> + case os:type() of + {unix,linux} -> + get_addrs_by_family_aux(Family, NumAddrs); + {unix,freebsd} -> + get_addrs_by_family_aux(Family, NumAddrs); + {unix,sunos} -> + case get_addrs_by_family_aux(Family, NumAddrs) of + {ok, [InetAddrs, Inet6Addrs]} when Family =:= inet_and_inet6 -> + %% Man page for sctp_bindx on Solaris says: "If sock is an + %% Internet Protocol Version 6 (IPv6) socket, addrs should + %% be an array of sockaddr_in6 structures containing IPv6 + %% or IPv4-mapped IPv6 addresses." + {ok, [ipv4_map_addrs(InetAddrs), Inet6Addrs]}; + {ok, Addrs} -> + {ok, Addrs}; + {error, Reason} -> + {error, Reason} + end; + Os -> + Reason = if Family =:= inet_and_inet6 -> + f("Mixing ipv4 and ipv6 addresses for multihoming " + " has not been verified on ~p", [Os]); + true -> + f("Multihoming for ~p has not been verified on ~p", + [Family, Os]) + end, + {error, Reason} + end. + +get_addrs_by_family_aux(Family, NumAddrs) when Family =:= inet; + Family =:= inet6 -> + ?line + case inet:getaddr(localhost, Family) of + {error,eafnosupport} -> + {skip, f("No support for ~p", Family)}; + {ok, _} -> + ?line IfAddrs = ok(inet:getifaddrs()), + ?line case filter_addrs_by_family(IfAddrs, Family) of + Addrs when length(Addrs) >= NumAddrs -> + {ok, lists:sublist(Addrs, NumAddrs)}; + [] -> + {error, f("Need ~p ~p address(es) found none~n", + [NumAddrs, Family])}; + Addrs -> + {error, + f("Need ~p ~p address(es) found only ~p: ~p~n", + [NumAddrs, Family, length(Addrs), Addrs])} + end + end; +get_addrs_by_family_aux(inet_and_inet6, NumAddrs) -> + ?line catch {ok, [case get_addrs_by_family_aux(Family, NumAddrs) of + {ok, Addrs} -> Addrs; + {error, Reason} -> throw({error, Reason}) + end || Family <- [inet, inet6]]}. + +filter_addrs_by_family(IfAddrs, Family) -> + lists:flatten([[Addr || {addr, Addr} <- Info, + is_good_addr(Addr, Family)] + || {_IfName, Info} <- IfAddrs]). + +is_good_addr(Addr, inet) when tuple_size(Addr) =:= 4 -> + true; +is_good_addr({0,0,0,0,0,16#ffff,_,_}, inet6) -> + false; %% ipv4 mapped +is_good_addr({16#fe80,_,_,_,_,_,_,_}, inet6) -> + false; %% link-local +is_good_addr(Addr, inet6) when tuple_size(Addr) =:= 8 -> + true; +is_good_addr(_Addr, _Family) -> + false. + +ipv4_map_addrs(InetAddrs) -> + [begin + <<AB:16>> = <<A,B>>, + <<CD:16>> = <<C,D>>, + {0, 0, 0, 0, 0, 16#ffff, AB, CD} + end || {A,B,C,D} <- InetAddrs]. + +f(F, A) -> + lists:flatten(io_lib:format(F, A)). + +do_open_and_connect(ServerAddresses, AddressToConnectTo) -> + ?line ServerFamily = get_family_by_addrs(ServerAddresses), + ?line io:format("Serving ~p addresses: ~p~n", + [ServerFamily, ServerAddresses]), + ?line S1 = ok(gen_sctp:open(0, [{ip,Addr} || Addr <- ServerAddresses] ++ + [ServerFamily])), + ?line ok = gen_sctp:listen(S1, true), + ?line P1 = ok(inet:port(S1)), + ?line ClientFamily = get_family_by_addr(AddressToConnectTo), + ?line io:format("Connecting to ~p ~p~n", + [ClientFamily, AddressToConnectTo]), + ?line S2 = ok(gen_sctp:open(0, [ClientFamily])), + %% Verify client can connect + ?line #sctp_assoc_change{state=comm_up} = + ok(gen_sctp:connect(S2, AddressToConnectTo, P1, [])), + %% verify server side also receives comm_up from client + ?line recv_comm_up_eventually(S1), + ?line ok = gen_sctp:close(S2), + ?line ok = gen_sctp:close(S1). + +%% If at least one of the addresses is an ipv6 address, return inet6, else inet. +get_family_by_addrs(Addresses) -> + ?line case lists:usort([get_family_by_addr(Addr) || Addr <- Addresses]) of + [inet, inet6] -> inet6; + [inet] -> inet; + [inet6] -> inet6 + end. + +get_family_by_addr(Addr) when tuple_size(Addr) =:= 4 -> inet; +get_family_by_addr(Addr) when tuple_size(Addr) =:= 8 -> inet6. + +recv_comm_up_eventually(S) -> + ?line case ok(gen_sctp:recv(S)) of + {_Addr, _Port, _Info, #sctp_assoc_change{state=comm_up}} -> + ok; + {_Addr, _Port, _Info, _OtherSctpMsg} -> + ?line recv_comm_up_eventually(S) + end. + %%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%% socket gen_server ultra light diff --git a/lib/mnesia/src/mnesia.appup.src b/lib/mnesia/src/mnesia.appup.src index 304a15242f..355aafb215 100644 --- a/lib/mnesia/src/mnesia.appup.src +++ b/lib/mnesia/src/mnesia.appup.src @@ -1,6 +1,9 @@ %% -*- erlang -*- {"%VSN%", [ + {"4.7.1", [{restart_application, mnesia}]}, + {"4.7", [{restart_application, mnesia}]}, + {"4.6", [{restart_application, mnesia}]}, {"4.5.1", [{restart_application, mnesia}]}, {"4.5", [{restart_application, mnesia}]}, {"4.4.19", [{restart_application, mnesia}]}, @@ -9,6 +12,9 @@ {"4.4.16", [{restart_application, mnesia}]} ], [ + {"4.7.1", [{restart_application, mnesia}]}, + {"4.7", [{restart_application, mnesia}]}, + {"4.6", [{restart_application, mnesia}]}, {"4.5.1", [{restart_application, mnesia}]}, {"4.5", [{restart_application, mnesia}]}, {"4.4.19", [{restart_application, mnesia}]}, diff --git a/lib/mnesia/src/mnesia_index.erl b/lib/mnesia/src/mnesia_index.erl index 61210d7e55..37989a1958 100644 --- a/lib/mnesia/src/mnesia_index.erl +++ b/lib/mnesia/src/mnesia_index.erl @@ -120,9 +120,9 @@ del_object_bag(Tab, Key, Obj, Pos, Ixt, undefined) -> IxKey = element(Pos, Obj), Old = [X || X <- mnesia_lib:db_get(Tab, Key), element(Pos, X) =:= IxKey], del_object_bag(Tab, Key, Obj, Pos, Ixt, Old); -%% If Tab type is bag we need remove index identifier if Tab -%% contains less than 2 elements. -del_object_bag(_Tab, Key, Obj, Pos, Ixt, Old) when length(Old) < 2 -> +%% If Tab type is bag we need remove index identifier if the object being +%% deleted was the last one +del_object_bag(_Tab, Key, Obj, Pos, Ixt, Old) when Old =:= [Obj] -> del_ixes(Ixt, [Obj], Pos, Key); del_object_bag(_Tab, _Key, _Obj, _Pos, _Ixt, _Old) -> ok. diff --git a/lib/mnesia/test/mnesia_dirty_access_test.erl b/lib/mnesia/test/mnesia_dirty_access_test.erl index abbdab48c0..a57adefbac 100644 --- a/lib/mnesia/test/mnesia_dirty_access_test.erl +++ b/lib/mnesia/test/mnesia_dirty_access_test.erl @@ -527,6 +527,9 @@ dirty_index_update_bag(Config, Storage) -> ?match(ok, mnesia:dirty_write(Rec1)), ?match([Rec1], mnesia:dirty_index_read(Tab, 2, ValPos)), + ?match(ok, mnesia:dirty_delete_object(Rec5)), + ?match([Rec1], mnesia:dirty_index_read(Tab, 2, ValPos)), + ?match({atomic, ok}, mnesia:transaction(fun() -> mnesia:write(Rec2) end)), R1 = mnesia:dirty_index_read(Tab, 2, ValPos), ?match([Rec1, Rec2], lists:sort(R1)), diff --git a/lib/mnesia/test/mnesia_trans_access_test.erl b/lib/mnesia/test/mnesia_trans_access_test.erl index c040d0ca3f..73c3fe0362 100644 --- a/lib/mnesia/test/mnesia_trans_access_test.erl +++ b/lib/mnesia/test/mnesia_trans_access_test.erl @@ -896,6 +896,10 @@ index_update_bag(Config)when is_list(Config) -> ?match({atomic, [Rec1]}, mnesia:transaction(fun() -> mnesia:index_read(Tab, 2, ValPos) end)), + ?match({atomic, ok}, mnesia:transaction(fun() -> mnesia:delete_object(Rec5) end)), + ?match({atomic, [Rec1]}, + mnesia:transaction(fun() -> mnesia:index_read(Tab, 2, ValPos) end)), + ?match({atomic, ok}, mnesia:transaction(fun() -> mnesia:write(Rec2) end)), {atomic, R1} = mnesia:transaction(fun() -> mnesia:index_read(Tab, 2, ValPos) end), diff --git a/lib/observer/src/observer.app.src b/lib/observer/src/observer.app.src index 5c65ea5c8f..d3aaf351dd 100644 --- a/lib/observer/src/observer.app.src +++ b/lib/observer/src/observer.app.src @@ -25,6 +25,18 @@ etop_gui, etop_tr, etop_txt, + observer, + observer_app_wx, + observer_lib, + observer_perf_wx, + observer_pro_wx, + observer_procinfo, + observer_sys_wx, + observer_trace_wx, + observer_traceoptions_wx, + observer_tv_table, + observer_tv_wx, + observer_wx, ttb, ttb_et]}, {registered, []}, diff --git a/lib/observer/src/observer_tv_table.erl b/lib/observer/src/observer_tv_table.erl index 8fdcbf331c..8eeffb7f91 100644 --- a/lib/observer/src/observer_tv_table.erl +++ b/lib/observer/src/observer_tv_table.erl @@ -324,7 +324,7 @@ handle_event(#wx{id=?SEARCH_ENTRY, event=#wxCommand{type=command_text_enter,cmdS wxStatusBar:setStatusText(SB, "Not found"), Pid ! {mark_search_hit, Find#find.start}, wxListCtrl:refreshItem(Grid, Find#find.start), - {noreply, State#state{search=Search#search{find=#find{found=false}}}}; + {noreply, State#state{search=Search#search{find=Find#find{found=false}}}}; Row -> wxListCtrl:ensureVisible(Grid, Row), wxListCtrl:refreshItem(Grid, Row), @@ -616,7 +616,7 @@ search([Str, Row, Dir0, CaseSens], search(Row, Dir, Re, Table) -> Res = try lists:nth(Row+1, Table) of - Term -> + [Term|_] -> Str = format(Term), re:run(Str, Re) catch _:_ -> no_more @@ -772,7 +772,7 @@ format_tuple(_Tuple, 1, 0) -> format_list([]) -> "[]"; format_list(List) -> case printable_list(List) of - true -> io_lib:format("\"~ts\"", [List]); + true -> io_lib:format("\"~ts\"", [map_printable_list(List)]); false -> [$[ | make_list(List)] end. @@ -781,6 +781,24 @@ make_list([Last]) -> make_list([Head|Tail]) -> [format(Head), $,|make_list(Tail)]. +map_printable_list([$\n|Cs]) -> + [$\\, $n|map_printable_list(Cs)]; +map_printable_list([$\r|Cs]) -> + [$\\, $r|map_printable_list(Cs)]; +map_printable_list([$\t|Cs]) -> + [$\\, $t|map_printable_list(Cs)]; +map_printable_list([$\v|Cs]) -> + [$\\, $v|map_printable_list(Cs)]; +map_printable_list([$\b|Cs]) -> + [$\\, $b|map_printable_list(Cs)]; +map_printable_list([$\f|Cs]) -> + [$\\, $f|map_printable_list(Cs)]; +map_printable_list([$\e|Cs]) -> + [$\\, $e|map_printable_list(Cs)]; +map_printable_list([]) -> []; +map_printable_list([C|Cs]) -> + [C|map_printable_list(Cs)]. + %% printable_list([Char]) -> bool() %% Return true if CharList is a list of printable characters, else %% false. diff --git a/lib/odbc/aclocal.m4 b/lib/odbc/aclocal.m4 index 339a15a2bb..a76594d86f 100644 --- a/lib/odbc/aclocal.m4 +++ b/lib/odbc/aclocal.m4 @@ -59,6 +59,7 @@ AC_ARG_VAR(erl_xcomp_isysroot, [Absolute cross system root include path (only us dnl Cross compilation variables AC_ARG_VAR(erl_xcomp_bigendian, [big endian system: yes|no (only used when cross compiling)]) +AC_ARG_VAR(erl_xcomp_double_middle_endian, [double-middle-endian system: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_clock_gettime_correction, [clock_gettime() can be used for time correction: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_nptl, [have Native POSIX Thread Library: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_usable_sigusrx, [SIGUSR1 and SIGUSR2 can be used: yes|no (only used when cross compiling)]) @@ -606,6 +607,103 @@ ifelse([$5], , , [$5 fi ]) +dnl ---------------------------------------------------------------------- +dnl +dnl AC_DOUBLE_MIDDLE_ENDIAN +dnl +dnl Checks whether doubles are represented in "middle-endian" format. +dnl Sets ac_cv_double_middle_endian={no,yes,unknown} accordingly, +dnl as well as DOUBLE_MIDDLE_ENDIAN. +dnl +dnl + +AC_DEFUN([AC_C_DOUBLE_MIDDLE_ENDIAN], +[AC_CACHE_CHECK(whether double word ordering is middle-endian, ac_cv_c_double_middle_endian, +[# It does not; compile a test program. +AC_RUN_IFELSE( +[AC_LANG_SOURCE([[#include <stdlib.h> + +int +main(void) +{ + int i = 0; + int zero = 0; + int bigendian; + int zero_index = 0; + + union + { + long int l; + char c[sizeof (long int)]; + } u; + + /* we'll use the one with 32-bit words */ + union + { + double d; + unsigned int c[2]; + } vint; + + union + { + double d; + unsigned long c[2]; + } vlong; + + union + { + double d; + unsigned short c[2]; + } vshort; + + + /* Are we little or big endian? From Harbison&Steele. */ + u.l = 1; + bigendian = (u.c[sizeof (long int) - 1] == 1); + + zero_index = bigendian ? 1 : 0; + + vint.d = 1.0; + vlong.d = 1.0; + vshort.d = 1.0; + + if (sizeof(unsigned int) == 4) + { + if (vint.c[zero_index] != 0) + zero = 1; + } + else if (sizeof(unsigned long) == 4) + { + if (vlong.c[zero_index] != 0) + zero = 1; + } + else if (sizeof(unsigned short) == 4) + { + if (vshort.c[zero_index] != 0) + zero = 1; + } + + exit (zero); +} +]])], + [ac_cv_c_double_middle_endian=no], + [ac_cv_c_double_middle_endian=yes], + [ac_cv_c_double_middle=unknown])]) +case $ac_cv_c_double_middle_endian in + yes) + m4_default([$1], + [AC_DEFINE([DOUBLE_MIDDLE_ENDIAN], 1, + [Define to 1 if your processor stores the words in a double in + middle-endian format (like some ARMs).])]) ;; + no) + $2 ;; + *) + m4_default([$3], + [AC_MSG_WARN([unknown double endianness +presetting ac_cv_c_double_middle_endian=no (or yes) will help])]) ;; +esac +])# AC_C_DOUBLE_MIDDLE_ENDIAN + dnl ---------------------------------------------------------------------- dnl @@ -1337,6 +1435,14 @@ if test "$ac_cv_c_bigendian" = "yes"; then AC_DEFINE(ETHR_BIGENDIAN, 1, [Define if bigendian]) fi +case X$erl_xcomp_double_middle_endian in + X) ;; + Xyes|Xno|Xunknown) ac_cv_c_double_middle_endian=$erl_xcomp_double_middle_endian;; + *) AC_MSG_ERROR([Bad erl_xcomp_double_middle_endian value: $erl_xcomp_double_middle_endian]);; +esac + +AC_C_DOUBLE_MIDDLE_ENDIAN + AC_ARG_ENABLE(native-ethr-impls, AS_HELP_STRING([--disable-native-ethr-impls], [disable native ethread implementations]), diff --git a/lib/public_key/asn1/OTP-PKIX.asn1 b/lib/public_key/asn1/OTP-PKIX.asn1 index fbf531df40..e94a77a3e7 100644 --- a/lib/public_key/asn1/OTP-PKIX.asn1 +++ b/lib/public_key/asn1/OTP-PKIX.asn1 @@ -225,7 +225,17 @@ dnQualifier ATTRIBUTE-TYPE-AND-VALUE-CLASS ::= { countryName ATTRIBUTE-TYPE-AND-VALUE-CLASS ::= { ID id-at-countryName - TYPE X520countryName } + TYPE X520countryName } -- this is currently not used when decoding + -- The decoding and mapping between ID and Type is done in the code + -- in module publickey_cert_records via the function attribute_type + -- To be more forgiving and compatible with other SSL implementations + -- regarding how to handle and sometimes accept incorrect certificates + -- we define and use the type below instead of X520countryName + + OTP-X520countryname ::= CHOICE { + printableString PrintableString (SIZE (2)), + utf8String UTF8String (SIZE (2)) +} serialNumber ATTRIBUTE-TYPE-AND-VALUE-CLASS ::= { ID id-at-serialNumber diff --git a/lib/public_key/src/pubkey_cert_records.erl b/lib/public_key/src/pubkey_cert_records.erl index b86d7a1f0c..33fe940ea2 100644 --- a/lib/public_key/src/pubkey_cert_records.erl +++ b/lib/public_key/src/pubkey_cert_records.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2008-2011. All Rights Reserved. +%% Copyright Ericsson AB 2008-2012. All Rights Reserved. %% %% The contents of this file are subject to the Erlang Public License, %% Version 1.1, (the "License"); you may not use this file except in @@ -57,6 +57,15 @@ transform(#'OTPTBSCertificate'{}= TBS, decode) -> transform(#'AttributeTypeAndValue'{type=Id,value=Value0} = ATAV, Func) -> {ok, Value} = case attribute_type(Id) of + 'X520countryName'when Func == decode -> + %% Workaround that some certificates break the ASN-1 spec + %% and encode countryname as utf8 + case 'OTP-PUB-KEY':Func('OTP-X520countryname', Value0) of + {ok, {utf8String, Utf8Value}} -> + {ok, unicode:characters_to_list(Utf8Value)}; + {ok, {printableString, ASCCI}} -> + {ok, ASCCI} + end; Type when is_atom(Type) -> 'OTP-PUB-KEY':Func(Type, Value0); _UnknownType -> {ok, Value0} end, diff --git a/lib/public_key/test/public_key_SUITE.erl b/lib/public_key/test/public_key_SUITE.erl index a91dcfa029..6a879867e1 100644 --- a/lib/public_key/test/public_key_SUITE.erl +++ b/lib/public_key/test/public_key_SUITE.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2008-2011. All Rights Reserved. +%% Copyright Ericsson AB 2008-2012. All Rights Reserved. %% %% The contents of this file are subject to the Erlang Public License, %% Version 1.1, (the "License"); you may not use this file except in @@ -107,7 +107,7 @@ all() -> {group, ssh_public_key_decode_encode}, encrypt_decrypt, {group, sign_verify}, - pkix, pkix_path_validation]. + pkix, pkix_countryname, pkix_path_validation]. groups() -> [{pem_decode_encode, [], [dsa_pem, rsa_pem, encrypted_pem, @@ -626,6 +626,34 @@ pkix(Config) when is_list(Config) -> VerifyStr = public_key:pkix_normalize_name(TestStr), ok. + +%%-------------------------------------------------------------------- +pkix_countryname(doc) -> + "Test workaround for certs that code x509countryname as utf8"; +pkix_countryname(suite) -> + []; +pkix_countryname(Config) when is_list(Config) -> + Cert = incorrect_pkix_cert(), + OTPCert = public_key:pkix_decode_cert(Cert, otp), + TBSCert = OTPCert#'OTPCertificate'.tbsCertificate, + Issuer = TBSCert#'OTPTBSCertificate'.issuer, + Subj = TBSCert#'OTPTBSCertificate'.subject, + check_countryname(Issuer), + check_countryname(Subj). + +check_countryname({rdnSequence,DirName}) -> + do_check_countryname(DirName). +do_check_countryname([]) -> + ok; +do_check_countryname([#'AttributeTypeAndValue'{type = ?'id-at-countryName', + value = "US"}|_]) -> + ok; +do_check_countryname([#'AttributeTypeAndValue'{type = ?'id-at-countryName', + value = Value}|_]) -> + test_server:fail({incorrect_cuntry_name, Value}); +do_check_countryname([_| Rest]) -> + do_check_countryname(Rest). + %%-------------------------------------------------------------------- pkix_path_validation(doc) -> "Misc pkix tests not covered elsewhere"; @@ -716,3 +744,6 @@ check_entry_type(_,_) -> strip_ending_newlines(Bin) -> string:strip(binary_to_list(Bin), right, 10). + +incorrect_pkix_cert() -> + <<48,130,5,186,48,130,4,162,160,3,2,1,2,2,7,7,250,61,63,6,140,137,48,13,6,9,42, 134,72,134,247,13,1,1,5,5,0,48,129,220,49,11,48,9,6,3,85,4,6,19,2,85,83,49, 16,48,14,6,3,85,4,8,19,7,65,114,105,122,111,110,97,49,19,48,17,6,3,85,4,7,19, 10,83,99,111,116,116,115,100,97,108,101,49,37,48,35,6,3,85,4,10,19,28,83,116, 97,114,102,105,101,108,100,32,84,101,99,104,110,111,108,111,103,105,101,115, 44,32,73,110,99,46,49,57,48,55,6,3,85,4,11,19,48,104,116,116,112,58,47,47,99, 101,114,116,105,102,105,99,97,116,101,115,46,115,116,97,114,102,105,101,108, 100,116,101,99,104,46,99,111,109,47,114,101,112,111,115,105,116,111,114,121, 49,49,48,47,6,3,85,4,3,19,40,83,116,97,114,102,105,101,108,100,32,83,101,99, 117,114,101,32,67,101,114,116,105,102,105,99,97,116,105,111,110,32,65,117, 116,104,111,114,105,116,121,49,17,48,15,6,3,85,4,5,19,8,49,48,54,56,56,52,51, 53,48,30,23,13,49,48,49,48,50,51,48,49,51,50,48,53,90,23,13,49,50,49,48,50, 51,48,49,51,50,48,53,90,48,122,49,11,48,9,6,3,85,4,6,12,2,85,83,49,11,48,9,6, 3,85,4,8,12,2,65,90,49,19,48,17,6,3,85,4,7,12,10,83,99,111,116,116,115,100, 97,108,101,49,38,48,36,6,3,85,4,10,12,29,83,112,101,99,105,97,108,32,68,111, 109,97,105,110,32,83,101,114,118,105,99,101,115,44,32,73,110,99,46,49,33,48, 31,6,3,85,4,3,12,24,42,46,108,111,103,105,110,46,115,101,99,117,114,101,115, 101,114,118,101,114,46,110,101,116,48,130,1,34,48,13,6,9,42,134,72,134,247, 13,1,1,1,5,0,3,130,1,15,0,48,130,1,10,2,130,1,1,0,185,136,240,80,141,36,124, 245,182,130,73,19,188,74,166,117,72,228,185,209,43,129,244,40,44,193,231,11, 209,12,234,88,43,142,1,162,48,122,17,95,230,105,171,131,12,147,46,204,36,80, 250,171,33,253,35,62,83,22,71,212,186,141,14,198,89,89,121,204,224,122,246, 127,110,188,229,162,67,95,6,74,231,127,99,131,7,240,85,102,203,251,50,58,58, 104,245,103,181,183,134,32,203,121,232,54,32,188,139,136,112,166,126,14,91, 223,153,172,164,14,61,38,163,208,215,186,210,136,213,143,70,147,173,109,217, 250,169,108,31,211,104,238,103,93,182,59,165,43,196,189,218,241,30,148,240, 109,90,69,176,194,52,116,173,151,135,239,10,209,179,129,192,102,75,11,25,168, 223,32,174,84,223,134,70,167,55,172,143,27,130,123,226,226,7,34,142,166,39, 48,246,96,231,150,84,220,106,133,193,55,95,159,227,24,249,64,36,1,142,171,16, 202,55,126,7,156,15,194,22,116,53,113,174,104,239,203,120,45,131,57,87,84, 163,184,27,83,57,199,91,200,34,43,98,61,180,144,76,65,170,177,2,3,1,0,1,163, 130,1,224,48,130,1,220,48,15,6,3,85,29,19,1,1,255,4,5,48,3,1,1,0,48,29,6,3, 85,29,37,4,22,48,20,6,8,43,6,1,5,5,7,3,1,6,8,43,6,1,5,5,7,3,2,48,14,6,3,85, 29,15,1,1,255,4,4,3,2,5,160,48,56,6,3,85,29,31,4,49,48,47,48,45,160,43,160, 41,134,39,104,116,116,112,58,47,47,99,114,108,46,115,116,97,114,102,105,101, 108,100,116,101,99,104,46,99,111,109,47,115,102,115,50,45,48,46,99,114,108, 48,83,6,3,85,29,32,4,76,48,74,48,72,6,11,96,134,72,1,134,253,110,1,7,23,2,48, 57,48,55,6,8,43,6,1,5,5,7,2,1,22,43,104,116,116,112,115,58,47,47,99,101,114, 116,115,46,115,116,97,114,102,105,101,108,100,116,101,99,104,46,99,111,109, 47,114,101,112,111,115,105,116,111,114,121,47,48,129,141,6,8,43,6,1,5,5,7,1, 1,4,129,128,48,126,48,42,6,8,43,6,1,5,5,7,48,1,134,30,104,116,116,112,58,47, 47,111,99,115,112,46,115,116,97,114,102,105,101,108,100,116,101,99,104,46,99, 111,109,47,48,80,6,8,43,6,1,5,5,7,48,2,134,68,104,116,116,112,58,47,47,99, 101,114,116,105,102,105,99,97,116,101,115,46,115,116,97,114,102,105,101,108, 100,116,101,99,104,46,99,111,109,47,114,101,112,111,115,105,116,111,114,121, 47,115,102,95,105,110,116,101,114,109,101,100,105,97,116,101,46,99,114,116, 48,31,6,3,85,29,35,4,24,48,22,128,20,73,75,82,39,209,27,188,242,161,33,106, 98,123,81,66,122,138,215,213,86,48,59,6,3,85,29,17,4,52,48,50,130,24,42,46, 108,111,103,105,110,46,115,101,99,117,114,101,115,101,114,118,101,114,46,110, 101,116,130,22,108,111,103,105,110,46,115,101,99,117,114,101,115,101,114,118, 101,114,46,110,101,116,48,29,6,3,85,29,14,4,22,4,20,138,233,191,208,157,203, 249,85,242,239,20,195,48,10,148,49,144,101,255,116,48,13,6,9,42,134,72,134, 247,13,1,1,5,5,0,3,130,1,1,0,82,31,121,162,49,50,143,26,167,202,143,61,71, 189,201,199,57,81,122,116,90,192,88,24,102,194,174,48,157,74,27,87,210,223, 253,93,3,91,150,109,120,1,110,27,11,200,198,141,222,246,14,200,71,105,41,138, 13,114,122,106,63,17,197,181,234,121,61,89,74,65,41,231,248,219,129,83,176, 219,55,107,55,211,112,98,38,49,69,77,96,221,108,123,152,12,210,159,157,141, 43,226,55,187,129,3,82,49,136,66,81,196,91,234,196,10,82,48,6,80,163,83,71, 127,102,177,93,209,129,26,104,2,84,24,255,248,161,3,244,169,234,92,122,110, 43,4,17,113,185,235,108,219,210,236,132,216,177,227,17,169,58,162,159,182, 162,93,160,229,200,9,163,229,110,121,240,168,232,14,91,214,188,196,109,210, 164,222,0,109,139,132,113,91,16,118,173,178,176,80,132,34,41,199,51,206,250, 224,132,60,115,192,94,107,163,219,212,226,225,65,169,148,108,213,46,174,173, 103,110,189,229,166,149,254,31,51,44,144,108,187,182,11,251,201,206,86,138, 208,59,51,86,132,235,81,225,88,34,190,8,184>>. diff --git a/lib/ssh/test/ssh_basic_SUITE.erl b/lib/ssh/test/ssh_basic_SUITE.erl index c5019425cd..2ceaa9daa5 100644 --- a/lib/ssh/test/ssh_basic_SUITE.erl +++ b/lib/ssh/test/ssh_basic_SUITE.erl @@ -194,10 +194,10 @@ misc_ssh_options(Config) when is_list(Config) -> SystemDir = filename:join(?config(priv_dir, Config), system), UserDir = ?config(priv_dir, Config), - CMiscOpt0 = [{connecect_timeout, 1000}, {ip_v6_disable, false}, {user_dir, UserDir}], - CMiscOpt1 = [{connecect_timeout, infinity}, {ip_v6_disable, true}, {user_dir, UserDir}], - SMiscOpt0 = [{ip_v6_disable, false}, {user_dir, UserDir}, {system_dir, SystemDir}], - SMiscOpt1 = [{ip_v6_disable, true}, {user_dir, UserDir}, {system_dir, SystemDir}], + CMiscOpt0 = [{connecect_timeout, 1000}, {ip_v6_disabled, false}, {user_dir, UserDir}], + CMiscOpt1 = [{connecect_timeout, infinity}, {ip_v6_disabled, true}, {user_dir, UserDir}], + SMiscOpt0 = [{ip_v6_disabled, false}, {user_dir, UserDir}, {system_dir, SystemDir}], + SMiscOpt1 = [{ip_v6_disabled, true}, {user_dir, UserDir}, {system_dir, SystemDir}], ClientOpts = ?config(client_opts, Config), ServerOpts = ?config(server_opts, Config), diff --git a/lib/ssl/src/ssl_handshake.erl b/lib/ssl/src/ssl_handshake.erl index 28469dfa5f..bb26302fff 100644 --- a/lib/ssl/src/ssl_handshake.erl +++ b/lib/ssl/src/ssl_handshake.erl @@ -220,18 +220,23 @@ certify(#certificate{asn1_certificates = ASN1Certs}, CertDbHandle, CertDbRef, end, {Role, UserState0}} end, - {TrustedErlCert, CertPath} = - ssl_certificate:trusted_cert_and_path(ASN1Certs, CertDbHandle, CertDbRef), - - case public_key:pkix_path_validation(TrustedErlCert, - CertPath, - [{max_path_length, - MaxPathLen}, - {verify_fun, ValidationFunAndState}]) of - {ok, {PublicKeyInfo,_}} -> - {PeerCert, PublicKeyInfo}; - {error, Reason} -> - path_validation_alert(Reason) + try + {TrustedErlCert, CertPath} = + ssl_certificate:trusted_cert_and_path(ASN1Certs, CertDbHandle, CertDbRef), + case public_key:pkix_path_validation(TrustedErlCert, + CertPath, + [{max_path_length, + MaxPathLen}, + {verify_fun, ValidationFunAndState}]) of + {ok, {PublicKeyInfo,_}} -> + {PeerCert, PublicKeyInfo}; + {error, Reason} -> + path_validation_alert(Reason) + end + catch + error:_ -> + %% ASN-1 decode of certificate somehow failed + ?ALERT_REC(?FATAL, ?CERTIFICATE_UNKNOWN) end. %%-------------------------------------------------------------------- diff --git a/lib/stdlib/src/zip.erl b/lib/stdlib/src/zip.erl index c82c8159b6..fd480726a7 100644 --- a/lib/stdlib/src/zip.erl +++ b/lib/stdlib/src/zip.erl @@ -1017,7 +1017,7 @@ cd_file_header_from_lh_and_pos(LH, Pos) -> file_name_length = FileNameLength, extra_field_length = ExtraFieldLength, file_comment_length = 0, % FileCommentLength, - disk_num_start = 1, % DiskNumStart, + disk_num_start = 0, % DiskNumStart, internal_attr = 0, % InternalAttr, external_attr = 0, % ExternalAttr, local_header_offset = Pos}. diff --git a/lib/syntax_tools/doc/overview.edoc b/lib/syntax_tools/doc/overview.edoc index 23eadce8fe..df02ad0b3a 100644 --- a/lib/syntax_tools/doc/overview.edoc +++ b/lib/syntax_tools/doc/overview.edoc @@ -1,5 +1,9 @@ + -*- html -*- -@author Richard Carlsson <[email protected]> + Syntax Tools overview page + + +@author Richard Carlsson <[email protected]> @copyright 1997-2004 Richard Carlsson @version {@version} @title Erlang Syntax Tools diff --git a/lib/syntax_tools/src/epp_dodger.erl b/lib/syntax_tools/src/epp_dodger.erl index 9f6f7d815e..b3ced34c14 100644 --- a/lib/syntax_tools/src/epp_dodger.erl +++ b/lib/syntax_tools/src/epp_dodger.erl @@ -14,10 +14,8 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @copyright 2001-2006 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @end %% ===================================================================== diff --git a/lib/syntax_tools/src/erl_comment_scan.erl b/lib/syntax_tools/src/erl_comment_scan.erl index 108ab3bffd..b833e1c069 100644 --- a/lib/syntax_tools/src/erl_comment_scan.erl +++ b/lib/syntax_tools/src/erl_comment_scan.erl @@ -16,7 +16,7 @@ %% %% ===================================================================== %% @copyright 1997-2006 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @end %% ===================================================================== diff --git a/lib/syntax_tools/src/erl_prettypr.erl b/lib/syntax_tools/src/erl_prettypr.erl index 7caf0b3db6..f4bbf975c3 100644 --- a/lib/syntax_tools/src/erl_prettypr.erl +++ b/lib/syntax_tools/src/erl_prettypr.erl @@ -14,10 +14,8 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @copyright 1997-2006 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @end %% ===================================================================== diff --git a/lib/syntax_tools/src/erl_recomment.erl b/lib/syntax_tools/src/erl_recomment.erl index fc7c515700..7b2f9f7adb 100644 --- a/lib/syntax_tools/src/erl_recomment.erl +++ b/lib/syntax_tools/src/erl_recomment.erl @@ -14,10 +14,8 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @copyright 1997-2006 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @end %% ===================================================================== diff --git a/lib/syntax_tools/src/erl_syntax.erl b/lib/syntax_tools/src/erl_syntax.erl index 32fd3722d6..76a6a6dc36 100644 --- a/lib/syntax_tools/src/erl_syntax.erl +++ b/lib/syntax_tools/src/erl_syntax.erl @@ -14,10 +14,8 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @copyright 1997-2006 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @end %% ===================================================================== @@ -26,23 +24,20 @@ %% This module defines an abstract data type for representing Erlang %% source code as syntax trees, in a way that is backwards compatible %% with the data structures created by the Erlang standard library -%% parser module <code>erl_parse</code> (often referred to as "parse +%% parser module `erl_parse' (often referred to as "parse %% trees", which is a bit of a misnomer). This means that all -%% <code>erl_parse</code> trees are valid abstract syntax trees, but the +%% `erl_parse' trees are valid abstract syntax trees, but the %% reverse is not true: abstract syntax trees can in general not be used -%% as input to functions expecting an <code>erl_parse</code> tree. +%% as input to functions expecting an `erl_parse' tree. %% However, as long as an abstract syntax tree represents a correct -%% Erlang program, the function <a -%% href="#revert-1"><code>revert/1</code></a> should be able to -%% transform it to the corresponding <code>erl_parse</code> +%% Erlang program, the function {@link revert/1} should be able to +%% transform it to the corresponding `erl_parse' %% representation. %% -%% A recommended starting point for the first-time user is the -%% documentation of the <a -%% href="#type-syntaxTree"><code>syntaxTree()</code></a> data type, and -%% the function <a href="#type-1"><code>type/1</code></a>. +%% A recommended starting point for the first-time user is the documentation +%% of the {@link syntaxTree()} data type, and the function {@link type/1}. %% -%% <h3><b>NOTES:</b></h3> +%% == NOTES: == %% %% This module deals with the composition and decomposition of %% <em>syntactic</em> entities (as opposed to semantic ones); its @@ -52,36 +47,31 @@ %% in general, the user is assumed to pass type-correct arguments - if %% this is not done, the effects are not defined. %% -%% With the exception of the <code>erl_parse</code> data structures, +%% With the exception of the {@link erl_parse()} data structures, %% the internal representations of abstract syntax trees are subject to %% change without notice, and should not be documented outside this %% module. Furthermore, we do not give any guarantees on how an abstract %% syntax tree may or may not be represented, <em>with the following %% exceptions</em>: no syntax tree is represented by a single atom, such -%% as <code>none</code>, by a list constructor <code>[X | Y]</code>, or -%% by the empty list <code>[]</code>. This can be relied on when writing +%% as `none', by a list constructor `[X | Y]', or +%% by the empty list `[]'. This can be relied on when writing %% functions that operate on syntax trees. -%% @type syntaxTree(). An abstract syntax tree. The -%% <code>erl_parse</code> "parse tree" representation is a subset of the -%% <code>syntaxTree()</code> representation. +%% @type syntaxTree(). An abstract syntax tree. The {@link erl_parse()} +%% "parse tree" representation is a proper subset of the `syntaxTree()' +%% representation. %% %% Every abstract syntax tree node has a <em>type</em>, given by the -%% function <a href="#type-1"><code>type/1</code></a>. Each node also -%% has associated <em>attributes</em>; see <a -%% href="#get_attrs-1"><code>get_attrs/1</code></a> for details. The -%% functions <a href="#make_tree-2"><code>make_tree/2</code></a> and <a -%% href="#subtrees-1"><code>subtrees/1</code></a> are generic +%% function {@link type/1}. Each node also has associated +%% <em>attributes</em>; see {@link get_attrs/1} for details. The functions +%% {@link make_tree/2} and {@link subtrees/1} are generic %% constructor/decomposition functions for abstract syntax trees. The -%% functions <a href="#abstract-1"><code>abstract/1</code></a> and <a -%% href="#concrete-1"><code>concrete/1</code></a> convert between +%% functions {@link abstract/1} and {@link concrete/1} convert between %% constant Erlang terms and their syntactic representations. The set of -%% syntax tree nodes is extensible through the <a -%% href="#tree-2"><code>tree/2</code></a> function. +%% syntax tree nodes is extensible through the {@link tree/2} function. %% -%% A syntax tree can be transformed to the <code>erl_parse</code> -%% representation with the <a href="#revert-1"><code>revert/1</code></a> -%% function. +%% A syntax tree can be transformed to the {@link erl_parse()} +%% representation with the {@link revert/1} function. -module(erl_syntax). @@ -309,7 +299,7 @@ data/1, is_tree/1]). --export_type([forms/0, syntaxTree/0, syntaxTreeAttributes/0]). +-export_type([forms/0, syntaxTree/0, syntaxTreeAttributes/0, padding/0]). %% ===================================================================== %% IMPLEMENTATION NOTES: @@ -390,11 +380,15 @@ -record(wrapper, {type :: atom(), attr = #attr{} :: #attr{}, - tree :: term()}). + tree :: erl_parse()}). %% ===================================================================== --type syntaxTree() :: #tree{} | #wrapper{} | tuple(). % XXX: refine +-type syntaxTree() :: #tree{} | #wrapper{} | erl_parse(). + +-type erl_parse() :: erl_parse:abstract_form() | erl_parse:abstract_expr(). +%% The representation built by the Erlang standard library parser +%% `erl_parse'. This is a subset of the {@link syntaxTree()} type. %% ===================================================================== %% @@ -404,12 +398,11 @@ %% ===================================================================== -%% @spec type(Node::syntaxTree()) -> atom() -%% -%% @doc Returns the type tag of <code>Node</code>. If <code>Node</code> +%% @doc Returns the type tag of `Node'. If `Node' %% does not represent a syntax tree, evaluation fails with reason -%% <code>badarg</code>. Node types currently defined by this module are: -%% <p><center><table border="1"> +%% `badarg'. Node types currently defined by this module are: +%% +%% <center><table border="1"> %% <tr> %% <td>application</td> %% <td>arity_qualifier</td> @@ -476,12 +469,13 @@ %% <td>variable</td> %% <td>warning_marker</td> %% </tr> -%% </table></center></p> -%% <p>The user may (for special purposes) create additional nodes -%% with other type tags, using the <code>tree/2</code> function.</p> +%% </table></center> +%% +%% The user may (for special purposes) create additional nodes +%% with other type tags, using the {@link tree/2} function. %% -%% <p>Note: The primary constructor functions for a node type should -%% always have the same name as the node type itself.</p> +%% Note: The primary constructor functions for a node type should +%% always have the same name as the node type itself. %% %% @see tree/2 %% @see application/3 @@ -606,39 +600,38 @@ type(Node) -> %% ===================================================================== -%% @spec is_leaf(Node::syntaxTree()) -> boolean() -%% -%% @doc Returns <code>true</code> if <code>Node</code> is a leaf node, -%% otherwise <code>false</code>. The currently recognised leaf node +%% @doc Returns `true' if `Node' is a leaf node, +%% otherwise `false'. The currently recognised leaf node %% types are: -%% <p><center><table border="1"> +%% +%% <center><table border="1"> %% <tr> -%% <td><code>atom</code></td> -%% <td><code>char</code></td> -%% <td><code>comment</code></td> -%% <td><code>eof_marker</code></td> -%% <td><code>error_marker</code></td> +%% <td>`atom'</td> +%% <td>`char'</td> +%% <td>`comment'</td> +%% <td>`eof_marker'</td> +%% <td>`error_marker'</td> %% </tr><tr> -%% <td><code>float</code></td> -%% <td><code>integer</code></td> -%% <td><code>nil</code></td> -%% <td><code>operator</code></td> -%% <td><code>string</code></td> +%% <td>`float'</td> +%% <td>`integer'</td> +%% <td>`nil'</td> +%% <td>`operator'</td> +%% <td>`string'</td> %% </tr><tr> -%% <td><code>text</code></td> -%% <td><code>underscore</code></td> -%% <td><code>variable</code></td> -%% <td><code>warning_marker</code></td> +%% <td>`text'</td> +%% <td>`underscore'</td> +%% <td>`variable'</td> +%% <td>`warning_marker'</td> %% </tr> -%% </table></center></p> -%% <p>A node of type <code>tuple</code> is a leaf node if and only if -%% its arity is zero.</p> +%% </table></center> %% -%% <p>Note: not all literals are leaf nodes, and vice versa. E.g., +%% A node of type `tuple' is a leaf node if and only if its arity is zero. +%% +%% Note: not all literals are leaf nodes, and vice versa. E.g., %% tuples with nonzero arity and nonempty lists may be literals, but are %% not leaf nodes. Variables, on the other hand, are leaf nodes but not -%% literals.</p> -%% +%% literals. +%% %% @see type/1 %% @see is_literal/1 @@ -666,29 +659,29 @@ is_leaf(Node) -> %% ===================================================================== -%% @spec is_form(Node::syntaxTree()) -> boolean() -%% -%% @doc Returns <code>true</code> if <code>Node</code> is a syntax tree +%% @doc Returns `true' if `Node' is a syntax tree %% representing a so-called "source code form", otherwise -%% <code>false</code>. Forms are the Erlang source code units which, +%% `false'. Forms are the Erlang source code units which, %% placed in sequence, constitute an Erlang program. Current form types %% are: -%% <p><center><table border="1"> +%% +%% <center><table border="1"> %% <tr> -%% <td><code>attribute</code></td> -%% <td><code>comment</code></td> -%% <td><code>error_marker</code></td> -%% <td><code>eof_marker</code></td> -%% <td><code>form_list</code></td> +%% <td>`attribute'</td> +%% <td>`comment'</td> +%% <td>`error_marker'</td> +%% <td>`eof_marker'</td> +%% <td>`form_list'</td> %% </tr><tr> -%% <td><code>function</code></td> -%% <td><code>rule</code></td> -%% <td><code>warning_marker</code></td> -%% <td><code>text</code></td> +%% <td>`function'</td> +%% <td>`rule'</td> +%% <td>`warning_marker'</td> +%% <td>`text'</td> %% </tr> -%% </table></center></p> +%% </table></center> +%% %% @see type/1 -%% @see attribute/2 +%% @see attribute/2 %% @see comment/2 %% @see eof_marker/0 %% @see error_marker/1 @@ -715,10 +708,8 @@ is_form(Node) -> %% ===================================================================== -%% @spec get_pos(Node::syntaxTree()) -> term() -%% %% @doc Returns the position information associated with -%% <code>Node</code>. This is usually a nonnegative integer (indicating +%% `Node'. This is usually a nonnegative integer (indicating %% the source code line number), but may be any term. By default, all %% new tree nodes have their associated position information set to the %% integer zero. @@ -750,10 +741,7 @@ get_pos(Node) -> %% ===================================================================== -%% @spec set_pos(Node::syntaxTree(), Pos::term()) -> syntaxTree() -%% -%% @doc Sets the position information of <code>Node</code> to -%% <code>Pos</code>. +%% @doc Sets the position information of `Node' to `Pos'. %% %% @see get_pos/1 %% @see copy_pos/2 @@ -774,14 +762,10 @@ set_pos(Node, Pos) -> %% ===================================================================== -%% @spec copy_pos(Source::syntaxTree(), Target::syntaxTree()) -> -%% syntaxTree() -%% -%% @doc Copies the position information from <code>Source</code> to -%% <code>Target</code>. +%% @doc Copies the position information from `Source' to `Target'. %% -%% <p>This is equivalent to <code>set_pos(Target, -%% get_pos(Source))</code>, but potentially more efficient.</p> +%% This is equivalent to `set_pos(Target, +%% get_pos(Source))', but potentially more efficient. %% %% @see get_pos/1 %% @see set_pos/2 @@ -811,24 +795,20 @@ set_com(Node, Com) -> %% ===================================================================== -%% @spec get_precomments(syntaxTree()) -> [syntaxTree()] -%% %% @doc Returns the associated pre-comments of a node. This is a %% possibly empty list of abstract comments, in top-down textual order. %% When the code is formatted, pre-comments are typically displayed %% directly above the node. For example: -%% <pre> -%% % Pre-comment of function -%% foo(X) -> {bar, X}.</pre> +%% ```% Pre-comment of function +%% foo(X) -> {bar, X}.''' %% -%% <p>If possible, the comment should be moved before any preceding +%% If possible, the comment should be moved before any preceding %% separator characters on the same line. E.g.: -%% <pre> -%% foo([X | Xs]) -> -%% % Pre-comment of 'bar(X)' node -%% [bar(X) | foo(Xs)]; -%% ...</pre> -%% (where the comment is moved before the "<code>[</code>").</p> +%% ```foo([X | Xs]) -> +%% % Pre-comment of 'bar(X)' node +%% [bar(X) | foo(Xs)]; +%% ...''' +%% (where the comment is moved before the "`['"). %% %% @see comment/2 %% @see set_precomments/2 @@ -846,11 +826,8 @@ get_precomments_1(#attr{com = #com{pre = Cs}}) -> Cs. %% ===================================================================== -%% @spec set_precomments(Node::syntaxTree(), -%% Comments::[syntaxTree()]) -> syntaxTree() -%% -%% @doc Sets the pre-comments of <code>Node</code> to -%% <code>Comments</code>. <code>Comments</code> should be a possibly +%% @doc Sets the pre-comments of `Node' to +%% `Comments'. `Comments' should be a possibly %% empty list of abstract comments, in top-down textual order. %% %% @see comment/2 @@ -880,15 +857,11 @@ set_precomments_1(#attr{com = Com} = Attr, Cs) -> %% ===================================================================== -%% @spec add_precomments(Comments::[syntaxTree()], -%% Node::syntaxTree()) -> syntaxTree() +%% @doc Appends `Comments' to the pre-comments of `Node'. %% -%% @doc Appends <code>Comments</code> to the pre-comments of -%% <code>Node</code>. -%% -%% <p>Note: This is equivalent to <code>set_precomments(Node, -%% get_precomments(Node) ++ Comments)</code>, but potentially more -%% efficient.</p> +%% Note: This is equivalent to `set_precomments(Node, +%% get_precomments(Node) ++ Comments)', but potentially more +%% efficient. %% %% @see comment/2 %% @see get_precomments/1 @@ -915,24 +888,20 @@ add_precomments_1(Cs, #attr{com = Com} = Attr) -> %% ===================================================================== -%% @spec get_postcomments(syntaxTree()) -> [syntaxTree()] -%% %% @doc Returns the associated post-comments of a node. This is a %% possibly empty list of abstract comments, in top-down textual order. %% When the code is formatted, post-comments are typically displayed to %% the right of and/or below the node. For example: -%% <pre> -%% {foo, X, Y} % Post-comment of tuple</pre> +%% ```{foo, X, Y} % Post-comment of tuple''' %% -%% <p>If possible, the comment should be moved past any following +%% If possible, the comment should be moved past any following %% separator characters on the same line, rather than placing the %% separators on the following line. E.g.: -%% <pre> -%% foo([X | Xs], Y) -> -%% foo(Xs, bar(X)); % Post-comment of 'bar(X)' node -%% ...</pre> -%% (where the comment is moved past the rightmost "<code>)</code>" and -%% the "<code>;</code>").</p> +%% ```foo([X | Xs], Y) -> +%% foo(Xs, bar(X)); % Post-comment of 'bar(X)' node +%% ...''' +%% (where the comment is moved past the rightmost "`)'" and +%% the "`;'"). %% %% @see comment/2 %% @see set_postcomments/2 @@ -950,11 +919,8 @@ get_postcomments_1(#attr{com = #com{post = Cs}}) -> Cs. %% ===================================================================== -%% @spec set_postcomments(Node::syntaxTree(), -%% Comments::[syntaxTree()]) -> syntaxTree() -%% -%% @doc Sets the post-comments of <code>Node</code> to -%% <code>Comments</code>. <code>Comments</code> should be a possibly +%% @doc Sets the post-comments of `Node' to +%% `Comments'. `Comments' should be a possibly %% empty list of abstract comments, in top-down textual order %% %% @see comment/2 @@ -984,15 +950,11 @@ set_postcomments_1(#attr{com = Com} = Attr, Cs) -> %% ===================================================================== -%% @spec add_postcomments(Comments::[syntaxTree()], -%% Node::syntaxTree()) -> syntaxTree() -%% -%% @doc Appends <code>Comments</code> to the post-comments of -%% <code>Node</code>. +%% @doc Appends `Comments' to the post-comments of `Node'. %% -%% <p>Note: This is equivalent to <code>set_postcomments(Node, -%% get_postcomments(Node) ++ Comments)</code>, but potentially more -%% efficient.</p> +%% Note: This is equivalent to `set_postcomments(Node, +%% get_postcomments(Node) ++ Comments)', but potentially more +%% efficient. %% %% @see comment/2 %% @see get_postcomments/1 @@ -1019,14 +981,12 @@ add_postcomments_1(Cs, #attr{com = Com} = Attr) -> %% ===================================================================== -%% @spec has_comments(Node::syntaxTree()) -> boolean() +%% @doc Yields `false' if the node has no associated +%% comments, and `true' otherwise. %% -%% @doc Yields <code>false</code> if the node has no associated -%% comments, and <code>true</code> otherwise. -%% -%% <p>Note: This is equivalent to <code>(get_precomments(Node) == []) -%% and (get_postcomments(Node) == [])</code>, but potentially more -%% efficient.</p> +%% Note: This is equivalent to `(get_precomments(Node) == []) +%% and (get_postcomments(Node) == [])', but potentially more +%% efficient. %% %% @see get_precomments/1 %% @see get_postcomments/1 @@ -1050,13 +1010,11 @@ has_comments(_) -> false. %% ===================================================================== -%% @spec remove_comments(Node::syntaxTree()) -> syntaxTree() -%% -%% @doc Clears the associated comments of <code>Node</code>. +%% @doc Clears the associated comments of `Node'. %% -%% <p>Note: This is equivalent to -%% <code>set_precomments(set_postcomments(Node, []), [])</code>, but -%% potentially more efficient.</p> +%% Note: This is equivalent to +%% `set_precomments(set_postcomments(Node, []), [])', but +%% potentially more efficient. %% %% @see set_precomments/2 %% @see set_postcomments/2 @@ -1075,16 +1033,12 @@ remove_comments(Node) -> %% ===================================================================== -%% @spec copy_comments(Source::syntaxTree(), Target::syntaxTree()) -> -%% syntaxTree() -%% -%% @doc Copies the pre- and postcomments from <code>Source</code> to -%% <code>Target</code>. +%% @doc Copies the pre- and postcomments from `Source' to `Target'. %% -%% <p>Note: This is equivalent to -%% <code>set_postcomments(set_precomments(Target, -%% get_precomments(Source)), get_postcomments(Source))</code>, but -%% potentially more efficient.</p> +%% Note: This is equivalent to +%% `set_postcomments(set_precomments(Target, +%% get_precomments(Source)), get_postcomments(Source))', but +%% potentially more efficient. %% %% @see comment/2 %% @see get_precomments/1 @@ -1099,16 +1053,13 @@ copy_comments(Source, Target) -> %% ===================================================================== -%% @spec join_comments(Source::syntaxTree(), Target::syntaxTree()) -> -%% syntaxTree() +%% @doc Appends the comments of `Source' to the current +%% comments of `Target'. %% -%% @doc Appends the comments of <code>Source</code> to the current -%% comments of <code>Target</code>. -%% -%% <p>Note: This is equivalent to -%% <code>add_postcomments(get_postcomments(Source), -%% add_precomments(get_precomments(Source), Target))</code>, but -%% potentially more efficient.</p> +%% Note: This is equivalent to +%% `add_postcomments(get_postcomments(Source), +%% add_precomments(get_precomments(Source), Target))', but +%% potentially more efficient. %% %% @see comment/2 %% @see get_precomments/1 @@ -1125,8 +1076,6 @@ join_comments(Source, Target) -> %% ===================================================================== -%% @spec get_ann(syntaxTree()) -> [term()] -%% %% @doc Returns the list of user annotations associated with a syntax %% tree node. For a newly created node, this is the empty list. The %% annotations may be any terms. @@ -1142,11 +1091,7 @@ get_ann(_) -> []. %% ===================================================================== -%% @spec set_ann(Node::syntaxTree(), Annotations::[term()]) -> -%% syntaxTree() -%% -%% @doc Sets the list of user annotations of <code>Node</code> to -%% <code>Annotations</code>. +%% @doc Sets the list of user annotations of `Node' to `Annotations'. %% %% @see get_ann/1 %% @see add_ann/2 @@ -1168,13 +1113,11 @@ set_ann(Node, As) -> %% ===================================================================== -%% @spec add_ann(Annotation::term(), Node::syntaxTree()) -> syntaxTree() -%% -%% @doc Appends the term <code>Annotation</code> to the list of user -%% annotations of <code>Node</code>. +%% @doc Appends the term `Annotation' to the list of user +%% annotations of `Node'. %% -%% <p>Note: this is equivalent to <code>set_ann(Node, [Annotation | -%% get_ann(Node)])</code>, but potentially more efficient.</p> +%% Note: this is equivalent to `set_ann(Node, [Annotation | +%% get_ann(Node)])', but potentially more efficient. %% %% @see get_ann/1 %% @see set_ann/2 @@ -1195,14 +1138,10 @@ add_ann(A, Node) -> %% ===================================================================== -%% @spec copy_ann(Source::syntaxTree(), Target::syntaxTree()) -> -%% syntaxTree() +%% @doc Copies the list of user annotations from `Source' to `Target'. %% -%% @doc Copies the list of user annotations from <code>Source</code> to -%% <code>Target</code>. -%% -%% <p>Note: this is equivalent to <code>set_ann(Target, -%% get_ann(Source))</code>, but potentially more efficient.</p> +%% Note: this is equivalent to `set_ann(Target, +%% get_ann(Source))', but potentially more efficient. %% %% @see get_ann/1 %% @see set_ann/2 @@ -1214,23 +1153,20 @@ copy_ann(Source, Target) -> %% ===================================================================== -%% @spec get_attrs(syntaxTree()) -> syntaxTreeAttributes() -%% %% @doc Returns a representation of the attributes associated with a %% syntax tree node. The attributes are all the extra information that %% can be attached to a node. Currently, this includes position %% information, source code comments, and user annotations. The result %% of this function cannot be inspected directly; only attached to -%% another node (cf. <code>set_attrs/2</code>). +%% another node (see {@link set_attrs/2}). %% -%% <p>For accessing individual attributes, see <code>get_pos/1</code>, -%% <code>get_ann/1</code>, <code>get_precomments/1</code> and -%% <code>get_postcomments/1</code>.</p> +%% For accessing individual attributes, see {@link get_pos/1}, +%% {@link get_ann/1}, {@link get_precomments/1} and +%% {@link get_postcomments/1}. %% %% @type syntaxTreeAttributes(). This is an abstract representation of -%% syntax tree node attributes; see the function <a -%% href="#get_attrs-1"><code>get_attrs/1</code></a>. -%% +%% syntax tree node attributes; see the function {@link get_attrs/1}. +%% %% @see set_attrs/2 %% @see get_pos/1 %% @see get_ann/1 @@ -1247,11 +1183,7 @@ get_attrs(Node) -> #attr{pos = get_pos(Node), %% ===================================================================== -%% @spec set_attrs(Node::syntaxTree(), -%% Attributes::syntaxTreeAttributes()) -> syntaxTree() -%% -%% @doc Sets the attributes of <code>Node</code> to -%% <code>Attributes</code>. +%% @doc Sets the attributes of `Node' to `Attributes'. %% %% @see get_attrs/1 %% @see copy_attrs/2 @@ -1270,14 +1202,10 @@ set_attrs(Node, Attr) -> %% ===================================================================== -%% @spec copy_attrs(Source::syntaxTree(), Target::syntaxTree()) -> -%% syntaxTree() +%% @doc Copies the attributes from `Source' to `Target'. %% -%% @doc Copies the attributes from <code>Source</code> to -%% <code>Target</code>. -%% -%% <p>Note: this is equivalent to <code>set_attrs(Target, -%% get_attrs(Source))</code>, but potentially more efficient.</p> +%% Note: this is equivalent to `set_attrs(Target, +%% get_attrs(Source))', but potentially more efficient. %% %% @see get_attrs/1 %% @see set_attrs/2 @@ -1289,7 +1217,6 @@ copy_attrs(S, T) -> %% ===================================================================== -%% @spec comment(Strings) -> syntaxTree() %% @equiv comment(none, Strings) -spec comment([string()]) -> syntaxTree(). @@ -1299,22 +1226,19 @@ comment(Strings) -> %% ===================================================================== -%% @spec comment(Padding, Strings::[string()]) -> syntaxTree() -%% Padding = none | integer() -%% %% @doc Creates an abstract comment with the given padding and text. If -%% <code>Strings</code> is a (possibly empty) list +%% `Strings' is a (possibly empty) list %% <code>["<em>Txt1</em>", ..., "<em>TxtN</em>"]</code>, the result %% represents the source code text %% <pre> -%% %<em>Txt1</em> -%% ... -%% %<em>TxtN</em></pre> -%% <code>Padding</code> states the number of empty character positions +%% %<em>Txt1</em> +%% ... +%% %<em>TxtN</em></pre> +%% `Padding' states the number of empty character positions %% to the left of the comment separating it horizontally from -%% source code on the same line (if any). If <code>Padding</code> is -%% <code>none</code>, a default positive number is used. If -%% <code>Padding</code> is an integer less than 1, there should be no +%% source code on the same line (if any). If `Padding' is +%% `none', a default positive number is used. If +%% `Padding' is an integer less than 1, there should be no %% separating space. Comments are in themselves regarded as source %% program forms. %% @@ -1338,8 +1262,6 @@ comment(Pad, Strings) -> %% ===================================================================== -%% @spec comment_text(syntaxTree()) -> [string()] -%% %% @doc Returns the lines of text of the abstract comment. %% %% @see comment/2 @@ -1351,11 +1273,8 @@ comment_text(Node) -> %% ===================================================================== -%% @spec comment_padding(syntaxTree()) -> none | integer() -%% %% @doc Returns the amount of padding before the comment, or -%% <code>none</code>. The latter means that a default padding may be -%% used. +%% `none'. The latter means that a default padding may be used. %% %% @see comment/2 @@ -1366,23 +1285,21 @@ comment_padding(Node) -> %% ===================================================================== -%% @spec form_list(Forms::[syntaxTree()]) -> syntaxTree() -%% %% @doc Creates an abstract sequence of "source code forms". If -%% <code>Forms</code> is <code>[F1, ..., Fn]</code>, where each -%% <code>Fi</code> is a form (cf. <code>is_form/1</code>, the result +%% `Forms' is `[F1, ..., Fn]', where each +%% `Fi' is a form (see {@link is_form/1}, the result %% represents %% <pre> -%% <em>F1</em> -%% ... -%% <em>Fn</em></pre> -%% where the <code>Fi</code> are separated by one or more line breaks. A -%% node of type <code>form_list</code> is itself regarded as a source -%% code form; cf. <code>flatten_form_list/1</code>. -%% -%% <p>Note: this is simply a way of grouping source code forms as a +%% <em>F1</em> +%% ... +%% <em>Fn</em></pre> +%% where the `Fi' are separated by one or more line breaks. A +%% node of type `form_list' is itself regarded as a source +%% code form; see {@link flatten_form_list/1}. +%% +%% Note: this is simply a way of grouping source code forms as a %% single syntax tree, usually in order to form an Erlang module -%% definition.</p> +%% definition. %% %% @see form_list_elements/1 %% @see is_form/1 @@ -1401,9 +1318,7 @@ form_list(Forms) -> %% ===================================================================== -%% @spec form_list_elements(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of subnodes of a <code>form_list</code> node. +%% @doc Returns the list of subnodes of a `form_list' node. %% %% @see form_list/1 @@ -1414,10 +1329,8 @@ form_list_elements(Node) -> %% ===================================================================== -%% @spec flatten_form_list(Node::syntaxTree()) -> syntaxTree() -%% -%% @doc Flattens sublists of a <code>form_list</code> node. Returns -%% <code>Node</code> with all subtrees of type <code>form_list</code> +%% @doc Flattens sublists of a `form_list' node. Returns +%% `Node' with all subtrees of type `form_list' %% recursively expanded, yielding a single "flat" abstract form %% sequence. %% @@ -1443,10 +1356,8 @@ flatten_form_list_1([], As) -> %% ===================================================================== -%% @spec text(String::string()) -> syntaxTree() -%% %% @doc Creates an abstract piece of source code text. The result -%% represents exactly the sequence of characters in <code>String</code>. +%% represents exactly the sequence of characters in `String'. %% This is useful in cases when one wants full control of the resulting %% output, e.g., for the appearance of floating-point numbers or macro %% definitions. @@ -1463,10 +1374,7 @@ text(String) -> %% ===================================================================== -%% @spec text_string(syntaxTree()) -> string() -%% -%% @doc Returns the character sequence represented by a -%% <code>text</code> node. +%% @doc Returns the character sequence represented by a `text' node. %% %% @see text/1 @@ -1477,18 +1385,15 @@ text_string(Node) -> %% ===================================================================== -%% @spec variable(Name) -> syntaxTree() -%% Name = atom() | string() -%% %% @doc Creates an abstract variable with the given name. -%% <code>Name</code> may be any atom or string that represents a +%% `Name' may be any atom or string that represents a %% lexically valid variable name, but <em>not</em> a single underscore -%% character; cf. <code>underscore/0</code>. +%% character; see {@link underscore/0}. %% -%% <p>Note: no checking is done whether the character sequence +%% Note: no checking is done whether the character sequence %% represents a proper variable name, i.e., whether or not its first %% character is an uppercase Erlang character, or whether it does not -%% contain control characters, whitespace, etc.</p> +%% contain control characters, whitespace, etc. %% %% @see variable_name/1 %% @see variable_literal/1 @@ -1517,9 +1422,7 @@ revert_variable(Node) -> %% ===================================================================== -%% @spec variable_name(syntaxTree()) -> atom() -%% -%% @doc Returns the name of a <code>variable</code> node as an atom. +%% @doc Returns the name of a `variable' node as an atom. %% %% @see variable/1 @@ -1535,9 +1438,7 @@ variable_name(Node) -> %% ===================================================================== -%% @spec variable_literal(syntaxTree()) -> string() -%% -%% @doc Returns the name of a <code>variable</code> node as a string. +%% @doc Returns the name of a `variable' node as a string. %% %% @see variable/1 @@ -1553,9 +1454,7 @@ variable_literal(Node) -> %% ===================================================================== -%% @spec underscore() -> syntaxTree() -%% -%% @doc Creates an abstract universal pattern ("<code>_</code>"). The +%% @doc Creates an abstract universal pattern ("`_'"). The %% lexical representation is a single underscore character. Note that %% this is <em>not</em> a variable, lexically speaking. %% @@ -1579,10 +1478,8 @@ revert_underscore(Node) -> %% ===================================================================== -%% @spec integer(Value::integer()) -> syntaxTree() -%% %% @doc Creates an abstract integer literal. The lexical representation -%% is the canonical decimal numeral of <code>Value</code>. +%% is the canonical decimal numeral of `Value'. %% %% @see integer_value/1 %% @see integer_literal/1 @@ -1608,11 +1505,8 @@ revert_integer(Node) -> %% ===================================================================== -%% @spec is_integer(Node::syntaxTree(), Value::integer()) -> boolean() -%% -%% @doc Returns <code>true</code> if <code>Node</code> has type -%% <code>integer</code> and represents <code>Value</code>, otherwise -%% <code>false</code>. +%% @doc Returns `true' if `Node' has type +%% `integer' and represents `Value', otherwise `false'. %% %% @see integer/1 @@ -1630,9 +1524,7 @@ is_integer(Node, Value) -> %% ===================================================================== -%% @spec integer_value(syntaxTree()) -> integer() -%% -%% @doc Returns the value represented by an <code>integer</code> node. +%% @doc Returns the value represented by an `integer' node. %% %% @see integer/1 @@ -1648,10 +1540,7 @@ integer_value(Node) -> %% ===================================================================== -%% @spec integer_literal(syntaxTree()) -> string() -%% -%% @doc Returns the numeral string represented by an -%% <code>integer</code> node. +%% @doc Returns the numeral string represented by an `integer' node. %% %% @see integer/1 @@ -1662,11 +1551,8 @@ integer_literal(Node) -> %% ===================================================================== -%% @spec float(Value::float()) -> syntaxTree() -%% %% @doc Creates an abstract floating-point literal. The lexical -%% representation is the decimal floating-point numeral of -%% <code>Value</code>. +%% representation is the decimal floating-point numeral of `Value'. %% %% @see float_value/1 %% @see float_literal/1 @@ -1701,9 +1587,7 @@ revert_float(Node) -> %% ===================================================================== -%% @spec float_value(syntaxTree()) -> float() -%% -%% @doc Returns the value represented by a <code>float</code> node. Note +%% @doc Returns the value represented by a `float' node. Note %% that floating-point values should usually not be compared for %% equality. %% @@ -1721,10 +1605,7 @@ float_value(Node) -> %% ===================================================================== -%% @spec float_literal(syntaxTree()) -> string() -%% -%% @doc Returns the numeral string represented by a <code>float</code> -%% node. +%% @doc Returns the numeral string represented by a `float' node. %% %% @see float/1 @@ -1735,17 +1616,15 @@ float_literal(Node) -> %% ===================================================================== -%% @spec char(Value::char()) -> syntaxTree() -%% %% @doc Creates an abstract character literal. The result represents -%% "<code>$<em>Name</em></code>", where <code>Name</code> corresponds to -%% <code>Value</code>. +%% "<code>$<em>Name</em></code>", where `Name' corresponds to +%% `Value'. %% -%% <p>Note: the literal corresponding to a particular character value is -%% not uniquely defined. E.g., the character "<code>a</code>" can be -%% written both as "<code>$a</code>" and "<code>$\141</code>", and a Tab -%% character can be written as "<code>$\11</code>", "<code>$\011</code>" -%% or "<code>$\t</code>".</p> +%% Note: the literal corresponding to a particular character value is +%% not uniquely defined. E.g., the character "`a'" can be +%% written both as "`$a'" and "`$\141'", and a Tab +%% character can be written as "`$\11'", "`$\011'" +%% or "`$\t'". %% %% @see char_value/1 %% @see char_literal/1 @@ -1771,11 +1650,8 @@ revert_char(Node) -> %% ===================================================================== -%% @spec is_char(Node::syntaxTree(), Value::char()) -> boolean() -%% -%% @doc Returns <code>true</code> if <code>Node</code> has type -%% <code>char</code> and represents <code>Value</code>, otherwise -%% <code>false</code>. +%% @doc Returns `true' if `Node' has type +%% `char' and represents `Value', otherwise `false'. %% %% @see char/1 @@ -1793,9 +1669,7 @@ is_char(Node, Value) -> %% ===================================================================== -%% @spec char_value(syntaxTree()) -> char() -%% -%% @doc Returns the value represented by a <code>char</code> node. +%% @doc Returns the value represented by a `char' node. %% %% @see char/1 @@ -1811,10 +1685,8 @@ char_value(Node) -> %% ===================================================================== -%% @spec char_literal(syntaxTree()) -> string() -%% -%% @doc Returns the literal string represented by a <code>char</code> -%% node. This includes the leading "<code>$</code>" character. +%% @doc Returns the literal string represented by a `char' +%% node. This includes the leading "`$'" character. %% %% @see char/1 @@ -1825,16 +1697,14 @@ char_literal(Node) -> %% ===================================================================== -%% @spec string(Value::string()) -> syntaxTree() -%% %% @doc Creates an abstract string literal. The result represents %% <code>"<em>Text</em>"</code> (including the surrounding -%% double-quotes), where <code>Text</code> corresponds to the sequence -%% of characters in <code>Value</code>, but not representing a -%% <em>specific</em> string literal. E.g., the result of -%% <code>string("x\ny")</code> represents any and all of -%% <code>"x\ny"</code>, <code>"x\12y"</code>, <code>"x\012y"</code> and -%% <code>"x\^Jy"</code>; cf. <code>char/1</code>. +%% double-quotes), where `Text' corresponds to the sequence +%% of characters in `Value', but not representing a +%% <em>specific</em> string literal. +%% +%% For example, the result of `string("x\ny")' represents any and all of +%% `"x\ny"', `"x\12y"', `"x\012y"' and `"x\^Jy"'; see {@link char/1}. %% %% @see string_value/1 %% @see string_literal/1 @@ -1861,11 +1731,8 @@ revert_string(Node) -> %% ===================================================================== -%% @spec is_string(Node::syntaxTree(), Value::string()) -> boolean() -%% -%% @doc Returns <code>true</code> if <code>Node</code> has type -%% <code>string</code> and represents <code>Value</code>, otherwise -%% <code>false</code>. +%% @doc Returns `true' if `Node' has type +%% `string' and represents `Value', otherwise `false'. %% %% @see string/1 @@ -1883,9 +1750,7 @@ is_string(Node, Value) -> %% ===================================================================== -%% @spec string_value(syntaxTree()) -> string() -%% -%% @doc Returns the value represented by a <code>string</code> node. +%% @doc Returns the value represented by a `string' node. %% %% @see string/1 @@ -1901,9 +1766,7 @@ string_value(Node) -> %% ===================================================================== -%% @spec string_literal(syntaxTree()) -> string() -%% -%% @doc Returns the literal string represented by a <code>string</code> +%% @doc Returns the literal string represented by a `string' %% node. This includes surrounding double-quote characters. %% %% @see string/1 @@ -1915,11 +1778,8 @@ string_literal(Node) -> %% ===================================================================== -%% @spec atom(Name) -> syntaxTree() -%% Name = atom() | string() -%% %% @doc Creates an abstract atom literal. The print name of the atom is -%% the character sequence represented by <code>Name</code>. +%% the character sequence represented by `Name'. %% %% @see atom_value/1 %% @see atom_name/1 @@ -1948,11 +1808,8 @@ revert_atom(Node) -> %% ===================================================================== -%% @spec is_atom(Node::syntaxTree(), Value::atom()) -> boolean() -%% -%% @doc Returns <code>true</code> if <code>Node</code> has type -%% <code>atom</code> and represents <code>Value</code>, otherwise -%% <code>false</code>. +%% @doc Returns `true' if `Node' has type +%% `atom' and represents `Value', otherwise `false'. %% %% @see atom/1 @@ -1970,9 +1827,7 @@ is_atom(Node, Value) -> %% ===================================================================== -%% @spec atom_value(syntaxTree()) -> atom() -%% -%% @doc Returns the value represented by an <code>atom</code> node. +%% @doc Returns the value represented by an `atom' node. %% %% @see atom/1 @@ -1988,9 +1843,7 @@ atom_value(Node) -> %% ===================================================================== -%% @spec atom_name(syntaxTree()) -> string() -%% -%% @doc Returns the printname of an <code>atom</code> node. +%% @doc Returns the printname of an `atom' node. %% %% @see atom/1 @@ -2001,15 +1854,12 @@ atom_name(Node) -> %% ===================================================================== -%% @spec atom_literal(syntaxTree()) -> string() -%% -%% @doc Returns the literal string represented by an <code>atom</code> +%% @doc Returns the literal string represented by an `atom' %% node. This includes surrounding single-quote characters if necessary. %% -%% <p>Note that e.g. the result of <code>atom("x\ny")</code> represents -%% any and all of <code>'x\ny'</code>, <code>'x\12y'</code>, -%% <code>'x\012y'</code> and <code>'x\^Jy\'</code>; cf. -%% <code>string/1</code>.</p> +%% Note that e.g. the result of `atom("x\ny")' represents +%% any and all of `'x\ny'', `'x\12y'', +%% `'x\012y'' and `'x\^Jy\''; see {@link string/1}. %% %% @see atom/1 %% @see string/1 @@ -2021,14 +1871,12 @@ atom_literal(Node) -> %% ===================================================================== -%% @spec tuple(Elements::[syntaxTree()]) -> syntaxTree() -%% -%% @doc Creates an abstract tuple. If <code>Elements</code> is -%% <code>[X1, ..., Xn]</code>, the result represents +%% @doc Creates an abstract tuple. If `Elements' is +%% `[X1, ..., Xn]', the result represents %% "<code>{<em>X1</em>, ..., <em>Xn</em>}</code>". %% -%% <p>Note: The Erlang language has distinct 1-tuples, i.e., -%% <code>{X}</code> is always distinct from <code>X</code> itself.</p> +%% Note: The Erlang language has distinct 1-tuples, i.e., +%% `{X}' is always distinct from `X' itself. %% %% @see tuple_elements/1 %% @see tuple_size/1 @@ -2055,10 +1903,7 @@ revert_tuple(Node) -> %% ===================================================================== -%% @spec tuple_elements(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of element subtrees of a <code>tuple</code> -%% node. +%% @doc Returns the list of element subtrees of a `tuple' node. %% %% @see tuple/1 @@ -2074,13 +1919,11 @@ tuple_elements(Node) -> %% ===================================================================== -%% @spec tuple_size(syntaxTree()) -> integer() -%% -%% @doc Returns the number of elements of a <code>tuple</code> node. +%% @doc Returns the number of elements of a `tuple' node. %% -%% <p>Note: this is equivalent to -%% <code>length(tuple_elements(Node))</code>, but potentially more -%% efficient.</p> +%% Note: this is equivalent to +%% `length(tuple_elements(Node))', but potentially more +%% efficient. %% %% @see tuple/1 %% @see tuple_elements/1 @@ -2092,7 +1935,6 @@ tuple_size(Node) -> %% ===================================================================== -%% @spec list(List) -> syntaxTree() %% @equiv list(List, none) -spec list([syntaxTree()]) -> syntaxTree(). @@ -2102,35 +1944,31 @@ list(List) -> %% ===================================================================== -%% @spec list(List, Tail) -> syntaxTree() -%% List = [syntaxTree()] -%% Tail = none | syntaxTree() -%% %% @doc Constructs an abstract list skeleton. The result has type -%% <code>list</code> or <code>nil</code>. If <code>List</code> is a -%% nonempty list <code>[E1, ..., En]</code>, the result has type -%% <code>list</code> and represents either "<code>[<em>E1</em>, ..., -%% <em>En</em>]</code>", if <code>Tail</code> is <code>none</code>, or +%% `list' or `nil'. If `List' is a +%% nonempty list `[E1, ..., En]', the result has type +%% `list' and represents either "<code>[<em>E1</em>, ..., +%% <em>En</em>]</code>", if `Tail' is `none', or %% otherwise "<code>[<em>E1</em>, ..., <em>En</em> | -%% <em>Tail</em>]</code>". If <code>List</code> is the empty list, -%% <code>Tail</code> <em>must</em> be <code>none</code>, and in that -%% case the result has type <code>nil</code> and represents -%% "<code>[]</code>" (cf. <code>nil/0</code>). +%% <em>Tail</em>]</code>". If `List' is the empty list, +%% `Tail' <em>must</em> be `none', and in that +%% case the result has type `nil' and represents +%% "`[]'" (see {@link nil/0}). %% -%% <p>The difference between lists as semantic objects (built up of +%% The difference between lists as semantic objects (built up of %% individual "cons" and "nil" terms) and the various syntactic forms %% for denoting lists may be bewildering at first. This module provides %% functions both for exact control of the syntactic representation as %% well as for the simple composition and deconstruction in terms of -%% cons and head/tail operations.</p> +%% cons and head/tail operations. %% -%% <p>Note: in <code>list(Elements, none)</code>, the "nil" list -%% terminator is implicit and has no associated information (cf. -%% <code>get_attrs/1</code>), while in the seemingly equivalent -%% <code>list(Elements, Tail)</code> when <code>Tail</code> has type -%% <code>nil</code>, the list terminator subtree <code>Tail</code> may +%% Note: in `list(Elements, none)', the "nil" list +%% terminator is implicit and has no associated information (see +%% {@link get_attrs/1}), while in the seemingly equivalent +%% `list(Elements, Tail)' when `Tail' has type +%% `nil', the list terminator subtree `Tail' may %% have attached attributes such as position, comments, and annotations, -%% which will be preserved in the result.</p> +%% which will be preserved in the result. %% %% @see nil/0 %% @see list/1 @@ -2187,10 +2025,8 @@ revert_list(Node) -> S, P). %% ===================================================================== -%% @spec nil() -> syntaxTree() -%% %% @doc Creates an abstract empty list. The result represents -%% "<code>[]</code>". The empty list is traditionally called "nil". +%% "`[]'". The empty list is traditionally called "nil". %% %% @see list/2 %% @see is_list_skeleton/1 @@ -2213,13 +2049,11 @@ revert_nil(Node) -> %% ===================================================================== -%% @spec list_prefix(Node::syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the prefix element subtrees of a <code>list</code> node. -%% If <code>Node</code> represents "<code>[<em>E1</em>, ..., +%% @doc Returns the prefix element subtrees of a `list' node. +%% If `Node' represents "<code>[<em>E1</em>, ..., %% <em>En</em>]</code>" or "<code>[<em>E1</em>, ..., <em>En</em> | -%% <em>Tail</em>]</code>", the returned value is <code>[E1, ..., -%% En]</code>. +%% <em>Tail</em>]</code>", the returned value is `[E1, ..., +%% En]'. %% %% @see list/2 @@ -2227,28 +2061,31 @@ revert_nil(Node) -> list_prefix(Node) -> case unwrap(Node) of - {cons, _, Head, _} -> - [Head]; + {cons, _, Head, Tail} -> + [Head | cons_prefix(Tail)]; Node1 -> (data(Node1))#list.prefix end. +%% collects sequences of conses; cf. cons_suffix/1 below +cons_prefix({cons, _, Head, Tail}) -> + [Head | cons_prefix(Tail)]; +cons_prefix(_) -> + []. + %% ===================================================================== -%% @spec list_suffix(Node::syntaxTree()) -> none | syntaxTree() -%% -%% @doc Returns the suffix subtree of a <code>list</code> node, if one -%% exists. If <code>Node</code> represents "<code>[<em>E1</em>, ..., +%% @doc Returns the suffix subtree of a `list' node, if one +%% exists. If `Node' represents "<code>[<em>E1</em>, ..., %% <em>En</em> | <em>Tail</em>]</code>", the returned value is -%% <code>Tail</code>, otherwise, i.e., if <code>Node</code> represents -%% "<code>[<em>E1</em>, ..., <em>En</em>]</code>", <code>none</code> is +%% `Tail', otherwise, i.e., if `Node' represents +%% "<code>[<em>E1</em>, ..., <em>En</em>]</code>", `none' is %% returned. %% -%% <p>Note that even if this function returns some <code>Tail</code> -%% that is not <code>none</code>, the type of <code>Tail</code> can be -%% <code>nil</code>, if the tail has been given explicitly, and the list -%% skeleton has not been compacted (cf. -%% <code>compact_list/1</code>).</p> +%% Note that even if this function returns some `Tail' +%% that is not `none', the type of `Tail' can be +%% `nil', if the tail has been given explicitly, and the list +%% skeleton has not been compacted (see {@link compact_list/1}). %% %% @see list/2 %% @see nil/0 @@ -2259,34 +2096,36 @@ list_prefix(Node) -> list_suffix(Node) -> case unwrap(Node) of {cons, _, _, Tail} -> - %% If there could be comments/annotations on the tail node, - %% we should not return `none' even if it has type `nil'. - case Tail of + case cons_suffix(Tail) of {nil, _} -> - none; % no interesting information is lost - _ -> - Tail + none; + Tail1 -> + Tail1 end; Node1 -> (data(Node1))#list.suffix end. +%% skips sequences of conses; cf. cons_prefix/1 above +cons_suffix({cons, _, _, Tail}) -> + cons_suffix(Tail); +cons_suffix(Tail) -> + Tail. + %% ===================================================================== -%% @spec cons(Head::syntaxTree(), Tail::syntaxTree()) -> syntaxTree() -%% %% @doc "Optimising" list skeleton cons operation. Creates an abstract -%% list skeleton whose first element is <code>Head</code> and whose tail -%% corresponds to <code>Tail</code>. This is similar to -%% <code>list([Head], Tail)</code>, except that <code>Tail</code> may -%% not be <code>none</code>, and that the result does not necessarily +%% list skeleton whose first element is `Head' and whose tail +%% corresponds to `Tail'. This is similar to +%% `list([Head], Tail)', except that `Tail' may +%% not be `none', and that the result does not necessarily %% represent exactly "<code>[<em>Head</em> | <em>Tail</em>]</code>", but -%% may depend on the <code>Tail</code> subtree. E.g., if -%% <code>Tail</code> represents <code>[X, Y]</code>, the result may +%% may depend on the `Tail' subtree. E.g., if +%% `Tail' represents `[X, Y]', the result may %% represent "<code>[<em>Head</em>, X, Y]</code>", rather than %% "<code>[<em>Head</em> | [X, Y]]</code>". Annotations on -%% <code>Tail</code> itself may be lost if <code>Tail</code> represents -%% a list skeleton, but comments on <code>Tail</code> are propagated to +%% `Tail' itself may be lost if `Tail' represents +%% a list skeleton, but comments on `Tail' are propagated to %% the result. %% %% @see list/2 @@ -2308,10 +2147,8 @@ cons(Head, Tail) -> %% ===================================================================== -%% @spec list_head(Node::syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the head element subtree of a <code>list</code> node. If -%% <code>Node</code> represents "<code>[<em>Head</em> ...]</code>", the +%% @doc Returns the head element subtree of a `list' node. If +%% `Node' represents "<code>[<em>Head</em> ...]</code>", the %% result will represent "<code><em>Head</em></code>". %% %% @see list/2 @@ -2325,15 +2162,13 @@ list_head(Node) -> %% ===================================================================== -%% @spec list_tail(Node::syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the tail of a <code>list</code> node. If -%% <code>Node</code> represents a single-element list +%% @doc Returns the tail of a `list' node. If +%% `Node' represents a single-element list %% "<code>[<em>E</em>]</code>", then the result has type -%% <code>nil</code>, representing "<code>[]</code>". If -%% <code>Node</code> represents "<code>[<em>E1</em>, <em>E2</em> +%% `nil', representing "`[]'". If +%% `Node' represents "<code>[<em>E1</em>, <em>E2</em> %% ...]</code>", the result will represent "<code>[<em>E2</em> -%% ...]</code>", and if <code>Node</code> represents +%% ...]</code>", and if `Node' represents %% "<code>[<em>Head</em> | <em>Tail</em>]</code>", the result will %% represent "<code><em>Tail</em></code>". %% @@ -2358,10 +2193,8 @@ list_tail(Node) -> %% ===================================================================== -%% @spec is_list_skeleton(syntaxTree()) -> boolean() -%% -%% @doc Returns <code>true</code> if <code>Node</code> has type -%% <code>list</code> or <code>nil</code>, otherwise <code>false</code>. +%% @doc Returns `true' if `Node' has type +%% `list' or `nil', otherwise `false'. %% %% @see list/2 %% @see nil/0 @@ -2377,24 +2210,22 @@ is_list_skeleton(Node) -> %% ===================================================================== -%% @spec is_proper_list(Node::syntaxTree()) -> boolean() -%% -%% @doc Returns <code>true</code> if <code>Node</code> represents a -%% proper list, and <code>false</code> otherwise. A proper list is a -%% list skeleton either on the form "<code>[]</code>" or +%% @doc Returns `true' if `Node' represents a +%% proper list, and `false' otherwise. A proper list is a +%% list skeleton either on the form "`[]'" or %% "<code>[<em>E1</em>, ..., <em>En</em>]</code>", or "<code>[... | -%% <em>Tail</em>]</code>" where recursively <code>Tail</code> also +%% <em>Tail</em>]</code>" where recursively `Tail' also %% represents a proper list. %% -%% <p>Note: Since <code>Node</code> is a syntax tree, the actual +%% Note: Since `Node' is a syntax tree, the actual %% run-time values corresponding to its subtrees may often be partially -%% or completely unknown. Thus, if <code>Node</code> represents e.g. -%% "<code>[... | Ns]</code>" (where <code>Ns</code> is a variable), then -%% the function will return <code>false</code>, because it is not known -%% whether <code>Ns</code> will be bound to a list at run-time. If -%% <code>Node</code> instead represents e.g. "<code>[1, 2, 3]</code>" or -%% "<code>[A | []]</code>", then the function will return -%% <code>true</code>.</p> +%% or completely unknown. Thus, if `Node' represents e.g. +%% "`[... | Ns]'" (where `Ns' is a variable), then +%% the function will return `false', because it is not known +%% whether `Ns' will be bound to a list at run-time. If +%% `Node' instead represents e.g. "`[1, 2, 3]'" or +%% "`[A | []]'", then the function will return +%% `true'. %% %% @see list/2 @@ -2417,14 +2248,11 @@ is_proper_list(Node) -> %% ===================================================================== -%% @spec list_elements(Node::syntaxTree()) -> [syntaxTree()] -%% %% @doc Returns the list of element subtrees of a list skeleton. -%% <code>Node</code> must represent a proper list. E.g., if -%% <code>Node</code> represents "<code>[<em>X1</em>, <em>X2</em> | +%% `Node' must represent a proper list. E.g., if +%% `Node' represents "<code>[<em>X1</em>, <em>X2</em> | %% [<em>X3</em>, <em>X4</em> | []]</code>", then -%% <code>list_elements(Node)</code> yields the list <code>[X1, X2, X3, -%% X4]</code>. +%% `list_elements(Node)' yields the list `[X1, X2, X3, X4]'. %% %% @see list/2 %% @see is_proper_list/1 @@ -2450,17 +2278,15 @@ list_elements(Node, As) -> %% ===================================================================== -%% @spec list_length(Node::syntaxTree()) -> integer() -%% %% @doc Returns the number of element subtrees of a list skeleton. -%% <code>Node</code> must represent a proper list. E.g., if -%% <code>Node</code> represents "<code>[X1 | [X2, X3 | [X4, X5, -%% X6]]]</code>", then <code>list_length(Node)</code> returns the +%% `Node' must represent a proper list. E.g., if +%% `Node' represents "`[X1 | [X2, X3 | [X4, X5, +%% X6]]]'", then `list_length(Node)' returns the %% integer 6. %% -%% <p>Note: this is equivalent to -%% <code>length(list_elements(Node))</code>, but potentially more -%% efficient.</p> +%% Note: this is equivalent to +%% `length(list_elements(Node))', but potentially more +%% efficient. %% %% @see list/2 %% @see is_proper_list/1 @@ -2487,18 +2313,16 @@ list_length(Node, A) -> %% ===================================================================== -%% @spec normalize_list(Node::syntaxTree()) -> syntaxTree() -%% %% @doc Expands an abstract list skeleton to its most explicit form. If -%% <code>Node</code> represents "<code>[<em>E1</em>, ..., <em>En</em> | +%% `Node' represents "<code>[<em>E1</em>, ..., <em>En</em> | %% <em>Tail</em>]</code>", the result represents "<code>[<em>E1</em> | %% ... [<em>En</em> | <em>Tail1</em>] ... ]</code>", where -%% <code>Tail1</code> is the result of -%% <code>normalize_list(Tail)</code>. If <code>Node</code> represents +%% `Tail1' is the result of +%% `normalize_list(Tail)'. If `Node' represents %% "<code>[<em>E1</em>, ..., <em>En</em>]</code>", the result simply %% represents "<code>[<em>E1</em> | ... [<em>En</em> | []] ... -%% ]</code>". If <code>Node</code> does not represent a list skeleton, -%% <code>Node</code> itself is returned. +%% ]</code>". If `Node' does not represent a list skeleton, +%% `Node' itself is returned. %% %% @see list/2 %% @see compact_list/1 @@ -2528,16 +2352,14 @@ normalize_list_1(Es, Tail) -> %% ===================================================================== -%% @spec compact_list(Node::syntaxTree()) -> syntaxTree() -%% %% @doc Yields the most compact form for an abstract list skeleton. The %% result either represents "<code>[<em>E1</em>, ..., <em>En</em> | -%% <em>Tail</em>]</code>", where <code>Tail</code> is not a list +%% <em>Tail</em>]</code>", where `Tail' is not a list %% skeleton, or otherwise simply "<code>[<em>E1</em>, ..., -%% <em>En</em>]</code>". Annotations on subtrees of <code>Node</code> +%% <em>En</em>]</code>". Annotations on subtrees of `Node' %% that represent list skeletons may be lost, but comments will be -%% propagated to the result. Returns <code>Node</code> itself if -%% <code>Node</code> does not represent a list skeleton. +%% propagated to the result. Returns `Node' itself if +%% `Node' does not represent a list skeleton. %% %% @see list/2 %% @see normalize_list/1 @@ -2575,10 +2397,8 @@ compact_list(Node) -> %% ===================================================================== -%% @spec binary(Fields::[syntaxTree()]) -> syntaxTree() -%% %% @doc Creates an abstract binary-object template. If -%% <code>Fields</code> is <code>[F1, ..., Fn]</code>, the result +%% `Fields' is `[F1, ..., Fn]', the result %% represents "<code><<<em>F1</em>, ..., %% <em>Fn</em>>></code>". %% @@ -2611,10 +2431,7 @@ revert_binary(Node) -> %% ===================================================================== -%% @spec binary_fields(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of field subtrees of a <code>binary</code> -%% node. +%% @doc Returns the list of field subtrees of a `binary' node. %% %% @see binary/1 %% @see binary_field/2 @@ -2631,7 +2448,6 @@ binary_fields(Node) -> %% ===================================================================== -%% @spec binary_field(Body) -> syntaxTree() %% @equiv binary_field(Body, []) -spec binary_field(syntaxTree()) -> syntaxTree(). @@ -2641,15 +2457,11 @@ binary_field(Body) -> %% ===================================================================== -%% @spec binary_field(Body::syntaxTree(), Size, -%% Types::[syntaxTree()]) -> syntaxTree() -%% Size = none | syntaxTree() -%% %% @doc Creates an abstract binary template field. -%% If <code>Size</code> is <code>none</code>, this is equivalent to -%% "<code>binary_field(Body, Types)</code>", otherwise it is -%% equivalent to "<code>binary_field(size_qualifier(Body, Size), -%% Types)</code>". +%% If `Size' is `none', this is equivalent to +%% "`binary_field(Body, Types)'", otherwise it is +%% equivalent to "`binary_field(size_qualifier(Body, Size), +%% Types)'". %% %% (This is a utility function.) %% @@ -2667,13 +2479,10 @@ binary_field(Body, Size, Types) -> %% ===================================================================== -%% @spec binary_field(Body::syntaxTree(), Types::[syntaxTree()]) -> -%% syntaxTree() -%% %% @doc Creates an abstract binary template field. If -%% <code>Types</code> is the empty list, the result simply represents -%% "<code><em>Body</em></code>", otherwise, if <code>Types</code> is -%% <code>[T1, ..., Tn]</code>, the result represents +%% `Types' is the empty list, the result simply represents +%% "<code><em>Body</em></code>", otherwise, if `Types' is +%% `[T1, ..., Tn]', the result represents %% "<code><em>Body</em>/<em>T1</em>-...-<em>Tn</em></code>". %% %% @see binary/1 @@ -2727,9 +2536,7 @@ revert_binary_field(Node) -> %% ===================================================================== -%% @spec binary_field_body(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the body subtree of a <code>binary_field</code>. +%% @doc Returns the body subtree of a `binary_field'. %% %% @see binary_field/2 @@ -2749,12 +2556,10 @@ binary_field_body(Node) -> %% ===================================================================== -%% @spec binary_field_types(Node::syntaxTree()) -> [syntaxTree()] -%% %% @doc Returns the list of type-specifier subtrees of a -%% <code>binary_field</code> node. If <code>Node</code> represents +%% `binary_field' node. If `Node' represents %% "<code>.../<em>T1</em>, ..., <em>Tn</em></code>", the result is -%% <code>[T1, ..., Tn]</code>, otherwise the result is the empty list. +%% `[T1, ..., Tn]', otherwise the result is the empty list. %% %% @see binary_field/2 @@ -2774,14 +2579,12 @@ binary_field_types(Node) -> %% ===================================================================== -%% @spec binary_field_size(Node::syntaxTree()) -> none | syntaxTree() -%% %% @doc Returns the size specifier subtree of a -%% <code>binary_field</code> node, if any. If <code>Node</code> +%% `binary_field' node, if any. If `Node' %% represents "<code><em>Body</em>:<em>Size</em></code>" or %% "<code><em>Body</em>:<em>Size</em>/<em>T1</em>, ..., -%% <em>Tn</em></code>", the result is <code>Size</code>, otherwise -%% <code>none</code> is returned. +%% <em>Tn</em></code>", the result is `Size', otherwise +%% `none' is returned. %% %% (This is a utility function.) %% @@ -2810,9 +2613,6 @@ binary_field_size(Node) -> %% ===================================================================== -%% @spec size_qualifier(Body::syntaxTree(), Size::syntaxTree()) -> -%% syntaxTree() -%% %% @doc Creates an abstract size qualifier. The result represents %% "<code><em>Body</em>:<em>Size</em></code>". %% @@ -2834,10 +2634,7 @@ size_qualifier(Body, Size) -> %% ===================================================================== -%% @spec size_qualifier_body(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the body subtree of a <code>size_qualifier</code> -%% node. +%% @doc Returns the body subtree of a `size_qualifier' node. %% %% @see size_qualifier/2 @@ -2848,10 +2645,8 @@ size_qualifier_body(Node) -> %% ===================================================================== -%% @spec size_qualifier_argument(syntaxTree()) -> syntaxTree() -%% %% @doc Returns the argument subtree (the size) of a -%% <code>size_qualifier</code> node. +%% `size_qualifier' node. %% %% @see size_qualifier/2 @@ -2862,16 +2657,14 @@ size_qualifier_argument(Node) -> %% ===================================================================== -%% @spec error_marker(Error::term()) -> syntaxTree() -%% %% @doc Creates an abstract error marker. The result represents an %% occurrence of an error in the source code, with an associated Erlang -%% I/O ErrorInfo structure given by <code>Error</code> (see module +%% I/O ErrorInfo structure given by `Error' (see module %% {@link //stdlib/io} for details). Error markers are regarded as source %% code forms, but have no defined lexical form. %% -%% <p>Note: this is supported only for backwards compatibility with -%% existing parsers and tools.</p> +%% Note: this is supported only for backwards compatibility with +%% existing parsers and tools. %% %% @see error_marker_info/1 %% @see warning_marker/1 @@ -2902,10 +2695,7 @@ revert_error_marker(Node) -> %% ===================================================================== -%% @spec error_marker_info(syntaxTree()) -> term() -%% -%% @doc Returns the ErrorInfo structure of an <code>error_marker</code> -%% node. +%% @doc Returns the ErrorInfo structure of an `error_marker' node. %% %% @see error_marker/1 @@ -2921,16 +2711,14 @@ error_marker_info(Node) -> %% ===================================================================== -%% @spec warning_marker(Error::term()) -> syntaxTree() -%% %% @doc Creates an abstract warning marker. The result represents an %% occurrence of a possible problem in the source code, with an -%% associated Erlang I/O ErrorInfo structure given by <code>Error</code> +%% associated Erlang I/O ErrorInfo structure given by `Error' %% (see module {@link //stdlib/io} for details). Warning markers are %% regarded as source code forms, but have no defined lexical form. %% -%% <p>Note: this is supported only for backwards compatibility with -%% existing parsers and tools.</p> +%% Note: this is supported only for backwards compatibility with +%% existing parsers and tools. %% %% @see warning_marker_info/1 %% @see error_marker/1 @@ -2961,10 +2749,7 @@ revert_warning_marker(Node) -> %% ===================================================================== -%% @spec warning_marker_info(syntaxTree()) -> term() -%% -%% @doc Returns the ErrorInfo structure of a <code>warning_marker</code> -%% node. +%% @doc Returns the ErrorInfo structure of a `warning_marker' node. %% %% @see warning_marker/1 @@ -2980,16 +2765,14 @@ warning_marker_info(Node) -> %% ===================================================================== -%% @spec eof_marker() -> syntaxTree() -%% %% @doc Creates an abstract end-of-file marker. This represents the %% end of input when reading a sequence of source code forms. An %% end-of-file marker is itself regarded as a source code form %% (namely, the last in any sequence in which it occurs). It has no %% defined lexical form. %% -%% <p>Note: this is retained only for backwards compatibility with -%% existing parsers and tools.</p> +%% Note: this is retained only for backwards compatibility with +%% existing parsers and tools. %% %% @see error_marker/1 %% @see warning_marker/1 @@ -3013,7 +2796,6 @@ revert_eof_marker(Node) -> %% ===================================================================== -%% @spec attribute(Name) -> syntaxTree() %% @equiv attribute(Name, none) -spec attribute(syntaxTree()) -> syntaxTree(). @@ -3023,23 +2805,20 @@ attribute(Name) -> %% ===================================================================== -%% @spec attribute(Name::syntaxTree(), Arguments) -> syntaxTree() -%% Arguments = none | [syntaxTree()] -%% %% @doc Creates an abstract program attribute. If -%% <code>Arguments</code> is <code>[A1, ..., An]</code>, the result +%% `Arguments' is `[A1, ..., An]', the result %% represents "<code>-<em>Name</em>(<em>A1</em>, ..., -%% <em>An</em>).</code>". Otherwise, if <code>Arguments</code> is -%% <code>none</code>, the result represents +%% <em>An</em>).</code>". Otherwise, if `Arguments' is +%% `none', the result represents %% "<code>-<em>Name</em>.</code>". The latter form makes it possible %% to represent preprocessor directives such as -%% "<code>-endif.</code>". Attributes are source code forms. +%% "`-endif.'". Attributes are source code forms. %% -%% <p>Note: The preprocessor macro definition directive +%% Note: The preprocessor macro definition directive %% "<code>-define(<em>Name</em>, <em>Body</em>).</code>" has relatively -%% few requirements on the syntactical form of <code>Body</code> (viewed -%% as a sequence of tokens). The <code>text</code> node type can be used -%% for a <code>Body</code> that is not a normal Erlang construct.</p> +%% few requirements on the syntactical form of `Body' (viewed +%% as a sequence of tokens). The `text' node type can be used +%% for a `Body' that is not a normal Erlang construct. %% %% @see attribute/1 %% @see attribute_name/1 @@ -3233,9 +3012,7 @@ revert_module_name(A) -> %% ===================================================================== -%% @spec attribute_name(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the name subtree of an <code>attribute</code> node. +%% @doc Returns the name subtree of an `attribute' node. %% %% @see attribute/1 @@ -3251,15 +3028,12 @@ attribute_name(Node) -> %% ===================================================================== -%% @spec attribute_arguments(Node::syntaxTree()) -> -%% none | [syntaxTree()] -%% %% @doc Returns the list of argument subtrees of an -%% <code>attribute</code> node, if any. If <code>Node</code> +%% `attribute' node, if any. If `Node' %% represents "<code>-<em>Name</em>.</code>", the result is -%% <code>none</code>. Otherwise, if <code>Node</code> represents +%% `none'. Otherwise, if `Node' represents %% "<code>-<em>Name</em>(<em>E1</em>, ..., <em>En</em>).</code>", -%% <code>[E1, ..., E1]</code> is returned. +%% `[E1, ..., E1]' is returned. %% %% @see attribute/1 @@ -3326,9 +3100,6 @@ attribute_arguments(Node) -> %% ===================================================================== -%% @spec arity_qualifier(Body::syntaxTree(), Arity::syntaxTree()) -> -%% syntaxTree() -%% %% @doc Creates an abstract arity qualifier. The result represents %% "<code><em>Body</em>/<em>Arity</em></code>". %% @@ -3350,10 +3121,7 @@ arity_qualifier(Body, Arity) -> %% ===================================================================== -%% @spec arity_qualifier_body(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the body subtree of an <code>arity_qualifier</code> -%% node. +%% @doc Returns the body subtree of an `arity_qualifier' node. %% %% @see arity_qualifier/2 @@ -3364,10 +3132,8 @@ arity_qualifier_body(Node) -> %% ===================================================================== -%% @spec arity_qualifier_argument(syntaxTree()) -> syntaxTree() -%% %% @doc Returns the argument (the arity) subtree of an -%% <code>arity_qualifier</code> node. +%% `arity_qualifier' node. %% %% @see arity_qualifier/2 @@ -3378,9 +3144,6 @@ arity_qualifier_argument(Node) -> %% ===================================================================== -%% @spec module_qualifier(Module::syntaxTree(), Body::syntaxTree()) -> -%% syntaxTree() -%% %% @doc Creates an abstract module qualifier. The result represents %% "<code><em>Module</em>:<em>Body</em></code>". %% @@ -3414,10 +3177,8 @@ revert_module_qualifier(Node) -> %% ===================================================================== -%% @spec module_qualifier_argument(syntaxTree()) -> syntaxTree() -%% %% @doc Returns the argument (the module) subtree of a -%% <code>module_qualifier</code> node. +%% `module_qualifier' node. %% %% @see module_qualifier/2 @@ -3433,10 +3194,7 @@ module_qualifier_argument(Node) -> %% ===================================================================== -%% @spec module_qualifier_body(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the body subtree of a <code>module_qualifier</code> -%% node. +%% @doc Returns the body subtree of a `module_qualifier' node. %% %% @see module_qualifier/2 @@ -3452,11 +3210,9 @@ module_qualifier_body(Node) -> %% ===================================================================== -%% @spec qualified_name(Segments::[syntaxTree()]) -> syntaxTree() -%% %% @doc Creates an abstract qualified name. The result represents %% "<code><em>S1</em>.<em>S2</em>. ... .<em>Sn</em></code>", if -%% <code>Segments</code> is <code>[S1, S2, ..., Sn]</code>. +%% `Segments' is `[S1, S2, ..., Sn]'. %% %% @see qualified_name_segments/1 @@ -3484,10 +3240,8 @@ revert_qualified_name(Node) -> %% ===================================================================== -%% @spec qualified_name_segments(syntaxTree()) -> [syntaxTree()] -%% %% @doc Returns the list of name segments of a -%% <code>qualified_name</code> node. +%% `qualified_name' node. %% %% @see qualified_name/1 @@ -3503,13 +3257,10 @@ qualified_name_segments(Node) -> %% ===================================================================== -%% @spec function(Name::syntaxTree(), Clauses::[syntaxTree()]) -> -%% syntaxTree() -%% -%% @doc Creates an abstract function definition. If <code>Clauses</code> -%% is <code>[C1, ..., Cn]</code>, the result represents +%% @doc Creates an abstract function definition. If `Clauses' +%% is `[C1, ..., Cn]', the result represents %% "<code><em>Name</em> <em>C1</em>; ...; <em>Name</em> -%% <em>Cn</em>.</code>". More exactly, if each <code>Ci</code> +%% <em>Cn</em>.</code>". More exactly, if each `Ci' %% represents "<code>(<em>Pi1</em>, ..., <em>Pim</em>) <em>Gi</em> -> %% <em>Bi</em></code>", then the result represents %% "<code><em>Name</em>(<em>P11</em>, ..., <em>P1m</em>) <em>G1</em> -> @@ -3523,13 +3274,12 @@ qualified_name_segments(Node) -> %% @see is_form/1 %% @see rule/2 --record(function, {name, clauses}). -%% XXX: This one is problematic because there is a tuple with the same -%% tag and size that comes from 'erl_parse' -%% -record(function, {name :: syntaxTree(), clauses :: [syntaxTree()]}). +%% Don't use the name 'function' for this record, to avoid confusion with +%% the tuples on the form {function,Name,Arity} used by erl_parse. +-record(func, {name :: syntaxTree(), clauses :: [syntaxTree()]}). %% type(Node) = function -%% data(Node) = #function{name :: Name, clauses :: Clauses} +%% data(Node) = #func{name :: Name, clauses :: Clauses} %% %% Name = syntaxTree() %% Clauses = [syntaxTree()] @@ -3556,7 +3306,7 @@ qualified_name_segments(Node) -> -spec function(syntaxTree(), [syntaxTree()]) -> syntaxTree(). function(Name, Clauses) -> - tree(function, #function{name = Name, clauses = Clauses}). + tree(function, #func{name = Name, clauses = Clauses}). revert_function(Node) -> Name = function_name(Node), @@ -3572,9 +3322,7 @@ revert_function(Node) -> %% ===================================================================== -%% @spec function_name(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the name subtree of a <code>function</code> node. +%% @doc Returns the name subtree of a `function' node. %% %% @see function/2 @@ -3585,15 +3333,12 @@ function_name(Node) -> {function, Pos, Name, _, _} -> set_pos(atom(Name), Pos); Node1 -> - (data(Node1))#function.name + (data(Node1))#func.name end. %% ===================================================================== -%% @spec function_clauses(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of clause subtrees of a <code>function</code> -%% node. +%% @doc Returns the list of clause subtrees of a `function' node. %% %% @see function/2 @@ -3604,21 +3349,19 @@ function_clauses(Node) -> {function, _, _, _, Clauses} -> Clauses; Node1 -> - (data(Node1))#function.clauses + (data(Node1))#func.clauses end. %% ===================================================================== -%% @spec function_arity(Node::syntaxTree()) -> integer() -%% -%% @doc Returns the arity of a <code>function</code> node. The result +%% @doc Returns the arity of a `function' node. The result %% is the number of parameter patterns in the first clause of the %% function; subsequent clauses are ignored. %% -%% <p>An exception is thrown if <code>function_clauses(Node)</code> +%% An exception is thrown if `function_clauses(Node)' %% returns an empty list, or if the first element of that list is not -%% a syntax tree <code>C</code> of type <code>clause</code> such that -%% <code>clause_patterns(C)</code> is a nonempty list.</p> +%% a syntax tree `C' of type `clause' such that +%% `clause_patterns(C)' is a nonempty list. %% %% @see function/2 %% @see function_clauses/1 @@ -3634,7 +3377,6 @@ function_arity(Node) -> %% ===================================================================== -%% @spec clause(Guard, Body) -> syntaxTree() %% @equiv clause([], Guard, Body) -type guard() :: 'none' | syntaxTree() | [syntaxTree()] | [[syntaxTree()]]. @@ -3646,34 +3388,28 @@ clause(Guard, Body) -> %% ===================================================================== -%% @spec clause(Patterns::[syntaxTree()], Guard, -%% Body::[syntaxTree()]) -> syntaxTree() -%% Guard = none | syntaxTree() -%% | [syntaxTree()] | [[syntaxTree()]] -%% -%% @doc Creates an abstract clause. If <code>Patterns</code> is -%% <code>[P1, ..., Pn]</code> and <code>Body</code> is <code>[B1, ..., -%% Bm]</code>, then if <code>Guard</code> is <code>none</code>, the +%% @doc Creates an abstract clause. If `Patterns' is +%% `[P1, ..., Pn]' and `Body' is `[B1, ..., +%% Bm]', then if `Guard' is `none', the %% result represents "<code>(<em>P1</em>, ..., <em>Pn</em>) -> %% <em>B1</em>, ..., <em>Bm</em></code>", otherwise, unless -%% <code>Guard</code> is a list, the result represents +%% `Guard' is a list, the result represents %% "<code>(<em>P1</em>, ..., <em>Pn</em>) when <em>Guard</em> -> %% <em>B1</em>, ..., <em>Bm</em></code>". %% -%% <p>For simplicity, the <code>Guard</code> argument may also be any +%% For simplicity, the `Guard' argument may also be any %% of the following: %% <ul> -%% <li>An empty list <code>[]</code>. This is equivalent to passing -%% <code>none</code>.</li> -%% <li>A nonempty list <code>[E1, ..., Ej]</code> of syntax trees. -%% This is equivalent to passing <code>conjunction([E1, ..., -%% Ej])</code>.</li> -%% <li>A nonempty list of lists of syntax trees <code>[[E1_1, ..., -%% E1_k1], ..., [Ej_1, ..., Ej_kj]]</code>, which is equivalent -%% to passing <code>disjunction([conjunction([E1_1, ..., -%% E1_k1]), ..., conjunction([Ej_1, ..., Ej_kj])])</code>.</li> +%% <li>An empty list `[]'. This is equivalent to passing +%% `none'.</li> +%% <li>A nonempty list `[E1, ..., Ej]' of syntax trees. +%% This is equivalent to passing `conjunction([E1, ..., +%% Ej])'.</li> +%% <li>A nonempty list of lists of syntax trees `[[E1_1, ..., +%% E1_k1], ..., [Ej_1, ..., Ej_kj]]', which is equivalent +%% to passing `disjunction([conjunction([E1_1, ..., +%% E1_k1]), ..., conjunction([Ej_1, ..., Ej_kj])])'.</li> %% </ul> -%% </p> %% %% @see clause/2 %% @see clause_patterns/1 @@ -3789,10 +3525,7 @@ unfold_try_clause({clause, Pos, [{tuple, _, [C, V, _]}], %% ===================================================================== -%% @spec clause_patterns(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of pattern subtrees of a <code>clause</code> -%% node. +%% @doc Returns the list of pattern subtrees of a `clause' node. %% %% @see clause/3 @@ -3808,13 +3541,11 @@ clause_patterns(Node) -> %% ===================================================================== -%% @spec clause_guard(Node::syntaxTree()) -> none | syntaxTree() -%% -%% @doc Returns the guard subtree of a <code>clause</code> node, if -%% any. If <code>Node</code> represents "<code>(<em>P1</em>, ..., +%% @doc Returns the guard subtree of a `clause' node, if +%% any. If `Node' represents "<code>(<em>P1</em>, ..., %% <em>Pn</em>) when <em>Guard</em> -> <em>B1</em>, ..., -%% <em>Bm</em></code>", <code>Guard</code> is returned. Otherwise, the -%% result is <code>none</code>. +%% <em>Bm</em></code>", `Guard' is returned. Otherwise, the +%% result is `none'. %% %% @see clause/3 @@ -3836,10 +3567,7 @@ clause_guard(Node) -> %% ===================================================================== -%% @spec clause_body(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Return the list of body subtrees of a <code>clause</code> -%% node. +%% @doc Return the list of body subtrees of a `clause' node. %% %% @see clause/3 @@ -3855,10 +3583,8 @@ clause_body(Node) -> %% ===================================================================== -%% @spec disjunction(List::[syntaxTree()]) -> syntaxTree() -%% -%% @doc Creates an abstract disjunction. If <code>List</code> is -%% <code>[E1, ..., En]</code>, the result represents +%% @doc Creates an abstract disjunction. If `List' is +%% `[E1, ..., En]', the result represents %% "<code><em>E1</em>; ...; <em>En</em></code>". %% %% @see disjunction_body/1 @@ -3874,10 +3600,8 @@ disjunction(Tests) -> %% ===================================================================== -%% @spec disjunction_body(syntaxTree()) -> [syntaxTree()] -%% %% @doc Returns the list of body subtrees of a -%% <code>disjunction</code> node. +%% `disjunction' node. %% %% @see disjunction/1 @@ -3888,10 +3612,8 @@ disjunction_body(Node) -> %% ===================================================================== -%% @spec conjunction(List::[syntaxTree()]) -> syntaxTree() -%% -%% @doc Creates an abstract conjunction. If <code>List</code> is -%% <code>[E1, ..., En]</code>, the result represents +%% @doc Creates an abstract conjunction. If `List' is +%% `[E1, ..., En]', the result represents %% "<code><em>E1</em>, ..., <em>En</em></code>". %% %% @see conjunction_body/1 @@ -3907,10 +3629,8 @@ conjunction(Tests) -> %% ===================================================================== -%% @spec conjunction_body(syntaxTree()) -> [syntaxTree()] -%% %% @doc Returns the list of body subtrees of a -%% <code>conjunction</code> node. +%% `conjunction' node. %% %% @see conjunction/1 @@ -3921,8 +3641,6 @@ conjunction_body(Node) -> %% ===================================================================== -%% @spec catch_expr(Expr::syntaxTree()) -> syntaxTree() -%% %% @doc Creates an abstract catch-expression. The result represents %% "<code>catch <em>Expr</em></code>". %% @@ -3949,9 +3667,7 @@ revert_catch_expr(Node) -> %% ===================================================================== -%% @spec catch_expr_body(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the body subtree of a <code>catch_expr</code> node. +%% @doc Returns the body subtree of a `catch_expr' node. %% %% @see catch_expr/1 @@ -3967,9 +3683,6 @@ catch_expr_body(Node) -> %% ===================================================================== -%% @spec match_expr(Pattern::syntaxTree(), Body::syntaxTree()) -> -%% syntaxTree() -%% %% @doc Creates an abstract match-expression. The result represents %% "<code><em>Pattern</em> = <em>Body</em></code>". %% @@ -4002,9 +3715,7 @@ revert_match_expr(Node) -> %% ===================================================================== -%% @spec match_expr_pattern(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the pattern subtree of a <code>match_expr</code> node. +%% @doc Returns the pattern subtree of a `match_expr' node. %% %% @see match_expr/2 @@ -4020,9 +3731,7 @@ match_expr_pattern(Node) -> %% ===================================================================== -%% @spec match_expr_body(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the body subtree of a <code>match_expr</code> node. +%% @doc Returns the body subtree of a `match_expr' node. %% %% @see match_expr/2 @@ -4038,15 +3747,12 @@ match_expr_body(Node) -> %% ===================================================================== -%% @spec operator(Name) -> syntaxTree() -%% Name = atom() | string() -%% %% @doc Creates an abstract operator. The name of the operator is the -%% character sequence represented by <code>Name</code>. This is +%% character sequence represented by `Name'. This is %% analogous to the print name of an atom, but an operator is never %% written within single-quotes; e.g., the result of -%% <code>operator('++')</code> represents "<code>++</code>" rather -%% than "<code>'++'</code>". +%% `operator('++')' represents "`++'" rather +%% than "`'++''". %% %% @see operator_name/1 %% @see operator_literal/1 @@ -4064,9 +3770,7 @@ operator(Name) -> %% ===================================================================== -%% @spec operator_name(syntaxTree()) -> atom() -%% -%% @doc Returns the name of an <code>operator</code> node. Note that +%% @doc Returns the name of an `operator' node. Note that %% the name is returned as an atom. %% %% @see operator/1 @@ -4078,11 +3782,8 @@ operator_name(Node) -> %% ===================================================================== -%% @spec operator_literal(syntaxTree()) -> string() -%% %% @doc Returns the literal string represented by an -%% <code>operator</code> node. This is simply the operator name as a -%% string. +%% `operator' node. This is simply the operator name as a string. %% %% @see operator/1 @@ -4093,9 +3794,6 @@ operator_literal(Node) -> %% ===================================================================== -%% @spec infix_expr(Left::syntaxTree(), Operator::syntaxTree(), -%% Right::syntaxTree()) -> syntaxTree() -%% %% @doc Creates an abstract infix operator expression. The result %% represents "<code><em>Left</em> <em>Operator</em> %% <em>Right</em></code>". @@ -4144,10 +3842,8 @@ revert_infix_expr(Node) -> %% ===================================================================== -%% @spec infix_expr_left(syntaxTree()) -> syntaxTree() -%% %% @doc Returns the left argument subtree of an -%% <code>infix_expr</code> node. +%% `infix_expr' node. %% %% @see infix_expr/3 @@ -4163,10 +3859,7 @@ infix_expr_left(Node) -> %% ===================================================================== -%% @spec infix_expr_operator(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the operator subtree of an <code>infix_expr</code> -%% node. +%% @doc Returns the operator subtree of an `infix_expr' node. %% %% @see infix_expr/3 @@ -4182,10 +3875,8 @@ infix_expr_operator(Node) -> %% ===================================================================== -%% @spec infix_expr_right(syntaxTree()) -> syntaxTree() -%% %% @doc Returns the right argument subtree of an -%% <code>infix_expr</code> node. +%% `infix_expr' node. %% %% @see infix_expr/3 @@ -4201,9 +3892,6 @@ infix_expr_right(Node) -> %% ===================================================================== -%% @spec prefix_expr(Operator::syntaxTree(), Argument::syntaxTree()) -> -%% syntaxTree() -%% %% @doc Creates an abstract prefix operator expression. The result %% represents "<code><em>Operator</em> <em>Argument</em></code>". %% @@ -4247,10 +3935,7 @@ revert_prefix_expr(Node) -> %% ===================================================================== -%% @spec prefix_expr_operator(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the operator subtree of a <code>prefix_expr</code> -%% node. +%% @doc Returns the operator subtree of a `prefix_expr' node. %% %% @see prefix_expr/2 @@ -4266,10 +3951,7 @@ prefix_expr_operator(Node) -> %% ===================================================================== -%% @spec prefix_expr_argument(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the argument subtree of a <code>prefix_expr</code> -%% node. +%% @doc Returns the argument subtree of a `prefix_expr' node. %% %% @see prefix_expr/2 @@ -4285,7 +3967,6 @@ prefix_expr_argument(Node) -> %% ===================================================================== -%% @spec record_field(Name) -> syntaxTree() %% @equiv record_field(Name, none) -spec record_field(syntaxTree()) -> syntaxTree(). @@ -4295,11 +3976,8 @@ record_field(Name) -> %% ===================================================================== -%% @spec record_field(Name::syntaxTree(), Value) -> syntaxTree() -%% Value = none | syntaxTree() -%% %% @doc Creates an abstract record field specification. If -%% <code>Value</code> is <code>none</code>, the result represents +%% `Value' is `none', the result represents %% simply "<code><em>Name</em></code>", otherwise it represents %% "<code><em>Name</em> = <em>Value</em></code>". %% @@ -4321,9 +3999,7 @@ record_field(Name, Value) -> %% ===================================================================== -%% @spec record_field_name(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the name subtree of a <code>record_field</code> node. +%% @doc Returns the name subtree of a `record_field' node. %% %% @see record_field/2 @@ -4334,13 +4010,11 @@ record_field_name(Node) -> %% ===================================================================== -%% @spec record_field_value(syntaxTree()) -> none | syntaxTree() -%% -%% @doc Returns the value subtree of a <code>record_field</code> node, -%% if any. If <code>Node</code> represents -%% "<code><em>Name</em></code>", <code>none</code> is -%% returned. Otherwise, if <code>Node</code> represents -%% "<code><em>Name</em> = <em>Value</em></code>", <code>Value</code> +%% @doc Returns the value subtree of a `record_field' node, +%% if any. If `Node' represents +%% "<code><em>Name</em></code>", `none' is +%% returned. Otherwise, if `Node' represents +%% "<code><em>Name</em> = <em>Value</em></code>", `Value' %% is returned. %% %% @see record_field/2 @@ -4352,15 +4026,12 @@ record_field_value(Node) -> %% ===================================================================== -%% @spec record_index_expr(Type::syntaxTree(), Field::syntaxTree()) -> -%% syntaxTree() -%% %% @doc Creates an abstract record field index expression. The result %% represents "<code>#<em>Type</em>.<em>Field</em></code>". %% -%% <p>(Note: the function name <code>record_index/2</code> is reserved +%% (Note: the function name `record_index/2' is reserved %% by the Erlang compiler, which is why that name could not be used -%% for this constructor.)</p> +%% for this constructor.) %% %% @see record_index_expr_type/1 %% @see record_index_expr_field/1 @@ -4399,10 +4070,7 @@ revert_record_index_expr(Node) -> %% ===================================================================== -%% @spec record_index_expr_type(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the type subtree of a <code>record_index_expr</code> -%% node. +%% @doc Returns the type subtree of a `record_index_expr' node. %% %% @see record_index_expr/2 @@ -4418,10 +4086,7 @@ record_index_expr_type(Node) -> %% ===================================================================== -%% @spec record_index_expr_field(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the field subtree of a <code>record_index_expr</code> -%% node. +%% @doc Returns the field subtree of a `record_index_expr' node. %% %% @see record_index_expr/2 @@ -4437,7 +4102,6 @@ record_index_expr_field(Node) -> %% ===================================================================== -%% @spec record_access(Argument, Field) -> syntaxTree() %% @equiv record_access(Argument, none, Field) -spec record_access(syntaxTree(), syntaxTree()) -> syntaxTree(). @@ -4447,17 +4111,13 @@ record_access(Argument, Field) -> %% ===================================================================== -%% @spec record_access(Argument::syntaxTree(), Type, -%% Field::syntaxTree()) -> syntaxTree() -%% Type = none | syntaxTree() -%% %% @doc Creates an abstract record field access expression. If -%% <code>Type</code> is not <code>none</code>, the result represents +%% `Type' is not `none', the result represents %% "<code><em>Argument</em>#<em>Type</em>.<em>Field</em></code>". %% -%% <p>If <code>Type</code> is <code>none</code>, the result represents +%% If `Type' is `none', the result represents %% "<code><em>Argument</em>.<em>Field</em></code>". This is a special -%% form only allowed within Mnemosyne queries.</p> +%% form only allowed within Mnemosyne queries. %% %% @see record_access/2 %% @see record_access_argument/1 @@ -4512,10 +4172,7 @@ revert_record_access(Node) -> %% ===================================================================== -%% @spec record_access_argument(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the argument subtree of a <code>record_access</code> -%% node. +%% @doc Returns the argument subtree of a `record_access' node. %% %% @see record_access/3 @@ -4533,14 +4190,12 @@ record_access_argument(Node) -> %% ===================================================================== -%% @spec record_access_type(syntaxTree()) -> none | syntaxTree() -%% -%% @doc Returns the type subtree of a <code>record_access</code> node, -%% if any. If <code>Node</code> represents -%% "<code><em>Argument</em>.<em>Field</em></code>", <code>none</code> -%% is returned, otherwise if <code>Node</code> represents +%% @doc Returns the type subtree of a `record_access' node, +%% if any. If `Node' represents +%% "<code><em>Argument</em>.<em>Field</em></code>", `none' +%% is returned, otherwise if `Node' represents %% "<code><em>Argument</em>#<em>Type</em>.<em>Field</em></code>", -%% <code>Type</code> is returned. +%% `Type' is returned. %% %% @see record_access/3 @@ -4558,10 +4213,7 @@ record_access_type(Node) -> %% ===================================================================== -%% @spec record_access_field(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the field subtree of a <code>record_access</code> -%% node. +%% @doc Returns the field subtree of a `record_access' node. %% %% @see record_access/3 @@ -4579,7 +4231,6 @@ record_access_field(Node) -> %% ===================================================================== -%% @spec record_expr(Type, Fields) -> syntaxTree() %% @equiv record_expr(none, Type, Fields) -spec record_expr(syntaxTree(), [syntaxTree()]) -> syntaxTree(). @@ -4589,13 +4240,9 @@ record_expr(Type, Fields) -> %% ===================================================================== -%% @spec record_expr(Argument, Type::syntaxTree(), -%% Fields::[syntaxTree()]) -> syntaxTree() -%% Argument = none | syntaxTree() -%% -%% @doc Creates an abstract record expression. If <code>Fields</code> is -%% <code>[F1, ..., Fn]</code>, then if <code>Argument</code> is -%% <code>none</code>, the result represents +%% @doc Creates an abstract record expression. If `Fields' is +%% `[F1, ..., Fn]', then if `Argument' is +%% `none', the result represents %% "<code>#<em>Type</em>{<em>F1</em>, ..., <em>Fn</em>}</code>", %% otherwise it represents %% "<code><em>Argument</em>#<em>Type</em>{<em>F1</em>, ..., @@ -4661,14 +4308,12 @@ revert_record_expr(Node) -> %% ===================================================================== -%% @spec record_expr_argument(syntaxTree()) -> none | syntaxTree() -%% -%% @doc Returns the argument subtree of a <code>record_expr</code> node, -%% if any. If <code>Node</code> represents -%% "<code>#<em>Type</em>{...}</code>", <code>none</code> is returned. -%% Otherwise, if <code>Node</code> represents +%% @doc Returns the argument subtree of a `record_expr' node, +%% if any. If `Node' represents +%% "<code>#<em>Type</em>{...}</code>", `none' is returned. +%% Otherwise, if `Node' represents %% "<code><em>Argument</em>#<em>Type</em>{...}</code>", -%% <code>Argument</code> is returned. +%% `Argument' is returned. %% %% @see record_expr/3 @@ -4686,9 +4331,7 @@ record_expr_argument(Node) -> %% ===================================================================== -%% @spec record_expr_type(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the type subtree of a <code>record_expr</code> node. +%% @doc Returns the type subtree of a `record_expr' node. %% %% @see record_expr/3 @@ -4706,10 +4349,8 @@ record_expr_type(Node) -> %% ===================================================================== -%% @spec record_expr_fields(syntaxTree()) -> [syntaxTree()] -%% %% @doc Returns the list of field subtrees of a -%% <code>record_expr</code> node. +%% `record_expr' node. %% %% @see record_expr/3 @@ -4727,15 +4368,11 @@ record_expr_fields(Node) -> %% ===================================================================== -%% @spec application(Module, Function::syntaxTree(), -%% Arguments::[syntaxTree()]) -> syntaxTree() -%% Module = none | syntaxTree() -%% %% @doc Creates an abstract function application expression. If -%% <code>Module</code> is <code>none</code>, this is call is equivalent -%% to <code>application(Function, Arguments)</code>, otherwise it is -%% equivalent to <code>application(module_qualifier(Module, Function), -%% Arguments)</code>. +%% `Module' is `none', this is call is equivalent +%% to `application(Function, Arguments)', otherwise it is +%% equivalent to `application(module_qualifier(Module, Function), +%% Arguments)'. %% %% (This is a utility function.) %% @@ -4752,11 +4389,8 @@ application(Module, Name, Arguments) -> %% ===================================================================== -%% @spec application(Operator::syntaxTree(), -%% Arguments::[syntaxTree()]) -> syntaxTree() -%% %% @doc Creates an abstract function application expression. If -%% <code>Arguments</code> is <code>[A1, ..., An]</code>, the result +%% `Arguments' is `[A1, ..., An]', the result %% represents "<code><em>Operator</em>(<em>A1</em>, ..., %% <em>An</em>)</code>". %% @@ -4794,14 +4428,11 @@ revert_application(Node) -> %% ===================================================================== -%% @spec application_operator(syntaxTree()) -> syntaxTree() +%% @doc Returns the operator subtree of an `application' node. %% -%% @doc Returns the operator subtree of an <code>application</code> -%% node. -%% -%% <p>Note: if <code>Node</code> represents +%% Note: if `Node' represents %% "<code><em>M</em>:<em>F</em>(...)</code>", then the result is the -%% subtree representing "<code><em>M</em>:<em>F</em></code>".</p> +%% subtree representing "<code><em>M</em>:<em>F</em></code>". %% %% @see application/2 %% @see module_qualifier/2 @@ -4818,10 +4449,8 @@ application_operator(Node) -> %% ===================================================================== -%% @spec application_arguments(syntaxTree()) -> [syntaxTree()] -%% %% @doc Returns the list of argument subtrees of an -%% <code>application</code> node. +%% `application' node. %% %% @see application/2 @@ -4837,11 +4466,8 @@ application_arguments(Node) -> %% ===================================================================== -%% @spec list_comp(Template::syntaxTree(), Body::[syntaxTree()]) -> -%% syntaxTree() -%% -%% @doc Creates an abstract list comprehension. If <code>Body</code> is -%% <code>[E1, ..., En]</code>, the result represents +%% @doc Creates an abstract list comprehension. If `Body' is +%% `[E1, ..., En]', the result represents %% "<code>[<em>Template</em> || <em>E1</em>, ..., <em>En</em>]</code>". %% %% @see list_comp_template/1 @@ -4876,9 +4502,7 @@ revert_list_comp(Node) -> %% ===================================================================== -%% @spec list_comp_template(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the template subtree of a <code>list_comp</code> node. +%% @doc Returns the template subtree of a `list_comp' node. %% %% @see list_comp/2 @@ -4894,10 +4518,7 @@ list_comp_template(Node) -> %% ===================================================================== -%% @spec list_comp_body(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of body subtrees of a <code>list_comp</code> -%% node. +%% @doc Returns the list of body subtrees of a `list_comp' node. %% %% @see list_comp/2 @@ -4912,11 +4533,8 @@ list_comp_body(Node) -> end. %% ===================================================================== -%% @spec binary_comp(Template::syntaxTree(), Body::[syntaxTree()]) -> -%% syntaxTree() -%% -%% @doc Creates an abstract binary comprehension. If <code>Body</code> is -%% <code>[E1, ..., En]</code>, the result represents +%% @doc Creates an abstract binary comprehension. If `Body' is +%% `[E1, ..., En]', the result represents %% "<code><<<em>Template</em> || <em>E1</em>, ..., <em>En</em>>></code>". %% %% @see binary_comp_template/1 @@ -4951,9 +4569,7 @@ revert_binary_comp(Node) -> %% ===================================================================== -%% @spec binary_comp_template(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the template subtree of a <code>binary_comp</code> node. +%% @doc Returns the template subtree of a `binary_comp' node. %% %% @see binary_comp/2 @@ -4969,10 +4585,7 @@ binary_comp_template(Node) -> %% ===================================================================== -%% @spec binary_comp_body(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of body subtrees of a <code>binary_comp</code> -%% node. +%% @doc Returns the list of body subtrees of a `binary_comp' node. %% %% @see binary_comp/2 @@ -4988,8 +4601,6 @@ binary_comp_body(Node) -> %% ===================================================================== -%% @spec query_expr(Body::syntaxTree()) -> syntaxTree() -%% %% @doc Creates an abstract Mnemosyne query expression. The result %% represents "<code>query <em>Body</em> end</code>". %% @@ -5018,9 +4629,7 @@ revert_query_expr(Node) -> %% ===================================================================== -%% @spec query_expr_body(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the body subtree of a <code>query_expr</code> node. +%% @doc Returns the body subtree of a `query_expr' node. %% %% @see query_expr/1 @@ -5036,13 +4645,10 @@ query_expr_body(Node) -> %% ===================================================================== -%% @spec rule(Name::syntaxTree(), Clauses::[syntaxTree()]) -> -%% syntaxTree() -%% -%% @doc Creates an abstract Mnemosyne rule. If <code>Clauses</code> is -%% <code>[C1, ..., Cn]</code>, the results represents +%% @doc Creates an abstract Mnemosyne rule. If `Clauses' is +%% `[C1, ..., Cn]', the results represents %% "<code><em>Name</em> <em>C1</em>; ...; <em>Name</em> -%% <em>Cn</em>.</code>". More exactly, if each <code>Ci</code> +%% <em>Cn</em>.</code>". More exactly, if each `Ci' %% represents "<code>(<em>Pi1</em>, ..., <em>Pim</em>) <em>Gi</em> -> %% <em>Bi</em></code>", then the result represents %% "<code><em>Name</em>(<em>P11</em>, ..., <em>P1m</em>) <em>G1</em> :- @@ -5097,9 +4703,7 @@ revert_rule(Node) -> %% ===================================================================== -%% @spec rule_name(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the name subtree of a <code>rule</code> node. +%% @doc Returns the name subtree of a `rule' node. %% %% @see rule/2 @@ -5114,9 +4718,7 @@ rule_name(Node) -> end. %% ===================================================================== -%% @spec rule_clauses(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of clause subtrees of a <code>rule</code> node. +%% @doc Returns the list of clause subtrees of a `rule' node. %% %% @see rule/2 @@ -5131,16 +4733,14 @@ rule_clauses(Node) -> end. %% ===================================================================== -%% @spec rule_arity(Node::syntaxTree()) -> integer() -%% -%% @doc Returns the arity of a <code>rule</code> node. The result is the +%% @doc Returns the arity of a `rule' node. The result is the %% number of parameter patterns in the first clause of the rule; %% subsequent clauses are ignored. %% -%% <p>An exception is thrown if <code>rule_clauses(Node)</code> returns +%% An exception is thrown if `rule_clauses(Node)' returns %% an empty list, or if the first element of that list is not a syntax -%% tree <code>C</code> of type <code>clause</code> such that -%% <code>clause_patterns(C)</code> is a nonempty list.</p> +%% tree `C' of type `clause' such that +%% `clause_patterns(C)' is a nonempty list. %% %% @see rule/2 %% @see rule_clauses/1 @@ -5156,9 +4756,6 @@ rule_arity(Node) -> %% ===================================================================== -%% @spec generator(Pattern::syntaxTree(), Body::syntaxTree()) -> -%% syntaxTree() -%% %% @doc Creates an abstract generator. The result represents %% "<code><em>Pattern</em> <- <em>Body</em></code>". %% @@ -5193,9 +4790,7 @@ revert_generator(Node) -> %% ===================================================================== -%% @spec generator_pattern(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the pattern subtree of a <code>generator</code> node. +%% @doc Returns the pattern subtree of a `generator' node. %% %% @see generator/2 @@ -5211,9 +4806,7 @@ generator_pattern(Node) -> %% ===================================================================== -%% @spec generator_body(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the body subtree of a <code>generator</code> node. +%% @doc Returns the body subtree of a `generator' node. %% %% @see generator/2 @@ -5229,9 +4822,6 @@ generator_body(Node) -> %% ===================================================================== -%% @spec binary_generator(Pattern::syntaxTree(), Body::syntaxTree()) -> -%% syntaxTree() -%% %% @doc Creates an abstract binary_generator. The result represents %% "<code><em>Pattern</em> <- <em>Body</em></code>". %% @@ -5266,9 +4856,7 @@ revert_binary_generator(Node) -> %% ===================================================================== -%% @spec binary_generator_pattern(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the pattern subtree of a <code>generator</code> node. +%% @doc Returns the pattern subtree of a `generator' node. %% %% @see binary_generator/2 @@ -5284,9 +4872,7 @@ binary_generator_pattern(Node) -> %% ===================================================================== -%% @spec binary_generator_body(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the body subtree of a <code>generator</code> node. +%% @doc Returns the body subtree of a `generator' node. %% %% @see binary_generator/2 @@ -5302,10 +4888,8 @@ binary_generator_body(Node) -> %% ===================================================================== -%% @spec block_expr(Body::[syntaxTree()]) -> syntaxTree() -%% -%% @doc Creates an abstract block expression. If <code>Body</code> is -%% <code>[B1, ..., Bn]</code>, the result represents "<code>begin +%% @doc Creates an abstract block expression. If `Body' is +%% `[B1, ..., Bn]', the result represents "<code>begin %% <em>B1</em>, ..., <em>Bn</em> end</code>". %% %% @see block_expr_body/1 @@ -5321,7 +4905,7 @@ binary_generator_body(Node) -> %% %% Body = [erl_parse()] \ [] --spec block_expr(Body::[syntaxTree()]) -> syntaxTree(). +-spec block_expr([syntaxTree()]) -> syntaxTree(). block_expr(Body) -> tree(block_expr, Body). @@ -5333,10 +4917,7 @@ revert_block_expr(Node) -> %% ===================================================================== -%% @spec block_expr_body(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of body subtrees of a <code>block_expr</code> -%% node. +%% @doc Returns the list of body subtrees of a `block_expr' node. %% %% @see block_expr/1 @@ -5352,12 +4933,10 @@ block_expr_body(Node) -> %% ===================================================================== -%% @spec if_expr(Clauses::[syntaxTree()]) -> syntaxTree() -%% -%% @doc Creates an abstract if-expression. If <code>Clauses</code> is -%% <code>[C1, ..., Cn]</code>, the result represents "<code>if +%% @doc Creates an abstract if-expression. If `Clauses' is +%% `[C1, ..., Cn]', the result represents "<code>if %% <em>C1</em>; ...; <em>Cn</em> end</code>". More exactly, if each -%% <code>Ci</code> represents "<code>() <em>Gi</em> -> +%% `Ci' represents "<code>() <em>Gi</em> -> %% <em>Bi</em></code>", then the result represents "<code>if %% <em>G1</em> -> <em>B1</em>; ...; <em>Gn</em> -> <em>Bn</em> %% end</code>". @@ -5392,10 +4971,7 @@ revert_if_expr(Node) -> %% ===================================================================== -%% @spec if_expr_clauses(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of clause subtrees of an <code>if_expr</code> -%% node. +%% @doc Returns the list of clause subtrees of an `if_expr' node. %% %% @see if_expr/1 @@ -5411,13 +4987,10 @@ if_expr_clauses(Node) -> %% ===================================================================== -%% @spec case_expr(Argument::syntaxTree(), Clauses::[syntaxTree()]) -> -%% syntaxTree() -%% -%% @doc Creates an abstract case-expression. If <code>Clauses</code> is -%% <code>[C1, ..., Cn]</code>, the result represents "<code>case +%% @doc Creates an abstract case-expression. If `Clauses' is +%% `[C1, ..., Cn]', the result represents "<code>case %% <em>Argument</em> of <em>C1</em>; ...; <em>Cn</em> end</code>". More -%% exactly, if each <code>Ci</code> represents "<code>(<em>Pi</em>) +%% exactly, if each `Ci' represents "<code>(<em>Pi</em>) %% <em>Gi</em> -> <em>Bi</em></code>", then the result represents %% "<code>case <em>Argument</em> of <em>P1</em> <em>G1</em> -> %% <em>B1</em>; ...; <em>Pn</em> <em>Gn</em> -> <em>Bn</em> end</code>". @@ -5461,9 +5034,7 @@ revert_case_expr(Node) -> %% ===================================================================== -%% @spec case_expr_argument(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the argument subtree of a <code>case_expr</code> node. +%% @doc Returns the argument subtree of a `case_expr' node. %% %% @see case_expr/2 @@ -5479,10 +5050,7 @@ case_expr_argument(Node) -> %% ===================================================================== -%% @spec case_expr_clauses(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of clause subtrees of a <code>case_expr</code> -%% node. +%% @doc Returns the list of clause subtrees of a `case_expr' node. %% %% @see case_expr/2 @@ -5498,12 +5066,10 @@ case_expr_clauses(Node) -> %% ===================================================================== -%% @spec cond_expr(Clauses::[syntaxTree()]) -> syntaxTree() -%% -%% @doc Creates an abstract cond-expression. If <code>Clauses</code> is -%% <code>[C1, ..., Cn]</code>, the result represents "<code>cond +%% @doc Creates an abstract cond-expression. If `Clauses' is +%% `[C1, ..., Cn]', the result represents "<code>cond %% <em>C1</em>; ...; <em>Cn</em> end</code>". More exactly, if each -%% <code>Ci</code> represents "<code>() <em>Ei</em> -> +%% `Ci' represents "<code>() <em>Ei</em> -> %% <em>Bi</em></code>", then the result represents "<code>cond %% <em>E1</em> -> <em>B1</em>; ...; <em>En</em> -> <em>Bn</em> %% end</code>". @@ -5538,10 +5104,7 @@ revert_cond_expr(Node) -> %% ===================================================================== -%% @spec cond_expr_clauses(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of clause subtrees of a <code>cond_expr</code> -%% node. +%% @doc Returns the list of clause subtrees of a `cond_expr' node. %% %% @see cond_expr/1 @@ -5557,7 +5120,6 @@ cond_expr_clauses(Node) -> %% ===================================================================== -%% @spec receive_expr(Clauses) -> syntaxTree() %% @equiv receive_expr(Clauses, none, []) -spec receive_expr([syntaxTree()]) -> syntaxTree(). @@ -5567,25 +5129,21 @@ receive_expr(Clauses) -> %% ===================================================================== -%% @spec receive_expr(Clauses::[syntaxTree()], Timeout, -%% Action::[syntaxTree()]) -> syntaxTree() -%% Timeout = none | syntaxTree() -%% -%% @doc Creates an abstract receive-expression. If <code>Timeout</code> -%% is <code>none</code>, the result represents "<code>receive -%% <em>C1</em>; ...; <em>Cn</em> end</code>" (the <code>Action</code> -%% argument is ignored). Otherwise, if <code>Clauses</code> is -%% <code>[C1, ..., Cn]</code> and <code>Action</code> is <code>[A1, ..., -%% Am]</code>, the result represents "<code>receive <em>C1</em>; ...; +%% @doc Creates an abstract receive-expression. If `Timeout' +%% is `none', the result represents "<code>receive +%% <em>C1</em>; ...; <em>Cn</em> end</code>" (the `Action' +%% argument is ignored). Otherwise, if `Clauses' is +%% `[C1, ..., Cn]' and `Action' is `[A1, ..., +%% Am]', the result represents "<code>receive <em>C1</em>; ...; %% <em>Cn</em> after <em>Timeout</em> -> <em>A1</em>, ..., <em>Am</em> -%% end</code>". More exactly, if each <code>Ci</code> represents +%% end</code>". More exactly, if each `Ci' represents %% "<code>(<em>Pi</em>) <em>Gi</em> -> <em>Bi</em></code>", then the %% result represents "<code>receive <em>P1</em> <em>G1</em> -> %% <em>B1</em>; ...; <em>Pn</em> <em>Gn</em> -> <em>Bn</em> ... %% end</code>". %% -%% <p>Note that in Erlang, a receive-expression must have at least one -%% clause if no timeout part is specified.</p> +%% Note that in Erlang, a receive-expression must have at least one +%% clause if no timeout part is specified. %% %% @see receive_expr_clauses/1 %% @see receive_expr_timeout/1 @@ -5649,11 +5207,8 @@ revert_receive_expr(Node) -> %% ===================================================================== -%% @spec receive_expr_clauses(syntaxTree()) -> [syntaxTree()] -%% type(Node) = receive_expr -%% %% @doc Returns the list of clause subtrees of a -%% <code>receive_expr</code> node. +%% `receive_expr' node. %% %% @see receive_expr/3 @@ -5671,15 +5226,12 @@ receive_expr_clauses(Node) -> %% ===================================================================== -%% @spec receive_expr_timeout(Node::syntaxTree()) -> Timeout -%% Timeout = none | syntaxTree() -%% -%% @doc Returns the timeout subtree of a <code>receive_expr</code> node, -%% if any. If <code>Node</code> represents "<code>receive <em>C1</em>; -%% ...; <em>Cn</em> end</code>", <code>none</code> is returned. -%% Otherwise, if <code>Node</code> represents "<code>receive +%% @doc Returns the timeout subtree of a `receive_expr' node, +%% if any. If `Node' represents "<code>receive <em>C1</em>; +%% ...; <em>Cn</em> end</code>", `none' is returned. +%% Otherwise, if `Node' represents "<code>receive %% <em>C1</em>; ...; <em>Cn</em> after <em>Timeout</em> -> ... end</code>", -%% <code>Timeout</code> is returned. +%% `Timeout' is returned. %% %% @see receive_expr/3 @@ -5697,10 +5249,8 @@ receive_expr_timeout(Node) -> %% ===================================================================== -%% @spec receive_expr_action(Node::syntaxTree()) -> [syntaxTree()] -%% %% @doc Returns the list of action body subtrees of a -%% <code>receive_expr</code> node. If <code>Node</code> represents +%% `receive_expr' node. If `Node' represents %% "<code>receive <em>C1</em>; ...; <em>Cn</em> end</code>", this is the %% empty list. %% @@ -5720,8 +5270,6 @@ receive_expr_action(Node) -> %% ===================================================================== -%% @spec try_expr(Body::syntaxTree(), Handlers::[syntaxTree()]) -> -%% syntaxTree() %% @equiv try_expr(Body, [], Handlers) -spec try_expr([syntaxTree()], [syntaxTree()]) -> syntaxTree(). @@ -5731,8 +5279,6 @@ try_expr(Body, Handlers) -> %% ===================================================================== -%% @spec try_expr(Body::syntaxTree(), Clauses::[syntaxTree()], -%% Handlers::[syntaxTree()]) -> syntaxTree() %% @equiv try_expr(Body, Clauses, Handlers, []) -spec try_expr([syntaxTree()], [syntaxTree()], [syntaxTree()]) -> syntaxTree(). @@ -5742,8 +5288,6 @@ try_expr(Body, Clauses, Handlers) -> %% ===================================================================== -%% @spec try_after_expr(Body::syntaxTree(), After::[syntaxTree()]) -> -%% syntaxTree() %% @equiv try_expr(Body, [], [], After) -spec try_after_expr([syntaxTree()], [syntaxTree()]) -> syntaxTree(). @@ -5753,30 +5297,26 @@ try_after_expr(Body, After) -> %% ===================================================================== -%% @spec try_expr(Body::[syntaxTree()], Clauses::[syntaxTree()], -%% Handlers::[syntaxTree()], After::[syntaxTree()]) -> -%% syntaxTree() -%% -%% @doc Creates an abstract try-expression. If <code>Body</code> is -%% <code>[B1, ..., Bn]</code>, <code>Clauses</code> is <code>[C1, ..., -%% Cj]</code>, <code>Handlers</code> is <code>[H1, ..., Hk]</code>, and -%% <code>After</code> is <code>[A1, ..., Am]</code>, the result +%% @doc Creates an abstract try-expression. If `Body' is +%% `[B1, ..., Bn]', `Clauses' is `[C1, ..., +%% Cj]', `Handlers' is `[H1, ..., Hk]', and +%% `After' is `[A1, ..., Am]', the result %% represents "<code>try <em>B1</em>, ..., <em>Bn</em> of <em>C1</em>; %% ...; <em>Cj</em> catch <em>H1</em>; ...; <em>Hk</em> after %% <em>A1</em>, ..., <em>Am</em> end</code>". More exactly, if each -%% <code>Ci</code> represents "<code>(<em>CPi</em>) <em>CGi</em> -> -%% <em>CBi</em></code>", and each <code>Hi</code> represents +%% `Ci' represents "<code>(<em>CPi</em>) <em>CGi</em> -> +%% <em>CBi</em></code>", and each `Hi' represents %% "<code>(<em>HPi</em>) <em>HGi</em> -> <em>HBi</em></code>", then the %% result represents "<code>try <em>B1</em>, ..., <em>Bn</em> of %% <em>CP1</em> <em>CG1</em> -> <em>CB1</em>; ...; <em>CPj</em> %% <em>CGj</em> -> <em>CBj</em> catch <em>HP1</em> <em>HG1</em> -> %% <em>HB1</em>; ...; <em>HPk</em> <em>HGk</em> -> <em>HBk</em> after -%% <em>A1</em>, ..., <em>Am</em> end</code>"; cf. -%% <code>case_expr/2</code>. If <code>Clauses</code> is the empty list, -%% the <code>of ...</code> section is left out. If <code>After</code> is -%% the empty list, the <code>after ...</code> section is left out. If -%% <code>Handlers</code> is the empty list, and <code>After</code> is -%% nonempty, the <code>catch ...</code> section is left out. +%% <em>A1</em>, ..., <em>Am</em> end</code>"; see +%% {@link case_expr/2}. If `Clauses' is the empty list, +%% the `of ...' section is left out. If `After' is +%% the empty list, the `after ...' section is left out. If +%% `Handlers' is the empty list, and `After' is +%% nonempty, the `catch ...' section is left out. %% %% @see try_expr_body/1 %% @see try_expr_clauses/1 @@ -5834,10 +5374,7 @@ revert_try_expr(Node) -> %% ===================================================================== -%% @spec try_expr_body(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of body subtrees of a <code>try_expr</code> -%% node. +%% @doc Returns the list of body subtrees of a `try_expr' node. %% %% @see try_expr/4 @@ -5853,10 +5390,8 @@ try_expr_body(Node) -> %% ===================================================================== -%% @spec try_expr_clauses(Node::syntaxTree()) -> [syntaxTree()] -%% %% @doc Returns the list of case-clause subtrees of a -%% <code>try_expr</code> node. If <code>Node</code> represents +%% `try_expr' node. If `Node' represents %% "<code>try <em>Body</em> catch <em>H1</em>; ...; <em>Hn</em> %% end</code>", the result is the empty list. %% @@ -5874,10 +5409,8 @@ try_expr_clauses(Node) -> %% ===================================================================== -%% @spec try_expr_handlers(syntaxTree()) -> [syntaxTree()] -%% %% @doc Returns the list of handler-clause subtrees of a -%% <code>try_expr</code> node. +%% `try_expr' node. %% %% @see try_expr/4 @@ -5893,10 +5426,7 @@ try_expr_handlers(Node) -> %% ===================================================================== -%% @spec try_expr_after(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of "after" subtrees of a <code>try_expr</code> -%% node. +%% @doc Returns the list of "after" subtrees of a `try_expr' node. %% %% @see try_expr/4 @@ -5912,9 +5442,6 @@ try_expr_after(Node) -> %% ===================================================================== -%% @spec class_qualifier(Class::syntaxTree(), Body::syntaxTree()) -> -%% syntaxTree() -%% %% @doc Creates an abstract class qualifier. The result represents %% "<code><em>Class</em>:<em>Body</em></code>". %% @@ -5937,10 +5464,8 @@ class_qualifier(Class, Body) -> %% ===================================================================== -%% @spec class_qualifier_argument(syntaxTree()) -> syntaxTree() -%% %% @doc Returns the argument (the class) subtree of a -%% <code>class_qualifier</code> node. +%% `class_qualifier' node. %% %% @see class_qualifier/2 @@ -5951,9 +5476,7 @@ class_qualifier_argument(Node) -> %% ===================================================================== -%% @spec class_qualifier_body(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the body subtree of a <code>class_qualifier</code> node. +%% @doc Returns the body subtree of a `class_qualifier' node. %% %% @see class_qualifier/2 @@ -5964,13 +5487,10 @@ class_qualifier_body(Node) -> %% ===================================================================== -%% @spec implicit_fun(Name::syntaxTree(), Arity::syntaxTree()) -> -%% syntaxTree() -%% %% @doc Creates an abstract "implicit fun" expression. If -%% <code>Arity</code> is <code>none</code>, this is equivalent to -%% <code>implicit_fun(Name)</code>, otherwise it is equivalent to -%% <code>implicit_fun(arity_qualifier(Name, Arity))</code>. +%% `Arity' is `none', this is equivalent to +%% `implicit_fun(Name)', otherwise it is equivalent to +%% `implicit_fun(arity_qualifier(Name, Arity))'. %% %% (This is a utility function.) %% @@ -5986,14 +5506,11 @@ implicit_fun(Name, Arity) -> %% ===================================================================== -%% @spec implicit_fun(Module::syntaxTree(), Name::syntaxTree(), -%% Arity::syntaxTree()) -> syntaxTree() -%% %% @doc Creates an abstract module-qualified "implicit fun" expression. -%% If <code>Module</code> is <code>none</code>, this is equivalent to -%% <code>implicit_fun(Name, Arity)</code>, otherwise it is equivalent to -%% <code>implicit_fun(module_qualifier(Module, arity_qualifier(Name, -%% Arity))</code>. +%% If `Module' is `none', this is equivalent to +%% `implicit_fun(Name, Arity)', otherwise it is equivalent to +%% `implicit_fun(module_qualifier(Module, arity_qualifier(Name, +%% Arity))'. %% %% (This is a utility function.) %% @@ -6010,10 +5527,8 @@ implicit_fun(Module, Name, Arity) -> %% ===================================================================== -%% @spec implicit_fun(Name::syntaxTree()) -> syntaxTree() -%% %% @doc Creates an abstract "implicit fun" expression. The result -%% represents "<code>fun <em>Name</em></code>". <code>Name</code> should +%% represents "<code>fun <em>Name</em></code>". `Name' should %% represent either <code><em>F</em>/<em>A</em></code> or %% <code><em>M</em>:<em>F</em>/<em>A</em></code> %% @@ -6072,15 +5587,13 @@ revert_implicit_fun(Node) -> %% ===================================================================== -%% @spec implicit_fun_name(Node::syntaxTree()) -> syntaxTree() +%% @doc Returns the name subtree of an `implicit_fun' node. %% -%% @doc Returns the name subtree of an <code>implicit_fun</code> node. -%% -%% <p>Note: if <code>Node</code> represents "<code>fun +%% Note: if `Node' represents "<code>fun %% <em>N</em>/<em>A</em></code>" or "<code>fun %% <em>M</em>:<em>N</em>/<em>A</em></code>", then the result is the %% subtree representing "<code><em>N</em>/<em>A</em></code>" or -%% "<code><em>M</em>:<em>N</em>/<em>A</em></code>", respectively.</p> +%% "<code><em>M</em>:<em>N</em>/<em>A</em></code>", respectively. %% %% @see implicit_fun/1 %% @see arity_qualifier/2 @@ -6110,12 +5623,10 @@ implicit_fun_name(Node) -> %% ===================================================================== -%% @spec fun_expr(Clauses::[syntaxTree()]) -> syntaxTree() -%% -%% @doc Creates an abstract fun-expression. If <code>Clauses</code> is -%% <code>[C1, ..., Cn]</code>, the result represents "<code>fun +%% @doc Creates an abstract fun-expression. If `Clauses' is +%% `[C1, ..., Cn]', the result represents "<code>fun %% <em>C1</em>; ...; <em>Cn</em> end</code>". More exactly, if each -%% <code>Ci</code> represents "<code>(<em>Pi1</em>, ..., <em>Pim</em>) +%% `Ci' represents "<code>(<em>Pi1</em>, ..., <em>Pim</em>) %% <em>Gi</em> -> <em>Bi</em></code>", then the result represents %% "<code>fun (<em>P11</em>, ..., <em>P1m</em>) <em>G1</em> -> %% <em>B1</em>; ...; (<em>Pn1</em>, ..., <em>Pnm</em>) <em>Gn</em> -> @@ -6152,10 +5663,7 @@ revert_fun_expr(Node) -> %% ===================================================================== -%% @spec fun_expr_clauses(syntaxTree()) -> [syntaxTree()] -%% -%% @doc Returns the list of clause subtrees of a <code>fun_expr</code> -%% node. +%% @doc Returns the list of clause subtrees of a `fun_expr' node. %% %% @see fun_expr/1 @@ -6171,16 +5679,14 @@ fun_expr_clauses(Node) -> %% ===================================================================== -%% @spec fun_expr_arity(syntaxTree()) -> integer() -%% -%% @doc Returns the arity of a <code>fun_expr</code> node. The result is +%% @doc Returns the arity of a `fun_expr' node. The result is %% the number of parameter patterns in the first clause of the %% fun-expression; subsequent clauses are ignored. %% -%% <p>An exception is thrown if <code>fun_expr_clauses(Node)</code> +%% An exception is thrown if `fun_expr_clauses(Node)' %% returns an empty list, or if the first element of that list is not a -%% syntax tree <code>C</code> of type <code>clause</code> such that -%% <code>clause_patterns(C)</code> is a nonempty list.</p> +%% syntax tree `C' of type `clause' such that +%% `clause_patterns(C)' is a nonempty list. %% %% @see fun_expr/1 %% @see fun_expr_clauses/1 @@ -6194,8 +5700,6 @@ fun_expr_arity(Node) -> %% ===================================================================== -%% @spec parentheses(Body::syntaxTree()) -> syntaxTree() -%% %% @doc Creates an abstract parenthesised expression. The result %% represents "<code>(<em>Body</em>)</code>", independently of the %% context. @@ -6215,9 +5719,7 @@ revert_parentheses(Node) -> %% ===================================================================== -%% @spec parentheses_body(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the body subtree of a <code>parentheses</code> node. +%% @doc Returns the body subtree of a `parentheses' node. %% %% @see parentheses/1 @@ -6228,7 +5730,6 @@ parentheses_body(Node) -> %% ===================================================================== -%% @spec macro(Name) -> syntaxTree() %% @equiv macro(Name, none) -spec macro(syntaxTree()) -> syntaxTree(). @@ -6238,25 +5739,22 @@ macro(Name) -> %% ===================================================================== -%% @spec macro(Name::syntaxTree(), Arguments) -> syntaxTree() -%% Arguments = none | [syntaxTree()] -%% -%% @doc Creates an abstract macro application. If <code>Arguments</code> -%% is <code>none</code>, the result represents -%% "<code>?<em>Name</em></code>", otherwise, if <code>Arguments</code> -%% is <code>[A1, ..., An]</code>, the result represents +%% @doc Creates an abstract macro application. If `Arguments' +%% is `none', the result represents +%% "<code>?<em>Name</em></code>", otherwise, if `Arguments' +%% is `[A1, ..., An]', the result represents %% "<code>?<em>Name</em>(<em>A1</em>, ..., <em>An</em>)</code>". %% -%% <p>Notes: if <code>Arguments</code> is the empty list, the result +%% Notes: if `Arguments' is the empty list, the result %% will thus represent "<code>?<em>Name</em>()</code>", including a pair -%% of matching parentheses.</p> +%% of matching parentheses. %% -%% <p>The only syntactical limitation imposed by the preprocessor on the +%% The only syntactical limitation imposed by the preprocessor on the %% arguments to a macro application (viewed as sequences of tokens) is %% that they must be balanced with respect to parentheses, brackets, -%% <code>begin ... end</code>, <code>case ... end</code>, etc. The -%% <code>text</code> node type can be used to represent arguments which -%% are not regular Erlang constructs.</p> +%% `begin ... end', `case ... end', etc. The +%% `text' node type can be used to represent arguments which +%% are not regular Erlang constructs. %% %% @see macro_name/1 %% @see macro_arguments/1 @@ -6278,9 +5776,7 @@ macro(Name, Arguments) -> %% ===================================================================== -%% @spec macro_name(syntaxTree()) -> syntaxTree() -%% -%% @doc Returns the name subtree of a <code>macro</code> node. +%% @doc Returns the name subtree of a `macro' node. %% %% @see macro/2 @@ -6291,14 +5787,12 @@ macro_name(Node) -> %% ===================================================================== -%% @spec macro_arguments(Node::syntaxTree()) -> none | [syntaxTree()] -%% -%% @doc Returns the list of argument subtrees of a <code>macro</code> -%% node, if any. If <code>Node</code> represents -%% "<code>?<em>Name</em></code>", <code>none</code> is returned. -%% Otherwise, if <code>Node</code> represents +%% @doc Returns the list of argument subtrees of a `macro' +%% node, if any. If `Node' represents +%% "<code>?<em>Name</em></code>", `none' is returned. +%% Otherwise, if `Node' represents %% "<code>?<em>Name</em>(<em>A1</em>, ..., <em>An</em>)</code>", -%% <code>[A1, ..., An]</code> is returned. +%% `[A1, ..., An]' is returned. %% %% @see macro/2 @@ -6309,15 +5803,13 @@ macro_arguments(Node) -> %% ===================================================================== -%% @spec abstract(Term::term()) -> syntaxTree() -%% %% @doc Returns the syntax tree corresponding to an Erlang term. -%% <code>Term</code> must be a literal term, i.e., one that can be +%% `Term' must be a literal term, i.e., one that can be %% represented as a source code literal. Thus, it may not contain a %% process identifier, port, reference, binary or function value as a %% subterm. The function recognises printable strings, in order to get a %% compact and readable representation. Evaluation fails with reason -%% <code>badarg</code> if <code>Term</code> is not a literal term. +%% `badarg' if `Term' is not a literal term. %% %% @see concrete/1 %% @see is_literal/1 @@ -6367,19 +5859,17 @@ abstract_tail(H, T) -> %% ===================================================================== -%% @spec concrete(Node::syntaxTree()) -> term() -%% %% @doc Returns the Erlang term represented by a syntax tree. Evaluation -%% fails with reason <code>badarg</code> if <code>Node</code> does not +%% fails with reason `badarg' if `Node' does not %% represent a literal term. %% -%% <p>Note: Currently, the set of syntax trees which have a concrete +%% Note: Currently, the set of syntax trees which have a concrete %% representation is larger than the set of trees which can be built -%% using the function <code>abstract/1</code>. An abstract character -%% will be concretised as an integer, while <code>abstract/1</code> does +%% using the function {@link abstract/1}. An abstract character +%% will be concretised as an integer, while {@link abstract/1} does %% not at present yield an abstract character for any input. (Use the -%% <code>char/1</code> function to explicitly create an abstract -%% character.)</p> +%% {@link char/1} function to explicitly create an abstract +%% character.) %% %% @see abstract/1 %% @see is_literal/1 @@ -6422,7 +5912,7 @@ concrete(Node) -> {value, concrete(F), []} end, [], true), B; - _ -> + _ -> erlang:error({badarg, Node}) end. @@ -6433,12 +5923,10 @@ concrete_list([]) -> %% ===================================================================== -%% @spec is_literal(Node::syntaxTree()) -> boolean() -%% -%% @doc Returns <code>true</code> if <code>Node</code> represents a -%% literal term, otherwise <code>false</code>. This function returns -%% <code>true</code> if and only if the value of -%% <code>concrete(Node)</code> is defined. +%% @doc Returns `true' if `Node' represents a +%% literal term, otherwise `false'. This function returns +%% `true' if and only if the value of +%% `concrete(Node)' is defined. %% %% @see abstract/1 %% @see concrete/1 @@ -6469,21 +5957,19 @@ is_literal(T) -> %% ===================================================================== -%% @spec revert(Tree::syntaxTree()) -> syntaxTree() -%% -%% @doc Returns an <code>erl_parse</code>-compatible representation of a -%% syntax tree, if possible. If <code>Tree</code> represents a +%% @doc Returns an `erl_parse'-compatible representation of a +%% syntax tree, if possible. If `Tree' represents a %% well-formed Erlang program or expression, the conversion should work -%% without problems. Typically, <code>is_tree/1</code> yields -%% <code>true</code> if conversion failed (i.e., the result is still an -%% abstract syntax tree), and <code>false</code> otherwise. +%% without problems. Typically, {@link is_tree/1} yields +%% `true' if conversion failed (i.e., the result is still an +%% abstract syntax tree), and `false' otherwise. %% -%% <p>The <code>is_tree/1</code> test is not completely foolproof. For a -%% few special node types (e.g. <code>arity_qualifier</code>), if such a +%% The {@link is_tree/1} test is not completely foolproof. For a +%% few special node types (e.g. `arity_qualifier'), if such a %% node occurs in a context where it is not expected, it will be left %% unchanged as a non-reverted subtree of the result. This can only -%% happen if <code>Tree</code> does not actually represent legal Erlang -%% code.</p> +%% happen if `Tree' does not actually represent legal Erlang +%% code. %% %% @see revert_forms/1 %% @see //stdlib/erl_parse @@ -6493,9 +5979,13 @@ is_literal(T) -> revert(Node) -> case is_tree(Node) of false -> - %% Just remove any wrapper. `erl_parse' nodes never contain - %% abstract syntax tree nodes as subtrees. - unwrap(Node); + %% Just remove any wrapper and copy the position. `erl_parse' + %% nodes never contain abstract syntax tree nodes as subtrees. + case unwrap(Node) of + {error, Info} -> {error, setelement(1,Info,get_pos(Node))}; + {warning, Info} -> {warning, setelement(1,Info,get_pos(Node))}; + Node1 -> setelement(2,Node1,get_pos(Node)) + end; true -> case is_leaf(Node) of true -> @@ -6615,16 +6105,12 @@ revert_root(Node) -> %% ===================================================================== -%% @spec revert_forms(Forms) -> [erl_parse()] -%% -%% Forms = syntaxTree() | [syntaxTree()] -%% %% @doc Reverts a sequence of Erlang source code forms. The sequence can -%% be given either as a <code>form_list</code> syntax tree (possibly +%% be given either as a `form_list' syntax tree (possibly %% nested), or as a list of "program form" syntax trees. If successful, -%% the corresponding flat list of <code>erl_parse</code>-compatible -%% syntax trees is returned (cf. <code>revert/1</code>). If some program -%% form could not be reverted, <code>{error, Form}</code> is thrown. +%% the corresponding flat list of `erl_parse'-compatible +%% syntax trees is returned (see {@link revert/1}). If some program +%% form could not be reverted, `{error, Form}' is thrown. %% Standalone comments in the form sequence are discarded. %% %% @see revert/1 @@ -6633,10 +6119,10 @@ revert_root(Node) -> -type forms() :: syntaxTree() | [syntaxTree()]. -%% -spec revert_forms(forms()) -> [erl_parse()]. +-spec revert_forms(forms()) -> [erl_parse()]. -revert_forms(L) when is_list(L) -> - revert_forms(form_list(L)); +revert_forms(Forms) when is_list(Forms) -> + revert_forms(form_list(Forms)); revert_forms(T) -> case type(T) of form_list -> @@ -6673,60 +6159,54 @@ revert_forms_1([]) -> %% ===================================================================== -%% @spec subtrees(Node::syntaxTree()) -> [[syntaxTree()]] -%% %% @doc Returns the grouped list of all subtrees of a syntax tree. If -%% <code>Node</code> is a leaf node (cf. <code>is_leaf/1</code>), this +%% `Node' is a leaf node (see {@link is_leaf/1}), this %% is the empty list, otherwise the result is always a nonempty list, -%% containing the lists of subtrees of <code>Node</code>, in +%% containing the lists of subtrees of `Node', in %% left-to-right order as they occur in the printed program text, and %% grouped by category. Often, each group contains only a single %% subtree. %% -%% <p>Depending on the type of <code>Node</code>, the size of some +%% Depending on the type of `Node', the size of some %% groups may be variable (e.g., the group consisting of all the %% elements of a tuple), while others always contain the same number of %% elements - usually exactly one (e.g., the group containing the %% argument expression of a case-expression). Note, however, that the %% exact structure of the returned list (for a given node type) should %% in general not be depended upon, since it might be subject to change -%% without notice.</p> +%% without notice. %% -%% <p>The function <code>subtrees/1</code> and the constructor functions -%% <code>make_tree/2</code> and <code>update_tree/2</code> can be a +%% The function {@link subtrees/1} and the constructor functions +%% {@link make_tree/2} and {@link update_tree/2} can be a %% great help if one wants to traverse a syntax tree, visiting all its %% subtrees, but treat nodes of the tree in a uniform way in most or all %% cases. Using these functions makes this simple, and also assures that %% your code is not overly sensitive to extensions of the syntax tree %% data type, because any node types not explicitly handled by your code -%% can be left to a default case.</p> +%% can be left to a default case. %% -%% <p>For example: -%% <pre> -%% postorder(F, Tree) -> +%% For example: +%% ```postorder(F, Tree) -> %% F(case subtrees(Tree) of %% [] -> Tree; %% List -> update_tree(Tree, %% [[postorder(F, Subtree) %% || Subtree <- Group] %% || Group <- List]) -%% end). -%% </pre> -%% maps the function <code>F</code> on <code>Tree</code> and all its +%% end).''' +%% maps the function `F' on `Tree' and all its %% subtrees, doing a post-order traversal of the syntax tree. (Note the -%% use of <code>update_tree/2</code> to preserve node attributes.) For a +%% use of {@link update_tree/2} to preserve node attributes.) For a %% simple function like: -%% <pre> -%% f(Node) -> +%% ```f(Node) -> %% case type(Node) of %% atom -> atom("a_" ++ atom_name(Node)); %% _ -> Node -%% end. -%% </pre> -%% the call <code>postorder(fun f/1, Tree)</code> will yield a new -%% representation of <code>Tree</code> in which all atom names have been +%% end.''' +%% the call `postorder(fun f/1, Tree)' will yield a new +%% representation of `Tree' in which all atom names have been %% extended with the prefix "a_", but nothing else (including comments, -%% annotations and line numbers) has been changed.</p> +%% annotations and line numbers) has been changed. %% %% @see make_tree/2 %% @see type/1 @@ -6896,12 +6376,9 @@ subtrees(T) -> %% ===================================================================== -%% @spec update_tree(Node::syntaxTree(), Groups::[[syntaxTree()]]) -> -%% syntaxTree() -%% %% @doc Creates a syntax tree with the same type and attributes as the -%% given tree. This is equivalent to <code>copy_attrs(Node, -%% make_tree(type(Node), Groups))</code>. +%% given tree. This is equivalent to `copy_attrs(Node, +%% make_tree(type(Node), Groups))'. %% %% @see make_tree/2 %% @see copy_attrs/2 @@ -6914,23 +6391,20 @@ update_tree(Node, Groups) -> %% ===================================================================== -%% @spec make_tree(Type::atom(), Groups::[[syntaxTree()]]) -> -%% syntaxTree() -%% %% @doc Creates a syntax tree with the given type and subtrees. -%% <code>Type</code> must be a node type name (cf. <code>type/1</code>) -%% that does not denote a leaf node type (cf. <code>is_leaf/1</code>). -%% <code>Groups</code> must be a <em>nonempty</em> list of groups of +%% `Type' must be a node type name (see {@link type/1}) +%% that does not denote a leaf node type (see {@link is_leaf/1}). +%% `Groups' must be a <em>nonempty</em> list of groups of %% syntax trees, representing the subtrees of a node of the given type, %% in left-to-right order as they would occur in the printed program -%% text, grouped by category as done by <code>subtrees/1</code>. +%% text, grouped by category as done by {@link subtrees/1}. %% -%% <p>The result of <code>copy_attrs(Node, make_tree(type(Node), -%% subtrees(Node)))</code> (cf. <code>update_tree/2</code>) represents -%% the same source code text as the original <code>Node</code>, assuming -%% that <code>subtrees(Node)</code> yields a nonempty list. However, it +%% The result of `copy_attrs(Node, make_tree(type(Node), +%% subtrees(Node)))' (see {@link update_tree/2}) represents +%% the same source code text as the original `Node', assuming +%% that `subtrees(Node)' yields a nonempty list. However, it %% does not necessarily have the same data representation as -%% <code>Node</code>.</p> +%% `Node'. %% %% @see update_tree/2 %% @see subtrees/1 @@ -6995,42 +6469,40 @@ make_tree(tuple, [E]) -> tuple(E). %% ===================================================================== -%% @spec meta(Tree::syntaxTree()) -> syntaxTree() -%% %% @doc Creates a meta-representation of a syntax tree. The result %% represents an Erlang expression "<code><em>MetaTree</em></code>" %% which, if evaluated, will yield a new syntax tree representing the -%% same source code text as <code>Tree</code> (although the actual data +%% same source code text as `Tree' (although the actual data %% representation may be different). The expression represented by -%% <code>MetaTree</code> is <em>implementation independent</em> with +%% `MetaTree' is <em>implementation independent</em> with %% regard to the data structures used by the abstract syntax tree -%% implementation. Comments attached to nodes of <code>Tree</code> will +%% implementation. Comments attached to nodes of `Tree' will %% be preserved, but other attributes are lost. %% -%% <p>Any node in <code>Tree</code> whose node type is -%% <code>variable</code> (cf. <code>type/1</code>), and whose list of -%% annotations (cf. <code>get_ann/1</code>) contains the atom -%% <code>meta_var</code>, will remain unchanged in the resulting tree, -%% except that exactly one occurrence of <code>meta_var</code> is -%% removed from its annotation list.</p> +%% Any node in `Tree' whose node type is +%% `variable' (see {@link type/1}), and whose list of +%% annotations (see {@link get_ann/1}) contains the atom +%% `meta_var', will remain unchanged in the resulting tree, +%% except that exactly one occurrence of `meta_var' is +%% removed from its annotation list. %% -%% <p>The main use of the function <code>meta/1</code> is to transform a -%% data structure <code>Tree</code>, which represents a piece of program +%% The main use of the function `meta/1' is to transform a +%% data structure `Tree', which represents a piece of program %% code, into a form that is <em>representation independent when -%% printed</em>. E.g., suppose <code>Tree</code> represents a variable -%% named "V". Then (assuming a function <code>print/1</code> for -%% printing syntax trees), evaluating <code>print(abstract(Tree))</code> -%% - simply using <code>abstract/1</code> to map the actual data +%% printed</em>. E.g., suppose `Tree' represents a variable +%% named "V". Then (assuming a function `print/1' for +%% printing syntax trees), evaluating `print(abstract(Tree))' +%% - simply using {@link abstract/1} to map the actual data %% structure onto a syntax tree representation - would output a string -%% that might look something like "<code>{tree, variable, ..., "V", -%% ...}</code>", which is obviously dependent on the implementation of +%% that might look something like "`{tree, variable, ..., "V", +%% ...}'", which is obviously dependent on the implementation of %% the abstract syntax trees. This could e.g. be useful for caching a %% syntax tree in a file. However, in some situations like in a program %% generator generator (with two "generator"), it may be unacceptable. -%% Using <code>print(meta(Tree))</code> instead would output a +%% Using `print(meta(Tree))' instead would output a %% <em>representation independent</em> syntax tree generating %% expression; in the above case, something like -%% "<code>erl_syntax:variable("V")</code>".</p> +%% "`erl_syntax:variable("V")'". %% %% @see abstract/1 %% @see type/1 @@ -7161,60 +6633,56 @@ meta_call(F, As) -> %% ===================================================================== -%% @spec tree(Type) -> syntaxTree() %% @equiv tree(Type, []) --spec tree(atom()) -> syntaxTree(). +-spec tree(atom()) -> #tree{}. tree(Type) -> tree(Type, []). %% ===================================================================== -%% @spec tree(Type::atom(), Data::term()) -> syntaxTree() -%% %% @doc <em>For special purposes only</em>. Creates an abstract syntax -%% tree node with type tag <code>Type</code> and associated data -%% <code>Data</code>. +%% tree node with type tag `Type' and associated data +%% `Data'. %% -%% <p>This function and the related <code>is_tree/1</code> and -%% <code>data/1</code> provide a uniform way to extend the set of -%% <code>erl_parse</code> node types. The associated data is any term, -%% whose format may depend on the type tag.</p> +%% This function and the related {@link is_tree/1} and +%% {@link data/1} provide a uniform way to extend the set of +%% `erl_parse' node types. The associated data is any term, +%% whose format may depend on the type tag. %% -%% <h4>Notes:</h4> +%% === Notes: === %% <ul> %% <li>Any nodes created outside of this module must have type tags %% distinct from those currently defined by this module; see -%% <code>type/1</code> for a complete list.</li> +%% {@link type/1} for a complete list.</li> %% <li>The type tag of a syntax tree node may also be used -%% as a primary tag by the <code>erl_parse</code> representation; +%% as a primary tag by the `erl_parse' representation; %% in that case, the selector functions for that node type %% <em>must</em> handle both the abstract syntax tree and the -%% <code>erl_parse</code> form. The function <code>type(T)</code> +%% `erl_parse' form. The function `type(T)' %% should return the correct type tag regardless of the -%% representation of <code>T</code>, so that the user sees no -%% difference between <code>erl_syntax</code> and -%% <code>erl_parse</code> nodes.</li> +%% representation of `T', so that the user sees no +%% difference between `erl_syntax' and +%% `erl_parse' nodes.</li> %% </ul> +%% %% @see is_tree/1 %% @see data/1 %% @see type/1 --spec tree(atom(), term()) -> syntaxTree(). +-spec tree(atom(), term()) -> #tree{}. tree(Type, Data) -> #tree{type = Type, data = Data}. %% ===================================================================== -%% @spec is_tree(Tree::syntaxTree()) -> boolean() -%% -%% @doc <em>For special purposes only</em>. Returns <code>true</code> if -%% <code>Tree</code> is an abstract syntax tree and <code>false</code> +%% @doc <em>For special purposes only</em>. Returns `true' if +%% `Tree' is an abstract syntax tree and `false' %% otherwise. %% -%% <p><em>Note</em>: this function yields <code>false</code> for all -%% "old-style" <code>erl_parse</code>-compatible "parse trees".</p> +%% <em>Note</em>: this function yields `false' for all +%% "old-style" `erl_parse'-compatible "parse trees". %% %% @see tree/2 @@ -7227,12 +6695,10 @@ is_tree(_) -> %% ===================================================================== -%% @spec data(Tree::syntaxTree()) -> term() -%% %% @doc <em>For special purposes only</em>. Returns the associated data %% of a syntax tree node. Evaluation fails with reason -%% <code>badarg</code> if <code>is_tree(Node)</code> does not yield -%% <code>true</code>. +%% `badarg' if `is_tree(Node)' does not yield +%% `true'. %% %% @see tree/2 @@ -7248,26 +6714,19 @@ data(T) -> erlang:error({badarg, T}). %% ===================================================================== -%% @spec wrap(Node::erl_parse()) -> syntaxTree() -%% -%% @type erl_parse() = erl_parse:parse_tree(). The "parse tree" -%% representation built by the Erlang standard library parser -%% <code>erl_parse</code>. This is a subset of the -%% <a href="#type-syntaxTree"><code>syntaxTree</code></a> type. -%% -%% @doc Creates a wrapper structure around an <code>erl_parse</code> +%% @doc Creates a wrapper structure around an `erl_parse' %% "parse tree". %% -%% <p>This function and the related <code>unwrap/1</code> and -%% <code>is_wrapper/1</code> provide a uniform way to attach arbitrary -%% information to an <code>erl_parse</code> tree. Some information about +%% This function and the related {@link unwrap/1} and +%% {@link is_wrapper/1} provide a uniform way to attach arbitrary +%% information to an `erl_parse' tree. Some information about %% the encapsuled tree may be cached in the wrapper, such as the node %% type. All functions on syntax trees must behave so that the user sees -%% no difference between wrapped and non-wrapped <code>erl_parse</code> +%% no difference between wrapped and non-wrapped `erl_parse' %% trees. <em>Attaching a wrapper onto another wrapper structure is an -%% error</em>.</p> +%% error</em>. -%%-spec wrap(erl_parse:parse_tree()) -> syntaxTree(). +-spec wrap(erl_parse()) -> #wrapper{}. wrap(Node) -> %% We assume that Node is an old-school `erl_parse' tree. @@ -7276,24 +6735,20 @@ wrap(Node) -> %% ===================================================================== -%% @spec unwrap(Node::syntaxTree()) -> syntaxTree() -%% -%% @doc Removes any wrapper structure, if present. If <code>Node</code> +%% @doc Removes any wrapper structure, if present. If `Node' %% is a wrapper structure, this function returns the wrapped -%% <code>erl_parse</code> tree; otherwise it returns <code>Node</code> +%% `erl_parse' tree; otherwise it returns `Node' %% itself. --spec unwrap(syntaxTree()) -> syntaxTree(). +-spec unwrap(syntaxTree()) -> #tree{} | erl_parse(). unwrap(#wrapper{tree = Node}) -> Node; unwrap(Node) -> Node. % This could also be a new-form node. %% ===================================================================== -%% @spec is_wrapper(Term::term()) -> boolean() -%% -%% @doc Returns <code>true</code> if the argument is a wrapper -%% structure, otherwise <code>false</code>. +%% @doc Returns `true' if the argument is a wrapper +%% structure, otherwise `false'. -ifndef(NO_UNUSED). -spec is_wrapper(term()) -> boolean(). diff --git a/lib/syntax_tools/src/erl_syntax_lib.erl b/lib/syntax_tools/src/erl_syntax_lib.erl index 97dfbfd7cd..36cd35f15d 100644 --- a/lib/syntax_tools/src/erl_syntax_lib.erl +++ b/lib/syntax_tools/src/erl_syntax_lib.erl @@ -14,10 +14,8 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @copyright 1997-2006 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @end %% ===================================================================== diff --git a/lib/syntax_tools/src/erl_tidy.erl b/lib/syntax_tools/src/erl_tidy.erl index 09efc9c392..59cf6c0a92 100644 --- a/lib/syntax_tools/src/erl_tidy.erl +++ b/lib/syntax_tools/src/erl_tidy.erl @@ -14,10 +14,8 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @copyright 1999-2006 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @end %% ===================================================================== diff --git a/lib/syntax_tools/src/igor.erl b/lib/syntax_tools/src/igor.erl index aa933eb54b..37e561cbbe 100644 --- a/lib/syntax_tools/src/igor.erl +++ b/lib/syntax_tools/src/igor.erl @@ -14,10 +14,8 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @copyright 1998-2006 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @end %% ===================================================================== diff --git a/lib/syntax_tools/src/prettypr.erl b/lib/syntax_tools/src/prettypr.erl index c13fa30998..1b5ba6b05a 100644 --- a/lib/syntax_tools/src/prettypr.erl +++ b/lib/syntax_tools/src/prettypr.erl @@ -14,10 +14,8 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @copyright 2000-2006 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @end %% ===================================================================== diff --git a/lib/syntax_tools/vsn.mk b/lib/syntax_tools/vsn.mk index 2b9a08e192..8f774c5d75 100644 --- a/lib/syntax_tools/vsn.mk +++ b/lib/syntax_tools/vsn.mk @@ -1 +1 @@ -SYNTAX_TOOLS_VSN = 1.6.8 +SYNTAX_TOOLS_VSN = 1.6.9 diff --git a/lib/test_server/src/ts_run.erl b/lib/test_server/src/ts_run.erl index a61028e4bc..2e8c092400 100644 --- a/lib/test_server/src/ts_run.erl +++ b/lib/test_server/src/ts_run.erl @@ -334,9 +334,9 @@ path_separator() -> end. -make_common_test_args(Args0, Options, _Vars) -> +make_common_test_args(Args0, Options0, _Vars) -> Trace = - case lists:keysearch(trace,1,Options) of + case lists:keysearch(trace,1,Options0) of {value,{trace,TI}} when is_tuple(TI); is_tuple(hd(TI)) -> ok = file:write_file(?tracefile,io_lib:format("~p.~n",[TI])), [{ct_trace,?tracefile}]; @@ -348,7 +348,7 @@ make_common_test_args(Args0, Options, _Vars) -> [] end, Cover = - case lists:keysearch(cover,1,Options) of + case lists:keysearch(cover,1,Options0) of {value,{cover, App, none, _Analyse}} -> io:format("No cover file found for ~p~n",[App]), []; @@ -358,7 +358,7 @@ make_common_test_args(Args0, Options, _Vars) -> [] end, - Logdir = case lists:keysearch(logdir, 1, Options) of + Logdir = case lists:keysearch(logdir, 1, Options0) of {value,{logdir, _}} -> []; false -> @@ -373,15 +373,16 @@ make_common_test_args(Args0, Options, _Vars) -> {scale_timetraps, true}] end, - ConfigPath = case {os:getenv("TEST_CONFIG_PATH"), - lists:keysearch(config, 1, Options)} of - {false,{value, {config, Path}}} -> - Path; - {false,false} -> - "../test_server"; - {Path,_} -> - Path - end, + {ConfigPath, + Options} = case {os:getenv("TEST_CONFIG_PATH"), + lists:keysearch(config, 1, Options0)} of + {_,{value, {config, Path}}} -> + {Path,lists:keydelete(config, 1, Options0)}; + {false,false} -> + {"../test_server",Options0}; + {Path,_} -> + {Path,Options0} + end, ConfigFiles = [{config,[filename:join(ConfigPath,File) || File <- get_config_files()]}], io_lib:format("~100000p",[Args0++Trace++Cover++Logdir++ diff --git a/lib/test_server/vsn.mk b/lib/test_server/vsn.mk index a1f4559083..aecf595f3f 100644 --- a/lib/test_server/vsn.mk +++ b/lib/test_server/vsn.mk @@ -1 +1 @@ -TEST_SERVER_VSN = 3.5.1 +TEST_SERVER_VSN = 3.5.2 diff --git a/lib/wx/aclocal.m4 b/lib/wx/aclocal.m4 index 339a15a2bb..a76594d86f 100644 --- a/lib/wx/aclocal.m4 +++ b/lib/wx/aclocal.m4 @@ -59,6 +59,7 @@ AC_ARG_VAR(erl_xcomp_isysroot, [Absolute cross system root include path (only us dnl Cross compilation variables AC_ARG_VAR(erl_xcomp_bigendian, [big endian system: yes|no (only used when cross compiling)]) +AC_ARG_VAR(erl_xcomp_double_middle_endian, [double-middle-endian system: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_clock_gettime_correction, [clock_gettime() can be used for time correction: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_nptl, [have Native POSIX Thread Library: yes|no (only used when cross compiling)]) AC_ARG_VAR(erl_xcomp_linux_usable_sigusrx, [SIGUSR1 and SIGUSR2 can be used: yes|no (only used when cross compiling)]) @@ -606,6 +607,103 @@ ifelse([$5], , , [$5 fi ]) +dnl ---------------------------------------------------------------------- +dnl +dnl AC_DOUBLE_MIDDLE_ENDIAN +dnl +dnl Checks whether doubles are represented in "middle-endian" format. +dnl Sets ac_cv_double_middle_endian={no,yes,unknown} accordingly, +dnl as well as DOUBLE_MIDDLE_ENDIAN. +dnl +dnl + +AC_DEFUN([AC_C_DOUBLE_MIDDLE_ENDIAN], +[AC_CACHE_CHECK(whether double word ordering is middle-endian, ac_cv_c_double_middle_endian, +[# It does not; compile a test program. +AC_RUN_IFELSE( +[AC_LANG_SOURCE([[#include <stdlib.h> + +int +main(void) +{ + int i = 0; + int zero = 0; + int bigendian; + int zero_index = 0; + + union + { + long int l; + char c[sizeof (long int)]; + } u; + + /* we'll use the one with 32-bit words */ + union + { + double d; + unsigned int c[2]; + } vint; + + union + { + double d; + unsigned long c[2]; + } vlong; + + union + { + double d; + unsigned short c[2]; + } vshort; + + + /* Are we little or big endian? From Harbison&Steele. */ + u.l = 1; + bigendian = (u.c[sizeof (long int) - 1] == 1); + + zero_index = bigendian ? 1 : 0; + + vint.d = 1.0; + vlong.d = 1.0; + vshort.d = 1.0; + + if (sizeof(unsigned int) == 4) + { + if (vint.c[zero_index] != 0) + zero = 1; + } + else if (sizeof(unsigned long) == 4) + { + if (vlong.c[zero_index] != 0) + zero = 1; + } + else if (sizeof(unsigned short) == 4) + { + if (vshort.c[zero_index] != 0) + zero = 1; + } + + exit (zero); +} +]])], + [ac_cv_c_double_middle_endian=no], + [ac_cv_c_double_middle_endian=yes], + [ac_cv_c_double_middle=unknown])]) +case $ac_cv_c_double_middle_endian in + yes) + m4_default([$1], + [AC_DEFINE([DOUBLE_MIDDLE_ENDIAN], 1, + [Define to 1 if your processor stores the words in a double in + middle-endian format (like some ARMs).])]) ;; + no) + $2 ;; + *) + m4_default([$3], + [AC_MSG_WARN([unknown double endianness +presetting ac_cv_c_double_middle_endian=no (or yes) will help])]) ;; +esac +])# AC_C_DOUBLE_MIDDLE_ENDIAN + dnl ---------------------------------------------------------------------- dnl @@ -1337,6 +1435,14 @@ if test "$ac_cv_c_bigendian" = "yes"; then AC_DEFINE(ETHR_BIGENDIAN, 1, [Define if bigendian]) fi +case X$erl_xcomp_double_middle_endian in + X) ;; + Xyes|Xno|Xunknown) ac_cv_c_double_middle_endian=$erl_xcomp_double_middle_endian;; + *) AC_MSG_ERROR([Bad erl_xcomp_double_middle_endian value: $erl_xcomp_double_middle_endian]);; +esac + +AC_C_DOUBLE_MIDDLE_ENDIAN + AC_ARG_ENABLE(native-ethr-impls, AS_HELP_STRING([--disable-native-ethr-impls], [disable native ethread implementations]), diff --git a/xcomp/README.md b/xcomp/README.md index 5f4b36bdca..7217fea5fb 100644 --- a/xcomp/README.md +++ b/xcomp/README.md @@ -462,6 +462,10 @@ When a variable has been set, no warning will be issued. `configure` will fail unless this variable is set. Since no default value is used, `configure` will try to figure this out automatically. +* `erl_xcomp_double_middle` - `yes|no`. Defaults to `no`. + If `yes`, the target system must have doubles in "middle-endian" format. If + `no`, it has "regular" endianness. + * `erl_xcomp_clock_gettime_cpu_time` - `yes|no`. Defaults to `no`. If `yes`, the target system must have a working `clock_gettime()` implementation that can be used for retrieving process CPU time. diff --git a/xcomp/erl-xcomp-TileraMDE2.0-tilepro.conf b/xcomp/erl-xcomp-TileraMDE2.0-tilepro.conf index f9fff0fa8e..287cb787d9 100644 --- a/xcomp/erl-xcomp-TileraMDE2.0-tilepro.conf +++ b/xcomp/erl-xcomp-TileraMDE2.0-tilepro.conf @@ -187,6 +187,15 @@ erl_xcomp_sysroot="$TILERA_ROOT/tile" # value is used, `configure' will try to figure this out automatically. #erl_xcomp_bigendian= +# * `erl_xcomp_double_middle_endian` - `yes|no`. No default. If `yes`, the +# target system must have doubles in "middle-endian" format. If +# `no`, it has "regular" endianness. This can often be automatically +# detected, but not always. If not automatically detected, +# `configure` will fail unless this variable is set. Since no +# default value is used, `configure` will try to figure this out +# automatically. +#erl_xcomp_double_middle_endian + # * `erl_xcomp_clock_gettime_cpu_time' - `yes|no'. Defaults to `no'. If `yes', # the target system must have a working `clock_gettime()' implementation # that can be used for retrieving process CPU time. diff --git a/xcomp/erl-xcomp-avr32-atmel-linux-gnu.conf b/xcomp/erl-xcomp-avr32-atmel-linux-gnu.conf index be22d498d6..e86043f5c8 100644 --- a/xcomp/erl-xcomp-avr32-atmel-linux-gnu.conf +++ b/xcomp/erl-xcomp-avr32-atmel-linux-gnu.conf @@ -190,6 +190,15 @@ erl_xcomp_sysroot="$ATMEL_SYSROOT_AVR32" # value is used, `configure' will try to figure this out automatically. #erl_xcomp_bigendian= +# * `erl_xcomp_double_middle_endian` - `yes|no`. No default. If `yes`, the +# target system must have doubles in "middle-endian" format. If +# `no`, it has "regular" endianness. This can often be automatically +# detected, but not always. If not automatically detected, +# `configure` will fail unless this variable is set. Since no +# default value is used, `configure` will try to figure this out +# automatically. +#erl_xcomp_double_middle_endian + # * `erl_xcomp_clock_gettime_cpu_time' - `yes|no'. Defaults to `no'. If `yes', # the target system must have a working `clock_gettime()' implementation # that can be used for retrieving process CPU time. diff --git a/xcomp/erl-xcomp-mips-linux.conf b/xcomp/erl-xcomp-mips-linux.conf index 3ac057bb4c..2195b7d6e9 100644 --- a/xcomp/erl-xcomp-mips-linux.conf +++ b/xcomp/erl-xcomp-mips-linux.conf @@ -187,6 +187,15 @@ CFLAGS=-Os # value is used, `configure' will try to figure this out automatically. #erl_xcomp_bigendian= +# * `erl_xcomp_double_middle_endian` - `yes|no`. No default. If `yes`, the +# target system must have doubles in "middle-endian" format. If +# `no`, it has "regular" endianness. This can often be automatically +# detected, but not always. If not automatically detected, +# `configure` will fail unless this variable is set. Since no +# default value is used, `configure` will try to figure this out +# automatically. +#erl_xcomp_double_middle_endian + # * `erl_xcomp_clock_gettime_cpu_time' - `yes|no'. Defaults to `no'. If `yes', # the target system must have a working `clock_gettime()' implementation # that can be used for retrieving process CPU time. diff --git a/xcomp/erl-xcomp-vars.sh b/xcomp/erl-xcomp-vars.sh index d9972eb3db..168b25262a 100644 --- a/xcomp/erl-xcomp-vars.sh +++ b/xcomp/erl-xcomp-vars.sh @@ -26,4 +26,4 @@ # and precious variables in $ERL_TOP/erts/aclocal.m4. # -erl_xcomp_vars="erl_xcomp_sysroot erl_xcomp_isysroot erl_xcomp_bigendian erl_xcomp_linux_clock_gettime_correction erl_xcomp_linux_nptl erl_xcomp_linux_usable_sigusrx erl_xcomp_linux_usable_sigaltstack erl_xcomp_poll erl_xcomp_kqueue erl_xcomp_putenv_copy erl_xcomp_reliable_fpe erl_xcomp_getaddrinfo erl_xcomp_gethrvtime_procfs_ioctl erl_xcomp_clock_gettime_cpu_time erl_xcomp_after_morecore_hook erl_xcomp_dlsym_brk_wrappers" +erl_xcomp_vars="erl_xcomp_sysroot erl_xcomp_isysroot erl_xcomp_bigendian erl_xcomp_double_middle_endian erl_xcomp_linux_clock_gettime_correction erl_xcomp_linux_nptl erl_xcomp_linux_usable_sigusrx erl_xcomp_linux_usable_sigaltstack erl_xcomp_poll erl_xcomp_kqueue erl_xcomp_putenv_copy erl_xcomp_reliable_fpe erl_xcomp_getaddrinfo erl_xcomp_gethrvtime_procfs_ioctl erl_xcomp_clock_gettime_cpu_time erl_xcomp_after_morecore_hook erl_xcomp_dlsym_brk_wrappers" diff --git a/xcomp/erl-xcomp-vxworks_ppc32.conf b/xcomp/erl-xcomp-vxworks_ppc32.conf index ed8305ea93..bea4b3e374 100644 --- a/xcomp/erl-xcomp-vxworks_ppc32.conf +++ b/xcomp/erl-xcomp-vxworks_ppc32.conf @@ -187,6 +187,15 @@ AR="$WIND_BASE/gnu/3.4.4-vxworks-6.3/$WIND_HOST_TYPE/bin/arppc" # value is used, `configure' will try to figure this out automatically. erl_xcomp_bigendian=yes +# * `erl_xcomp_double_middle_endian` - `yes|no`. No default. If `yes`, the +# target system must have doubles in "middle-endian" format. If +# `no`, it has "regular" endianness. This can often be automatically +# detected, but not always. If not automatically detected, +# `configure` will fail unless this variable is set. Since no +# default value is used, `configure` will try to figure this out +# automatically. +#erl_xcomp_double_middle_endian + # * `erl_xcomp_clock_gettime_cpu_time' - `yes|no'. Defaults to `no'. If `yes', # the target system must have a working `clock_gettime()' implementation # that can be used for retrieving process CPU time. diff --git a/xcomp/erl-xcomp-x86_64-saf-linux-gnu.conf b/xcomp/erl-xcomp-x86_64-saf-linux-gnu.conf index f645ddbd96..de9118ae30 100644 --- a/xcomp/erl-xcomp-x86_64-saf-linux-gnu.conf +++ b/xcomp/erl-xcomp-x86_64-saf-linux-gnu.conf @@ -187,6 +187,15 @@ erl_xcomp_after_morecore_hook=yes # value is used, `configure' will try to figure this out automatically. #erl_xcomp_bigendian= +# * `erl_xcomp_double_middle_endian` - `yes|no`. No default. If `yes`, the +# target system must have doubles in "middle-endian" format. If +# `no`, it has "regular" endianness. This can often be automatically +# detected, but not always. If not automatically detected, +# `configure` will fail unless this variable is set. Since no +# default value is used, `configure` will try to figure this out +# automatically. +#erl_xcomp_double_middle_endian + # * `erl_xcomp_clock_gettime_cpu_time' - `yes|no'. Defaults to `no'. If `yes', # the target system must have a working `clock_gettime()' implementation # that can be used for retrieving process CPU time. diff --git a/xcomp/erl-xcomp.conf.template b/xcomp/erl-xcomp.conf.template index eb331ffe92..c215f0fb13 100644 --- a/xcomp/erl-xcomp.conf.template +++ b/xcomp/erl-xcomp.conf.template @@ -187,6 +187,15 @@ # value is used, `configure' will try to figure this out automatically. #erl_xcomp_bigendian= +# * `erl_xcomp_double_middle` - `yes|no`. No default. If `yes`, the +# target system must have doubles in "middle-endian" format. If +# `no`, it has "regular" endianness. This can often be automatically +# detected, but not always. If not automatically detected, +# `configure` will fail unless this variable is set. Since no +# default value is used, `configure` will try to figure this out +# automatically. +#erl_xcomp_double_middle_endian + # * `erl_xcomp_clock_gettime_cpu_time' - `yes|no'. Defaults to `no'. If `yes', # the target system must have a working `clock_gettime()' implementation # that can be used for retrieving process CPU time. |