diff options
93 files changed, 26350 insertions, 6961 deletions
diff --git a/OTP_VERSION b/OTP_VERSION index d11ab1e02f..a027c639c4 100644 --- a/OTP_VERSION +++ b/OTP_VERSION @@ -1 +1 @@ -19.1.2 +19.1.5 diff --git a/configure.in b/configure.in index 6db83124be..a149acbb55 100644 --- a/configure.in +++ b/configure.in @@ -2,7 +2,7 @@ dnl Process this file with autoconf to produce a configure script. dnl %CopyrightBegin% dnl -dnl Copyright Ericsson AB 1998-2014. All Rights Reserved. +dnl Copyright Ericsson AB 1998-2016. All Rights Reserved. dnl dnl Licensed under the Apache License, Version 2.0 (the "License"); dnl you may not use this file except in compliance with the License. @@ -228,7 +228,10 @@ AS_HELP_STRING([--enable-kernel-poll], [enable kernel poll support]) AS_HELP_STRING([--disable-kernel-poll], [disable kernel poll support])) AC_ARG_ENABLE(sctp, -AS_HELP_STRING([--enable-sctp], [enable sctp support]) +AS_HELP_STRING([--enable-sctp], [enable sctp support (default) +to on demand load the SCTP library in runtime]) +AS_HELP_STRING([--enable-sctp=lib], [enable sctp support +to link against the SCTP library]) AS_HELP_STRING([--disable-sctp], [disable sctp support])) AC_ARG_ENABLE(hipe, diff --git a/erts/configure.in b/erts/configure.in index 69b9af3c8c..4799178583 100644 --- a/erts/configure.in +++ b/erts/configure.in @@ -196,12 +196,18 @@ AS_HELP_STRING([--disable-kernel-poll], [disable kernel poll support]), AC_ARG_ENABLE(sctp, -AS_HELP_STRING([--enable-sctp], [enable sctp support (default)]) +AS_HELP_STRING([--enable-sctp], [enable sctp support (default) +to on demand load the SCTP library in runtime if needed]) +AS_HELP_STRING([--enable-sctp=lib], [enable sctp support +to link against the SCTP library]) AS_HELP_STRING([--disable-sctp], [disable sctp support]), -[ case "$enableval" in - no) enable_sctp=no ;; - *) enable_sctp=yes ;; - esac ], enable_sctp=unknown) +[ case "x$enableval" in + xno|xyes|xlib|x) + ;; + x*) + AC_MSG_ERROR("invalid value --enable-sctp=$enableval") + ;; + esac ]) AC_ARG_ENABLE(hipe, AS_HELP_STRING([--enable-hipe], [enable hipe support]) @@ -1726,8 +1732,9 @@ if test "x$enable_sctp" != "xno" ; then fi if test x"$ac_cv_header_netinet_sctp_h" = x"yes"; then - AC_CHECK_LIB(sctp, sctp_bindx) - AC_CHECK_FUNCS([sctp_peeloff sctp_getladdrs sctp_freeladdrs sctp_getpaddrs sctp_freepaddrs]) + AS_IF([test "x$enable_sctp" = "xlib"], + AC_CHECK_LIB(sctp, sctp_bindx)) + AC_CHECK_FUNCS([sctp_bindx sctp_peeloff sctp_getladdrs sctp_freeladdrs sctp_getpaddrs sctp_freepaddrs]) AC_CHECK_DECLS([SCTP_UNORDERED, SCTP_ADDR_OVER, SCTP_ABORT, SCTP_EOF, SCTP_SENDALL, SCTP_ADDR_CONFIRMED, SCTP_DELAYED_ACK_TIME, diff --git a/erts/emulator/beam/erl_nif.c b/erts/emulator/beam/erl_nif.c index 3a547982da..9a873857b9 100644 --- a/erts/emulator/beam/erl_nif.c +++ b/erts/emulator/beam/erl_nif.c @@ -3360,7 +3360,7 @@ BIF_RETTYPE load_nif_2(BIF_ALIST_2) veto = entry->reload(&env, &lib->priv_data, BIF_ARG_2); erts_post_nif(&env); if (veto) { - ret = load_nif_error(BIF_P, reload, "Library reload-call unsuccessful."); + ret = load_nif_error(BIF_P, reload, "Library reload-call unsuccessful (%d).", veto); } else { commit_opened_resource_types(lib); @@ -3382,7 +3382,7 @@ BIF_RETTYPE load_nif_2(BIF_ALIST_2) erts_post_nif(&env); if (veto) { prev_mi->nif->priv_data = prev_old_data; - ret = load_nif_error(BIF_P, upgrade, "Library upgrade-call unsuccessful."); + ret = load_nif_error(BIF_P, upgrade, "Library upgrade-call unsuccessful (%d).", veto); } else commit_opened_resource_types(lib); @@ -3392,7 +3392,7 @@ BIF_RETTYPE load_nif_2(BIF_ALIST_2) veto = entry->load(&env, &lib->priv_data, BIF_ARG_2); erts_post_nif(&env); if (veto) { - ret = load_nif_error(BIF_P, "load", "Library load-call unsuccessful."); + ret = load_nif_error(BIF_P, "load", "Library load-call unsuccessful (%d).", veto); } else commit_opened_resource_types(lib); diff --git a/erts/etc/unix/etp-commands.in b/erts/etc/unix/etp-commands.in index e2bf302cca..1a4f641301 100644 --- a/erts/etc/unix/etp-commands.in +++ b/erts/etc/unix/etp-commands.in @@ -52,7 +52,7 @@ document etp-help % etpf-cons, etpf-boxed, % % Special commands for not really terms: -% etp-mfa, etp-cp, +% etp-mfa, etp-cp, etp-disasm, % etp-msgq, etpf-msgq, % etp-stacktrace, etp-stackdump, etpf-stackdump, etp-dictdump % etp-process-info, etp-process-memory-info @@ -1090,12 +1090,10 @@ document etp-mfa %--------------------------------------------------------------------------- end - - -define etp-cp-1 +define etp-cp-func-info-1 # Args: Eterm cp # -# Non-reentrant +# Non-reentrant, takes cp, sets $etp_cp_p to MFA in func_info # set $etp_cp = (Eterm)($arg0) set $etp_ranges = &r[(int)the_active_code_index] @@ -1137,8 +1135,21 @@ define etp-cp-1 end end if $etp_cp_p + set $cp_cp_p_offset = ($etp_cp-((Eterm)($etp_cp_p-2))) + else + set $cp_cp_p_offset = 0 + end +end + +define etp-cp-1 +# Args: Eterm cp +# +# Non-reentrant +# + etp-cp-func-info-1 $arg0 + if $etp_cp_p printf "#Cp" - etp-mfa-1 ($etp_cp_p) ($etp_cp-((Eterm)($etp_cp_p-2))) + etp-mfa-1 $etp_cp_p $cp_cp_p_offset else if $etp_cp == beam_apply+1 printf "#Cp<terminate process normally>" @@ -2478,11 +2489,58 @@ end document etp-schedulers %--------------------------------------------------------------------------- % etp-schedulers -% +% % Print misc info about all schedulers %--------------------------------------------------------------------------- end +define etp-disasm-1 + set $code_ptr = ((BeamInstr*)$arg0) + set $addr = *$code_ptr + set $i = 0 + while $i < (sizeof(opc) / sizeof(OpEntry)) + if $addr == beam_ops[$i] + printf "%s %d", opc[$i].name, opc[$i].sz + set $next_i = $code_ptr + opc[$i].sz + set $i += 4999 + end + set $i++ + end +end + +define etp-disasm + etp-cp-func-info-1 $arg0 + if $etp_cp_p == 0 + printf "invalid argument" + else + etp-mfa-1 $etp_cp_p $cp_cp_p_offset + printf ": " + etp-disasm-1 $arg0 + printf "\r\n" + while $next_i < ((BeamInstr*)$arg1) + set $prev_i = $next_i + etp-cp-func-info-1 $next_i + etp-mfa-1 $etp_cp_p $cp_cp_p_offset + printf ": " + etp-disasm-1 $next_i + if $prev_i == $next_i + # ptr did not advance, we are inside some strange opcode with argument + set $next_i++ + printf "instr argument" + end + printf "\r\n" + end + end +end + +document etp-disasm +%--------------------------------------------------------------------------- +% etp-disasm StartI EndI +% +% Disassemble the code inbetween StartI and EndI +%--------------------------------------------------------------------------- +end + define etp-migration-info set $minfo = (ErtsMigrationPaths *) *((UWord *) &erts_migration_paths) set $rq_ix = 0 diff --git a/erts/preloaded/ebin/init.beam b/erts/preloaded/ebin/init.beam Binary files differindex 849273f746..74a0184818 100644 --- a/erts/preloaded/ebin/init.beam +++ b/erts/preloaded/ebin/init.beam diff --git a/erts/preloaded/src/init.erl b/erts/preloaded/src/init.erl index 962528f7ab..551ca4ea40 100644 --- a/erts/preloaded/src/init.erl +++ b/erts/preloaded/src/init.erl @@ -205,7 +205,7 @@ boot(BootArgs) -> {Start0,Flags,Args} = parse_boot_args(BootArgs), %% We don't get to profile parsing of BootArgs - case get_flag(profile_boot, Flags, false) of + case b2a(get_flag(profile_boot, Flags, false)) of false -> ok; true -> debug_profile_start() end, @@ -782,7 +782,7 @@ do_boot(Init,Flags,Start) -> (catch erlang:system_info({purify, "Node: " ++ atom_to_list(node())})), start_em(Start), - case get_flag(profile_boot,Flags,false) of + case b2a(get_flag(profile_boot,Flags,false)) of false -> ok; true -> debug_profile_format_mfas(debug_profile_mfas()), diff --git a/lib/compiler/src/beam_bsm.erl b/lib/compiler/src/beam_bsm.erl index 286307a4be..ae1b34ba49 100644 --- a/lib/compiler/src/beam_bsm.erl +++ b/lib/compiler/src/beam_bsm.erl @@ -205,8 +205,15 @@ btb_reaches_match_1(Is, Regs, D) -> btb_reaches_match_2([{block,Bl}|Is], Regs0, D) -> Regs = btb_reaches_match_block(Bl, Regs0), btb_reaches_match_1(Is, Regs, D); -btb_reaches_match_2([{call,Arity,{f,Lbl}}|Is], Regs, D) -> - btb_call(Arity, Lbl, Regs, Is, D); +btb_reaches_match_2([{call,Arity,{f,Lbl}}|Is], Regs0, D) -> + case is_tail_call(Is) of + true -> + Regs1 = btb_kill_not_live(Arity, Regs0), + Regs = btb_kill_yregs(Regs1), + btb_tail_call(Lbl, Regs, D); + false -> + btb_call(Arity, Lbl, Regs0, Is, D) + end; btb_reaches_match_2([{apply,Arity}|Is], Regs, D) -> btb_call(Arity+2, apply, Regs, Is, D); btb_reaches_match_2([{call_fun,Live}=I|Is], Regs, D) -> @@ -360,6 +367,10 @@ btb_reaches_match_2([{line,_}|Is], Regs, D) -> btb_reaches_match_2([I|_], Regs, _) -> btb_error({btb_context_regs(Regs),I,not_handled}). +is_tail_call([{deallocate,_}|_]) -> true; +is_tail_call([return|_]) -> true; +is_tail_call(_) -> false. + btb_call(Arity, Lbl, Regs0, Is, D0) -> Regs = btb_kill_not_live(Arity, Regs0), case btb_are_x_registers_empty(Regs) of @@ -369,15 +380,15 @@ btb_call(Arity, Lbl, Regs0, Is, D0) -> D = btb_tail_call(Lbl, Regs, D0), %% No problem so far (the called function can handle a - %% match context). Now we must make sure that the rest - %% of this function following the call does not attempt - %% to use the match context in case there is a copy - %% tucked away in a y register. + %% match context). Now we must make sure that we don't + %% have any copies of the match context tucked away in an + %% y register. RegList = btb_context_regs(Regs), - YRegs = [R || {y,_}=R <- RegList], - case btb_are_all_unused(YRegs, Is, D) of - true -> D; - false -> btb_error({multiple_uses,RegList}) + case [R || {y,_}=R <- RegList] of + [] -> + D; + [_|_] -> + btb_error({multiple_uses,RegList}) end; true -> %% No match context in any x register. It could have been diff --git a/lib/compiler/test/bs_match_SUITE.erl b/lib/compiler/test/bs_match_SUITE.erl index 224abf6c29..a9bee888d9 100644 --- a/lib/compiler/test/bs_match_SUITE.erl +++ b/lib/compiler/test/bs_match_SUITE.erl @@ -38,7 +38,8 @@ no_partition/1,calling_a_binary/1,binary_in_map/1, match_string_opt/1,select_on_integer/1, map_and_binary/1,unsafe_branch_caching/1, - bad_literals/1,good_literals/1,constant_propagation/1]). + bad_literals/1,good_literals/1,constant_propagation/1 + ]). -export([coverage_id/1,coverage_external_ignore/2]). @@ -768,6 +769,11 @@ multiple_uses(Config) when is_list(Config) -> {344,62879,345,<<245,159,1,89>>} = multiple_uses_1(<<1,88,245,159,1,89>>), true = multiple_uses_2(<<0,0,197,18>>), <<42,43>> = multiple_uses_3(<<0,0,42,43>>, fun id/1), + + ok = first_after(<<>>, 42), + <<1>> = first_after(<<1,2,3>>, 0), + <<2>> = first_after(<<1,2,3>>, 1), + ok. multiple_uses_1(<<X:16,Tail/binary>>) -> @@ -789,6 +795,24 @@ multiple_uses_match(<<Y:16,Z:16>>) -> multiple_uses_cmp(<<Y:16>>, <<Y:16>>) -> true; multiple_uses_cmp(<<_:16>>, <<_:16>>) -> false. +first_after(Data, Offset) -> + case byte_size(Data) > Offset of + false -> + {First, Rest} = {ok, ok}, + ok; + true -> + <<_:Offset/binary, Rest/binary>> = Data, + %% 'Rest' saved in y(0) before the call. + {First, _} = match_first(Data, Rest), + %% When beam_bsm sees the code, the following line + %% which uses y(0) has been optimized away. + {First, Rest} = {First, Rest}, + First + end. + +match_first(_, <<First:1/binary, Rest/binary>>) -> + {First, Rest}. + zero_label(Config) when is_list(Config) -> <<"nosemouth">> = read_pols(<<"FACE","nose","mouth">>), <<"CE">> = read_pols(<<"noFACE">>), diff --git a/lib/crypto/c_src/crypto.c b/lib/crypto/c_src/crypto.c index 0e4e85cef7..c100fc8ee2 100644 --- a/lib/crypto/c_src/crypto.c +++ b/lib/crypto/c_src/crypto.c @@ -588,7 +588,7 @@ static void error_handler(void* null, const char* errstr) } #endif /* HAVE_DYNAMIC_CRYPTO_LIB */ -static int init(ErlNifEnv* env, ERL_NIF_TERM load_info) +static int initialize(ErlNifEnv* env, ERL_NIF_TERM load_info) { #ifdef OPENSSL_THREADS ErlNifSysInfo sys_info; @@ -603,7 +603,7 @@ static int init(ErlNifEnv* env, ERL_NIF_TERM load_info) char lib_buf[1000]; if (!verify_lib_version()) - return 0; + return __LINE__; /* load_info: {301, <<"/full/path/of/this/library">>} */ if (!enif_get_tuple(env, load_info, &tpl_arity, &tpl_array) @@ -613,7 +613,7 @@ static int init(ErlNifEnv* env, ERL_NIF_TERM load_info) || !enif_inspect_binary(env, tpl_array[1], &lib_bin)) { PRINTF_ERR1("CRYPTO: Invalid load_info '%T'", load_info); - return 0; + return __LINE__; } hmac_context_rtype = enif_open_resource_type(env, NULL, "hmac_context", @@ -622,7 +622,7 @@ static int init(ErlNifEnv* env, ERL_NIF_TERM load_info) NULL); if (!hmac_context_rtype) { PRINTF_ERR0("CRYPTO: Could not open resource type 'hmac_context'"); - return 0; + return __LINE__; } #if OPENSSL_VERSION_NUMBER >= OpenSSL_version_plain(1,0,0) evp_md_ctx_rtype = enif_open_resource_type(env, NULL, "EVP_MD_CTX", @@ -631,7 +631,7 @@ static int init(ErlNifEnv* env, ERL_NIF_TERM load_info) NULL); if (!evp_md_ctx_rtype) { PRINTF_ERR0("CRYPTO: Could not open resource type 'EVP_MD_CTX'"); - return 0; + return __LINE__; } #endif #ifdef HAVE_EVP_AES_CTR @@ -641,14 +641,14 @@ static int init(ErlNifEnv* env, ERL_NIF_TERM load_info) NULL); if (!evp_cipher_ctx_rtype) { PRINTF_ERR0("CRYPTO: Could not open resource type 'EVP_CIPHER_CTX'"); - return 0; + return __LINE__; } #endif if (library_refc > 0) { /* Repeated loading of this library (module upgrade). * Atoms and callbacks are already set, we are done. */ - return 1; + return 0; } atom_true = enif_make_atom(env,"true"); @@ -694,14 +694,14 @@ static int init(ErlNifEnv* env, ERL_NIF_TERM load_info) { void* handle; if (!change_basename(&lib_bin, lib_buf, sizeof(lib_buf), crypto_callback_name)) { - return 0; + return __LINE__; } if (!(handle = enif_dlopen(lib_buf, &error_handler, NULL))) { - return 0; + return __LINE__; } if (!(funcp = (get_crypto_callbacks_t*) enif_dlsym(handle, "get_crypto_callbacks", &error_handler, NULL))) { - return 0; + return __LINE__; } } #else /* !HAVE_DYNAMIC_CRYPTO_LIB */ @@ -720,7 +720,7 @@ static int init(ErlNifEnv* env, ERL_NIF_TERM load_info) if (!ccb || ccb->sizeof_me != sizeof(*ccb)) { PRINTF_ERR0("Invalid 'crypto_callbacks'"); - return 0; + return __LINE__; } CRYPTO_set_mem_functions(ccb->crypto_alloc, ccb->crypto_realloc, ccb->crypto_free); @@ -734,13 +734,14 @@ static int init(ErlNifEnv* env, ERL_NIF_TERM load_info) CRYPTO_set_dynlock_destroy_callback(ccb->dyn_destroy_function); } #endif /* OPENSSL_THREADS */ - return 1; + return 0; } static int load(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info) { - if (!init(env, load_info)) { - return -1; + int errline = initialize(env, load_info); + if (errline) { + return errline; } *priv_data = NULL; @@ -751,14 +752,16 @@ static int load(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info) static int upgrade(ErlNifEnv* env, void** priv_data, void** old_priv_data, ERL_NIF_TERM load_info) { + int errline; if (*old_priv_data != NULL) { - return -1; /* Don't know how to do that */ + return __LINE__; /* Don't know how to do that */ } if (*priv_data != NULL) { - return -1; /* Don't know how to do that */ + return __LINE__; /* Don't know how to do that */ } - if (!init(env, load_info)) { - return -1; + errline = initialize(env, load_info); + if (errline) { + return errline; } library_refc++; return 0; diff --git a/lib/dialyzer/doc/src/book.xml b/lib/dialyzer/doc/src/book.xml index aecc0e5bfa..46df8b81b8 100644 --- a/lib/dialyzer/doc/src/book.xml +++ b/lib/dialyzer/doc/src/book.xml @@ -25,7 +25,7 @@ <title>Dialyzer</title> <prepared></prepared> <docno></docno> - <date></date> + <date>2016-09-19</date> <rev></rev> <file>book.xml</file> </header> diff --git a/lib/dialyzer/doc/src/dialyzer.xml b/lib/dialyzer/doc/src/dialyzer.xml index 619db125b1..553bfef41b 100644 --- a/lib/dialyzer/doc/src/dialyzer.xml +++ b/lib/dialyzer/doc/src/dialyzer.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2006</year><year>2015</year> + <year>2006</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -25,341 +25,477 @@ <title>dialyzer</title> <prepared></prepared> <docno></docno> - <date></date> + <date>2016-09-20</date> <rev></rev> + <file>dialyzer.xml</file> </header> <module>dialyzer</module> - <modulesummary>The Dialyzer, a DIscrepancy AnalYZer for ERlang programs</modulesummary> + <modulesummary>Dialyzer, a DIscrepancy AnaLYZer for ERlang programs. + </modulesummary> <description> - <p>The Dialyzer is a static analysis tool that identifies software - discrepancies such as definite type errors, code which has become - dead or unreachable due to some programming error, unnecessary - tests, etc. in single Erlang modules or entire (sets of) - applications. Dialyzer starts its analysis from either - debug-compiled BEAM bytecode or from Erlang source code. The file - and line number of a discrepancy is reported along with an - indication of what the discrepancy is about. Dialyzer bases its - analysis on the concept of success typings which allows for sound - warnings (no false positives).</p> - <p>Read more about Dialyzer and about how to use it from the GUI - in <seealso marker="dialyzer_chapter">Dialyzer User's - Guide</seealso>.</p> + <p>Dialyzer is a static analysis tool that identifies software + discrepancies, such as definite type errors, code that has become dead + or unreachable because of programming error, and unnecessary tests, + in single Erlang modules or entire (sets of) applications.</p> + + <p>Dialyzer starts its analysis from either + debug-compiled BEAM bytecode or from Erlang source code. The file + and line number of a discrepancy is reported along with an + indication of what the discrepancy is about. Dialyzer bases its + analysis on the concept of success typings, which allows for sound + warnings (no false positives).</p> </description> <section> - <title>Using the Dialyzer from the command line</title> - <p>Dialyzer also has a command line version for automated use. Below is a - brief description of the list of its options. The same information can - be obtained by writing</p> - <code type="none"> - dialyzer --help</code> - <p>in a shell. Please refer to the GUI description for more details on - the operation of Dialyzer.</p> - <p>The exit status of the command line version is:</p> + <marker id="command_line"></marker> + <title>Using Dialyzer from the Command Line</title> + <p>Dialyzer has a command-line version for automated use. This + section provides a brief description of the options. The same information + can be obtained by writing the following in a shell:</p> + <code type="none"> - 0 - No problems were encountered during the analysis and no - warnings were emitted. - 1 - Problems were encountered during the analysis. - 2 - No problems were encountered, but warnings were emitted.</code> - <p>Usage:</p> +dialyzer --help</code> + + <p>For more details about the operation of Dialyzer, see section + <seealso marker="dialyzer_chapter#dialyzer_gui"> + Using Dialyzer from the GUI</seealso> in the User's Guide.</p> + + <p><em>Exit status of the command-line version:</em></p> + + <taglist> + <tag><c>0</c></tag> + <item> + <p>No problems were found during the analysis and no warnings were + emitted.</p> + </item> + <tag><c>1</c></tag> + <item> + <p>Problems were found during the analysis.</p> + </item> + <tag><c>2</c></tag> + <item> + <p>No problems were found during the analysis, but warnings were + emitted.</p> + </item> + </taglist> + + <p><em>Usage:</em></p> + <code type="none"> - dialyzer [--help] [--version] [--shell] [--quiet] [--verbose] - [-pa dir]* [--plt plt] [--plts plt*] [-Ddefine]* - [-I include_dir]* [--output_plt file] [-Wwarn]* [--raw] - [--src] [--gui] [files_or_dirs] [-r dirs] - [--apps applications] [-o outfile] - [--build_plt] [--add_to_plt] [--remove_from_plt] - [--check_plt] [--no_check_plt] [--plt_info] [--get_warnings] - [--dump_callgraph file] [--no_native] [--fullpath] - [--statistics] [--no_native_cache]</code> - <p>Options:</p> +dialyzer [--add_to_plt] [--apps applications] [--build_plt] + [--check_plt] [-Ddefine]* [-Dname] [--dump_callgraph file] + [files_or_dirs] [--fullpath] [--get_warnings] [--gui] [--help] + [-I include_dir]* [--no_check_plt] [--no_native] + [--no_native_cache] [-o outfile] [--output_plt file] [-pa dir]* + [--plt plt] [--plt_info] [--plts plt*] [--quiet] [-r dirs] + [--raw] [--remove_from_plt] [--shell] [--src] [--statistics] + [--verbose] [--version] [-Wwarn]*</code> + + <note> + <p>* denotes that multiple occurrences of the option are possible.</p> + </note> + + <p><em>Options:</em></p> + <taglist> - <tag><c><![CDATA[files_or_dirs]]></c> (for backwards compatibility also - as: <c><![CDATA[-c files_or_dirs]]></c>)</tag> - <item>Use Dialyzer from the command line to detect defects in the - specified files or directories containing <c><![CDATA[.erl]]></c> or - <c><![CDATA[.beam]]></c> files, depending on the type of the - analysis.</item> - <tag><c><![CDATA[-r dirs]]></c></tag> - <item>Same as the previous but the specified directories are searched - recursively for subdirectories containing <c><![CDATA[.erl]]></c> or - <c><![CDATA[.beam]]></c> files in them, depending on the type of - analysis.</item> - <tag><c><![CDATA[--apps applications]]></c></tag> - <item>Option typically used when building or modifying a plt as in: + <tag><c>--add_to_plt</c></tag> + <item> + <p>The PLT is extended to also include the files specified with + <c>-c</c> and <c>-r</c>. Use + <c>--plt</c> to specify which PLT to start from, + and <c>--output_plt</c> to specify where to put the PLT. + Notice that the analysis possibly can include files from the PLT if + they depend on the new files. This option only works for BEAM + files.</p> + </item> + <tag><c>--apps applications</c></tag> + <item> + <p>This option is typically used when building or modifying a PLT as + in:</p> <code type="none"> - dialyzer --build_plt --apps erts kernel stdlib mnesia ...</code> - to conveniently refer to library applications corresponding to the - Erlang/OTP installation. However, the option is general and can also - be used during analysis in order to refer to Erlang/OTP applications. - In addition, file or directory names can also be included, as in: +dialyzer --build_plt --apps erts kernel stdlib mnesia ...</code> + <p>to refer conveniently to library applications corresponding to the + Erlang/OTP installation. However, this option is general and can also + be used during analysis to refer to Erlang/OTP applications. + File or directory names can also be included, as in:</p> <code type="none"> - dialyzer --apps inets ssl ./ebin ../other_lib/ebin/my_module.beam</code></item> - <tag><c><![CDATA[-o outfile]]></c> (or - <c><![CDATA[--output outfile]]></c>)</tag> - <item>When using Dialyzer from the command line, send the analysis - results to the specified outfile rather than to stdout.</item> - <tag><c><![CDATA[--raw]]></c></tag> - <item>When using Dialyzer from the command line, output the raw analysis - results (Erlang terms) instead of the formatted result. The raw format - is easier to post-process (for instance, to filter warnings or to - output HTML pages).</item> - <tag><c><![CDATA[--src]]></c></tag> - <item>Override the default, which is to analyze BEAM files, and - analyze starting from Erlang source code instead.</item> - <tag><c><![CDATA[-Dname]]></c> (or <c><![CDATA[-Dname=value]]></c>)</tag> - <item>When analyzing from source, pass the define to Dialyzer. (**)</item> - <tag><c><![CDATA[-I include_dir]]></c></tag> - <item>When analyzing from source, pass the <c><![CDATA[include_dir]]></c> - to Dialyzer. (**)</item> - <tag><c><![CDATA[-pa dir]]></c></tag> - <item>Include <c><![CDATA[dir]]></c> in the path for Erlang (useful when - analyzing files that have <c><![CDATA['-include_lib()']]></c> - directives).</item> - <tag><c><![CDATA[--output_plt file]]></c></tag> - <item>Store the plt at the specified file after building it.</item> - <tag><c><![CDATA[--plt plt]]></c></tag> - <item>Use the specified plt as the initial plt (if the plt was built - during setup the files will be checked for consistency).</item> - <tag><c><![CDATA[--plts plt*]]></c></tag> - <item>Merge the specified plts to create the initial plt -- requires - that the plts are disjoint (i.e., do not have any module - appearing in more than one plt). - The plts are created in the usual way: +dialyzer --apps inets ssl ./ebin ../other_lib/ebin/my_module.beam</code> + </item> + <tag><c>--build_plt</c></tag> + <item> + <p>The analysis starts from an empty PLT and creates a new one from + the files specified with <c>-c</c> and + <c>-r</c>. This option only works for BEAM files. + To override the default PLT location, use + <c>--plt</c> or <c>--output_plt</c>.</p> + </item> + <tag><c>--check_plt</c></tag> + <item> + <p>Check the PLT for consistency and rebuild it if it is not + up-to-date.</p> + </item> + <tag><c>-Dname</c> (or <c>-Dname=value</c>)</tag> + <item> + <p>When analyzing from source, pass the define to Dialyzer. + (**)</p> + </item> + <tag><c>--dump_callgraph file</c></tag> + <item> + <p>Dump the call graph into the specified file whose format is + determined by the filename extension. Supported extensions are: + <c>raw</c>, <c>dot</c>, and <c>ps</c>. If something else is used as + filename extension, default format <c>.raw</c> is used.</p> + </item> + <tag><c>files_or_dirs</c> (for backward compatibility also + as <c>-c files_or_dirs</c>)</tag> + <item> + <p>Use Dialyzer from the command line to detect defects in the + specified files or directories containing <c>.erl</c> or + <c>.beam</c> files, depending on the type of the + analysis.</p> + </item> + <tag><c>--fullpath</c></tag> + <item> + <p>Display the full path names of files for which warnings are + emitted.</p> + </item> + <tag><c>--get_warnings</c></tag> + <item> + <p>Make Dialyzer emit warnings even when manipulating the PLT. + Warnings are only emitted for files that are analyzed.</p> + </item> + <tag><c>--gui</c></tag> + <item> + <p>Use the GUI.</p></item> + <tag><c>--help</c> (or <c>-h</c>)</tag> + <item> + <p>Print this message and exit.</p> + </item> + <tag><c>-I include_dir</c></tag> + <item> + <p>When analyzing from source, pass the <c>include_dir</c> + to Dialyzer. (**)</p> + </item> + <tag><c>--no_check_plt</c></tag> + <item> + <p>Skip the PLT check when running Dialyzer. This is useful when + working with installed PLTs that never change.</p> + </item> + <tag><c>--no_native</c> (or <c>-nn</c>)</tag> + <item> + <p>Bypass the native code compilation of some key files that + Dialyzer heuristically performs when dialyzing many files. + This avoids the compilation time, but can result in (much) longer + analysis time.</p> + </item> + <tag><c>--no_native_cache</c></tag> + <item> + <p>By default, Dialyzer caches the results of native compilation + in directory <c>$XDG_CACHE_HOME/erlang/dialyzer_hipe_cache</c>. + <c>XDG_CACHE_HOME</c> defaults to <c>$HOME/.cache</c>. + Use this option to disable caching.</p> + </item> + <tag><c>-o outfile</c> (or + <c>--output outfile</c>)</tag> + <item> + <p>When using Dialyzer from the command line, send the analysis + results to the specified outfile rather than to <c>stdout</c>.</p> + </item> + <tag><c>--output_plt file</c></tag> + <item> + <p>Store the PLT at the specified file after building it.</p> + </item> + <tag><c>-pa dir</c></tag> + <item> + <p>Include <c>dir</c> in the path for Erlang. This is useful + when analyzing files that have <c>-include_lib()</c> + directives.</p> + </item> + <tag><c>--plt plt</c></tag> + <item> + <p>Use the specified PLT as the initial PLT. If the PLT was built + during setup, the files are checked for consistency.</p> + </item> + <tag><c>--plt_info</c></tag> + <item> + <p>Make Dialyzer print information about the PLT and then quit. + The PLT can be specified with <c>--plt(s)</c>.</p> + </item> + <tag><c>--plts plt*</c></tag> + <item> + <p>Merge the specified PLTs to create the initial PLT. This requires + that the PLTs are disjoint (that is, do not have any module + appearing in more than one PLT). + The PLTs are created in the usual way:</p> <code type="none"> - dialyzer --build_plt --output_plt plt_1 files_to_include - ... - dialyzer --build_plt --output_plt plt_n files_to_include</code> - and then can be used in either of the following ways: +dialyzer --build_plt --output_plt plt_1 files_to_include +... +dialyzer --build_plt --output_plt plt_n files_to_include</code> + <p>They can then be used in either of the following ways:</p> <code type="none"> - dialyzer files_to_analyze --plts plt_1 ... plt_n</code> - or: +dialyzer files_to_analyze --plts plt_1 ... plt_n</code> + <p>or</p> <code type="none"> - dialyzer --plts plt_1 ... plt_n -- files_to_analyze</code> - (Note the -- delimiter in the second case)</item> - <tag><c><![CDATA[-Wwarn]]></c></tag> - <item>A family of options which selectively turn on/off warnings - (for help on the names of warnings use - <c><![CDATA[dialyzer -Whelp]]></c>). - Note that the options can also be given in the file with a - <c>-dialyzer()</c> attribute. See <seealso - marker="#suppression">Requesting or Suppressing Warnings in - Source Files</seealso> below for details.</item> - <tag><c><![CDATA[--shell]]></c></tag> - <item>Do not disable the Erlang shell while running the GUI.</item> - <tag><c><![CDATA[--version]]></c> (or <c><![CDATA[-v]]></c>)</tag> - <item>Print the Dialyzer version and some more information and - exit.</item> - <tag><c><![CDATA[--help]]></c> (or <c><![CDATA[-h]]></c>)</tag> - <item>Print this message and exit.</item> - <tag><c><![CDATA[--quiet]]></c> (or <c><![CDATA[-q]]></c>)</tag> - <item>Make Dialyzer a bit more quiet.</item> - <tag><c><![CDATA[--verbose]]></c></tag> - <item>Make Dialyzer a bit more verbose.</item> - <tag><c><![CDATA[--statistics]]></c></tag> - <item>Prints information about the progress of execution (analysis phases, - time spent in each and size of the relative input).</item> - <tag><c><![CDATA[--build_plt]]></c></tag> - <item>The analysis starts from an empty plt and creates a new one from - the files specified with <c><![CDATA[-c]]></c> and - <c><![CDATA[-r]]></c>. Only works for beam files. Use - <c><![CDATA[--plt]]></c> or <c><![CDATA[--output_plt]]></c> to - override the default plt location.</item> - <tag><c><![CDATA[--add_to_plt]]></c></tag> - <item>The plt is extended to also include the files specified with - <c><![CDATA[-c]]></c> and <c><![CDATA[-r]]></c>. Use - <c><![CDATA[--plt]]></c> to specify which plt to start from, - and <c><![CDATA[--output_plt]]></c> to specify where to put the plt. - Note that the analysis might include files from the plt if they depend - on the new files. This option only works with beam files.</item> - <tag><c><![CDATA[--remove_from_plt]]></c></tag> - <item>The information from the files specified with - <c><![CDATA[-c]]></c> and <c><![CDATA[-r]]></c> is removed - from the plt. Note that this may cause a re-analysis of the remaining - dependent files.</item> - <tag><c><![CDATA[--check_plt]]></c></tag> - <item>Check the plt for consistency and rebuild it if it is not - up-to-date.</item> - <tag><c><![CDATA[--no_check_plt]]></c></tag> - <item>Skip the plt check when running Dialyzer. Useful when working with - installed plts that never change.</item> - <tag><c><![CDATA[--plt_info]]></c></tag> - <item>Make Dialyzer print information about the plt and then quit. The - plt can be specified with <c><![CDATA[--plt(s)]]></c>.</item> - <tag><c><![CDATA[--get_warnings]]></c></tag> - <item>Make Dialyzer emit warnings even when manipulating the plt. - Warnings are only emitted for files that are actually analyzed.</item> - <tag><c><![CDATA[--dump_callgraph file]]></c></tag> - <item>Dump the call graph into the specified file whose format is - determined by the file name extension. Supported extensions are: raw, - dot, and ps. If something else is used as file name extension, default - format '.raw' will be used.</item> - <tag><c><![CDATA[--no_native]]></c> (or <c><![CDATA[-nn]]></c>)</tag> - <item>Bypass the native code compilation of some key files that Dialyzer - heuristically performs when dialyzing many files; this avoids the - compilation time but it may result in (much) longer analysis - time.</item> - <tag><c><![CDATA[--no_native_cache]]></c></tag> - <item>By default, Dialyzer caches the results of native compilation in the - <c>$XDG_CACHE_HOME/erlang/dialyzer_hipe_cache</c> directory. - <c>XDG_CACHE_HOME</c> defaults to <c>$HOME/.cache</c>. - Use this option to disable caching.</item> - <tag><c><![CDATA[--fullpath]]></c></tag> - <item>Display the full path names of files for which warnings are emitted.</item> - <tag><c><![CDATA[--gui]]></c></tag> - <item>Use the GUI.</item> +dialyzer --plts plt_1 ... plt_n -- files_to_analyze</code> + <p>Notice the <c>--</c> delimiter in the second case.</p> + </item> + <tag><c>--quiet</c> (or <c>-q</c>)</tag> + <item> + <p>Make Dialyzer a bit more quiet.</p> + </item> + <tag><c>-r dirs</c></tag> + <item> + <p>Same as <c>files_or_dirs</c>, but the specified + directories are searched + recursively for subdirectories containing <c>.erl</c> or + <c>.beam</c> files in them, depending on the type of + analysis.</p> + </item> + <tag><c>--raw</c></tag> + <item> + <p>When using Dialyzer from the command line, output the raw + analysis results (Erlang terms) instead of the formatted result. + The raw format + is easier to post-process (for example, to filter warnings or to + output HTML pages).</p> + </item> + <tag><c>--remove_from_plt</c></tag> + <item> + <p>The information from the files specified with + <c>-c</c> and <c>-r</c> is removed from + the PLT. Notice that this can cause a reanalysis of the remaining + dependent files.</p> + </item> + <tag><c>--shell</c></tag> + <item> + <p>Do not disable the Erlang shell while running the GUI.</p> + </item> + <tag><c>--src</c></tag> + <item> + <p>Override the default, which is to analyze BEAM files, and + analyze starting from Erlang source code instead.</p> + </item> + <tag><c>--statistics</c></tag> + <item> + <p>Print information about the progress of execution (analysis phases, + time spent in each, and size of the relative input).</p> + </item> + <tag><c>--verbose</c></tag> + <item> + <p>Make Dialyzer a bit more verbose.</p> + </item> + <tag><c>--version</c> (or <c>-v</c>)</tag> + <item> + <p>Print the Dialyzer version and some more information and + exit.</p> + </item> + <tag><c>-Wwarn</c></tag> + <item> + <p>A family of options that selectively turn on/off warnings. + (For help on the names of warnings, use + <c>dialyzer -Whelp</c>.) + Notice that the options can also be specified in the file with a + <c>-dialyzer()</c> attribute. For details, see section <seealso + marker="#suppression">Requesting or Suppressing Warnings in + Source Files</seealso>.</p> + </item> </taglist> + <note> - <p>* denotes that multiple occurrences of these options are possible.</p> - <p>** options <c><![CDATA[-D]]></c> and <c><![CDATA[-I]]></c> work both from command-line and in the Dialyzer GUI; - the syntax of defines and includes is the same as that used by <c><![CDATA[erlc]]></c>.</p> + <p>** options <c>-D</c> and <c>-I</c> work both + from the command line and in the Dialyzer GUI; the syntax of + defines and includes is the same as that used by + <seealso marker="erts:erlc">erlc(1)</seealso>.</p> </note> - <p>Warning options:</p> + + <p><em>Warning options:</em></p> + <taglist> - <tag><c><![CDATA[-Wno_return]]></c></tag> - <item>Suppress warnings for functions that will never return a - value.</item> - <tag><c><![CDATA[-Wno_unused]]></c></tag> - <item>Suppress warnings for unused functions.</item> - <tag><c><![CDATA[-Wno_improper_lists]]></c></tag> - <item>Suppress warnings for construction of improper lists.</item> - <tag><c><![CDATA[-Wno_fun_app]]></c></tag> - <item>Suppress warnings for fun applications that will fail.</item> - <tag><c><![CDATA[-Wno_match]]></c></tag> - <item>Suppress warnings for patterns that are unused or cannot - match.</item> - <tag><c><![CDATA[-Wno_opaque]]></c></tag> - <item>Suppress warnings for violations of opaqueness of data types.</item> - <tag><c><![CDATA[-Wno_fail_call]]></c></tag> - <item>Suppress warnings for failing calls.</item> - <tag><c><![CDATA[-Wno_contracts]]></c></tag> - <item>Suppress warnings about invalid contracts.</item> - <tag><c><![CDATA[-Wno_behaviours]]></c></tag> - <item>Suppress warnings about behaviour callbacks which drift from the - published recommended interfaces.</item> - <tag><c><![CDATA[-Wno_missing_calls]]></c></tag> - <item>Suppress warnings about calls to missing functions.</item> - <tag><c><![CDATA[-Wno_undefined_callbacks]]></c></tag> - <item>Suppress warnings about behaviours that have no - <c>-callback</c> attributes for their callbacks.</item> - <tag><c><![CDATA[-Wunmatched_returns]]></c>***</tag> - <item>Include warnings for function calls which ignore a structured return - value or do not match against one of many possible return - value(s).</item> - <tag><c><![CDATA[-Werror_handling]]></c>***</tag> - <item>Include warnings for functions that only return by means of an - exception.</item> - <tag><c><![CDATA[-Wrace_conditions]]></c>***</tag> - <item>Include warnings for possible race conditions. Note that the - analysis that finds data races performs intra-procedural data flow analysis - and can sometimes explode in time. Enable it at your own risk. - </item> - <tag><c><![CDATA[-Wunderspecs]]></c>***</tag> - <item>Warn about underspecified functions - (the -spec is strictly more allowing than the success typing).</item> - <tag><c><![CDATA[-Wunknown]]></c>***</tag> - <item>Let warnings about unknown functions and types affect the - exit status of the command line version. The default is to ignore - warnings about unknown functions and types when setting the exit - status. When using the Dialyzer from Erlang, warnings about unknown - functions and types are returned; the default is not to return - these warnings.</item> + <tag><c>-Werror_handling</c> (***)</tag> + <item> + <p>Include warnings for functions that only return by an exception.</p> + </item> + <tag><c>-Wno_behaviours</c></tag> + <item> + <p>Suppress warnings about behavior callbacks that drift from the + published recommended interfaces.</p> + </item> + <tag><c>-Wno_contracts</c></tag> + <item> + <p>Suppress warnings about invalid contracts.</p> + </item> + <tag><c>-Wno_fail_call</c></tag> + <item> + <p>Suppress warnings for failing calls.</p> + </item> + <tag><c>-Wno_fun_app</c></tag> + <item> + <p>Suppress warnings for fun applications that will fail.</p> + </item> + <tag><c>-Wno_improper_lists</c></tag> + <item> + <p>Suppress warnings for construction of improper lists.</p> + </item> + <tag><c>-Wno_match</c></tag> + <item> + <p>Suppress warnings for patterns that are unused or cannot match.</p> + </item> + <tag><c>-Wno_missing_calls</c></tag> + <item> + <p>Suppress warnings about calls to missing functions.</p> + </item> + <tag><c>-Wno_opaque</c></tag> + <item> + <p>Suppress warnings for violations of opaqueness of data types.</p> + </item> + <tag><c>-Wno_return</c></tag> + <item> + <p>Suppress warnings for functions that will never return a value.</p> + </item> + <tag><c>-Wno_undefined_callbacks</c></tag> + <item> + <p>Suppress warnings about behaviors that have no + <c>-callback</c> attributes for their callbacks.</p> + </item> + <tag><c>-Wno_unused</c></tag> + <item> + <p>Suppress warnings for unused functions.</p> + </item> + <tag><c>-Wrace_conditions</c> (***)</tag> + <item> + <p>Include warnings for possible race conditions. Notice that the + analysis that finds data races performs intra-procedural data flow + analysis and can sometimes explode in time. Enable it at your own + risk.</p> + </item> + <tag><c>-Wunderspecs</c> (***)</tag> + <item> + <p>Warn about underspecified functions (the specification is strictly + more allowing than the success typing).</p> + </item> + <tag><c>-Wunknown</c> (***)</tag> + <item> + <p>Let warnings about unknown functions and types affect the + exit status of the command-line version. The default is to ignore + warnings about unknown functions and types when setting the exit + status. When using Dialyzer from Erlang, warnings about unknown + functions and types are returned; the default is not to return + these warnings.</p> + </item> + <tag><c>-Wunmatched_returns</c> (***)</tag> + <item> + <p>Include warnings for function calls that ignore a structured return + value or do not match against one of many possible return + value(s).</p> + </item> </taglist> - <p>The following options are also available but their use is not - recommended: (they are mostly for Dialyzer developers and internal - debugging)</p> + + <p>The following options are also available, but their use is not + recommended (they are mostly for Dialyzer developers and internal + debugging):</p> + <taglist> - <tag><c><![CDATA[-Woverspecs]]></c>***</tag> - <item>Warn about overspecified functions - (the -spec is strictly less allowing than the success typing).</item> - <tag><c><![CDATA[-Wspecdiffs]]></c>***</tag> - <item>Warn when the -spec is different than the success typing.</item> + <tag><c>-Woverspecs</c> (***)</tag> + <item> + <p>Warn about overspecified functions (the specification is strictly + less allowing than the success typing).</p> + </item> + <tag><c>-Wspecdiffs</c> (***)</tag> + <item> + <p>Warn when the specification is different than the success typing.</p> + </item> </taglist> + <note> - <p>*** Identifies options that turn on warnings rather than - turning them off.</p> + <p>*** denotes options that turn on warnings rather than + turning them off.</p> </note> </section> <section> - <title>Using the Dialyzer from Erlang</title> - <p>You can also use Dialyzer directly from Erlang. Both the GUI and the - command line versions are available. The options are similar to the ones - given from the command line, so please refer to the sections above for - a description of these.</p> + <title>Using Dialyzer from Erlang</title> + <p>Dialyzer can be used directly from Erlang. Both the GUI and the + command-line versions are also available. The options are similar to the + ones given from the command line, see section + <seealso marker="#command_line"> + Using Dialyzer from the Command Line</seealso>.</p> </section> <section> <marker id="suppression"></marker> <title>Requesting or Suppressing Warnings in Source Files</title> - <p> - The <c>-dialyzer()</c> attribute can be used for turning off + <p>Attribute <c>-dialyzer()</c> can be used for turning off warnings in a module by specifying functions or warning options. For example, to turn off all warnings for the function - <c>f/0</c>, include the following line: - </p> -<code type="none"> --dialyzer({nowarn_function, f/0}). -</code> + <c>f/0</c>, include the following line:</p> + + <code type="none"> +-dialyzer({nowarn_function, f/0}).</code> + <p>To turn off warnings for improper lists, add the following line - to the source file: - </p> -<code type="none"> --dialyzer(no_improper_lists). -</code> - <p>The <c>-dialyzer()</c> attribute is allowed after function - declarations. Lists of warning options or functions are allowed: - </p> -<code type="none"> --dialyzer([{nowarn_function, [f/0]}, no_improper_lists]). -</code> - <p> - Warning options can be restricted to functions: - </p> -<code type="none"> --dialyzer({no_improper_lists, g/0}). -</code> -<code type="none"> --dialyzer({[no_return, no_match], [g/0, h/0]}). -</code> - <p> - For help on the warning options use <c>dialyzer -Whelp</c>. The - options are also enumerated <seealso - marker="#gui/1">below</seealso> (<c>WarnOpts</c>). - </p> + to the source file:</p> + + <code type="none"> +-dialyzer(no_improper_lists).</code> + + <p>Attribute <c>-dialyzer()</c> is allowed after function + declarations. Lists of warning options or functions are allowed:</p> + + <code type="none"> +-dialyzer([{nowarn_function, [f/0]}, no_improper_lists]).</code> + + <p>Warning options can be restricted to functions:</p> + + <code type="none"> +-dialyzer({no_improper_lists, g/0}).</code> + + <code type="none"> +-dialyzer({[no_return, no_match], [g/0, h/0]}).</code> + + <p>For help on the warning options, use <c>dialyzer -Whelp</c>. The + options are also enumerated, see function <seealso marker="#gui/1"> + <c>gui/1</c></seealso> below (<c>WarnOpts</c>).</p> + <note> - <p> - The <c>-dialyzer()</c> attribute is not checked by the Erlang - Compiler, but by the Dialyzer itself. - </p> + <p>Attribute <c>-dialyzer()</c> is not checked by the Erlang + compiler, but by Dialyzer itself.</p> </note> + <note> - <p> - The warning option <c>-Wrace_conditions</c> has no effect when - set in source files. - </p> + <p>Warning option <c>-Wrace_conditions</c> has no effect when + set in source files.</p> </note> - <p> - The <c>-dialyzer()</c> attribute can also be used for turning on - warnings. For instance, if a module has been fixed regarding - unmatched returns, adding the line - </p> -<code type="none"> --dialyzer(unmatched_returns). -</code> - <p> - can help in assuring that no new unmatched return warnings are - introduced. - </p> + + <p>Attribute <c>-dialyzer()</c> can also be used for turning on + warnings. For example, if a module has been fixed regarding + unmatched returns, adding the following line can help in assuring + that no new unmatched return warnings are introduced:</p> + + <code type="none"> +-dialyzer(unmatched_returns).</code> </section> <funcs> <func> + <name>format_warning(Msg) -> string()</name> + <fsummary>Get the string version of a warning message.</fsummary> + <type> + <v>Msg = {Tag, Id, msg()}</v> + <d>See <c>run/1</c>.</d> + </type> + <desc> + <p>Get a string from warnings as returned by + <seealso marker="#run/1"><c>run/1</c></seealso>.</p> + </desc> + </func> + + <func> <name>gui() -> ok | {error, Msg}</name> <name>gui(OptList) -> ok | {error, Msg}</name> - <fsummary>Dialyzer GUI version</fsummary> + <fsummary>Dialyzer GUI version.</fsummary> <type> - <v>OptList -- see below</v> + <v>OptList</v> + <d>See below.</d> </type> <desc> <p>Dialyzer GUI version.</p> @@ -368,9 +504,12 @@ OptList :: [Option] Option :: {files, [Filename :: string()]} | {files_rec, [DirName :: string()]} | {defines, [{Macro :: atom(), Value :: term()}]} - | {from, src_code | byte_code} %% Defaults to byte_code - | {init_plt, FileName :: string()} %% If changed from default - | {plts, [FileName :: string()]} %% If changed from default + | {from, src_code | byte_code} + %% Defaults to byte_code + | {init_plt, FileName :: string()} + %% If changed from default + | {plts, [FileName :: string()]} + %% If changed from default | {include_dirs, [DirName :: string()]} | {output_file, FileName :: string()} | {output_plt, FileName :: string()} @@ -383,76 +522,71 @@ Option :: {files, [Filename :: string()]} | {warnings, [WarnOpts]} | {get_warnings, bool()} -WarnOpts :: no_return - | no_unused - | no_improper_lists +WarnOpts :: error_handling + | no_behaviours + | no_contracts + | no_fail_call | no_fun_app + | no_improper_lists | no_match + | no_missing_calls | no_opaque - | no_fail_call - | no_contracts - | no_behaviours + | no_return | no_undefined_callbacks - | unmatched_returns - | error_handling + | no_unused | race_conditions - | overspecs | underspecs - | specdiffs - | unknown</code> + | unknown + | unmatched_returns + | overspecs + | specdiffs</code> </desc> </func> + <func> - <name>run(OptList) -> Warnings</name> - <fsummary>Dialyzer command line version</fsummary> - <type> - <v>OptList -- see gui/0,1</v> - <v>Warnings -- see below </v> - </type> + <name>plt_info(string()) -> {'ok', [{atom(), any()}]} | {'error', atom()}</name> + <fsummary>Return information about the specified PLT.</fsummary> <desc> - <p>Dialyzer command line version.</p> - <code type="none"> -Warnings :: [{Tag, Id, Msg}] -Tag :: 'warn_behaviour' - | 'warn_bin_construction' - | 'warn_callgraph' - | 'warn_contract_not_equal' - | 'warn_contract_range' - | 'warn_contract_subtype' - | 'warn_contract_supertype' - | 'warn_contract_syntax' - | 'warn_contract_types' - | 'warn_failing_call' - | 'warn_fun_app' - | 'warn_matching' - | 'warn_non_proper_list' - | 'warn_not_called' - | 'warn_opaque' - | 'warn_race_condition' - | 'warn_return_no_exit' - | 'warn_return_only_exit' - | 'warn_umatched_return' - | 'warn_undefined_callbacks' - | 'warn_unknown' -Id = {File :: string(), Line :: integer()} -Msg = msg() -- Undefined</code> + <p>Returns information about the specified PLT.</p> </desc> </func> + <func> - <name>format_warning(Msg) -> string()</name> - <fsummary>Get the string version of a warning message.</fsummary> + <name>run(OptList) -> Warnings</name> + <fsummary>Dialyzer command-line version.</fsummary> <type> - <v>Msg = {Tag, Id, msg()} -- See run/1</v> + <v>OptList</v> + <d>See <c>gui/0,1</c>.</d> + <v>Warnings</v> + <d>See below.</d> </type> <desc> - <p>Get a string from warnings as returned by dialyzer:run/1.</p> - </desc> - </func> - <func> - <name>plt_info(string()) -> {'ok', [{atom(), any()}]} | {'error', atom()}</name> - <fsummary>Returns information about the specified plt.</fsummary> - <desc> - <p>Returns information about the specified plt.</p> + <p>Dialyzer command-line version.</p> + <code type="none"> +Warnings :: [{Tag, Id, Msg}] +Tag :: 'warn_behaviour' + | 'warn_bin_construction' + | 'warn_callgraph' + | 'warn_contract_not_equal' + | 'warn_contract_range' + | 'warn_contract_subtype' + | 'warn_contract_supertype' + | 'warn_contract_syntax' + | 'warn_contract_types' + | 'warn_failing_call' + | 'warn_fun_app' + | 'warn_matching' + | 'warn_non_proper_list' + | 'warn_not_called' + | 'warn_opaque' + | 'warn_race_condition' + | 'warn_return_no_exit' + | 'warn_return_only_exit' + | 'warn_umatched_return' + | 'warn_undefined_callbacks' + | 'warn_unknown' +Id = {File :: string(), Line :: integer()} +Msg = msg() -- Undefined</code> </desc> </func> </funcs> diff --git a/lib/dialyzer/doc/src/dialyzer_chapter.xml b/lib/dialyzer/doc/src/dialyzer_chapter.xml index c445f2633f..b5acf3732e 100644 --- a/lib/dialyzer/doc/src/dialyzer_chapter.xml +++ b/lib/dialyzer/doc/src/dialyzer_chapter.xml @@ -25,196 +25,211 @@ <title>Dialyzer</title> <prepared></prepared> <docno></docno> - <date></date> + <date>2016-09-19</date> <rev></rev> <file>dialyzer_chapter.xml</file> </header> <section> <title>Introduction</title> - <p><em>Dialyzer</em> is a static analysis tool that identifies software discrepancies - such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules - or entire (sets of) applications.</p> - </section> - - <section> - <title>Using the Dialyzer from the GUI</title> - <section> - <title>Choosing the applications or modules</title> - <p>In the "File" window you will find a listing of the current directory. - Click your way to the directories/modules you want to add or type the - correct path in the entry.</p> - <p>Mark the directories/modules you want to analyze for discrepancies and - click "Add". You can either add the <c><![CDATA[.beam]]></c> and <c><![CDATA[.erl]]></c>-files directly, or - you can add directories that contain these kinds of files. Note that - you are only allowed to add the type of files that can be analyzed in - the current mode of operation (see below), and that you cannot mix - <c><![CDATA[.beam]]></c> and <c><![CDATA[.erl]]></c>-files.</p> + <title>Scope</title> + <p>Dialyzer is a static analysis tool that identifies software + discrepancies, such as definite type errors, code that has become dead + or unreachable because of programming error, and unnecessary tests, + in single Erlang modules or entire (sets of) applications.</p> + + <p>Dialyzer can be called from the command line, from Erlang, + and from a GUI.</p> </section> <section> - <title>The analysis modes</title> - <p>Dialyzer has two modes of analysis, "Byte Code" or "Source Code". - These are controlled by the buttons in the top-middle part of the - main window, under "Analysis Options".</p> - </section> - - <section> - <title>Controlling the discrepancies reported by the Dialyzer</title> - <p>Under the "Warnings" pull-down menu, there are buttons that control - which discrepancies are reported to the user in the "Warnings" window. - By clicking on these buttons, one can enable/disable a whole class of - warnings. Information about the classes of warnings can be found on - the "Warnings" item under the "Help" menu (at the rightmost top corner).</p> - <p>If modules are compiled with inlining, spurious warnings may be emitted. - In the "Options" menu you can choose to ignore inline-compiled modules - when analyzing byte code. When starting from source code this is not a - problem since the inlining is explicitly turned off by Dialyzer. The - option causes Dialyzer to suppress all warnings from inline-compiled - modules, since there is currently no way for Dialyzer to find what - parts of the code have been produced by inlining. </p> + <title>Prerequisites</title> + <p>It is assumed that the reader is familiar with the Erlang programming + language.</p> </section> + </section> - <section> - <title>Running the analysis</title> - <p>Once you have chosen the modules or directories you want to analyze, - click the "Run" button to start the analysis. If for some reason you - want to stop the analysis while it is running, push the "Stop" button.</p> - <p>The information from the analysis will be displayed in the Log and the - Warnings windows.</p> - </section> + <section> + <marker id="plt"/> + <title>The Persistent Lookup Table</title> + <p>Dialyzer stores the result of an analysis in a Persistent + Lookup Table (PLT). The PLT can then be used as a starting + point for later analyses. It is recommended to build a PLT with the + Erlang/OTP applications that you are using, but also to include your + own applications that you are using frequently.</p> + + <p>The PLT is built using option <c>--build_plt</c> to Dialyzer. + The following command builds the recommended minimal PLT for + Erlang/OTP:</p> - <section> - <title>Include directories and macro definitions</title> - <p>When analyzing from source you might have to supply Dialyzer with a - list of include directories and macro definitions (as you can do with - the <c><![CDATA[erlc]]></c> flags <c><![CDATA[-I]]></c> and <c><![CDATA[-D]]></c>). This can be done either by starting Dialyzer - with these flags from the command line as in:</p> - <code type="none"> + <code type="none"> +dialyzer --build_plt --apps erts kernel stdlib mnesia</code> - dialyzer -I my_includes -DDEBUG -Dvsn=42 -I one_more_dir - </code> - <p>or by adding these explicitly using the "Manage Macro Definitions" or - "Manage Include Directories" sub-menus in the "Options" menu.</p> - </section> + <p>Dialyzer looks if there is an environment variable called + <c>DIALYZER_PLT</c> and places the PLT at this location. If no such + variable is set, Dialyzer places the PLT at + <c>$HOME/.dialyzer_plt</c>. The placement can also be specified using + the options <c>--plt</c> or <c>--output_plt</c>.</p> - <section> - <title>Saving the information on the Log and Warnings windows</title> - <p>In the "File" menu there are options to save the contents of the Log - and the Warnings window. Just choose the options and enter the file to - save the contents in.</p> - <p>There are also buttons to clear the contents of each window.</p> - </section> + <p>Information can be added to an existing PLT using option + <c>--add_to_plt</c>. If you also want to include the Erlang compiler in + the PLT and place it in a new PLT, then use the following command:</p> - <section> - <title>Inspecting the inferred types of the analyzed functions</title> - <p>Dialyzer stores the information of the analyzed functions in a - Persistent Lookup Table (PLT). After an analysis you can inspect this - information. In the PLT menu you can choose to either search the PLT - or inspect the contents of the whole PLT. The information is presented - in edoc format.</p> - </section> - </section> + <code type="none"> +dialyzer --add_to_plt --apps compiler --output_plt my.plt</code> - <section> - <title>Using the Dialyzer from the command line</title> - <p>See <seealso marker="dialyzer">dialyzer(3)</seealso>.</p> - </section> + <p>Then you can add your favorite application my_app to the new + PLT:</p> - <section> - <title>Using the Dialyzer from Erlang</title> - <p>See <seealso marker="dialyzer">dialyzer(3)</seealso>.</p> - </section> + <code type="none"> +dialyzer --add_to_plt --plt my.plt -r my_app/ebin</code> - <section> - <title>More on the Persistent Lookup Table (PLT)</title> + <p>But you realize that it is unnecessary to have the Erlang compiler in this + one:</p> - <p> The persistent lookup table, or PLT, is used to store the - result of an analysis. The PLT can then be used as a starting - point for later analyses. It is recommended to build a PLT with - the otp applications that you are using, but also to include your - own applications that you are using frequently.</p> + <code type="none"> +dialyzer --remove_from_plt --plt my.plt --apps compiler</code> - <p>The PLT is built using the --build_plt option to dialyzer. The - following command builds the recommended minimal PLT for OTP.</p> + <p>Later, when you have fixed a bug in your application my_app, + you want to update the PLT so that it becomes fresh the next time + you run Dialyzer. In this case, run the following command:</p> <code type="none"> +dialyzer --check_plt --plt my.plt</code> - dialyzer --build_plt -r $ERL_TOP/lib/stdlib/ebin\ - $ERL_TOP/lib/kernel/ebin \ - $ERL_TOP/lib/mnesia/ebin - </code> + <p>Dialyzer then reanalyzes the changed files + and the files that depend on these files. Notice that this + consistency check is performed automatically the next time you + run Dialyzer with this PLT. Option <c>--check_plt</c> is only + for doing so without doing any other analysis.</p> - <p>Dialyzer will look if there is an environment variable called - $DIALYZER_PLT and place the PLT at this location. If no such - variable is set, Dialyzer will place the PLT at - $HOME/.dialyzer_plt. The placement can also be specified using the - --plt, or --output_plt options.</p> - - <p>You can also add information to an existing plt using the - --add_to_plt option. Suppose you want to also include the compiler - in the PLT and place it in a new PLT, then give the command</p> + <p>To get information about a PLT, use the following option:</p> <code type="none"> +dialyzer --plt_info</code> - dialyzer --add_to_plt -r $ERL_TOP/lib/compiler/ebin --output_plt my.plt - </code> + <p>To specify which PLT, use option <c>--plt</c>.</p> - <p>Then you would like to add your favorite application my_app to - the new plt.</p> + <p>To get the output printed to a file, use option <c>--output_file</c>.</p> - <code type="none"> + <p>Notice that when manipulating the PLT, no warnings are + emitted. To turn on warnings during (re)analysis of the PLT, use + option <c>--get_warnings</c>.</p> + </section> - dialyzer --add_to_plt --plt my.plt -r my_app/ebin - </code> + <section> + <title>Using Dialyzer from the Command Line</title> + <p>Dialyzer has a command-line version for automated use. + See <seealso marker="dialyzer"><c>dialyzer(3)</c></seealso>.</p> + </section> - <p>But you realize that it is unnecessary to have compiler in this one.</p> + <section> + <title>Using Dialyzer from Erlang</title> + <p>Dialyzer can also be used directly from Erlang. + See <seealso marker="dialyzer"><c>dialyzer(3)</c></seealso>.</p> + </section> - <code type="none"> + <section> + <marker id="dialyzer_gui"/> + <title>Using Dialyzer from the GUI</title> + <section> + <title>Choosing the Applications or Modules</title> + <p>The <em>File</em> window displays a listing of the current directory. + Click your way to the directories/modules you want to add or type the + correct path in the entry.</p> - dialyzer --remove_from_plt --plt my.plt -r $ERL_TOP/lib/compiler/ebin - </code> + <p>Mark the directories/modules you want to analyze for discrepancies and + click <em>Add</em>. You can either add the <c>.beam</c> and + <c>.erl</c> files directly, or add directories that contain + these kind of files. Notice that + you are only allowed to add the type of files that can be analyzed in + the current mode of operation (see below), and that you cannot mix + <c>.beam</c> and <c>.erl</c> files.</p> + </section> - <p> Later, when you have fixed a bug in your application my_app, - you want to update the plt so that it will be fresh the next time - you run Dialyzer, run the command</p> + <section> + <title>Analysis Modes</title> + <p>Dialyzer has two analysis modes: "Byte Code" and "Source Code". + They are controlled by the buttons in the top-middle part of the + main window, under <em>Analysis Options</em>.</p> + </section> - <code type="none"> + <section> + <title>Controlling the Discrepancies Reported by Dialyzer</title> + <p>Under the <em>Warnings</em> pull-down menu, there are buttons that + control which discrepancies are reported to the user in the + <em>Warnings</em> window. By clicking these buttons, you can + enable/disable a whole class of warnings. Information about the classes + of warnings is found on the "Warnings" item under the <em>Help</em> + menu (in the rightmost top corner).</p> + + <p>If modules are compiled with inlining, spurious warnings can be + emitted. In the <em>Options</em> menu you can choose to ignore + inline-compiled modules when analyzing byte code. + When starting from source code, this is not a problem because + inlining is explicitly turned off by Dialyzer. The option causes + Dialyzer to suppress all warnings from inline-compiled + modules, as there is currently no way for Dialyzer to find what + parts of the code have been produced by inlining.</p> + </section> - dialyzer --check_plt --plt my.plt - </code> + <section> + <title>Running the Analysis</title> + <p>Once you have chosen the modules or directories you want to analyze, + click the <em>Run</em> button to start the analysis. If you for some + reason want to stop the analysis while it is running, click the + <em>Stop</em> button.</p> - <p> Dialyzer will then reanalyze the files that have been changed, - and the files that depend on these files. Note that this - consistency check will be performed automatically the next time - you run Dialyzer with this plt. The --check_plt option is merely - for doing so without doing any other analysis.</p> + <p>The information from the analysis is displayed in the <em>Log</em> + window and the <em>Warnings</em> window.</p> + </section> - <p> To get some information about a plt use the option</p> - <code type="none"> + <section> + <title>Include Directories and Macro Definitions</title> + <p>When analyzing from source, you might have to supply Dialyzer + with a list of include directories and macro definitions (as you can do + with the <seealso marker="erts:erlc"><c>erlc</c></seealso> flags + <c>-I</c> and <c>-D</c>). This can be done + either by starting Dialyzer with these flags from the command + line as in:</p> + + <code type="none"> +dialyzer -I my_includes -DDEBUG -Dvsn=42 -I one_more_dir</code> - dialyzer --plt_info - </code> + <p>or by adding these explicitly using submenu + <em>Manage Macro Definitions</em> or + <em>Manage Include Directories</em> in the <em>Options</em> menu.</p> + </section> - <p>You can also specify which plt with the --plt option, and get the - output printed to a file with --output_file</p> + <section> + <title>Saving the Information on the Log and Warnings Windows</title> + <p>The <em>File</em> menu includes options to save the contents of the + <em>Log</em> window and the <em>Warnings</em> window. Simply choose the + options and enter the file to save the contents in.</p> - <p>Note that when manipulating the plt, no warnings are - emitted. To turn on warnings during (re)analysis of the plt, use - the option --get_warnings.</p> + <p>There are also buttons to clear the contents of each window.</p> + </section> + <section> + <title>Inspecting the Inferred Types of the Analyzed Functions</title> + <p>Dialyzer stores the information of the analyzed functions in a + Persistent Lookup Table (PLT), see section + <seealso marker="#plt">The Persistent Lookup Table</seealso>.</p> + + <p>After an analysis, you can inspect this information. + In the <em>PLT</em> menu you can choose to either search the PLT + or inspect the contents of the whole PLT. The information is presented + in <seealso marker="edoc:edoc"><c>EDoc</c></seealso> format.</p> + </section> </section> <section> - <title>Feedback and bug reports</title> - <p>At this point, we very much welcome user feedback (even wish-lists!). - If you notice something weird, especially if the Dialyzer reports any - discrepancy that is a false positive, please send an error report - describing the symptoms and how to reproduce them to:</p> - <code type="none"><![CDATA[ - ]]></code> + <title>Feedback and Bug Reports</title> + <p>We very much welcome user feedback - even wishlists! + If you notice anything weird, especially if Dialyzer reports + any discrepancy that is a false positive, please send an error report + describing the symptoms and how to reproduce them.</p> </section> </chapter> diff --git a/lib/dialyzer/doc/src/part.xml b/lib/dialyzer/doc/src/part.xml index 575f77549a..9bfcf21a66 100644 --- a/lib/dialyzer/doc/src/part.xml +++ b/lib/dialyzer/doc/src/part.xml @@ -25,12 +25,11 @@ <title>Dialyzer User's Guide</title> <prepared></prepared> <docno></docno> - <date></date> + <date>2016-09-19</date> <rev></rev> <file>part.xml</file> </header> <description> - <p><em>Dialyzer</em> is a static analysis tool that identifies software discrepancies such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules or entire (sets of) applications.</p> </description> <xi:include href="dialyzer_chapter.xml"/> </part> diff --git a/lib/dialyzer/doc/src/ref_man.xml b/lib/dialyzer/doc/src/ref_man.xml index 01478cfb40..ddac047f2e 100644 --- a/lib/dialyzer/doc/src/ref_man.xml +++ b/lib/dialyzer/doc/src/ref_man.xml @@ -25,11 +25,10 @@ <title>Dialyzer Reference Manual</title> <prepared></prepared> <docno></docno> - <date></date> + <date>2016-09-19</date> <rev></rev> </header> <description> - <p><em>Dialyzer</em> is a static analysis tool that identifies software discrepancies such as type errors, unreachable code, unnecessary tests, etc in single Erlang modules or entire (sets of) applications.</p> </description> <xi:include href="dialyzer.xml"/> </application> diff --git a/lib/dialyzer/src/dialyzer_analysis_callgraph.erl b/lib/dialyzer/src/dialyzer_analysis_callgraph.erl index 50fc1d8471..08e55a78bd 100644 --- a/lib/dialyzer/src/dialyzer_analysis_callgraph.erl +++ b/lib/dialyzer/src/dialyzer_analysis_callgraph.erl @@ -406,24 +406,28 @@ compile_common(File, AbstrCode, CompOpts, Callgraph, CServer, {ok, RecInfo} -> CServer1 = dialyzer_codeserver:store_temp_records(Mod, RecInfo, CServer), - MetaFunInfo = - dialyzer_utils:get_fun_meta_info(Mod, AbstrCode, LegalWarnings), - CServer2 = - dialyzer_codeserver:insert_fun_meta_info(MetaFunInfo, CServer1), - case UseContracts of - true -> - case dialyzer_utils:get_spec_info(Mod, AbstrCode, RecInfo) of - {error, _} = Error -> Error; - {ok, SpecInfo, CallbackInfo} -> - CServer3 = - dialyzer_codeserver:store_temp_contracts(Mod, SpecInfo, - CallbackInfo, - CServer2), - store_core(Mod, Core, Callgraph, CServer3) - end; - false -> - store_core(Mod, Core, Callgraph, CServer2) - end + case + dialyzer_utils:get_fun_meta_info(Mod, AbstrCode, LegalWarnings) + of + {error, _} = Error -> Error; + MetaFunInfo -> + CServer2 = + dialyzer_codeserver:insert_fun_meta_info(MetaFunInfo, CServer1), + case UseContracts of + true -> + case dialyzer_utils:get_spec_info(Mod, AbstrCode, RecInfo) of + {error, _} = Error -> Error; + {ok, SpecInfo, CallbackInfo} -> + CServer3 = + dialyzer_codeserver:store_temp_contracts(Mod, SpecInfo, + CallbackInfo, + CServer2), + store_core(Mod, Core, Callgraph, CServer3) + end; + false -> + store_core(Mod, Core, Callgraph, CServer2) + end + end end end. diff --git a/lib/dialyzer/src/dialyzer_utils.erl b/lib/dialyzer/src/dialyzer_utils.erl index 76a5cf3d0b..1f2d3e3aaa 100644 --- a/lib/dialyzer/src/dialyzer_utils.erl +++ b/lib/dialyzer/src/dialyzer_utils.erl @@ -514,16 +514,21 @@ get_spec_info([], SpecDict, CallbackDict, {ok, SpecDict, CallbackDict}. -spec get_fun_meta_info(module(), abstract_code(), [dial_warn_tag()]) -> - dialyzer_codeserver:fun_meta_info(). + dialyzer_codeserver:fun_meta_info() | {'error', string()}. get_fun_meta_info(M, Abs, LegalWarnings) -> - NoWarn = get_nowarn_unused_function(M, Abs), - FuncSupp = get_func_suppressions(M, Abs), - Warnings0 = get_options(Abs, LegalWarnings), - Warnings = ordsets:to_list(Warnings0), - ModuleWarnings = [{M, W} || W <- Warnings], - RawProps = lists:append([NoWarn, FuncSupp, ModuleWarnings]), - process_options(dialyzer_utils:family(RawProps), Warnings0). + try + {get_nowarn_unused_function(M, Abs), get_func_suppressions(M, Abs)} + of + {NoWarn, FuncSupp} -> + Warnings0 = get_options(Abs, LegalWarnings), + Warnings = ordsets:to_list(Warnings0), + ModuleWarnings = [{M, W} || W <- Warnings], + RawProps = lists:append([NoWarn, FuncSupp, ModuleWarnings]), + process_options(dialyzer_utils:family(RawProps), Warnings0) + catch throw:{error, _} = Error -> + Error + end. process_options([{M, _}=Mod|Left], Warnings) when is_atom(M) -> [Mod|process_options(Left, Warnings)]; diff --git a/lib/dialyzer/test/opaque_SUITE_data/dialyzer_options b/lib/dialyzer/test/opaque_SUITE_data/dialyzer_options index ffdf8270c8..06ed52043a 100644 --- a/lib/dialyzer/test/opaque_SUITE_data/dialyzer_options +++ b/lib/dialyzer/test/opaque_SUITE_data/dialyzer_options @@ -1,2 +1,2 @@ {dialyzer_options, [{warnings, [no_unused, no_return]}]}. -{time_limit, 2}. +{time_limit, 20}. diff --git a/lib/dialyzer/test/opaque_SUITE_data/results/para b/lib/dialyzer/test/opaque_SUITE_data/results/para index 8fe67e39ad..b23d0cae3a 100644 --- a/lib/dialyzer/test/opaque_SUITE_data/results/para +++ b/lib/dialyzer/test/opaque_SUITE_data/results/para @@ -19,9 +19,9 @@ para3.erl:55: Invalid type specification for function para3:t2/0. The success ty para3.erl:65: The attempt to match a term of type {{{{{para3_adt:ot1(_,_,_,_,_)}}}}} against the pattern {{{{{17}}}}} breaks the opaqueness of para3_adt:ot1(_,_,_,_,_) para3.erl:68: The pattern {{{{17}}}} can never match the type {{{{{para3_adt:ot1(_,_,_,_,_)}}}}} para3.erl:74: Invalid type specification for function para3:exp_adt/0. The success typing is () -> 3 -para4.erl:21: Invalid type specification for function para4:a/1. The success typing is (dict:dict(atom() | integer(),atom() | integer()) | para4:d_all()) -> [{atom() | integer(),atom() | integer()}] -para4.erl:26: Invalid type specification for function para4:i/1. The success typing is (dict:dict(atom() | integer(),atom() | integer()) | para4:d_all()) -> [{atom() | integer(),atom() | integer()}] -para4.erl:31: Invalid type specification for function para4:t/1. The success typing is (dict:dict(atom() | integer(),atom() | integer()) | para4:d_all()) -> [{atom() | integer(),atom() | integer()}] +para4.erl:21: Invalid type specification for function para4:a/1. The success typing is (para4:d_all() | para4:d_atom()) -> [{atom() | integer(),atom() | integer()}] +para4.erl:26: Invalid type specification for function para4:i/1. The success typing is (para4:d_all() | para4:d_integer()) -> [{atom() | integer(),atom() | integer()}] +para4.erl:31: Invalid type specification for function para4:t/1. The success typing is (para4:d_all() | para4:d_tuple()) -> [{atom() | integer(),atom() | integer()}] para4.erl:59: Attempt to test for equality between a term of type para4_adt:t(atom() | integer()) and a term of opaque type para4_adt:t(integer()) para4.erl:64: Attempt to test for equality between a term of type para4_adt:t(atom() | integer()) and a term of opaque type para4_adt:t(atom()) para4.erl:69: Attempt to test for equality between a term of type para4_adt:int(1 | 2 | 3 | 4) and a term of opaque type para4_adt:int(1 | 2) diff --git a/lib/dialyzer/test/opaque_SUITE_data/src/hipe_vectors/hipe_ig_moves.erl b/lib/dialyzer/test/opaque_SUITE_data/src/hipe_vectors/hipe_ig_moves.erl new file mode 100644 index 0000000000..2a70606dab --- /dev/null +++ b/lib/dialyzer/test/opaque_SUITE_data/src/hipe_vectors/hipe_ig_moves.erl @@ -0,0 +1,83 @@ +%% -*- erlang-indent-level: 2 -*- +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2001-2016. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% +%% +%%============================================================================= + +-module(hipe_ig_moves). +-export([new/1, + new_move/3, + get_moves/1]). + +%%----------------------------------------------------------------------------- +%% The main data structure; its fields are: +%% - movelist : mapping from temp to set of associated move numbers +%% - nrmoves : number of distinct move instructions seen so far +%% - moveinsns : list of move instructions, in descending move number order +%% - moveset : set of move instructions + +-record(ig_moves, {movelist :: movelist(), + nrmoves = 0 :: non_neg_integer(), + moveinsns = [] :: [{_,_}], + moveset = gb_sets:empty() :: gb_sets:set()}). + +-type movelist() :: hipe_vectors:vector(ordsets:ordset(non_neg_integer())). + +%%----------------------------------------------------------------------------- + +-spec new(non_neg_integer()) -> #ig_moves{}. + +new(NrTemps) -> + MoveList = hipe_vectors:new(NrTemps, ordsets:new()), + #ig_moves{movelist = MoveList}. + +-spec new_move(_, _, #ig_moves{}) -> #ig_moves{}. + +new_move(Dst, Src, IG_moves) -> + MoveSet = IG_moves#ig_moves.moveset, + MoveInsn = {Dst, Src}, + case gb_sets:is_member(MoveInsn, MoveSet) of + true -> + IG_moves; + false -> + MoveNr = IG_moves#ig_moves.nrmoves, + Movelist0 = IG_moves#ig_moves.movelist, + Movelist1 = add_movelist(MoveNr, Dst, + add_movelist(MoveNr, Src, Movelist0)), + IG_moves#ig_moves{nrmoves = MoveNr+1, + movelist = Movelist1, + moveinsns = [MoveInsn|IG_moves#ig_moves.moveinsns], + moveset = gb_sets:insert(MoveInsn, MoveSet)} + end. + +-spec add_movelist(non_neg_integer(), non_neg_integer(), movelist()) + -> movelist(). + +add_movelist(MoveNr, Temp, MoveList) -> + AssocMoves = hipe_vectors:get(MoveList, Temp), + %% XXX: MoveNr does not occur in moveList[Temp], but the new list must be an + %% ordset due to the ordsets:union in hipe_coalescing_regalloc:combine(). + hipe_vectors:set(MoveList, Temp, ordsets:add_element(MoveNr, AssocMoves)). + +-spec get_moves(#ig_moves{}) -> {movelist(), non_neg_integer(), tuple()}. + +get_moves(IG_moves) -> % -> {MoveList, NrMoves, MoveInsns} + {IG_moves#ig_moves.movelist, + IG_moves#ig_moves.nrmoves, + list_to_tuple(lists:reverse(IG_moves#ig_moves.moveinsns))}. diff --git a/lib/dialyzer/test/opaque_SUITE_data/src/hipe_vectors/hipe_vectors.erl b/lib/dialyzer/test/opaque_SUITE_data/src/hipe_vectors/hipe_vectors.erl new file mode 100644 index 0000000000..279f244586 --- /dev/null +++ b/lib/dialyzer/test/opaque_SUITE_data/src/hipe_vectors/hipe_vectors.erl @@ -0,0 +1,136 @@ +%% -*- erlang-indent-level: 2 -*- +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2001-2016. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% VECTORS IN ERLANG +%% +%% Abstract interface to vectors, indexed from 0 to size-1. + +-module(hipe_vectors). +-export([new/2, + set/3, + get/2, + size/1, + vector_to_list/1, + %% list_to_vector/1, + list/1]). + +%%-define(USE_TUPLES, true). +%%-define(USE_GBTREES, true). +-define(USE_ARRAYS, true). + +-type vector() :: vector(_). +-export_type([vector/0, vector/1]). + +-spec new(non_neg_integer(), V) -> vector(E) when V :: E. +-spec set(vector(E), non_neg_integer(), V :: E) -> vector(E). +-spec get(vector(E), non_neg_integer()) -> E. +-spec size(vector(_)) -> non_neg_integer(). +-spec vector_to_list(vector(E)) -> [E]. +%% -spec list_to_vector([E]) -> vector(E). +-spec list(vector(E)) -> [{non_neg_integer(), E}]. + +%% --------------------------------------------------------------------- + +-ifdef(USE_TUPLES). +-opaque vector(_) :: tuple(). + +new(N, V) -> + erlang:make_tuple(N, V). + +size(V) -> erlang:tuple_size(V). + +list(Vec) -> + index(tuple_to_list(Vec), 0). + +index([X|Xs],N) -> + [{N,X} | index(Xs,N+1)]; +index([],_) -> + []. + +%% list_to_vector(Xs) -> +%% list_to_tuple(Xs). + +vector_to_list(V) -> + tuple_to_list(V). + +set(Vec, Ix, V) -> + setelement(Ix+1, Vec, V). + +get(Vec, Ix) -> element(Ix+1, Vec). + +-endif. %% ifdef USE_TUPLES + +%% --------------------------------------------------------------------- + +-ifdef(USE_GBTREES). +-opaque vector(E) :: gb_trees:tree(non_neg_integer(), E). + +new(N, V) when is_integer(N), N >= 0 -> + gb_trees:from_orddict(mklist(N, V)). + +mklist(N, V) -> + mklist(0, N, V). + +mklist(M, N, V) when M < N -> + [{M, V} | mklist(M+1, N, V)]; +mklist(_, _, _) -> + []. + +size(V) -> gb_trees:size(V). + +list(Vec) -> + gb_trees:to_list(Vec). + +%% list_to_vector(Xs) -> +%% gb_trees:from_orddict(index(Xs, 0)). +%% +%% index([X|Xs], N) -> +%% [{N, X} | index(Xs, N+1)]; +%% index([],_) -> +%% []. + +vector_to_list(V) -> + gb_trees:values(V). + +set(Vec, Ix, V) -> + gb_trees:update(Ix, V, Vec). + +get(Vec, Ix) -> + gb_trees:get(Ix, Vec). + +-endif. %% ifdef USE_GBTREES + +%% --------------------------------------------------------------------- + +-ifdef(USE_ARRAYS). +-opaque vector(E) :: array:array(E). +%%-type vector(E) :: array:array(E). % Work around dialyzer bug + +new(N, V) -> array:new(N, {default, V}). +size(V) -> array:size(V). +list(Vec) -> array:to_orddict(Vec). +%% list_to_vector(Xs) -> array:from_list(Xs). +vector_to_list(V) -> array:to_list(V). +set(Vec, Ix, V) -> array:set(Ix, V, Vec). +get(Vec, Ix) -> array:get(Ix, Vec). + +-endif. %% ifdef USE_ARRAYS diff --git a/lib/dialyzer/test/opaque_SUITE_data/src/recrec/cerl.erl b/lib/dialyzer/test/opaque_SUITE_data/src/recrec/cerl.erl new file mode 100644 index 0000000000..a4fdbfd5f0 --- /dev/null +++ b/lib/dialyzer/test/opaque_SUITE_data/src/recrec/cerl.erl @@ -0,0 +1,4602 @@ +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2001-2016. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% + +%% ===================================================================== +%% @doc Core Erlang abstract syntax trees. +%% +%% <p> This module defines an abstract data type for representing Core +%% Erlang source code as syntax trees.</p> +%% +%% <p>A recommended starting point for the first-time user is the +%% documentation of the function <a +%% href="#type-1"><code>type/1</code></a>.</p> +%% +%% <h3><b>NOTES:</b></h3> +%% +%% <p>This module deals with the composition and decomposition of +%% <em>syntactic</em> entities (as opposed to semantic ones); its +%% purpose is to hide all direct references to the data structures +%% used to represent these entities. With few exceptions, the +%% functions in this module perform no semantic interpretation of +%% their inputs, and in general, the user is assumed to pass +%% type-correct arguments - if this is not done, the effects are not +%% defined.</p> +%% +%% <p>Currently, the internal data structure used is the same as +%% the record-based data structures used traditionally in the Beam +%% compiler.</p> +%% +%% <p>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 functions that operate on syntax +%% trees.</p> +%% +%% @type cerl(). An abstract Core Erlang syntax tree. +%% +%% <p>Every abstract syntax tree has a <em>type</em>, given by the +%% function <a href="#type-1"><code>type/1</code></a>. In addition, +%% each syntax tree has a list of <em>user annotations</em> (cf. <a +%% href="#get_ann-1"><code>get_ann/1</code></a>), which are included +%% in the Core Erlang syntax.</p> + +-module(cerl). + +-export([abstract/1, add_ann/2, alias_pat/1, alias_var/1, + ann_abstract/2, ann_c_alias/3, ann_c_apply/3, ann_c_atom/2, + ann_c_call/4, ann_c_case/3, ann_c_catch/2, ann_c_char/2, + ann_c_clause/3, ann_c_clause/4, ann_c_cons/3, ann_c_float/2, + ann_c_fname/3, ann_c_fun/3, ann_c_int/2, ann_c_let/4, + ann_c_letrec/3, ann_c_module/4, ann_c_module/5, ann_c_nil/1, + ann_c_cons_skel/3, ann_c_tuple_skel/2, ann_c_primop/3, + ann_c_receive/2, ann_c_receive/4, ann_c_seq/3, ann_c_string/2, + ann_c_try/6, ann_c_tuple/2, ann_c_values/2, ann_c_var/2, + ann_make_data/3, ann_make_list/2, ann_make_list/3, + ann_make_data_skel/3, ann_make_tree/3, apply_args/1, + apply_arity/1, apply_op/1, atom_lit/1, atom_name/1, atom_val/1, + c_alias/2, c_apply/2, c_atom/1, c_call/3, c_case/2, c_catch/1, + c_char/1, c_clause/2, c_clause/3, c_cons/2, c_float/1, + c_fname/2, c_fun/2, c_int/1, c_let/3, c_letrec/2, c_module/3, + c_module/4, c_nil/0, c_cons_skel/2, c_tuple_skel/1, c_primop/2, + c_receive/1, c_receive/3, c_seq/2, c_string/1, c_try/5, + c_tuple/1, c_values/1, c_var/1, call_args/1, call_arity/1, + call_module/1, call_name/1, case_arg/1, case_arity/1, + case_clauses/1, catch_body/1, char_lit/1, char_val/1, + clause_arity/1, clause_body/1, clause_guard/1, clause_pats/1, + clause_vars/1, concrete/1, cons_hd/1, cons_tl/1, copy_ann/2, + data_arity/1, data_es/1, data_type/1, float_lit/1, float_val/1, + fname_arity/1, fname_id/1, fold_literal/1, from_records/1, + fun_arity/1, fun_body/1, fun_vars/1, get_ann/1, int_lit/1, + int_val/1, is_c_alias/1, is_c_apply/1, is_c_atom/1, + is_c_call/1, is_c_case/1, is_c_catch/1, is_c_char/1, + is_c_clause/1, is_c_cons/1, is_c_float/1, is_c_fname/1, + is_c_fun/1, is_c_int/1, is_c_let/1, is_c_letrec/1, is_c_list/1, + is_c_module/1, is_c_nil/1, is_c_primop/1, is_c_receive/1, + is_c_seq/1, is_c_string/1, is_c_try/1, is_c_tuple/1, + is_c_values/1, is_c_var/1, is_data/1, is_leaf/1, is_literal/1, + is_literal_term/1, is_print_char/1, is_print_string/1, + let_arg/1, let_arity/1, let_body/1, let_vars/1, letrec_body/1, + letrec_defs/1, letrec_vars/1, list_elements/1, list_length/1, + make_data/2, make_list/1, make_list/2, make_data_skel/2, + make_tree/2, meta/1, module_attrs/1, module_defs/1, + module_exports/1, module_name/1, module_vars/1, + pat_list_vars/1, pat_vars/1, primop_args/1, primop_arity/1, + primop_name/1, receive_action/1, receive_clauses/1, + receive_timeout/1, seq_arg/1, seq_body/1, set_ann/2, + string_lit/1, string_val/1, subtrees/1, to_records/1, + try_arg/1, try_body/1, try_vars/1, try_evars/1, try_handler/1, + tuple_arity/1, tuple_es/1, type/1, unfold_literal/1, + update_c_alias/3, update_c_apply/3, update_c_call/4, + update_c_case/3, update_c_catch/2, update_c_clause/4, + update_c_cons/3, update_c_cons_skel/3, update_c_fname/2, + update_c_fname/3, update_c_fun/3, update_c_let/4, + update_c_letrec/3, update_c_module/5, update_c_primop/3, + update_c_receive/4, update_c_seq/3, update_c_try/6, + update_c_tuple/2, update_c_tuple_skel/2, update_c_values/2, + update_c_var/2, update_data/3, update_list/2, update_list/3, + update_data_skel/3, update_tree/2, update_tree/3, + values_arity/1, values_es/1, var_name/1, c_binary/1, + update_c_binary/2, ann_c_binary/2, is_c_binary/1, + binary_segments/1, c_bitstr/3, c_bitstr/4, c_bitstr/5, + update_c_bitstr/5, update_c_bitstr/6, ann_c_bitstr/5, + ann_c_bitstr/6, is_c_bitstr/1, bitstr_val/1, bitstr_size/1, + bitstr_bitsize/1, bitstr_unit/1, bitstr_type/1, bitstr_flags/1, + + %% keep map exports here for now + c_map_pattern/1, + is_c_map/1, + is_c_map_pattern/1, + map_es/1, + map_arg/1, + update_c_map/3, + c_map/1, is_c_map_empty/1, + ann_c_map/2, ann_c_map/3, + ann_c_map_pattern/2, + map_pair_op/1,map_pair_key/1,map_pair_val/1, + update_c_map_pair/4, + c_map_pair/2, c_map_pair_exact/2, + ann_c_map_pair/4 + ]). + +-export_type([c_binary/0, c_bitstr/0, c_call/0, c_clause/0, c_cons/0, c_fun/0, + c_let/0, c_literal/0, c_map/0, c_map_pair/0, + c_module/0, c_tuple/0, + c_values/0, c_var/0, cerl/0, + anns/0, attrs/0, defs/0, litval/0, var_name/0]). + +-include("core_parse.hrl"). + +-type c_alias() :: #c_alias{}. +-type c_apply() :: #c_apply{}. +-type c_binary() :: #c_binary{}. +-type c_bitstr() :: #c_bitstr{}. +-type c_call() :: #c_call{}. +-type c_case() :: #c_case{}. +-type c_catch() :: #c_catch{}. +-type c_clause() :: #c_clause{}. +-type c_cons() :: #c_cons{}. +-type c_fun() :: #c_fun{}. +-type c_let() :: #c_let{}. +-type c_letrec() :: #c_letrec{}. +-type c_literal() :: #c_literal{}. +-type c_map() :: #c_map{}. +-type c_map_pair() :: #c_map_pair{}. +-type c_module() :: #c_module{}. +-type c_primop() :: #c_primop{}. +-type c_receive() :: #c_receive{}. +-type c_seq() :: #c_seq{}. +-type c_try() :: #c_try{}. +-type c_tuple() :: #c_tuple{}. +-type c_values() :: #c_values{}. +-type c_var() :: #c_var{}. + +-type cerl() :: c_alias() | c_apply() | c_binary() | c_bitstr() + | c_call() | c_case() | c_catch() | c_clause() | c_cons() + | c_fun() | c_let() | c_letrec() | c_literal() + | c_map() | c_map_pair() + | c_module() | c_primop() | c_receive() | c_seq() + | c_try() | c_tuple() | c_values() | c_var(). + +-type anns() :: [term()]. +-type attr() :: {c_literal(), c_literal()}. +-type attrs() :: [attr()]. +-type def() :: {c_var(), c_fun()}. +-type defs() :: [def()]. + +-type litval() :: atom() | bitstring() | map() | number() + | string() | tuple() | [litval()]. + +-type var_name() :: integer() | atom() | {atom(), arity()}. + + +%% ===================================================================== +%% Representation (general) +%% +%% All nodes are represented by tuples of arity 2 or (generally) +%% greater, whose first element is an atom which uniquely identifies the +%% type of the node, and whose second element is a (proper) list of +%% annotation terms associated with the node - this is by default empty. +%% +%% For most node constructor functions, there are analogous functions +%% named 'ann_...', taking one extra argument 'As' (always the first +%% argument), specifying an annotation list at node creation time. +%% Similarly, there are also functions named 'update_...', taking one +%% extra argument 'Old', specifying a node from which all fields not +%% explicitly given as arguments should be copied (generally, this is +%% the annotation field only). +%% ===================================================================== + +%% @spec type(Node::cerl()) -> atom() +%% +%% @doc Returns the type tag of <code>Node</code>. Current node types +%% are: +%% +%% <p><center><table border="1"> +%% <tr> +%% <td>alias</td> +%% <td>apply</td> +%% <td>binary</td> +%% <td>bitstr</td> +%% <td>call</td> +%% <td>case</td> +%% <td>catch</td> +%% <td>clause</td> +%% </tr><tr> +%% <td>cons</td> +%% <td>fun</td> +%% <td>let</td> +%% <td>letrec</td> +%% <td>literal</td> +%% <td>map</td> +%% <td>map_pair</td> +%% <td>module</td> +%% </tr><tr> +%% <td>primop</td> +%% <td>receive</td> +%% <td>seq</td> +%% <td>try</td> +%% <td>tuple</td> +%% <td>values</td> +%% <td>var</td> +%% </tr> +%% </table></center></p> +%% +%% <p>Note: The name of the primary constructor function for a node +%% type is always the name of the type itself, prefixed by +%% "<code>c_</code>"; recognizer predicates are correspondingly +%% prefixed by "<code>is_c_</code>". Furthermore, to simplify +%% preservation of annotations (cf. <code>get_ann/1</code>), there are +%% analogous constructor functions prefixed by "<code>ann_c_</code>" +%% and "<code>update_c_</code>", for setting the annotation list of +%% the new node to either a specific value or to the annotations of an +%% existing node, respectively.</p> +%% +%% @see abstract/1 +%% @see c_alias/2 +%% @see c_apply/2 +%% @see c_binary/1 +%% @see c_bitstr/5 +%% @see c_call/3 +%% @see c_case/2 +%% @see c_catch/1 +%% @see c_clause/3 +%% @see c_cons/2 +%% @see c_fun/2 +%% @see c_let/3 +%% @see c_letrec/2 +%% @see c_module/3 +%% @see c_primop/2 +%% @see c_receive/1 +%% @see c_seq/2 +%% @see c_try/5 +%% @see c_tuple/1 +%% @see c_values/1 +%% @see c_var/1 +%% @see get_ann/1 +%% @see to_records/1 +%% @see from_records/1 +%% @see data_type/1 +%% @see subtrees/1 +%% @see meta/1 + +-type ctype() :: 'alias' | 'apply' | 'binary' | 'bitrst' | 'call' | 'case' + | 'catch' | 'clause' | 'cons' | 'fun' | 'let' | 'letrec' + | 'literal' | 'map' | 'map_pair' | 'module' | 'primop' + | 'receive' | 'seq' | 'try' | 'tuple' | 'values' | 'var'. + +-spec type(cerl()) -> ctype(). + +type(#c_alias{}) -> alias; +type(#c_apply{}) -> apply; +type(#c_binary{}) -> binary; +type(#c_bitstr{}) -> bitstr; +type(#c_call{}) -> call; +type(#c_case{}) -> 'case'; +type(#c_catch{}) -> 'catch'; +type(#c_clause{}) -> clause; +type(#c_cons{}) -> cons; +type(#c_fun{}) -> 'fun'; +type(#c_let{}) -> 'let'; +type(#c_letrec{}) -> letrec; +type(#c_literal{}) -> literal; +type(#c_map{}) -> map; +type(#c_map_pair{}) -> map_pair; +type(#c_module{}) -> module; +type(#c_primop{}) -> primop; +type(#c_receive{}) -> 'receive'; +type(#c_seq{}) -> seq; +type(#c_try{}) -> 'try'; +type(#c_tuple{}) -> tuple; +type(#c_values{}) -> values; +type(#c_var{}) -> var. + + +%% @spec is_leaf(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is a leaf node, +%% otherwise <code>false</code>. The current leaf node types are +%% <code>literal</code> and <code>var</code>. +%% +%% <p>Note: all literals (cf. <code>is_literal/1</code>) are leaf +%% nodes, even if they represent structured (constant) values such as +%% <code>{foo, [bar, baz]}</code>. Also note that variables are leaf +%% nodes but not literals.</p> +%% +%% @see type/1 +%% @see is_literal/1 + +-spec is_leaf(cerl()) -> boolean(). + +is_leaf(Node) -> + case type(Node) of + literal -> true; + var -> true; + _ -> false + end. + + +%% @spec get_ann(cerl()) -> anns() +%% +%% @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. +%% +%% @see set_ann/2 + +-spec get_ann(cerl()) -> anns(). + +get_ann(Node) -> + element(2, Node). + + +%% @spec set_ann(Node::cerl(), Annotations::anns()) -> cerl() +%% +%% @doc Sets the list of user annotations of <code>Node</code> to +%% <code>Annotations</code>. +%% +%% @see get_ann/1 +%% @see add_ann/2 +%% @see copy_ann/2 + +-spec set_ann(cerl(), anns()) -> cerl(). + +set_ann(Node, List) -> + setelement(2, Node, List). + + +%% @spec add_ann(Annotations::anns(), Node::cerl()) -> cerl() +%% +%% @doc Appends <code>Annotations</code> to the list of user +%% annotations of <code>Node</code>. +%% +%% <p>Note: this is equivalent to <code>set_ann(Node, Annotations ++ +%% get_ann(Node))</code>, but potentially more efficient.</p> +%% +%% @see get_ann/1 +%% @see set_ann/2 + +-spec add_ann(anns(), cerl()) -> cerl(). + +add_ann(Terms, Node) -> + set_ann(Node, Terms ++ get_ann(Node)). + + +%% @spec copy_ann(Source::cerl(), Target::cerl()) -> cerl() +%% +%% @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> +%% +%% @see get_ann/1 +%% @see set_ann/2 + +-spec copy_ann(cerl(), cerl()) -> cerl(). + +copy_ann(Source, Target) -> + set_ann(Target, get_ann(Source)). + + +%% @spec abstract(Term::litval()) -> cerl() +%% +%% @doc Creates a syntax tree corresponding to an Erlang term. +%% <code>Term</code> 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 or function value as a subterm. +%% +%% <p>Note: This is a constant time operation.</p> +%% +%% @see ann_abstract/2 +%% @see concrete/1 +%% @see is_literal/1 +%% @see is_literal_term/1 + +-spec abstract(litval()) -> c_literal(). + +abstract(T) -> + #c_literal{val = T}. + + +%% @spec ann_abstract(Annotations::anns(), Term::litval()) -> cerl() +%% @see abstract/1 + +-spec ann_abstract(anns(), litval()) -> c_literal(). + +ann_abstract(As, T) -> + #c_literal{val = T, anno = As}. + + +%% @spec is_literal_term(Term::term()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Term</code> can be +%% represented as a literal, otherwise <code>false</code>. This +%% function takes time proportional to the size of <code>Term</code>. +%% +%% @see abstract/1 + +-spec is_literal_term(term()) -> boolean(). + +is_literal_term(T) when is_integer(T) -> true; +is_literal_term(T) when is_float(T) -> true; +is_literal_term(T) when is_atom(T) -> true; +is_literal_term([]) -> true; +is_literal_term([H | T]) -> + is_literal_term(H) andalso is_literal_term(T); +is_literal_term(T) when is_tuple(T) -> + is_literal_term_list(tuple_to_list(T)); +is_literal_term(B) when is_bitstring(B) -> true; +is_literal_term(M) when is_map(M) -> + is_literal_term_list(maps:to_list(M)); +is_literal_term(_) -> + false. + +-spec is_literal_term_list([term()]) -> boolean(). + +is_literal_term_list([T | Ts]) -> + case is_literal_term(T) of + true -> + is_literal_term_list(Ts); + false -> + false + end; +is_literal_term_list([]) -> + true. + + +%% @spec concrete(Node::c_literal()) -> litval() +%% +%% @doc Returns the Erlang term represented by a syntax tree. An +%% exception is thrown if <code>Node</code> does not represent a +%% literal term. +%% +%% <p>Note: This is a constant time operation.</p> +%% +%% @see abstract/1 +%% @see is_literal/1 + +%% Because the normal tuple and list constructor operations always +%% return a literal if the arguments are literals, 'concrete' and +%% 'is_literal' never need to traverse the structure. + +-spec concrete(c_literal()) -> litval(). + +concrete(#c_literal{val = V}) -> + V. + + +%% @spec is_literal(Node::cerl()) -> 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. +%% +%% <p>Note: This is a constant time operation.</p> +%% +%% @see abstract/1 +%% @see concrete/1 +%% @see fold_literal/1 + +-spec is_literal(cerl()) -> boolean(). + +is_literal(#c_literal{}) -> + true; +is_literal(_) -> + false. + + +%% @spec fold_literal(Node::cerl()) -> cerl() +%% +%% @doc Assures that literals have a compact representation. This is +%% occasionally useful if <code>c_cons_skel/2</code>, +%% <code>c_tuple_skel/1</code> or <code>unfold_literal/1</code> were +%% used in the construction of <code>Node</code>, and you want to revert +%% to the normal "folded" representation of literals. If +%% <code>Node</code> represents a tuple or list constructor, its +%% elements are rewritten recursively, and the node is reconstructed +%% using <code>c_cons/2</code> or <code>c_tuple/1</code>, respectively; +%% otherwise, <code>Node</code> is not changed. +%% +%% @see is_literal/1 +%% @see c_cons_skel/2 +%% @see c_tuple_skel/1 +%% @see c_cons/2 +%% @see c_tuple/1 +%% @see unfold_literal/1 + +-spec fold_literal(cerl()) -> cerl(). + +fold_literal(Node) -> + case type(Node) of + tuple -> + update_c_tuple(Node, fold_literal_list(tuple_es(Node))); + cons -> + update_c_cons(Node, fold_literal(cons_hd(Node)), + fold_literal(cons_tl(Node))); + _ -> + Node + end. + +fold_literal_list([E | Es]) -> + [fold_literal(E) | fold_literal_list(Es)]; +fold_literal_list([]) -> + []. + + +%% @spec unfold_literal(Node::cerl()) -> cerl() +%% +%% @doc Assures that literals have a fully expanded representation. If +%% <code>Node</code> represents a literal tuple or list constructor, its +%% elements are rewritten recursively, and the node is reconstructed +%% using <code>c_cons_skel/2</code> or <code>c_tuple_skel/1</code>, +%% respectively; otherwise, <code>Node</code> is not changed. The {@link +%% fold_literal/1} can be used to revert to the normal compact +%% representation. +%% +%% @see is_literal/1 +%% @see c_cons_skel/2 +%% @see c_tuple_skel/1 +%% @see c_cons/2 +%% @see c_tuple/1 +%% @see fold_literal/1 + +-spec unfold_literal(cerl()) -> cerl(). + +unfold_literal(Node) -> + case type(Node) of + literal -> + copy_ann(Node, unfold_concrete(concrete(Node))); + _ -> + Node + end. + +unfold_concrete(Val) -> + case Val of + _ when is_tuple(Val) -> + c_tuple_skel(unfold_concrete_list(tuple_to_list(Val))); + [H|T] -> + c_cons_skel(unfold_concrete(H), unfold_concrete(T)); + _ -> + abstract(Val) + end. + +unfold_concrete_list([E | Es]) -> + [unfold_concrete(E) | unfold_concrete_list(Es)]; +unfold_concrete_list([]) -> + []. + + +%% --------------------------------------------------------------------- + +%% @spec c_module(Name::c_literal(), Exports, Definitions) -> c_module() +%% +%% Exports = [c_var()] +%% Definitions = defs() +%% +%% @equiv c_module(Name, Exports, [], Definitions) + +-spec c_module(c_literal(), [c_var()], defs()) -> c_module(). + +c_module(Name, Exports, Defs) -> + #c_module{name = Name, exports = Exports, attrs = [], defs = Defs}. + + +%% @spec c_module(Name::c_literal(), Exports, Attributes, Definitions) -> +%% c_module() +%% +%% Exports = [c_var()] +%% Attributes = attrs() +%% Definitions = defs() +%% +%% @doc Creates an abstract module definition. The result represents +%% <pre> +%% module <em>Name</em> [<em>E1</em>, ..., <em>Ek</em>] +%% attributes [<em>K1</em> = <em>T1</em>, ..., +%% <em>Km</em> = <em>Tm</em>] +%% <em>V1</em> = <em>F1</em> +%% ... +%% <em>Vn</em> = <em>Fn</em> +%% end</pre> +%% +%% if <code>Exports</code> = <code>[E1, ..., Ek]</code>, +%% <code>Attributes</code> = <code>[{K1, T1}, ..., {Km, Tm}]</code>, +%% and <code>Definitions</code> = <code>[{V1, F1}, ..., {Vn, +%% Fn}]</code>. +%% +%% <p><code>Name</code> and all the <code>Ki</code> must be atom +%% literals, and all the <code>Ti</code> must be constant literals. All +%% the <code>Vi</code> and <code>Ei</code> must have type +%% <code>var</code> and represent function names. All the +%% <code>Fi</code> must have type <code>'fun'</code>.</p> +%% +%% @see c_module/3 +%% @see module_name/1 +%% @see module_exports/1 +%% @see module_attrs/1 +%% @see module_defs/1 +%% @see module_vars/1 +%% @see ann_c_module/4 +%% @see ann_c_module/5 +%% @see update_c_module/5 +%% @see c_atom/1 +%% @see c_var/1 +%% @see c_fun/2 +%% @see is_literal/1 + +-spec c_module(c_literal(), [c_var()], attrs(), defs()) -> c_module(). + +c_module(Name, Exports, Attrs, Defs) -> + #c_module{name = Name, exports = Exports, attrs = Attrs, defs = Defs}. + + +%% @spec ann_c_module(As::anns(), Name::c_literal(), Exports, +%% Definitions) -> c_module() +%% +%% Exports = [c_var()] +%% Definitions = defs() +%% +%% @see c_module/3 +%% @see ann_c_module/5 + +-spec ann_c_module(anns(), c_literal(), [c_var()], defs()) -> c_module(). + +ann_c_module(As, Name, Exports, Defs) -> + #c_module{name = Name, exports = Exports, attrs = [], defs = Defs, + anno = As}. + + +%% @spec ann_c_module(As::anns(), Name::c_literal(), Exports, +%% Attributes, Definitions) -> c_module() +%% +%% Exports = [c_var()] +%% Attributes = attrs() +%% Definitions = defs() +%% +%% @see c_module/4 +%% @see ann_c_module/4 + +-spec ann_c_module(anns(), c_literal(), [c_var()], attrs(), defs()) -> + c_module(). + +ann_c_module(As, Name, Exports, Attrs, Defs) -> + #c_module{name = Name, exports = Exports, attrs = Attrs, defs = Defs, + anno = As}. + + +%% @spec update_c_module(Old::cerl(), Name::c_literal(), Exports, +%% Attributes, Definitions) -> c_module() +%% +%% Exports = [c_var()] +%% Attributes = attrs() +%% Definitions = defs() +%% +%% @see c_module/4 + +-spec update_c_module(c_module(), c_literal(), [c_var()], attrs(), defs()) -> + c_module(). + +update_c_module(Node, Name, Exports, Attrs, Defs) -> + #c_module{name = Name, exports = Exports, attrs = Attrs, defs = Defs, + anno = get_ann(Node)}. + + +%% @spec is_c_module(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% module definition, otherwise <code>false</code>. +%% +%% @see type/1 + +-spec is_c_module(cerl()) -> boolean(). + +is_c_module(#c_module{}) -> + true; +is_c_module(_) -> + false. + + +%% @spec module_name(Node::c_module()) -> c_literal() +%% +%% @doc Returns the name subtree of an abstract module definition. +%% +%% @see c_module/4 + +-spec module_name(c_module()) -> c_literal(). + +module_name(Node) -> + Node#c_module.name. + + +%% @spec module_exports(Node::c_module()) -> [c_var()] +%% +%% @doc Returns the list of exports subtrees of an abstract module +%% definition. +%% +%% @see c_module/4 + +-spec module_exports(c_module()) -> [c_var()]. + +module_exports(Node) -> + Node#c_module.exports. + + +%% @spec module_attrs(Node::c_module()) -> [{cerl(), cerl()}] +%% +%% @doc Returns the list of pairs of attribute key/value subtrees of +%% an abstract module definition. +%% +%% @see c_module/4 + +-spec module_attrs(c_module()) -> attrs(). + +module_attrs(Node) -> + Node#c_module.attrs. + + +%% @spec module_defs(Node::c_module()) -> defs() +%% +%% @doc Returns the list of function definitions of an abstract module +%% definition. +%% +%% @see c_module/4 + +-spec module_defs(c_module()) -> defs(). + +module_defs(Node) -> + Node#c_module.defs. + + +%% @spec module_vars(Node::c_module()) -> [c_var()] +%% +%% @doc Returns the list of left-hand side function variable subtrees +%% of an abstract module definition. +%% +%% @see c_module/4 + +-spec module_vars(c_module()) -> [c_var()]. + +module_vars(Node) -> + [F || {F, _} <- module_defs(Node)]. + + +%% --------------------------------------------------------------------- + +%% @spec c_int(Value::integer()) -> c_literal() +%% +%% @doc Creates an abstract integer literal. The lexical +%% representation is the canonical decimal numeral of +%% <code>Value</code>. +%% +%% @see ann_c_int/2 +%% @see is_c_int/1 +%% @see int_val/1 +%% @see int_lit/1 +%% @see c_char/1 + +-spec c_int(integer()) -> c_literal(). + +c_int(Value) -> + #c_literal{val = Value}. + + +%% @spec ann_c_int(As::anns(), Value::integer()) -> c_literal() +%% @see c_int/1 + +-spec ann_c_int(anns(), integer()) -> c_literal(). + +ann_c_int(As, Value) -> + #c_literal{val = Value, anno = As}. + + +%% @spec is_c_int(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> represents an +%% integer literal, otherwise <code>false</code>. +%% @see c_int/1 + +-spec is_c_int(cerl()) -> boolean(). + +is_c_int(#c_literal{val = V}) when is_integer(V) -> + true; +is_c_int(_) -> + false. + + +%% @spec int_val(c_literal()) -> integer() +%% +%% @doc Returns the value represented by an integer literal node. +%% @see c_int/1 + +-spec int_val(c_literal()) -> integer(). + +int_val(Node) -> + Node#c_literal.val. + + +%% @spec int_lit(c_literal()) -> string() +%% +%% @doc Returns the numeral string represented by an integer literal +%% node. +%% @see c_int/1 + +-spec int_lit(c_literal()) -> string(). + +int_lit(Node) -> + integer_to_list(int_val(Node)). + + +%% --------------------------------------------------------------------- + +%% @spec c_float(Value::float()) -> c_literal() +%% +%% @doc Creates an abstract floating-point literal. The lexical +%% representation is the decimal floating-point numeral of +%% <code>Value</code>. +%% +%% @see ann_c_float/2 +%% @see is_c_float/1 +%% @see float_val/1 +%% @see float_lit/1 + +%% Note that not all floating-point numerals can be represented with +%% full precision. + +-spec c_float(float()) -> c_literal(). + +c_float(Value) -> + #c_literal{val = Value}. + + +%% @spec ann_c_float(As::anns(), Value::float()) -> c_literal() +%% @see c_float/1 + +-spec ann_c_float(anns(), float()) -> c_literal(). + +ann_c_float(As, Value) -> + #c_literal{val = Value, anno = As}. + + +%% @spec is_c_float(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> represents a +%% floating-point literal, otherwise <code>false</code>. +%% @see c_float/1 + +-spec is_c_float(cerl()) -> boolean(). + +is_c_float(#c_literal{val = V}) when is_float(V) -> + true; +is_c_float(_) -> + false. + + +%% @spec float_val(c_literal()) -> float() +%% +%% @doc Returns the value represented by a floating-point literal +%% node. +%% @see c_float/1 + +-spec float_val(c_literal()) -> float(). + +float_val(Node) -> + Node#c_literal.val. + + +%% @spec float_lit(c_literal()) -> string() +%% +%% @doc Returns the numeral string represented by a floating-point +%% literal node. +%% @see c_float/1 + +-spec float_lit(c_literal()) -> string(). + +float_lit(Node) -> + float_to_list(float_val(Node)). + + +%% --------------------------------------------------------------------- + +%% @spec c_atom(Name) -> c_literal() +%% Name = atom() | string() +%% +%% @doc Creates an abstract atom literal. The print name of the atom +%% is the character sequence represented by <code>Name</code>. +%% +%% <p>Note: passing a string as argument to this function causes a +%% corresponding atom to be created for the internal representation.</p> +%% +%% @see ann_c_atom/2 +%% @see is_c_atom/1 +%% @see atom_val/1 +%% @see atom_name/1 +%% @see atom_lit/1 + +-spec c_atom(atom() | string()) -> c_literal(). + +c_atom(Name) when is_atom(Name) -> + #c_literal{val = Name}; +c_atom(Name) -> + #c_literal{val = list_to_atom(Name)}. + + +%% @spec ann_c_atom(As::anns(), Name) -> cerl() +%% Name = atom() | string() +%% @see c_atom/1 + +-spec ann_c_atom(anns(), atom() | string()) -> c_literal(). + +ann_c_atom(As, Name) when is_atom(Name) -> + #c_literal{val = Name, anno = As}; +ann_c_atom(As, Name) -> + #c_literal{val = list_to_atom(Name), anno = As}. + + +%% @spec is_c_atom(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> represents an +%% atom literal, otherwise <code>false</code>. +%% +%% @see c_atom/1 + +-spec is_c_atom(cerl()) -> boolean(). + +is_c_atom(#c_literal{val = V}) when is_atom(V) -> + true; +is_c_atom(_) -> + false. + +%% @spec atom_val(c_literal()) -> atom() +%% +%% @doc Returns the value represented by an abstract atom. +%% +%% @see c_atom/1 + +-spec atom_val(c_literal()) -> atom(). + +atom_val(Node) -> + Node#c_literal.val. + + +%% @spec atom_name(c_literal()) -> string() +%% +%% @doc Returns the printname of an abstract atom. +%% +%% @see c_atom/1 + +-spec atom_name(c_literal()) -> string(). + +atom_name(Node) -> + atom_to_list(atom_val(Node)). + + +%% @spec atom_lit(cerl()) -> string() +%% +%% @doc Returns the literal string represented by an abstract +%% atom. This always includes surrounding single-quote characters. +%% +%% <p>Note that an abstract atom may have several literal +%% representations, and that the representation yielded by this +%% function is not fixed; e.g., +%% <code>atom_lit(c_atom("a\012b"))</code> could yield the string +%% <code>"\'a\\nb\'"</code>.</p> +%% +%% @see c_atom/1 + +%% TODO: replace the use of the unofficial 'write_string/2'. + +-spec atom_lit(cerl()) -> nonempty_string(). + +atom_lit(Node) -> + io_lib:write_string(atom_name(Node), $'). %' stupid Emacs. + + +%% --------------------------------------------------------------------- + +%% @spec c_char(Value) -> c_literal() +%% +%% Value = char() | integer() +%% +%% @doc Creates an abstract character literal. If the local +%% implementation of Erlang defines <code>char()</code> as a subset of +%% <code>integer()</code>, this function is equivalent to +%% <code>c_int/1</code>. Otherwise, if the given value is an integer, +%% it will be converted to the character with the corresponding +%% code. The lexical representation of a character is +%% "<code>$<em>Char</em></code>", where <code>Char</code> is a single +%% printing character or an escape sequence. +%% +%% @see c_int/1 +%% @see c_string/1 +%% @see ann_c_char/2 +%% @see is_c_char/1 +%% @see char_val/1 +%% @see char_lit/1 +%% @see is_print_char/1 + +-spec c_char(non_neg_integer()) -> c_literal(). + +c_char(Value) when is_integer(Value), Value >= 0 -> + #c_literal{val = Value}. + + +%% @spec ann_c_char(As::anns(), Value::char()) -> c_literal() +%% @see c_char/1 + +-spec ann_c_char(anns(), char()) -> c_literal(). + +ann_c_char(As, Value) -> + #c_literal{val = Value, anno = As}. + + +%% @spec is_c_char(Node::c_literal()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> may represent a +%% character literal, otherwise <code>false</code>. +%% +%% <p>If the local implementation of Erlang defines +%% <code>char()</code> as a subset of <code>integer()</code>, then +%% <code>is_c_int(<em>Node</em>)</code> will also yield +%% <code>true</code>.</p> +%% +%% @see c_char/1 +%% @see is_print_char/1 + +-spec is_c_char(c_literal()) -> boolean(). + +is_c_char(#c_literal{val = V}) when is_integer(V), V >= 0 -> + is_char_value(V); +is_c_char(_) -> + false. + + +%% @spec is_print_char(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> may represent a +%% "printing" character, otherwise <code>false</code>. (Cf. +%% <code>is_c_char/1</code>.) A "printing" character has either a +%% given graphical representation, or a "named" escape sequence such +%% as "<code>\n</code>". Currently, only ISO 8859-1 (Latin-1) +%% character values are recognized. +%% +%% @see c_char/1 +%% @see is_c_char/1 + +-spec is_print_char(cerl()) -> boolean(). + +is_print_char(#c_literal{val = V}) when is_integer(V), V >= 0 -> + is_print_char_value(V); +is_print_char(_) -> + false. + + +%% @spec char_val(c_literal()) -> char() +%% +%% @doc Returns the value represented by an abstract character literal. +%% +%% @see c_char/1 + +-spec char_val(c_literal()) -> char(). + +char_val(Node) -> + Node#c_literal.val. + + +%% @spec char_lit(c_literal()) -> string() +%% +%% @doc Returns the literal string represented by an abstract +%% character. This includes a leading <code>$</code> +%% character. Currently, all characters that are not in the set of ISO +%% 8859-1 (Latin-1) "printing" characters will be escaped. +%% +%% @see c_char/1 + +-spec char_lit(c_literal()) -> nonempty_string(). + +char_lit(Node) -> + io_lib:write_char(char_val(Node)). + + +%% --------------------------------------------------------------------- + +%% @spec c_string(Value::string()) -> c_literal() +%% +%% @doc Creates an abstract string literal. Equivalent to creating an +%% abstract list of the corresponding character literals +%% (cf. <code>is_c_string/1</code>), but is typically more +%% efficient. The lexical representation of a string is +%% "<code>"<em>Chars</em>"</code>", where <code>Chars</code> is a +%% sequence of printing characters or spaces. +%% +%% @see c_char/1 +%% @see ann_c_string/2 +%% @see is_c_string/1 +%% @see string_val/1 +%% @see string_lit/1 +%% @see is_print_string/1 + +-spec c_string(string()) -> c_literal(). + +c_string(Value) -> + #c_literal{val = Value}. + + +%% @spec ann_c_string(As::anns(), Value::string()) -> c_literal() +%% @see c_string/1 + +-spec ann_c_string(anns(), string()) -> c_literal(). + +ann_c_string(As, Value) -> + #c_literal{val = Value, anno = As}. + + +%% @spec is_c_string(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> may represent a +%% string literal, otherwise <code>false</code>. Strings are defined +%% as lists of characters; see <code>is_c_char/1</code> for details. +%% +%% @see c_string/1 +%% @see is_c_char/1 +%% @see is_print_string/1 + +-spec is_c_string(cerl()) -> boolean(). + +is_c_string(#c_literal{val = V}) -> + is_char_list(V); +is_c_string(_) -> + false. + + +%% @spec is_print_string(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> may represent a +%% string literal containing only "printing" characters, otherwise +%% <code>false</code>. See <code>is_c_string/1</code> and +%% <code>is_print_char/1</code> for details. Currently, only ISO +%% 8859-1 (Latin-1) character values are recognized. +%% +%% @see c_string/1 +%% @see is_c_string/1 +%% @see is_print_char/1 + +-spec is_print_string(cerl()) -> boolean(). + +is_print_string(#c_literal{val = V}) -> + is_print_char_list(V); +is_print_string(_) -> + false. + + +%% @spec string_val(cerl()) -> string() +%% +%% @doc Returns the value represented by an abstract string literal. +%% +%% @see c_string/1 + +-spec string_val(c_literal()) -> string(). + +string_val(Node) -> + Node#c_literal.val. + + +%% @spec string_lit(cerl()) -> string() +%% +%% @doc Returns the literal string represented by an abstract string. +%% This includes surrounding double-quote characters +%% <code>"..."</code>. Currently, characters that are not in the set +%% of ISO 8859-1 (Latin-1) "printing" characters will be escaped, +%% except for spaces. +%% +%% @see c_string/1 + +-spec string_lit(c_literal()) -> nonempty_string(). + +string_lit(Node) -> + io_lib:write_string(string_val(Node)). + + +%% --------------------------------------------------------------------- + +%% @spec c_nil() -> cerl() +%% +%% @doc Creates an abstract empty list. The result represents +%% "<code>[]</code>". The empty list is traditionally called "nil". +%% +%% @see ann_c_nil/1 +%% @see is_c_list/1 +%% @see c_cons/2 + +-spec c_nil() -> c_literal(). + +c_nil() -> + #c_literal{val = []}. + + +%% @spec ann_c_nil(As::anns()) -> cerl() +%% @see c_nil/0 + +-spec ann_c_nil(anns()) -> c_literal(). + +ann_c_nil(As) -> + #c_literal{val = [], anno = As}. + + +%% @spec is_c_nil(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% empty list, otherwise <code>false</code>. + +-spec is_c_nil(cerl()) -> boolean(). + +is_c_nil(#c_literal{val = []}) -> + true; +is_c_nil(_) -> + false. + + +%% --------------------------------------------------------------------- + +%% @spec c_cons(Head::cerl(), Tail::cerl()) -> cerl() +%% +%% @doc Creates an abstract list constructor. The result represents +%% "<code>[<em>Head</em> | <em>Tail</em>]</code>". Note that if both +%% <code>Head</code> and <code>Tail</code> have type +%% <code>literal</code>, then the result will also have type +%% <code>literal</code>, and annotations on <code>Head</code> and +%% <code>Tail</code> are lost. +%% +%% <p>Recall that in Erlang, the tail element of a list constructor is +%% not necessarily a list.</p> +%% +%% @see ann_c_cons/3 +%% @see update_c_cons/3 +%% @see c_cons_skel/2 +%% @see is_c_cons/1 +%% @see cons_hd/1 +%% @see cons_tl/1 +%% @see is_c_list/1 +%% @see c_nil/0 +%% @see list_elements/1 +%% @see list_length/1 +%% @see make_list/2 + +%% *Always* collapse literals. + +-spec c_cons(cerl(), cerl()) -> c_literal() | c_cons(). + +c_cons(#c_literal{val = Head}, #c_literal{val = Tail}) -> + #c_literal{val = [Head | Tail]}; +c_cons(Head, Tail) -> + #c_cons{hd = Head, tl = Tail}. + + +%% @spec ann_c_cons(As::anns(), Head::cerl(), Tail::cerl()) -> cerl() +%% @see c_cons/2 + +-spec ann_c_cons(anns(), cerl(), cerl()) -> c_literal() | c_cons(). + +ann_c_cons(As, #c_literal{val = Head}, #c_literal{val = Tail}) -> + #c_literal{val = [Head | Tail], anno = As}; +ann_c_cons(As, Head, Tail) -> + #c_cons{hd = Head, tl = Tail, anno = As}. + + +%% @spec update_c_cons(Old::cerl(), Head::cerl(), Tail::cerl()) -> +%% cerl() +%% @see c_cons/2 + +-spec update_c_cons(c_literal() | c_cons(), cerl(), cerl()) -> + c_literal() | c_cons(). + +update_c_cons(Node, #c_literal{val = Head}, #c_literal{val = Tail}) -> + #c_literal{val = [Head | Tail], anno = get_ann(Node)}; +update_c_cons(Node, Head, Tail) -> + #c_cons{hd = Head, tl = Tail, anno = get_ann(Node)}. + + +%% @spec c_cons_skel(Head::cerl(), Tail::cerl()) -> c_cons() +%% +%% @doc Creates an abstract list constructor skeleton. Does not fold +%% constant literals, i.e., the result always has type +%% <code>cons</code>, representing "<code>[<em>Head</em> | +%% <em>Tail</em>]</code>". +%% +%% <p>This function is occasionally useful when it is necessary to have +%% annotations on the subnodes of a list constructor node, even when the +%% subnodes are constant literals. Note however that +%% <code>is_literal/1</code> will yield <code>false</code> and +%% <code>concrete/1</code> will fail if passed the result from this +%% function.</p> +%% +%% <p><code>fold_literal/1</code> can be used to revert a node to the +%% normal-form representation.</p> +%% +%% @see ann_c_cons_skel/3 +%% @see update_c_cons_skel/3 +%% @see c_cons/2 +%% @see is_c_cons/1 +%% @see is_c_list/1 +%% @see c_nil/0 +%% @see is_literal/1 +%% @see fold_literal/1 +%% @see concrete/1 + +%% *Never* collapse literals. + +-spec c_cons_skel(cerl(), cerl()) -> c_cons(). + +c_cons_skel(Head, Tail) -> + #c_cons{hd = Head, tl = Tail}. + + +%% @spec ann_c_cons_skel(As::anns(), Head::cerl(), Tail::cerl()) -> +%% c_cons() +%% @see c_cons_skel/2 + +-spec ann_c_cons_skel(anns(), cerl(), cerl()) -> c_cons(). + +ann_c_cons_skel(As, Head, Tail) -> + #c_cons{hd = Head, tl = Tail, anno = As}. + + +%% @spec update_c_cons_skel(Old::cerl(), Head::cerl(), Tail::cerl()) -> +%% c_cons() +%% @see c_cons_skel/2 + +-spec update_c_cons_skel(c_cons() | c_literal(), cerl(), cerl()) -> c_cons(). + +update_c_cons_skel(Node, Head, Tail) -> + #c_cons{hd = Head, tl = Tail, anno = get_ann(Node)}. + + +%% @spec is_c_cons(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% list constructor, otherwise <code>false</code>. + +-spec is_c_cons(cerl()) -> boolean(). + +is_c_cons(#c_cons{}) -> + true; +is_c_cons(#c_literal{val = [_ | _]}) -> + true; +is_c_cons(_) -> + false. + + +%% @spec cons_hd(cerl()) -> cerl() +%% +%% @doc Returns the head subtree of an abstract list constructor. +%% +%% @see c_cons/2 + +-spec cons_hd(c_cons() | c_literal()) -> cerl(). + +cons_hd(#c_cons{hd = Head}) -> + Head; +cons_hd(#c_literal{val = [Head | _]}) -> + #c_literal{val = Head}. + + +%% @spec cons_tl(c_cons() | c_literal()) -> cerl() +%% +%% @doc Returns the tail subtree of an abstract list constructor. +%% +%% <p>Recall that the tail does not necessarily represent a proper +%% list.</p> +%% +%% @see c_cons/2 + +-spec cons_tl(c_cons() | c_literal()) -> cerl(). + +cons_tl(#c_cons{tl = Tail}) -> + Tail; +cons_tl(#c_literal{val = [_ | Tail]}) -> + #c_literal{val = Tail}. + + +%% @spec is_c_list(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> represents a +%% proper list, otherwise <code>false</code>. A proper list is either +%% the empty list <code>[]</code>, or a cons cell <code>[<em>Head</em> | +%% <em>Tail</em>]</code>, where recursively <code>Tail</code> is a +%% proper list. +%% +%% <p>Note: Because <code>Node</code> 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> +%% +%% @see c_cons/2 +%% @see c_nil/0 +%% @see list_elements/1 +%% @see list_length/1 + +-spec is_c_list(cerl()) -> boolean(). + +is_c_list(#c_cons{tl = Tail}) -> + is_c_list(Tail); +is_c_list(#c_literal{val = V}) -> + is_proper_list(V); +is_c_list(_) -> + false. + +is_proper_list([_ | Tail]) -> + is_proper_list(Tail); +is_proper_list([]) -> + true; +is_proper_list(_) -> + false. + +%% @spec list_elements(c_cons() | c_literal()) -> [cerl()] +%% +%% @doc Returns the list of element subtrees of an abstract list. +%% <code>Node</code> must represent a proper list. E.g., if +%% <code>Node</code> 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>. +%% +%% @see c_cons/2 +%% @see c_nil/0 +%% @see is_c_list/1 +%% @see list_length/1 +%% @see make_list/2 + +-spec list_elements(c_cons() | c_literal()) -> [cerl()]. + +list_elements(#c_cons{hd = Head, tl = Tail}) -> + [Head | list_elements(Tail)]; +list_elements(#c_literal{val = V}) -> + abstract_list(V). + +abstract_list([X | Xs]) -> + [abstract(X) | abstract_list(Xs)]; +abstract_list([]) -> + []. + + +%% @spec list_length(Node::c_cons() | c_literal()) -> integer() +%% +%% @doc Returns the number of element subtrees of an abstract list. +%% <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 +%% integer 6. +%% +%% <p>Note: this is equivalent to +%% <code>length(list_elements(Node))</code>, but potentially more +%% efficient.</p> +%% +%% @see c_cons/2 +%% @see c_nil/0 +%% @see is_c_list/1 +%% @see list_elements/1 + +-spec list_length(c_cons() | c_literal()) -> non_neg_integer(). + +list_length(L) -> + list_length(L, 0). + +list_length(#c_cons{tl = Tail}, A) -> + list_length(Tail, A + 1); +list_length(#c_literal{val = V}, A) -> + A + length(V). + + +%% @spec make_list(List) -> Node +%% @equiv make_list(List, none) + +-spec make_list([cerl()]) -> cerl(). + +make_list(List) -> + ann_make_list([], List). + + +%% @spec make_list(List::[cerl()], Tail) -> cerl() +%% +%% Tail = cerl() | none +%% +%% @doc Creates an abstract list from the elements in <code>List</code> +%% and the optional <code>Tail</code>. If <code>Tail</code> is +%% <code>none</code>, the result will represent a nil-terminated list, +%% otherwise it represents "<code>[... | <em>Tail</em>]</code>". +%% +%% @see c_cons/2 +%% @see c_nil/0 +%% @see ann_make_list/3 +%% @see update_list/3 +%% @see list_elements/1 + +-spec make_list([cerl()], cerl() | 'none') -> cerl(). + +make_list(List, Tail) -> + ann_make_list([], List, Tail). + + +%% @spec update_list(Old::cerl(), List::[cerl()]) -> cerl() +%% @equiv update_list(Old, List, none) + +-spec update_list(cerl(), [cerl()]) -> cerl(). + +update_list(Node, List) -> + ann_make_list(get_ann(Node), List). + + +%% @spec update_list(Old::cerl(), List::[cerl()], Tail) -> cerl() +%% +%% Tail = cerl() | none +%% +%% @see make_list/2 +%% @see update_list/2 + +-spec update_list(cerl(), [cerl()], cerl() | 'none') -> cerl(). + +update_list(Node, List, Tail) -> + ann_make_list(get_ann(Node), List, Tail). + + +%% @spec ann_make_list(As::anns(), List::[cerl()]) -> cerl() +%% @equiv ann_make_list(As, List, none) + +-spec ann_make_list(anns(), [cerl()]) -> cerl(). + +ann_make_list(As, List) -> + ann_make_list(As, List, none). + + +%% @spec ann_make_list(As::anns(), List::[cerl()], Tail) -> cerl() +%% +%% Tail = cerl() | none +%% +%% @see make_list/2 +%% @see ann_make_list/2 + +-spec ann_make_list(anns(), [cerl()], cerl() | 'none') -> cerl(). + +ann_make_list(As, [H | T], Tail) -> + ann_c_cons(As, H, make_list(T, Tail)); % `c_cons' folds literals +ann_make_list(As, [], none) -> + ann_c_nil(As); +ann_make_list(_, [], Node) -> + Node. + + +%% --------------------------------------------------------------------- +%% maps + +%% @spec is_c_map(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% map constructor, otherwise <code>false</code>. + +-spec is_c_map(cerl()) -> boolean(). + +is_c_map(#c_map{}) -> + true; +is_c_map(#c_literal{val = V}) when is_map(V) -> + true; +is_c_map(_) -> + false. + +-spec map_es(c_map() | c_literal()) -> [c_map_pair()]. + +map_es(#c_literal{anno=As,val=M}) when is_map(M) -> + [ann_c_map_pair(As, + #c_literal{anno=As,val='assoc'}, + #c_literal{anno=As,val=K}, + #c_literal{anno=As,val=V}) || {K,V} <- maps:to_list(M)]; +map_es(#c_map{es = Es}) -> + Es. + +-spec map_arg(c_map() | c_literal()) -> c_map() | c_literal(). + +map_arg(#c_literal{anno=As,val=M}) when is_map(M) -> + #c_literal{anno=As,val=#{}}; +map_arg(#c_map{arg=M}) -> + M. + +-spec c_map([c_map_pair()]) -> c_map(). + +c_map(Pairs) -> + ann_c_map([], Pairs). + +-spec c_map_pattern([c_map_pair()]) -> c_map(). + +c_map_pattern(Pairs) -> + #c_map{es=Pairs, is_pat=true}. + +-spec ann_c_map_pattern([term()], [c_map_pair()]) -> c_map(). + +ann_c_map_pattern(As, Pairs) -> + #c_map{anno=As, es=Pairs, is_pat=true}. + +-spec is_c_map_empty(c_map() | c_literal()) -> boolean(). + +is_c_map_empty(#c_map{ es=[] }) -> true; +is_c_map_empty(#c_literal{val=M}) when is_map(M),map_size(M) =:= 0 -> true; +is_c_map_empty(_) -> false. + +-spec is_c_map_pattern(c_map()) -> boolean(). + +is_c_map_pattern(#c_map{is_pat=IsPat}) -> + IsPat. + +-spec ann_c_map([term()], [c_map_pair()]) -> c_map() | c_literal(). + +ann_c_map(As, Es) -> + ann_c_map(As, #c_literal{val=#{}}, Es). + +-spec ann_c_map(anns(), c_map() | c_literal(), [c_map_pair()]) -> c_map() | c_literal(). + +ann_c_map(As, #c_literal{val=M}, Es) when is_map(M) -> + fold_map_pairs(As,Es,M); +ann_c_map(As, M, Es) -> + #c_map{arg=M, es=Es, anno=As}. + +fold_map_pairs(As,[],M) -> #c_literal{anno=As,val=M}; +%% M#{ K => V} +fold_map_pairs(As,[#c_map_pair{op=#c_literal{val=assoc},key=Ck,val=Cv}=E|Es],M) -> + case is_lit_list([Ck,Cv]) of + true -> + [K,V] = lit_list_vals([Ck,Cv]), + fold_map_pairs(As,Es,maps:put(K,V,M)); + false -> + #c_map{arg=#c_literal{val=M,anno=As}, es=[E|Es], anno=As} + end; +%% M#{ K := V} +fold_map_pairs(As,[#c_map_pair{op=#c_literal{val=exact},key=Ck,val=Cv}=E|Es],M) -> + case is_lit_list([Ck,Cv]) of + true -> + [K,V] = lit_list_vals([Ck,Cv]), + case maps:is_key(K,M) of + true -> fold_map_pairs(As,Es,maps:put(K,V,M)); + false -> + #c_map{arg=#c_literal{val=M,anno=As}, es=[E|Es], anno=As } + end; + false -> + #c_map{arg=#c_literal{val=M,anno=As}, es=[E|Es], anno=As } + end. + +-spec update_c_map(c_map(), cerl(), [cerl()]) -> c_map() | c_literal(). + +update_c_map(#c_map{is_pat=true}=Old, M, Es) -> + Old#c_map{arg=M, es=Es}; +update_c_map(#c_map{is_pat=false}=Old, M, Es) -> + ann_c_map(get_ann(Old), M, Es). + +map_pair_key(#c_map_pair{key=K}) -> K. +map_pair_val(#c_map_pair{val=V}) -> V. +map_pair_op(#c_map_pair{op=Op}) -> Op. + +-spec c_map_pair(cerl(), cerl()) -> c_map_pair(). + +c_map_pair(Key,Val) -> + #c_map_pair{op=#c_literal{val=assoc},key=Key,val=Val}. + +-spec c_map_pair_exact(cerl(), cerl()) -> c_map_pair(). + +c_map_pair_exact(Key,Val) -> + #c_map_pair{op=#c_literal{val=exact},key=Key,val=Val}. + +-spec ann_c_map_pair(anns(), cerl(), cerl(), cerl()) -> + c_map_pair(). + +ann_c_map_pair(As,Op,K,V) -> + #c_map_pair{op = Op, key = K, val = V, anno = As}. + +update_c_map_pair(Old,Op,K,V) -> + #c_map_pair{op = Op, key = K, val = V, anno = get_ann(Old)}. + + +%% --------------------------------------------------------------------- + +%% @spec c_tuple(Elements::[cerl()]) -> cerl() +%% +%% @doc Creates an abstract tuple. If <code>Elements</code> is +%% <code>[E1, ..., En]</code>, the result represents +%% "<code>{<em>E1</em>, ..., <em>En</em>}</code>". Note that if all +%% nodes in <code>Elements</code> have type <code>literal</code>, or if +%% <code>Elements</code> is empty, then the result will also have type +%% <code>literal</code> and annotations on nodes in +%% <code>Elements</code> are lost. +%% +%% <p>Recall that Erlang has distinct 1-tuples, i.e., <code>{X}</code> +%% is always distinct from <code>X</code> itself.</p> +%% +%% @see ann_c_tuple/2 +%% @see update_c_tuple/2 +%% @see is_c_tuple/1 +%% @see tuple_es/1 +%% @see tuple_arity/1 +%% @see c_tuple_skel/1 + +%% *Always* collapse literals. + +-spec c_tuple([cerl()]) -> c_tuple() | c_literal(). + +c_tuple(Es) -> + case is_lit_list(Es) of + false -> + #c_tuple{es = Es}; + true -> + #c_literal{val = list_to_tuple(lit_list_vals(Es))} + end. + + +%% @spec ann_c_tuple(As::anns(), Elements::[cerl()]) -> cerl() +%% @see c_tuple/1 + +-spec ann_c_tuple(anns(), [cerl()]) -> c_tuple() | c_literal(). + +ann_c_tuple(As, Es) -> + case is_lit_list(Es) of + false -> + #c_tuple{es = Es, anno = As}; + true -> + #c_literal{val = list_to_tuple(lit_list_vals(Es)), anno = As} + end. + + +%% @spec update_c_tuple(Old::cerl(), Elements::[cerl()]) -> cerl() +%% @see c_tuple/1 + +-spec update_c_tuple(c_tuple() | c_literal(), [cerl()]) -> c_tuple() | c_literal(). + +update_c_tuple(Node, Es) -> + case is_lit_list(Es) of + false -> + #c_tuple{es = Es, anno = get_ann(Node)}; + true -> + #c_literal{val = list_to_tuple(lit_list_vals(Es)), + anno = get_ann(Node)} + end. + + +%% @spec c_tuple_skel(Elements::[cerl()]) -> cerl() +%% +%% @doc Creates an abstract tuple skeleton. Does not fold constant +%% literals, i.e., the result always has type <code>tuple</code>, +%% representing "<code>{<em>E1</em>, ..., <em>En</em>}</code>", if +%% <code>Elements</code> is <code>[E1, ..., En]</code>. +%% +%% <p>This function is occasionally useful when it is necessary to have +%% annotations on the subnodes of a tuple node, even when all the +%% subnodes are constant literals. Note however that +%% <code>is_literal/1</code> will yield <code>false</code> and +%% <code>concrete/1</code> will fail if passed the result from this +%% function.</p> +%% +%% <p><code>fold_literal/1</code> can be used to revert a node to the +%% normal-form representation.</p> +%% +%% @see ann_c_tuple_skel/2 +%% @see update_c_tuple_skel/2 +%% @see c_tuple/1 +%% @see tuple_es/1 +%% @see is_c_tuple/1 +%% @see is_literal/1 +%% @see fold_literal/1 +%% @see concrete/1 + +%% *Never* collapse literals. + +-spec c_tuple_skel([cerl()]) -> c_tuple(). + +c_tuple_skel(Es) -> + #c_tuple{es = Es}. + + +%% @spec ann_c_tuple_skel(As::anns(), Elements::[cerl()]) -> cerl() +%% @see c_tuple_skel/1 + +-spec ann_c_tuple_skel(anns(), [cerl()]) -> c_tuple(). + +ann_c_tuple_skel(As, Es) -> + #c_tuple{es = Es, anno = As}. + + +%% @spec update_c_tuple_skel(Old::cerl(), Elements::[cerl()]) -> cerl() +%% @see c_tuple_skel/1 + +-spec update_c_tuple_skel(c_tuple(), [cerl()]) -> c_tuple(). + +update_c_tuple_skel(Old, Es) -> + #c_tuple{es = Es, anno = get_ann(Old)}. + + +%% @spec is_c_tuple(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% tuple, otherwise <code>false</code>. +%% +%% @see c_tuple/1 + +-spec is_c_tuple(cerl()) -> boolean(). + +is_c_tuple(#c_tuple{}) -> + true; +is_c_tuple(#c_literal{val = V}) when is_tuple(V) -> + true; +is_c_tuple(_) -> + false. + + +%% @spec tuple_es(cerl()) -> [cerl()] +%% +%% @doc Returns the list of element subtrees of an abstract tuple. +%% +%% @see c_tuple/1 + +-spec tuple_es(c_tuple() | c_literal()) -> [cerl()]. + +tuple_es(#c_tuple{es = Es}) -> + Es; +tuple_es(#c_literal{val = V}) -> + make_lit_list(tuple_to_list(V)). + + +%% @spec tuple_arity(Node::cerl()) -> integer() +%% +%% @doc Returns the number of element subtrees of an abstract tuple. +%% +%% <p>Note: this is equivalent to <code>length(tuple_es(Node))</code>, +%% but potentially more efficient.</p> +%% +%% @see tuple_es/1 +%% @see c_tuple/1 + +-spec tuple_arity(c_tuple() | c_literal()) -> non_neg_integer(). + +tuple_arity(#c_tuple{es = Es}) -> + length(Es); +tuple_arity(#c_literal{val = V}) when is_tuple(V) -> + tuple_size(V). + + +%% --------------------------------------------------------------------- + +%% @spec c_var(Name::var_name()) -> cerl() +%% +%% var_name() = integer() | atom() | {atom(), arity()} +%% +%% @doc Creates an abstract variable. A variable is identified by its +%% name, given by the <code>Name</code> parameter. +%% +%% <p>If a name is given by a single atom, it should either be a +%% "simple" atom which does not need to be single-quoted in Erlang, or +%% otherwise its print name should correspond to a proper Erlang +%% variable, i.e., begin with an uppercase character or an +%% underscore. Names on the form <code>{A, N}</code> represent +%% function name variables "<code><em>A</em>/<em>N</em></code>"; these +%% are special variables which may be bound only in the function +%% definitions of a module or a <code>letrec</code>. They may not be +%% bound in <code>let</code> expressions and cannot occur in clause +%% patterns. The atom <code>A</code> in a function name may be any +%% atom; the integer <code>N</code> must be nonnegative. The functions +%% <code>c_fname/2</code> etc. are utilities for handling function +%% name variables.</p> +%% +%% <p>When printing variable names, they must have the form of proper +%% Core Erlang variables and function names. E.g., a name represented +%% by an integer such as <code>42</code> could be formatted as +%% "<code>_42</code>", an atom <code>'Xxx'</code> simply as +%% "<code>Xxx</code>", and an atom <code>foo</code> as +%% "<code>_foo</code>". However, one must assure that any two valid +%% distinct names are never mapped to the same strings. Tuples such +%% as <code>{foo, 2}</code> representing function names can simply by +%% formatted as "<code>'foo'/2</code>", with no risk of conflicts.</p> +%% +%% @see ann_c_var/2 +%% @see update_c_var/2 +%% @see is_c_var/1 +%% @see var_name/1 +%% @see c_fname/2 +%% @see c_module/4 +%% @see c_letrec/2 + +-spec c_var(var_name()) -> c_var(). + +c_var(Name) -> + #c_var{name = Name}. + + +%% @spec ann_c_var(As::anns(), Name::var_name()) -> c_var() +%% +%% @see c_var/1 + +-spec ann_c_var(anns(), var_name()) -> c_var(). + +ann_c_var(As, Name) -> + #c_var{name = Name, anno = As}. + +%% @spec update_c_var(Old::cerl(), Name::var_name()) -> c_var() +%% +%% @see c_var/1 + +-spec update_c_var(c_var(), var_name()) -> c_var(). + +update_c_var(Node, Name) -> + #c_var{name = Name, anno = get_ann(Node)}. + + +%% @spec is_c_var(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% variable, otherwise <code>false</code>. +%% +%% @see c_var/1 + +-spec is_c_var(cerl()) -> boolean(). + +is_c_var(#c_var{}) -> + true; +is_c_var(_) -> + false. + + +%% @spec c_fname(Name::atom(), Arity::arity()) -> c_var() +%% @equiv c_var({Name, Arity}) +%% @see fname_id/1 +%% @see fname_arity/1 +%% @see is_c_fname/1 +%% @see ann_c_fname/3 +%% @see update_c_fname/3 + +-spec c_fname(atom(), arity()) -> c_var(). + +c_fname(Atom, Arity) -> + c_var({Atom, Arity}). + + +%% @spec ann_c_fname(As::anns(), Name::atom(), Arity::arity()) -> c_var() +%% +%% @equiv ann_c_var(As, {Atom, Arity}) +%% @see c_fname/2 + +-spec ann_c_fname(anns(), atom(), arity()) -> c_var(). + +ann_c_fname(As, Atom, Arity) -> + ann_c_var(As, {Atom, Arity}). + + +%% @spec update_c_fname(Old::c_var(), Name::atom()) -> c_var() +%% @doc Like <code>update_c_fname/3</code>, but takes the arity from +%% <code>Node</code>. +%% @see update_c_fname/3 +%% @see c_fname/2 + +-spec update_c_fname(c_var(), atom()) -> c_var(). + +update_c_fname(#c_var{name = {_, Arity}, anno = As}, Atom) -> + #c_var{name = {Atom, Arity}, anno = As}. + + +%% @spec update_c_fname(Old::var(), Name::atom(), Arity::arity()) -> c_var() +%% +%% @equiv update_c_var(Old, {Atom, Arity}) +%% @see update_c_fname/2 +%% @see c_fname/2 + +-spec update_c_fname(c_var(), atom(), arity()) -> c_var(). + +update_c_fname(Node, Atom, Arity) -> + update_c_var(Node, {Atom, Arity}). + + +%% @spec is_c_fname(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% function name variable, otherwise <code>false</code>. +%% +%% @see c_fname/2 +%% @see c_var/1 +%% @see var_name/1 + +-spec is_c_fname(cerl()) -> boolean(). + +is_c_fname(#c_var{name = {A, N}}) when is_atom(A), is_integer(N), N >= 0 -> + true; +is_c_fname(_) -> + false. + + +%% @spec var_name(c_var()) -> var_name() +%% +%% @doc Returns the name of an abstract variable. +%% +%% @see c_var/1 + +-spec var_name(c_var()) -> var_name(). + +var_name(Node) -> + Node#c_var.name. + + +%% @spec fname_id(c_var()) -> atom() +%% +%% @doc Returns the identifier part of an abstract function name +%% variable. +%% +%% @see fname_arity/1 +%% @see c_fname/2 + +-spec fname_id(c_var()) -> atom(). + +fname_id(#c_var{name={A,_}}) -> + A. + + +%% @spec fname_arity(c_var()) -> arity() +%% +%% @doc Returns the arity part of an abstract function name variable. +%% +%% @see fname_id/1 +%% @see c_fname/2 + +-spec fname_arity(c_var()) -> arity(). + +fname_arity(#c_var{name={_,N}}) -> + N. + + +%% --------------------------------------------------------------------- + +%% @spec c_values(Elements::[cerl()]) -> c_values() +%% +%% @doc Creates an abstract value list. If <code>Elements</code> is +%% <code>[E1, ..., En]</code>, the result represents +%% "<code><<em>E1</em>, ..., <em>En</em>></code>". +%% +%% @see ann_c_values/2 +%% @see update_c_values/2 +%% @see is_c_values/1 +%% @see values_es/1 +%% @see values_arity/1 + +-spec c_values([cerl()]) -> c_values(). + +c_values(Es) -> + #c_values{es = Es}. + + +%% @spec ann_c_values(As::anns(), Elements::[cerl()]) -> c_values() +%% @see c_values/1 + +-spec ann_c_values(anns(), [cerl()]) -> c_values(). + +ann_c_values(As, Es) -> + #c_values{es = Es, anno = As}. + + +%% @spec update_c_values(Old::cerl(), Elements::[cerl()]) -> c_values() +%% @see c_values/1 + +-spec update_c_values(c_values(), [cerl()]) -> c_values(). + +update_c_values(Node, Es) -> + #c_values{es = Es, anno = get_ann(Node)}. + + +%% @spec is_c_values(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% value list; otherwise <code>false</code>. +%% +%% @see c_values/1 + +-spec is_c_values(cerl()) -> boolean(). + +is_c_values(#c_values{}) -> + true; +is_c_values(_) -> + false. + + +%% @spec values_es(c_values()) -> [cerl()] +%% +%% @doc Returns the list of element subtrees of an abstract value +%% list. +%% +%% @see c_values/1 +%% @see values_arity/1 + +-spec values_es(c_values()) -> [cerl()]. + +values_es(Node) -> + Node#c_values.es. + + +%% @spec values_arity(Node::c_values()) -> non_neg_integer() +%% +%% @doc Returns the number of element subtrees of an abstract value +%% list. +%% +%% <p>Note: This is equivalent to +%% <code>length(values_es(Node))</code>, but potentially more +%% efficient.</p> +%% +%% @see c_values/1 +%% @see values_es/1 + +-spec values_arity(c_values()) -> non_neg_integer(). + +values_arity(Node) -> + length(values_es(Node)). + + +%% --------------------------------------------------------------------- + +%% @spec c_binary(Segments::[c_bitstr()]) -> c_binary() +%% +%% @doc Creates an abstract binary-template. A binary object is a +%% sequence of 8-bit bytes. It is specified by zero or more bit-string +%% template <em>segments</em> of arbitrary lengths (in number of bits), +%% such that the sum of the lengths is evenly divisible by 8. If +%% <code>Segments</code> is <code>[S1, ..., Sn]</code>, the result +%% represents "<code>#{<em>S1</em>, ..., <em>Sn</em>}#</code>". All the +%% <code>Si</code> must have type <code>bitstr</code>. +%% +%% @see ann_c_binary/2 +%% @see update_c_binary/2 +%% @see is_c_binary/1 +%% @see binary_segments/1 +%% @see c_bitstr/5 + +-spec c_binary([c_bitstr()]) -> c_binary(). + +c_binary(Segments) -> + #c_binary{segments = Segments}. + + +%% @spec ann_c_binary(As::anns(), Segments::[c_bitstr()]) -> c_binary() +%% @see c_binary/1 + +-spec ann_c_binary(anns(), [c_bitstr()]) -> c_binary(). + +ann_c_binary(As, Segments) -> + #c_binary{segments = Segments, anno = As}. + + +%% @spec update_c_binary(Old::cerl(), Segments::[c_bitstr()]) -> cerl() +%% @see c_binary/1 + +-spec update_c_binary(c_binary(), [c_bitstr()]) -> c_binary(). + +update_c_binary(Node, Segments) -> + #c_binary{segments = Segments, anno = get_ann(Node)}. + + +%% @spec is_c_binary(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% binary-template; otherwise <code>false</code>. +%% +%% @see c_binary/1 + +-spec is_c_binary(cerl()) -> boolean(). + +is_c_binary(#c_binary{}) -> + true; +is_c_binary(_) -> + false. + + +%% @spec binary_segments(cerl()) -> [c_bitstr()] +%% +%% @doc Returns the list of segment subtrees of an abstract +%% binary-template. +%% +%% @see c_binary/1 +%% @see c_bitstr/5 + +-spec binary_segments(c_binary()) -> [c_bitstr()]. + +binary_segments(Node) -> + Node#c_binary.segments. + + +%% @spec c_bitstr(Value::cerl(), Size::cerl(), Unit::cerl(), +%% Type::cerl(), Flags::cerl()) -> c_bitstr() +%% +%% @doc Creates an abstract bit-string template. These can only occur as +%% components of an abstract binary-template (see {@link c_binary/1}). +%% The result represents "<code>#<<em>Value</em>>(<em>Size</em>, +%% <em>Unit</em>, <em>Type</em>, <em>Flags</em>)</code>", where +%% <code>Unit</code> must represent a positive integer constant, +%% <code>Type</code> must represent a constant atom (one of +%% <code>'integer'</code>, <code>'float'</code>, or +%% <code>'binary'</code>), and <code>Flags</code> must represent a +%% constant list <code>"[<em>F1</em>, ..., <em>Fn</em>]"</code> where +%% all the <code>Fi</code> are atoms. +%% +%% @see c_binary/1 +%% @see ann_c_bitstr/6 +%% @see update_c_bitstr/6 +%% @see is_c_bitstr/1 +%% @see bitstr_val/1 +%% @see bitstr_size/1 +%% @see bitstr_unit/1 +%% @see bitstr_type/1 +%% @see bitstr_flags/1 + +-spec c_bitstr(cerl(), cerl(), cerl(), cerl(), cerl()) -> c_bitstr(). + +c_bitstr(Val, Size, Unit, Type, Flags) -> + #c_bitstr{val = Val, size = Size, unit = Unit, type = Type, + flags = Flags}. + + +%% @spec c_bitstr(Value::cerl(), Size::cerl(), Type::cerl(), +%% Flags::cerl()) -> c_bitstr() +%% @equiv c_bitstr(Value, Size, abstract(1), Type, Flags) + +-spec c_bitstr(cerl(), cerl(), cerl(), cerl()) -> c_bitstr(). + +c_bitstr(Val, Size, Type, Flags) -> + c_bitstr(Val, Size, abstract(1), Type, Flags). + + +%% @spec c_bitstr(Value::cerl(), Type::cerl(), +%% Flags::cerl()) -> c_bitstr() +%% @equiv c_bitstr(Value, abstract(all), abstract(1), Type, Flags) + +-spec c_bitstr(cerl(), cerl(), cerl()) -> c_bitstr(). + +c_bitstr(Val, Type, Flags) -> + c_bitstr(Val, abstract(all), abstract(1), Type, Flags). + + +%% @spec ann_c_bitstr(As::anns(), Value::cerl(), Size::cerl(), +%% Unit::cerl(), Type::cerl(), Flags::cerl()) -> cerl() +%% @see c_bitstr/5 +%% @see ann_c_bitstr/5 + +-spec ann_c_bitstr(anns(), cerl(), cerl(), cerl(), cerl(), cerl()) -> + c_bitstr(). + +ann_c_bitstr(As, Val, Size, Unit, Type, Flags) -> + #c_bitstr{val = Val, size = Size, unit = Unit, type = Type, + flags = Flags, anno = As}. + +%% @spec ann_c_bitstr(As::anns(), Value::cerl(), Size::cerl(), +%% Type::cerl(), Flags::cerl()) -> c_bitstr() +%% @equiv ann_c_bitstr(As, Value, Size, abstract(1), Type, Flags) + +-spec ann_c_bitstr(anns(), cerl(), cerl(), cerl(), cerl()) -> c_bitstr(). + +ann_c_bitstr(As, Value, Size, Type, Flags) -> + ann_c_bitstr(As, Value, Size, abstract(1), Type, Flags). + + +%% @spec update_c_bitstr(Old::c_bitstr(), Value::cerl(), Size::cerl(), +%% Unit::cerl(), Type::cerl(), Flags::cerl()) -> c_bitstr() +%% @see c_bitstr/5 +%% @see update_c_bitstr/5 + +-spec update_c_bitstr(c_bitstr(), cerl(), cerl(), cerl(), cerl(), cerl()) -> + c_bitstr(). + +update_c_bitstr(Node, Val, Size, Unit, Type, Flags) -> + #c_bitstr{val = Val, size = Size, unit = Unit, type = Type, + flags = Flags, anno = get_ann(Node)}. + + +%% @spec update_c_bitstr(Old::c_bitstr(), Value::cerl(), Size::cerl(), +%% Type::cerl(), Flags::cerl()) -> c_bitstr() +%% @equiv update_c_bitstr(Node, Value, Size, abstract(1), Type, Flags) + +-spec update_c_bitstr(c_bitstr(), cerl(), cerl(), cerl(), cerl()) -> c_bitstr(). + +update_c_bitstr(Node, Value, Size, Type, Flags) -> + update_c_bitstr(Node, Value, Size, abstract(1), Type, Flags). + +%% @spec is_c_bitstr(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% bit-string template; otherwise <code>false</code>. +%% +%% @see c_bitstr/5 + +-spec is_c_bitstr(cerl()) -> boolean(). + +is_c_bitstr(#c_bitstr{}) -> + true; +is_c_bitstr(_) -> + false. + + +%% @spec bitstr_val(c_bitstr()) -> cerl() +%% +%% @doc Returns the value subtree of an abstract bit-string template. +%% +%% @see c_bitstr/5 + +-spec bitstr_val(c_bitstr()) -> cerl(). + +bitstr_val(Node) -> + Node#c_bitstr.val. + + +%% @spec bitstr_size(c_bitstr()) -> cerl() +%% +%% @doc Returns the size subtree of an abstract bit-string template. +%% +%% @see c_bitstr/5 + +-spec bitstr_size(c_bitstr()) -> cerl(). + +bitstr_size(Node) -> + Node#c_bitstr.size. + + +%% @spec bitstr_bitsize(c_bitstr()) -> any | all | utf | integer() +%% +%% @doc Returns the total size in bits of an abstract bit-string +%% template. If the size field is an integer literal, the result is the +%% product of the size and unit values; if the size field is the atom +%% literal <code>all</code>, the atom <code>all</code> is returned. +%% If the size is not a literal, the atom <code>any</code> is returned. +%% +%% @see c_bitstr/5 + +-spec bitstr_bitsize(c_bitstr()) -> 'all' | 'any' | 'utf' | non_neg_integer(). + +bitstr_bitsize(Node) -> + Size = Node#c_bitstr.size, + case is_literal(Size) of + true -> + case concrete(Size) of + all -> + all; + undefined -> + %% just an assertion below + "utf" ++ _ = atom_to_list(concrete(Node#c_bitstr.type)), + utf; + S when is_integer(S) -> + S * concrete(Node#c_bitstr.unit) + end; + false -> + any + end. + + +%% @spec bitstr_unit(c_bitstr()) -> cerl() +%% +%% @doc Returns the unit subtree of an abstract bit-string template. +%% +%% @see c_bitstr/5 + +-spec bitstr_unit(c_bitstr()) -> cerl(). + +bitstr_unit(Node) -> + Node#c_bitstr.unit. + + +%% @spec bitstr_type(c_bitstr()) -> cerl() +%% +%% @doc Returns the type subtree of an abstract bit-string template. +%% +%% @see c_bitstr/5 + +-spec bitstr_type(c_bitstr()) -> cerl(). + +bitstr_type(Node) -> + Node#c_bitstr.type. + + +%% @spec bitstr_flags(c_bitstr()) -> cerl() +%% +%% @doc Returns the flags subtree of an abstract bit-string template. +%% +%% @see c_bitstr/5 + +-spec bitstr_flags(c_bitstr()) -> cerl(). + +bitstr_flags(Node) -> + Node#c_bitstr.flags. + + +%% --------------------------------------------------------------------- + +%% @spec c_fun(Variables::[c_var()], Body::cerl()) -> c_fun() +%% +%% @doc Creates an abstract fun-expression. If <code>Variables</code> +%% is <code>[V1, ..., Vn]</code>, the result represents "<code>fun +%% (<em>V1</em>, ..., <em>Vn</em>) -> <em>Body</em></code>". All the +%% <code>Vi</code> must have type <code>var</code>. +%% +%% @see ann_c_fun/3 +%% @see update_c_fun/3 +%% @see is_c_fun/1 +%% @see fun_vars/1 +%% @see fun_body/1 +%% @see fun_arity/1 + +-spec c_fun([c_var()], cerl()) -> c_fun(). + +c_fun(Variables, Body) -> + #c_fun{vars = Variables, body = Body}. + + +%% @spec ann_c_fun(As::anns(), Variables::[c_var()], Body::cerl()) -> +%% c_fun() +%% @see c_fun/2 + +-spec ann_c_fun(anns(), [c_var()], cerl()) -> c_fun(). + +ann_c_fun(As, Variables, Body) -> + #c_fun{vars = Variables, body = Body, anno = As}. + + +%% @spec update_c_fun(Old::c_fun(), Variables::[c_var()], +%% Body::cerl()) -> c_fun() +%% @see c_fun/2 + +-spec update_c_fun(c_fun(), [c_var()], cerl()) -> c_fun(). + +update_c_fun(Node, Variables, Body) -> + #c_fun{vars = Variables, body = Body, anno = get_ann(Node)}. + + +%% @spec is_c_fun(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% fun-expression, otherwise <code>false</code>. +%% +%% @see c_fun/2 + +-spec is_c_fun(cerl()) -> boolean(). + +is_c_fun(#c_fun{}) -> + true; % Now this is fun! +is_c_fun(_) -> + false. + + +%% @spec fun_vars(c_fun()) -> [c_var()] +%% +%% @doc Returns the list of parameter subtrees of an abstract +%% fun-expression. +%% +%% @see c_fun/2 +%% @see fun_arity/1 + +-spec fun_vars(c_fun()) -> [c_var()]. + +fun_vars(Node) -> + Node#c_fun.vars. + + +%% @spec fun_body(c_fun()) -> cerl() +%% +%% @doc Returns the body subtree of an abstract fun-expression. +%% +%% @see c_fun/2 + +-spec fun_body(c_fun()) -> cerl(). + +fun_body(Node) -> + Node#c_fun.body. + + +%% @spec fun_arity(Node::c_fun()) -> arity() +%% +%% @doc Returns the number of parameter subtrees of an abstract +%% fun-expression. +%% +%% <p>Note: this is equivalent to <code>length(fun_vars(Node))</code>, +%% but potentially more efficient.</p> +%% +%% @see c_fun/2 +%% @see fun_vars/1 + +-spec fun_arity(c_fun()) -> arity(). + +fun_arity(Node) -> + length(fun_vars(Node)). + + +%% --------------------------------------------------------------------- + +%% @spec c_seq(Argument::cerl(), Body::cerl()) -> c_seq() +%% +%% @doc Creates an abstract sequencing expression. The result +%% represents "<code>do <em>Argument</em> <em>Body</em></code>". +%% +%% @see ann_c_seq/3 +%% @see update_c_seq/3 +%% @see is_c_seq/1 +%% @see seq_arg/1 +%% @see seq_body/1 + +-spec c_seq(cerl(), cerl()) -> c_seq(). + +c_seq(Argument, Body) -> + #c_seq{arg = Argument, body = Body}. + + +%% @spec ann_c_seq(As::anns(), Argument::cerl(), Body::cerl()) -> c_seq() +%% +%% @see c_seq/2 + +-spec ann_c_seq(anns(), cerl(), cerl()) -> c_seq(). + +ann_c_seq(As, Argument, Body) -> + #c_seq{arg = Argument, body = Body, anno = As}. + + +%% @spec update_c_seq(Old::c_seq(), Argument::cerl(), Body::cerl()) -> +%% c_seq() +%% @see c_seq/2 + +-spec update_c_seq(c_seq(), cerl(), cerl()) -> c_seq(). + +update_c_seq(Node, Argument, Body) -> + #c_seq{arg = Argument, body = Body, anno = get_ann(Node)}. + + +%% @spec is_c_seq(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% sequencing expression, otherwise <code>false</code>. +%% +%% @see c_seq/2 + +-spec is_c_seq(cerl()) -> boolean(). + +is_c_seq(#c_seq{}) -> + true; +is_c_seq(_) -> + false. + + +%% @spec seq_arg(c_seq()) -> cerl() +%% +%% @doc Returns the argument subtree of an abstract sequencing +%% expression. +%% +%% @see c_seq/2 + +-spec seq_arg(c_seq()) -> cerl(). + +seq_arg(Node) -> + Node#c_seq.arg. + + +%% @spec seq_body(c_seq()) -> cerl() +%% +%% @doc Returns the body subtree of an abstract sequencing expression. +%% +%% @see c_seq/2 + +-spec seq_body(c_seq()) -> cerl(). + +seq_body(Node) -> + Node#c_seq.body. + + +%% --------------------------------------------------------------------- + +%% @spec c_let(Variables::[c_var()], Argument::cerl(), Body::cerl()) -> +%% c_let() +%% +%% @doc Creates an abstract let-expression. If <code>Variables</code> +%% is <code>[V1, ..., Vn]</code>, the result represents "<code>let +%% <<em>V1</em>, ..., <em>Vn</em>> = <em>Argument</em> in +%% <em>Body</em></code>". All the <code>Vi</code> must have type +%% <code>var</code>. +%% +%% @see ann_c_let/4 +%% @see update_c_let/4 +%% @see is_c_let/1 +%% @see let_vars/1 +%% @see let_arg/1 +%% @see let_body/1 +%% @see let_arity/1 + +-spec c_let([c_var()], cerl(), cerl()) -> c_let(). + +c_let(Variables, Argument, Body) -> + #c_let{vars = Variables, arg = Argument, body = Body}. + + +%% ann_c_let(As, Variables, Argument, Body) -> c_let() +%% @see c_let/3 + +-spec ann_c_let(anns(), [c_var()], cerl(), cerl()) -> c_let(). + +ann_c_let(As, Variables, Argument, Body) -> + #c_let{vars = Variables, arg = Argument, body = Body, anno = As}. + + +%% update_c_let(Old, Variables, Argument, Body) -> c_let() +%% @see c_let/3 + +-spec update_c_let(c_let(), [c_var()], cerl(), cerl()) -> c_let(). + +update_c_let(Node, Variables, Argument, Body) -> + #c_let{vars = Variables, arg = Argument, body = Body, + anno = get_ann(Node)}. + + +%% @spec is_c_let(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% let-expression, otherwise <code>false</code>. +%% +%% @see c_let/3 + +-spec is_c_let(cerl()) -> boolean(). + +is_c_let(#c_let{}) -> + true; +is_c_let(_) -> + false. + + +%% @spec let_vars(c_let()) -> [c_var()] +%% +%% @doc Returns the list of left-hand side variables of an abstract +%% let-expression. +%% +%% @see c_let/3 +%% @see let_arity/1 + +-spec let_vars(c_let()) -> [c_var()]. + +let_vars(Node) -> + Node#c_let.vars. + + +%% @spec let_arg(c_let()) -> cerl() +%% +%% @doc Returns the argument subtree of an abstract let-expression. +%% +%% @see c_let/3 + +-spec let_arg(c_let()) -> cerl(). + +let_arg(Node) -> + Node#c_let.arg. + + +%% @spec let_body(c_let()) -> cerl() +%% +%% @doc Returns the body subtree of an abstract let-expression. +%% +%% @see c_let/3 + +-spec let_body(c_let()) -> cerl(). + +let_body(Node) -> + Node#c_let.body. + + +%% @spec let_arity(Node::c_let()) -> non_neg_integer() +%% +%% @doc Returns the number of left-hand side variables of an abstract +%% let-expression. +%% +%% <p>Note: this is equivalent to <code>length(let_vars(Node))</code>, +%% but potentially more efficient.</p> +%% +%% @see c_let/3 +%% @see let_vars/1 + +-spec let_arity(c_let()) -> non_neg_integer(). + +let_arity(Node) -> + length(let_vars(Node)). + + +%% --------------------------------------------------------------------- + +%% @spec c_letrec(Definitions::defs(), Body::cerl()) -> c_letrec() +%% +%% @doc Creates an abstract letrec-expression. If +%% <code>Definitions</code> is <code>[{V1, F1}, ..., {Vn, Fn}]</code>, +%% the result represents "<code>letrec <em>V1</em> = <em>F1</em> +%% ... <em>Vn</em> = <em>Fn</em> in <em>Body</em></code>. All the +%% <code>Vi</code> must have type <code>var</code> and represent +%% function names. All the <code>Fi</code> must have type +%% <code>'fun'</code>. +%% +%% @see ann_c_letrec/3 +%% @see update_c_letrec/3 +%% @see is_c_letrec/1 +%% @see letrec_defs/1 +%% @see letrec_body/1 +%% @see letrec_vars/1 + +-spec c_letrec(defs(), cerl()) -> c_letrec(). + +c_letrec(Defs, Body) -> + #c_letrec{defs = Defs, body = Body}. + + +%% @spec ann_c_letrec(As::anns(), Definitions::defs(), +%% Body::cerl()) -> c_letrec() +%% @see c_letrec/2 + +-spec ann_c_letrec(anns(), defs(), cerl()) -> c_letrec(). + +ann_c_letrec(As, Defs, Body) -> + #c_letrec{defs = Defs, body = Body, anno = As}. + + +%% @spec update_c_letrec(Old::c_letrec(), Definitions::defs(), +%% Body::cerl()) -> c_letrec() +%% @see c_letrec/2 + +-spec update_c_letrec(c_letrec(), defs(), cerl()) -> c_letrec(). + +update_c_letrec(Node, Defs, Body) -> + #c_letrec{defs = Defs, body = Body, anno = get_ann(Node)}. + + +%% @spec is_c_letrec(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% letrec-expression, otherwise <code>false</code>. +%% +%% @see c_letrec/2 + +-spec is_c_letrec(cerl()) -> boolean(). + +is_c_letrec(#c_letrec{}) -> + true; +is_c_letrec(_) -> + false. + + +%% @spec letrec_defs(Node::c_letrec()) -> defs() +%% +%% @doc Returns the list of definitions of an abstract +%% letrec-expression. If <code>Node</code> represents "<code>letrec +%% <em>V1</em> = <em>F1</em> ... <em>Vn</em> = <em>Fn</em> in +%% <em>Body</em></code>", the returned value is <code>[{V1, F1}, ..., +%% {Vn, Fn}]</code>. +%% +%% @see c_letrec/2 + +-spec letrec_defs(c_letrec()) -> defs(). + +letrec_defs(Node) -> + Node#c_letrec.defs. + + +%% @spec letrec_body(c_letrec()) -> cerl() +%% +%% @doc Returns the body subtree of an abstract letrec-expression. +%% +%% @see c_letrec/2 + +-spec letrec_body(c_letrec()) -> cerl(). + +letrec_body(Node) -> + Node#c_letrec.body. + + +%% @spec letrec_vars(c_letrec()) -> [cerl()] +%% +%% @doc Returns the list of left-hand side function variable subtrees +%% of a letrec-expression. If <code>Node</code> represents +%% "<code>letrec <em>V1</em> = <em>F1</em> ... <em>Vn</em> = +%% <em>Fn</em> in <em>Body</em></code>", the returned value is +%% <code>[V1, ..., Vn]</code>. +%% +%% @see c_letrec/2 + +-spec letrec_vars(c_letrec()) -> [cerl()]. + +letrec_vars(Node) -> + [F || {F, _} <- letrec_defs(Node)]. + + +%% --------------------------------------------------------------------- + +%% @spec c_case(Argument::cerl(), Clauses::[cerl()]) -> c_case() +%% +%% @doc Creates an abstract case-expression. If <code>Clauses</code> +%% is <code>[C1, ..., Cn]</code>, the result represents "<code>case +%% <em>Argument</em> of <em>C1</em> ... <em>Cn</em> +%% end</code>". <code>Clauses</code> must not be empty. +%% +%% @see ann_c_case/3 +%% @see update_c_case/3 +%% @see is_c_case/1 +%% @see c_clause/3 +%% @see case_arg/1 +%% @see case_clauses/1 +%% @see case_arity/1 + +-spec c_case(cerl(), [cerl()]) -> c_case(). + +c_case(Expr, Clauses) -> + #c_case{arg = Expr, clauses = Clauses}. + + +%% @spec ann_c_case(As::anns(), Argument::cerl(), +%% Clauses::[cerl()]) -> c_case() +%% @see c_case/2 + +-spec ann_c_case(anns(), cerl(), [cerl()]) -> c_case(). + +ann_c_case(As, Expr, Clauses) -> + #c_case{arg = Expr, clauses = Clauses, anno = As}. + + +%% @spec update_c_case(Old::cerl(), Argument::cerl(), +%% Clauses::[cerl()]) -> c_case() +%% @see c_case/2 + +-spec update_c_case(c_case(), cerl(), [cerl()]) -> c_case(). + +update_c_case(Node, Expr, Clauses) -> + #c_case{arg = Expr, clauses = Clauses, anno = get_ann(Node)}. + + +%% is_c_case(Node) -> boolean() +%% +%% Node = cerl() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% case-expression; otherwise <code>false</code>. +%% +%% @see c_case/2 + +-spec is_c_case(cerl()) -> boolean(). + +is_c_case(#c_case{}) -> + true; +is_c_case(_) -> + false. + + +%% @spec case_arg(c_case()) -> cerl() +%% +%% @doc Returns the argument subtree of an abstract case-expression. +%% +%% @see c_case/2 + +-spec case_arg(c_case()) -> cerl(). + +case_arg(Node) -> + Node#c_case.arg. + + +%% @spec case_clauses(c_case()) -> [cerl()] +%% +%% @doc Returns the list of clause subtrees of an abstract +%% case-expression. +%% +%% @see c_case/2 +%% @see case_arity/1 + +-spec case_clauses(c_case()) -> [cerl()]. + +case_clauses(Node) -> + Node#c_case.clauses. + + +%% @spec case_arity(Node::c_case()) -> non_neg_integer() +%% +%% @doc Equivalent to +%% <code>clause_arity(hd(case_clauses(Node)))</code>, but potentially +%% more efficient. +%% +%% @see c_case/2 +%% @see case_clauses/1 +%% @see clause_arity/1 + +-spec case_arity(c_case()) -> non_neg_integer(). + +case_arity(Node) -> + clause_arity(hd(case_clauses(Node))). + + +%% --------------------------------------------------------------------- + +%% @spec c_clause(Patterns::[cerl()], Body::cerl()) -> c_clause() +%% @equiv c_clause(Patterns, c_atom(true), Body) +%% @see c_atom/1 + +-spec c_clause([cerl()], cerl()) -> c_clause(). + +c_clause(Patterns, Body) -> + c_clause(Patterns, c_atom(true), Body). + + +%% @spec c_clause(Patterns::[cerl()], Guard::cerl(), Body::cerl()) -> +%% c_clause() +%% +%% @doc Creates an an abstract clause. If <code>Patterns</code> is +%% <code>[P1, ..., Pn]</code>, the result represents +%% "<code><<em>P1</em>, ..., <em>Pn</em>> when <em>Guard</em> -> +%% <em>Body</em></code>". +%% +%% @see c_clause/2 +%% @see ann_c_clause/4 +%% @see update_c_clause/4 +%% @see is_c_clause/1 +%% @see c_case/2 +%% @see c_receive/3 +%% @see clause_pats/1 +%% @see clause_guard/1 +%% @see clause_body/1 +%% @see clause_arity/1 +%% @see clause_vars/1 + +-spec c_clause([cerl()], cerl(), cerl()) -> c_clause(). + +c_clause(Patterns, Guard, Body) -> + #c_clause{pats = Patterns, guard = Guard, body = Body}. + + +%% @spec ann_c_clause(As::anns(), Patterns::[cerl()], +%% Body::cerl()) -> c_clause() +%% @equiv ann_c_clause(As, Patterns, c_atom(true), Body) +%% @see c_clause/3 + +-spec ann_c_clause(anns(), [cerl()], cerl()) -> c_clause(). + +ann_c_clause(As, Patterns, Body) -> + ann_c_clause(As, Patterns, c_atom(true), Body). + + +%% @spec ann_c_clause(As::anns(), Patterns::[cerl()], Guard::cerl(), +%% Body::cerl()) -> c_clause() +%% @see ann_c_clause/3 +%% @see c_clause/3 + +-spec ann_c_clause(anns(), [cerl()], cerl(), cerl()) -> c_clause(). + +ann_c_clause(As, Patterns, Guard, Body) -> + #c_clause{pats = Patterns, guard = Guard, body = Body, anno = As}. + + +%% @spec update_c_clause(Old::c_clause(), Patterns::[cerl()], +%% Guard::cerl(), Body::cerl()) -> c_clause() +%% @see c_clause/3 + +-spec update_c_clause(c_clause(), [cerl()], cerl(), cerl()) -> c_clause(). + +update_c_clause(Node, Patterns, Guard, Body) -> + #c_clause{pats = Patterns, guard = Guard, body = Body, + anno = get_ann(Node)}. + + +%% @spec is_c_clause(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% clause, otherwise <code>false</code>. +%% +%% @see c_clause/3 + +-spec is_c_clause(cerl()) -> boolean(). + +is_c_clause(#c_clause{}) -> + true; +is_c_clause(_) -> + false. + + +%% @spec clause_pats(c_clause()) -> [cerl()] +%% +%% @doc Returns the list of pattern subtrees of an abstract clause. +%% +%% @see c_clause/3 +%% @see clause_arity/1 + +-spec clause_pats(c_clause()) -> [cerl()]. + +clause_pats(Node) -> + Node#c_clause.pats. + + +%% @spec clause_guard(c_clause()) -> cerl() +%% +%% @doc Returns the guard subtree of an abstract clause. +%% +%% @see c_clause/3 + +-spec clause_guard(c_clause()) -> cerl(). + +clause_guard(Node) -> + Node#c_clause.guard. + + +%% @spec clause_body(c_clause()) -> cerl() +%% +%% @doc Returns the body subtree of an abstract clause. +%% +%% @see c_clause/3 + +-spec clause_body(c_clause()) -> cerl(). + +clause_body(Node) -> + Node#c_clause.body. + + +%% @spec clause_arity(Node::c_clause()) -> non_neg_integer() +%% +%% @doc Returns the number of pattern subtrees of an abstract clause. +%% +%% <p>Note: this is equivalent to +%% <code>length(clause_pats(Node))</code>, but potentially more +%% efficient.</p> +%% +%% @see c_clause/3 +%% @see clause_pats/1 + +-spec clause_arity(c_clause()) -> non_neg_integer(). + +clause_arity(Node) -> + length(clause_pats(Node)). + + +%% @spec clause_vars(c_clause()) -> [cerl()] +%% +%% @doc Returns the list of all abstract variables in the patterns of +%% an abstract clause. The order of listing is not defined. +%% +%% @see c_clause/3 +%% @see pat_list_vars/1 + +-spec clause_vars(c_clause()) -> [cerl()]. + +clause_vars(Clause) -> + pat_list_vars(clause_pats(Clause)). + + +%% @spec pat_vars(Pattern::cerl()) -> [cerl()] +%% +%% @doc Returns the list of all abstract variables in a pattern. An +%% exception is thrown if <code>Node</code> does not represent a +%% well-formed Core Erlang clause pattern. The order of listing is not +%% defined. +%% +%% @see pat_list_vars/1 +%% @see clause_vars/1 + +-spec pat_vars(cerl()) -> [cerl()]. + +pat_vars(Node) -> + pat_vars(Node, []). + +pat_vars(Node, Vs) -> + case type(Node) of + var -> + [Node | Vs]; + literal -> + Vs; + cons -> + pat_vars(cons_hd(Node), pat_vars(cons_tl(Node), Vs)); + tuple -> + pat_list_vars(tuple_es(Node), Vs); + map -> + pat_list_vars(map_es(Node), Vs); + map_pair -> + %% map_pair_key is not a pattern var, excluded + pat_list_vars([map_pair_op(Node),map_pair_val(Node)],Vs); + binary -> + pat_list_vars(binary_segments(Node), Vs); + bitstr -> + %% bitstr_size is not a pattern var, excluded + pat_vars(bitstr_val(Node), Vs); + alias -> + pat_vars(alias_pat(Node), [alias_var(Node) | Vs]) + end. + + +%% @spec pat_list_vars(Patterns::[cerl()]) -> [cerl()] +%% +%% @doc Returns the list of all abstract variables in the given +%% patterns. An exception is thrown if some element in +%% <code>Patterns</code> does not represent a well-formed Core Erlang +%% clause pattern. The order of listing is not defined. +%% +%% @see pat_vars/1 +%% @see clause_vars/1 + +-spec pat_list_vars([cerl()]) -> [cerl()]. + +pat_list_vars(Ps) -> + pat_list_vars(Ps, []). + +pat_list_vars([P | Ps], Vs) -> + pat_list_vars(Ps, pat_vars(P, Vs)); +pat_list_vars([], Vs) -> + Vs. + + +%% --------------------------------------------------------------------- + +%% @spec c_alias(Variable::c_var(), Pattern::cerl()) -> c_alias() +%% +%% @doc Creates an abstract pattern alias. The result represents +%% "<code><em>Variable</em> = <em>Pattern</em></code>". +%% +%% @see ann_c_alias/3 +%% @see update_c_alias/3 +%% @see is_c_alias/1 +%% @see alias_var/1 +%% @see alias_pat/1 +%% @see c_clause/3 + +-spec c_alias(c_var(), cerl()) -> c_alias(). + +c_alias(Var, Pattern) -> + #c_alias{var = Var, pat = Pattern}. + + +%% @spec ann_c_alias(As::anns(), Variable::c_var(), +%% Pattern::cerl()) -> c_alias() +%% @see c_alias/2 + +-spec ann_c_alias(anns(), c_var(), cerl()) -> c_alias(). + +ann_c_alias(As, Var, Pattern) -> + #c_alias{var = Var, pat = Pattern, anno = As}. + + +%% @spec update_c_alias(Old::cerl(), Variable::c_var(), +%% Pattern::cerl()) -> c_alias() +%% @see c_alias/2 + +-spec update_c_alias(c_alias(), c_var(), cerl()) -> c_alias(). + +update_c_alias(Node, Var, Pattern) -> + #c_alias{var = Var, pat = Pattern, anno = get_ann(Node)}. + + +%% @spec is_c_alias(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% pattern alias, otherwise <code>false</code>. +%% +%% @see c_alias/2 + +-spec is_c_alias(cerl()) -> boolean(). + +is_c_alias(#c_alias{}) -> + true; +is_c_alias(_) -> + false. + + +%% @spec alias_var(c_alias()) -> c_var() +%% +%% @doc Returns the variable subtree of an abstract pattern alias. +%% +%% @see c_alias/2 + +-spec alias_var(c_alias()) -> c_var(). + +alias_var(Node) -> + Node#c_alias.var. + + +%% @spec alias_pat(c_alias()) -> cerl() +%% +%% @doc Returns the pattern subtree of an abstract pattern alias. +%% +%% @see c_alias/2 + +-spec alias_pat(c_alias()) -> cerl(). + +alias_pat(Node) -> + Node#c_alias.pat. + + +%% --------------------------------------------------------------------- + +%% @spec c_receive(Clauses::[cerl()]) -> c_receive() +%% @equiv c_receive(Clauses, c_atom(infinity), c_atom(true)) +%% @see c_atom/1 + +-spec c_receive([cerl()]) -> c_receive(). + +c_receive(Clauses) -> + c_receive(Clauses, c_atom(infinity), c_atom(true)). + + +%% @spec c_receive(Clauses::[cerl()], Timeout::cerl(), +%% Action::cerl()) -> c_receive() +%% +%% @doc Creates an abstract receive-expression. If +%% <code>Clauses</code> is <code>[C1, ..., Cn]</code>, the result +%% represents "<code>receive <em>C1</em> ... <em>Cn</em> after +%% <em>Timeout</em> -> <em>Action</em> end</code>". +%% +%% @see c_receive/1 +%% @see ann_c_receive/4 +%% @see update_c_receive/4 +%% @see is_c_receive/1 +%% @see receive_clauses/1 +%% @see receive_timeout/1 +%% @see receive_action/1 + +-spec c_receive([cerl()], cerl(), cerl()) -> c_receive(). + +c_receive(Clauses, Timeout, Action) -> + #c_receive{clauses = Clauses, timeout = Timeout, action = Action}. + + +%% @spec ann_c_receive(As::anns(), Clauses::[cerl()]) -> c_receive() +%% @equiv ann_c_receive(As, Clauses, c_atom(infinity), c_atom(true)) +%% @see c_receive/3 +%% @see c_atom/1 + +-spec ann_c_receive(anns(), [cerl()]) -> c_receive(). + +ann_c_receive(As, Clauses) -> + ann_c_receive(As, Clauses, c_atom(infinity), c_atom(true)). + + +%% @spec ann_c_receive(As::anns(), Clauses::[cerl()], +%% Timeout::cerl(), Action::cerl()) -> c_receive() +%% @see ann_c_receive/2 +%% @see c_receive/3 + +-spec ann_c_receive(anns(), [cerl()], cerl(), cerl()) -> c_receive(). + +ann_c_receive(As, Clauses, Timeout, Action) -> + #c_receive{clauses = Clauses, timeout = Timeout, action = Action, + anno = As}. + + +%% @spec update_c_receive(Old::cerl(), Clauses::[cerl()], +%% Timeout::cerl(), Action::cerl()) -> c_receive() +%% @see c_receive/3 + +-spec update_c_receive(c_receive(), [cerl()], cerl(), cerl()) -> c_receive(). + +update_c_receive(Node, Clauses, Timeout, Action) -> + #c_receive{clauses = Clauses, timeout = Timeout, action = Action, + anno = get_ann(Node)}. + + +%% @spec is_c_receive(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% receive-expression, otherwise <code>false</code>. +%% +%% @see c_receive/3 + +-spec is_c_receive(cerl()) -> boolean(). + +is_c_receive(#c_receive{}) -> + true; +is_c_receive(_) -> + false. + + +%% @spec receive_clauses(c_receive()) -> [cerl()] +%% +%% @doc Returns the list of clause subtrees of an abstract +%% receive-expression. +%% +%% @see c_receive/3 + +-spec receive_clauses(c_receive()) -> [cerl()]. + +receive_clauses(Node) -> + Node#c_receive.clauses. + + +%% @spec receive_timeout(c_receive()) -> cerl() +%% +%% @doc Returns the timeout subtree of an abstract receive-expression. +%% +%% @see c_receive/3 + +-spec receive_timeout(c_receive()) -> cerl(). + +receive_timeout(Node) -> + Node#c_receive.timeout. + + +%% @spec receive_action(c_receive()) -> cerl() +%% +%% @doc Returns the action subtree of an abstract receive-expression. +%% +%% @see c_receive/3 + +-spec receive_action(c_receive()) -> cerl(). + +receive_action(Node) -> + Node#c_receive.action. + + +%% --------------------------------------------------------------------- + +%% @spec c_apply(Operator::c_var(), Arguments::[cerl()]) -> c_apply() +%% +%% @doc Creates an abstract function application. If +%% <code>Arguments</code> is <code>[A1, ..., An]</code>, the result +%% represents "<code>apply <em>Operator</em>(<em>A1</em>, ..., +%% <em>An</em>)</code>". +%% +%% @see ann_c_apply/3 +%% @see update_c_apply/3 +%% @see is_c_apply/1 +%% @see apply_op/1 +%% @see apply_args/1 +%% @see apply_arity/1 +%% @see c_call/3 +%% @see c_primop/2 + +-spec c_apply(c_var(), [cerl()]) -> c_apply(). + +c_apply(Operator, Arguments) -> + #c_apply{op = Operator, args = Arguments}. + + +%% @spec ann_c_apply(As::anns(), Operator::c_var(), +%% Arguments::[cerl()]) -> c_apply() +%% @see c_apply/2 + +-spec ann_c_apply(anns(), c_var(), [cerl()]) -> c_apply(). + +ann_c_apply(As, Operator, Arguments) -> + #c_apply{op = Operator, args = Arguments, anno = As}. + + +%% @spec update_c_apply(Old::c_apply(), Operator::cerl(), +%% Arguments::[cerl()]) -> c_apply() +%% @see c_apply/2 + +-spec update_c_apply(c_apply(), c_var(), [cerl()]) -> c_apply(). + +update_c_apply(Node, Operator, Arguments) -> + #c_apply{op = Operator, args = Arguments, anno = get_ann(Node)}. + + +%% @spec is_c_apply(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% function application, otherwise <code>false</code>. +%% +%% @see c_apply/2 + +-spec is_c_apply(cerl()) -> boolean(). + +is_c_apply(#c_apply{}) -> + true; +is_c_apply(_) -> + false. + + +%% @spec apply_op(c_apply()) -> c_var() +%% +%% @doc Returns the operator subtree of an abstract function +%% application. +%% +%% @see c_apply/2 + +-spec apply_op(c_apply()) -> c_var(). + +apply_op(Node) -> + Node#c_apply.op. + + +%% @spec apply_args(c_apply()) -> [cerl()] +%% +%% @doc Returns the list of argument subtrees of an abstract function +%% application. +%% +%% @see c_apply/2 +%% @see apply_arity/1 + +-spec apply_args(c_apply()) -> [cerl()]. + +apply_args(Node) -> + Node#c_apply.args. + + +%% @spec apply_arity(Node::c_apply()) -> arity() +%% +%% @doc Returns the number of argument subtrees of an abstract +%% function application. +%% +%% <p>Note: this is equivalent to +%% <code>length(apply_args(Node))</code>, but potentially more +%% efficient.</p> +%% +%% @see c_apply/2 +%% @see apply_args/1 + +-spec apply_arity(c_apply()) -> arity(). + +apply_arity(Node) -> + length(apply_args(Node)). + + +%% --------------------------------------------------------------------- + +%% @spec c_call(Module::cerl(), Name::cerl(), Arguments::[cerl()]) -> +%% c_call() +%% +%% @doc Creates an abstract inter-module call. If +%% <code>Arguments</code> is <code>[A1, ..., An]</code>, the result +%% represents "<code>call <em>Module</em>:<em>Name</em>(<em>A1</em>, +%% ..., <em>An</em>)</code>". +%% +%% @see ann_c_call/4 +%% @see update_c_call/4 +%% @see is_c_call/1 +%% @see call_module/1 +%% @see call_name/1 +%% @see call_args/1 +%% @see call_arity/1 +%% @see c_apply/2 +%% @see c_primop/2 + +-spec c_call(cerl(), cerl(), [cerl()]) -> c_call(). + +c_call(Module, Name, Arguments) -> + #c_call{module = Module, name = Name, args = Arguments}. + + +%% @spec ann_c_call(As::anns(), Module::cerl(), Name::cerl(), +%% Arguments::[cerl()]) -> c_call() +%% @see c_call/3 + +-spec ann_c_call(anns(), cerl(), cerl(), [cerl()]) -> c_call(). + +ann_c_call(As, Module, Name, Arguments) -> + #c_call{module = Module, name = Name, args = Arguments, anno = As}. + + +%% @spec update_c_call(Old::cerl(), Module::cerl(), Name::cerl(), +%% Arguments::[cerl()]) -> c_call() +%% @see c_call/3 + +-spec update_c_call(cerl(), cerl(), cerl(), [cerl()]) -> c_call(). + +update_c_call(Node, Module, Name, Arguments) -> + #c_call{module = Module, name = Name, args = Arguments, + anno = get_ann(Node)}. + + +%% @spec is_c_call(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% inter-module call expression; otherwise <code>false</code>. +%% +%% @see c_call/3 + +-spec is_c_call(cerl()) -> boolean(). + +is_c_call(#c_call{}) -> + true; +is_c_call(_) -> + false. + + +%% @spec call_module(c_call()) -> cerl() +%% +%% @doc Returns the module subtree of an abstract inter-module call. +%% +%% @see c_call/3 + +-spec call_module(c_call()) -> cerl(). + +call_module(Node) -> + Node#c_call.module. + + +%% @spec call_name(c_call()) -> cerl() +%% +%% @doc Returns the name subtree of an abstract inter-module call. +%% +%% @see c_call/3 + +-spec call_name(c_call()) -> cerl(). + +call_name(Node) -> + Node#c_call.name. + + +%% @spec call_args(c_call()) -> [cerl()] +%% +%% @doc Returns the list of argument subtrees of an abstract +%% inter-module call. +%% +%% @see c_call/3 +%% @see call_arity/1 + +-spec call_args(c_call()) -> [cerl()]. + +call_args(Node) -> + Node#c_call.args. + + +%% @spec call_arity(Node::c_call()) -> arity() +%% +%% @doc Returns the number of argument subtrees of an abstract +%% inter-module call. +%% +%% <p>Note: this is equivalent to +%% <code>length(call_args(Node))</code>, but potentially more +%% efficient.</p> +%% +%% @see c_call/3 +%% @see call_args/1 + +-spec call_arity(c_call()) -> arity(). + +call_arity(Node) -> + length(call_args(Node)). + + +%% --------------------------------------------------------------------- + +%% @spec c_primop(Name::c_literal(), Arguments::[cerl()]) -> c_primop() +%% +%% @doc Creates an abstract primitive operation call. If +%% <code>Arguments</code> is <code>[A1, ..., An]</code>, the result +%% represents "<code>primop <em>Name</em>(<em>A1</em>, ..., +%% <em>An</em>)</code>". <code>Name</code> must be an atom literal. +%% +%% @see ann_c_primop/3 +%% @see update_c_primop/3 +%% @see is_c_primop/1 +%% @see primop_name/1 +%% @see primop_args/1 +%% @see primop_arity/1 +%% @see c_apply/2 +%% @see c_call/3 + +-spec c_primop(c_literal(), [cerl()]) -> c_primop(). + +c_primop(Name, Arguments) -> + #c_primop{name = Name, args = Arguments}. + + +%% @spec ann_c_primop(As::anns(), Name::c_literal(), +%% Arguments::[cerl()]) -> c_primop() +%% @see c_primop/2 + +-spec ann_c_primop(anns(), c_literal(), [cerl()]) -> c_primop(). + +ann_c_primop(As, Name, Arguments) -> + #c_primop{name = Name, args = Arguments, anno = As}. + + +%% @spec update_c_primop(Old::cerl(), Name::c_literal(), +%% Arguments::[cerl()]) -> c_primop() +%% @see c_primop/2 + +-spec update_c_primop(cerl(), c_literal(), [cerl()]) -> c_primop(). + +update_c_primop(Node, Name, Arguments) -> + #c_primop{name = Name, args = Arguments, anno = get_ann(Node)}. + + +%% @spec is_c_primop(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% primitive operation call, otherwise <code>false</code>. +%% +%% @see c_primop/2 + +-spec is_c_primop(cerl()) -> boolean(). + +is_c_primop(#c_primop{}) -> + true; +is_c_primop(_) -> + false. + + +%% @spec primop_name(c_primop()) -> c_literal() +%% +%% @doc Returns the name subtree of an abstract primitive operation +%% call. +%% +%% @see c_primop/2 + +-spec primop_name(c_primop()) -> c_literal(). + +primop_name(Node) -> + Node#c_primop.name. + + +%% @spec primop_args(c_primop()) -> [cerl()] +%% +%% @doc Returns the list of argument subtrees of an abstract primitive +%% operation call. +%% +%% @see c_primop/2 +%% @see primop_arity/1 + +-spec primop_args(c_primop()) -> [cerl()]. + +primop_args(Node) -> + Node#c_primop.args. + + +%% @spec primop_arity(Node::c_primop()) -> arity() +%% +%% @doc Returns the number of argument subtrees of an abstract +%% primitive operation call. +%% +%% <p>Note: this is equivalent to +%% <code>length(primop_args(Node))</code>, but potentially more +%% efficient.</p> +%% +%% @see c_primop/2 +%% @see primop_args/1 + +-spec primop_arity(c_primop()) -> arity(). + +primop_arity(Node) -> + length(primop_args(Node)). + + +%% --------------------------------------------------------------------- + +%% @spec c_try(Argument::cerl(), Variables::[c_var()], Body::cerl(), +%% ExceptionVars::[c_var()], Handler::cerl()) -> c_try() +%% +%% @doc Creates an abstract try-expression. If <code>Variables</code> is +%% <code>[V1, ..., Vn]</code> and <code>ExceptionVars</code> is +%% <code>[X1, ..., Xm]</code>, the result represents "<code>try +%% <em>Argument</em> of <<em>V1</em>, ..., <em>Vn</em>> -> +%% <em>Body</em> catch <<em>X1</em>, ..., <em>Xm</em>> -> +%% <em>Handler</em></code>". All the <code>Vi</code> and <code>Xi</code> +%% must have type <code>var</code>. +%% +%% @see ann_c_try/6 +%% @see update_c_try/6 +%% @see is_c_try/1 +%% @see try_arg/1 +%% @see try_vars/1 +%% @see try_body/1 +%% @see c_catch/1 + +-spec c_try(cerl(), [c_var()], cerl(), [c_var()], cerl()) -> c_try(). + +c_try(Expr, Vs, Body, Evs, Handler) -> + #c_try{arg = Expr, vars = Vs, body = Body, + evars = Evs, handler = Handler}. + + +%% @spec ann_c_try(As::[term()], Expression::cerl(), +%% Variables::[c_var()], Body::cerl(), +%% EVars::[c_var()], Handler::cerl()) -> c_try() +%% @see c_try/5 + +-spec ann_c_try(anns(), cerl(), [c_var()], cerl(), [c_var()], cerl()) -> + c_try(). + +ann_c_try(As, Expr, Vs, Body, Evs, Handler) -> + #c_try{arg = Expr, vars = Vs, body = Body, + evars = Evs, handler = Handler, anno = As}. + + +%% @spec update_c_try(Old::c_try(), Expression::cerl(), +%% Variables::[c_var()], Body::cerl(), +%% EVars::[c_var()], Handler::cerl()) -> cerl() +%% @see c_try/5 + +-spec update_c_try(c_try(), cerl(), [c_var()], cerl(), [c_var()], cerl()) -> + c_try(). + +update_c_try(Node, Expr, Vs, Body, Evs, Handler) -> + #c_try{arg = Expr, vars = Vs, body = Body, + evars = Evs, handler = Handler, anno = get_ann(Node)}. + + +%% @spec is_c_try(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% try-expression, otherwise <code>false</code>. +%% +%% @see c_try/5 + +-spec is_c_try(cerl()) -> boolean(). + +is_c_try(#c_try{}) -> + true; +is_c_try(_) -> + false. + + +%% @spec try_arg(c_try()) -> cerl() +%% +%% @doc Returns the expression subtree of an abstract try-expression. +%% +%% @see c_try/5 + +-spec try_arg(c_try()) -> cerl(). + +try_arg(Node) -> + Node#c_try.arg. + + +%% @spec try_vars(c_try()) -> [c_var()] +%% +%% @doc Returns the list of success variable subtrees of an abstract +%% try-expression. +%% +%% @see c_try/5 + +-spec try_vars(c_try()) -> [c_var()]. + +try_vars(Node) -> + Node#c_try.vars. + + +%% @spec try_body(c_try()) -> cerl() +%% +%% @doc Returns the success body subtree of an abstract try-expression. +%% +%% @see c_try/5 + +-spec try_body(c_try()) -> cerl(). + +try_body(Node) -> + Node#c_try.body. + + +%% @spec try_evars(c_try()) -> [c_var()] +%% +%% @doc Returns the list of exception variable subtrees of an abstract +%% try-expression. +%% +%% @see c_try/5 + +-spec try_evars(c_try()) -> [c_var()]. + +try_evars(Node) -> + Node#c_try.evars. + + +%% @spec try_handler(c_try()) -> cerl() +%% +%% @doc Returns the exception body subtree of an abstract +%% try-expression. +%% +%% @see c_try/5 + +-spec try_handler(c_try()) -> cerl(). + +try_handler(Node) -> + Node#c_try.handler. + + +%% --------------------------------------------------------------------- + +%% @spec c_catch(Body::cerl()) -> c_catch() +%% +%% @doc Creates an abstract catch-expression. The result represents +%% "<code>catch <em>Body</em></code>". +%% +%% <p>Note: catch-expressions can be rewritten as try-expressions, and +%% will eventually be removed from Core Erlang.</p> +%% +%% @see ann_c_catch/2 +%% @see update_c_catch/2 +%% @see is_c_catch/1 +%% @see catch_body/1 +%% @see c_try/5 + +-spec c_catch(cerl()) -> c_catch(). + +c_catch(Body) -> + #c_catch{body = Body}. + + +%% @spec ann_c_catch(As::anns(), Body::cerl()) -> c_catch() +%% @see c_catch/1 + +-spec ann_c_catch(anns(), cerl()) -> c_catch(). + +ann_c_catch(As, Body) -> + #c_catch{body = Body, anno = As}. + + +%% @spec update_c_catch(Old::c_catch(), Body::cerl()) -> c_catch() +%% @see c_catch/1 + +-spec update_c_catch(c_catch(), cerl()) -> c_catch(). + +update_c_catch(Node, Body) -> + #c_catch{body = Body, anno = get_ann(Node)}. + + +%% @spec is_c_catch(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> is an abstract +%% catch-expression, otherwise <code>false</code>. +%% +%% @see c_catch/1 + +-spec is_c_catch(cerl()) -> boolean(). + +is_c_catch(#c_catch{}) -> + true; +is_c_catch(_) -> + false. + + +%% @spec catch_body(Node::c_catch()) -> cerl() +%% +%% @doc Returns the body subtree of an abstract catch-expression. +%% +%% @see c_catch/1 + +-spec catch_body(c_catch()) -> cerl(). + +catch_body(Node) -> + Node#c_catch.body. + + +%% --------------------------------------------------------------------- + +%% @spec to_records(Tree::cerl()) -> record(record_types()) +%% +%% @doc Translates an abstract syntax tree to a corresponding explicit +%% record representation. The records are defined in the file +%% "<code>cerl.hrl</code>". +%% +%% @see type/1 +%% @see from_records/1 + +-spec to_records(cerl()) -> cerl(). + +to_records(Node) -> + Node. + +%% @spec from_records(Tree::record(record_types())) -> cerl() +%% +%% record_types() = c_alias | c_apply | c_binary | c_bitstr | c_call | +%% c_case | c_catch | c_clause | c_cons | c_fun | +%% c_let | c_letrec | c_literal | c_map | c_map_pair | +%% c_module | c_primop | c_receive | c_seq | +%% c_try | c_tuple | c_values | c_var +%% +%% @doc Translates an explicit record representation to a +%% corresponding abstract syntax tree. The records are defined in the +%% file "<code>core_parse.hrl</code>". +%% +%% @see type/1 +%% @see to_records/1 + +-spec from_records(cerl()) -> cerl(). + +from_records(Node) -> + Node. + + +%% --------------------------------------------------------------------- + +%% @spec is_data(Node::cerl()) -> boolean() +%% +%% @doc Returns <code>true</code> if <code>Node</code> represents a +%% data constructor, otherwise <code>false</code>. Data constructors +%% are cons cells, tuples, and atomic literals. +%% +%% @see data_type/1 +%% @see data_es/1 +%% @see data_arity/1 + +-spec is_data(cerl()) -> boolean(). + +is_data(#c_literal{}) -> + true; +is_data(#c_cons{}) -> + true; +is_data(#c_tuple{}) -> + true; +is_data(_) -> + false. + + +%% @spec data_type(Node::cerl()) -> dtype() +%% +%% dtype() = cons | tuple | {atomic, Value} +%% Value = integer() | float() | atom() | [] +%% +%% @doc Returns a type descriptor for a data constructor +%% node. (Cf. <code>is_data/1</code>.) This is mainly useful for +%% comparing types and for constructing new nodes of the same type +%% (cf. <code>make_data/2</code>). If <code>Node</code> represents an +%% integer, floating-point number, atom or empty list, the result is +%% <code>{atomic, Value}</code>, where <code>Value</code> is the value +%% of <code>concrete(Node)</code>, otherwise the result is either +%% <code>cons</code> or <code>tuple</code>. +%% +%% <p>Type descriptors can be compared for equality or order (in the +%% Erlang term order), but remember that floating-point values should +%% in general never be tested for equality.</p> +%% +%% @see is_data/1 +%% @see make_data/2 +%% @see type/1 +%% @see concrete/1 + +-type value() :: integer() | float() | atom() | []. +-type dtype() :: 'cons' | 'tuple' | {'atomic', value()}. +-type c_lct() :: c_literal() | c_cons() | c_tuple(). + +-spec data_type(c_lct()) -> dtype(). + +data_type(#c_literal{val = V}) -> + case V of + [_ | _] -> + cons; + _ when is_tuple(V) -> + tuple; + _ -> + {atomic, V} + end; +data_type(#c_cons{}) -> + cons; +data_type(#c_tuple{}) -> + tuple. + +%% @spec data_es(Node::cerl()) -> [cerl()] +%% +%% @doc Returns the list of subtrees of a data constructor node. If +%% the arity of the constructor is zero, the result is the empty list. +%% +%% <p>Note: if <code>data_type(Node)</code> is <code>cons</code>, the +%% number of subtrees is exactly two. If <code>data_type(Node)</code> +%% is <code>{atomic, Value}</code>, the number of subtrees is +%% zero.</p> +%% +%% @see is_data/1 +%% @see data_type/1 +%% @see data_arity/1 +%% @see make_data/2 + +-spec data_es(c_lct()) -> [cerl()]. + +data_es(#c_literal{val = V}) -> + case V of + [Head | Tail] -> + [#c_literal{val = Head}, #c_literal{val = Tail}]; + _ when is_tuple(V) -> + make_lit_list(tuple_to_list(V)); + _ -> + [] + end; +data_es(#c_cons{hd = H, tl = T}) -> + [H, T]; +data_es(#c_tuple{es = Es}) -> + Es. + +%% @spec data_arity(Node::cerl()) -> non_neg_integer() +%% +%% @doc Returns the number of subtrees of a data constructor +%% node. This is equivalent to <code>length(data_es(Node))</code>, but +%% potentially more efficient. +%% +%% @see is_data/1 +%% @see data_es/1 + +-spec data_arity(c_lct()) -> non_neg_integer(). + +data_arity(#c_literal{val = V}) -> + case V of + [_ | _] -> + 2; + _ when is_tuple(V) -> + tuple_size(V); + _ -> + 0 + end; +data_arity(#c_cons{}) -> + 2; +data_arity(#c_tuple{es = Es}) -> + length(Es). + + +%% @spec make_data(Type::dtype(), Elements::[cerl()]) -> cerl() +%% +%% @doc Creates a data constructor node with the specified type and +%% subtrees. (Cf. <code>data_type/1</code>.) An exception is thrown +%% if the length of <code>Elements</code> is invalid for the given +%% <code>Type</code>; see <code>data_es/1</code> for arity constraints +%% on constructor types. +%% +%% @see data_type/1 +%% @see data_es/1 +%% @see ann_make_data/3 +%% @see update_data/3 +%% @see make_data_skel/2 + +-spec make_data(dtype(), [cerl()]) -> c_lct(). + +make_data(CType, Es) -> + ann_make_data([], CType, Es). + + +%% @spec ann_make_data(As::anns(), Type::dtype(), +%% Elements::[cerl()]) -> cerl() +%% @see make_data/2 + +-spec ann_make_data(anns(), dtype(), [cerl()]) -> c_lct(). + +ann_make_data(As, {atomic, V}, []) -> #c_literal{val = V, anno = As}; +ann_make_data(As, cons, [H, T]) -> ann_c_cons(As, H, T); +ann_make_data(As, tuple, Es) -> ann_c_tuple(As, Es). + +%% @spec update_data(Old::cerl(), Type::dtype(), +%% Elements::[cerl()]) -> cerl() +%% @see make_data/2 + +-spec update_data(cerl(), dtype(), [cerl()]) -> c_lct(). + +update_data(Node, CType, Es) -> + ann_make_data(get_ann(Node), CType, Es). + + +%% @spec make_data_skel(Type::dtype(), Elements::[cerl()]) -> cerl() +%% +%% @doc Like <code>make_data/2</code>, but analogous to +%% <code>c_tuple_skel/1</code> and <code>c_cons_skel/2</code>. +%% +%% @see ann_make_data_skel/3 +%% @see update_data_skel/3 +%% @see make_data/2 +%% @see c_tuple_skel/1 +%% @see c_cons_skel/2 + +-spec make_data_skel(dtype(), [cerl()]) -> c_lct(). + +make_data_skel(CType, Es) -> + ann_make_data_skel([], CType, Es). + + +%% @spec ann_make_data_skel(As::anns(), Type::dtype(), +%% Elements::[cerl()]) -> cerl() +%% @see make_data_skel/2 + +-spec ann_make_data_skel(anns(), dtype(), [cerl()]) -> c_lct(). + +ann_make_data_skel(As, {atomic, V}, []) -> #c_literal{val = V, anno = As}; +ann_make_data_skel(As, cons, [H, T]) -> ann_c_cons_skel(As, H, T); +ann_make_data_skel(As, tuple, Es) -> ann_c_tuple_skel(As, Es). + + +%% @spec update_data_skel(Old::cerl(), Type::dtype(), +%% Elements::[cerl()]) -> cerl() +%% @see make_data_skel/2 + +-spec update_data_skel(cerl(), dtype(), [cerl()]) -> c_lct(). + +update_data_skel(Node, CType, Es) -> + ann_make_data_skel(get_ann(Node), CType, Es). + + +%% --------------------------------------------------------------------- + +%% @spec subtrees(Node::cerl()) -> [[cerl()]] +%% +%% @doc Returns the grouped list of all subtrees of a node. If +%% <code>Node</code> is a leaf node (cf. <code>is_leaf/1</code>), this +%% is the empty list, otherwise the result is always a nonempty list, +%% containing the lists of subtrees of <code>Node</code>, 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 +%% 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> +%% +%% <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 +%% 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> +%% +%% <p>For example: +%% <pre> +%% 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 +%% subtrees, doing a post-order traversal of the syntax tree. (Note +%% the use of <code>update_tree/2</code> to preserve annotations.) For +%% a simple function like: +%% <pre> +%% 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 extended with the prefix "a_", but nothing else (including +%% annotations) has been changed.</p> +%% +%% @see is_leaf/1 +%% @see make_tree/2 +%% @see update_tree/2 + +-spec subtrees(cerl()) -> [[cerl()]]. + +subtrees(T) -> + case is_leaf(T) of + true -> + []; + false -> + case type(T) of + values -> + [values_es(T)]; + binary -> + [binary_segments(T)]; + bitstr -> + [[bitstr_val(T)], [bitstr_size(T)], + [bitstr_unit(T)], [bitstr_type(T)], + [bitstr_flags(T)]]; + cons -> + [[cons_hd(T)], [cons_tl(T)]]; + tuple -> + [tuple_es(T)]; + map -> + [map_es(T)]; + map_pair -> + [[map_pair_op(T)],[map_pair_key(T)],[map_pair_val(T)]]; + 'let' -> + [let_vars(T), [let_arg(T)], [let_body(T)]]; + seq -> + [[seq_arg(T)], [seq_body(T)]]; + apply -> + [[apply_op(T)], apply_args(T)]; + call -> + [[call_module(T)], [call_name(T)], + call_args(T)]; + primop -> + [[primop_name(T)], primop_args(T)]; + 'case' -> + [[case_arg(T)], case_clauses(T)]; + clause -> + [clause_pats(T), [clause_guard(T)], + [clause_body(T)]]; + alias -> + [[alias_var(T)], [alias_pat(T)]]; + 'fun' -> + [fun_vars(T), [fun_body(T)]]; + 'receive' -> + [receive_clauses(T), [receive_timeout(T)], + [receive_action(T)]]; + 'try' -> + [[try_arg(T)], try_vars(T), [try_body(T)], + try_evars(T), [try_handler(T)]]; + 'catch' -> + [[catch_body(T)]]; + letrec -> + Es = unfold_tuples(letrec_defs(T)), + [Es, [letrec_body(T)]]; + module -> + As = unfold_tuples(module_attrs(T)), + Es = unfold_tuples(module_defs(T)), + [[module_name(T)], module_exports(T), As, Es] + end + end. + + +%% @spec update_tree(Old::cerl(), Groups::[[cerl()]]) -> cerl() +%% +%% @doc Creates a syntax tree with the given subtrees, and the same +%% type and annotations as the <code>Old</code> node. This is +%% equivalent to <code>ann_make_tree(get_ann(Node), type(Node), +%% Groups)</code>, but potentially more efficient. +%% +%% @see update_tree/3 +%% @see ann_make_tree/3 +%% @see get_ann/1 +%% @see type/1 + +-spec update_tree(cerl(), [[cerl()],...]) -> cerl(). + +update_tree(Node, Gs) -> + ann_make_tree(get_ann(Node), type(Node), Gs). + + +%% @spec update_tree(Old::cerl(), Type::ctype(), Groups::[[cerl()]]) -> +%% cerl() +%% +%% @doc Creates a syntax tree with the given type and subtrees, and +%% the same annotations as the <code>Old</code> node. This is +%% equivalent to <code>ann_make_tree(get_ann(Node), Type, +%% Groups)</code>, but potentially more efficient. +%% +%% @see update_tree/2 +%% @see ann_make_tree/3 +%% @see get_ann/1 + +-spec update_tree(cerl(), ctype(), [[cerl()],...]) -> cerl(). + +update_tree(Node, Type, Gs) -> + ann_make_tree(get_ann(Node), Type, Gs). + + +%% @spec make_tree(Type::ctype(), Groups::[[cerl()]]) -> cerl() +%% +%% @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 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>. +%% +%% <p>The result of <code>ann_make_tree(get_ann(Node), 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 does not necessarily have the exact same data +%% representation as <code>Node</code>.</p> +%% +%% @see ann_make_tree/3 +%% @see type/1 +%% @see is_leaf/1 +%% @see subtrees/1 +%% @see update_tree/2 + +-spec make_tree(ctype(), [[cerl()],...]) -> cerl(). + +make_tree(Type, Gs) -> + ann_make_tree([], Type, Gs). + + +%% @spec ann_make_tree(As::anns(), Type::ctype(), +%% Groups::[[cerl()]]) -> cerl() +%% +%% @doc Creates a syntax tree with the given annotations, type and +%% subtrees. See <code>make_tree/2</code> for details. +%% +%% @see make_tree/2 + +-spec ann_make_tree(anns(), ctype(), [[cerl()],...]) -> cerl(). + +ann_make_tree(As, values, [Es]) -> ann_c_values(As, Es); +ann_make_tree(As, binary, [Ss]) -> ann_c_binary(As, Ss); +ann_make_tree(As, bitstr, [[V],[S],[U],[T],[Fs]]) -> + ann_c_bitstr(As, V, S, U, T, Fs); +ann_make_tree(As, cons, [[H], [T]]) -> ann_c_cons(As, H, T); +ann_make_tree(As, tuple, [Es]) -> ann_c_tuple(As, Es); +ann_make_tree(As, map, [Es]) -> ann_c_map(As, Es); +ann_make_tree(As, map, [[A], Es]) -> ann_c_map(As, A, Es); +ann_make_tree(As, map_pair, [[Op], [K], [V]]) -> ann_c_map_pair(As, Op, K, V); +ann_make_tree(As, 'let', [Vs, [A], [B]]) -> ann_c_let(As, Vs, A, B); +ann_make_tree(As, seq, [[A], [B]]) -> ann_c_seq(As, A, B); +ann_make_tree(As, apply, [[Op], Es]) -> ann_c_apply(As, Op, Es); +ann_make_tree(As, call, [[M], [N], Es]) -> ann_c_call(As, M, N, Es); +ann_make_tree(As, primop, [[N], Es]) -> ann_c_primop(As, N, Es); +ann_make_tree(As, 'case', [[A], Cs]) -> ann_c_case(As, A, Cs); +ann_make_tree(As, clause, [Ps, [G], [B]]) -> ann_c_clause(As, Ps, G, B); +ann_make_tree(As, alias, [[V], [P]]) -> ann_c_alias(As, V, P); +ann_make_tree(As, 'fun', [Vs, [B]]) -> ann_c_fun(As, Vs, B); +ann_make_tree(As, 'receive', [Cs, [T], [A]]) -> + ann_c_receive(As, Cs, T, A); +ann_make_tree(As, 'try', [[E], Vs, [B], Evs, [H]]) -> + ann_c_try(As, E, Vs, B, Evs, H); +ann_make_tree(As, 'catch', [[B]]) -> ann_c_catch(As, B); +ann_make_tree(As, letrec, [Es, [B]]) -> + ann_c_letrec(As, fold_tuples(Es), B); +ann_make_tree(As, module, [[N], Xs, Es, Ds]) -> + ann_c_module(As, N, Xs, fold_tuples(Es), fold_tuples(Ds)). + + +%% --------------------------------------------------------------------- + +%% @spec meta(Tree::cerl()) -> cerl() +%% +%% @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 representation may be different). The expression represented +%% by <code>MetaTree</code> is <em>implementation independent</em> +%% with regard to the data structures used by the abstract syntax tree +%% implementation. +%% +%% <p>Any node in <code>Tree</code> whose node type is +%% <code>var</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> +%% +%% <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 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 structure onto a +%% syntax tree representation - would output a string that might look +%% something like "<code>{var, ..., 'V'}</code>", 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 +%% <em>representation independent</em> syntax tree generating +%% expression; in the above case, something like +%% "<code>cerl:c_var('V')</code>".</p> +%% +%% <p>The implementation tries to generate compact code with respect +%% to literals and lists.</p> +%% +%% @see abstract/1 +%% @see type/1 +%% @see get_ann/1 + +-spec meta(cerl()) -> cerl(). + +meta(Node) -> + %% First of all we check for metavariables: + case type(Node) of + var -> + case lists:member(meta_var, get_ann(Node)) of + false -> + meta_0(var, Node); + true -> + %% A meta-variable: remove the first found + %% 'meta_var' annotation, but otherwise leave + %% the node unchanged. + set_ann(Node, lists:delete(meta_var, get_ann(Node))) + end; + Type -> + meta_0(Type, Node) + end. + +meta_0(Type, Node) -> + case get_ann(Node) of + [] -> + meta_1(Type, Node); + As -> + meta_call(set_ann, [meta_1(Type, Node), abstract(As)]) + end. + +meta_1(literal, Node) -> + %% We handle atomic literals separately, to get a bit + %% more compact code. For the rest, we use 'abstract'. + case concrete(Node) of + V when is_atom(V) -> + meta_call(c_atom, [Node]); + V when is_integer(V) -> + meta_call(c_int, [Node]); + V when is_float(V) -> + meta_call(c_float, [Node]); + [] -> + meta_call(c_nil, []); + _ -> + meta_call(abstract, [Node]) + end; +meta_1(var, Node) -> + %% A normal variable or function name. + meta_call(c_var, [abstract(var_name(Node))]); +meta_1(values, Node) -> + meta_call(c_values, + [make_list(meta_list(values_es(Node)))]); +meta_1(binary, Node) -> + meta_call(c_binary, + [make_list(meta_list(binary_segments(Node)))]); +meta_1(bitstr, Node) -> + meta_call(c_bitstr, + [meta(bitstr_val(Node)), + meta(bitstr_size(Node)), + meta(bitstr_unit(Node)), + meta(bitstr_type(Node)), + meta(bitstr_flags(Node))]); +meta_1(cons, Node) -> + %% The list is split up if some sublist has annotatations. If + %% we get exactly one element, we generate a 'c_cons' call + %% instead of 'make_list' to reconstruct the node. + case split_list(Node) of + {[H], Node1} -> + meta_call(c_cons, [meta(H), meta(Node1)]); + {L, Node1} -> + meta_call(make_list, + [make_list(meta_list(L)), meta(Node1)]) + end; +meta_1(tuple, Node) -> + meta_call(c_tuple, + [make_list(meta_list(tuple_es(Node)))]); +meta_1('let', Node) -> + meta_call(c_let, + [make_list(meta_list(let_vars(Node))), + meta(let_arg(Node)), meta(let_body(Node))]); +meta_1(seq, Node) -> + meta_call(c_seq, + [meta(seq_arg(Node)), meta(seq_body(Node))]); +meta_1(apply, Node) -> + meta_call(c_apply, + [meta(apply_op(Node)), + make_list(meta_list(apply_args(Node)))]); +meta_1(call, Node) -> + meta_call(c_call, + [meta(call_module(Node)), meta(call_name(Node)), + make_list(meta_list(call_args(Node)))]); +meta_1(primop, Node) -> + meta_call(c_primop, + [meta(primop_name(Node)), + make_list(meta_list(primop_args(Node)))]); +meta_1('case', Node) -> + meta_call(c_case, + [meta(case_arg(Node)), + make_list(meta_list(case_clauses(Node)))]); +meta_1(clause, Node) -> + meta_call(c_clause, + [make_list(meta_list(clause_pats(Node))), + meta(clause_guard(Node)), + meta(clause_body(Node))]); +meta_1(alias, Node) -> + meta_call(c_alias, + [meta(alias_var(Node)), meta(alias_pat(Node))]); +meta_1('fun', Node) -> + meta_call(c_fun, + [make_list(meta_list(fun_vars(Node))), + meta(fun_body(Node))]); +meta_1('receive', Node) -> + meta_call(c_receive, + [make_list(meta_list(receive_clauses(Node))), + meta(receive_timeout(Node)), + meta(receive_action(Node))]); +meta_1('try', Node) -> + meta_call(c_try, + [meta(try_arg(Node)), + make_list(meta_list(try_vars(Node))), + meta(try_body(Node)), + make_list(meta_list(try_evars(Node))), + meta(try_handler(Node))]); +meta_1('catch', Node) -> + meta_call(c_catch, [meta(catch_body(Node))]); +meta_1(letrec, Node) -> + meta_call(c_letrec, + [make_list([c_tuple([meta(N), meta(F)]) + || {N, F} <- letrec_defs(Node)]), + meta(letrec_body(Node))]); +meta_1(module, Node) -> + meta_call(c_module, + [meta(module_name(Node)), + make_list(meta_list(module_exports(Node))), + make_list([c_tuple([meta(A), meta(V)]) + || {A, V} <- module_attrs(Node)]), + make_list([c_tuple([meta(N), meta(F)]) + || {N, F} <- module_defs(Node)])]). + +meta_call(F, As) -> + c_call(c_atom(?MODULE), c_atom(F), As). + +meta_list([T | Ts]) -> + [meta(T) | meta_list(Ts)]; +meta_list([]) -> + []. + +split_list(Node) -> + split_list(set_ann(Node, []), []). + +split_list(Node, L) -> + A = get_ann(Node), + case type(Node) of + cons when A =:= [] -> + split_list(cons_tl(Node), [cons_hd(Node) | L]); + _ -> + {lists:reverse(L), Node} + end. + + +%% --------------------------------------------------------------------- + +%% General utilities + +is_lit_list([#c_literal{} | Es]) -> + is_lit_list(Es); +is_lit_list([_ | _]) -> + false; +is_lit_list([]) -> + true. + +lit_list_vals([#c_literal{val = V} | Es]) -> + [V | lit_list_vals(Es)]; +lit_list_vals([]) -> + []. + +-spec make_lit_list([litval()]) -> [c_literal()]. + +make_lit_list([V | Vs]) -> + [#c_literal{val = V} | make_lit_list(Vs)]; +make_lit_list([]) -> + []. + +%% The following tests are the same as done by 'io_lib:char_list' and +%% 'io_lib:printable_list', respectively, but for a single character. + +is_char_value(V) when V >= $\000, V =< $\377 -> true; +is_char_value(_) -> false. + +is_print_char_value(V) when V >= $\040, V =< $\176 -> true; +is_print_char_value(V) when V >= $\240, V =< $\377 -> true; +is_print_char_value(V) when V =:= $\b -> true; +is_print_char_value(V) when V =:= $\d -> true; +is_print_char_value(V) when V =:= $\e -> true; +is_print_char_value(V) when V =:= $\f -> true; +is_print_char_value(V) when V =:= $\n -> true; +is_print_char_value(V) when V =:= $\r -> true; +is_print_char_value(V) when V =:= $\s -> true; +is_print_char_value(V) when V =:= $\t -> true; +is_print_char_value(V) when V =:= $\v -> true; +is_print_char_value(V) when V =:= $\" -> true; +is_print_char_value(V) when V =:= $\' -> true; %' stupid Emacs. +is_print_char_value(V) when V =:= $\\ -> true; +is_print_char_value(_) -> false. + +is_char_list([V | Vs]) when is_integer(V) -> + is_char_value(V) andalso is_char_list(Vs); +is_char_list([]) -> + true; +is_char_list(_) -> + false. + +is_print_char_list([V | Vs]) when is_integer(V) -> + is_print_char_value(V) andalso is_print_char_list(Vs); +is_print_char_list([]) -> + true; +is_print_char_list(_) -> + false. + +unfold_tuples([{X, Y} | Ps]) -> + [X, Y | unfold_tuples(Ps)]; +unfold_tuples([]) -> + []. + +fold_tuples([X, Y | Es]) -> + [{X, Y} | fold_tuples(Es)]; +fold_tuples([]) -> + []. diff --git a/lib/dialyzer/test/opaque_SUITE_data/src/recrec/core_parse.hrl b/lib/dialyzer/test/opaque_SUITE_data/src/recrec/core_parse.hrl new file mode 100644 index 0000000000..5823622f05 --- /dev/null +++ b/lib/dialyzer/test/opaque_SUITE_data/src/recrec/core_parse.hrl @@ -0,0 +1,122 @@ +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 1999-2016. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% +%% +%% Purpose : Core Erlang syntax trees as records. + +%% It would be nice to incorporate some generic functions as well but +%% this could make including this file difficult. + +%% Note: the annotation list is *always* the first record field. +%% Thus it is possible to define the macros: +%% -define(get_ann(X), element(2, X)). +%% -define(set_ann(X, Y), setelement(2, X, Y)). + +%% The record definitions appear alphabetically + +-record(c_alias, {anno=[] :: cerl:anns(), + var :: cerl:c_var(), + pat :: cerl:cerl()}). + +-record(c_apply, {anno=[] :: cerl:anns(), + op :: cerl:c_var(), + args :: [cerl:cerl()]}). + +-record(c_binary, {anno=[] :: cerl:anns(), + segments :: [cerl:c_bitstr()]}). + +-record(c_bitstr, {anno=[], val, % val :: Tree, + size, % size :: Tree, + unit, % unit :: Tree, + type, % type :: Tree, + flags}). % flags :: Tree + +-record(c_call, {anno=[], module, % module :: cerl:cerl(), + name, % name :: cerl:cerl(), + args}). % args :: [cerl:cerl()] + +-record(c_case, {anno=[] :: cerl:anns(), + arg :: cerl:cerl(), + clauses :: [cerl:cerl()]}). + +-record(c_catch, {anno=[] :: cerl:anns(), body :: cerl:cerl()}). + +-record(c_clause, {anno=[] :: cerl:anns(), + pats, % :: [cerl:cerl()], % pats :: [Tree], + guard, % :: cerl:cerl(), % guard :: Tree, + body}). % :: cerl:cerl()}). % body :: Tree + +-record(c_cons, {anno=[] :: cerl:anns(), + hd :: cerl:cerl(), + tl :: cerl:cerl()}). + +-record(c_fun, {anno=[] :: cerl:anns(), + vars :: [cerl:c_var()], + body :: cerl:cerl()}). + +-record(c_let, {anno=[] :: cerl:anns(), + vars :: [cerl:c_var()], + arg :: cerl:cerl(), + body :: cerl:cerl()}). + +-record(c_letrec, {anno=[] :: cerl:anns(), + defs :: cerl:defs(), + body :: cerl:cerl()}). + +-record(c_literal, {anno=[] :: cerl:anns(), val :: cerl:litval()}). + +-record(c_map, {anno=[] :: cerl:anns(), + arg=#c_literal{val=#{}} :: cerl:c_var() | cerl:c_literal(), + es :: [cerl:c_map_pair()], + is_pat=false :: boolean()}). + +-record(c_map_pair, {anno=[] :: cerl:anns(), + op, %:: #c_literal{val::'assoc'} | #c_literal{val::'exact'}, + key, + val}). + +-record(c_module, {anno=[] :: cerl:anns(), + name :: cerl:c_literal(), + exports :: [cerl:c_var()], + attrs :: cerl:attrs(), + defs :: cerl:defs()}). + +-record(c_primop, {anno=[] :: cerl:anns(), + name :: cerl:c_literal(), + args :: [cerl:cerl()]}). + +-record(c_receive, {anno=[]:: cerl:anns(), + clauses, % clauses :: [Tree], + timeout, % timeout :: Tree, + action}). % action :: Tree + +-record(c_seq, {anno=[] :: cerl:anns(), + arg, % arg :: cerl:cerl(), + body}). % body :: cerl:cerl() + +-record(c_try, {anno=[], arg, % arg :: cerl:cerl(), + vars, % vars :: [cerl:c_var()], + body, % body :: cerl:cerl(), + evars, % evars :: [cerl:c_var()], + handler}). % handler :: cerl:cerl() + +-record(c_tuple, {anno=[] :: cerl:anns(), es :: [cerl:cerl()]}). + +-record(c_values, {anno=[] :: cerl:anns(), es :: [cerl:cerl()]}). + +-record(c_var, {anno=[] :: cerl:anns(), name :: cerl:var_name()}). diff --git a/lib/dialyzer/test/opaque_SUITE_data/src/recrec/dialyzer.hrl b/lib/dialyzer/test/opaque_SUITE_data/src/recrec/dialyzer.hrl new file mode 100644 index 0000000000..ea6a71217c --- /dev/null +++ b/lib/dialyzer/test/opaque_SUITE_data/src/recrec/dialyzer.hrl @@ -0,0 +1,180 @@ +%%% This is an -*- Erlang -*- file. +%%% +%%% %CopyrightBegin% +%%% +%%% Copyright Ericsson AB 2006-2015. All Rights Reserved. +%%% +%%% Licensed under the Apache License, Version 2.0 (the "License"); +%%% you may not use this file except in compliance with the License. +%%% You may obtain a copy of the License at +%%% +%%% http://www.apache.org/licenses/LICENSE-2.0 +%%% +%%% Unless required by applicable law or agreed to in writing, software +%%% distributed under the License is distributed on an "AS IS" BASIS, +%%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%%% See the License for the specific language governing permissions and +%%% limitations under the License. +%%% +%%% %CopyrightEnd% +%%% +%%%------------------------------------------------------------------- +%%% File : dialyzer.hrl +%%% Author : Tobias Lindahl <[email protected]> +%%% Kostis Sagonas <[email protected]> +%%% Description : Header file for Dialyzer. +%%% +%%% Created : 1 Oct 2004 by Kostis Sagonas <[email protected]> +%%%------------------------------------------------------------------- + +-define(RET_NOTHING_SUSPICIOUS, 0). +-define(RET_INTERNAL_ERROR, 1). +-define(RET_DISCREPANCIES, 2). + +-type dial_ret() :: ?RET_NOTHING_SUSPICIOUS + | ?RET_INTERNAL_ERROR + | ?RET_DISCREPANCIES. + +%%-------------------------------------------------------------------- +%% Warning classification +%%-------------------------------------------------------------------- + +-define(WARN_RETURN_NO_RETURN, warn_return_no_exit). +-define(WARN_RETURN_ONLY_EXIT, warn_return_only_exit). +-define(WARN_NOT_CALLED, warn_not_called). +-define(WARN_NON_PROPER_LIST, warn_non_proper_list). +-define(WARN_FUN_APP, warn_fun_app). +-define(WARN_MATCHING, warn_matching). +-define(WARN_OPAQUE, warn_opaque). +-define(WARN_FAILING_CALL, warn_failing_call). +-define(WARN_BIN_CONSTRUCTION, warn_bin_construction). +-define(WARN_CONTRACT_TYPES, warn_contract_types). +-define(WARN_CONTRACT_SYNTAX, warn_contract_syntax). +-define(WARN_CONTRACT_NOT_EQUAL, warn_contract_not_equal). +-define(WARN_CONTRACT_SUBTYPE, warn_contract_subtype). +-define(WARN_CONTRACT_SUPERTYPE, warn_contract_supertype). +-define(WARN_CONTRACT_RANGE, warn_contract_range). +-define(WARN_CALLGRAPH, warn_callgraph). +-define(WARN_UNMATCHED_RETURN, warn_umatched_return). +-define(WARN_RACE_CONDITION, warn_race_condition). +-define(WARN_BEHAVIOUR, warn_behaviour). +-define(WARN_UNDEFINED_CALLBACK, warn_undefined_callbacks). +-define(WARN_UNKNOWN, warn_unknown). +-define(WARN_MAP_CONSTRUCTION, warn_map_construction). + +%% +%% The following type has double role: +%% 1. It is the set of warnings that will be collected. +%% 2. It is also the set of tags for warnings that will be returned. +%% +-type dial_warn_tag() :: ?WARN_RETURN_NO_RETURN | ?WARN_RETURN_ONLY_EXIT + | ?WARN_NOT_CALLED | ?WARN_NON_PROPER_LIST + | ?WARN_MATCHING | ?WARN_OPAQUE | ?WARN_FUN_APP + | ?WARN_FAILING_CALL | ?WARN_BIN_CONSTRUCTION + | ?WARN_CONTRACT_TYPES | ?WARN_CONTRACT_SYNTAX + | ?WARN_CONTRACT_NOT_EQUAL | ?WARN_CONTRACT_SUBTYPE + | ?WARN_CONTRACT_SUPERTYPE | ?WARN_CALLGRAPH + | ?WARN_UNMATCHED_RETURN | ?WARN_RACE_CONDITION + | ?WARN_BEHAVIOUR | ?WARN_CONTRACT_RANGE + | ?WARN_UNDEFINED_CALLBACK | ?WARN_UNKNOWN + | ?WARN_MAP_CONSTRUCTION. + +%% +%% This is the representation of each warning as they will be returned +%% to dialyzer's callers +%% +-type file_line() :: {file:filename(), non_neg_integer()}. +-type dial_warning() :: {dial_warn_tag(), file_line(), {atom(), [term()]}}. + +%% +%% This is the representation of each warning before suppressions have +%% been applied +%% +-type m_or_mfa() :: module() % warnings not associated with any function + | mfa(). +-type warning_info() :: {file:filename(), non_neg_integer(), m_or_mfa()}. +-type raw_warning() :: {dial_warn_tag(), warning_info(), {atom(), [term()]}}. + +%% +%% This is the representation of dialyzer's internal errors +%% +-type dial_error() :: any(). %% XXX: underspecified + +%%-------------------------------------------------------------------- +%% Basic types used either in the record definitions below or in other +%% parts of the application +%%-------------------------------------------------------------------- + +-type anal_type() :: 'succ_typings' | 'plt_build'. +-type anal_type1() :: anal_type() | 'plt_add' | 'plt_check' | 'plt_remove'. +-type contr_constr() :: {'subtype', erl_types:erl_type(), erl_types:erl_type()}. +-type contract_pair() :: {erl_types:erl_type(), [contr_constr()]}. +-type dial_define() :: {atom(), term()}. +-type dial_option() :: {atom(), term()}. +-type dial_options() :: [dial_option()]. +-type fopt() :: 'basename' | 'fullpath'. +-type format() :: 'formatted' | 'raw'. +-type label() :: non_neg_integer(). +-type dial_warn_tags():: ordsets:ordset(dial_warn_tag()). +-type rep_mode() :: 'quiet' | 'normal' | 'verbose'. +-type start_from() :: 'byte_code' | 'src_code'. +-type mfa_or_funlbl() :: label() | mfa(). +-type solver() :: 'v1' | 'v2'. + +%%-------------------------------------------------------------------- +%% Record declarations used by various files +%%-------------------------------------------------------------------- + +-type doc_plt() :: 'undefined' | dialyzer_plt:plt(). + +-record(analysis, {analysis_pid :: pid() | 'undefined', + type = succ_typings :: anal_type(), + defines = [] :: [dial_define()], + doc_plt :: doc_plt(), + files = [] :: [file:filename()], + include_dirs = [] :: [file:filename()], + start_from = byte_code :: start_from(), + plt :: dialyzer_plt:plt(), + use_contracts = true :: boolean(), + race_detection = false :: boolean(), + behaviours_chk = false :: boolean(), + timing = false :: boolean() | 'debug', + timing_server = none :: dialyzer_timing:timing_server(), + callgraph_file = "" :: file:filename(), + solvers :: [solver()]}). + +-record(options, {files = [] :: [file:filename()], + files_rec = [] :: [file:filename()], + analysis_type = succ_typings :: anal_type1(), + timing = false :: boolean() | 'debug', + defines = [] :: [dial_define()], + from = byte_code :: start_from(), + get_warnings = maybe :: boolean() | 'maybe', + init_plts = [] :: [file:filename()], + include_dirs = [] :: [file:filename()], + output_plt = none :: 'none' | file:filename(), + legal_warnings = ordsets:new() :: dial_warn_tags(), + report_mode = normal :: rep_mode(), + erlang_mode = false :: boolean(), + use_contracts = true :: boolean(), + output_file = none :: 'none' | file:filename(), + output_format = formatted :: format(), + filename_opt = basename :: fopt(), + callgraph_file = "" :: file:filename(), + check_plt = true :: boolean(), + solvers = [] :: [solver()]}). + +-record(contract, {contracts = [] :: [contract_pair()], + args = [] :: [erl_types:erl_type()], + forms = [] :: [{_, _}]}). + +%%-------------------------------------------------------------------- + +-define(timing(Server, Msg, Var, Expr), + begin + dialyzer_timing:start_stamp(Server, Msg), + Var = Expr, + dialyzer_timing:end_stamp(Server), + Var + end). +-define(timing(Server, Msg, Expr), ?timing(Server, Msg, _T, Expr)). diff --git a/lib/dialyzer/test/opaque_SUITE_data/src/recrec/dialyzer_dataflow.erl b/lib/dialyzer/test/opaque_SUITE_data/src/recrec/dialyzer_dataflow.erl new file mode 100644 index 0000000000..9399789464 --- /dev/null +++ b/lib/dialyzer/test/opaque_SUITE_data/src/recrec/dialyzer_dataflow.erl @@ -0,0 +1,3802 @@ +%% -*- erlang-indent-level: 2 -*- +%%-------------------------------------------------------------------- +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2006-2016. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% +%% + +%%%------------------------------------------------------------------- +%%% File : dialyzer_dataflow.erl +%%% Author : Tobias Lindahl <[email protected]> +%%% Description : +%%% +%%% Created : 19 Apr 2005 by Tobias Lindahl <[email protected]> +%%%------------------------------------------------------------------- + +-module(dialyzer_dataflow). + +-export([get_fun_types/5, get_warnings/5, format_args/3]). + +%% Data structure interfaces. +-export([state__add_warning/2, state__cleanup/1, + state__duplicate/1, dispose_state/1, + state__get_callgraph/1, state__get_races/1, + state__get_records/1, state__put_callgraph/2, + state__put_races/2, state__records_only/1, + state__find_function/2]). + +-export_type([state/0]). + +-include("dialyzer.hrl"). + +-import(erl_types, + [t_inf/2, t_inf/3, t_inf_lists/2, t_inf_lists/3, + t_inf_lists/3, t_is_equal/2, t_is_subtype/2, t_subtract/2, + t_sup/1, t_sup/2]). + +-import(erl_types, + [any_none/1, t_any/0, t_atom/0, t_atom/1, t_atom_vals/1, t_atom_vals/2, + t_binary/0, t_boolean/0, + t_bitstr/0, t_bitstr/2, t_bitstr_concat/1, t_bitstr_match/2, + t_cons/0, t_cons/2, t_cons_hd/2, t_cons_tl/2, + t_contains_opaque/2, + t_find_opaque_mismatch/3, t_float/0, t_from_range/2, t_from_term/1, + t_fun/0, t_fun/2, t_fun_args/1, t_fun_args/2, t_fun_range/1, + t_fun_range/2, t_integer/0, t_integers/1, + t_is_any/1, t_is_atom/1, t_is_atom/2, t_is_any_atom/3, + t_is_boolean/2, + t_is_integer/2, t_is_list/1, + t_is_nil/2, t_is_none/1, t_is_none_or_unit/1, + t_is_number/2, t_is_reference/2, t_is_pid/2, t_is_port/2, + t_is_unit/1, + t_limit/2, t_list/0, t_list_elements/2, + t_maybe_improper_list/0, t_module/0, + t_none/0, t_non_neg_integer/0, t_number/0, t_number_vals/2, + t_pid/0, t_port/0, t_product/1, t_reference/0, + t_to_string/2, t_to_tlist/1, + t_tuple/0, t_tuple/1, t_tuple_args/1, t_tuple_args/2, + t_tuple_subtypes/2, + t_unit/0, t_unopaque/2, + t_map/0, t_map/1, t_is_singleton/2 + ]). + +%%-define(DEBUG, true). +%%-define(DEBUG_PP, true). +%%-define(DEBUG_TIME, true). + +-ifdef(DEBUG). +-import(erl_types, [t_to_string/1]). +-define(debug(S_, L_), io:format(S_, L_)). +-else. +-define(debug(S_, L_), ok). +-endif. + +%%-------------------------------------------------------------------- + +-type type() :: erl_types:erl_type(). +-type types() :: erl_types:type_table(). + +-type curr_fun() :: 'undefined' | 'top' | mfa_or_funlbl(). + +-define(no_arg, no_arg). + +-define(TYPE_LIMIT, 3). + +-define(BITS, 128). + +%% Types with comment 'race' are due to dialyzer_races.erl. +-record(state, {callgraph :: dialyzer_callgraph:callgraph() + | 'undefined', % race + codeserver :: dialyzer_codeserver:codeserver() + | 'undefined', % race + envs :: env_tab() + | 'undefined', % race + fun_tab :: fun_tab() + | 'undefined', % race + fun_homes :: dict:dict(label(), mfa()) + | 'undefined', % race + plt :: dialyzer_plt:plt() + | 'undefined', % race + opaques :: [type()] + | 'undefined', % race + races = dialyzer_races:new() :: dialyzer_races:races(), + records = dict:new() :: types(), + tree_map :: dict:dict(label(), cerl:cerl()) + | 'undefined', % race + warning_mode = false :: boolean(), + warnings = [] :: [raw_warning()], + work :: {[_], [_], sets:set()} + | 'undefined', % race + module :: module(), + curr_fun :: curr_fun() + }). + +-record(map, {map = maps:new() :: type_tab(), + subst = maps:new() :: subst_tab(), + modified = [] :: [Key :: term()], + modified_stack = [] :: [{[Key :: term()],reference()}], + ref = undefined :: reference() | undefined}). + +-type env_tab() :: dict:dict(label(), #map{}). +-type fun_entry() :: {Args :: [type()], RetType :: type()}. +-type fun_tab() :: dict:dict('top' | label(), + {'not_handled', fun_entry()} | fun_entry()). +-type key() :: label() | cerl:cerl(). +-type type_tab() :: #{key() => type()}. +-type subst_tab() :: #{key() => cerl:cerl()}. + +%% Exported Types + +-opaque state() :: #state{}. + +%%-------------------------------------------------------------------- + +-type fun_types() :: dict:dict(label(), type()). + +-spec get_warnings(cerl:c_module(), dialyzer_plt:plt(), + dialyzer_callgraph:callgraph(), + dialyzer_codeserver:codeserver(), + types()) -> + {[raw_warning()], fun_types()}. + +get_warnings(Tree, Plt, Callgraph, Codeserver, Records) -> + State1 = analyze_module(Tree, Plt, Callgraph, Codeserver, Records, true), + State2 = state__renew_warnings(state__get_warnings(State1), State1), + State3 = state__get_race_warnings(State2), + {State3#state.warnings, state__all_fun_types(State3)}. + +-spec get_fun_types(cerl:c_module(), dialyzer_plt:plt(), + dialyzer_callgraph:callgraph(), + dialyzer_codeserver:codeserver(), + types()) -> fun_types(). + +get_fun_types(Tree, Plt, Callgraph, Codeserver, Records) -> + State = analyze_module(Tree, Plt, Callgraph, Codeserver, Records, false), + state__all_fun_types(State). + +%%% =========================================================================== +%%% +%%% The analysis. +%%% +%%% =========================================================================== + +analyze_module(Tree, Plt, Callgraph, Codeserver, Records, GetWarnings) -> + debug_pp(Tree, false), + Module = cerl:atom_val(cerl:module_name(Tree)), + TopFun = cerl:ann_c_fun([{label, top}], [], Tree), + State = state__new(Callgraph, Codeserver, TopFun, Plt, Module, Records), + State1 = state__race_analysis(not GetWarnings, State), + State2 = analyze_loop(State1), + case GetWarnings of + true -> + State3 = state__set_warning_mode(State2), + State4 = analyze_loop(State3), + dialyzer_races:race(State4); + false -> + State2 + end. + +analyze_loop(State) -> + case state__get_work(State) of + none -> state__set_curr_fun(undefined, State); + {Fun, NewState0} -> + NewState1 = state__set_curr_fun(get_label(Fun), NewState0), + {ArgTypes, IsCalled} = state__get_args_and_status(Fun, NewState1), + case not IsCalled of + true -> + ?debug("Not handling (not called) ~w: ~s\n", + [NewState1#state.curr_fun, + t_to_string(t_product(ArgTypes))]), + analyze_loop(NewState1); + false -> + case state__fun_env(Fun, NewState1) of + none -> + ?debug("Not handling (no env) ~w: ~s\n", + [NewState1#state.curr_fun, + t_to_string(t_product(ArgTypes))]), + analyze_loop(NewState1); + Map -> + ?debug("Handling fun ~p: ~s\n", + [NewState1#state.curr_fun, + t_to_string(state__fun_type(Fun, NewState1))]), + Vars = cerl:fun_vars(Fun), + Map1 = enter_type_lists(Vars, ArgTypes, Map), + Body = cerl:fun_body(Fun), + FunLabel = get_label(Fun), + IsRaceAnalysisEnabled = is_race_analysis_enabled(State), + NewState3 = + case IsRaceAnalysisEnabled of + true -> + NewState2 = state__renew_curr_fun( + state__lookup_name(FunLabel, NewState1), FunLabel, + NewState1), + state__renew_race_list([], 0, NewState2); + false -> NewState1 + end, + {NewState4, _Map2, BodyType} = + traverse(Body, Map1, NewState3), + ?debug("Done analyzing: ~w:~s\n", + [NewState1#state.curr_fun, + t_to_string(t_fun(ArgTypes, BodyType))]), + NewState5 = + case IsRaceAnalysisEnabled of + true -> renew_race_code(NewState4); + false -> NewState4 + end, + NewState6 = + state__update_fun_entry(Fun, ArgTypes, BodyType, NewState5), + ?debug("done adding stuff for ~w\n", + [state__lookup_name(get_label(Fun), State)]), + analyze_loop(NewState6) + end + end + end. + +traverse(Tree, Map, State) -> + ?debug("Handling ~p\n", [cerl:type(Tree)]), + %% debug_pp_map(Map), + case cerl:type(Tree) of + alias -> + %% This only happens when checking for illegal record patterns + %% so the handling is a bit rudimentary. + traverse(cerl:alias_pat(Tree), Map, State); + apply -> + handle_apply(Tree, Map, State); + binary -> + Segs = cerl:binary_segments(Tree), + {State1, Map1, SegTypes} = traverse_list(Segs, Map, State), + {State1, Map1, t_bitstr_concat(SegTypes)}; + bitstr -> + handle_bitstr(Tree, Map, State); + call -> + handle_call(Tree, Map, State); + 'case' -> + handle_case(Tree, Map, State); + 'catch' -> + {State1, _Map1, _} = traverse(cerl:catch_body(Tree), Map, State), + {State1, Map, t_any()}; + cons -> + handle_cons(Tree, Map, State); + 'fun' -> + Type = state__fun_type(Tree, State), + case state__warning_mode(State) of + true -> {State, Map, Type}; + false -> + State2 = state__add_work(get_label(Tree), State), + State3 = state__update_fun_env(Tree, Map, State2), + {State3, Map, Type} + end; + 'let' -> + handle_let(Tree, Map, State); + letrec -> + Defs = cerl:letrec_defs(Tree), + Body = cerl:letrec_body(Tree), + %% By not including the variables in scope we can assure that we + %% will get the current function type when using the variables. + FoldFun = fun({Var, Fun}, {AccState, AccMap}) -> + {NewAccState, NewAccMap0, FunType} = + traverse(Fun, AccMap, AccState), + NewAccMap = enter_type(Var, FunType, NewAccMap0), + {NewAccState, NewAccMap} + end, + {State1, Map1} = lists:foldl(FoldFun, {State, Map}, Defs), + traverse(Body, Map1, State1); + literal -> + Type = literal_type(Tree), + {State, Map, Type}; + module -> + handle_module(Tree, Map, State); + primop -> + Type = + case cerl:atom_val(cerl:primop_name(Tree)) of + match_fail -> t_none(); + raise -> t_none(); + bs_init_writable -> t_from_term(<<>>); + Other -> erlang:error({'Unsupported primop', Other}) + end, + {State, Map, Type}; + 'receive' -> + handle_receive(Tree, Map, State); + seq -> + Arg = cerl:seq_arg(Tree), + Body = cerl:seq_body(Tree), + {State1, Map1, ArgType} = SMA = traverse(Arg, Map, State), + case t_is_none_or_unit(ArgType) of + true -> + SMA; + false -> + State2 = + case + t_is_any(ArgType) + orelse t_is_simple(ArgType, State) + orelse is_call_to_send(Arg) + orelse is_lc_simple_list(Arg, ArgType, State) + of + true -> % do not warn in these cases + State1; + false -> + state__add_warning(State1, ?WARN_UNMATCHED_RETURN, Arg, + {unmatched_return, + [format_type(ArgType, State1)]}) + end, + traverse(Body, Map1, State2) + end; + 'try' -> + handle_try(Tree, Map, State); + tuple -> + handle_tuple(Tree, Map, State); + map -> + handle_map(Tree, Map, State); + values -> + Elements = cerl:values_es(Tree), + {State1, Map1, EsType} = traverse_list(Elements, Map, State), + Type = t_product(EsType), + {State1, Map1, Type}; + var -> + ?debug("Looking up unknown variable: ~p\n", [Tree]), + case state__lookup_type_for_letrec(Tree, State) of + error -> + LType = lookup_type(Tree, Map), + {State, Map, LType}; + {ok, Type} -> {State, Map, Type} + end; + Other -> + erlang:error({'Unsupported type', Other}) + end. + +traverse_list(Trees, Map, State) -> + traverse_list(Trees, Map, State, []). + +traverse_list([Tree|Tail], Map, State, Acc) -> + {State1, Map1, Type} = traverse(Tree, Map, State), + traverse_list(Tail, Map1, State1, [Type|Acc]); +traverse_list([], Map, State, Acc) -> + {State, Map, lists:reverse(Acc)}. + +%%________________________________________ +%% +%% Special instructions +%% + +handle_apply(Tree, Map, State) -> + Args = cerl:apply_args(Tree), + Op = cerl:apply_op(Tree), + {State0, Map1, ArgTypes} = traverse_list(Args, Map, State), + {State1, Map2, OpType} = traverse(Op, Map1, State0), + case any_none(ArgTypes) of + true -> + {State1, Map2, t_none()}; + false -> + FunList = + case state__lookup_call_site(Tree, State) of + error -> [external]; %% so that we go directly in the fallback + {ok, List} -> List + end, + FunInfoList = [{local, state__fun_info(Fun, State)} || Fun <- FunList], + case + handle_apply_or_call(FunInfoList, Args, ArgTypes, Map2, Tree, State1) + of + {had_external, State2} -> + %% Fallback: use whatever info we collected from traversing the op + %% instead of the result that has been generalized to t_any(). + Arity = length(Args), + OpType1 = t_inf(OpType, t_fun(Arity, t_any())), + case t_is_none(OpType1) of + true -> + Msg = {fun_app_no_fun, + [format_cerl(Op), format_type(OpType, State2), Arity]}, + State3 = state__add_warning(State2, ?WARN_FAILING_CALL, + Tree, Msg), + {State3, Map2, t_none()}; + false -> + NewArgs = t_inf_lists(ArgTypes, + t_fun_args(OpType1, 'universe')), + case any_none(NewArgs) of + true -> + Msg = {fun_app_args, + [format_args(Args, ArgTypes, State), + format_type(OpType, State)]}, + State3 = state__add_warning(State2, ?WARN_FAILING_CALL, + Tree, Msg), + {State3, enter_type(Op, OpType1, Map2), t_none()}; + false -> + Map3 = enter_type_lists(Args, NewArgs, Map2), + Range0 = t_fun_range(OpType1, 'universe'), + Range = + case t_is_unit(Range0) of + true -> t_none(); + false -> Range0 + end, + {State2, enter_type(Op, OpType1, Map3), Range} + end + end; + Normal -> Normal + end + end. + +handle_apply_or_call(FunInfoList, Args, ArgTypes, Map, Tree, State) -> + None = t_none(), + %% Call-site analysis may be inaccurate and consider more funs than those that + %% are actually possible. If all of them are incorrect, then warnings can be + %% emitted. If at least one fun is ok, however, then no warning is emitted, + %% just in case the bad ones are not really possible. The last argument is + %% used for this, with the following encoding: + %% Initial value: {none, []} + %% First fun checked: {one, <List of warns>} + %% More funs checked: {many, <List of warns>} + %% A '{one, []}' can only become '{many, []}'. + %% If at any point an fun does not add warnings, then the list is also + %% replaced with an empty list. + handle_apply_or_call(FunInfoList, Args, ArgTypes, Map, Tree, State, + [None || _ <- ArgTypes], None, false, {none, []}). + +handle_apply_or_call([{local, external}|Left], Args, ArgTypes, Map, Tree, State, + _AccArgTypes, _AccRet, _HadExternal, Warns) -> + {HowMany, _} = Warns, + NewHowMany = + case HowMany of + none -> one; + _ -> many + end, + NewWarns = {NewHowMany, []}, + handle_apply_or_call(Left, Args, ArgTypes, Map, Tree, State, + ArgTypes, t_any(), true, NewWarns); +handle_apply_or_call([{TypeOfApply, {Fun, Sig, Contr, LocalRet}}|Left], + Args, ArgTypes, Map, Tree, + #state{opaques = Opaques} = State, + AccArgTypes, AccRet, HadExternal, Warns) -> + Any = t_any(), + AnyArgs = [Any || _ <- Args], + GenSig = {AnyArgs, fun(_) -> t_any() end}, + {CArgs, CRange} = + case Contr of + {value, #contract{args = As} = C} -> + {As, fun(FunArgs) -> + dialyzer_contracts:get_contract_return(C, FunArgs) + end}; + none -> GenSig + end, + {BifArgs, BifRange} = + case TypeOfApply of + remote -> + {M, F, A} = Fun, + case erl_bif_types:is_known(M, F, A) of + true -> + BArgs = erl_bif_types:arg_types(M, F, A), + BRange = + fun(FunArgs) -> + erl_bif_types:type(M, F, A, FunArgs, Opaques) + end, + {BArgs, BRange}; + false -> + GenSig + end; + local -> GenSig + end, + {SigArgs, SigRange} = + case Sig of + {value, {SR, SA}} -> {SA, SR}; + none -> {AnyArgs, t_any()} + end, + + ?debug("--------------------------------------------------------\n", []), + ?debug("Fun: ~p\n", [state__lookup_name(Fun, State)]), + ?debug("Module ~p\n", [State#state.module]), + ?debug("CArgs ~s\n", [erl_types:t_to_string(t_product(CArgs))]), + ?debug("ArgTypes ~s\n", [erl_types:t_to_string(t_product(ArgTypes))]), + ?debug("BifArgs ~p\n", [erl_types:t_to_string(t_product(BifArgs))]), + + NewArgsSig = t_inf_lists(SigArgs, ArgTypes, Opaques), + ?debug("SigArgs ~s\n", [erl_types:t_to_string(t_product(SigArgs))]), + ?debug("NewArgsSig: ~s\n", [erl_types:t_to_string(t_product(NewArgsSig))]), + NewArgsContract = t_inf_lists(CArgs, ArgTypes, Opaques), + ?debug("NewArgsContract: ~s\n", + [erl_types:t_to_string(t_product(NewArgsContract))]), + NewArgsBif = t_inf_lists(BifArgs, ArgTypes, Opaques), + ?debug("NewArgsBif: ~s\n", [erl_types:t_to_string(t_product(NewArgsBif))]), + NewArgTypes0 = t_inf_lists(NewArgsSig, NewArgsContract), + NewArgTypes = t_inf_lists(NewArgTypes0, NewArgsBif, Opaques), + ?debug("NewArgTypes ~s\n", [erl_types:t_to_string(t_product(NewArgTypes))]), + ?debug("\n", []), + + BifRet = BifRange(NewArgTypes), + ContrRet = CRange(NewArgTypes), + RetWithoutContr = t_inf(SigRange, BifRet), + RetWithoutLocal = t_inf(ContrRet, RetWithoutContr), + + ?debug("RetWithoutContr: ~s\n",[erl_types:t_to_string(RetWithoutContr)]), + ?debug("RetWithoutLocal: ~s\n", [erl_types:t_to_string(RetWithoutLocal)]), + ?debug("BifRet: ~s\n", [erl_types:t_to_string(BifRange(NewArgTypes))]), + ?debug("SigRange: ~s\n", [erl_types:t_to_string(SigRange)]), + ?debug("ContrRet: ~s\n", [erl_types:t_to_string(ContrRet)]), + ?debug("LocalRet: ~s\n", [erl_types:t_to_string(LocalRet)]), + + State1 = + case is_race_analysis_enabled(State) of + true -> + Ann = cerl:get_ann(Tree), + File = get_file(Ann), + Line = abs(get_line(Ann)), + dialyzer_races:store_race_call(Fun, ArgTypes, Args, + {File, Line}, State); + false -> State + end, + FailedConj = any_none([RetWithoutLocal|NewArgTypes]), + IsFailBif = t_is_none(BifRange(BifArgs)), + IsFailSig = t_is_none(SigRange), + ?debug("FailedConj: ~p~n", [FailedConj]), + ?debug("IsFailBif: ~p~n", [IsFailBif]), + ?debug("IsFailSig: ~p~n", [IsFailSig]), + State2 = + case FailedConj andalso not (IsFailBif orelse IsFailSig) of + true -> + case t_is_none(RetWithoutLocal) andalso + not t_is_none(RetWithoutContr) andalso + not any_none(NewArgTypes) of + true -> + {value, C1} = Contr, + Contract = dialyzer_contracts:contract_to_string(C1), + {M1, F1, A1} = state__lookup_name(Fun, State), + ArgStrings = format_args(Args, ArgTypes, State), + CRet = erl_types:t_to_string(RetWithoutContr), + %% This Msg will be post_processed by dialyzer_succ_typings + Msg = + {contract_range, [Contract, M1, F1, A1, ArgStrings, CRet]}, + state__add_warning(State1, ?WARN_CONTRACT_RANGE, Tree, Msg); + false -> + FailedSig = any_none(NewArgsSig), + FailedContract = + any_none([CRange(NewArgsContract)|NewArgsContract]), + FailedBif = any_none([BifRange(NewArgsBif)|NewArgsBif]), + InfSig = t_inf(t_fun(SigArgs, SigRange), + t_fun(BifArgs, BifRange(BifArgs))), + FailReason = + apply_fail_reason(FailedSig, FailedBif, FailedContract), + Msg = get_apply_fail_msg(Fun, Args, ArgTypes, NewArgTypes, InfSig, + Contr, CArgs, State1, FailReason, Opaques), + WarnType = case Msg of + {call, _} -> ?WARN_FAILING_CALL; + {apply, _} -> ?WARN_FAILING_CALL; + {call_with_opaque, _} -> ?WARN_OPAQUE; + {call_without_opaque, _} -> ?WARN_OPAQUE; + {opaque_type_test, _} -> ?WARN_OPAQUE + end, + Frc = {erlang, is_record, 3} =:= state__lookup_name(Fun, State), + state__add_warning(State1, WarnType, Tree, Msg, Frc) + end; + false -> State1 + end, + State3 = + case TypeOfApply of + local -> + case state__is_escaping(Fun, State2) of + true -> State2; + false -> + ForwardArgs = [t_limit(X, ?TYPE_LIMIT) || X <- ArgTypes], + forward_args(Fun, ForwardArgs, State2) + end; + remote -> + add_bif_warnings(Fun, NewArgTypes, Tree, State2) + end, + NewAccArgTypes = + case FailedConj of + true -> AccArgTypes; + false -> [t_sup(X, Y) || {X, Y} <- lists:zip(NewArgTypes, AccArgTypes)] + end, + TotalRet = + case t_is_none(LocalRet) andalso t_is_unit(RetWithoutLocal) of + true -> RetWithoutLocal; + false -> t_inf(RetWithoutLocal, LocalRet) + end, + NewAccRet = t_sup(AccRet, TotalRet), + ?debug("NewAccRet: ~s\n", [t_to_string(NewAccRet)]), + {NewWarnings, State4} = state__remove_added_warnings(State, State3), + {HowMany, OldWarnings} = Warns, + NewWarns = + case HowMany of + none -> {one, NewWarnings}; + _ -> + case OldWarnings =:= [] of + true -> {many, []}; + false -> + case NewWarnings =:= [] of + true -> {many, []}; + false -> {many, NewWarnings ++ OldWarnings} + end + end + end, + handle_apply_or_call(Left, Args, ArgTypes, Map, Tree, + State4, NewAccArgTypes, NewAccRet, HadExternal, NewWarns); +handle_apply_or_call([], Args, _ArgTypes, Map, _Tree, State, + AccArgTypes, AccRet, HadExternal, {_, Warnings}) -> + State1 = state__add_warnings(Warnings, State), + case HadExternal of + false -> + NewMap = enter_type_lists(Args, AccArgTypes, Map), + {State1, NewMap, AccRet}; + true -> + {had_external, State1} + end. + +apply_fail_reason(FailedSig, FailedBif, FailedContract) -> + if + (FailedSig orelse FailedBif) andalso (not FailedContract) -> only_sig; + FailedContract andalso (not (FailedSig orelse FailedBif)) -> only_contract; + true -> both + end. + +get_apply_fail_msg(Fun, Args, ArgTypes, NewArgTypes, + Sig, Contract, ContrArgs, State, FailReason, Opaques) -> + ArgStrings = format_args(Args, ArgTypes, State), + ContractInfo = + case Contract of + {value, #contract{} = C} -> + {dialyzer_contracts:is_overloaded(C), + dialyzer_contracts:contract_to_string(C)}; + none -> {false, none} + end, + EnumArgTypes = lists:zip(lists:seq(1, length(NewArgTypes)), NewArgTypes), + ArgNs = [Arg || {Arg, Type} <- EnumArgTypes, t_is_none(Type)], + case state__lookup_name(Fun, State) of + {M, F, A} -> + case is_opaque_type_test_problem(Fun, Args, NewArgTypes, State) of + {yes, Arg, ArgType} -> + {opaque_type_test, [atom_to_list(F), ArgStrings, + format_arg(Arg), format_type(ArgType, State)]}; + no -> + SigArgs = t_fun_args(Sig), + BadOpaque = + opaque_problems([SigArgs, ContrArgs], ArgTypes, Opaques, ArgNs), + %% In fact *both* 'call_with_opaque' and + %% 'call_without_opaque' are possible. + case lists:keyfind(decl, 1, BadOpaque) of + {decl, BadArgs} -> + %% a structured term is used where an opaque is expected + ExpectedTriples = + case FailReason of + only_sig -> expected_arg_triples(BadArgs, SigArgs, State); + _ -> expected_arg_triples(BadArgs, ContrArgs, State) + end, + {call_without_opaque, [M, F, ArgStrings, ExpectedTriples]}; + false -> + case lists:keyfind(use, 1, BadOpaque) of + {use, BadArgs} -> + %% an opaque term is used where a structured term is expected + ExpectedArgs = + case FailReason of + only_sig -> SigArgs; + _ -> ContrArgs + end, + {call_with_opaque, [M, F, ArgStrings, BadArgs, ExpectedArgs]}; + false -> + case + erl_bif_types:opaque_args(M, F, A, ArgTypes, Opaques) + of + [] -> %% there is a structured term clash in some argument + {call, [M, F, ArgStrings, + ArgNs, FailReason, + format_sig_args(Sig, State), + format_type(t_fun_range(Sig), State), + ContractInfo]}; + Ns -> + {call_with_opaque, [M, F, ArgStrings, Ns, ContrArgs]} + end + end + end + end; + Label when is_integer(Label) -> + {apply, [ArgStrings, + ArgNs, FailReason, + format_sig_args(Sig, State), + format_type(t_fun_range(Sig), State), + ContractInfo]} + end. + +%% -> [{ElementI, [ArgN]}] where [ArgN] is a non-empty list of +%% arguments containing unknown opaque types and Element is 1 or 2. +opaque_problems(ContractOrSigList, ArgTypes, Opaques, ArgNs) -> + ArgElementList = find_unknown(ContractOrSigList, ArgTypes, Opaques, ArgNs), + F = fun(1) -> decl; (2) -> use end, + [{F(ElementI), lists:usort([ArgN || {ArgN, EI} <- ArgElementList, + EI =:= ElementI])} || + ElementI <- lists:usort([EI || {_, EI} <- ArgElementList])]. + +%% -> [{ArgN, ElementI}] where ElementI = 1 means there is an unknown +%% opaque type in argument ArgN of the the contract/signature, +%% and ElementI = 2 means that there is an unknown opaque type in +%% argument ArgN of the the (current) argument types. +find_unknown(ContractOrSigList, ArgTypes, Opaques, NoneArgNs) -> + ArgNs = lists:seq(1, length(ArgTypes)), + [{ArgN, ElementI} || + ContractOrSig <- ContractOrSigList, + {E1, E2, ArgN} <- lists:zip3(ContractOrSig, ArgTypes, ArgNs), + lists:member(ArgN, NoneArgNs), + ElementI <- erl_types:t_find_unknown_opaque(E1, E2, Opaques)]. + +is_opaque_type_test_problem(Fun, Args, ArgTypes, State) -> + case Fun of + {erlang, FN, 1} when FN =:= is_atom; FN =:= is_boolean; + FN =:= is_binary; FN =:= is_bitstring; + FN =:= is_float; FN =:= is_function; + FN =:= is_integer; FN =:= is_list; + FN =:= is_number; FN =:= is_pid; FN =:= is_port; + FN =:= is_reference; FN =:= is_tuple; + FN =:= is_map -> + type_test_opaque_arg(Args, ArgTypes, State#state.opaques); + {erlang, FN, 2} when FN =:= is_function -> + type_test_opaque_arg(Args, ArgTypes, State#state.opaques); + _ -> no + end. + +type_test_opaque_arg([], [], _Opaques) -> + no; +type_test_opaque_arg([Arg|Args], [ArgType|ArgTypes], Opaques) -> + case erl_types:t_has_opaque_subtype(ArgType, Opaques) of + true -> {yes, Arg, ArgType}; + false -> type_test_opaque_arg(Args, ArgTypes, Opaques) + end. + +expected_arg_triples(ArgNs, ArgTypes, State) -> + [begin + Arg = lists:nth(N, ArgTypes), + {N, Arg, format_type(Arg, State)} + end || N <- ArgNs]. + +add_bif_warnings({erlang, Op, 2}, [T1, T2] = Ts, Tree, State) + when Op =:= '=:='; Op =:= '==' -> + Opaques = State#state.opaques, + Inf = t_inf(T1, T2, Opaques), + case + t_is_none(Inf) andalso (not any_none(Ts)) + andalso (not is_int_float_eq_comp(T1, Op, T2, Opaques)) + of + true -> + %% Give priority to opaque warning (as usual). + case erl_types:t_find_unknown_opaque(T1, T2, Opaques) of + [] -> + Args = comp_format_args([], T1, Op, T2, State), + state__add_warning(State, ?WARN_MATCHING, Tree, {exact_eq, Args}); + Ns -> + Args = comp_format_args(Ns, T1, Op, T2, State), + state__add_warning(State, ?WARN_OPAQUE, Tree, {opaque_eq, Args}) + end; + false -> + State + end; +add_bif_warnings({erlang, Op, 2}, [T1, T2] = Ts, Tree, State) + when Op =:= '=/='; Op =:= '/=' -> + Opaques = State#state.opaques, + case + (not any_none(Ts)) + andalso (not is_int_float_eq_comp(T1, Op, T2, Opaques)) + of + true -> + case erl_types:t_find_unknown_opaque(T1, T2, Opaques) of + [] -> State; + Ns -> + Args = comp_format_args(Ns, T1, Op, T2, State), + state__add_warning(State, ?WARN_OPAQUE, Tree, {opaque_neq, Args}) + end; + false -> + State + end; +add_bif_warnings(_, _, _, State) -> + State. + +is_int_float_eq_comp(T1, Op, T2, Opaques) -> + (Op =:= '==' orelse Op =:= '/=') andalso + ((erl_types:t_is_float(T1, Opaques) + andalso t_is_integer(T2, Opaques)) orelse + (t_is_integer(T1, Opaques) + andalso erl_types:t_is_float(T2, Opaques))). + +comp_format_args([1|_], T1, Op, T2, State) -> + [format_type(T2, State), Op, format_type(T1, State)]; +comp_format_args(_, T1, Op, T2, State) -> + [format_type(T1, State), Op, format_type(T2, State)]. + +%%---------------------------------------- + +handle_bitstr(Tree, Map, State) -> + %% Construction of binaries. + Size = cerl:bitstr_size(Tree), + Val = cerl:bitstr_val(Tree), + BitstrType = cerl:concrete(cerl:bitstr_type(Tree)), + {State1, Map1, SizeType0} = traverse(Size, Map, State), + {State2, Map2, ValType0} = traverse(Val, Map1, State1), + case cerl:bitstr_bitsize(Tree) of + BitSz when BitSz =:= all orelse BitSz =:= utf -> + ValType = + case BitSz of + all -> + true = (BitstrType =:= binary), + t_inf(ValType0, t_bitstr()); + utf -> + true = lists:member(BitstrType, [utf8, utf16, utf32]), + t_inf(ValType0, t_integer()) + end, + Map3 = enter_type(Val, ValType, Map2), + case t_is_none(ValType) of + true -> + Msg = {bin_construction, ["value", + format_cerl(Val), format_cerl(Tree), + format_type(ValType0, State2)]}, + State3 = state__add_warning(State2, ?WARN_BIN_CONSTRUCTION, Val, Msg), + {State3, Map3, t_none()}; + false -> + {State2, Map3, t_bitstr()} + end; + BitSz when is_integer(BitSz) orelse BitSz =:= any -> + SizeType = t_inf(SizeType0, t_non_neg_integer()), + ValType = + case BitstrType of + binary -> t_inf(ValType0, t_bitstr()); + float -> t_inf(ValType0, t_number()); + integer -> t_inf(ValType0, t_integer()) + end, + case any_none([SizeType, ValType]) of + true -> + {Msg, Offending} = + case t_is_none(SizeType) of + true -> + {{bin_construction, + ["size", format_cerl(Size), format_cerl(Tree), + format_type(SizeType0, State2)]}, + Size}; + false -> + {{bin_construction, + ["value", format_cerl(Val), format_cerl(Tree), + format_type(ValType0, State2)]}, + Val} + end, + State3 = state__add_warning(State2, ?WARN_BIN_CONSTRUCTION, + Offending, Msg), + {State3, Map2, t_none()}; + false -> + UnitVal = cerl:concrete(cerl:bitstr_unit(Tree)), + Opaques = State2#state.opaques, + NumberVals = t_number_vals(SizeType, Opaques), + {State3, Type} = + case t_contains_opaque(SizeType, Opaques) of + true -> + Msg = {opaque_size, [format_type(SizeType, State2), + format_cerl(Size)]}, + {state__add_warning(State2, ?WARN_OPAQUE, Size, Msg), + t_none()}; + false -> + case NumberVals of + [OneSize] -> {State2, t_bitstr(0, OneSize * UnitVal)}; + unknown -> {State2, t_bitstr()}; + _ -> + MinSize = erl_types:number_min(SizeType, Opaques), + {State2, t_bitstr(UnitVal, UnitVal * MinSize)} + end + end, + Map3 = enter_type_lists([Val, Size, Tree], + [ValType, SizeType, Type], Map2), + {State3, Map3, Type} + end + end. + +%%---------------------------------------- + +handle_call(Tree, Map, State) -> + M = cerl:call_module(Tree), + F = cerl:call_name(Tree), + Args = cerl:call_args(Tree), + MFAList = [M, F|Args], + {State1, Map1, [MType0, FType0|As]} = traverse_list(MFAList, Map, State), + Opaques = State#state.opaques, + MType = t_inf(t_module(), MType0, Opaques), + FType = t_inf(t_atom(), FType0, Opaques), + Map2 = enter_type_lists([M, F], [MType, FType], Map1), + MOpaque = t_is_none(MType) andalso (not t_is_none(MType0)), + FOpaque = t_is_none(FType) andalso (not t_is_none(FType0)), + case any_none([MType, FType|As]) of + true -> + State2 = + if + MOpaque -> % This is a problem we just detected; not a known one + MS = format_cerl(M), + case t_is_none(t_inf(t_module(), MType0)) of + true -> + Msg = {app_call, [MS, format_cerl(F), + format_args(Args, As, State1), + MS, format_type(t_module(), State1), + format_type(MType0, State1)]}, + state__add_warning(State1, ?WARN_FAILING_CALL, Tree, Msg); + false -> + Msg = {opaque_call, [MS, format_cerl(F), + format_args(Args, As, State1), + MS, format_type(MType0, State1)]}, + state__add_warning(State1, ?WARN_FAILING_CALL, Tree, Msg) + end; + FOpaque -> + FS = format_cerl(F), + case t_is_none(t_inf(t_atom(), FType0)) of + true -> + Msg = {app_call, [format_cerl(M), FS, + format_args(Args, As, State1), + FS, format_type(t_atom(), State1), + format_type(FType0, State1)]}, + state__add_warning(State1, ?WARN_FAILING_CALL, Tree, Msg); + false -> + Msg = {opaque_call, [format_cerl(M), FS, + format_args(Args, As, State1), + FS, format_type(FType0, State1)]}, + state__add_warning(State1, ?WARN_FAILING_CALL, Tree, Msg) + end; + true -> State1 + end, + {State2, Map2, t_none()}; + false -> + case t_is_atom(MType) of + true -> + %% XXX: Consider doing this for all combinations of MF + case {t_atom_vals(MType), t_atom_vals(FType)} of + {[MAtom], [FAtom]} -> + FunInfo = [{remote, state__fun_info({MAtom, FAtom, length(Args)}, + State1)}], + handle_apply_or_call(FunInfo, Args, As, Map2, Tree, State1); + {_MAtoms, _FAtoms} -> + {State1, Map2, t_any()} + end; + false -> + {State1, Map2, t_any()} + end + end. + +%%---------------------------------------- + +handle_case(Tree, Map, State) -> + Arg = cerl:case_arg(Tree), + Clauses = filter_match_fail(cerl:case_clauses(Tree)), + {State1, Map1, ArgType} = SMA = traverse(Arg, Map, State), + case t_is_none_or_unit(ArgType) of + true -> SMA; + false -> + State2 = + case is_race_analysis_enabled(State) of + true -> + {RaceList, RaceListSize} = get_race_list_and_size(State1), + state__renew_race_list([beg_case|RaceList], + RaceListSize + 1, State1); + false -> State1 + end, + Map2 = join_maps_begin(Map1), + {MapList, State3, Type} = + handle_clauses(Clauses, Arg, ArgType, ArgType, State2, + [], Map2, [], []), + Map3 = join_maps_end(MapList, Map2), + debug_pp_map(Map3), + {State3, Map3, Type} + end. + +%%---------------------------------------- + +handle_cons(Tree, Map, State) -> + Hd = cerl:cons_hd(Tree), + Tl = cerl:cons_tl(Tree), + {State1, Map1, HdType} = traverse(Hd, Map, State), + {State2, Map2, TlType} = traverse(Tl, Map1, State1), + State3 = + case t_is_none(t_inf(TlType, t_list(), State2#state.opaques)) of + true -> + Msg = {improper_list_constr, [format_type(TlType, State2)]}, + state__add_warning(State2, ?WARN_NON_PROPER_LIST, Tree, Msg); + false -> + State2 + end, + Type = t_cons(HdType, TlType), + {State3, Map2, Type}. + +%%---------------------------------------- + +handle_let(Tree, Map, State) -> + IsRaceAnalysisEnabled = is_race_analysis_enabled(State), + Arg = cerl:let_arg(Tree), + Vars = cerl:let_vars(Tree), + {Map0, State0} = + case cerl:is_c_var(Arg) of + true -> + [Var] = Vars, + {enter_subst(Var, Arg, Map), + case IsRaceAnalysisEnabled of + true -> + {RaceList, RaceListSize} = get_race_list_and_size(State), + state__renew_race_list( + [dialyzer_races:let_tag_new(Var, Arg)|RaceList], + RaceListSize + 1, State); + false -> State + end}; + false -> {Map, State} + end, + Body = cerl:let_body(Tree), + {State1, Map1, ArgTypes} = SMA = traverse(Arg, Map0, State0), + State2 = + case IsRaceAnalysisEnabled andalso cerl:is_c_call(Arg) of + true -> + Mod = cerl:call_module(Arg), + Name = cerl:call_name(Arg), + case cerl:is_literal(Mod) andalso + cerl:concrete(Mod) =:= ets andalso + cerl:is_literal(Name) andalso + cerl:concrete(Name) =:= new of + true -> renew_race_public_tables(Vars, State1); + false -> State1 + end; + false -> State1 + end, + case t_is_none_or_unit(ArgTypes) of + true -> SMA; + false -> + Map2 = enter_type_lists(Vars, t_to_tlist(ArgTypes), Map1), + traverse(Body, Map2, State2) + end. + +%%---------------------------------------- + +handle_module(Tree, Map, State) -> + %% By not including the variables in scope we can assure that we + %% will get the current function type when using the variables. + Defs = cerl:module_defs(Tree), + PartFun = fun({_Var, Fun}) -> + state__is_escaping(get_label(Fun), State) + end, + {Defs1, Defs2} = lists:partition(PartFun, Defs), + Letrec = cerl:c_letrec(Defs1, cerl:c_int(42)), + {State1, Map1, _FunTypes} = traverse(Letrec, Map, State), + %% Also add environments for the other top-level functions. + VarTypes = [{Var, state__fun_type(Fun, State1)} || {Var, Fun} <- Defs], + EnvMap = enter_type_list(VarTypes, Map), + FoldFun = fun({_Var, Fun}, AccState) -> + state__update_fun_env(Fun, EnvMap, AccState) + end, + State2 = lists:foldl(FoldFun, State1, Defs2), + {State2, Map1, t_any()}. + +%%---------------------------------------- + +handle_receive(Tree, Map, State) -> + Clauses = filter_match_fail(cerl:receive_clauses(Tree)), + Timeout = cerl:receive_timeout(Tree), + State1 = + case is_race_analysis_enabled(State) of + true -> + {RaceList, RaceListSize} = get_race_list_and_size(State), + state__renew_race_list([beg_case|RaceList], + RaceListSize + 1, State); + false -> State + end, + {MapList, State2, ReceiveType} = + handle_clauses(Clauses, ?no_arg, t_any(), t_any(), State1, [], Map, + [], []), + Map1 = join_maps(MapList, Map), + {State3, Map2, TimeoutType} = traverse(Timeout, Map1, State2), + Opaques = State3#state.opaques, + case (t_is_atom(TimeoutType, Opaques) andalso + (t_atom_vals(TimeoutType, Opaques) =:= ['infinity'])) of + true -> + {State3, Map2, ReceiveType}; + false -> + Action = cerl:receive_action(Tree), + {State4, Map3, ActionType} = traverse(Action, Map, State3), + Map4 = join_maps([Map3, Map1], Map), + Type = t_sup(ReceiveType, ActionType), + {State4, Map4, Type} + end. + +%%---------------------------------------- + +handle_try(Tree, Map, State) -> + Arg = cerl:try_arg(Tree), + EVars = cerl:try_evars(Tree), + Vars = cerl:try_vars(Tree), + Body = cerl:try_body(Tree), + Handler = cerl:try_handler(Tree), + {State1, Map1, ArgType} = traverse(Arg, Map, State), + Map2 = mark_as_fresh(Vars, Map1), + {SuccState, SuccMap, SuccType} = + case bind_pat_vars(Vars, t_to_tlist(ArgType), [], Map2, State1) of + {error, _, _, _, _} -> + {State1, map__new(), t_none()}; + {SuccMap1, VarTypes} -> + %% Try to bind the argument. Will only succeed if + %% it is a simple structured term. + SuccMap2 = + case bind_pat_vars_reverse([Arg], [t_product(VarTypes)], [], + SuccMap1, State1) of + {error, _, _, _, _} -> SuccMap1; + {SM, _} -> SM + end, + traverse(Body, SuccMap2, State1) + end, + ExcMap1 = mark_as_fresh(EVars, Map), + {State2, ExcMap2, HandlerType} = traverse(Handler, ExcMap1, SuccState), + TryType = t_sup(SuccType, HandlerType), + {State2, join_maps([ExcMap2, SuccMap], Map1), TryType}. + +%%---------------------------------------- + +handle_map(Tree,Map,State) -> + Pairs = cerl:map_es(Tree), + Arg = cerl:map_arg(Tree), + {State1, Map1, ArgType} = traverse(Arg, Map, State), + ArgType1 = t_inf(t_map(), ArgType), + case t_is_none_or_unit(ArgType1) of + true -> + {State1, Map1, ArgType1}; + false -> + {State2, Map2, TypePairs, ExactKeys} = + traverse_map_pairs(Pairs, Map1, State1, t_none(), [], []), + InsertPair = fun({KV,assoc,_},Acc) -> erl_types:t_map_put(KV,Acc); + ({KV,exact,KVTree},Acc) -> + case t_is_none(T=erl_types:t_map_update(KV,Acc)) of + true -> throw({none, Acc, KV, KVTree}); + false -> T + end + end, + try lists:foldl(InsertPair, ArgType1, TypePairs) + of ResT -> + BindT = t_map([{K, t_any()} || K <- ExactKeys]), + case bind_pat_vars_reverse([Arg], [BindT], [], Map2, State2) of + {error, _, _, _, _} -> {State2, Map2, ResT}; + {Map3, _} -> {State2, Map3, ResT} + end + catch {none, MapType, {K,_}, KVTree} -> + Msg2 = {map_update, [format_type(MapType, State2), + format_type(K, State2)]}, + {state__add_warning(State2, ?WARN_MAP_CONSTRUCTION, KVTree, Msg2), + Map2, t_none()} + end + end. + +traverse_map_pairs([], Map, State, _ShadowKeys, PairAcc, KeyAcc) -> + {State, Map, lists:reverse(PairAcc), KeyAcc}; +traverse_map_pairs([Pair|Pairs], Map, State, ShadowKeys, PairAcc, KeyAcc) -> + Key = cerl:map_pair_key(Pair), + Val = cerl:map_pair_val(Pair), + Op = cerl:map_pair_op(Pair), + {State1, Map1, [K,V]} = traverse_list([Key,Val],Map,State), + KeyAcc1 = + case cerl:is_literal(Op) andalso cerl:concrete(Op) =:= exact andalso + t_is_singleton(K, State#state.opaques) andalso + t_is_none(t_inf(ShadowKeys, K)) of + true -> [K|KeyAcc]; + false -> KeyAcc + end, + traverse_map_pairs(Pairs, Map1, State1, t_sup(K, ShadowKeys), + [{{K,V},cerl:concrete(Op),Pair}|PairAcc], KeyAcc1). + +%%---------------------------------------- + +handle_tuple(Tree, Map, State) -> + Elements = cerl:tuple_es(Tree), + {State1, Map1, EsType} = traverse_list(Elements, Map, State), + TupleType = t_tuple(EsType), + case t_is_none(TupleType) of + true -> + {State1, Map1, t_none()}; + false -> + %% Let's find out if this is a record + case Elements of + [Tag|Left] -> + case cerl:is_c_atom(Tag) andalso is_literal_record(Tree) of + true -> + TagVal = cerl:atom_val(Tag), + case state__lookup_record(TagVal, length(Left), State1) of + error -> {State1, Map1, TupleType}; + {ok, RecType} -> + InfTupleType = t_inf(RecType, TupleType), + case t_is_none(InfTupleType) of + true -> + RecC = format_type(TupleType, State1), + FieldDiffs = format_field_diffs(TupleType, State1), + Msg = {record_constr, [RecC, FieldDiffs]}, + State2 = state__add_warning(State1, ?WARN_MATCHING, + Tree, Msg), + {State2, Map1, t_none()}; + false -> + case bind_pat_vars(Elements, t_tuple_args(RecType), + [], Map1, State1) of + {error, bind, ErrorPat, ErrorType, _} -> + Msg = {record_constr, + [TagVal, format_patterns(ErrorPat), + format_type(ErrorType, State1)]}, + State2 = state__add_warning(State1, ?WARN_MATCHING, + Tree, Msg), + {State2, Map1, t_none()}; + {error, opaque, ErrorPat, ErrorType, OpaqueType} -> + Msg = {opaque_match, + [format_patterns(ErrorPat), + format_type(ErrorType, State1), + format_type(OpaqueType, State1)]}, + State2 = state__add_warning(State1, ?WARN_OPAQUE, + Tree, Msg), + {State2, Map1, t_none()}; + {Map2, ETypes} -> + {State1, Map2, t_tuple(ETypes)} + end + end + end; + false -> + {State1, Map1, t_tuple(EsType)} + end; + [] -> + {State1, Map1, t_tuple([])} + end + end. + +%%---------------------------------------- +%% Clauses +%% +handle_clauses([C|Left], Arg, ArgType, OrigArgType, State, CaseTypes, MapIn, + Acc, ClauseAcc) -> + IsRaceAnalysisEnabled = is_race_analysis_enabled(State), + State1 = + case IsRaceAnalysisEnabled of + true -> + {RaceList, RaceListSize} = get_race_list_and_size(State), + state__renew_race_list( + [dialyzer_races:beg_clause_new(Arg, cerl:clause_pats(C), + cerl:clause_guard(C))| + RaceList], RaceListSize + 1, + State); + false -> State + end, + {State2, ClauseMap, BodyType, NewArgType} = + do_clause(C, Arg, ArgType, OrigArgType, MapIn, State1), + {NewClauseAcc, State3} = + case IsRaceAnalysisEnabled of + true -> + {RaceList1, RaceListSize1} = get_race_list_and_size(State2), + EndClause = dialyzer_races:end_clause_new(Arg, cerl:clause_pats(C), + cerl:clause_guard(C)), + {[EndClause|ClauseAcc], + state__renew_race_list([EndClause|RaceList1], + RaceListSize1 + 1, State2)}; + false -> {ClauseAcc, State2} + end, + {NewCaseTypes, NewAcc} = + case t_is_none(BodyType) of + true -> {CaseTypes, Acc}; + false -> {[BodyType|CaseTypes], [ClauseMap|Acc]} + end, + handle_clauses(Left, Arg, NewArgType, OrigArgType, State3, + NewCaseTypes, MapIn, NewAcc, NewClauseAcc); +handle_clauses([], _Arg, _ArgType, _OrigArgType, State, CaseTypes, _MapIn, Acc, + ClauseAcc) -> + State1 = + case is_race_analysis_enabled(State) of + true -> + {RaceList, RaceListSize} = get_race_list_and_size(State), + state__renew_race_list( + [dialyzer_races:end_case_new(ClauseAcc)|RaceList], + RaceListSize + 1, State); + false -> State + end, + {lists:reverse(Acc), State1, t_sup(CaseTypes)}. + +do_clause(C, Arg, ArgType0, OrigArgType, Map, State) -> + Pats = cerl:clause_pats(C), + Guard = cerl:clause_guard(C), + Body = cerl:clause_body(C), + State1 = + case is_race_analysis_enabled(State) of + true -> + state__renew_fun_args(Pats, State); + false -> State + end, + Map0 = mark_as_fresh(Pats, Map), + Map1 = if Arg =:= ?no_arg -> Map0; + true -> bind_subst(Arg, Pats, Map0) + end, + BindRes = + case t_is_none(ArgType0) of + true -> + {error, bind, Pats, ArgType0, ArgType0}; + false -> + ArgTypes = + case t_is_any(ArgType0) of + true -> [ArgType0 || _ <- Pats]; + false -> t_to_tlist(ArgType0) + end, + bind_pat_vars(Pats, ArgTypes, [], Map1, State1) + end, + case BindRes of + {error, ErrorType, NewPats, Type, OpaqueTerm} -> + ?debug("Failed binding pattern: ~s\nto ~s\n", + [cerl_prettypr:format(C), format_type(ArgType0, State1)]), + case state__warning_mode(State1) of + false -> + {State1, Map, t_none(), ArgType0}; + true -> + {Msg, Force} = + case t_is_none(ArgType0) of + true -> + PatString = format_patterns(Pats), + PatTypes = [PatString, format_type(OrigArgType, State1)], + %% See if this is covered by an earlier clause or if it + %% simply cannot match + OrigArgTypes = + case t_is_any(OrigArgType) of + true -> Any = t_any(), [Any || _ <- Pats]; + false -> t_to_tlist(OrigArgType) + end, + Tag = + case bind_pat_vars(Pats, OrigArgTypes, [], Map1, State1) of + {error, bind, _, _, _} -> pattern_match; + {error, record, _, _, _} -> record_match; + {error, opaque, _, _, _} -> opaque_match; + {_, _} -> pattern_match_cov + end, + {{Tag, PatTypes}, false}; + false -> + %% Try to find out if this is a default clause in a list + %% comprehension and supress this. A real Hack(tm) + Force0 = + case is_compiler_generated(cerl:get_ann(C)) of + true -> + case Pats of + [Pat] -> + case cerl:is_c_cons(Pat) of + true -> + not (cerl:is_c_var(cerl:cons_hd(Pat)) andalso + cerl:is_c_var(cerl:cons_tl(Pat)) andalso + cerl:is_literal(Guard) andalso + (cerl:concrete(Guard) =:= true)); + false -> + true + end; + [Pat0, Pat1] -> % binary comprehension + case cerl:is_c_cons(Pat0) of + true -> + not (cerl:is_c_var(cerl:cons_hd(Pat0)) andalso + cerl:is_c_var(cerl:cons_tl(Pat0)) andalso + cerl:is_c_var(Pat1) andalso + cerl:is_literal(Guard) andalso + (cerl:concrete(Guard) =:= true)); + false -> + true + end; + _ -> true + end; + false -> + true + end, + PatString = + case ErrorType of + bind -> format_patterns(Pats); + record -> format_patterns(NewPats); + opaque -> format_patterns(NewPats) + end, + PatTypes = case ErrorType of + bind -> [PatString, format_type(ArgType0, State1)]; + record -> [PatString, format_type(Type, State1)]; + opaque -> [PatString, format_type(Type, State1), + format_type(OpaqueTerm, State1)] + end, + FailedTag = case ErrorType of + bind -> pattern_match; + record -> record_match; + opaque -> opaque_match + end, + {{FailedTag, PatTypes}, Force0} + end, + WarnType = case Msg of + {opaque_match, _} -> ?WARN_OPAQUE; + {pattern_match, _} -> ?WARN_MATCHING; + {record_match, _} -> ?WARN_MATCHING; + {pattern_match_cov, _} -> ?WARN_MATCHING + end, + {state__add_warning(State1, WarnType, C, Msg, Force), + Map, t_none(), ArgType0} + end; + {Map2, PatTypes} -> + Map3 = + case Arg =:= ?no_arg of + true -> Map2; + false -> + %% Try to bind the argument. Will only succeed if + %% it is a simple structured term. + case bind_pat_vars_reverse([Arg], [t_product(PatTypes)], + [], Map2, State1) of + {error, _, _, _, _} -> Map2; + {NewMap, _} -> NewMap + end + end, + NewArgType = + case Arg =:= ?no_arg of + true -> ArgType0; + false -> + GenType = dialyzer_typesig:get_safe_underapprox(Pats, Guard), + t_subtract(t_product(t_to_tlist(ArgType0)), GenType) + end, + case bind_guard(Guard, Map3, State1) of + {error, Reason} -> + ?debug("Failed guard: ~s\n", + [cerl_prettypr:format(C, [{hook, cerl_typean:pp_hook()}])]), + PatString = format_patterns(Pats), + DefaultMsg = + case Pats =:= [] of + true -> {guard_fail, []}; + false -> + {guard_fail_pat, [PatString, format_type(ArgType0, State1)]} + end, + State2 = + case Reason of + none -> state__add_warning(State1, ?WARN_MATCHING, C, DefaultMsg); + {FailGuard, Msg} -> + case is_compiler_generated(cerl:get_ann(FailGuard)) of + false -> + WarnType = case Msg of + {guard_fail, _} -> ?WARN_MATCHING; + {neg_guard_fail, _} -> ?WARN_MATCHING; + {opaque_guard, _} -> ?WARN_OPAQUE + end, + state__add_warning(State1, WarnType, FailGuard, Msg); + true -> + state__add_warning(State1, ?WARN_MATCHING, C, Msg) + end + end, + {State2, Map, t_none(), NewArgType}; + Map4 -> + {RetState, RetMap, BodyType} = traverse(Body, Map4, State1), + {RetState, RetMap, BodyType, NewArgType} + end + end. + +bind_subst(Arg, Pats, Map) -> + case cerl:type(Arg) of + values -> + bind_subst_list(cerl:values_es(Arg), Pats, Map); + var -> + [Pat] = Pats, + enter_subst(Arg, Pat, Map); + _ -> + Map + end. + +bind_subst_list([Arg|ArgLeft], [Pat|PatLeft], Map) -> + NewMap = + case {cerl:type(Arg), cerl:type(Pat)} of + {var, var} -> enter_subst(Arg, Pat, Map); + {var, alias} -> enter_subst(Arg, cerl:alias_pat(Pat), Map); + {literal, literal} -> Map; + {T, T} -> bind_subst_list(lists:flatten(cerl:subtrees(Arg)), + lists:flatten(cerl:subtrees(Pat)), + Map); + _ -> Map + end, + bind_subst_list(ArgLeft, PatLeft, NewMap); +bind_subst_list([], [], Map) -> + Map. + +%%---------------------------------------- +%% Patterns +%% + +bind_pat_vars(Pats, Types, Acc, Map, State) -> + try + bind_pat_vars(Pats, Types, Acc, Map, State, false) + catch + throw:Error -> + %% Error = {error, bind | opaque | record, ErrorPats, ErrorType} + Error + end. + +bind_pat_vars_reverse(Pats, Types, Acc, Map, State) -> + try + bind_pat_vars(Pats, Types, Acc, Map, State, true) + catch + throw:Error -> + %% Error = {error, bind | opaque | record, ErrorPats, ErrorType} + Error + end. + +bind_pat_vars([Pat|PatLeft], [Type|TypeLeft], Acc, Map, State, Rev) -> + ?debug("Binding pat: ~w to ~s\n", [cerl:type(Pat), format_type(Type, State)] +), + Opaques = State#state.opaques, + {NewMap, TypeOut} = + case cerl:type(Pat) of + alias -> + %% Map patterns are more allowing than the type of their literal. We + %% must unfold AliasPat if it is a literal. + AliasPat = dialyzer_utils:refold_pattern(cerl:alias_pat(Pat)), + Var = cerl:alias_var(Pat), + Map1 = enter_subst(Var, AliasPat, Map), + {Map2, [PatType]} = bind_pat_vars([AliasPat], [Type], [], + Map1, State, Rev), + {enter_type(Var, PatType, Map2), PatType}; + binary -> + %% Cannot bind the binary if we are in reverse match since + %% binary patterns and binary construction are not symmetric. + case Rev of + true -> {Map, t_bitstr()}; + false -> + BinType = t_inf(t_bitstr(), Type, Opaques), + case t_is_none(BinType) of + true -> + case t_find_opaque_mismatch(t_bitstr(), Type, Opaques) of + {ok, T1, T2} -> + bind_error([Pat], T1, T2, opaque); + error -> + bind_error([Pat], Type, t_none(), bind) + end; + false -> + Segs = cerl:binary_segments(Pat), + {Map1, SegTypes} = bind_bin_segs(Segs, BinType, Map, State), + {Map1, t_bitstr_concat(SegTypes)} + end + end; + cons -> + Cons = t_inf(Type, t_cons(), Opaques), + case t_is_none(Cons) of + true -> + bind_opaque_pats(t_cons(), Type, Pat, State); + false -> + {Map1, [HdType, TlType]} = + bind_pat_vars([cerl:cons_hd(Pat), cerl:cons_tl(Pat)], + [t_cons_hd(Cons, Opaques), + t_cons_tl(Cons, Opaques)], + [], Map, State, Rev), + {Map1, t_cons(HdType, TlType)} + end; + literal -> + Pat0 = dialyzer_utils:refold_pattern(Pat), + case cerl:is_literal(Pat0) of + true -> + Literal = literal_type(Pat), + case t_is_none(t_inf(Literal, Type, Opaques)) of + true -> + bind_opaque_pats(Literal, Type, Pat, State); + false -> {Map, Literal} + end; + false -> + %% Retry with the unfolded pattern + {Map1, [PatType]} + = bind_pat_vars([Pat0], [Type], [], Map, State, Rev), + {Map1, PatType} + end; + map -> + MapT = t_inf(Type, t_map(), Opaques), + case t_is_none(MapT) of + true -> + bind_opaque_pats(t_map(), Type, Pat, State); + false -> + case Rev of + %% TODO: Reverse matching (propagating a matched subset back to a value) + true -> {Map, MapT}; + false -> + FoldFun = + fun(Pair, {MapAcc, ListAcc}) -> + %% Only exact (:=) can appear in patterns + exact = cerl:concrete(cerl:map_pair_op(Pair)), + Key = cerl:map_pair_key(Pair), + KeyType = + case cerl:type(Key) of + var -> + case state__lookup_type_for_letrec(Key, State) of + error -> lookup_type(Key, MapAcc); + {ok, RecType} -> RecType + end; + literal -> + literal_type(Key) + end, + Bind = erl_types:t_map_get(KeyType, MapT), + {MapAcc1, [ValType]} = + bind_pat_vars([cerl:map_pair_val(Pair)], + [Bind], [], MapAcc, State, Rev), + case t_is_singleton(KeyType, Opaques) of + true -> {MapAcc1, [{KeyType, ValType}|ListAcc]}; + false -> {MapAcc1, ListAcc} + end + end, + {Map1, Pairs} = lists:foldl(FoldFun, {Map, []}, cerl:map_es(Pat)), + {Map1, t_inf(MapT, t_map(Pairs))} + end + end; + tuple -> + Es = cerl:tuple_es(Pat), + {TypedRecord, Prototype} = + case Es of + [] -> {false, t_tuple([])}; + [Tag|Left] -> + case cerl:is_c_atom(Tag) andalso is_literal_record(Pat) of + true -> + TagAtom = cerl:atom_val(Tag), + case state__lookup_record(TagAtom, length(Left), State) of + error -> {false, t_tuple(length(Es))}; + {ok, Record} -> + [_Head|AnyTail] = [t_any() || _ <- Es], + UntypedRecord = t_tuple([t_atom(TagAtom)|AnyTail]), + {not t_is_equal(Record, UntypedRecord), Record} + end; + false -> {false, t_tuple(length(Es))} + end + end, + Tuple = t_inf(Prototype, Type, Opaques), + case t_is_none(Tuple) of + true -> + bind_opaque_pats(Prototype, Type, Pat, State); + false -> + SubTuples = t_tuple_subtypes(Tuple, Opaques), + %% Need to call the top function to get the try-catch wrapper + MapJ = join_maps_begin(Map), + Results = + case Rev of + true -> + [bind_pat_vars_reverse(Es, t_tuple_args(SubTuple, Opaques), + [], MapJ, State) + || SubTuple <- SubTuples]; + false -> + [bind_pat_vars(Es, t_tuple_args(SubTuple, Opaques), [], + MapJ, State) + || SubTuple <- SubTuples] + end, + case lists:keyfind(opaque, 2, Results) of + {error, opaque, _PatList, _Type, Opaque} -> + bind_error([Pat], Tuple, Opaque, opaque); + false -> + case [M || {M, _} <- Results, M =/= error] of + [] -> + case TypedRecord of + true -> bind_error([Pat], Tuple, Prototype, record); + false -> bind_error([Pat], Tuple, t_none(), bind) + end; + Maps -> + Map1 = join_maps_end(Maps, MapJ), + TupleType = t_sup([t_tuple(EsTypes) + || {M, EsTypes} <- Results, M =/= error]), + {Map1, TupleType} + end + end + end; + values -> + Es = cerl:values_es(Pat), + {Map1, EsTypes} = + bind_pat_vars(Es, t_to_tlist(Type), [], Map, State, Rev), + {Map1, t_product(EsTypes)}; + var -> + VarType1 = + case state__lookup_type_for_letrec(Pat, State) of + error -> lookup_type(Pat, Map); + {ok, RecType} -> RecType + end, + %% Must do inf when binding args to pats. Vars in pats are fresh. + VarType2 = t_inf(VarType1, Type, Opaques), + case t_is_none(VarType2) of + true -> + case t_find_opaque_mismatch(VarType1, Type, Opaques) of + {ok, T1, T2} -> + bind_error([Pat], T1, T2, opaque); + error -> + bind_error([Pat], Type, t_none(), bind) + end; + false -> + Map1 = enter_type(Pat, VarType2, Map), + {Map1, VarType2} + end; + _Other -> + %% Catch all is needed when binding args to pats + ?debug("Failed match for ~p\n", [_Other]), + bind_error([Pat], Type, t_none(), bind) + end, + bind_pat_vars(PatLeft, TypeLeft, [TypeOut|Acc], NewMap, State, Rev); +bind_pat_vars([], [], Acc, Map, _State, _Rev) -> + {Map, lists:reverse(Acc)}. + +bind_bin_segs(BinSegs, BinType, Map, State) -> + bind_bin_segs(BinSegs, BinType, [], Map, State). + +bind_bin_segs([Seg|Segs], BinType, Acc, Map, State) -> + Val = cerl:bitstr_val(Seg), + SegType = cerl:concrete(cerl:bitstr_type(Seg)), + UnitVal = cerl:concrete(cerl:bitstr_unit(Seg)), + case cerl:bitstr_bitsize(Seg) of + all -> + binary = SegType, [] = Segs, %% just an assert + T = t_inf(t_bitstr(UnitVal, 0), BinType), + {Map1, [Type]} = bind_pat_vars([Val], [T], [], Map, State, false), + Type1 = remove_local_opaque_types(Type, State#state.opaques), + bind_bin_segs(Segs, t_bitstr(0, 0), [Type1|Acc], Map1, State); + utf -> % XXX: possibly can be strengthened + true = lists:member(SegType, [utf8, utf16, utf32]), + {Map1, [_]} = bind_pat_vars([Val], [t_integer()], [], Map, State, false), + Type = t_binary(), + bind_bin_segs(Segs, BinType, [Type|Acc], Map1, State); + BitSz when is_integer(BitSz) orelse BitSz =:= any -> + Size = cerl:bitstr_size(Seg), + {Map1, [SizeType]} = + bind_pat_vars([Size], [t_non_neg_integer()], [], Map, State, false), + Opaques = State#state.opaques, + NumberVals = t_number_vals(SizeType, Opaques), + case t_contains_opaque(SizeType, Opaques) of + true -> bind_error([Seg], SizeType, t_none(), opaque); + false -> ok + end, + Type = + case NumberVals of + [OneSize] -> t_bitstr(0, UnitVal * OneSize); + _ -> % 'unknown' too + MinSize = erl_types:number_min(SizeType, Opaques), + t_bitstr(UnitVal, UnitVal * MinSize) + end, + ValConstr = + case SegType of + binary -> Type; %% The same constraints as for the whole bitstr + float -> t_float(); + integer -> + case NumberVals of + unknown -> t_integer(); + List -> + SizeVal = lists:max(List), + Flags = cerl:concrete(cerl:bitstr_flags(Seg)), + N = SizeVal * UnitVal, + case N >= ?BITS of + true -> + case lists:member(signed, Flags) of + true -> t_from_range(neg_inf, pos_inf); + false -> t_from_range(0, pos_inf) + end; + false -> + case lists:member(signed, Flags) of + true -> t_from_range(-(1 bsl (N - 1)), 1 bsl (N - 1) - 1); + false -> t_from_range(0, 1 bsl N - 1) + end + end + end + end, + {Map2, [_]} = bind_pat_vars([Val], [ValConstr], [], Map1, State, false), + NewBinType = t_bitstr_match(Type, BinType), + case t_is_none(NewBinType) of + true -> bind_error([Seg], BinType, t_none(), bind); + false -> bind_bin_segs(Segs, NewBinType, [Type|Acc], Map2, State) + end + end; +bind_bin_segs([], _BinType, Acc, Map, _State) -> + {Map, lists:reverse(Acc)}. + +bind_error(Pats, Type, OpaqueType, Error0) -> + Error = case {Error0, Pats} of + {bind, [Pat]} -> + case is_literal_record(Pat) of + true -> record; + false -> Error0 + end; + _ -> Error0 + end, + throw({error, Error, Pats, Type, OpaqueType}). + +-spec bind_opaque_pats(type(), type(), cerl:c_literal(), state()) -> + no_return(). + +bind_opaque_pats(GenType, Type, Pat, State) -> + case t_find_opaque_mismatch(GenType, Type, State#state.opaques) of + {ok, T1, T2} -> + bind_error([Pat], T1, T2, opaque); + error -> + bind_error([Pat], Type, t_none(), bind) + end. + +%%---------------------------------------- +%% Guards +%% + +bind_guard(Guard, Map, State) -> + try bind_guard(Guard, Map, maps:new(), pos, State) of + {Map1, _Type} -> Map1 + catch + throw:{fail, Warning} -> {error, Warning}; + throw:{fatal_fail, Warning} -> {error, Warning} + end. + +bind_guard(Guard, Map, Env, Eval, State) -> + ?debug("Handling ~w guard: ~s\n", + [Eval, cerl_prettypr:format(Guard, [{noann, true}])]), + case cerl:type(Guard) of + binary -> + {Map, t_binary()}; + 'case' -> + Arg = cerl:case_arg(Guard), + Clauses = cerl:case_clauses(Guard), + bind_guard_case_clauses(Arg, Clauses, Map, Env, Eval, State); + cons -> + Hd = cerl:cons_hd(Guard), + Tl = cerl:cons_tl(Guard), + {Map1, HdType} = bind_guard(Hd, Map, Env, dont_know, State), + {Map2, TlType} = bind_guard(Tl, Map1, Env, dont_know, State), + {Map2, t_cons(HdType, TlType)}; + literal -> + {Map, literal_type(Guard)}; + 'try' -> + Arg = cerl:try_arg(Guard), + [Var] = cerl:try_vars(Guard), + EVars = cerl:try_evars(Guard), + %%?debug("Storing: ~w\n", [Var]), + Map1 = join_maps_begin(Map), + Map2 = mark_as_fresh(EVars, Map1), + %% Visit handler first so we know if it should be ignored + {{HandlerMap, HandlerType}, HandlerE} = + try {bind_guard(cerl:try_handler(Guard), Map2, Env, Eval, State), none} + catch throw:HE -> + {{Map2, t_none()}, HE} + end, + BodyEnv = maps:put(get_label(Var), Arg, Env), + Wanted = case Eval of pos -> t_atom(true); neg -> t_atom(false); + dont_know -> t_any() end, + case t_is_none(t_inf(HandlerType, Wanted)) of + %% Handler won't save us; pretend it does not exist + true -> bind_guard(cerl:try_body(Guard), Map, BodyEnv, Eval, State); + false -> + {{BodyMap, BodyType}, BodyE} = + try {bind_guard(cerl:try_body(Guard), Map1, BodyEnv, + Eval, State), none} + catch throw:BE -> + {{Map1, t_none()}, BE} + end, + Map3 = join_maps_end([BodyMap, HandlerMap], Map1), + case t_is_none(Sup = t_sup(BodyType, HandlerType)) of + true -> + %% Pick a reason. N.B. We assume that the handler is always + %% compiler-generated if the body is; that way, we won't need to + %% check. + Fatality = case {BodyE, HandlerE} of + {{fatal_fail, _}, _} -> fatal_fail; + {_, {fatal_fail, _}} -> fatal_fail; + _ -> fail + end, + throw({Fatality, + case {BodyE, HandlerE} of + {{_, Rsn}, _} when Rsn =/= none -> Rsn; + {_, {_,Rsn}} -> Rsn; + _ -> none + end}); + false -> {Map3, Sup} + end + end; + tuple -> + Es0 = cerl:tuple_es(Guard), + {Map1, Es} = bind_guard_list(Es0, Map, Env, dont_know, State), + {Map1, t_tuple(Es)}; + map -> + case Eval of + dont_know -> handle_guard_map(Guard, Map, Env, State); + _PosOrNeg -> {Map, t_none()} %% Map exprs do not produce bools + end; + 'let' -> + Arg = cerl:let_arg(Guard), + [Var] = cerl:let_vars(Guard), + %%?debug("Storing: ~w\n", [Var]), + NewEnv = maps:put(get_label(Var), Arg, Env), + bind_guard(cerl:let_body(Guard), Map, NewEnv, Eval, State); + values -> + Es = cerl:values_es(Guard), + List = [bind_guard(V, Map, Env, dont_know, State) || V <- Es], + Type = t_product([T || {_, T} <- List]), + {Map, Type}; + var -> + ?debug("Looking for var(~w)...", [cerl_trees:get_label(Guard)]), + case maps:find(get_label(Guard), Env) of + error -> + ?debug("Did not find it\n", []), + Type = lookup_type(Guard, Map), + Constr = + case Eval of + pos -> t_atom(true); + neg -> t_atom(false); + dont_know -> Type + end, + Inf = t_inf(Constr, Type), + {enter_type(Guard, Inf, Map), Inf}; + {ok, Tree} -> + ?debug("Found it\n", []), + {Map1, Type} = bind_guard(Tree, Map, Env, Eval, State), + {enter_type(Guard, Type, Map1), Type} + end; + call -> + handle_guard_call(Guard, Map, Env, Eval, State) + end. + +handle_guard_call(Guard, Map, Env, Eval, State) -> + MFA = {cerl:atom_val(cerl:call_module(Guard)), + cerl:atom_val(cerl:call_name(Guard)), + cerl:call_arity(Guard)}, + case MFA of + {erlang, F, 1} when F =:= is_atom; F =:= is_boolean; + F =:= is_binary; F =:= is_bitstring; + F =:= is_float; F =:= is_function; + F =:= is_integer; F =:= is_list; F =:= is_map; + F =:= is_number; F =:= is_pid; F =:= is_port; + F =:= is_reference; F =:= is_tuple -> + handle_guard_type_test(Guard, F, Map, Env, Eval, State); + {erlang, is_function, 2} -> + handle_guard_is_function(Guard, Map, Env, Eval, State); + MFA when (MFA =:= {erlang, internal_is_record, 3}) or + (MFA =:= {erlang, is_record, 3}) -> + handle_guard_is_record(Guard, Map, Env, Eval, State); + {erlang, '=:=', 2} -> + handle_guard_eqeq(Guard, Map, Env, Eval, State); + {erlang, '==', 2} -> + handle_guard_eq(Guard, Map, Env, Eval, State); + {erlang, 'and', 2} -> + handle_guard_and(Guard, Map, Env, Eval, State); + {erlang, 'or', 2} -> + handle_guard_or(Guard, Map, Env, Eval, State); + {erlang, 'not', 1} -> + handle_guard_not(Guard, Map, Env, Eval, State); + {erlang, Comp, 2} when Comp =:= '<'; Comp =:= '=<'; + Comp =:= '>'; Comp =:= '>=' -> + handle_guard_comp(Guard, Comp, Map, Env, Eval, State); + _ -> + handle_guard_gen_fun(MFA, Guard, Map, Env, Eval, State) + end. + +handle_guard_gen_fun({M, F, A}, Guard, Map, Env, Eval, State) -> + Args = cerl:call_args(Guard), + {Map1, As} = bind_guard_list(Args, Map, Env, dont_know, State), + Opaques = State#state.opaques, + BifRet = erl_bif_types:type(M, F, A, As, Opaques), + case t_is_none(BifRet) of + true -> + %% Is this an error-bif? + case t_is_none(erl_bif_types:type(M, F, A)) of + true -> signal_guard_fail(Eval, Guard, As, State); + false -> signal_guard_fatal_fail(Eval, Guard, As, State) + end; + false -> + BifArgs = bif_args(M, F, A), + Map2 = enter_type_lists(Args, t_inf_lists(BifArgs, As, Opaques), Map1), + Ret = + case Eval of + pos -> t_inf(t_atom(true), BifRet); + neg -> t_inf(t_atom(false), BifRet); + dont_know -> BifRet + end, + case t_is_none(Ret) of + true -> + case Eval =:= pos of + true -> signal_guard_fail(Eval, Guard, As, State); + false -> throw({fail, none}) + end; + false -> {Map2, Ret} + end + end. + +handle_guard_type_test(Guard, F, Map, Env, Eval, State) -> + [Arg] = cerl:call_args(Guard), + {Map1, ArgType} = bind_guard(Arg, Map, Env, dont_know, State), + case bind_type_test(Eval, F, ArgType, State) of + error -> + ?debug("Type test: ~w failed\n", [F]), + signal_guard_fail(Eval, Guard, [ArgType], State); + {ok, NewArgType, Ret} -> + ?debug("Type test: ~w succeeded, NewType: ~s, Ret: ~s\n", + [F, t_to_string(NewArgType), t_to_string(Ret)]), + {enter_type(Arg, NewArgType, Map1), Ret} + end. + +bind_type_test(Eval, TypeTest, ArgType, State) -> + Type = case TypeTest of + is_atom -> t_atom(); + is_boolean -> t_boolean(); + is_binary -> t_binary(); + is_bitstring -> t_bitstr(); + is_float -> t_float(); + is_function -> t_fun(); + is_integer -> t_integer(); + is_list -> t_maybe_improper_list(); + is_map -> t_map(); + is_number -> t_number(); + is_pid -> t_pid(); + is_port -> t_port(); + is_reference -> t_reference(); + is_tuple -> t_tuple() + end, + case Eval of + pos -> + Inf = t_inf(Type, ArgType, State#state.opaques), + case t_is_none(Inf) of + true -> error; + false -> {ok, Inf, t_atom(true)} + end; + neg -> + Sub = t_subtract(ArgType, Type), + case t_is_none(Sub) of + true -> error; + false -> {ok, Sub, t_atom(false)} + end; + dont_know -> + {ok, ArgType, t_boolean()} + end. + +handle_guard_comp(Guard, Comp, Map, Env, Eval, State) -> + Args = cerl:call_args(Guard), + [Arg1, Arg2] = Args, + {Map1, ArgTypes} = bind_guard_list(Args, Map, Env, dont_know, State), + Opaques = State#state.opaques, + [Type1, Type2] = ArgTypes, + IsInt1 = t_is_integer(Type1, Opaques), + IsInt2 = t_is_integer(Type2, Opaques), + case {type(Arg1), type(Arg2)} of + {{literal, Lit1}, {literal, Lit2}} -> + case erlang:Comp(cerl:concrete(Lit1), cerl:concrete(Lit2)) of + true when Eval =:= pos -> {Map, t_atom(true)}; + true when Eval =:= dont_know -> {Map, t_atom(true)}; + true when Eval =:= neg -> {Map, t_atom(true)}; + false when Eval =:= pos -> + signal_guard_fail(Eval, Guard, ArgTypes, State); + false when Eval =:= dont_know -> {Map, t_atom(false)}; + false when Eval =:= neg -> {Map, t_atom(false)} + end; + {{literal, Lit1}, var} when IsInt1 andalso IsInt2 andalso (Eval =:= pos) -> + case bind_comp_literal_var(Lit1, Arg2, Type2, Comp, Map1, Opaques) of + error -> signal_guard_fail(Eval, Guard, ArgTypes, State); + {ok, NewMap} -> {NewMap, t_atom(true)} + end; + {var, {literal, Lit2}} when IsInt1 andalso IsInt2 andalso (Eval =:= pos) -> + case bind_comp_literal_var(Lit2, Arg1, Type1, invert_comp(Comp), + Map1, Opaques) of + error -> signal_guard_fail(Eval, Guard, ArgTypes, State); + {ok, NewMap} -> {NewMap, t_atom(true)} + end; + {_, _} -> + handle_guard_gen_fun({erlang, Comp, 2}, Guard, Map, Env, Eval, State) + end. + +invert_comp('=<') -> '>='; +invert_comp('<') -> '>'; +invert_comp('>=') -> '=<'; +invert_comp('>') -> '<'. + +bind_comp_literal_var(Lit, Var, VarType, CompOp, Map, Opaques) -> + LitVal = cerl:concrete(Lit), + NewVarType = + case t_number_vals(VarType, Opaques) of + unknown -> + Range = + case CompOp of + '=<' -> t_from_range(LitVal, pos_inf); + '<' -> t_from_range(LitVal + 1, pos_inf); + '>=' -> t_from_range(neg_inf, LitVal); + '>' -> t_from_range(neg_inf, LitVal - 1) + end, + t_inf(Range, VarType, Opaques); + NumberVals -> + NewNumberVals = [X || X <- NumberVals, erlang:CompOp(LitVal, X)], + t_integers(NewNumberVals) + end, + case t_is_none(NewVarType) of + true -> error; + false -> {ok, enter_type(Var, NewVarType, Map)} + end. + +handle_guard_is_function(Guard, Map, Env, Eval, State) -> + Args = cerl:call_args(Guard), + {Map1, ArgTypes0} = bind_guard_list(Args, Map, Env, dont_know, State), + [FunType0, ArityType0] = ArgTypes0, + Opaques = State#state.opaques, + ArityType = t_inf(ArityType0, t_integer(), Opaques), + case t_is_none(ArityType) of + true -> signal_guard_fail(Eval, Guard, ArgTypes0, State); + false -> + FunTypeConstr = + case t_number_vals(ArityType, State#state.opaques) of + unknown -> t_fun(); + Vals -> + t_sup([t_fun(lists:duplicate(X, t_any()), t_any()) || X <- Vals]) + end, + FunType = t_inf(FunType0, FunTypeConstr, Opaques), + case t_is_none(FunType) of + true -> + case Eval of + pos -> signal_guard_fail(Eval, Guard, ArgTypes0, State); + neg -> {Map1, t_atom(false)}; + dont_know -> {Map1, t_atom(false)} + end; + false -> + case Eval of + pos -> {enter_type_lists(Args, [FunType, ArityType], Map1), + t_atom(true)}; + neg -> {Map1, t_atom(false)}; + dont_know -> {Map1, t_boolean()} + end + end + end. + +handle_guard_is_record(Guard, Map, Env, Eval, State) -> + Args = cerl:call_args(Guard), + [Rec, Tag0, Arity0] = Args, + Tag = cerl:atom_val(Tag0), + Arity = cerl:int_val(Arity0), + {Map1, RecType} = bind_guard(Rec, Map, Env, dont_know, State), + ArityMin1 = Arity - 1, + Opaques = State#state.opaques, + Tuple = t_tuple([t_atom(Tag)|lists:duplicate(ArityMin1, t_any())]), + case t_is_none(t_inf(Tuple, RecType, Opaques)) of + true -> + case erl_types:t_has_opaque_subtype(RecType, Opaques) of + true -> + signal_guard_fail(Eval, Guard, + [RecType, t_from_term(Tag), + t_from_term(Arity)], + State); + false -> + case Eval of + pos -> signal_guard_fail(Eval, Guard, + [RecType, t_from_term(Tag), + t_from_term(Arity)], + State); + neg -> {Map1, t_atom(false)}; + dont_know -> {Map1, t_atom(false)} + end + end; + false -> + TupleType = + case state__lookup_record(Tag, ArityMin1, State) of + error -> Tuple; + {ok, Prototype} -> Prototype + end, + Type = t_inf(TupleType, RecType, State#state.opaques), + case t_is_none(Type) of + true -> + %% No special handling of opaque errors. + FArgs = "record " ++ format_type(RecType, State), + Msg = {record_matching, [FArgs, Tag]}, + throw({fail, {Guard, Msg}}); + false -> + case Eval of + pos -> {enter_type(Rec, Type, Map1), t_atom(true)}; + neg -> {Map1, t_atom(false)}; + dont_know -> {Map1, t_boolean()} + end + end + end. + +handle_guard_eq(Guard, Map, Env, Eval, State) -> + [Arg1, Arg2] = cerl:call_args(Guard), + case {type(Arg1), type(Arg2)} of + {{literal, Lit1}, {literal, Lit2}} -> + case cerl:concrete(Lit1) =:= cerl:concrete(Lit2) of + true -> + if + Eval =:= pos -> {Map, t_atom(true)}; + Eval =:= neg -> + ArgTypes = [t_from_term(cerl:concrete(Lit1)), + t_from_term(cerl:concrete(Lit2))], + signal_guard_fail(Eval, Guard, ArgTypes, State); + Eval =:= dont_know -> {Map, t_atom(true)} + end; + false -> + if + Eval =:= neg -> {Map, t_atom(false)}; + Eval =:= dont_know -> {Map, t_atom(false)}; + Eval =:= pos -> + ArgTypes = [t_from_term(cerl:concrete(Lit1)), + t_from_term(cerl:concrete(Lit2))], + signal_guard_fail(Eval, Guard, ArgTypes, State) + end + end; + {{literal, Lit1}, _} when Eval =:= pos -> + case cerl:concrete(Lit1) of + Atom when is_atom(Atom) -> + bind_eqeq_guard_lit_other(Guard, Lit1, Arg2, Map, Env, State); + [] -> + bind_eqeq_guard_lit_other(Guard, Lit1, Arg2, Map, Env, State); + _ -> + bind_eq_guard(Guard, Lit1, Arg2, Map, Env, Eval, State) + end; + {_, {literal, Lit2}} when Eval =:= pos -> + case cerl:concrete(Lit2) of + Atom when is_atom(Atom) -> + bind_eqeq_guard_lit_other(Guard, Lit2, Arg1, Map, Env, State); + [] -> + bind_eqeq_guard_lit_other(Guard, Lit2, Arg1, Map, Env, State); + _ -> + bind_eq_guard(Guard, Arg1, Lit2, Map, Env, Eval, State) + end; + {_, _} -> + bind_eq_guard(Guard, Arg1, Arg2, Map, Env, Eval, State) + end. + +bind_eq_guard(Guard, Arg1, Arg2, Map, Env, Eval, State) -> + {Map1, Type1} = bind_guard(Arg1, Map, Env, dont_know, State), + {Map2, Type2} = bind_guard(Arg2, Map1, Env, dont_know, State), + Opaques = State#state.opaques, + case + t_is_nil(Type1, Opaques) orelse t_is_nil(Type2, Opaques) + orelse t_is_atom(Type1, Opaques) orelse t_is_atom(Type2, Opaques) + of + true -> bind_eqeq_guard(Guard, Arg1, Arg2, Map, Env, Eval, State); + false -> + %% XXX. Is this test OK? + OpArgs = erl_types:t_find_unknown_opaque(Type1, Type2, Opaques), + case OpArgs =:= [] of + true -> + case Eval of + pos -> {Map2, t_atom(true)}; + neg -> {Map2, t_atom(false)}; + dont_know -> {Map2, t_boolean()} + end; + false -> + signal_guard_fail(Eval, Guard, [Type1, Type2], State) + end + end. + +handle_guard_eqeq(Guard, Map, Env, Eval, State) -> + [Arg1, Arg2] = cerl:call_args(Guard), + case {type(Arg1), type(Arg2)} of + {{literal, Lit1}, {literal, Lit2}} -> + + case cerl:concrete(Lit1) =:= cerl:concrete(Lit2) of + true -> + if Eval =:= neg -> + ArgTypes = [t_from_term(cerl:concrete(Lit1)), + t_from_term(cerl:concrete(Lit2))], + signal_guard_fail(Eval, Guard, ArgTypes, State); + Eval =:= pos -> {Map, t_atom(true)}; + Eval =:= dont_know -> {Map, t_atom(true)} + end; + false -> + if Eval =:= neg -> {Map, t_atom(false)}; + Eval =:= dont_know -> {Map, t_atom(false)}; + Eval =:= pos -> + ArgTypes = [t_from_term(cerl:concrete(Lit1)), + t_from_term(cerl:concrete(Lit2))], + signal_guard_fail(Eval, Guard, ArgTypes, State) + end + end; + {{literal, Lit1}, _} when Eval =:= pos -> + bind_eqeq_guard_lit_other(Guard, Lit1, Arg2, Map, Env, State); + {_, {literal, Lit2}} when Eval =:= pos -> + bind_eqeq_guard_lit_other(Guard, Lit2, Arg1, Map, Env, State); + {_, _} -> + bind_eqeq_guard(Guard, Arg1, Arg2, Map, Env, Eval, State) + end. + +bind_eqeq_guard(Guard, Arg1, Arg2, Map, Env, Eval, State) -> + {Map1, Type1} = bind_guard(Arg1, Map, Env, dont_know, State), + {Map2, Type2} = bind_guard(Arg2, Map1, Env, dont_know, State), + ?debug("Types are:~s =:= ~s\n", [t_to_string(Type1), + t_to_string(Type2)]), + Opaques = State#state.opaques, + Inf = t_inf(Type1, Type2, Opaques), + case t_is_none(Inf) of + true -> + OpArgs = erl_types:t_find_unknown_opaque(Type1, Type2, Opaques), + case OpArgs =:= [] of + true -> + case Eval of + neg -> {Map2, t_atom(false)}; + dont_know -> {Map2, t_atom(false)}; + pos -> signal_guard_fail(Eval, Guard, [Type1, Type2], State) + end; + false -> + signal_guard_fail(Eval, Guard, [Type1, Type2], State) + end; + false -> + case Eval of + pos -> + case {cerl:type(Arg1), cerl:type(Arg2)} of + {var, var} -> + Map3 = enter_subst(Arg1, Arg2, Map2), + Map4 = enter_type(Arg2, Inf, Map3), + {Map4, t_atom(true)}; + {var, _} -> + Map3 = enter_type(Arg1, Inf, Map2), + {Map3, t_atom(true)}; + {_, var} -> + Map3 = enter_type(Arg2, Inf, Map2), + {Map3, t_atom(true)}; + {_, _} -> + {Map2, t_atom(true)} + end; + neg -> + {Map2, t_atom(false)}; + dont_know -> + {Map2, t_boolean()} + end + end. + +bind_eqeq_guard_lit_other(Guard, Arg1, Arg2, Map, Env, State) -> + Eval = dont_know, + Opaques = State#state.opaques, + case cerl:concrete(Arg1) of + true -> + {_, Type} = MT = bind_guard(Arg2, Map, Env, pos, State), + case t_is_any_atom(true, Type, Opaques) of + true -> MT; + false -> + {_, Type0} = bind_guard(Arg2, Map, Env, Eval, State), + signal_guard_fail(Eval, Guard, [Type0, t_atom(true)], State) + end; + false -> + {Map1, Type} = bind_guard(Arg2, Map, Env, neg, State), + case t_is_any_atom(false, Type, Opaques) of + true -> {Map1, t_atom(true)}; + false -> + {_, Type0} = bind_guard(Arg2, Map, Env, Eval, State), + signal_guard_fail(Eval, Guard, [Type0, t_atom(false)], State) + end; + Term -> + LitType = t_from_term(Term), + {Map1, Type} = bind_guard(Arg2, Map, Env, Eval, State), + case t_is_subtype(LitType, Type) of + false -> signal_guard_fail(Eval, Guard, [Type, LitType], State); + true -> + case cerl:is_c_var(Arg2) of + true -> {enter_type(Arg2, LitType, Map1), t_atom(true)}; + false -> {Map1, t_atom(true)} + end + end + end. + +handle_guard_and(Guard, Map, Env, Eval, State) -> + [Arg1, Arg2] = cerl:call_args(Guard), + Opaques = State#state.opaques, + case Eval of + pos -> + {Map1, Type1} = bind_guard(Arg1, Map, Env, Eval, State), + case t_is_any_atom(true, Type1, Opaques) of + false -> signal_guard_fail(Eval, Guard, [Type1, t_any()], State); + true -> + {Map2, Type2} = bind_guard(Arg2, Map1, Env, Eval, State), + case t_is_any_atom(true, Type2, Opaques) of + false -> signal_guard_fail(Eval, Guard, [Type1, Type2], State); + true -> {Map2, t_atom(true)} + end + end; + neg -> + MapJ = join_maps_begin(Map), + {Map1, Type1} = + try bind_guard(Arg1, MapJ, Env, neg, State) + catch throw:{fail, _} -> bind_guard(Arg2, MapJ, Env, pos, State) + end, + {Map2, Type2} = + try bind_guard(Arg2, MapJ, Env, neg, State) + catch throw:{fail, _} -> bind_guard(Arg1, MapJ, Env, pos, State) + end, + case + t_is_any_atom(false, Type1, Opaques) + orelse t_is_any_atom(false, Type2, Opaques) + of + true -> {join_maps_end([Map1, Map2], MapJ), t_atom(false)}; + false -> signal_guard_fail(Eval, Guard, [Type1, Type2], State) + end; + dont_know -> + MapJ = join_maps_begin(Map), + {Map1, Type1} = bind_guard(Arg1, MapJ, Env, dont_know, State), + {Map2, Type2} = bind_guard(Arg2, MapJ, Env, dont_know, State), + Bool1 = t_inf(Type1, t_boolean()), + Bool2 = t_inf(Type2, t_boolean()), + case t_is_none(Bool1) orelse t_is_none(Bool2) of + true -> throw({fatal_fail, none}); + false -> + NewMap = join_maps_end([Map1, Map2], MapJ), + NewType = + case {t_atom_vals(Bool1, Opaques), t_atom_vals(Bool2, Opaques)} of + {['true'] , ['true'] } -> t_atom(true); + {['false'], _ } -> t_atom(false); + {_ , ['false']} -> t_atom(false); + {unknown , _ } -> + signal_guard_fail(Eval, Guard, [Type1, Type2], State); + {_ , unknown } -> + signal_guard_fail(Eval, Guard, [Type1, Type2], State); + {_ , _ } -> t_boolean() + + end, + {NewMap, NewType} + end + end. + +handle_guard_or(Guard, Map, Env, Eval, State) -> + [Arg1, Arg2] = cerl:call_args(Guard), + Opaques = State#state.opaques, + case Eval of + pos -> + MapJ = join_maps_begin(Map), + {Map1, Bool1} = + try bind_guard(Arg1, MapJ, Env, pos, State) + catch + throw:{fail,_} -> bind_guard(Arg1, MapJ, Env, dont_know, State) + end, + {Map2, Bool2} = + try bind_guard(Arg2, MapJ, Env, pos, State) + catch + throw:{fail,_} -> bind_guard(Arg2, MapJ, Env, dont_know, State) + end, + case + ((t_is_any_atom(true, Bool1, Opaques) + andalso t_is_boolean(Bool2, Opaques)) + orelse + (t_is_any_atom(true, Bool2, Opaques) + andalso t_is_boolean(Bool1, Opaques))) + of + true -> {join_maps_end([Map1, Map2], MapJ), t_atom(true)}; + false -> signal_guard_fail(Eval, Guard, [Bool1, Bool2], State) + end; + neg -> + {Map1, Type1} = bind_guard(Arg1, Map, Env, neg, State), + case t_is_any_atom(false, Type1, Opaques) of + false -> signal_guard_fail(Eval, Guard, [Type1, t_any()], State); + true -> + {Map2, Type2} = bind_guard(Arg2, Map1, Env, neg, State), + case t_is_any_atom(false, Type2, Opaques) of + false -> signal_guard_fail(Eval, Guard, [Type1, Type2], State); + true -> {Map2, t_atom(false)} + end + end; + dont_know -> + MapJ = join_maps_begin(Map), + {Map1, Type1} = bind_guard(Arg1, MapJ, Env, dont_know, State), + {Map2, Type2} = bind_guard(Arg2, MapJ, Env, dont_know, State), + Bool1 = t_inf(Type1, t_boolean()), + Bool2 = t_inf(Type2, t_boolean()), + case t_is_none(Bool1) orelse t_is_none(Bool2) of + true -> throw({fatal_fail, none}); + false -> + NewMap = join_maps_end([Map1, Map2], MapJ), + NewType = + case {t_atom_vals(Bool1, Opaques), t_atom_vals(Bool2, Opaques)} of + {['false'], ['false']} -> t_atom(false); + {['true'] , _ } -> t_atom(true); + {_ , ['true'] } -> t_atom(true); + {unknown , _ } -> + signal_guard_fail(Eval, Guard, [Type1, Type2], State); + {_ , unknown } -> + signal_guard_fail(Eval, Guard, [Type1, Type2], State); + {_ , _ } -> t_boolean() + end, + {NewMap, NewType} + end + end. + +handle_guard_not(Guard, Map, Env, Eval, State) -> + [Arg] = cerl:call_args(Guard), + Opaques = State#state.opaques, + case Eval of + neg -> + {Map1, Type} = bind_guard(Arg, Map, Env, pos, State), + case t_is_any_atom(true, Type, Opaques) of + true -> {Map1, t_atom(false)}; + false -> + {_, Type0} = bind_guard(Arg, Map, Env, Eval, State), + signal_guard_fail(Eval, Guard, [Type0], State) + end; + pos -> + {Map1, Type} = bind_guard(Arg, Map, Env, neg, State), + case t_is_any_atom(false, Type, Opaques) of + true -> {Map1, t_atom(true)}; + false -> + {_, Type0} = bind_guard(Arg, Map, Env, Eval, State), + signal_guard_fail(Eval, Guard, [Type0], State) + end; + dont_know -> + {Map1, Type} = bind_guard(Arg, Map, Env, dont_know, State), + Bool = t_inf(Type, t_boolean()), + case t_is_none(Bool) of + true -> throw({fatal_fail, none}); + false -> + case t_atom_vals(Bool, Opaques) of + ['true'] -> {Map1, t_atom(false)}; + ['false'] -> {Map1, t_atom(true)}; + [_, _] -> {Map1, Bool}; + unknown -> signal_guard_fail(Eval, Guard, [Type], State) + end + end + end. + +bind_guard_list(Guards, Map, Env, Eval, State) -> + bind_guard_list(Guards, Map, Env, Eval, State, []). + +bind_guard_list([G|Gs], Map, Env, Eval, State, Acc) -> + {Map1, T} = bind_guard(G, Map, Env, Eval, State), + bind_guard_list(Gs, Map1, Env, Eval, State, [T|Acc]); +bind_guard_list([], Map, _Env, _Eval, _State, Acc) -> + {Map, lists:reverse(Acc)}. + +handle_guard_map(Guard, Map, Env, State) -> + Pairs = cerl:map_es(Guard), + Arg = cerl:map_arg(Guard), + {Map1, ArgType0} = bind_guard(Arg, Map, Env, dont_know, State), + ArgType1 = t_inf(t_map(), ArgType0), + case t_is_none_or_unit(ArgType1) of + true -> {Map1, t_none()}; + false -> + {Map2, TypePairs} = bind_guard_map_pairs(Pairs, Map1, Env, State, []), + {Map2, lists:foldl(fun({KV,assoc},Acc) -> erl_types:t_map_put(KV,Acc); + ({KV,exact},Acc) -> erl_types:t_map_update(KV,Acc) + end, ArgType1, TypePairs)} + end. + +bind_guard_map_pairs([], Map, _Env, _State, PairAcc) -> + {Map, lists:reverse(PairAcc)}; +bind_guard_map_pairs([Pair|Pairs], Map, Env, State, PairAcc) -> + Key = cerl:map_pair_key(Pair), + Val = cerl:map_pair_val(Pair), + Op = cerl:map_pair_op(Pair), + {Map1, [K,V]} = bind_guard_list([Key,Val],Map,Env,dont_know,State), + bind_guard_map_pairs(Pairs, Map1, Env, State, + [{{K,V},cerl:concrete(Op)}|PairAcc]). + +-type eval() :: 'pos' | 'neg' | 'dont_know'. + +-spec signal_guard_fail(eval(), cerl:c_call(), [type()], + state()) -> no_return(). + +signal_guard_fail(Eval, Guard, ArgTypes, State) -> + signal_guard_failure(Eval, Guard, ArgTypes, fail, State). + +-spec signal_guard_fatal_fail(eval(), cerl:c_call(), [erl_types:erl_type()], + state()) -> no_return(). + +signal_guard_fatal_fail(Eval, Guard, ArgTypes, State) -> + signal_guard_failure(Eval, Guard, ArgTypes, fatal_fail, State). + +signal_guard_failure(Eval, Guard, ArgTypes, Tag, State) -> + Args = cerl:call_args(Guard), + F = cerl:atom_val(cerl:call_name(Guard)), + {M, F, A} = MFA = {cerl:atom_val(cerl:call_module(Guard)), F, length(Args)}, + Opaques = State#state.opaques, + {Kind, XInfo} = + case erl_bif_types:opaque_args(M, F, A, ArgTypes, Opaques) of + [] -> + {case Eval of + neg -> neg_guard_fail; + pos -> guard_fail; + dont_know -> guard_fail + end, + []}; + Ns -> {opaque_guard, [Ns]} + end, + FArgs = + case is_infix_op(MFA) of + true -> + [ArgType1, ArgType2] = ArgTypes, + [Arg1, Arg2] = Args, + [format_args_1([Arg1], [ArgType1], State), + atom_to_list(F), + format_args_1([Arg2], [ArgType2], State)] ++ XInfo; + false -> + [F, format_args(Args, ArgTypes, State)] + end, + Msg = {Kind, FArgs}, + throw({Tag, {Guard, Msg}}). + +is_infix_op({erlang, '=:=', 2}) -> true; +is_infix_op({erlang, '==', 2}) -> true; +is_infix_op({erlang, '=/=', 2}) -> true; +is_infix_op({erlang, '=/', 2}) -> true; +is_infix_op({erlang, '<', 2}) -> true; +is_infix_op({erlang, '=<', 2}) -> true; +is_infix_op({erlang, '>', 2}) -> true; +is_infix_op({erlang, '>=', 2}) -> true; +is_infix_op({M, F, A}) when is_atom(M), is_atom(F), + is_integer(A), 0 =< A, A =< 255 -> false. + +bif_args(M, F, A) -> + case erl_bif_types:arg_types(M, F, A) of + unknown -> lists:duplicate(A, t_any()); + List -> List + end. + +bind_guard_case_clauses(Arg, Clauses, Map0, Env, Eval, State) -> + Clauses1 = filter_fail_clauses(Clauses), + Map = join_maps_begin(Map0), + {GenMap, GenArgType} = bind_guard(Arg, Map, Env, dont_know, State), + bind_guard_case_clauses(GenArgType, GenMap, Arg, Clauses1, Map, Env, Eval, + t_none(), [], State). + +filter_fail_clauses([Clause|Left]) -> + case (cerl:clause_pats(Clause) =:= []) of + true -> + Body = cerl:clause_body(Clause), + case cerl:is_literal(Body) andalso (cerl:concrete(Body) =:= fail) orelse + cerl:is_c_primop(Body) andalso + (cerl:atom_val(cerl:primop_name(Body)) =:= match_fail) of + true -> filter_fail_clauses(Left); + false -> [Clause|filter_fail_clauses(Left)] + end; + false -> + [Clause|filter_fail_clauses(Left)] + end; +filter_fail_clauses([]) -> + []. + +bind_guard_case_clauses(GenArgType, GenMap, ArgExpr, [Clause|Left], + Map, Env, Eval, AccType, AccMaps, State) -> + Pats = cerl:clause_pats(Clause), + {NewMap0, ArgType} = + case Pats of + [Pat] -> + case cerl:is_literal(Pat) of + true -> + try + case cerl:concrete(Pat) of + true -> bind_guard(ArgExpr, Map, Env, pos, State); + false -> bind_guard(ArgExpr, Map, Env, neg, State); + _ -> {GenMap, GenArgType} + end + catch + throw:{fail, _} -> {none, GenArgType} + end; + false -> + {GenMap, GenArgType} + end; + _ -> {GenMap, GenArgType} + end, + NewMap1 = + case Pats =:= [] of + true -> NewMap0; + false -> + case t_is_none(ArgType) of + true -> none; + false -> + ArgTypes = case t_is_any(ArgType) of + true -> Any = t_any(), [Any || _ <- Pats]; + false -> t_to_tlist(ArgType) + end, + case bind_pat_vars(Pats, ArgTypes, [], NewMap0, State) of + {error, _, _, _, _} -> none; + {PatMap, _PatTypes} -> PatMap + end + end + end, + Guard = cerl:clause_guard(Clause), + GenPatType = dialyzer_typesig:get_safe_underapprox(Pats, Guard), + NewGenArgType = t_subtract(GenArgType, GenPatType), + case (NewMap1 =:= none) orelse t_is_none(GenArgType) of + true -> + bind_guard_case_clauses(NewGenArgType, GenMap, ArgExpr, Left, Map, Env, + Eval, AccType, AccMaps, State); + false -> + {NewAccType, NewAccMaps} = + try + {NewMap2, GuardType} = bind_guard(Guard, NewMap1, Env, pos, State), + case t_is_none(t_inf(t_atom(true), GuardType)) of + true -> throw({fail, none}); + false -> ok + end, + {NewMap3, CType} = bind_guard(cerl:clause_body(Clause), NewMap2, + Env, Eval, State), + Opaques = State#state.opaques, + case Eval of + pos -> + case t_is_any_atom(true, CType, Opaques) of + true -> ok; + false -> throw({fail, none}) + end; + neg -> + case t_is_any_atom(false, CType, Opaques) of + true -> ok; + false -> throw({fail, none}) + end; + dont_know -> + ok + end, + {t_sup(AccType, CType), [NewMap3|AccMaps]} + catch + throw:{fail, _What} -> {AccType, AccMaps} + end, + bind_guard_case_clauses(NewGenArgType, GenMap, ArgExpr, Left, Map, Env, + Eval, NewAccType, NewAccMaps, State) + end; +bind_guard_case_clauses(_GenArgType, _GenMap, _ArgExpr, [], Map, _Env, _Eval, + AccType, AccMaps, _State) -> + case t_is_none(AccType) of + true -> throw({fail, none}); + false -> {join_maps_end(AccMaps, Map), AccType} + end. + +%%% =========================================================================== +%%% +%%% Maps and types. +%%% +%%% =========================================================================== + +map__new() -> + #map{}. + +%% join_maps_begin pushes 'modified' to the stack; join_maps pops +%% 'modified' from the stack. + +join_maps_begin(#map{modified = M, modified_stack = S, ref = Ref} = Map) -> + Map#map{ref = make_ref(), modified = [], modified_stack = [{M,Ref} | S]}. + +join_maps_end(Maps, MapOut) -> + #map{ref = Ref, modified_stack = [{M1,R1} | S]} = MapOut, + true = lists:all(fun(M) -> M#map.ref =:= Ref end, Maps), % sanity + Keys0 = lists:usort(lists:append([M#map.modified || M <- Maps])), + #map{map = Map, subst = Subst} = MapOut, + Keys = [Key || + Key <- Keys0, + maps:is_key(Key, Map) orelse maps:is_key(Key, Subst)], + Out = case Maps of + [] -> join_maps(Maps, MapOut); + _ -> join_maps(Keys, Maps, MapOut) + end, + debug_join_check(Maps, MapOut, Out), + Out#map{ref = R1, + modified = Out#map.modified ++ M1, % duplicates possible + modified_stack = S}. + +join_maps(Maps, MapOut) -> + #map{map = Map, subst = Subst} = MapOut, + Keys = ordsets:from_list(maps:keys(Map) ++ maps:keys(Subst)), + join_maps(Keys, Maps, MapOut). + +join_maps(Keys, Maps, MapOut) -> + KTs = join_maps_collect(Keys, Maps, MapOut), + lists:foldl(fun({K, T}, M) -> enter_type(K, T, M) end, MapOut, KTs). + +join_maps_collect([Key|Left], Maps, MapOut) -> + Type = join_maps_one_key(Maps, Key, t_none()), + case t_is_equal(lookup_type(Key, MapOut), Type) of + true -> join_maps_collect(Left, Maps, MapOut); + false -> [{Key, Type} | join_maps_collect(Left, Maps, MapOut)] + end; +join_maps_collect([], _Maps, _MapOut) -> + []. + +join_maps_one_key([Map|Left], Key, AccType) -> + case t_is_any(AccType) of + true -> + %% We can stop here + AccType; + false -> + join_maps_one_key(Left, Key, t_sup(lookup_type(Key, Map), AccType)) + end; +join_maps_one_key([], _Key, AccType) -> + AccType. + +-ifdef(DEBUG). +debug_join_check(Maps, MapOut, Out) -> + #map{map = Map, subst = Subst} = Out, + #map{map = Map2, subst = Subst2} = join_maps(Maps, MapOut), + F = fun(D) -> lists:keysort(1, maps:to_list(D)) end, + [throw({bug, join_maps}) || + F(Map) =/= F(Map2) orelse F(Subst) =/= F(Subst2)]. +-else. +debug_join_check(_Maps, _MapOut, _Out) -> ok. +-endif. + +enter_type_lists([Key|KeyTail], [Val|ValTail], Map) -> + Map1 = enter_type(Key, Val, Map), + enter_type_lists(KeyTail, ValTail, Map1); +enter_type_lists([], [], Map) -> + Map. + +enter_type_list([{Key, Val}|Left], Map) -> + Map1 = enter_type(Key, Val, Map), + enter_type_list(Left, Map1); +enter_type_list([], Map) -> + Map. + +enter_type(Key, Val, MS) -> + case cerl:is_literal(Key) of + true -> MS; + false -> + case cerl:is_c_values(Key) of + true -> + Keys = cerl:values_es(Key), + case t_is_any(Val) orelse t_is_none(Val) of + true -> + enter_type_lists(Keys, [Val || _ <- Keys], MS); + false -> + enter_type_lists(Keys, t_to_tlist(Val), MS) + end; + false -> + #map{map = Map, subst = Subst} = MS, + KeyLabel = get_label(Key), + case maps:find(KeyLabel, Subst) of + {ok, NewKey} -> + ?debug("Binding ~p to ~p\n", [KeyLabel, NewKey]), + enter_type(NewKey, Val, MS); + error -> + ?debug("Entering ~p :: ~s\n", [KeyLabel, t_to_string(Val)]), + case maps:find(KeyLabel, Map) of + {ok, Value} -> + case erl_types:t_is_equal(Val, Value) of + true -> MS; + false -> store_map(KeyLabel, Val, MS) + end; + error -> store_map(KeyLabel, Val, MS) + end + end + end + end. + +store_map(Key, Val, #map{map = Map, ref = undefined} = MapRec) -> + MapRec#map{map = maps:put(Key, Val, Map)}; +store_map(Key, Val, #map{map = Map, modified = Mod} = MapRec) -> + MapRec#map{map = maps:put(Key, Val, Map), modified = [Key | Mod]}. + +enter_subst(Key, Val0, #map{subst = Subst} = MS) -> + KeyLabel = get_label(Key), + Val = dialyzer_utils:refold_pattern(Val0), + case cerl:is_literal(Val) of + true -> + store_map(KeyLabel, literal_type(Val), MS); + false -> + case cerl:is_c_var(Val) of + false -> MS; + true -> + ValLabel = get_label(Val), + case maps:find(ValLabel, Subst) of + {ok, NewVal} -> + enter_subst(Key, NewVal, MS); + error -> + if KeyLabel =:= ValLabel -> MS; + true -> + ?debug("Subst: storing ~p = ~p\n", [KeyLabel, ValLabel]), + store_subst(KeyLabel, ValLabel, MS) + end + end + end + end. + +store_subst(Key, Val, #map{subst = S, ref = undefined} = Map) -> + Map#map{subst = maps:put(Key, Val, S)}; +store_subst(Key, Val, #map{subst = S, modified = Mod} = Map) -> + Map#map{subst = maps:put(Key, Val, S), modified = [Key | Mod]}. + +lookup_type(Key, #map{map = Map, subst = Subst}) -> + lookup(Key, Map, Subst, t_none()). + +lookup(Key, Map, Subst, AnyNone) -> + case cerl:is_literal(Key) of + true -> literal_type(Key); + false -> + Label = get_label(Key), + case maps:find(Label, Subst) of + {ok, NewKey} -> lookup(NewKey, Map, Subst, AnyNone); + error -> + case maps:find(Label, Map) of + {ok, Val} -> Val; + error -> AnyNone + end + end + end. + +lookup_fun_sig(Fun, Callgraph, Plt) -> + MFAorLabel = + case dialyzer_callgraph:lookup_name(Fun, Callgraph) of + error -> Fun; + {ok, MFA} -> MFA + end, + dialyzer_plt:lookup(Plt, MFAorLabel). + +literal_type(Lit) -> + t_from_term(cerl:concrete(Lit)). + +mark_as_fresh([Tree|Left], Map) -> + SubTrees1 = lists:append(cerl:subtrees(Tree)), + {SubTrees2, Map1} = + case cerl:type(Tree) of + bitstr -> + %% The Size field is not fresh. + {SubTrees1 -- [cerl:bitstr_size(Tree)], Map}; + map_pair -> + %% The keys are not fresh + {SubTrees1 -- [cerl:map_pair_key(Tree)], Map}; + var -> + {SubTrees1, enter_type(Tree, t_any(), Map)}; + _ -> + {SubTrees1, Map} + end, + mark_as_fresh(SubTrees2 ++ Left, Map1); +mark_as_fresh([], Map) -> + Map. + +-ifdef(DEBUG). +debug_pp_map(#map{map = Map}=MapRec) -> + Keys = maps:keys(Map), + io:format("Map:\n", []), + lists:foreach(fun (Key) -> + io:format("\t~w :: ~s\n", + [Key, t_to_string(lookup_type(Key, MapRec))]) + end, Keys), + ok. +-else. +debug_pp_map(_Map) -> ok. +-endif. + +%%% =========================================================================== +%%% +%%% Utilities +%%% +%%% =========================================================================== + +get_label(L) when is_integer(L) -> + L; +get_label(T) -> + cerl_trees:get_label(T). + +t_is_simple(ArgType, State) -> + Opaques = State#state.opaques, + t_is_atom(ArgType, Opaques) orelse t_is_number(ArgType, Opaques) + orelse t_is_port(ArgType, Opaques) + orelse t_is_pid(ArgType, Opaques) orelse t_is_reference(ArgType, Opaques) + orelse t_is_nil(ArgType, Opaques). + +remove_local_opaque_types(Type, Opaques) -> + t_unopaque(Type, Opaques). + +%% t_is_structured(ArgType) -> +%% case t_is_nil(ArgType) of +%% true -> false; +%% false -> +%% SType = t_inf(t_sup([t_list(), t_tuple(), t_binary()]), ArgType), +%% t_is_equal(ArgType, SType) +%% end. + +is_call_to_send(Tree) -> + case cerl:is_c_call(Tree) of + false -> false; + true -> + Mod = cerl:call_module(Tree), + Name = cerl:call_name(Tree), + Arity = cerl:call_arity(Tree), + cerl:is_c_atom(Mod) + andalso cerl:is_c_atom(Name) + andalso is_send(cerl:atom_val(Name)) + andalso (cerl:atom_val(Mod) =:= erlang) + andalso (Arity =:= 2) + end. + +is_send('!') -> true; +is_send(send) -> true; +is_send(_) -> false. + +is_lc_simple_list(Tree, TreeType, State) -> + Opaques = State#state.opaques, + Ann = cerl:get_ann(Tree), + lists:member(list_comprehension, Ann) + andalso t_is_list(TreeType) + andalso t_is_simple(t_list_elements(TreeType, Opaques), State). + +filter_match_fail([Clause] = Cls) -> + Body = cerl:clause_body(Clause), + case cerl:type(Body) of + primop -> + case cerl:atom_val(cerl:primop_name(Body)) of + match_fail -> []; + raise -> []; + _ -> Cls + end; + _ -> Cls + end; +filter_match_fail([H|T]) -> + [H|filter_match_fail(T)]; +filter_match_fail([]) -> + %% This can actually happen, for example in + %% receive after 1 -> ok end + []. + +%%% =========================================================================== +%%% +%%% The State. +%%% +%%% =========================================================================== + +state__new(Callgraph, Codeserver, Tree, Plt, Module, Records) -> + Opaques = erl_types:t_opaque_from_records(Records), + {TreeMap, FunHomes} = build_tree_map(Tree, Callgraph), + Funs = dict:fetch_keys(TreeMap), + FunTab = init_fun_tab(Funs, dict:new(), TreeMap, Callgraph, Plt), + ExportedFuns = + [Fun || Fun <- Funs--[top], dialyzer_callgraph:is_escaping(Fun, Callgraph)], + Work = init_work(ExportedFuns), + Env = lists:foldl(fun(Fun, Env) -> dict:store(Fun, map__new(), Env) end, + dict:new(), Funs), + #state{callgraph = Callgraph, codeserver = Codeserver, + envs = Env, fun_tab = FunTab, fun_homes = FunHomes, opaques = Opaques, + plt = Plt, races = dialyzer_races:new(), records = Records, + warning_mode = false, warnings = [], work = Work, tree_map = TreeMap, + module = Module}. + +state__warning_mode(#state{warning_mode = WM}) -> + WM. + +state__set_warning_mode(#state{tree_map = TreeMap, fun_tab = FunTab, + races = Races} = State) -> + ?debug("==========\nStarting warning pass\n==========\n", []), + Funs = dict:fetch_keys(TreeMap), + State#state{work = init_work([top|Funs--[top]]), + fun_tab = FunTab, warning_mode = true, + races = dialyzer_races:put_race_analysis(true, Races)}. + +state__race_analysis(Analysis, #state{races = Races} = State) -> + State#state{races = dialyzer_races:put_race_analysis(Analysis, Races)}. + +state__renew_curr_fun(CurrFun, CurrFunLabel, + #state{races = Races} = State) -> + State#state{races = dialyzer_races:put_curr_fun(CurrFun, CurrFunLabel, + Races)}. + +state__renew_fun_args(Args, #state{races = Races} = State) -> + case state__warning_mode(State) of + true -> State; + false -> + State#state{races = dialyzer_races:put_fun_args(Args, Races)} + end. + +state__renew_race_list(RaceList, RaceListSize, + #state{races = Races} = State) -> + State#state{races = dialyzer_races:put_race_list(RaceList, RaceListSize, + Races)}. + +state__renew_warnings(Warnings, State) -> + State#state{warnings = Warnings}. + +-spec state__add_warning(raw_warning(), state()) -> state(). + +state__add_warning(Warn, #state{warnings = Warnings} = State) -> + State#state{warnings = [Warn|Warnings]}. + +state__add_warning(State, Tag, Tree, Msg) -> + state__add_warning(State, Tag, Tree, Msg, false). + +state__add_warning(#state{warning_mode = false} = State, _, _, _, _) -> + State; +state__add_warning(#state{warnings = Warnings, warning_mode = true} = State, + Tag, Tree, Msg, Force) -> + Ann = cerl:get_ann(Tree), + case Force of + true -> + WarningInfo = {get_file(Ann), + abs(get_line(Ann)), + State#state.curr_fun}, + Warn = {Tag, WarningInfo, Msg}, + ?debug("MSG ~s\n", [dialyzer:format_warning(Warn)]), + State#state{warnings = [Warn|Warnings]}; + false -> + case is_compiler_generated(Ann) of + true -> State; + false -> + WarningInfo = {get_file(Ann), get_line(Ann), State#state.curr_fun}, + Warn = {Tag, WarningInfo, Msg}, + case Tag of + ?WARN_CONTRACT_RANGE -> ok; + _ -> ?debug("MSG ~s\n", [dialyzer:format_warning(Warn)]) + end, + State#state{warnings = [Warn|Warnings]} + end + end. + +state__remove_added_warnings(OldState, NewState) -> + #state{warnings = OldWarnings} = OldState, + #state{warnings = NewWarnings} = NewState, + {NewWarnings -- OldWarnings, NewState#state{warnings = OldWarnings}}. + +state__add_warnings(Warns, #state{warnings = Warnings} = State) -> + State#state{warnings = Warns ++ Warnings}. + +-spec state__set_curr_fun(curr_fun(), state()) -> state(). + +state__set_curr_fun(undefined, State) -> + State#state{curr_fun = undefined}; +state__set_curr_fun(FunLbl, State) -> + State#state{curr_fun = find_function(FunLbl, State)}. + +-spec state__find_function(mfa_or_funlbl(), state()) -> mfa_or_funlbl(). + +state__find_function(FunLbl, State) -> + find_function(FunLbl, State). + +state__get_race_warnings(#state{races = Races} = State) -> + {Races1, State1} = dialyzer_races:get_race_warnings(Races, State), + State1#state{races = Races1}. + +state__get_warnings(#state{tree_map = TreeMap, fun_tab = FunTab, + callgraph = Callgraph, plt = Plt} = State) -> + FoldFun = + fun({top, _}, AccState) -> AccState; + ({FunLbl, Fun}, AccState) -> + AccState1 = state__set_curr_fun(FunLbl, AccState), + {NotCalled, Ret} = + case dict:fetch(get_label(Fun), FunTab) of + {not_handled, {_Args0, Ret0}} -> {true, Ret0}; + {_Args0, Ret0} -> {false, Ret0} + end, + case NotCalled of + true -> + case dialyzer_callgraph:lookup_name(FunLbl, Callgraph) of + error -> AccState1; + {ok, {_M, F, A}} -> + Msg = {unused_fun, [F, A]}, + state__add_warning(AccState1, ?WARN_NOT_CALLED, Fun, Msg) + end; + false -> + {Name, Contract} = + case dialyzer_callgraph:lookup_name(FunLbl, Callgraph) of + error -> {[], none}; + {ok, {_M, F, A} = MFA} -> + {[F, A], dialyzer_plt:lookup_contract(Plt, MFA)} + end, + case t_is_none(Ret) of + true -> + %% Check if the function has a contract that allows this. + Warn = + case Contract of + none -> not parent_allows_this(FunLbl, AccState1); + {value, C} -> + GenRet = dialyzer_contracts:get_contract_return(C), + not t_is_unit(GenRet) + end, + case Warn of + true -> + case classify_returns(Fun) of + no_match -> + Msg = {no_return, [no_match|Name]}, + state__add_warning(AccState1, ?WARN_RETURN_NO_RETURN, + Fun, Msg); + only_explicit -> + Msg = {no_return, [only_explicit|Name]}, + state__add_warning(AccState1, ?WARN_RETURN_ONLY_EXIT, + Fun, Msg); + only_normal -> + Msg = {no_return, [only_normal|Name]}, + state__add_warning(AccState1, ?WARN_RETURN_NO_RETURN, + Fun, Msg); + both -> + Msg = {no_return, [both|Name]}, + state__add_warning(AccState1, ?WARN_RETURN_NO_RETURN, + Fun, Msg) + end; + false -> + AccState + end; + false -> + AccState + end + end + end, + #state{warnings = Warn} = lists:foldl(FoldFun, State, dict:to_list(TreeMap)), + Warn. + +state__is_escaping(Fun, #state{callgraph = Callgraph}) -> + dialyzer_callgraph:is_escaping(Fun, Callgraph). + +state__lookup_type_for_letrec(Var, #state{callgraph = Callgraph} = State) -> + Label = get_label(Var), + case dialyzer_callgraph:lookup_letrec(Label, Callgraph) of + error -> error; + {ok, FunLabel} -> + {ok, state__fun_type(FunLabel, State)} + end. + +state__lookup_name({_, _, _} = MFA, #state{}) -> + MFA; +state__lookup_name(top, #state{}) -> + top; +state__lookup_name(Fun, #state{callgraph = Callgraph}) -> + case dialyzer_callgraph:lookup_name(Fun, Callgraph) of + {ok, MFA} -> MFA; + error -> Fun + end. + +state__lookup_record(Tag, Arity, #state{records = Records}) -> + case erl_types:lookup_record(Tag, Arity, Records) of + {ok, Fields} -> + RecType = + t_tuple([t_atom(Tag)| + [FieldType || {_FieldName, _Abstr, FieldType} <- Fields]]), + {ok, RecType}; + error -> + error + end. + +state__get_args_and_status(Tree, #state{fun_tab = FunTab}) -> + Fun = get_label(Tree), + case dict:find(Fun, FunTab) of + {ok, {not_handled, {ArgTypes, _}}} -> {ArgTypes, false}; + {ok, {ArgTypes, _}} -> {ArgTypes, true} + end. + +build_tree_map(Tree, Callgraph) -> + Fun = + fun(T, {Dict, Homes, FunLbls} = Acc) -> + case cerl:is_c_fun(T) of + true -> + FunLbl = get_label(T), + Dict1 = dict:store(FunLbl, T, Dict), + case catch dialyzer_callgraph:lookup_name(FunLbl, Callgraph) of + {ok, MFA} -> + F2 = + fun(Lbl, Dict0) -> + dict:store(Lbl, MFA, Dict0) + end, + Homes1 = lists:foldl(F2, Homes, [FunLbl|FunLbls]), + {Dict1, Homes1, []}; + _ -> + {Dict1, Homes, [FunLbl|FunLbls]} + end; + false -> + Acc + end + end, + Dict0 = dict:new(), + {Dict, Homes, _} = cerl_trees:fold(Fun, {Dict0, Dict0, []}, Tree), + {Dict, Homes}. + +init_fun_tab([top|Left], Dict, TreeMap, Callgraph, Plt) -> + NewDict = dict:store(top, {[], t_none()}, Dict), + init_fun_tab(Left, NewDict, TreeMap, Callgraph, Plt); +init_fun_tab([Fun|Left], Dict, TreeMap, Callgraph, Plt) -> + Arity = cerl:fun_arity(dict:fetch(Fun, TreeMap)), + FunEntry = + case dialyzer_callgraph:is_escaping(Fun, Callgraph) of + true -> + Args = lists:duplicate(Arity, t_any()), + case lookup_fun_sig(Fun, Callgraph, Plt) of + none -> {Args, t_unit()}; + {value, {RetType, _}} -> + case t_is_none(RetType) of + true -> {Args, t_none()}; + false -> {Args, t_unit()} + end + end; + false -> {not_handled, {lists:duplicate(Arity, t_none()), t_unit()}} + end, + NewDict = dict:store(Fun, FunEntry, Dict), + init_fun_tab(Left, NewDict, TreeMap, Callgraph, Plt); +init_fun_tab([], Dict, _TreeMap, _Callgraph, _Plt) -> + ?debug("DICT:~p\n",[dict:to_list(Dict)]), + Dict. + +state__update_fun_env(Tree, Map, #state{envs = Envs} = State) -> + NewEnvs = dict:store(get_label(Tree), Map, Envs), + State#state{envs = NewEnvs}. + +state__fun_env(Tree, #state{envs = Envs}) -> + Fun = get_label(Tree), + case dict:find(Fun, Envs) of + error -> none; + {ok, Map} -> Map + end. + +state__clean_not_called(#state{fun_tab = FunTab} = State) -> + NewFunTab = + dict:map(fun(top, Entry) -> Entry; + (_Fun, {not_handled, {Args, _}}) -> {Args, t_none()}; + (_Fun, Entry) -> Entry + end, FunTab), + State#state{fun_tab = NewFunTab}. + +state__all_fun_types(State) -> + #state{fun_tab = FunTab} = state__clean_not_called(State), + Tab1 = dict:erase(top, FunTab), + dict:map(fun(_Fun, {Args, Ret}) -> t_fun(Args, Ret)end, Tab1). + +state__fun_type(Fun, #state{fun_tab = FunTab}) -> + Label = + if is_integer(Fun) -> Fun; + true -> get_label(Fun) + end, + Entry = dict:find(Label, FunTab), + ?debug("FunType ~p:~p\n",[Label, Entry]), + case Entry of + {ok, {not_handled, {A, R}}} -> + t_fun(A, R); + {ok, {A, R}} -> + t_fun(A, R) + end. + +state__update_fun_entry(Tree, ArgTypes, Out0, + #state{fun_tab=FunTab, callgraph=CG, plt=Plt} = State)-> + Fun = get_label(Tree), + Out1 = + if Fun =:= top -> Out0; + true -> + case lookup_fun_sig(Fun, CG, Plt) of + {value, {SigRet, _}} -> t_inf(SigRet, Out0); + none -> Out0 + end + end, + Out = t_limit(Out1, ?TYPE_LIMIT), + {ok, {OldArgTypes, OldOut}} = dict:find(Fun, FunTab), + SameArgs = lists:all(fun({A, B}) -> erl_types:t_is_equal(A, B) + end, lists:zip(OldArgTypes, ArgTypes)), + SameOut = t_is_equal(OldOut, Out), + if + SameArgs, SameOut -> + ?debug("Fixpoint for ~w: ~s\n", + [state__lookup_name(Fun, State), + t_to_string(t_fun(ArgTypes, Out))]), + State; + true -> + %% Can only happen in self-recursive functions. + NewEntry = {OldArgTypes, Out}, + ?debug("New Entry for ~w: ~s\n", + [state__lookup_name(Fun, State), + t_to_string(t_fun(OldArgTypes, Out))]), + NewFunTab = dict:store(Fun, NewEntry, FunTab), + State1 = State#state{fun_tab = NewFunTab}, + state__add_work_from_fun(Tree, State1) + end. + +state__add_work_from_fun(_Tree, #state{warning_mode = true} = State) -> + State; +state__add_work_from_fun(Tree, #state{callgraph = Callgraph, + tree_map = TreeMap} = State) -> + case get_label(Tree) of + top -> State; + Label when is_integer(Label) -> + case dialyzer_callgraph:in_neighbours(Label, Callgraph) of + none -> State; + MFAList -> + LabelList = [dialyzer_callgraph:lookup_label(MFA, Callgraph) + || MFA <- MFAList], + %% Must filter the result for results in this module. + FilteredList = [L || {ok, L} <- LabelList, dict:is_key(L, TreeMap)], + ?debug("~w: Will try to add:~w\n", + [state__lookup_name(Label, State), MFAList]), + lists:foldl(fun(L, AccState) -> + state__add_work(L, AccState) + end, State, FilteredList) + end + end. + +state__add_work(external, State) -> + State; +state__add_work(top, State) -> + State; +state__add_work(Fun, #state{work = Work} = State) -> + NewWork = add_work(Fun, Work), + State#state{work = NewWork}. + +state__get_work(#state{work = Work, tree_map = TreeMap} = State) -> + case get_work(Work) of + none -> none; + {Fun, NewWork} -> + {dict:fetch(Fun, TreeMap), State#state{work = NewWork}} + end. + +state__lookup_call_site(Tree, #state{callgraph = Callgraph}) -> + Label = get_label(Tree), + dialyzer_callgraph:lookup_call_site(Label, Callgraph). + +state__fun_info(external, #state{}) -> + external; +state__fun_info({_, _, _} = MFA, #state{plt = PLT}) -> + {MFA, + dialyzer_plt:lookup(PLT, MFA), + dialyzer_plt:lookup_contract(PLT, MFA), + t_any()}; +state__fun_info(Fun, #state{callgraph = CG, fun_tab = FunTab, plt = PLT}) -> + {Sig, Contract} = + case dialyzer_callgraph:lookup_name(Fun, CG) of + error -> + {dialyzer_plt:lookup(PLT, Fun), none}; + {ok, MFA} -> + {dialyzer_plt:lookup(PLT, MFA), dialyzer_plt:lookup_contract(PLT, MFA)} + end, + LocalRet = + case dict:fetch(Fun, FunTab) of + {not_handled, {_Args, Ret}} -> Ret; + {_Args, Ret} -> Ret + end, + ?debug("LocalRet: ~s\n", [t_to_string(LocalRet)]), + {Fun, Sig, Contract, LocalRet}. + +forward_args(Fun, ArgTypes, #state{work = Work, fun_tab = FunTab} = State) -> + {OldArgTypes, OldOut, Fixpoint} = + case dict:find(Fun, FunTab) of + {ok, {not_handled, {OldArgTypes0, OldOut0}}} -> + {OldArgTypes0, OldOut0, false}; + {ok, {OldArgTypes0, OldOut0}} -> + {OldArgTypes0, OldOut0, + t_is_subtype(t_product(ArgTypes), t_product(OldArgTypes0))} + end, + case Fixpoint of + true -> State; + false -> + NewArgTypes = [t_sup(X, Y) || + {X, Y} <- lists:zip(ArgTypes, OldArgTypes)], + NewWork = add_work(Fun, Work), + ?debug("~w: forwarding args ~s\n", + [state__lookup_name(Fun, State), + t_to_string(t_product(NewArgTypes))]), + NewFunTab = dict:store(Fun, {NewArgTypes, OldOut}, FunTab), + State#state{work = NewWork, fun_tab = NewFunTab} + end. + +-spec state__cleanup(state()) -> state(). + +state__cleanup(#state{callgraph = Callgraph, + races = Races, + records = Records}) -> + #state{callgraph = dialyzer_callgraph:cleanup(Callgraph), + races = dialyzer_races:cleanup(Races), + records = Records}. + +-spec state__duplicate(state()) -> state(). + +state__duplicate(#state{callgraph = Callgraph} = State) -> + State#state{callgraph = dialyzer_callgraph:duplicate(Callgraph)}. + +-spec dispose_state(state()) -> ok. + +dispose_state(#state{callgraph = Callgraph}) -> + dialyzer_callgraph:dispose_race_server(Callgraph). + +-spec state__get_callgraph(state()) -> dialyzer_callgraph:callgraph(). + +state__get_callgraph(#state{callgraph = Callgraph}) -> + Callgraph. + +-spec state__get_races(state()) -> dialyzer_races:races(). + +state__get_races(#state{races = Races}) -> + Races. + +-spec state__get_records(state()) -> types(). + +state__get_records(#state{records = Records}) -> + Records. + +-spec state__put_callgraph(dialyzer_callgraph:callgraph(), state()) -> + state(). + +state__put_callgraph(Callgraph, State) -> + State#state{callgraph = Callgraph}. + +-spec state__put_races(dialyzer_races:races(), state()) -> state(). + +state__put_races(Races, State) -> + State#state{races = Races}. + +-spec state__records_only(state()) -> state(). + +state__records_only(#state{records = Records}) -> + #state{records = Records}. + +%%% =========================================================================== +%%% +%%% Races +%%% +%%% =========================================================================== + +is_race_analysis_enabled(#state{races = Races, callgraph = Callgraph}) -> + RaceDetection = dialyzer_callgraph:get_race_detection(Callgraph), + RaceAnalysis = dialyzer_races:get_race_analysis(Races), + RaceDetection andalso RaceAnalysis. + +get_race_list_and_size(#state{races = Races}) -> + dialyzer_races:get_race_list_and_size(Races). + +renew_race_code(#state{races = Races, callgraph = Callgraph, + warning_mode = WarningMode} = State) -> + case WarningMode of + true -> State; + false -> + NewCallgraph = dialyzer_callgraph:renew_race_code(Races, Callgraph), + State#state{callgraph = NewCallgraph} + end. + +renew_race_public_tables([Var], #state{races = Races, callgraph = Callgraph, + warning_mode = WarningMode} = State) -> + case WarningMode of + true -> State; + false -> + Table = dialyzer_races:get_new_table(Races), + case Table of + no_t -> State; + _Other -> + VarLabel = get_label(Var), + NewCallgraph = + dialyzer_callgraph:renew_race_public_tables(VarLabel, Callgraph), + State#state{callgraph = NewCallgraph} + end + end. + +%%% =========================================================================== +%%% +%%% Worklist +%%% +%%% =========================================================================== + +init_work(List) -> + {List, [], sets:from_list(List)}. + +get_work({[], [], _Set}) -> + none; +get_work({[H|T], Rev, Set}) -> + {H, {T, Rev, sets:del_element(H, Set)}}; +get_work({[], Rev, Set}) -> + get_work({lists:reverse(Rev), [], Set}). + +add_work(New, {List, Rev, Set} = Work) -> + case sets:is_element(New, Set) of + true -> Work; + false -> {List, [New|Rev], sets:add_element(New, Set)} + end. + +%%% =========================================================================== +%%% +%%% Utilities. +%%% +%%% =========================================================================== + +get_line([Line|_]) when is_integer(Line) -> Line; +get_line([_|Tail]) -> get_line(Tail); +get_line([]) -> -1. + +get_file([]) -> []; +get_file([{file, File}|_]) -> File; +get_file([_|Tail]) -> get_file(Tail). + +is_compiler_generated(Ann) -> + lists:member(compiler_generated, Ann) orelse (get_line(Ann) < 1). + +is_literal_record(Tree) -> + Ann = cerl:get_ann(Tree), + lists:member(record, Ann). + +-spec format_args([cerl:cerl()], [type()], state()) -> + nonempty_string(). + +format_args([], [], _State) -> + "()"; +format_args(ArgList0, TypeList, State) -> + ArgList = fold_literals(ArgList0), + "(" ++ format_args_1(ArgList, TypeList, State) ++ ")". + +format_args_1([Arg], [Type], State) -> + format_arg(Arg) ++ format_type(Type, State); +format_args_1([Arg|Args], [Type|Types], State) -> + String = + case cerl:is_literal(Arg) of + true -> format_cerl(Arg); + false -> format_arg(Arg) ++ format_type(Type, State) + end, + String ++ "," ++ format_args_1(Args, Types, State). + +format_arg(Arg) -> + Default = "", + case cerl:is_c_var(Arg) of + true -> + case cerl:var_name(Arg) of + Atom when is_atom(Atom) -> + case atom_to_list(Atom) of + "cor"++_ -> Default; + "rec"++_ -> Default; + Name -> Name ++ "::" + end; + _What -> Default + end; + false -> + Default + end. + +-spec format_type(type(), state()) -> string(). + +format_type(Type, #state{records = R}) -> + t_to_string(Type, R). + +-spec format_field_diffs(type(), state()) -> string(). + +format_field_diffs(RecConstruction, #state{records = R}) -> + erl_types:record_field_diffs_to_string(RecConstruction, R). + +-spec format_sig_args(type(), state()) -> string(). + +format_sig_args(Type, #state{opaques = Opaques} = State) -> + SigArgs = t_fun_args(Type, Opaques), + case SigArgs of + [] -> "()"; + [SArg|SArgs] -> + lists:flatten("(" ++ format_type(SArg, State) + ++ ["," ++ format_type(T, State) || T <- SArgs] ++ ")") + end. + +format_cerl(Tree) -> + cerl_prettypr:format(cerl:set_ann(Tree, []), + [{hook, dialyzer_utils:pp_hook()}, + {noann, true}, + {paper, 100000}, %% These guys strip + {ribbon, 100000} %% newlines. + ]). + +format_patterns(Pats0) -> + Pats = fold_literals(Pats0), + NewPats = map_pats(cerl:c_values(Pats)), + String = format_cerl(NewPats), + case Pats of + [PosVar] -> + case cerl:is_c_var(PosVar) andalso (cerl:var_name(PosVar) =/= '') of + true -> "variable "++String; + false -> "pattern "++String + end; + _ -> + "pattern "++String + end. + +map_pats(Pats) -> + Fun = fun(Tree) -> + case cerl:is_c_var(Tree) of + true -> + case cerl:var_name(Tree) of + Atom when is_atom(Atom) -> + case atom_to_list(Atom) of + "cor"++_ -> cerl:c_var(''); + "rec"++_ -> cerl:c_var(''); + _ -> cerl:set_ann(Tree, []) + end; + _What -> cerl:c_var('') + end; + false -> + cerl:set_ann(Tree, []) + end + end, + cerl_trees:map(Fun, Pats). + +fold_literals(TreeList) -> + [cerl:fold_literal(Tree) || Tree <- TreeList]. + +type(Tree) -> + Folded = cerl:fold_literal(Tree), + case cerl:type(Folded) of + literal -> {literal, Folded}; + Type -> Type + end. + +is_literal(Tree) -> + Folded = cerl:fold_literal(Tree), + case cerl:is_literal(Folded) of + true -> {yes, Folded}; + false -> no + end. + +parent_allows_this(FunLbl, #state{callgraph = Callgraph, plt = Plt} =State) -> + case state__is_escaping(FunLbl, State) of + false -> false; % if it isn't escaping it can't be a return value + true -> + case state__lookup_name(FunLbl, State) of + {_M, _F, _A} -> false; % if it has a name it is not a fun + _ -> + case dialyzer_callgraph:in_neighbours(FunLbl, Callgraph) of + [Parent] -> + case state__lookup_name(Parent, State) of + {_M, _F, _A} = PMFA -> + case dialyzer_plt:lookup_contract(Plt, PMFA) of + none -> false; + {value, C} -> + GenRet = dialyzer_contracts:get_contract_return(C), + case erl_types:t_is_fun(GenRet) of + false -> false; % element of structure? far-fetched... + true -> t_is_unit(t_fun_range(GenRet)) + end + end; + _ -> false % parent should have a name to have a contract + end; + _ -> false % called in other funs? far-fetched... + end + end + end. + +find_function({_, _, _} = MFA, _State) -> + MFA; +find_function(top, _State) -> + top; +find_function(FunLbl, #state{fun_homes = Homes}) -> + dict:fetch(FunLbl, Homes). + +classify_returns(Tree) -> + case find_terminals(cerl:fun_body(Tree)) of + {false, false} -> no_match; + {true, false} -> only_explicit; + {false, true} -> only_normal; + {true, true} -> both + end. + +find_terminals(Tree) -> + case cerl:type(Tree) of + apply -> {false, true}; + binary -> {false, true}; + bitstr -> {false, true}; + call -> + M0 = cerl:call_module(Tree), + F0 = cerl:call_name(Tree), + A = length(cerl:call_args(Tree)), + case {is_literal(M0), is_literal(F0)} of + {{yes, LitM}, {yes, LitF}} -> + M = cerl:concrete(LitM), + F = cerl:concrete(LitF), + case (erl_bif_types:is_known(M, F, A) + andalso t_is_none(erl_bif_types:type(M, F, A))) of + true -> {true, false}; + false -> {false, true} + end; + _ -> + %% We cannot make assumptions. Say that both are true. + {true, true} + end; + 'case' -> find_terminals_list(cerl:case_clauses(Tree)); + 'catch' -> find_terminals(cerl:catch_body(Tree)); + clause -> find_terminals(cerl:clause_body(Tree)); + cons -> {false, true}; + 'fun' -> {false, true}; + 'let' -> find_terminals(cerl:let_body(Tree)); + letrec -> find_terminals(cerl:letrec_body(Tree)); + literal -> {false, true}; + map -> {false, true}; + primop -> {false, false}; %% match_fail, etc. are not explicit exits. + 'receive' -> + Timeout = cerl:receive_timeout(Tree), + Clauses = cerl:receive_clauses(Tree), + case (cerl:is_literal(Timeout) andalso + (cerl:concrete(Timeout) =:= infinity)) of + true -> + if Clauses =:= [] -> {false, true}; %% A never ending receive. + true -> find_terminals_list(Clauses) + end; + false -> find_terminals_list([cerl:receive_action(Tree)|Clauses]) + end; + seq -> find_terminals(cerl:seq_body(Tree)); + 'try' -> + find_terminals_list([cerl:try_handler(Tree), cerl:try_body(Tree)]); + tuple -> {false, true}; + values -> {false, true}; + var -> {false, true} + end. + +find_terminals_list(List) -> + find_terminals_list(List, false, false). + +find_terminals_list([Tree|Left], Explicit1, Normal1) -> + {Explicit2, Normal2} = find_terminals(Tree), + case {Explicit1 or Explicit2, Normal1 or Normal2} of + {true, true} = Ans -> Ans; + {NewExplicit, NewNormal} -> + find_terminals_list(Left, NewExplicit, NewNormal) + end; +find_terminals_list([], Explicit, Normal) -> + {Explicit, Normal}. + +%%---------------------------------------------------------------------------- + +-ifdef(DEBUG_PP). +debug_pp(Tree, true) -> + io:put_chars(cerl_prettypr:format(Tree, [{hook, cerl_typean:pp_hook()}])), + io:nl(), + ok; +debug_pp(Tree, false) -> + io:put_chars(cerl_prettypr:format(strip_annotations(Tree))), + io:nl(), + ok. + +strip_annotations(Tree) -> + Fun = fun(T) -> + case cerl:type(T) of + var -> + cerl:set_ann(T, [{label, cerl_trees:get_label(T)}]); + 'fun' -> + cerl:set_ann(T, [{label, cerl_trees:get_label(T)}]); + _ -> + cerl:set_ann(T, []) + end + end, + cerl_trees:map(Fun, Tree). + +-else. + +debug_pp(_Tree, _UseHook) -> + ok. +-endif. diff --git a/lib/dialyzer/test/opaque_SUITE_data/src/recrec/dialyzer_races.erl b/lib/dialyzer/test/opaque_SUITE_data/src/recrec/dialyzer_races.erl new file mode 100644 index 0000000000..bb43d1dcb8 --- /dev/null +++ b/lib/dialyzer/test/opaque_SUITE_data/src/recrec/dialyzer_races.erl @@ -0,0 +1,2494 @@ +%% -*- erlang-indent-level: 2 -*- +%%----------------------------------------------------------------------- +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2008-2015. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% +%% + +%%%---------------------------------------------------------------------- +%%% File : dialyzer_races.erl +%%% Author : Maria Christakis <[email protected]> +%%% Description : Utility functions for race condition detection +%%% +%%% Created : 21 Nov 2008 by Maria Christakis <[email protected]> +%%%---------------------------------------------------------------------- +-module(dialyzer_races). + +%% Race Analysis + +-export([store_race_call/5, race/1, get_race_warnings/2, format_args/4]). + +%% Record Interfaces + +-export([beg_clause_new/3, cleanup/1, end_case_new/1, end_clause_new/3, + get_curr_fun/1, get_curr_fun_args/1, get_new_table/1, + get_race_analysis/1, get_race_list/1, get_race_list_size/1, + get_race_list_and_size/1, + let_tag_new/2, new/0, put_curr_fun/3, put_fun_args/2, + put_race_analysis/2, put_race_list/3]). + +-export_type([races/0, core_vars/0]). + +-include("dialyzer.hrl"). + +%%% =========================================================================== +%%% +%%% Definitions +%%% +%%% =========================================================================== + +-define(local, 5). +-define(no_arg, no_arg). +-define(no_label, no_label). +-define(bypassed, bypassed). + +-define(WARN_WHEREIS_REGISTER, warn_whereis_register). +-define(WARN_WHEREIS_UNREGISTER, warn_whereis_unregister). +-define(WARN_ETS_LOOKUP_INSERT, warn_ets_lookup_insert). +-define(WARN_MNESIA_DIRTY_READ_WRITE, warn_mnesia_dirty_read_write). +-define(WARN_NO_WARN, warn_no_warn). + +%%% =========================================================================== +%%% +%%% Local Types +%%% +%%% =========================================================================== + +-type label_type() :: label() | [label()] | {label()} | ?no_label. +-type args() :: [label_type() | [string()]]. +-type core_vars() :: cerl:cerl() | ?no_arg | ?bypassed. +-type var_to_map1() :: core_vars() | [cerl:cerl()]. +-type var_to_map2() :: cerl:cerl() | [cerl:cerl()] | ?bypassed. +-type core_args() :: [core_vars()] | 'empty'. +-type op() :: 'bind' | 'unbind'. + +-type dep_calls() :: 'whereis' | 'ets_lookup' | 'mnesia_dirty_read'. +-type warn_calls() :: 'register' | 'unregister' | 'ets_insert' + | 'mnesia_dirty_write'. +-type call() :: 'whereis' | 'register' | 'unregister' | 'ets_new' + | 'ets_lookup' | 'ets_insert' | 'mnesia_dirty_read1' + | 'mnesia_dirty_read2' | 'mnesia_dirty_write1' + | 'mnesia_dirty_write2' | 'function_call'. +-type race_tag() :: 'whereis_register' | 'whereis_unregister' + | 'ets_lookup_insert' | 'mnesia_dirty_read_write'. + +%% The following type is similar to the raw_warning() type but has a +%% tag which is local to this module and is not propagated to outside +-type dial_race_warning() :: {race_warn_tag(), warning_info(), {atom(), [term()]}}. +-type race_warn_tag() :: ?WARN_WHEREIS_REGISTER | ?WARN_WHEREIS_UNREGISTER + | ?WARN_ETS_LOOKUP_INSERT | ?WARN_MNESIA_DIRTY_READ_WRITE. + +-record(beg_clause, {arg :: var_to_map1() | 'undefined', + pats :: var_to_map1() | 'undefined', + guard :: cerl:cerl() | 'undefined'}). +-record(end_clause, {arg :: var_to_map1() | 'undefined', + pats :: var_to_map1() | 'undefined', + guard :: cerl:cerl() | 'undefined'}). +-record(end_case, {clauses :: [#end_clause{}]}). +-record(curr_fun, {status :: 'in' | 'out' | 'undefined', + mfa :: dialyzer_callgraph:mfa_or_funlbl() + | 'undefined', + label :: label() | 'undefined', + def_vars :: [core_vars()] | 'undefined', + arg_types :: [erl_types:erl_type()] | 'undefined', + call_vars :: [core_vars()] | 'undefined', + var_map :: dict:dict() | 'undefined'}). +-record(dep_call, {call_name :: dep_calls(), + args :: args() | 'undefined', + arg_types :: [erl_types:erl_type()], + vars :: [core_vars()], + state :: dialyzer_dataflow:state(), + file_line :: file_line(), + var_map :: dict:dict() | 'undefined'}). +-record(fun_call, {caller :: dialyzer_callgraph:mfa_or_funlbl(), + callee :: dialyzer_callgraph:mfa_or_funlbl(), + arg_types :: [erl_types:erl_type()], + vars :: [core_vars()]}). +-record(let_tag, {var :: var_to_map1(), + arg :: var_to_map1()}). +-record(warn_call, {call_name :: warn_calls(), + args :: args(), + var_map :: dict:dict() | 'undefined'}). + +-type case_tags() :: 'beg_case' | #beg_clause{} | #end_clause{} | #end_case{}. +-type code() :: [#dep_call{} | #fun_call{} | #warn_call{} | + #curr_fun{} | #let_tag{} | case_tags() | race_tag()]. + +-type table_var() :: label() | ?no_label. +-type table() :: {'named', table_var(), [string()]} | 'other' | 'no_t'. + +-record(race_fun, {mfa :: mfa(), + args :: args(), + arg_types :: [erl_types:erl_type()], + vars :: [core_vars()], + file_line :: file_line(), + index :: non_neg_integer(), + fun_mfa :: dialyzer_callgraph:mfa_or_funlbl(), + fun_label :: label()}). + +-record(races, {curr_fun :: dialyzer_callgraph:mfa_or_funlbl() + | 'undefined', + curr_fun_label :: label() | 'undefined', + curr_fun_args = 'empty' :: core_args(), + new_table = 'no_t' :: table(), + race_list = [] :: code(), + race_list_size = 0 :: non_neg_integer(), + race_tags = [] :: [#race_fun{}], + %% true for fun types and warning mode + race_analysis = false :: boolean(), + race_warnings = [] :: [dial_race_warning()]}). + +%%% =========================================================================== +%%% +%%% Exported Types +%%% +%%% =========================================================================== + +-opaque races() :: #races{}. + +%%% =========================================================================== +%%% +%%% Race Analysis +%%% +%%% =========================================================================== + +-spec store_race_call(dialyzer_callgraph:mfa_or_funlbl(), + [erl_types:erl_type()], [core_vars()], + file_line(), dialyzer_dataflow:state()) -> + dialyzer_dataflow:state(). + +store_race_call(Fun, ArgTypes, Args, FileLine, State) -> + Races = dialyzer_dataflow:state__get_races(State), + CurrFun = Races#races.curr_fun, + CurrFunLabel = Races#races.curr_fun_label, + RaceTags = Races#races.race_tags, + CleanState = dialyzer_dataflow:state__records_only(State), + {NewRaceList, NewRaceListSize, NewRaceTags, NewTable} = + case CurrFun of + {_Module, module_info, A} when A =:= 0 orelse A =:= 1 -> + {[], 0, RaceTags, no_t}; + _Thing -> + RaceList = Races#races.race_list, + RaceListSize = Races#races.race_list_size, + case Fun of + {erlang, get_module_info, A} when A =:= 1 orelse A =:= 2 -> + {[], 0, RaceTags, no_t}; + {erlang, register, 2} -> + VarArgs = format_args(Args, ArgTypes, CleanState, register), + RaceFun = #race_fun{mfa = Fun, args = VarArgs, + arg_types = ArgTypes, vars = Args, + file_line = FileLine, index = RaceListSize, + fun_mfa = CurrFun, fun_label = CurrFunLabel}, + {[#warn_call{call_name = register, args = VarArgs}| + RaceList], RaceListSize + 1, [RaceFun|RaceTags], no_t}; + {erlang, unregister, 1} -> + VarArgs = format_args(Args, ArgTypes, CleanState, unregister), + RaceFun = #race_fun{mfa = Fun, args = VarArgs, + arg_types = ArgTypes, vars = Args, + file_line = FileLine, index = RaceListSize, + fun_mfa = CurrFun, fun_label = CurrFunLabel}, + {[#warn_call{call_name = unregister, args = VarArgs}| + RaceList], RaceListSize + 1, [RaceFun|RaceTags], no_t}; + {erlang, whereis, 1} -> + VarArgs = format_args(Args, ArgTypes, CleanState, whereis), + {[#dep_call{call_name = whereis, args = VarArgs, + arg_types = ArgTypes, vars = Args, + state = CleanState, file_line = FileLine}| + RaceList], RaceListSize + 1, RaceTags, no_t}; + {ets, insert, 2} -> + VarArgs = format_args(Args, ArgTypes, CleanState, ets_insert), + RaceFun = #race_fun{mfa = Fun, args = VarArgs, + arg_types = ArgTypes, vars = Args, + file_line = FileLine, index = RaceListSize, + fun_mfa = CurrFun, fun_label = CurrFunLabel}, + {[#warn_call{call_name = ets_insert, args = VarArgs}| + RaceList], RaceListSize + 1, [RaceFun|RaceTags], no_t}; + {ets, lookup, 2} -> + VarArgs = format_args(Args, ArgTypes, CleanState, ets_lookup), + {[#dep_call{call_name = ets_lookup, args = VarArgs, + arg_types = ArgTypes, vars = Args, + state = CleanState, file_line = FileLine}| + RaceList], RaceListSize + 1, RaceTags, no_t}; + {ets, new, 2} -> + VarArgs = format_args(Args, ArgTypes, CleanState, ets_new), + [VarArgs1, VarArgs2, _, Options] = VarArgs, + NewTable1 = + case lists:member("'public'", Options) of + true -> + case lists:member("'named_table'", Options) of + true -> + {named, VarArgs1, VarArgs2}; + false -> other + end; + false -> no_t + end, + {RaceList, RaceListSize, RaceTags, NewTable1}; + {mnesia, dirty_read, A} when A =:= 1 orelse A =:= 2 -> + VarArgs = + case A of + 1 -> + format_args(Args, ArgTypes, CleanState, mnesia_dirty_read1); + 2 -> + format_args(Args, ArgTypes, CleanState, mnesia_dirty_read2) + end, + {[#dep_call{call_name = mnesia_dirty_read, args = VarArgs, + arg_types = ArgTypes, vars = Args, + state = CleanState, file_line = FileLine}|RaceList], + RaceListSize + 1, RaceTags, no_t}; + {mnesia, dirty_write, A} when A =:= 1 orelse A =:= 2 -> + VarArgs = + case A of + 1 -> + format_args(Args, ArgTypes, CleanState, mnesia_dirty_write1); + 2 -> + format_args(Args, ArgTypes, CleanState, mnesia_dirty_write2) + end, + RaceFun = #race_fun{mfa = Fun, args = VarArgs, + arg_types = ArgTypes, vars = Args, + file_line = FileLine, index = RaceListSize, + fun_mfa = CurrFun, fun_label = CurrFunLabel}, + {[#warn_call{call_name = mnesia_dirty_write, + args = VarArgs}|RaceList], + RaceListSize + 1, [RaceFun|RaceTags], no_t}; + Int when is_integer(Int) -> + {[#fun_call{caller = CurrFun, callee = Int, arg_types = ArgTypes, + vars = Args}|RaceList], + RaceListSize + 1, RaceTags, no_t}; + _Other -> + Callgraph = dialyzer_dataflow:state__get_callgraph(State), + case digraph:vertex(dialyzer_callgraph:get_digraph(Callgraph), + Fun) of + {Fun, confirmed} -> + {[#fun_call{caller = CurrFun, callee = Fun, + arg_types = ArgTypes, vars = Args}|RaceList], + RaceListSize + 1, RaceTags, no_t}; + false -> + {RaceList, RaceListSize, RaceTags, no_t} + end + end + end, + state__renew_info(NewRaceList, NewRaceListSize, NewRaceTags, NewTable, State). + +-spec race(dialyzer_dataflow:state()) -> dialyzer_dataflow:state(). + +race(State) -> + Races = dialyzer_dataflow:state__get_races(State), + RaceTags = Races#races.race_tags, + RetState = + case RaceTags of + [] -> State; + [#race_fun{mfa = Fun, + args = VarArgs, arg_types = ArgTypes, + vars = Args, file_line = FileLine, + index = Index, fun_mfa = CurrFun, + fun_label = CurrFunLabel}|T] -> + Callgraph = dialyzer_dataflow:state__get_callgraph(State), + {ok, [_Args, Code]} = + dict:find(CurrFun, dialyzer_callgraph:get_race_code(Callgraph)), + RaceList = lists:reverse(Code), + RaceWarnTag = + case Fun of + {erlang, register, 2} -> ?WARN_WHEREIS_REGISTER; + {erlang, unregister, 1} -> ?WARN_WHEREIS_UNREGISTER; + {ets, insert, 2} -> ?WARN_ETS_LOOKUP_INSERT; + {mnesia, dirty_write, _A} -> ?WARN_MNESIA_DIRTY_READ_WRITE + end, + State1 = + state__renew_curr_fun(CurrFun, + state__renew_curr_fun_label(CurrFunLabel, + state__renew_race_list(lists:nthtail(length(RaceList) - Index, + RaceList), State))), + DepList = fixup_race_list(RaceWarnTag, VarArgs, State1), + {State2, RaceWarn} = + get_race_warn(Fun, Args, ArgTypes, DepList, State), + {File, Line} = FileLine, + CurrMFA = dialyzer_dataflow:state__find_function(CurrFun, State), + WarningInfo = {File, Line, CurrMFA}, + race( + state__add_race_warning( + state__renew_race_tags(T, State2), RaceWarn, RaceWarnTag, + WarningInfo)) + end, + state__renew_race_tags([], RetState). + +fixup_race_list(RaceWarnTag, WarnVarArgs, State) -> + Races = dialyzer_dataflow:state__get_races(State), + CurrFun = Races#races.curr_fun, + CurrFunLabel = Races#races.curr_fun_label, + RaceList = Races#races.race_list, + Callgraph = dialyzer_dataflow:state__get_callgraph(State), + Digraph = dialyzer_callgraph:get_digraph(Callgraph), + Calls = digraph:edges(Digraph), + RaceTag = + case RaceWarnTag of + ?WARN_WHEREIS_REGISTER -> whereis_register; + ?WARN_WHEREIS_UNREGISTER -> whereis_unregister; + ?WARN_ETS_LOOKUP_INSERT -> ets_lookup_insert; + ?WARN_MNESIA_DIRTY_READ_WRITE -> mnesia_dirty_read_write + end, + NewRaceList = [RaceTag|RaceList], + CleanState = dialyzer_dataflow:state__cleanup(State), + NewState = state__renew_race_list(NewRaceList, CleanState), + DepList1 = + fixup_race_forward_pullout(CurrFun, CurrFunLabel, Calls, + lists:reverse(NewRaceList), [], CurrFun, + WarnVarArgs, RaceWarnTag, dict:new(), + [], [], [], 2 * ?local, NewState), + Parents = fixup_race_backward(CurrFun, Calls, Calls, [], ?local), + UParents = lists:usort(Parents), + Filtered = filter_parents(UParents, UParents, Digraph), + NewParents = + case lists:member(CurrFun, Filtered) of + true -> Filtered; + false -> [CurrFun|Filtered] + end, + DepList2 = + fixup_race_list_helper(NewParents, Calls, CurrFun, WarnVarArgs, + RaceWarnTag, NewState), + dialyzer_dataflow:dispose_state(CleanState), + lists:usort(cleanup_dep_calls(DepList1 ++ DepList2)). + +fixup_race_list_helper(Parents, Calls, CurrFun, WarnVarArgs, RaceWarnTag, + State) -> + case Parents of + [] -> []; + [Head|Tail] -> + Callgraph = dialyzer_dataflow:state__get_callgraph(State), + Code = + case dict:find(Head, dialyzer_callgraph:get_race_code(Callgraph)) of + error -> []; + {ok, [_A, C]} -> C + end, + {ok, FunLabel} = dialyzer_callgraph:lookup_label(Head, Callgraph), + DepList1 = + fixup_race_forward_pullout(Head, FunLabel, Calls, Code, [], CurrFun, + WarnVarArgs, RaceWarnTag, dict:new(), + [], [], [], 2 * ?local, State), + DepList2 = + fixup_race_list_helper(Tail, Calls, CurrFun, WarnVarArgs, + RaceWarnTag, State), + DepList1 ++ DepList2 + end. + +%%% =========================================================================== +%%% +%%% Forward Analysis +%%% +%%% =========================================================================== + +fixup_race_forward_pullout(CurrFun, CurrFunLabel, Calls, Code, RaceList, + InitFun, WarnVarArgs, RaceWarnTag, RaceVarMap, + FunDefVars, FunCallVars, FunArgTypes, NestingLevel, + State) -> + TState = dialyzer_dataflow:state__duplicate(State), + {DepList, NewCurrFun, NewCurrFunLabel, NewCalls, + NewCode, NewRaceList, NewRaceVarMap, NewFunDefVars, + NewFunCallVars, NewFunArgTypes, NewNestingLevel} = + fixup_race_forward(CurrFun, CurrFunLabel, Calls, Code, RaceList, + InitFun, WarnVarArgs, RaceWarnTag, RaceVarMap, + FunDefVars, FunCallVars, FunArgTypes, NestingLevel, + cleanup_race_code(TState)), + dialyzer_dataflow:dispose_state(TState), + case NewCode of + [] -> DepList; + [#fun_call{caller = NewCurrFun, callee = Call, arg_types = FunTypes, + vars = FunArgs}|Tail] -> + Callgraph = dialyzer_dataflow:state__get_callgraph(State), + OkCall = {ok, Call}, + {Name, Label} = + case is_integer(Call) of + true -> + case dialyzer_callgraph:lookup_name(Call, Callgraph) of + error -> {OkCall, OkCall}; + N -> {N, OkCall} + end; + false -> + {OkCall, dialyzer_callgraph:lookup_label(Call, Callgraph)} + end, + {NewCurrFun1, NewCurrFunLabel1, NewCalls1, NewCode1, NewRaceList1, + NewRaceVarMap1, NewFunDefVars1, NewFunCallVars1, NewFunArgTypes1, + NewNestingLevel1} = + case Label =:= error of + true -> + {NewCurrFun, NewCurrFunLabel, NewCalls, Tail, NewRaceList, + NewRaceVarMap, NewFunDefVars, NewFunCallVars, NewFunArgTypes, + NewNestingLevel}; + false -> + {ok, Fun} = Name, + {ok, Int} = Label, + case dict:find(Fun, dialyzer_callgraph:get_race_code(Callgraph)) of + error -> + {NewCurrFun, NewCurrFunLabel, NewCalls, Tail, NewRaceList, + NewRaceVarMap, NewFunDefVars, NewFunCallVars, NewFunArgTypes, + NewNestingLevel}; + {ok, [Args, CodeB]} -> + Races = dialyzer_dataflow:state__get_races(State), + {RetCurrFun, RetCurrFunLabel, RetCalls, RetCode, + RetRaceList, RetRaceVarMap, RetFunDefVars, RetFunCallVars, + RetFunArgTypes, RetNestingLevel} = + fixup_race_forward_helper(NewCurrFun, + NewCurrFunLabel, Fun, Int, NewCalls, NewCalls, + [#curr_fun{status = out, mfa = NewCurrFun, + label = NewCurrFunLabel, + var_map = NewRaceVarMap, + def_vars = NewFunDefVars, + call_vars = NewFunCallVars, + arg_types = NewFunArgTypes}| + Tail], + NewRaceList, InitFun, FunArgs, FunTypes, RaceWarnTag, + NewRaceVarMap, NewFunDefVars, NewFunCallVars, + NewFunArgTypes, NewNestingLevel, Args, CodeB, + Races#races.race_list), + case RetCode of + [#curr_fun{}|_CodeTail] -> + {NewCurrFun, NewCurrFunLabel, RetCalls, RetCode, + RetRaceList, NewRaceVarMap, NewFunDefVars, + NewFunCallVars, NewFunArgTypes, RetNestingLevel}; + _Else -> + {RetCurrFun, RetCurrFunLabel, RetCalls, RetCode, + RetRaceList, RetRaceVarMap, RetFunDefVars, + RetFunCallVars, RetFunArgTypes, RetNestingLevel} + end + end + end, + DepList ++ + fixup_race_forward_pullout(NewCurrFun1, NewCurrFunLabel1, NewCalls1, + NewCode1, NewRaceList1, InitFun, WarnVarArgs, + RaceWarnTag, NewRaceVarMap1, NewFunDefVars1, + NewFunCallVars1, NewFunArgTypes1, + NewNestingLevel1, State) + end. + +fixup_race_forward(CurrFun, CurrFunLabel, Calls, Code, RaceList, + InitFun, WarnVarArgs, RaceWarnTag, RaceVarMap, + FunDefVars, FunCallVars, FunArgTypes, NestingLevel, + State) -> + case Code of + [] -> + {[], CurrFun, CurrFunLabel, Calls, Code, RaceList, RaceVarMap, + FunDefVars, FunCallVars, FunArgTypes, NestingLevel}; + [Head|Tail] -> + Callgraph = dialyzer_dataflow:state__get_callgraph(State), + {NewRL, DepList, NewNL, Return} = + case Head of + #dep_call{call_name = whereis} -> + case RaceWarnTag of + WarnWhereis when WarnWhereis =:= ?WARN_WHEREIS_REGISTER orelse + WarnWhereis =:= ?WARN_WHEREIS_UNREGISTER -> + {[Head#dep_call{var_map = RaceVarMap}|RaceList], + [], NestingLevel, false}; + _Other -> + {RaceList, [], NestingLevel, false} + end; + #dep_call{call_name = ets_lookup} -> + case RaceWarnTag of + ?WARN_ETS_LOOKUP_INSERT -> + {[Head#dep_call{var_map = RaceVarMap}|RaceList], + [], NestingLevel, false}; + _Other -> + {RaceList, [], NestingLevel, false} + end; + #dep_call{call_name = mnesia_dirty_read} -> + case RaceWarnTag of + ?WARN_MNESIA_DIRTY_READ_WRITE -> + {[Head#dep_call{var_map = RaceVarMap}|RaceList], + [], NestingLevel, false}; + _Other -> + {RaceList, [], NestingLevel, false} + end; + #warn_call{call_name = RegCall} when RegCall =:= register orelse + RegCall =:= unregister -> + case RaceWarnTag of + WarnWhereis when WarnWhereis =:= ?WARN_WHEREIS_REGISTER orelse + WarnWhereis =:= ?WARN_WHEREIS_UNREGISTER -> + {[Head#warn_call{var_map = RaceVarMap}|RaceList], + [], NestingLevel, false}; + _Other -> + {RaceList, [], NestingLevel, false} + end; + #warn_call{call_name = ets_insert} -> + case RaceWarnTag of + ?WARN_ETS_LOOKUP_INSERT -> + {[Head#warn_call{var_map = RaceVarMap}|RaceList], + [], NestingLevel, false}; + _Other -> + {RaceList, [], NestingLevel, false} + end; + #warn_call{call_name = mnesia_dirty_write} -> + case RaceWarnTag of + ?WARN_MNESIA_DIRTY_READ_WRITE -> + {[Head#warn_call{var_map = RaceVarMap}|RaceList], + [], NestingLevel, false}; + _Other -> + {RaceList, [], NestingLevel, false} + end; + #fun_call{caller = CurrFun, callee = InitFun} -> + {RaceList, [], NestingLevel, false}; + #fun_call{caller = CurrFun} -> + {RaceList, [], NestingLevel - 1, false}; + beg_case -> + {[Head|RaceList], [], NestingLevel, false}; + #beg_clause{} -> + {[#beg_clause{}|RaceList], [], NestingLevel, false}; + #end_clause{} -> + {[#end_clause{}|RaceList], [], NestingLevel, false}; + #end_case{} -> + {[Head|RaceList], [], NestingLevel, false}; + #let_tag{} -> + {RaceList, [], NestingLevel, false}; + #curr_fun{status = in, mfa = InitFun, + label = _InitFunLabel, var_map = _NewRVM, + def_vars = NewFDV, call_vars = NewFCV, + arg_types = _NewFAT} -> + {[#curr_fun{status = out, var_map = RaceVarMap, + def_vars = NewFDV, call_vars = NewFCV}| + RaceList], [], NestingLevel - 1, false}; + #curr_fun{status = in, def_vars = NewFDV, + call_vars = NewFCV} -> + {[#curr_fun{status = out, var_map = RaceVarMap, + def_vars = NewFDV, call_vars = NewFCV}| + RaceList], + [], NestingLevel - 1, false}; + #curr_fun{status = out} -> + {[#curr_fun{status = in, var_map = RaceVarMap}|RaceList], [], + NestingLevel + 1, false}; + RaceTag -> + PublicTables = dialyzer_callgraph:get_public_tables(Callgraph), + NamedTables = dialyzer_callgraph:get_named_tables(Callgraph), + WarnVarArgs1 = + var_type_analysis(FunDefVars, FunArgTypes, WarnVarArgs, + RaceWarnTag, RaceVarMap, + dialyzer_dataflow:state__records_only(State)), + {NewDepList, IsPublic, _Return} = + get_deplist_paths(RaceList, WarnVarArgs1, RaceWarnTag, + RaceVarMap, 0, PublicTables, NamedTables), + {NewHead, NewDepList1} = + case RaceTag of + whereis_register -> + {[#warn_call{call_name = register, args = WarnVarArgs, + var_map = RaceVarMap}], + NewDepList}; + whereis_unregister -> + {[#warn_call{call_name = unregister, args = WarnVarArgs, + var_map = RaceVarMap}], + NewDepList}; + ets_lookup_insert -> + NewWarnCall = + [#warn_call{call_name = ets_insert, args = WarnVarArgs, + var_map = RaceVarMap}], + [Tab, Names, _, _] = WarnVarArgs, + case IsPublic orelse + compare_var_list(Tab, PublicTables, RaceVarMap) + orelse + length(Names -- NamedTables) < length(Names) of + true -> + {NewWarnCall, NewDepList}; + false -> {NewWarnCall, []} + end; + mnesia_dirty_read_write -> + {[#warn_call{call_name = mnesia_dirty_write, + args = WarnVarArgs, var_map = RaceVarMap}], + NewDepList} + end, + {NewHead ++ RaceList, NewDepList1, NestingLevel, + is_last_race(RaceTag, InitFun, Tail, Callgraph)} + end, + {NewCurrFun, NewCurrFunLabel, NewCode, NewRaceList, NewRaceVarMap, + NewFunDefVars, NewFunCallVars, NewFunArgTypes, NewNestingLevel, + PullOut} = + case Head of + #fun_call{caller = CurrFun} -> + case NewNL =:= 0 of + true -> + {CurrFun, CurrFunLabel, Tail, NewRL, RaceVarMap, + FunDefVars, FunCallVars, FunArgTypes, NewNL, false}; + false -> + {CurrFun, CurrFunLabel, Code, NewRL, RaceVarMap, + FunDefVars, FunCallVars, FunArgTypes, NewNL, true} + end; + #beg_clause{arg = Arg, pats = Pats, guard = Guard} -> + {RaceVarMap1, RemoveClause} = + race_var_map_guard(Arg, Pats, Guard, RaceVarMap, bind), + case RemoveClause of + true -> + {RaceList2, + #curr_fun{mfa = CurrFun2, label = CurrFunLabel2, + var_map = RaceVarMap2, def_vars = FunDefVars2, + call_vars = FunCallVars2, arg_types = FunArgTypes2}, + Code2, NestingLevel2} = + remove_clause(NewRL, + #curr_fun{mfa = CurrFun, label = CurrFunLabel, + var_map = RaceVarMap1, + def_vars = FunDefVars, + call_vars = FunCallVars, + arg_types = FunArgTypes}, + Tail, NewNL), + {CurrFun2, CurrFunLabel2, Code2, RaceList2, + RaceVarMap2, FunDefVars2, FunCallVars2, FunArgTypes2, + NestingLevel2, false}; + false -> + {CurrFun, CurrFunLabel, Tail, NewRL, RaceVarMap1, + FunDefVars, FunCallVars, FunArgTypes, NewNL, false} + end; + #end_clause{arg = Arg, pats = Pats, guard = Guard} -> + {RaceVarMap1, _RemoveClause} = + race_var_map_guard(Arg, Pats, Guard, RaceVarMap, unbind), + {CurrFun, CurrFunLabel, Tail, NewRL, RaceVarMap1, + FunDefVars, FunCallVars, FunArgTypes, NewNL, + false}; + #end_case{clauses = Clauses} -> + RaceVarMap1 = + race_var_map_clauses(Clauses, RaceVarMap), + {CurrFun, CurrFunLabel, Tail, NewRL, RaceVarMap1, + FunDefVars, FunCallVars, FunArgTypes, NewNL, + false}; + #let_tag{var = Var, arg = Arg} -> + {CurrFun, CurrFunLabel, Tail, NewRL, + race_var_map(Var, Arg, RaceVarMap, bind), FunDefVars, + FunCallVars, FunArgTypes, NewNL, false}; + #curr_fun{mfa = CurrFun1, label = CurrFunLabel1, + var_map = RaceVarMap1, def_vars = FunDefVars1, + call_vars = FunCallVars1, arg_types = FunArgTypes1} -> + case NewNL =:= 0 of + true -> + {CurrFun, CurrFunLabel, + remove_nonlocal_functions(Tail, 1), NewRL, RaceVarMap, + FunDefVars, FunCallVars, FunArgTypes, NewNL, false}; + false -> + {CurrFun1, CurrFunLabel1, Tail, NewRL, RaceVarMap1, + FunDefVars1, FunCallVars1, FunArgTypes1, NewNL, false} + end; + _Thing -> + {CurrFun, CurrFunLabel, Tail, NewRL, RaceVarMap, + FunDefVars, FunCallVars, FunArgTypes, NewNL, false} + end, + case Return of + true -> + {DepList, NewCurrFun, NewCurrFunLabel, Calls, + [], NewRaceList, NewRaceVarMap, NewFunDefVars, + NewFunCallVars, NewFunArgTypes, NewNestingLevel}; + false -> + NewNestingLevel1 = + case NewNestingLevel =:= 0 of + true -> NewNestingLevel + 1; + false -> NewNestingLevel + end, + case PullOut of + true -> + {DepList, NewCurrFun, NewCurrFunLabel, Calls, + NewCode, NewRaceList, NewRaceVarMap, NewFunDefVars, + NewFunCallVars, NewFunArgTypes, NewNestingLevel1}; + false -> + {RetDepList, NewCurrFun1, NewCurrFunLabel1, NewCalls1, + NewCode1, NewRaceList1, NewRaceVarMap1, NewFunDefVars1, + NewFunCallVars1, NewFunArgTypes1, NewNestingLevel2} = + fixup_race_forward(NewCurrFun, NewCurrFunLabel, Calls, + NewCode, NewRaceList, InitFun, WarnVarArgs, + RaceWarnTag, NewRaceVarMap, NewFunDefVars, + NewFunCallVars, NewFunArgTypes, + NewNestingLevel1, State), + {DepList ++ RetDepList, NewCurrFun1, NewCurrFunLabel1, + NewCalls1, NewCode1, NewRaceList1, NewRaceVarMap1, + NewFunDefVars1, NewFunCallVars1, NewFunArgTypes1, + NewNestingLevel2} + end + end + end. + +get_deplist_paths(RaceList, WarnVarArgs, RaceWarnTag, RaceVarMap, CurrLevel, + PublicTables, NamedTables) -> + case RaceList of + [] -> {[], false, true}; + [Head|Tail] -> + case Head of + #end_case{} -> + {RaceList1, DepList1, IsPublic1, Continue1} = + handle_case(Tail, WarnVarArgs, RaceWarnTag, RaceVarMap, CurrLevel, + PublicTables, NamedTables), + case Continue1 of + true -> + {DepList2, IsPublic2, Continue2} = + get_deplist_paths(RaceList1, WarnVarArgs, RaceWarnTag, + RaceVarMap, CurrLevel, PublicTables, + NamedTables), + {DepList1 ++ DepList2, IsPublic1 orelse IsPublic2, Continue2}; + false -> {DepList1, IsPublic1, false} + end; + #beg_clause{} -> + get_deplist_paths(fixup_before_case_path(Tail), WarnVarArgs, + RaceWarnTag, RaceVarMap, CurrLevel, PublicTables, + NamedTables); + #curr_fun{status = in, var_map = RaceVarMap1} -> + {DepList, IsPublic, Continue} = + get_deplist_paths(Tail, WarnVarArgs, RaceWarnTag, RaceVarMap, + CurrLevel + 1, PublicTables, NamedTables), + IsPublic1 = + case RaceWarnTag of + ?WARN_ETS_LOOKUP_INSERT -> + [Tabs, Names, _, _] = WarnVarArgs, + IsPublic orelse + lists:any( + fun (T) -> + compare_var_list(T, PublicTables, RaceVarMap1) + end, Tabs) + orelse + length(Names -- NamedTables) < length(Names); + _ -> true + end, + {DepList, IsPublic1, Continue}; + #curr_fun{status = out, var_map = RaceVarMap1, def_vars = FunDefVars, + call_vars = FunCallVars} -> + WarnVarArgs1 = + var_analysis([format_arg(DefVar) || DefVar <- FunDefVars], + [format_arg(CallVar) || CallVar <- FunCallVars], + WarnVarArgs, RaceWarnTag), + {WarnVarArgs2, Stop} = + case RaceWarnTag of + ?WARN_WHEREIS_REGISTER -> + [WVA1, WVA2, WVA3, WVA4] = WarnVarArgs1, + Vars = + lists:flatten( + [find_all_bound_vars(V, RaceVarMap1) || V <- WVA1]), + case {Vars, CurrLevel} of + {[], 0} -> + {WarnVarArgs, true}; + {[], _} -> + {WarnVarArgs, false}; + _ -> + {[Vars, WVA2, WVA3, WVA4], false} + end; + ?WARN_WHEREIS_UNREGISTER -> + [WVA1, WVA2] = WarnVarArgs1, + Vars = + lists:flatten( + [find_all_bound_vars(V, RaceVarMap1) || V <- WVA1]), + case {Vars, CurrLevel} of + {[], 0} -> + {WarnVarArgs, true}; + {[], _} -> + {WarnVarArgs, false}; + _ -> + {[Vars, WVA2], false} + end; + ?WARN_ETS_LOOKUP_INSERT -> + [WVA1, WVA2, WVA3, WVA4] = WarnVarArgs1, + Vars1 = + lists:flatten( + [find_all_bound_vars(V1, RaceVarMap1) || V1 <- WVA1]), + Vars2 = + lists:flatten( + [find_all_bound_vars(V2, RaceVarMap1) || V2 <- WVA3]), + case {Vars1, Vars2, CurrLevel} of + {[], _, 0} -> + {WarnVarArgs, true}; + {[], _, _} -> + {WarnVarArgs, false}; + {_, [], 0} -> + {WarnVarArgs, true}; + {_, [], _} -> + {WarnVarArgs, false}; + _ -> + {[Vars1, WVA2, Vars2, WVA4], false} + end; + ?WARN_MNESIA_DIRTY_READ_WRITE -> + [WVA1, WVA2|T] = WarnVarArgs1, + Vars = + lists:flatten( + [find_all_bound_vars(V, RaceVarMap1) || V <- WVA1]), + case {Vars, CurrLevel} of + {[], 0} -> + {WarnVarArgs, true}; + {[], _} -> + {WarnVarArgs, false}; + _ -> + {[Vars, WVA2|T], false} + end + end, + case Stop of + true -> {[], false, false}; + false -> + CurrLevel1 = + case CurrLevel of + 0 -> CurrLevel; + _ -> CurrLevel - 1 + end, + get_deplist_paths(Tail, WarnVarArgs2, RaceWarnTag, RaceVarMap1, + CurrLevel1, PublicTables, NamedTables) + end; + #warn_call{call_name = RegCall, args = WarnVarArgs1, + var_map = RaceVarMap1} when RegCall =:= register orelse + RegCall =:= unregister -> + case compare_first_arg(WarnVarArgs, WarnVarArgs1, RaceVarMap1) of + true -> {[], false, false}; + NewWarnVarArgs -> + get_deplist_paths(Tail, NewWarnVarArgs, RaceWarnTag, RaceVarMap, + CurrLevel, PublicTables, NamedTables) + end; + #warn_call{call_name = ets_insert, args = WarnVarArgs1, + var_map = RaceVarMap1} -> + case compare_ets_insert(WarnVarArgs, WarnVarArgs1, RaceVarMap1) of + true -> {[], false, false}; + NewWarnVarArgs -> + get_deplist_paths(Tail, NewWarnVarArgs, RaceWarnTag, RaceVarMap, + CurrLevel, PublicTables, NamedTables) + end; + #warn_call{call_name = mnesia_dirty_write, args = WarnVarArgs1, + var_map = RaceVarMap1} -> + case compare_first_arg(WarnVarArgs, WarnVarArgs1, RaceVarMap1) of + true -> {[], false, false}; + NewWarnVarArgs -> + get_deplist_paths(Tail, NewWarnVarArgs, RaceWarnTag, RaceVarMap, + CurrLevel, PublicTables, NamedTables) + end; + #dep_call{var_map = RaceVarMap1} -> + {DepList, IsPublic, Continue} = + get_deplist_paths(Tail, WarnVarArgs, RaceWarnTag, RaceVarMap, + CurrLevel, PublicTables, NamedTables), + {refine_race(Head, WarnVarArgs, RaceWarnTag, DepList, RaceVarMap1), + IsPublic, Continue} + end + end. + +handle_case(RaceList, WarnVarArgs, RaceWarnTag, RaceVarMap, CurrLevel, + PublicTables, NamedTables) -> + case RaceList of + [] -> {[], [], false, true}; + [Head|Tail] -> + case Head of + #end_clause{} -> + {RestRaceList, DepList1, IsPublic1, Continue1} = + do_clause(Tail, WarnVarArgs, RaceWarnTag, RaceVarMap, CurrLevel, + PublicTables, NamedTables), + {RetRaceList, DepList2, IsPublic2, Continue2} = + handle_case(RestRaceList, WarnVarArgs, RaceWarnTag, RaceVarMap, + CurrLevel, PublicTables, NamedTables), + {RetRaceList, DepList1 ++ DepList2, IsPublic1 orelse IsPublic2, + Continue1 orelse Continue2}; + beg_case -> {Tail, [], false, false} + end + end. + +do_clause(RaceList, WarnVarArgs, RaceWarnTag, RaceVarMap, CurrLevel, + PublicTables, NamedTables) -> + {DepList, IsPublic, Continue} = + get_deplist_paths(fixup_case_path(RaceList, 0), WarnVarArgs, + RaceWarnTag, RaceVarMap, CurrLevel, + PublicTables, NamedTables), + {fixup_case_rest_paths(RaceList, 0), DepList, IsPublic, Continue}. + +fixup_case_path(RaceList, NestingLevel) -> + case RaceList of + [] -> []; + [Head|Tail] -> + {NewNestingLevel, Return} = + case Head of + beg_case -> {NestingLevel - 1, false}; + #end_case{} -> {NestingLevel + 1, false}; + #beg_clause{} -> + case NestingLevel =:= 0 of + true -> {NestingLevel, true}; + false -> {NestingLevel, false} + end; + _Other -> {NestingLevel, false} + end, + case Return of + true -> []; + false -> [Head|fixup_case_path(Tail, NewNestingLevel)] + end + end. + +%% Gets the race list before a case clause. +fixup_before_case_path(RaceList) -> + case RaceList of + [] -> []; + [Head|Tail] -> + case Head of + #end_clause{} -> + fixup_before_case_path(fixup_case_rest_paths(Tail, 0)); + beg_case -> Tail + end + end. + +fixup_case_rest_paths(RaceList, NestingLevel) -> + case RaceList of + [] -> []; + [Head|Tail] -> + {NewNestingLevel, Return} = + case Head of + beg_case -> {NestingLevel - 1, false}; + #end_case{} -> {NestingLevel + 1, false}; + #beg_clause{} -> + case NestingLevel =:= 0 of + true -> {NestingLevel, true}; + false -> {NestingLevel, false} + end; + _Other -> {NestingLevel, false} + end, + case Return of + true -> Tail; + false -> fixup_case_rest_paths(Tail, NewNestingLevel) + end + end. + +fixup_race_forward_helper(CurrFun, CurrFunLabel, Fun, FunLabel, + Calls, CallsToAnalyze, Code, RaceList, + InitFun, NewFunArgs, NewFunTypes, + RaceWarnTag, RaceVarMap, FunDefVars, + FunCallVars, FunArgTypes, NestingLevel, + Args, CodeB, StateRaceList) -> + case Calls of + [] -> + {NewRaceList, + #curr_fun{mfa = NewCurrFun, label = NewCurrFunLabel, + var_map = NewRaceVarMap, def_vars = NewFunDefVars, + call_vars = NewFunCallVars, arg_types = NewFunArgTypes}, + NewCode, NewNestingLevel} = + remove_clause(RaceList, + #curr_fun{mfa = CurrFun, label = CurrFunLabel, var_map = RaceVarMap, + def_vars = FunDefVars, call_vars = FunCallVars, + arg_types = FunArgTypes}, + Code, NestingLevel), + {NewCurrFun, NewCurrFunLabel, CallsToAnalyze, NewCode, NewRaceList, + NewRaceVarMap, NewFunDefVars, NewFunCallVars, NewFunArgTypes, + NewNestingLevel}; + [Head|Tail] -> + case Head of + {InitFun, InitFun} when CurrFun =:= InitFun, Fun =:= InitFun -> + NewCallsToAnalyze = lists:delete(Head, CallsToAnalyze), + NewRaceVarMap = + race_var_map(Args, NewFunArgs, RaceVarMap, bind), + RetC = + fixup_all_calls(InitFun, InitFun, FunLabel, Args, + CodeB ++ + [#curr_fun{status = out, mfa = InitFun, + label = CurrFunLabel, var_map = RaceVarMap, + def_vars = FunDefVars, call_vars = FunCallVars, + arg_types = FunArgTypes}], + Code, RaceVarMap), + NewCode = + fixup_all_calls(InitFun, InitFun, FunLabel, Args, + CodeB ++ + [#curr_fun{status = out, mfa = InitFun, + label = CurrFunLabel, var_map = NewRaceVarMap, + def_vars = Args, call_vars = NewFunArgs, + arg_types = NewFunTypes}], + [#curr_fun{status = in, mfa = Fun, + label = FunLabel, var_map = NewRaceVarMap, + def_vars = Args, call_vars = NewFunArgs, + arg_types = NewFunTypes}| + lists:reverse(StateRaceList)] ++ + RetC, NewRaceVarMap), + {InitFun, FunLabel, NewCallsToAnalyze, NewCode, RaceList, + NewRaceVarMap, Args, NewFunArgs, NewFunTypes, NestingLevel}; + {CurrFun, Fun} -> + NewCallsToAnalyze = lists:delete(Head, CallsToAnalyze), + NewRaceVarMap = race_var_map(Args, NewFunArgs, RaceVarMap, bind), + RetC = + case Fun of + InitFun -> + fixup_all_calls(CurrFun, Fun, FunLabel, Args, + lists:reverse(StateRaceList) ++ + [#curr_fun{status = out, mfa = CurrFun, + label = CurrFunLabel, var_map = RaceVarMap, + def_vars = FunDefVars, call_vars = FunCallVars, + arg_types = FunArgTypes}], + Code, RaceVarMap); + _Other1 -> + fixup_all_calls(CurrFun, Fun, FunLabel, Args, + CodeB ++ + [#curr_fun{status = out, mfa = CurrFun, + label = CurrFunLabel, var_map = RaceVarMap, + def_vars = FunDefVars, call_vars = FunCallVars, + arg_types = FunArgTypes}], + Code, RaceVarMap) + end, + NewCode = + case Fun of + InitFun -> + [#curr_fun{status = in, mfa = Fun, + label = FunLabel, var_map = NewRaceVarMap, + def_vars = Args, call_vars = NewFunArgs, + arg_types = NewFunTypes}| + lists:reverse(StateRaceList)] ++ RetC; + _ -> + [#curr_fun{status = in, mfa = Fun, + label = FunLabel, var_map = NewRaceVarMap, + def_vars = Args, call_vars = NewFunArgs, + arg_types = NewFunTypes}|CodeB] ++ + RetC + end, + {Fun, FunLabel, NewCallsToAnalyze, NewCode, RaceList, NewRaceVarMap, + Args, NewFunArgs, NewFunTypes, NestingLevel}; + {_TupleA, _TupleB} -> + fixup_race_forward_helper(CurrFun, CurrFunLabel, Fun, FunLabel, + Tail, CallsToAnalyze, Code, RaceList, InitFun, NewFunArgs, + NewFunTypes, RaceWarnTag, RaceVarMap, FunDefVars, FunCallVars, + FunArgTypes, NestingLevel, Args, CodeB, StateRaceList) + end + end. + +%%% =========================================================================== +%%% +%%% Backward Analysis +%%% +%%% =========================================================================== + +fixup_race_backward(CurrFun, Calls, CallsToAnalyze, Parents, Height) -> + case Height =:= 0 of + true -> Parents; + false -> + case Calls of + [] -> + case is_integer(CurrFun) orelse lists:member(CurrFun, Parents) of + true -> Parents; + false -> [CurrFun|Parents] + end; + [Head|Tail] -> + {Parent, TupleB} = Head, + case TupleB =:= CurrFun of + true -> % more paths are needed + NewCallsToAnalyze = lists:delete(Head, CallsToAnalyze), + NewParents = + fixup_race_backward(Parent, NewCallsToAnalyze, + NewCallsToAnalyze, Parents, Height - 1), + fixup_race_backward(CurrFun, Tail, NewCallsToAnalyze, NewParents, + Height); + false -> + fixup_race_backward(CurrFun, Tail, CallsToAnalyze, Parents, + Height) + end + end + end. + +%%% =========================================================================== +%%% +%%% Utilities +%%% +%%% =========================================================================== + +are_bound_labels(Label1, Label2, RaceVarMap) -> + case dict:find(Label1, RaceVarMap) of + error -> false; + {ok, Labels} -> + lists:member(Label2, Labels) orelse + are_bound_labels_helper(Labels, Label1, Label2, RaceVarMap) + end. + +are_bound_labels_helper(Labels, OldLabel, CompLabel, RaceVarMap) -> + case dict:size(RaceVarMap) of + 0 -> false; + _ -> + case Labels of + [] -> false; + [Head|Tail] -> + NewRaceVarMap = dict:erase(OldLabel, RaceVarMap), + are_bound_labels(Head, CompLabel, NewRaceVarMap) orelse + are_bound_labels_helper(Tail, Head, CompLabel, NewRaceVarMap) + end + end. + +are_bound_vars(Vars1, Vars2, RaceVarMap) -> + case is_list(Vars1) andalso is_list(Vars2) of + true -> + case Vars1 of + [] -> false; + [AHead|ATail] -> + case Vars2 of + [] -> false; + [PHead|PTail] -> + are_bound_vars(AHead, PHead, RaceVarMap) andalso + are_bound_vars(ATail, PTail, RaceVarMap) + end + end; + false -> + {NewVars1, NewVars2, IsList} = + case is_list(Vars1) of + true -> + case Vars1 of + [Var1] -> {Var1, Vars2, true}; + _Thing -> {Vars1, Vars2, false} + end; + false -> + case is_list(Vars2) of + true -> + case Vars2 of + [Var2] -> {Vars1, Var2, true}; + _Thing -> {Vars1, Vars2, false} + end; + false -> {Vars1, Vars2, true} + end + end, + case IsList of + true -> + case cerl:type(NewVars1) of + var -> + case cerl:type(NewVars2) of + var -> + ALabel = cerl_trees:get_label(NewVars1), + PLabel = cerl_trees:get_label(NewVars2), + are_bound_labels(ALabel, PLabel, RaceVarMap) orelse + are_bound_labels(PLabel, ALabel, RaceVarMap); + alias -> + are_bound_vars(NewVars1, cerl:alias_var(NewVars2), + RaceVarMap); + values -> + are_bound_vars(NewVars1, cerl:values_es(NewVars2), + RaceVarMap); + _Other -> false + end; + tuple -> + case cerl:type(NewVars2) of + tuple -> + are_bound_vars(cerl:tuple_es(NewVars1), + cerl:tuple_es(NewVars2), RaceVarMap); + alias -> + are_bound_vars(NewVars1, cerl:alias_var(NewVars2), + RaceVarMap); + values -> + are_bound_vars(NewVars1, cerl:values_es(NewVars2), + RaceVarMap); + _Other -> false + end; + cons -> + case cerl:type(NewVars2) of + cons -> + are_bound_vars(cerl:cons_hd(NewVars1), + cerl:cons_hd(NewVars2), RaceVarMap) + andalso + are_bound_vars(cerl:cons_tl(NewVars1), + cerl:cons_tl(NewVars2), RaceVarMap); + alias -> + are_bound_vars(NewVars1, cerl:alias_var(NewVars2), + RaceVarMap); + values -> + are_bound_vars(NewVars1, cerl:values_es(NewVars2), + RaceVarMap); + _Other -> false + end; + alias -> + case cerl:type(NewVars2) of + alias -> + are_bound_vars(cerl:alias_var(NewVars1), + cerl:alias_var(NewVars2), RaceVarMap); + _Other -> + are_bound_vars(cerl:alias_var(NewVars1), + NewVars2, RaceVarMap) + end; + values -> + case cerl:type(NewVars2) of + values -> + are_bound_vars(cerl:values_es(NewVars1), + cerl:values_es(NewVars2), RaceVarMap); + _Other -> + are_bound_vars(cerl:values_es(NewVars1), + NewVars2, RaceVarMap) + end; + _Other -> false + end; + false -> false + end + end. + +callgraph__renew_tables(Table, Callgraph) -> + case Table of + {named, NameLabel, Names} -> + PTablesToAdd = + case NameLabel of + ?no_label -> []; + _Other -> [NameLabel] + end, + NamesToAdd = filter_named_tables(Names), + PTables = dialyzer_callgraph:get_public_tables(Callgraph), + NTables = dialyzer_callgraph:get_named_tables(Callgraph), + dialyzer_callgraph:put_public_tables( + lists:usort(PTablesToAdd ++ PTables), + dialyzer_callgraph:put_named_tables( + NamesToAdd ++ NTables, Callgraph)); + _Other -> + Callgraph + end. + +cleanup_clause_code(#curr_fun{mfa = CurrFun} = CurrTuple, Code, + NestingLevel, LocalNestingLevel) -> + case Code of + [] -> {CurrTuple, []}; + [Head|Tail] -> + {NewLocalNestingLevel, NewNestingLevel, NewCurrTuple, Return} = + case Head of + beg_case -> + {LocalNestingLevel, NestingLevel + 1, CurrTuple, false}; + #end_case{} -> + {LocalNestingLevel, NestingLevel - 1, CurrTuple, false}; + #end_clause{} -> + case NestingLevel =:= 0 of + true -> + {LocalNestingLevel, NestingLevel, CurrTuple, true}; + false -> + {LocalNestingLevel, NestingLevel, CurrTuple, false} + end; + #fun_call{caller = CurrFun} -> + {LocalNestingLevel - 1, NestingLevel, CurrTuple, false}; + #curr_fun{status = in} -> + {LocalNestingLevel - 1, NestingLevel, Head, false}; + #curr_fun{status = out} -> + {LocalNestingLevel + 1, NestingLevel, Head, false}; + Other when Other =/= #fun_call{} -> + {LocalNestingLevel, NestingLevel, CurrTuple, false} + end, + case Return of + true -> {NewCurrTuple, Tail}; + false -> + cleanup_clause_code(NewCurrTuple, Tail, NewNestingLevel, + NewLocalNestingLevel) + end + end. + +cleanup_dep_calls(DepList) -> + case DepList of + [] -> []; + [#dep_call{call_name = CallName, arg_types = ArgTypes, + vars = Vars, state = State, file_line = FileLine}|T] -> + [#dep_call{call_name = CallName, arg_types = ArgTypes, + vars = Vars, state = State, file_line = FileLine}| + cleanup_dep_calls(T)] + end. + +cleanup_race_code(State) -> + Callgraph = dialyzer_dataflow:state__get_callgraph(State), + dialyzer_dataflow:state__put_callgraph( + dialyzer_callgraph:race_code_new(Callgraph), State). + +filter_named_tables(NamesList) -> + case NamesList of + [] -> []; + [Head|Tail] -> + NewHead = + case string:rstr(Head, "()") of + 0 -> [Head]; + _Other -> [] + end, + NewHead ++ filter_named_tables(Tail) + end. + +filter_parents(Parents, NewParents, Digraph) -> + case Parents of + [] -> NewParents; + [Head|Tail] -> + NewParents1 = filter_parents_helper1(Head, Tail, NewParents, Digraph), + filter_parents(Tail, NewParents1, Digraph) + end. + +filter_parents_helper1(First, Rest, NewParents, Digraph) -> + case Rest of + [] -> NewParents; + [Head|Tail] -> + NewParents1 = filter_parents_helper2(First, Head, NewParents, Digraph), + filter_parents_helper1(First, Tail, NewParents1, Digraph) + end. + +filter_parents_helper2(Parent1, Parent2, NewParents, Digraph) -> + case digraph:get_path(Digraph, Parent1, Parent2) of + false -> + case digraph:get_path(Digraph, Parent2, Parent1) of + false -> NewParents; + _Vertices -> NewParents -- [Parent1] + end; + _Vertices -> NewParents -- [Parent2] + end. + +find_all_bound_vars(Label, RaceVarMap) -> + case dict:find(Label, RaceVarMap) of + error -> [Label]; + {ok, Labels} -> + lists:usort(Labels ++ + find_all_bound_vars_helper(Labels, Label, RaceVarMap)) + end. + +find_all_bound_vars_helper(Labels, Label, RaceVarMap) -> + case dict:size(RaceVarMap) of + 0 -> []; + _ -> + case Labels of + [] -> []; + [Head|Tail] -> + NewRaceVarMap = dict:erase(Label, RaceVarMap), + find_all_bound_vars(Head, NewRaceVarMap) ++ + find_all_bound_vars_helper(Tail, Head, NewRaceVarMap) + end + end. + +fixup_all_calls(CurrFun, NextFun, NextFunLabel, Args, CodeToReplace, + Code, RaceVarMap) -> + case Code of + [] -> []; + [Head|Tail] -> + NewCode = + case Head of + #fun_call{caller = CurrFun, callee = Callee, + arg_types = FunArgTypes, vars = FunArgs} + when Callee =:= NextFun orelse Callee =:= NextFunLabel -> + RaceVarMap1 = race_var_map(Args, FunArgs, RaceVarMap, bind), + [#curr_fun{status = in, mfa = NextFun, label = NextFunLabel, + var_map = RaceVarMap1, def_vars = Args, + call_vars = FunArgs, arg_types = FunArgTypes}| + CodeToReplace]; + _Other -> [Head] + end, + RetCode = + fixup_all_calls(CurrFun, NextFun, NextFunLabel, Args, CodeToReplace, + Tail, RaceVarMap), + NewCode ++ RetCode + end. + +is_last_race(RaceTag, InitFun, Code, Callgraph) -> + case Code of + [] -> true; + [Head|Tail] -> + case Head of + RaceTag -> false; + #fun_call{callee = Fun} -> + FunName = + case is_integer(Fun) of + true -> + case dialyzer_callgraph:lookup_name(Fun, Callgraph) of + error -> Fun; + {ok, Name} -> Name + end; + false -> Fun + end, + Digraph = dialyzer_callgraph:get_digraph(Callgraph), + case FunName =:= InitFun orelse + digraph:get_path(Digraph, FunName, InitFun) of + false -> is_last_race(RaceTag, InitFun, Tail, Callgraph); + _Vertices -> false + end; + _Other -> is_last_race(RaceTag, InitFun, Tail, Callgraph) + end + end. + +lists_key_member(Member, List, N) when is_integer(Member) -> + case List of + [] -> 0; + [Head|Tail] -> + NewN = N + 1, + case Head of + Member -> NewN; + _Other -> lists_key_member(Member, Tail, NewN) + end + end; +lists_key_member(_M, _L, _N) -> + 0. + +lists_key_member_lists(MemberList, List) -> + case MemberList of + [] -> 0; + [Head|Tail] -> + case lists_key_member(Head, List, 0) of + 0 -> lists_key_member_lists(Tail, List); + Other -> Other + end + end. + +lists_key_members_lists(MemberList, List) -> + case MemberList of + [] -> []; + [Head|Tail] -> + lists:usort( + lists_key_members_lists_helper(Head, List, 1) ++ + lists_key_members_lists(Tail, List)) + end. + +lists_key_members_lists_helper(Elem, List, N) when is_integer(Elem) -> + case List of + [] -> []; + [Head|Tail] -> + NewHead = + case Head =:= Elem of + true -> [N]; + false -> [] + end, + NewHead ++ lists_key_members_lists_helper(Elem, Tail, N + 1) + end; +lists_key_members_lists_helper(_Elem, _List, _N) -> + [0]. + +lists_key_replace(N, List, NewMember) -> + {Before, [_|After]} = lists:split(N - 1, List), + Before ++ [NewMember|After]. + +lists_get(0, _List) -> ?no_label; +lists_get(N, List) -> lists:nth(N, List). + +refine_race(RaceCall, WarnVarArgs, RaceWarnTag, DependencyList, RaceVarMap) -> + case RaceWarnTag of + WarnWhereis when WarnWhereis =:= ?WARN_WHEREIS_REGISTER orelse + WarnWhereis =:= ?WARN_WHEREIS_UNREGISTER -> + case RaceCall of + #dep_call{call_name = ets_lookup} -> + DependencyList; + #dep_call{call_name = mnesia_dirty_read} -> + DependencyList; + #dep_call{call_name = whereis, args = VarArgs} -> + refine_race_helper(RaceCall, VarArgs, WarnVarArgs, RaceWarnTag, + DependencyList, RaceVarMap) + end; + ?WARN_ETS_LOOKUP_INSERT -> + case RaceCall of + #dep_call{call_name = whereis} -> + DependencyList; + #dep_call{call_name = mnesia_dirty_read} -> + DependencyList; + #dep_call{call_name = ets_lookup, args = VarArgs} -> + refine_race_helper(RaceCall, VarArgs, WarnVarArgs, RaceWarnTag, + DependencyList, RaceVarMap) + end; + ?WARN_MNESIA_DIRTY_READ_WRITE -> + case RaceCall of + #dep_call{call_name = whereis} -> + DependencyList; + #dep_call{call_name = ets_lookup} -> + DependencyList; + #dep_call{call_name = mnesia_dirty_read, args = VarArgs} -> + refine_race_helper(RaceCall, VarArgs, WarnVarArgs, RaceWarnTag, + DependencyList, RaceVarMap) + end + end. + +refine_race_helper(RaceCall, VarArgs, WarnVarArgs, RaceWarnTag, DependencyList, + RaceVarMap) -> + case compare_types(VarArgs, WarnVarArgs, RaceWarnTag, RaceVarMap) of + true -> [RaceCall|DependencyList]; + false -> DependencyList + end. + +remove_clause(RaceList, CurrTuple, Code, NestingLevel) -> + NewRaceList = fixup_case_rest_paths(RaceList, 0), + {NewCurrTuple, NewCode} = + cleanup_clause_code(CurrTuple, Code, 0, NestingLevel), + ReturnTuple = {NewRaceList, NewCurrTuple, NewCode, NestingLevel}, + case NewRaceList of + [beg_case|RTail] -> + case NewCode of + [#end_case{}|CTail] -> + remove_clause(RTail, NewCurrTuple, CTail, NestingLevel); + _Other -> ReturnTuple + end; + _Else -> ReturnTuple + end. + +remove_nonlocal_functions(Code, NestingLevel) -> + case Code of + [] -> []; + [H|T] -> + NewNL = + case H of + #curr_fun{status = in} -> + NestingLevel + 1; + #curr_fun{status = out} -> + NestingLevel - 1; + _Other -> + NestingLevel + end, + case NewNL =:= 0 of + true -> T; + false -> remove_nonlocal_functions(T, NewNL) + end + end. + +renew_curr_fun(CurrFun, Races) -> + Races#races{curr_fun = CurrFun}. + +renew_curr_fun_label(CurrFunLabel, Races) -> + Races#races{curr_fun_label = CurrFunLabel}. + +renew_race_list(RaceList, Races) -> + Races#races{race_list = RaceList}. + +renew_race_list_size(RaceListSize, Races) -> + Races#races{race_list_size = RaceListSize}. + +renew_race_tags(RaceTags, Races) -> + Races#races{race_tags = RaceTags}. + +renew_table(Table, Races) -> + Races#races{new_table = Table}. + +state__renew_curr_fun(CurrFun, State) -> + Races = dialyzer_dataflow:state__get_races(State), + dialyzer_dataflow:state__put_races(renew_curr_fun(CurrFun, Races), State). + +state__renew_curr_fun_label(CurrFunLabel, State) -> + Races = dialyzer_dataflow:state__get_races(State), + dialyzer_dataflow:state__put_races( + renew_curr_fun_label(CurrFunLabel, Races), State). + +state__renew_race_list(RaceList, State) -> + Races = dialyzer_dataflow:state__get_races(State), + dialyzer_dataflow:state__put_races(renew_race_list(RaceList, Races), State). + +state__renew_race_tags(RaceTags, State) -> + Races = dialyzer_dataflow:state__get_races(State), + dialyzer_dataflow:state__put_races(renew_race_tags(RaceTags, Races), State). + +state__renew_info(RaceList, RaceListSize, RaceTags, Table, State) -> + Callgraph = dialyzer_dataflow:state__get_callgraph(State), + Races = dialyzer_dataflow:state__get_races(State), + dialyzer_dataflow:state__put_callgraph( + callgraph__renew_tables(Table, Callgraph), + dialyzer_dataflow:state__put_races( + renew_table(Table, + renew_race_list(RaceList, + renew_race_list_size(RaceListSize, + renew_race_tags(RaceTags, Races)))), State)). + +%%% =========================================================================== +%%% +%%% Variable and Type Utilities +%%% +%%% =========================================================================== + +any_args(StrList) -> + case StrList of + [] -> false; + [Head|Tail] -> + case string:rstr(Head, "()") of + 0 -> any_args(Tail); + _Other -> true + end + end. + +-spec bind_dict_vars(label(), label(), dict:dict()) -> dict:dict(). + +bind_dict_vars(Key, Label, RaceVarMap) -> + case Key =:= Label of + true -> RaceVarMap; + false -> + case dict:find(Key, RaceVarMap) of + error -> dict:store(Key, [Label], RaceVarMap); + {ok, Labels} -> + case lists:member(Label, Labels) of + true -> RaceVarMap; + false -> dict:store(Key, [Label|Labels], RaceVarMap) + end + end + end. + +bind_dict_vars_list(Key, Labels, RaceVarMap) -> + case Labels of + [] -> RaceVarMap; + [Head|Tail] -> + bind_dict_vars_list(Key, Tail, bind_dict_vars(Key, Head, RaceVarMap)) + end. + +compare_ets_insert(OldWarnVarArgs, NewWarnVarArgs, RaceVarMap) -> + [Old1, Old2, Old3, Old4] = OldWarnVarArgs, + [New1, New2, New3, New4] = NewWarnVarArgs, + Bool = + case any_args(Old2) of + true -> compare_var_list(New1, Old1, RaceVarMap); + false -> + case any_args(New2) of + true -> compare_var_list(New1, Old1, RaceVarMap); + false -> compare_var_list(New1, Old1, RaceVarMap) + orelse (Old2 =:= New2) + end + end, + case Bool of + true -> + case any_args(Old4) of + true -> + case compare_list_vars(Old3, ets_list_args(New3), [], RaceVarMap) of + true -> true; + Args3 -> lists_key_replace(3, OldWarnVarArgs, Args3) + end; + false -> + case any_args(New4) of + true -> + case compare_list_vars(Old3, ets_list_args(New3), [], + RaceVarMap) of + true -> true; + Args3 -> lists_key_replace(3, OldWarnVarArgs, Args3) + end; + false -> + case compare_list_vars(Old3, ets_list_args(New3), [], + RaceVarMap) of + true -> true; + Args3 -> + lists_key_replace(4, + lists_key_replace(3, OldWarnVarArgs, Args3), Old4 -- New4) + end + end + end; + false -> OldWarnVarArgs + end. + +compare_first_arg(OldWarnVarArgs, NewWarnVarArgs, RaceVarMap) -> + [Old1, Old2|_OldT] = OldWarnVarArgs, + [New1, New2|_NewT] = NewWarnVarArgs, + case any_args(Old2) of + true -> + case compare_var_list(New1, Old1, RaceVarMap) of + true -> true; + false -> OldWarnVarArgs + end; + false -> + case any_args(New2) of + true -> + case compare_var_list(New1, Old1, RaceVarMap) of + true -> true; + false -> OldWarnVarArgs + end; + false -> + case compare_var_list(New1, Old1, RaceVarMap) of + true -> true; + false -> lists_key_replace(2, OldWarnVarArgs, Old2 -- New2) + end + end + end. + +compare_argtypes(ArgTypes, WarnArgTypes) -> + lists:any(fun (X) -> lists:member(X, WarnArgTypes) end, ArgTypes). + +%% Compares the argument types of the two suspicious calls. +compare_types(VarArgs, WarnVarArgs, RaceWarnTag, RaceVarMap) -> + case RaceWarnTag of + ?WARN_WHEREIS_REGISTER -> + [VA1, VA2] = VarArgs, + [WVA1, WVA2, _, _] = WarnVarArgs, + case any_args(VA2) of + true -> compare_var_list(VA1, WVA1, RaceVarMap); + false -> + case any_args(WVA2) of + true -> compare_var_list(VA1, WVA1, RaceVarMap); + false -> + compare_var_list(VA1, WVA1, RaceVarMap) orelse + compare_argtypes(VA2, WVA2) + end + end; + ?WARN_WHEREIS_UNREGISTER -> + [VA1, VA2] = VarArgs, + [WVA1, WVA2] = WarnVarArgs, + case any_args(VA2) of + true -> compare_var_list(VA1, WVA1, RaceVarMap); + false -> + case any_args(WVA2) of + true -> compare_var_list(VA1, WVA1, RaceVarMap); + false -> + compare_var_list(VA1, WVA1, RaceVarMap) orelse + compare_argtypes(VA2, WVA2) + end + end; + ?WARN_ETS_LOOKUP_INSERT -> + [VA1, VA2, VA3, VA4] = VarArgs, + [WVA1, WVA2, WVA3, WVA4] = WarnVarArgs, + Bool = + case any_args(VA2) of + true -> compare_var_list(VA1, WVA1, RaceVarMap); + false -> + case any_args(WVA2) of + true -> compare_var_list(VA1, WVA1, RaceVarMap); + false -> + compare_var_list(VA1, WVA1, RaceVarMap) orelse + compare_argtypes(VA2, WVA2) + end + end, + Bool andalso + (case any_args(VA4) of + true -> + compare_var_list(VA3, WVA3, RaceVarMap); + false -> + case any_args(WVA4) of + true -> + compare_var_list(VA3, WVA3, RaceVarMap); + false -> + compare_var_list(VA3, WVA3, RaceVarMap) orelse + compare_argtypes(VA4, WVA4) + end + end); + ?WARN_MNESIA_DIRTY_READ_WRITE -> + [VA1, VA2|_] = VarArgs, %% Two or four elements + [WVA1, WVA2|_] = WarnVarArgs, + case any_args(VA2) of + true -> compare_var_list(VA1, WVA1, RaceVarMap); + false -> + case any_args(WVA2) of + true -> compare_var_list(VA1, WVA1, RaceVarMap); + false -> + compare_var_list(VA1, WVA1, RaceVarMap) orelse + compare_argtypes(VA2, WVA2) + end + end + end. + +compare_list_vars(VarList1, VarList2, NewVarList1, RaceVarMap) -> + case VarList1 of + [] -> + case NewVarList1 of + [] -> true; + _Other -> NewVarList1 + end; + [Head|Tail] -> + NewHead = + case compare_var_list(Head, VarList2, RaceVarMap) of + true -> []; + false -> [Head] + end, + compare_list_vars(Tail, VarList2, NewHead ++ NewVarList1, RaceVarMap) + end. + +compare_vars(Var1, Var2, RaceVarMap) when is_integer(Var1), is_integer(Var2) -> + Var1 =:= Var2 orelse + are_bound_labels(Var1, Var2, RaceVarMap) orelse + are_bound_labels(Var2, Var1, RaceVarMap); +compare_vars(_Var1, _Var2, _RaceVarMap) -> + false. + +-spec compare_var_list(label_type(), [label_type()], dict:dict()) -> boolean(). + +compare_var_list(Var, VarList, RaceVarMap) -> + lists:any(fun (V) -> compare_vars(Var, V, RaceVarMap) end, VarList). + +ets_list_args(MaybeList) -> + case is_list(MaybeList) of + true -> + try [ets_tuple_args(T) || T <- MaybeList] + catch _:_ -> [?no_label] + end; + false -> [ets_tuple_args(MaybeList)] + end. + +ets_list_argtypes(ListStr) -> + ListStr1 = string:strip(ListStr, left, $[), + ListStr2 = string:strip(ListStr1, right, $]), + ListStr3 = string:strip(ListStr2, right, $.), + string:strip(ListStr3, right, $,). + +ets_tuple_args(MaybeTuple) -> + case is_tuple(MaybeTuple) of + true -> element(1, MaybeTuple); + false -> ?no_label + end. + +ets_tuple_argtypes2(TupleList, ElemList) -> + case TupleList of + [] -> ElemList; + [H|T] -> + ets_tuple_argtypes2(T, + ets_tuple_argtypes2_helper(H, [], 0) ++ ElemList) + end. + +ets_tuple_argtypes2_helper(TupleStr, ElemStr, NestingLevel) -> + case TupleStr of + [] -> []; + [H|T] -> + {NewElemStr, NewNestingLevel, Return} = + case H of + ${ when NestingLevel =:= 0 -> + {ElemStr, NestingLevel + 1, false}; + ${ -> + {[H|ElemStr], NestingLevel + 1, false}; + $[ -> + {[H|ElemStr], NestingLevel + 1, false}; + $( -> + {[H|ElemStr], NestingLevel + 1, false}; + $} -> + {[H|ElemStr], NestingLevel - 1, false}; + $] -> + {[H|ElemStr], NestingLevel - 1, false}; + $) -> + {[H|ElemStr], NestingLevel - 1, false}; + $, when NestingLevel =:= 1 -> + {lists:reverse(ElemStr), NestingLevel, true}; + _Other -> + {[H|ElemStr], NestingLevel, false} + end, + case Return of + true -> string:tokens(NewElemStr, " |"); + false -> + ets_tuple_argtypes2_helper(T, NewElemStr, NewNestingLevel) + end + end. + +ets_tuple_argtypes1(Str, Tuple, TupleList, NestingLevel) -> + case Str of + [] -> TupleList; + [H|T] -> + {NewTuple, NewNestingLevel, Add} = + case H of + ${ -> + {[H|Tuple], NestingLevel + 1, false}; + $} -> + case NestingLevel of + 1 -> + {[H|Tuple], NestingLevel - 1, true}; + _Else -> + {[H|Tuple], NestingLevel - 1, false} + end; + _Other1 when NestingLevel =:= 0 -> + {Tuple, NestingLevel, false}; + _Other2 -> + {[H|Tuple], NestingLevel, false} + end, + case Add of + true -> + ets_tuple_argtypes1(T, [], + [lists:reverse(NewTuple)|TupleList], + NewNestingLevel); + false -> + ets_tuple_argtypes1(T, NewTuple, TupleList, NewNestingLevel) + end + end. + +format_arg(?bypassed) -> ?no_label; +format_arg(Arg0) -> + Arg = cerl:fold_literal(Arg0), + case cerl:type(Arg) of + var -> cerl_trees:get_label(Arg); + tuple -> list_to_tuple([format_arg(A) || A <- cerl:tuple_es(Arg)]); + cons -> [format_arg(cerl:cons_hd(Arg))|format_arg(cerl:cons_tl(Arg))]; + alias -> format_arg(cerl:alias_var(Arg)); + literal -> + case cerl:is_c_nil(Arg) of + true -> []; + false -> ?no_label + end; + _Other -> ?no_label + end. + +-spec format_args([core_vars()], [erl_types:erl_type()], + dialyzer_dataflow:state(), call()) -> + args(). + +format_args([], [], _State, _Call) -> + []; +format_args(ArgList, TypeList, CleanState, Call) -> + format_args_2(format_args_1(ArgList, TypeList, CleanState), Call). + +format_args_1([Arg], [Type], CleanState) -> + [format_arg(Arg), format_type(Type, CleanState)]; +format_args_1([Arg|Args], [Type|Types], CleanState) -> + List = + case Arg =:= ?bypassed of + true -> [?no_label, format_type(Type, CleanState)]; + false -> + case cerl:is_literal(cerl:fold_literal(Arg)) of + true -> [?no_label, format_cerl(Arg)]; + false -> [format_arg(Arg), format_type(Type, CleanState)] + end + end, + List ++ format_args_1(Args, Types, CleanState). + +format_args_2(StrArgList, Call) -> + case Call of + whereis -> + lists_key_replace(2, StrArgList, + string:tokens(lists:nth(2, StrArgList), " |")); + register -> + lists_key_replace(2, StrArgList, + string:tokens(lists:nth(2, StrArgList), " |")); + unregister -> + lists_key_replace(2, StrArgList, + string:tokens(lists:nth(2, StrArgList), " |")); + ets_new -> + StrArgList1 = lists_key_replace(2, StrArgList, + string:tokens(lists:nth(2, StrArgList), " |")), + lists_key_replace(4, StrArgList1, + string:tokens(ets_list_argtypes(lists:nth(4, StrArgList1)), " |")); + ets_lookup -> + StrArgList1 = lists_key_replace(2, StrArgList, + string:tokens(lists:nth(2, StrArgList), " |")), + lists_key_replace(4, StrArgList1, + string:tokens(lists:nth(4, StrArgList1), " |")); + ets_insert -> + StrArgList1 = lists_key_replace(2, StrArgList, + string:tokens(lists:nth(2, StrArgList), " |")), + lists_key_replace(4, StrArgList1, + ets_tuple_argtypes2( + ets_tuple_argtypes1(lists:nth(4, StrArgList1), [], [], 0), + [])); + mnesia_dirty_read1 -> + lists_key_replace(2, StrArgList, + [mnesia_tuple_argtypes(T) || T <- string:tokens( + lists:nth(2, StrArgList), " |")]); + mnesia_dirty_read2 -> + lists_key_replace(2, StrArgList, + string:tokens(lists:nth(2, StrArgList), " |")); + mnesia_dirty_write1 -> + lists_key_replace(2, StrArgList, + [mnesia_record_tab(R) || R <- string:tokens( + lists:nth(2, StrArgList), " |")]); + mnesia_dirty_write2 -> + lists_key_replace(2, StrArgList, + string:tokens(lists:nth(2, StrArgList), " |")); + function_call -> StrArgList + end. + +format_cerl(Tree) -> + cerl_prettypr:format(cerl:set_ann(Tree, []), + [{hook, dialyzer_utils:pp_hook()}, + {noann, true}, + {paper, 100000}, + {ribbon, 100000} + ]). + +format_type(Type, State) -> + R = dialyzer_dataflow:state__get_records(State), + erl_types:t_to_string(Type, R). + +mnesia_record_tab(RecordStr) -> + case string:str(RecordStr, "#") =:= 1 of + true -> + "'" ++ + string:sub_string(RecordStr, 2, string:str(RecordStr, "{") - 1) ++ + "'"; + false -> RecordStr + end. + +mnesia_tuple_argtypes(TupleStr) -> + TupleStr1 = string:strip(TupleStr, left, ${), + [TupleStr2|_T] = string:tokens(TupleStr1, " ,"), + lists:flatten(string:tokens(TupleStr2, " |")). + +-spec race_var_map(var_to_map1(), var_to_map2(), dict:dict(), op()) -> + dict:dict(). + +race_var_map(Vars1, Vars2, RaceVarMap, Op) -> + case Vars1 =:= ?no_arg orelse Vars1 =:= ?bypassed + orelse Vars2 =:= ?bypassed of + true -> RaceVarMap; + false -> + case is_list(Vars1) andalso is_list(Vars2) of + true -> + case Vars1 of + [] -> RaceVarMap; + [AHead|ATail] -> + case Vars2 of + [] -> RaceVarMap; + [PHead|PTail] -> + NewRaceVarMap = race_var_map(AHead, PHead, RaceVarMap, Op), + race_var_map(ATail, PTail, NewRaceVarMap, Op) + end + end; + false -> + {NewVars1, NewVars2, Bool} = + case is_list(Vars1) of + true -> + case Vars1 of + [Var1] -> {Var1, Vars2, true}; + _Thing -> {Vars1, Vars2, false} + end; + false -> + case is_list(Vars2) of + true -> + case Vars2 of + [Var2] -> {Vars1, Var2, true}; + _Thing -> {Vars1, Vars2, false} + end; + false -> {Vars1, Vars2, true} + end + end, + case Bool of + true -> + case cerl:type(NewVars1) of + var -> + case cerl:type(NewVars2) of + var -> + ALabel = cerl_trees:get_label(NewVars1), + PLabel = cerl_trees:get_label(NewVars2), + case Op of + bind -> + TempRaceVarMap = + bind_dict_vars(ALabel, PLabel, RaceVarMap), + bind_dict_vars(PLabel, ALabel, TempRaceVarMap); + unbind -> + TempRaceVarMap = + unbind_dict_vars(ALabel, PLabel, RaceVarMap), + unbind_dict_vars(PLabel, ALabel, TempRaceVarMap) + end; + alias -> + race_var_map(NewVars1, cerl:alias_var(NewVars2), + RaceVarMap, Op); + values -> + race_var_map(NewVars1, cerl:values_es(NewVars2), + RaceVarMap, Op); + _Other -> RaceVarMap + end; + tuple -> + case cerl:type(NewVars2) of + tuple -> + race_var_map(cerl:tuple_es(NewVars1), + cerl:tuple_es(NewVars2), RaceVarMap, Op); + alias -> + race_var_map(NewVars1, cerl:alias_var(NewVars2), + RaceVarMap, Op); + values -> + race_var_map(NewVars1, cerl:values_es(NewVars2), + RaceVarMap, Op); + _Other -> RaceVarMap + end; + cons -> + case cerl:type(NewVars2) of + cons -> + NewRaceVarMap = race_var_map(cerl:cons_hd(NewVars1), + cerl:cons_hd(NewVars2), RaceVarMap, Op), + race_var_map(cerl:cons_tl(NewVars1), + cerl:cons_tl(NewVars2), NewRaceVarMap, Op); + alias -> + race_var_map(NewVars1, cerl:alias_var(NewVars2), + RaceVarMap, Op); + values -> + race_var_map(NewVars1, cerl:values_es(NewVars2), + RaceVarMap, Op); + _Other -> RaceVarMap + end; + alias -> + case cerl:type(NewVars2) of + alias -> + race_var_map(cerl:alias_var(NewVars1), + cerl:alias_var(NewVars2), RaceVarMap, Op); + _Other -> + race_var_map(cerl:alias_var(NewVars1), + NewVars2, RaceVarMap, Op) + end; + values -> + case cerl:type(NewVars2) of + values -> + race_var_map(cerl:values_es(NewVars1), + cerl:values_es(NewVars2), RaceVarMap, Op); + _Other -> + race_var_map(cerl:values_es(NewVars1), + NewVars2, RaceVarMap, Op) + end; + _Other -> RaceVarMap + end; + false -> RaceVarMap + end + end + end. + +race_var_map_clauses(Clauses, RaceVarMap) -> + case Clauses of + [] -> RaceVarMap; + [#end_clause{arg = Arg, pats = Pats, guard = Guard}|T] -> + {RaceVarMap1, _RemoveClause} = + race_var_map_guard(Arg, Pats, Guard, RaceVarMap, bind), + race_var_map_clauses(T, RaceVarMap1) + end. + +race_var_map_guard(Arg, Pats, Guard, RaceVarMap, Op) -> + {NewRaceVarMap, RemoveClause} = + case cerl:type(Guard) of + call -> + CallName = cerl:call_name(Guard), + case cerl:is_literal(CallName) of + true -> + case cerl:concrete(CallName) of + '=:=' -> + [Arg1, Arg2] = cerl:call_args(Guard), + {race_var_map(Arg1, Arg2, RaceVarMap, Op), false}; + '==' -> + [Arg1, Arg2] = cerl:call_args(Guard), + {race_var_map(Arg1, Arg2, RaceVarMap, Op), false}; + '=/=' -> + case Op of + bind -> + [Arg1, Arg2] = cerl:call_args(Guard), + {RaceVarMap, are_bound_vars(Arg1, Arg2, RaceVarMap)}; + unbind -> {RaceVarMap, false} + end; + _Other -> {RaceVarMap, false} + end; + false -> {RaceVarMap, false} + end; + _Other -> {RaceVarMap, false} + end, + {RaceVarMap1, RemoveClause1} = + race_var_map_guard_helper1(Arg, Pats, + race_var_map(Arg, Pats, NewRaceVarMap, Op), Op), + {RaceVarMap1, RemoveClause orelse RemoveClause1}. + +race_var_map_guard_helper1(Arg, Pats, RaceVarMap, Op) -> + case Arg =:= ?no_arg orelse Arg =:= ?bypassed of + true -> {RaceVarMap, false}; + false -> + case cerl:type(Arg) of + call -> + case Pats of + [NewPat] -> + ModName = cerl:call_module(Arg), + CallName = cerl:call_name(Arg), + case cerl:is_literal(ModName) andalso + cerl:is_literal(CallName) of + true -> + case {cerl:concrete(ModName), + cerl:concrete(CallName)} of + {erlang, '=:='} -> + race_var_map_guard_helper2(Arg, NewPat, true, + RaceVarMap, Op); + {erlang, '=='} -> + race_var_map_guard_helper2(Arg, NewPat, true, + RaceVarMap, Op); + {erlang, '=/='} -> + race_var_map_guard_helper2(Arg, NewPat, false, + RaceVarMap, Op); + _Else -> {RaceVarMap, false} + end; + false -> {RaceVarMap, false} + end; + _Other -> {RaceVarMap, false} + end; + _Other -> {RaceVarMap, false} + end + end. + +race_var_map_guard_helper2(Arg, Pat0, Bool, RaceVarMap, Op) -> + Pat = cerl:fold_literal(Pat0), + case cerl:type(Pat) of + literal -> + [Arg1, Arg2] = cerl:call_args(Arg), + case cerl:concrete(Pat) of + Bool -> + {race_var_map(Arg1, Arg2, RaceVarMap, Op), false}; + _Else -> + case Op of + bind -> + {RaceVarMap, are_bound_vars(Arg1, Arg2, RaceVarMap)}; + unbind -> {RaceVarMap, false} + end + end; + _Else -> {RaceVarMap, false} + end. + +unbind_dict_vars(Var, Var, RaceVarMap) -> + RaceVarMap; +unbind_dict_vars(Var1, Var2, RaceVarMap) -> + case dict:find(Var1, RaceVarMap) of + error -> RaceVarMap; + {ok, Labels} -> + case Labels of + [] -> dict:erase(Var1, RaceVarMap); + _Else -> + case lists:member(Var2, Labels) of + true -> + unbind_dict_vars(Var1, Var2, + bind_dict_vars_list(Var1, Labels -- [Var2], + dict:erase(Var1, RaceVarMap))); + false -> + unbind_dict_vars_helper(Labels, Var1, Var2, RaceVarMap) + end + end + end. + +unbind_dict_vars_helper(Labels, Key, CompLabel, RaceVarMap) -> + case dict:size(RaceVarMap) of + 0 -> RaceVarMap; + _ -> + case Labels of + [] -> RaceVarMap; + [Head|Tail] -> + NewRaceVarMap = + case are_bound_labels(Head, CompLabel, RaceVarMap) orelse + are_bound_labels(CompLabel, Head, RaceVarMap) of + true -> + bind_dict_vars_list(Key, Labels -- [Head], + dict:erase(Key, RaceVarMap)); + false -> RaceVarMap + end, + unbind_dict_vars_helper(Tail, Key, CompLabel, NewRaceVarMap) + end + end. + +var_analysis(FunDefArgs, FunCallArgs, WarnVarArgs, RaceWarnTag) -> + case RaceWarnTag of + ?WARN_WHEREIS_REGISTER -> + [WVA1, WVA2, WVA3, WVA4] = WarnVarArgs, + ArgNos = lists_key_members_lists(WVA1, FunDefArgs), + [[lists_get(N, FunCallArgs) || N <- ArgNos], WVA2, WVA3, WVA4]; + ?WARN_WHEREIS_UNREGISTER -> + [WVA1, WVA2] = WarnVarArgs, + ArgNos = lists_key_members_lists(WVA1, FunDefArgs), + [[lists_get(N, FunCallArgs) || N <- ArgNos], WVA2]; + ?WARN_ETS_LOOKUP_INSERT -> + [WVA1, WVA2, WVA3, WVA4] = WarnVarArgs, + ArgNos1 = lists_key_members_lists(WVA1, FunDefArgs), + ArgNos2 = lists_key_members_lists(WVA3, FunDefArgs), + [[lists_get(N1, FunCallArgs) || N1 <- ArgNos1], WVA2, + [lists_get(N2, FunCallArgs) || N2 <- ArgNos2], WVA4]; + ?WARN_MNESIA_DIRTY_READ_WRITE -> + [WVA1, WVA2|T] = WarnVarArgs, + ArgNos = lists_key_members_lists(WVA1, FunDefArgs), + [[lists_get(N, FunCallArgs) || N <- ArgNos], WVA2|T] + end. + +var_type_analysis(FunDefArgs, FunCallTypes, WarnVarArgs, RaceWarnTag, + RaceVarMap, CleanState) -> + FunVarArgs = format_args(FunDefArgs, FunCallTypes, CleanState, function_call), + case RaceWarnTag of + ?WARN_WHEREIS_REGISTER -> + [WVA1, WVA2, WVA3, WVA4] = WarnVarArgs, + Vars = find_all_bound_vars(WVA1, RaceVarMap), + case lists_key_member_lists(Vars, FunVarArgs) of + 0 -> [Vars, WVA2, WVA3, WVA4]; + N when is_integer(N) -> + NewWVA2 = string:tokens(lists:nth(N + 1, FunVarArgs), " |"), + [Vars, NewWVA2, WVA3, WVA4] + end; + ?WARN_WHEREIS_UNREGISTER -> + [WVA1, WVA2] = WarnVarArgs, + Vars = find_all_bound_vars(WVA1, RaceVarMap), + case lists_key_member_lists(Vars, FunVarArgs) of + 0 -> [Vars, WVA2]; + N when is_integer(N) -> + NewWVA2 = string:tokens(lists:nth(N + 1, FunVarArgs), " |"), + [Vars, NewWVA2] + end; + ?WARN_ETS_LOOKUP_INSERT -> + [WVA1, WVA2, WVA3, WVA4] = WarnVarArgs, + Vars1 = find_all_bound_vars(WVA1, RaceVarMap), + FirstVarArg = + case lists_key_member_lists(Vars1, FunVarArgs) of + 0 -> [Vars1, WVA2]; + N1 when is_integer(N1) -> + NewWVA2 = string:tokens(lists:nth(N1 + 1, FunVarArgs), " |"), + [Vars1, NewWVA2] + end, + Vars2 = + lists:flatten( + [find_all_bound_vars(A, RaceVarMap) || A <- ets_list_args(WVA3)]), + case lists_key_member_lists(Vars2, FunVarArgs) of + 0 -> FirstVarArg ++ [Vars2, WVA4]; + N2 when is_integer(N2) -> + NewWVA4 = + ets_tuple_argtypes2( + ets_tuple_argtypes1(lists:nth(N2 + 1, FunVarArgs), [], [], 0), + []), + FirstVarArg ++ [Vars2, NewWVA4] + + end; + ?WARN_MNESIA_DIRTY_READ_WRITE -> + [WVA1, WVA2|T] = WarnVarArgs, + Arity = + case T of + [] -> 1; + _Else -> 2 + end, + Vars = find_all_bound_vars(WVA1, RaceVarMap), + case lists_key_member_lists(Vars, FunVarArgs) of + 0 -> [Vars, WVA2|T]; + N when is_integer(N) -> + NewWVA2 = + case Arity of + 1 -> + [mnesia_record_tab(R) || R <- string:tokens( + lists:nth(2, FunVarArgs), " |")]; + 2 -> + string:tokens(lists:nth(N + 1, FunVarArgs), " |") + end, + [Vars, NewWVA2|T] + end + end. + +%%% =========================================================================== +%%% +%%% Warning Format Utilities +%%% +%%% =========================================================================== + +add_race_warning(Warn, #races{race_warnings = Warns} = Races) -> + Races#races{race_warnings = [Warn|Warns]}. + +get_race_warn(Fun, Args, ArgTypes, DepList, State) -> + {M, F, _A} = Fun, + case DepList of + [] -> {State, no_race}; + _Other -> + {State, {race_condition, [M, F, Args, ArgTypes, State, DepList]}} + end. + +-spec get_race_warnings(races(), dialyzer_dataflow:state()) -> + {races(), dialyzer_dataflow:state()}. + +get_race_warnings(#races{race_warnings = RaceWarnings}, State) -> + get_race_warnings_helper(RaceWarnings, State). + +get_race_warnings_helper(Warnings, State) -> + case Warnings of + [] -> + {dialyzer_dataflow:state__get_races(State), State}; + [H|T] -> + {RaceWarnTag, WarningInfo, {race_condition, [M, F, A, AT, S, DepList]}} = H, + Reason = + case RaceWarnTag of + ?WARN_WHEREIS_REGISTER -> + get_reason(lists:keysort(7, DepList), + "might fail due to a possible race condition " + "caused by its combination with "); + ?WARN_WHEREIS_UNREGISTER -> + get_reason(lists:keysort(7, DepList), + "might fail due to a possible race condition " + "caused by its combination with "); + ?WARN_ETS_LOOKUP_INSERT -> + get_reason(lists:keysort(7, DepList), + "might have an unintended effect due to " ++ + "a possible race condition " ++ + "caused by its combination with "); + ?WARN_MNESIA_DIRTY_READ_WRITE -> + get_reason(lists:keysort(7, DepList), + "might have an unintended effect due to " ++ + "a possible race condition " ++ + "caused by its combination with ") + end, + W = + {?WARN_RACE_CONDITION, WarningInfo, + {race_condition, + [M, F, dialyzer_dataflow:format_args(A, AT, S), Reason]}}, + get_race_warnings_helper(T, + dialyzer_dataflow:state__add_warning(W, State)) + end. + +get_reason(DependencyList, Reason) -> + case DependencyList of + [] -> ""; + [#dep_call{call_name = Call, arg_types = ArgTypes, vars = Args, + state = State, file_line = {File, Line}}|T] -> + R = + Reason ++ + case Call of + whereis -> "the erlang:whereis"; + ets_lookup -> "the ets:lookup"; + mnesia_dirty_read -> "the mnesia:dirty_read" + end ++ + dialyzer_dataflow:format_args(Args, ArgTypes, State) ++ + " call in " ++ + filename:basename(File) ++ + " on line " ++ + lists:flatten(io_lib:write(Line)), + case T of + [] -> R; + _ -> get_reason(T, R ++ ", ") + end + end. + +state__add_race_warning(State, RaceWarn, RaceWarnTag, WarningInfo) -> + case RaceWarn of + no_race -> State; + _Else -> + Races = dialyzer_dataflow:state__get_races(State), + Warn = {RaceWarnTag, WarningInfo, RaceWarn}, + dialyzer_dataflow:state__put_races(add_race_warning(Warn, Races), State) + end. + +%%% =========================================================================== +%%% +%%% Record Interfaces +%%% +%%% =========================================================================== + +-spec beg_clause_new(var_to_map1(), var_to_map1(), cerl:cerl()) -> + #beg_clause{}. + +beg_clause_new(Arg, Pats, Guard) -> + #beg_clause{arg = Arg, pats = Pats, guard = Guard}. + +-spec cleanup(races()) -> races(). + +cleanup(#races{race_list = RaceList}) -> + #races{race_list = RaceList}. + +-spec end_case_new([#end_clause{}]) -> #end_case{}. + +end_case_new(Clauses) -> + #end_case{clauses = Clauses}. + +-spec end_clause_new(var_to_map1(), var_to_map1(), cerl:cerl()) -> + #end_clause{}. + +end_clause_new(Arg, Pats, Guard) -> + #end_clause{arg = Arg, pats = Pats, guard = Guard}. + +-spec get_curr_fun(races()) -> dialyzer_callgraph:mfa_or_funlbl(). + +get_curr_fun(#races{curr_fun = CurrFun}) -> + CurrFun. + +-spec get_curr_fun_args(races()) -> core_args(). + +get_curr_fun_args(#races{curr_fun_args = CurrFunArgs}) -> + CurrFunArgs. + +-spec get_new_table(races()) -> table(). + +get_new_table(#races{new_table = Table}) -> + Table. + +-spec get_race_analysis(races()) -> boolean(). + +get_race_analysis(#races{race_analysis = RaceAnalysis}) -> + RaceAnalysis. + +-spec get_race_list(races()) -> code(). + +get_race_list(#races{race_list = RaceList}) -> + RaceList. + +-spec get_race_list_size(races()) -> non_neg_integer(). + +get_race_list_size(#races{race_list_size = RaceListSize}) -> + RaceListSize. + +-spec get_race_list_and_size(races()) -> {code(), non_neg_integer()}. + +get_race_list_and_size(#races{race_list = RaceList, + race_list_size = RaceListSize}) -> + {RaceList, RaceListSize}. + +-spec let_tag_new(var_to_map1(), var_to_map1()) -> #let_tag{}. + +let_tag_new(Var, Arg) -> + #let_tag{var = Var, arg = Arg}. + +-spec new() -> races(). + +new() -> #races{}. + +-spec put_curr_fun(dialyzer_callgraph:mfa_or_funlbl(), label(), races()) -> + races(). + +put_curr_fun(CurrFun, CurrFunLabel, Races) -> + Races#races{curr_fun = CurrFun, + curr_fun_label = CurrFunLabel, + curr_fun_args = empty}. + +-spec put_fun_args(core_args(), races()) -> races(). + +put_fun_args(Args, #races{curr_fun_args = CurrFunArgs} = Races) -> + case CurrFunArgs of + empty -> Races#races{curr_fun_args = Args}; + _Other -> Races + end. + +-spec put_race_analysis(boolean(), races()) -> + races(). + +put_race_analysis(Analysis, Races) -> + Races#races{race_analysis = Analysis}. + +-spec put_race_list(code(), non_neg_integer(), races()) -> + races(). + +put_race_list(RaceList, RaceListSize, Races) -> + Races#races{race_list = RaceList, race_list_size = RaceListSize}. diff --git a/lib/dialyzer/test/opaque_SUITE_data/src/recrec/erl_types.erl b/lib/dialyzer/test/opaque_SUITE_data/src/recrec/erl_types.erl new file mode 100644 index 0000000000..7826dada9d --- /dev/null +++ b/lib/dialyzer/test/opaque_SUITE_data/src/recrec/erl_types.erl @@ -0,0 +1,5741 @@ +%% -*- erlang-indent-level: 2 -*- +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2003-2016. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% +%% +%% ====================================================================== +%% Copyright (C) 2000-2003 Richard Carlsson +%% +%% ====================================================================== +%% Provides a representation of Erlang types. +%% +%% The initial author of this file is Richard Carlsson (2000-2004). +%% In July 2006, the type representation was totally re-designed by +%% Tobias Lindahl. This is the representation which is used currently. +%% In late 2008, Manouk Manoukian and Kostis Sagonas added support for +%% opaque types to the structure-based representation of types. +%% During February and March 2009, Kostis Sagonas significantly +%% cleaned up the type representation and added spec declarations. +%% +%% ====================================================================== + +-module(erl_types). + +-export([any_none/1, + any_none_or_unit/1, + lookup_record/3, + max/2, + min/2, + number_max/1, number_max/2, + number_min/1, number_min/2, + t_abstract_records/2, + t_any/0, + t_arity/0, + t_atom/0, + t_atom/1, + t_atoms/1, + t_atom_vals/1, t_atom_vals/2, + t_binary/0, + t_bitstr/0, + t_bitstr/2, + t_bitstr_base/1, + t_bitstr_concat/1, + t_bitstr_concat/2, + t_bitstr_match/2, + t_bitstr_unit/1, + t_bitstrlist/0, + t_boolean/0, + t_byte/0, + t_char/0, + t_collect_vars/1, + t_cons/0, + t_cons/2, + t_cons_hd/1, t_cons_hd/2, + t_cons_tl/1, t_cons_tl/2, + t_contains_opaque/1, t_contains_opaque/2, + t_decorate_with_opaque/3, + t_elements/1, + t_find_opaque_mismatch/3, + t_find_unknown_opaque/3, + t_fixnum/0, + t_map/2, + t_non_neg_fixnum/0, + t_pos_fixnum/0, + t_float/0, + t_var_names/1, + t_form_to_string/1, + t_from_form/6, + t_from_form_without_remote/3, + t_check_record_fields/6, + t_from_range/2, + t_from_range_unsafe/2, + t_from_term/1, + t_fun/0, + t_fun/1, + t_fun/2, + t_fun_args/1, t_fun_args/2, + t_fun_arity/1, t_fun_arity/2, + t_fun_range/1, t_fun_range/2, + t_has_opaque_subtype/2, + t_has_var/1, + t_identifier/0, + %% t_improper_list/2, + t_inf/1, + t_inf/2, + t_inf/3, + t_inf_lists/2, + t_inf_lists/3, + t_integer/0, + t_integer/1, + t_non_neg_integer/0, + t_pos_integer/0, + t_integers/1, + t_iodata/0, + t_iolist/0, + t_is_any/1, + t_is_atom/1, t_is_atom/2, + t_is_any_atom/2, t_is_any_atom/3, + t_is_binary/1, t_is_binary/2, + t_is_bitstr/1, t_is_bitstr/2, + t_is_bitwidth/1, + t_is_boolean/1, t_is_boolean/2, + %% t_is_byte/1, + %% t_is_char/1, + t_is_cons/1, t_is_cons/2, + t_is_equal/2, + t_is_fixnum/1, + t_is_float/1, t_is_float/2, + t_is_fun/1, t_is_fun/2, + t_is_instance/2, + t_is_integer/1, t_is_integer/2, + t_is_list/1, + t_is_map/1, + t_is_map/2, + t_is_matchstate/1, + t_is_nil/1, t_is_nil/2, + t_is_non_neg_integer/1, + t_is_none/1, + t_is_none_or_unit/1, + t_is_number/1, t_is_number/2, + t_is_opaque/1, t_is_opaque/2, + t_is_pid/1, t_is_pid/2, + t_is_port/1, t_is_port/2, + t_is_maybe_improper_list/1, t_is_maybe_improper_list/2, + t_is_reference/1, t_is_reference/2, + t_is_singleton/1, + t_is_singleton/2, + t_is_string/1, + t_is_subtype/2, + t_is_tuple/1, t_is_tuple/2, + t_is_unit/1, + t_is_var/1, + t_limit/2, + t_list/0, + t_list/1, + t_list_elements/1, t_list_elements/2, + t_list_termination/1, t_list_termination/2, + t_map/0, + t_map/1, + t_map/3, + t_map_entries/2, t_map_entries/1, + t_map_def_key/2, t_map_def_key/1, + t_map_def_val/2, t_map_def_val/1, + t_map_get/2, t_map_get/3, + t_map_is_key/2, t_map_is_key/3, + t_map_update/2, t_map_update/3, + t_map_put/2, t_map_put/3, + t_matchstate/0, + t_matchstate/2, + t_matchstate_present/1, + t_matchstate_slot/2, + t_matchstate_slots/1, + t_matchstate_update_present/2, + t_matchstate_update_slot/3, + t_mfa/0, + t_module/0, + t_nil/0, + t_node/0, + t_none/0, + t_nonempty_list/0, + t_nonempty_list/1, + t_nonempty_string/0, + t_number/0, + t_number/1, + t_number_vals/1, t_number_vals/2, + t_opaque_from_records/1, + t_opaque_structure/1, + t_pid/0, + t_port/0, + t_maybe_improper_list/0, + %% t_maybe_improper_list/2, + t_product/1, + t_reference/0, + t_singleton_to_term/2, + t_string/0, + t_struct_from_opaque/2, + t_subst/2, + t_subtract/2, + t_subtract_list/2, + t_sup/1, + t_sup/2, + t_timeout/0, + t_to_string/1, + t_to_string/2, + t_to_tlist/1, + t_tuple/0, + t_tuple/1, + t_tuple_args/1, t_tuple_args/2, + t_tuple_size/1, t_tuple_size/2, + t_tuple_sizes/1, + t_tuple_subtypes/1, + t_tuple_subtypes/2, + t_unify/2, + t_unit/0, + t_unopaque/1, t_unopaque/2, + t_var/1, + t_var_name/1, + %% t_assign_variables_to_subtype/2, + type_is_defined/4, + record_field_diffs_to_string/2, + subst_all_vars_to_any/1, + lift_list_to_pos_empty/1, lift_list_to_pos_empty/2, + is_opaque_type/2, + is_erl_type/1, + atom_to_string/1, + var_table__new/0, + cache__new/0, + map_pairwise_merge/3 + ]). + +%%-define(DO_ERL_TYPES_TEST, true). +-compile({no_auto_import,[min/2,max/2]}). + +-ifdef(DO_ERL_TYPES_TEST). +-export([test/0]). +-else. +-define(NO_UNUSED, true). +-endif. + +-ifndef(NO_UNUSED). +-export([t_is_identifier/1]). +-endif. + +-export_type([erl_type/0, opaques/0, type_table/0, var_table/0, cache/0]). + +%%-define(DEBUG, true). + +-ifdef(DEBUG). +-define(debug(__A), __A). +-else. +-define(debug(__A), ok). +-endif. + +%%============================================================================= +%% +%% Definition of the type structure +%% +%%============================================================================= + +%%----------------------------------------------------------------------------- +%% Limits +%% + +-define(REC_TYPE_LIMIT, 2). +-define(EXPAND_DEPTH, 16). +-define(EXPAND_LIMIT, 10000). + +-define(TUPLE_TAG_LIMIT, 5). +-define(TUPLE_ARITY_LIMIT, 8). +-define(SET_LIMIT, 13). +-define(MAX_BYTE, 255). +-define(MAX_CHAR, 16#10ffff). + +-define(UNIT_MULTIPLIER, 8). + +-define(TAG_IMMED1_SIZE, 4). +-define(BITS, (erlang:system_info(wordsize) * 8) - ?TAG_IMMED1_SIZE). + +-define(MAX_TUPLE_SIZE, (1 bsl 10)). + +%%----------------------------------------------------------------------------- +%% Type tags and qualifiers +%% + +-define(atom_tag, atom). +-define(binary_tag, binary). +-define(function_tag, function). +-define(identifier_tag, identifier). +-define(list_tag, list). +-define(map_tag, map). +-define(matchstate_tag, matchstate). +-define(nil_tag, nil). +-define(number_tag, number). +-define(opaque_tag, opaque). +-define(product_tag, product). +-define(tuple_set_tag, tuple_set). +-define(tuple_tag, tuple). +-define(union_tag, union). +-define(var_tag, var). + +-type tag() :: ?atom_tag | ?binary_tag | ?function_tag | ?identifier_tag + | ?list_tag | ?map_tag | ?matchstate_tag | ?nil_tag | ?number_tag + | ?opaque_tag | ?product_tag + | ?tuple_tag | ?tuple_set_tag | ?union_tag | ?var_tag. + +-define(float_qual, float). +-define(integer_qual, integer). +-define(nonempty_qual, nonempty). +-define(pid_qual, pid). +-define(port_qual, port). +-define(reference_qual, reference). +-define(unknown_qual, unknown). + +-type qual() :: ?float_qual | ?integer_qual | ?nonempty_qual | ?pid_qual + | ?port_qual | ?reference_qual | ?unknown_qual | {_, _}. + +%%----------------------------------------------------------------------------- +%% The type representation +%% + +-define(any, any). +-define(none, none). +-define(unit, unit). +%% Generic constructor - elements can be many things depending on the tag. +-record(c, {tag :: tag(), + elements = [] :: term(), + qualifier = ?unknown_qual :: qual()}). + +-opaque erl_type() :: ?any | ?none | ?unit | #c{}. + +%%----------------------------------------------------------------------------- +%% Auxiliary types and convenient macros +%% + +-type parse_form() :: erl_parse:abstract_type(). +-type rng_elem() :: 'pos_inf' | 'neg_inf' | integer(). + +-record(int_set, {set :: [integer()]}). +-record(int_rng, {from :: rng_elem(), to :: rng_elem()}). +%% Note: the definition of #opaque{} was changed to 'mod' and 'name'; +%% it used to be an ordsets of {Mod, Name} pairs. The Dialyzer version +%% was updated to 2.7 due to this change. +-record(opaque, {mod :: module(), name :: atom(), + args = [] :: [erl_type()], struct :: erl_type()}). + +-define(atom(Set), #c{tag=?atom_tag, elements=Set}). +-define(bitstr(Unit, Base), #c{tag=?binary_tag, elements=[Unit,Base]}). +-define(float, ?number(?any, ?float_qual)). +-define(function(Domain, Range), #c{tag=?function_tag, + elements=[Domain, Range]}). +-define(identifier(Types), #c{tag=?identifier_tag, elements=Types}). +-define(integer(Types), ?number(Types, ?integer_qual)). +-define(int_range(From, To), ?integer(#int_rng{from=From, to=To})). +-define(int_set(Set), ?integer(#int_set{set=Set})). +-define(list(Types, Term, Size), #c{tag=?list_tag, elements=[Types,Term], + qualifier=Size}). +-define(nil, #c{tag=?nil_tag}). +-define(nonempty_list(Types, Term),?list(Types, Term, ?nonempty_qual)). +-define(number(Set, Qualifier), #c{tag=?number_tag, elements=Set, + qualifier=Qualifier}). +-define(map(Pairs,DefKey,DefVal), + #c{tag=?map_tag, elements={Pairs,DefKey,DefVal}}). +-define(opaque(Optypes), #c{tag=?opaque_tag, elements=Optypes}). +-define(product(Types), #c{tag=?product_tag, elements=Types}). +-define(tuple(Types, Arity, Qual), #c{tag=?tuple_tag, elements=Types, + qualifier={Arity, Qual}}). +-define(tuple_set(Tuples), #c{tag=?tuple_set_tag, elements=Tuples}). +-define(var(Id), #c{tag=?var_tag, elements=Id}). + +-define(matchstate(P, Slots), #c{tag=?matchstate_tag, elements=[P,Slots]}). +-define(any_matchstate, ?matchstate(t_bitstr(), ?any)). + +-define(byte, ?int_range(0, ?MAX_BYTE)). +-define(char, ?int_range(0, ?MAX_CHAR)). +-define(integer_pos, ?int_range(1, pos_inf)). +-define(integer_non_neg, ?int_range(0, pos_inf)). +-define(integer_neg, ?int_range(neg_inf, -1)). + +-type opaques() :: [erl_type()] | 'universe'. + +-type record_key() :: {'record', atom()}. +-type type_key() :: {'type' | 'opaque', mfa()}. +-type record_value() :: [{atom(), erl_parse:abstract_expr(), erl_type()}]. +-type type_value() :: {{module(), {file:name(), erl_anno:line()}, + erl_parse:abstract_type(), ArgNames :: [atom()]}, + erl_type()}. +-type type_table() :: dict:dict(record_key() | type_key(), + record_value() | type_value()). + +-opaque var_table() :: #{atom() => erl_type()}. + +%%----------------------------------------------------------------------------- +%% Unions +%% + +-define(union(List), #c{tag=?union_tag, elements=[_,_,_,_,_,_,_,_,_,_]=List}). + +-define(atom_union(T), ?union([T,?none,?none,?none,?none,?none,?none,?none,?none,?none])). +-define(bitstr_union(T), ?union([?none,T,?none,?none,?none,?none,?none,?none,?none,?none])). +-define(function_union(T), ?union([?none,?none,T,?none,?none,?none,?none,?none,?none,?none])). +-define(identifier_union(T), ?union([?none,?none,?none,T,?none,?none,?none,?none,?none,?none])). +-define(list_union(T), ?union([?none,?none,?none,?none,T,?none,?none,?none,?none,?none])). +-define(number_union(T), ?union([?none,?none,?none,?none,?none,T,?none,?none,?none,?none])). +-define(tuple_union(T), ?union([?none,?none,?none,?none,?none,?none,T,?none,?none,?none])). +-define(matchstate_union(T), ?union([?none,?none,?none,?none,?none,?none,?none,T,?none,?none])). +-define(opaque_union(T), ?union([?none,?none,?none,?none,?none,?none,?none,?none,T,?none])). +-define(map_union(T), ?union([?none,?none,?none,?none,?none,?none,?none,?none,?none,T])). +-define(integer_union(T), ?number_union(T)). +-define(float_union(T), ?number_union(T)). +-define(nil_union(T), ?list_union(T)). + + +%%============================================================================= +%% +%% Primitive operations such as type construction and type tests +%% +%%============================================================================= + +%%----------------------------------------------------------------------------- +%% Top and bottom +%% + +-spec t_any() -> erl_type(). + +t_any() -> + ?any. + +-spec t_is_any(erl_type()) -> boolean(). + +t_is_any(Type) -> + do_opaque(Type, 'universe', fun is_any/1). + +is_any(?any) -> true; +is_any(_) -> false. + +-spec t_none() -> erl_type(). + +t_none() -> + ?none. + +-spec t_is_none(erl_type()) -> boolean(). + +t_is_none(?none) -> true; +t_is_none(_) -> false. + +%%----------------------------------------------------------------------------- +%% Opaque types +%% + +-spec t_opaque(module(), atom(), [_], erl_type()) -> erl_type(). + +t_opaque(Mod, Name, Args, Struct) -> + O = #opaque{mod = Mod, name = Name, args = Args, struct = Struct}, + ?opaque(set_singleton(O)). + +-spec t_is_opaque(erl_type(), [erl_type()]) -> boolean(). + +t_is_opaque(?opaque(_) = Type, Opaques) -> + not is_opaque_type(Type, Opaques); +t_is_opaque(_Type, _Opaques) -> false. + +-spec t_is_opaque(erl_type()) -> boolean(). + +t_is_opaque(?opaque(_)) -> true; +t_is_opaque(_) -> false. + +-spec t_has_opaque_subtype(erl_type(), opaques()) -> boolean(). + +t_has_opaque_subtype(Type, Opaques) -> + do_opaque(Type, Opaques, fun has_opaque_subtype/1). + +has_opaque_subtype(?union(Ts)) -> + lists:any(fun t_is_opaque/1, Ts); +has_opaque_subtype(T) -> + t_is_opaque(T). + +-spec t_opaque_structure(erl_type()) -> erl_type(). + +t_opaque_structure(?opaque(Elements)) -> + t_sup([Struct || #opaque{struct = Struct} <- ordsets:to_list(Elements)]). + +-spec t_contains_opaque(erl_type()) -> boolean(). + +t_contains_opaque(Type) -> + t_contains_opaque(Type, []). + +%% Returns 'true' iff there is an opaque type that is *not* one of +%% the types of the second argument. + +-spec t_contains_opaque(erl_type(), [erl_type()]) -> boolean(). + +t_contains_opaque(?any, _Opaques) -> false; +t_contains_opaque(?none, _Opaques) -> false; +t_contains_opaque(?unit, _Opaques) -> false; +t_contains_opaque(?atom(_Set), _Opaques) -> false; +t_contains_opaque(?bitstr(_Unit, _Base), _Opaques) -> false; +t_contains_opaque(?float, _Opaques) -> false; +t_contains_opaque(?function(Domain, Range), Opaques) -> + t_contains_opaque(Domain, Opaques) + orelse t_contains_opaque(Range, Opaques); +t_contains_opaque(?identifier(_Types), _Opaques) -> false; +t_contains_opaque(?integer(_Types), _Opaques) -> false; +t_contains_opaque(?int_range(_From, _To), _Opaques) -> false; +t_contains_opaque(?int_set(_Set), _Opaques) -> false; +t_contains_opaque(?list(Type, Tail, _), Opaques) -> + t_contains_opaque(Type, Opaques) orelse t_contains_opaque(Tail, Opaques); +t_contains_opaque(?map(_, _, _) = Map, Opaques) -> + list_contains_opaque(map_all_types(Map), Opaques); +t_contains_opaque(?matchstate(_P, _Slots), _Opaques) -> false; +t_contains_opaque(?nil, _Opaques) -> false; +t_contains_opaque(?number(_Set, _Tag), _Opaques) -> false; +t_contains_opaque(?opaque(_)=T, Opaques) -> + not is_opaque_type(T, Opaques) + orelse t_contains_opaque(t_opaque_structure(T)); +t_contains_opaque(?product(Types), Opaques) -> + list_contains_opaque(Types, Opaques); +t_contains_opaque(?tuple(?any, _, _), _Opaques) -> false; +t_contains_opaque(?tuple(Types, _, _), Opaques) -> + list_contains_opaque(Types, Opaques); +t_contains_opaque(?tuple_set(_Set) = T, Opaques) -> + list_contains_opaque(t_tuple_subtypes(T), Opaques); +t_contains_opaque(?union(List), Opaques) -> + list_contains_opaque(List, Opaques); +t_contains_opaque(?var(_Id), _Opaques) -> false. + +-spec list_contains_opaque([erl_type()], [erl_type()]) -> boolean(). + +list_contains_opaque(List, Opaques) -> + lists:any(fun(E) -> t_contains_opaque(E, Opaques) end, List). + +%% t_find_opaque_mismatch/2 of two types should only be used if their +%% t_inf is t_none() due to some opaque type violation. +%% +%% The first argument of the function is the pattern and its second +%% argument the type we are matching against the pattern. + +-spec t_find_opaque_mismatch(erl_type(), erl_type(), [erl_type()]) -> + 'error' | {'ok', erl_type(), erl_type()}. + +t_find_opaque_mismatch(T1, T2, Opaques) -> + t_find_opaque_mismatch(T1, T2, T2, Opaques). + +t_find_opaque_mismatch(?any, _Type, _TopType, _Opaques) -> error; +t_find_opaque_mismatch(?none, _Type, _TopType, _Opaques) -> error; +t_find_opaque_mismatch(?list(T1, Tl1, _), ?list(T2, Tl2, _), TopType, Opaques) -> + t_find_opaque_mismatch_ordlists([T1, Tl1], [T2, Tl2], TopType, Opaques); +t_find_opaque_mismatch(T1, ?opaque(_) = T2, TopType, Opaques) -> + case is_opaque_type(T2, Opaques) of + false -> {ok, TopType, T2}; + true -> + t_find_opaque_mismatch(T1, t_opaque_structure(T2), TopType, Opaques) + end; +t_find_opaque_mismatch(?opaque(_) = T1, T2, TopType, Opaques) -> + %% The generated message is somewhat misleading: + case is_opaque_type(T1, Opaques) of + false -> {ok, TopType, T1}; + true -> + t_find_opaque_mismatch(t_opaque_structure(T1), T2, TopType, Opaques) + end; +t_find_opaque_mismatch(?product(T1), ?product(T2), TopType, Opaques) -> + t_find_opaque_mismatch_ordlists(T1, T2, TopType, Opaques); +t_find_opaque_mismatch(?tuple(T1, Arity, _), ?tuple(T2, Arity, _), + TopType, Opaques) -> + t_find_opaque_mismatch_ordlists(T1, T2, TopType, Opaques); +t_find_opaque_mismatch(?tuple(_, _, _) = T1, ?tuple_set(_) = T2, + TopType, Opaques) -> + Tuples1 = t_tuple_subtypes(T1), + Tuples2 = t_tuple_subtypes(T2), + t_find_opaque_mismatch_lists(Tuples1, Tuples2, TopType, Opaques); +t_find_opaque_mismatch(T1, ?union(U2), TopType, Opaques) -> + t_find_opaque_mismatch_lists([T1], U2, TopType, Opaques); +t_find_opaque_mismatch(_T1, _T2, _TopType, _Opaques) -> error. + +t_find_opaque_mismatch_ordlists(L1, L2, TopType, Opaques) -> + List = lists:zipwith(fun(T1, T2) -> + t_find_opaque_mismatch(T1, T2, TopType, Opaques) + end, L1, L2), + t_find_opaque_mismatch_list(List). + +t_find_opaque_mismatch_lists(L1, L2, _TopType, Opaques) -> + List = [t_find_opaque_mismatch(T1, T2, T2, Opaques) || T1 <- L1, T2 <- L2], + t_find_opaque_mismatch_list(List). + +t_find_opaque_mismatch_list([]) -> error; +t_find_opaque_mismatch_list([H|T]) -> + case H of + {ok, _T1, _T2} -> H; + error -> t_find_opaque_mismatch_list(T) + end. + +-spec t_find_unknown_opaque(erl_type(), erl_type(), opaques()) -> + [pos_integer()]. + +%% The nice thing about using two types and t_inf() as compared to +%% calling t_contains_opaque/2 is that the traversal stops when +%% there is a mismatch which means that unknown opaque types "below" +%% the mismatch are not found. +t_find_unknown_opaque(_T1, _T2, 'universe') -> []; +t_find_unknown_opaque(T1, T2, Opaques) -> + try t_inf(T1, T2, {match, Opaques}) of + _ -> [] + catch throw:{pos, Ns} -> Ns + end. + +-spec t_decorate_with_opaque(erl_type(), erl_type(), [erl_type()]) -> erl_type(). + +%% The first argument can contain opaque types. The second argument +%% is assumed to be taken from the contract. + +t_decorate_with_opaque(T1, T2, Opaques) -> + case t_is_equal(T1, T2) orelse not t_contains_opaque(T2) of + true -> T1; + false -> + T = t_inf(T1, T2), + case t_contains_opaque(T) of + false -> T1; + true -> + R = decorate(T1, T, Opaques), + ?debug(case catch t_is_equal(t_unopaque(R), t_unopaque(T1)) of + true -> ok; + false -> + io:format("T1 = ~p,\n", [T1]), + io:format("T2 = ~p,\n", [T2]), + io:format("O = ~p,\n", [Opaques]), + io:format("erl_types:t_decorate_with_opaque(T1,T2,O).\n"), + throw({error, "Failed to handle opaque types"}) + end), + R + end + end. + +decorate(Type, ?none, _Opaques) -> Type; +decorate(?function(Domain, Range), ?function(D, R), Opaques) -> + ?function(decorate(Domain, D, Opaques), decorate(Range, R, Opaques)); +decorate(?list(Types, Tail, Size), ?list(Ts, Tl, _Sz), Opaques) -> + ?list(decorate(Types, Ts, Opaques), decorate(Tail, Tl, Opaques), Size); +decorate(?product(Types), ?product(Ts), Opaques) -> + ?product(list_decorate(Types, Ts, Opaques)); +decorate(?tuple(_, _, _)=T, ?tuple(?any, _, _), _Opaques) -> T; +decorate(?tuple(?any, _, _)=T, ?tuple(_, _, _), _Opaques) -> T; +decorate(?tuple(Types, Arity, Tag), ?tuple(Ts, Arity, _), Opaques) -> + ?tuple(list_decorate(Types, Ts, Opaques), Arity, Tag); +decorate(?tuple_set(List), ?tuple(_, Arity, _) = T, Opaques) -> + decorate_tuple_sets(List, [{Arity, [T]}], Opaques); +decorate(?tuple_set(List), ?tuple_set(L), Opaques) -> + decorate_tuple_sets(List, L, Opaques); +decorate(?union(List), T, Opaques) when T =/= ?any -> + ?union(L) = force_union(T), + union_decorate(List, L, Opaques); +decorate(?opaque(_)=T, _, _Opaques) -> T; +decorate(T, ?union(L), Opaques) when T =/= ?any -> + ?union(List) = force_union(T), + union_decorate(List, L, Opaques); +decorate(Type, ?opaque(_)=T, Opaques) -> + decorate_with_opaque(Type, T, Opaques); +decorate(Type, _T, _Opaques) -> Type. + +%% Note: it is important that #opaque.struct is a subtype of the +%% opaque type. +decorate_with_opaque(Type, ?opaque(Set2), Opaques) -> + case decoration(set_to_list(Set2), Type, Opaques, [], false) of + {[], false} -> Type; + {List, All} when List =/= [] -> + NewType = ?opaque(ordsets:from_list(List)), + case All of + true -> NewType; + false -> t_sup(NewType, Type) + end + end. + +decoration([#opaque{struct = S} = Opaque|OpaqueTypes], Type, Opaques, + NewOpaqueTypes0, All) -> + IsOpaque = is_opaque_type2(Opaque, Opaques), + I = t_inf(Type, S), + case not IsOpaque orelse t_is_none(I) of + true -> decoration(OpaqueTypes, Type, Opaques, NewOpaqueTypes0, All); + false -> + NewOpaque = Opaque#opaque{struct = decorate(I, S, Opaques)}, + NewAll = All orelse t_is_equal(I, Type), + NewOpaqueTypes = [NewOpaque|NewOpaqueTypes0], + decoration(OpaqueTypes, Type, Opaques, NewOpaqueTypes, NewAll) + end; +decoration([], _Type, _Opaques, NewOpaqueTypes, All) -> + {NewOpaqueTypes, All}. + +-spec list_decorate([erl_type()], [erl_type()], opaques()) -> [erl_type()]. + +list_decorate(List, L, Opaques) -> + [decorate(Elem, E, Opaques) || {Elem, E} <- lists:zip(List, L)]. + +union_decorate(U1, U2, Opaques) -> + Union = union_decorate(U1, U2, Opaques, 0, []), + [A,B,F,I,L,N,T,M,_,Map] = U1, + [_,_,_,_,_,_,_,_,Opaque,_] = U2, + List = [A,B,F,I,L,N,T,M,Map], + DecList = [Dec || + E <- List, + not t_is_none(E), + not t_is_none(Dec = decorate(E, Opaque, Opaques))], + t_sup([Union|DecList]). + +union_decorate([?none|Left1], [_|Left2], Opaques, N, Acc) -> + union_decorate(Left1, Left2, Opaques, N, [?none|Acc]); +union_decorate([T1|Left1], [?none|Left2], Opaques, N, Acc) -> + union_decorate(Left1, Left2, Opaques, N+1, [T1|Acc]); +union_decorate([T1|Left1], [T2|Left2], Opaques, N, Acc) -> + union_decorate(Left1, Left2, Opaques, N+1, [decorate(T1, T2, Opaques)|Acc]); +union_decorate([], [], _Opaques, N, Acc) -> + if N =:= 0 -> ?none; + N =:= 1 -> + [Type] = [T || T <- Acc, T =/= ?none], + Type; + N >= 2 -> ?union(lists:reverse(Acc)) + end. + +decorate_tuple_sets(List, L, Opaques) -> + decorate_tuple_sets(List, L, Opaques, []). + +decorate_tuple_sets([{Arity, Tuples}|List], [{Arity, Ts}|L], Opaques, Acc) -> + DecTs = decorate_tuples_in_sets(Tuples, Ts, Opaques), + decorate_tuple_sets(List, L, Opaques, [{Arity, DecTs}|Acc]); +decorate_tuple_sets([ArTup|List], L, Opaques, Acc) -> + decorate_tuple_sets(List, L, Opaques, [ArTup|Acc]); +decorate_tuple_sets([], _L, _Opaques, Acc) -> + ?tuple_set(lists:reverse(Acc)). + +decorate_tuples_in_sets([?tuple(Elements, _, ?any)], Ts, Opaques) -> + NewList = [list_decorate(Elements, Es, Opaques) || ?tuple(Es, _, _) <- Ts], + case t_sup([t_tuple(Es) || Es <- NewList]) of + ?tuple_set([{_Arity, Tuples}]) -> Tuples; + ?tuple(_, _, _)=Tuple -> [Tuple] + end; +decorate_tuples_in_sets(Tuples, Ts, Opaques) -> + decorate_tuples_in_sets(Tuples, Ts, Opaques, []). + +decorate_tuples_in_sets([?tuple(Elements, Arity, Tag1) = T1|Tuples] = L1, + [?tuple(Es, Arity, Tag2)|Ts] = L2, Opaques, Acc) -> + if + Tag1 < Tag2 -> decorate_tuples_in_sets(Tuples, L2, Opaques, [T1|Acc]); + Tag1 > Tag2 -> decorate_tuples_in_sets(L1, Ts, Opaques, Acc); + Tag1 =:= Tag2 -> + NewElements = list_decorate(Elements, Es, Opaques), + NewAcc = [?tuple(NewElements, Arity, Tag1)|Acc], + decorate_tuples_in_sets(Tuples, Ts, Opaques, NewAcc) + end; +decorate_tuples_in_sets([T1|Tuples], L2, Opaques, Acc) -> + decorate_tuples_in_sets(Tuples, L2, Opaques, [T1|Acc]); +decorate_tuples_in_sets([], _L, _Opaques, Acc) -> + lists:reverse(Acc). + +-spec t_opaque_from_records(type_table()) -> [erl_type()]. + +t_opaque_from_records(RecDict) -> + OpaqueRecDict = + dict:filter(fun(Key, _Value) -> + case Key of + {opaque, _Name, _Arity} -> true; + _ -> false + end + end, RecDict), + OpaqueTypeDict = + dict:map(fun({opaque, Name, _Arity}, + {{Module, _FileLine, _Form, ArgNames}, _Type}) -> + %% Args = args_to_types(ArgNames), + %% List = lists:zip(ArgNames, Args), + %% TmpVarTab = maps:to_list(List), + %% Rep = t_from_form(Type, RecDict, TmpVarTab), + Rep = t_any(), % not used for anything right now + Args = [t_any() || _ <- ArgNames], + t_opaque(Module, Name, Args, Rep) + end, OpaqueRecDict), + [OpaqueType || {_Key, OpaqueType} <- dict:to_list(OpaqueTypeDict)]. + +%% Decompose opaque instances of type arg2 to structured types, in arg1 +%% XXX: Same as t_unopaque +-spec t_struct_from_opaque(erl_type(), [erl_type()]) -> erl_type(). + +t_struct_from_opaque(?function(Domain, Range), Opaques) -> + ?function(t_struct_from_opaque(Domain, Opaques), + t_struct_from_opaque(Range, Opaques)); +t_struct_from_opaque(?list(Types, Term, Size), Opaques) -> + ?list(t_struct_from_opaque(Types, Opaques), + t_struct_from_opaque(Term, Opaques), Size); +t_struct_from_opaque(?opaque(_) = T, Opaques) -> + case is_opaque_type(T, Opaques) of + true -> t_opaque_structure(T); + false -> T + end; +t_struct_from_opaque(?product(Types), Opaques) -> + ?product(list_struct_from_opaque(Types, Opaques)); +t_struct_from_opaque(?tuple(?any, _, _) = T, _Opaques) -> T; +t_struct_from_opaque(?tuple(Types, Arity, Tag), Opaques) -> + ?tuple(list_struct_from_opaque(Types, Opaques), Arity, Tag); +t_struct_from_opaque(?tuple_set(Set), Opaques) -> + NewSet = [{Sz, [t_struct_from_opaque(T, Opaques) || T <- Tuples]} + || {Sz, Tuples} <- Set], + ?tuple_set(NewSet); +t_struct_from_opaque(?union(List), Opaques) -> + t_sup(list_struct_from_opaque(List, Opaques)); +t_struct_from_opaque(Type, _Opaques) -> Type. + +list_struct_from_opaque(Types, Opaques) -> + [t_struct_from_opaque(Type, Opaques) || Type <- Types]. + +%%----------------------------------------------------------------------------- + +-type mod_records() :: dict:dict(module(), type_table()). + +%%----------------------------------------------------------------------------- +%% Unit type. Signals non termination. +%% + +-spec t_unit() -> erl_type(). + +t_unit() -> + ?unit. + +-spec t_is_unit(erl_type()) -> boolean(). + +t_is_unit(?unit) -> true; +t_is_unit(_) -> false. + +-spec t_is_none_or_unit(erl_type()) -> boolean(). + +t_is_none_or_unit(?none) -> true; +t_is_none_or_unit(?unit) -> true; +t_is_none_or_unit(_) -> false. + +%%----------------------------------------------------------------------------- +%% Atoms and the derived type boolean +%% + +-spec t_atom() -> erl_type(). + +t_atom() -> + ?atom(?any). + +-spec t_atom(atom()) -> erl_type(). + +t_atom(A) when is_atom(A) -> + ?atom(set_singleton(A)). + +-spec t_atoms([atom()]) -> erl_type(). + +t_atoms(List) when is_list(List) -> + t_sup([t_atom(A) || A <- List]). + +-spec t_atom_vals(erl_type()) -> 'unknown' | [atom(),...]. + +t_atom_vals(Type) -> + t_atom_vals(Type, 'universe'). + +-spec t_atom_vals(erl_type(), opaques()) -> 'unknown' | [atom(),...]. + +t_atom_vals(Type, Opaques) -> + do_opaque(Type, Opaques, fun atom_vals/1). + +atom_vals(?atom(?any)) -> unknown; +atom_vals(?atom(Set)) -> set_to_list(Set); +atom_vals(?opaque(_)) -> unknown; +atom_vals(Other) -> + ?atom(_) = Atm = t_inf(t_atom(), Other), + atom_vals(Atm). + +-spec t_is_atom(erl_type()) -> boolean(). + +t_is_atom(Type) -> + t_is_atom(Type, 'universe'). + +-spec t_is_atom(erl_type(), opaques()) -> boolean(). + +t_is_atom(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_atom1/1). + +is_atom1(?atom(_)) -> true; +is_atom1(_) -> false. + +-spec t_is_any_atom(atom(), erl_type()) -> boolean(). + +t_is_any_atom(Atom, SomeAtomsType) -> + t_is_any_atom(Atom, SomeAtomsType, 'universe'). + +-spec t_is_any_atom(atom(), erl_type(), opaques()) -> boolean(). + +t_is_any_atom(Atom, SomeAtomsType, Opaques) -> + do_opaque(SomeAtomsType, Opaques, + fun(AtomsType) -> is_any_atom(Atom, AtomsType) end). + +is_any_atom(Atom, ?atom(?any)) when is_atom(Atom) -> false; +is_any_atom(Atom, ?atom(Set)) when is_atom(Atom) -> + set_is_singleton(Atom, Set); +is_any_atom(Atom, _) when is_atom(Atom) -> false. + +%%------------------------------------ + +-spec t_is_boolean(erl_type()) -> boolean(). + +t_is_boolean(Type) -> + t_is_boolean(Type, 'universe'). + +-spec t_is_boolean(erl_type(), opaques()) -> boolean(). + +t_is_boolean(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_boolean/1). + +-spec t_boolean() -> erl_type(). + +t_boolean() -> + ?atom(set_from_list([false, true])). + +is_boolean(?atom(?any)) -> false; +is_boolean(?atom(Set)) -> + case set_size(Set) of + 1 -> set_is_element(true, Set) orelse set_is_element(false, Set); + 2 -> set_is_element(true, Set) andalso set_is_element(false, Set); + N when is_integer(N), N > 2 -> false + end; +is_boolean(_) -> false. + +%%----------------------------------------------------------------------------- +%% Binaries +%% + +-spec t_binary() -> erl_type(). + +t_binary() -> + ?bitstr(8, 0). + +-spec t_is_binary(erl_type()) -> boolean(). + +t_is_binary(Type) -> + t_is_binary(Type, 'universe'). + +-spec t_is_binary(erl_type(), opaques()) -> boolean(). + +t_is_binary(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_binary/1). + +is_binary(?bitstr(U, B)) -> + ((U rem 8) =:= 0) andalso ((B rem 8) =:= 0); +is_binary(_) -> false. + +%%----------------------------------------------------------------------------- +%% Bitstrings +%% + +-spec t_bitstr() -> erl_type(). + +t_bitstr() -> + ?bitstr(1, 0). + +-spec t_bitstr(non_neg_integer(), non_neg_integer()) -> erl_type(). + +t_bitstr(U, B) -> + NewB = + if + U =:= 0 -> B; + B >= (U * (?UNIT_MULTIPLIER + 1)) -> + (B rem U) + U * ?UNIT_MULTIPLIER; + true -> + B + end, + ?bitstr(U, NewB). + +-spec t_bitstr_unit(erl_type()) -> non_neg_integer(). + +t_bitstr_unit(?bitstr(U, _)) -> U. + +-spec t_bitstr_base(erl_type()) -> non_neg_integer(). + +t_bitstr_base(?bitstr(_, B)) -> B. + +-spec t_bitstr_concat([erl_type()]) -> erl_type(). + +t_bitstr_concat(List) -> + t_bitstr_concat_1(List, t_bitstr(0, 0)). + +t_bitstr_concat_1([T|Left], Acc) -> + t_bitstr_concat_1(Left, t_bitstr_concat(Acc, T)); +t_bitstr_concat_1([], Acc) -> + Acc. + +-spec t_bitstr_concat(erl_type(), erl_type()) -> erl_type(). + +t_bitstr_concat(T1, T2) -> + T1p = t_inf(t_bitstr(), T1), + T2p = t_inf(t_bitstr(), T2), + bitstr_concat(t_unopaque(T1p), t_unopaque(T2p)). + +-spec t_bitstr_match(erl_type(), erl_type()) -> erl_type(). + +t_bitstr_match(T1, T2) -> + T1p = t_inf(t_bitstr(), T1), + T2p = t_inf(t_bitstr(), T2), + bitstr_match(t_unopaque(T1p), t_unopaque(T2p)). + +-spec t_is_bitstr(erl_type()) -> boolean(). + +t_is_bitstr(Type) -> + t_is_bitstr(Type, 'universe'). + +-spec t_is_bitstr(erl_type(), opaques()) -> boolean(). + +t_is_bitstr(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_bitstr/1). + +is_bitstr(?bitstr(_, _)) -> true; +is_bitstr(_) -> false. + +%%----------------------------------------------------------------------------- +%% Matchstates +%% + +-spec t_matchstate() -> erl_type(). + +t_matchstate() -> + ?any_matchstate. + +-spec t_matchstate(erl_type(), non_neg_integer()) -> erl_type(). + +t_matchstate(Init, 0) -> + ?matchstate(Init, Init); +t_matchstate(Init, Max) when is_integer(Max) -> + Slots = [Init|[?none || _ <- lists:seq(1, Max)]], + ?matchstate(Init, t_product(Slots)). + +-spec t_is_matchstate(erl_type()) -> boolean(). + +t_is_matchstate(?matchstate(_, _)) -> true; +t_is_matchstate(_) -> false. + +-spec t_matchstate_present(erl_type()) -> erl_type(). + +t_matchstate_present(Type) -> + case t_inf(t_matchstate(), Type) of + ?matchstate(P, _) -> P; + _ -> ?none + end. + +-spec t_matchstate_slot(erl_type(), non_neg_integer()) -> erl_type(). + +t_matchstate_slot(Type, Slot) -> + RealSlot = Slot + 1, + case t_inf(t_matchstate(), Type) of + ?matchstate(_, ?any) -> ?any; + ?matchstate(_, ?product(Vals)) when length(Vals) >= RealSlot -> + lists:nth(RealSlot, Vals); + ?matchstate(_, ?product(_)) -> + ?none; + ?matchstate(_, SlotType) when RealSlot =:= 1 -> + SlotType; + _ -> + ?none + end. + +-spec t_matchstate_slots(erl_type()) -> erl_type(). + +t_matchstate_slots(?matchstate(_, Slots)) -> + Slots. + +-spec t_matchstate_update_present(erl_type(), erl_type()) -> erl_type(). + +t_matchstate_update_present(New, Type) -> + case t_inf(t_matchstate(), Type) of + ?matchstate(_, Slots) -> + ?matchstate(New, Slots); + _ -> ?none + end. + +-spec t_matchstate_update_slot(erl_type(), erl_type(), non_neg_integer()) -> erl_type(). + +t_matchstate_update_slot(New, Type, Slot) -> + RealSlot = Slot + 1, + case t_inf(t_matchstate(), Type) of + ?matchstate(Pres, Slots) -> + NewSlots = + case Slots of + ?any -> + ?any; + ?product(Vals) when length(Vals) >= RealSlot -> + NewTuple = setelement(RealSlot, list_to_tuple(Vals), New), + NewVals = tuple_to_list(NewTuple), + ?product(NewVals); + ?product(_) -> + ?none; + _ when RealSlot =:= 1 -> + New; + _ -> + ?none + end, + ?matchstate(Pres, NewSlots); + _ -> + ?none + end. + +%%----------------------------------------------------------------------------- +%% Functions +%% + +-spec t_fun() -> erl_type(). + +t_fun() -> + ?function(?any, ?any). + +-spec t_fun(erl_type()) -> erl_type(). + +t_fun(Range) -> + ?function(?any, Range). + +-spec t_fun([erl_type()] | arity(), erl_type()) -> erl_type(). + +t_fun(Domain, Range) when is_list(Domain) -> + ?function(?product(Domain), Range); +t_fun(Arity, Range) when is_integer(Arity), 0 =< Arity, Arity =< 255 -> + ?function(?product(lists:duplicate(Arity, ?any)), Range). + +-spec t_fun_args(erl_type()) -> 'unknown' | [erl_type()]. + +t_fun_args(Type) -> + t_fun_args(Type, 'universe'). + +-spec t_fun_args(erl_type(), opaques()) -> 'unknown' | [erl_type()]. + +t_fun_args(Type, Opaques) -> + do_opaque(Type, Opaques, fun fun_args/1). + +fun_args(?function(?any, _)) -> + unknown; +fun_args(?function(?product(Domain), _)) when is_list(Domain) -> + Domain. + +-spec t_fun_arity(erl_type()) -> 'unknown' | non_neg_integer(). + +t_fun_arity(Type) -> + t_fun_arity(Type, 'universe'). + +-spec t_fun_arity(erl_type(), opaques()) -> 'unknown' | non_neg_integer(). + +t_fun_arity(Type, Opaques) -> + do_opaque(Type, Opaques, fun fun_arity/1). + +fun_arity(?function(?any, _)) -> + unknown; +fun_arity(?function(?product(Domain), _)) -> + length(Domain). + +-spec t_fun_range(erl_type()) -> erl_type(). + +t_fun_range(Type) -> + t_fun_range(Type, 'universe'). + +-spec t_fun_range(erl_type(), opaques()) -> erl_type(). + +t_fun_range(Type, Opaques) -> + do_opaque(Type, Opaques, fun fun_range/1). + +fun_range(?function(_, Range)) -> + Range. + +-spec t_is_fun(erl_type()) -> boolean(). + +t_is_fun(Type) -> + t_is_fun(Type, 'universe'). + +-spec t_is_fun(erl_type(), opaques()) -> boolean(). + +t_is_fun(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_fun/1). + +is_fun(?function(_, _)) -> true; +is_fun(_) -> false. + +%%----------------------------------------------------------------------------- +%% Identifiers. Includes ports, pids and refs. +%% + +-spec t_identifier() -> erl_type(). + +t_identifier() -> + ?identifier(?any). + +-ifdef(DO_ERL_TYPES_TEST). +-spec t_is_identifier(erl_type()) -> erl_type(). + +t_is_identifier(?identifier(_)) -> true; +t_is_identifier(_) -> false. +-endif. + +%%------------------------------------ + +-spec t_port() -> erl_type(). + +t_port() -> + ?identifier(set_singleton(?port_qual)). + +-spec t_is_port(erl_type()) -> boolean(). + +t_is_port(Type) -> + t_is_port(Type, 'universe'). + +-spec t_is_port(erl_type(), opaques()) -> boolean(). + +t_is_port(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_port1/1). + +is_port1(?identifier(?any)) -> false; +is_port1(?identifier(Set)) -> set_is_singleton(?port_qual, Set); +is_port1(_) -> false. + +%%------------------------------------ + +-spec t_pid() -> erl_type(). + +t_pid() -> + ?identifier(set_singleton(?pid_qual)). + +-spec t_is_pid(erl_type()) -> boolean(). + +t_is_pid(Type) -> + t_is_pid(Type, 'universe'). + +-spec t_is_pid(erl_type(), opaques()) -> boolean(). + +t_is_pid(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_pid1/1). + +is_pid1(?identifier(?any)) -> false; +is_pid1(?identifier(Set)) -> set_is_singleton(?pid_qual, Set); +is_pid1(_) -> false. + +%%------------------------------------ + +-spec t_reference() -> erl_type(). + +t_reference() -> + ?identifier(set_singleton(?reference_qual)). + +-spec t_is_reference(erl_type()) -> boolean(). + +t_is_reference(Type) -> + t_is_reference(Type, 'universe'). + +-spec t_is_reference(erl_type(), opaques()) -> boolean(). + +t_is_reference(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_reference1/1). + +is_reference1(?identifier(?any)) -> false; +is_reference1(?identifier(Set)) -> set_is_singleton(?reference_qual, Set); +is_reference1(_) -> false. + +%%----------------------------------------------------------------------------- +%% Numbers are divided into floats, integers, chars and bytes. +%% + +-spec t_number() -> erl_type(). + +t_number() -> + ?number(?any, ?unknown_qual). + +-spec t_number(integer()) -> erl_type(). + +t_number(X) when is_integer(X) -> + t_integer(X). + +-spec t_is_number(erl_type()) -> boolean(). + +t_is_number(Type) -> + t_is_number(Type, 'universe'). + +-spec t_is_number(erl_type(), opaques()) -> boolean(). + +t_is_number(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_number/1). + +is_number(?number(_, _)) -> true; +is_number(_) -> false. + +%% Currently, the type system collapses all floats to ?float and does +%% not keep any information about their values. As a result, the list +%% that this function returns contains only integers. + +-spec t_number_vals(erl_type()) -> 'unknown' | [integer(),...]. + +t_number_vals(Type) -> + t_number_vals(Type, 'universe'). + +-spec t_number_vals(erl_type(), opaques()) -> 'unknown' | [integer(),...]. + +t_number_vals(Type, Opaques) -> + do_opaque(Type, Opaques, fun number_vals/1). + +number_vals(?int_set(Set)) -> set_to_list(Set); +number_vals(?number(_, _)) -> unknown; +number_vals(?opaque(_)) -> unknown; +number_vals(Other) -> + Inf = t_inf(Other, t_number()), + false = t_is_none(Inf), % sanity check + number_vals(Inf). + +%%------------------------------------ + +-spec t_float() -> erl_type(). + +t_float() -> + ?float. + +-spec t_is_float(erl_type()) -> boolean(). + +t_is_float(Type) -> + t_is_float(Type, 'universe'). + +-spec t_is_float(erl_type(), opaques()) -> boolean(). + +t_is_float(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_float1/1). + +is_float1(?float) -> true; +is_float1(_) -> false. + +%%------------------------------------ + +-spec t_integer() -> erl_type(). + +t_integer() -> + ?integer(?any). + +-spec t_integer(integer()) -> erl_type(). + +t_integer(I) when is_integer(I) -> + ?int_set(set_singleton(I)). + +-spec t_integers([integer()]) -> erl_type(). + +t_integers(List) when is_list(List) -> + t_sup([t_integer(I) || I <- List]). + +-spec t_is_integer(erl_type()) -> boolean(). + +t_is_integer(Type) -> + t_is_integer(Type, 'universe'). + +-spec t_is_integer(erl_type(), opaques()) -> boolean(). + +t_is_integer(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_integer1/1). + +is_integer1(?integer(_)) -> true; +is_integer1(_) -> false. + +%%------------------------------------ + +-spec t_byte() -> erl_type(). + +t_byte() -> + ?byte. + +-ifdef(DO_ERL_TYPES_TEST). +-spec t_is_byte(erl_type()) -> boolean(). + +t_is_byte(?int_range(neg_inf, _)) -> false; +t_is_byte(?int_range(_, pos_inf)) -> false; +t_is_byte(?int_range(From, To)) + when is_integer(From), From >= 0, is_integer(To), To =< ?MAX_BYTE -> true; +t_is_byte(?int_set(Set)) -> + (set_min(Set) >= 0) andalso (set_max(Set) =< ?MAX_BYTE); +t_is_byte(_) -> false. +-endif. + +%%------------------------------------ + +-spec t_char() -> erl_type(). + +t_char() -> + ?char. + +-spec t_is_char(erl_type()) -> boolean(). + +t_is_char(?int_range(neg_inf, _)) -> false; +t_is_char(?int_range(_, pos_inf)) -> false; +t_is_char(?int_range(From, To)) + when is_integer(From), From >= 0, is_integer(To), To =< ?MAX_CHAR -> true; +t_is_char(?int_set(Set)) -> + (set_min(Set) >= 0) andalso (set_max(Set) =< ?MAX_CHAR); +t_is_char(_) -> false. + +%%----------------------------------------------------------------------------- +%% Lists +%% + +-spec t_cons() -> erl_type(). + +t_cons() -> + ?nonempty_list(?any, ?any). + +%% Note that if the tail argument can be a list, we must collapse the +%% content of the list to include both the content of the tail list +%% and the head of the cons. If for example the tail argument is any() +%% then there can be any list in the tail and the content of the +%% returned list must be any(). + +-spec t_cons(erl_type(), erl_type()) -> erl_type(). + +t_cons(?none, _) -> ?none; +t_cons(_, ?none) -> ?none; +t_cons(?unit, _) -> ?none; +t_cons(_, ?unit) -> ?none; +t_cons(Hd, ?nil) -> + ?nonempty_list(Hd, ?nil); +t_cons(Hd, ?list(Contents, Termination, _)) -> + ?nonempty_list(t_sup(Contents, Hd), Termination); +t_cons(Hd, Tail) -> + case cons_tail(t_inf(Tail, t_maybe_improper_list())) of + ?list(Contents, Termination, _Size) -> + %% Collapse the list part of the termination but keep the + %% non-list part intact. + NewTermination = t_sup(t_subtract(Tail, t_maybe_improper_list()), + Termination), + ?nonempty_list(t_sup(Hd, Contents), NewTermination); + ?nil -> ?nonempty_list(Hd, Tail); + ?none -> ?nonempty_list(Hd, Tail); + ?unit -> ?none + end. + +cons_tail(Type) -> + do_opaque(Type, 'universe', fun(T) -> T end). + +-spec t_is_cons(erl_type()) -> boolean(). + +t_is_cons(Type) -> + t_is_cons(Type, 'universe'). + +-spec t_is_cons(erl_type(), opaques()) -> boolean(). + +t_is_cons(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_cons/1). + +is_cons(?nonempty_list(_, _)) -> true; +is_cons(_) -> false. + +-spec t_cons_hd(erl_type()) -> erl_type(). + +t_cons_hd(Type) -> + t_cons_hd(Type, 'universe'). + +-spec t_cons_hd(erl_type(), opaques()) -> erl_type(). + +t_cons_hd(Type, Opaques) -> + do_opaque(Type, Opaques, fun cons_hd/1). + +cons_hd(?nonempty_list(Contents, _Termination)) -> Contents. + +-spec t_cons_tl(erl_type()) -> erl_type(). + +t_cons_tl(Type) -> + t_cons_tl(Type, 'universe'). + +-spec t_cons_tl(erl_type(), opaques()) -> erl_type(). + +t_cons_tl(Type, Opaques) -> + do_opaque(Type, Opaques, fun cons_tl/1). + +cons_tl(?nonempty_list(_Contents, Termination) = T) -> + t_sup(Termination, T). + +-spec t_nil() -> erl_type(). + +t_nil() -> + ?nil. + +-spec t_is_nil(erl_type()) -> boolean(). + +t_is_nil(Type) -> + t_is_nil(Type, 'universe'). + +-spec t_is_nil(erl_type(), opaques()) -> boolean(). + +t_is_nil(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_nil/1). + +is_nil(?nil) -> true; +is_nil(_) -> false. + +-spec t_list() -> erl_type(). + +t_list() -> + ?list(?any, ?nil, ?unknown_qual). + +-spec t_list(erl_type()) -> erl_type(). + +t_list(?none) -> ?none; +t_list(?unit) -> ?none; +t_list(Contents) -> + ?list(Contents, ?nil, ?unknown_qual). + +-spec t_list_elements(erl_type()) -> erl_type(). + +t_list_elements(Type) -> + t_list_elements(Type, 'universe'). + +-spec t_list_elements(erl_type(), opaques()) -> erl_type(). + +t_list_elements(Type, Opaques) -> + do_opaque(Type, Opaques, fun list_elements/1). + +list_elements(?list(Contents, _, _)) -> Contents; +list_elements(?nil) -> ?none. + +-spec t_list_termination(erl_type(), opaques()) -> erl_type(). + +t_list_termination(Type, Opaques) -> + do_opaque(Type, Opaques, fun t_list_termination/1). + +-spec t_list_termination(erl_type()) -> erl_type(). + +t_list_termination(?nil) -> ?nil; +t_list_termination(?list(_, Term, _)) -> Term. + +-spec t_is_list(erl_type()) -> boolean(). + +t_is_list(?list(_Contents, ?nil, _)) -> true; +t_is_list(?nil) -> true; +t_is_list(_) -> false. + +-spec t_nonempty_list() -> erl_type(). + +t_nonempty_list() -> + t_cons(?any, ?nil). + +-spec t_nonempty_list(erl_type()) -> erl_type(). + +t_nonempty_list(Type) -> + t_cons(Type, ?nil). + +-spec t_nonempty_string() -> erl_type(). + +t_nonempty_string() -> + t_nonempty_list(t_char()). + +-spec t_string() -> erl_type(). + +t_string() -> + t_list(t_char()). + +-spec t_is_string(erl_type()) -> boolean(). + +t_is_string(X) -> + t_is_list(X) andalso t_is_char(t_list_elements(X)). + +-spec t_maybe_improper_list() -> erl_type(). + +t_maybe_improper_list() -> + ?list(?any, ?any, ?unknown_qual). + +%% Should only be used if you know what you are doing. See t_cons/2 +-spec t_maybe_improper_list(erl_type(), erl_type()) -> erl_type(). + +t_maybe_improper_list(_Content, ?unit) -> ?none; +t_maybe_improper_list(?unit, _Termination) -> ?none; +t_maybe_improper_list(Content, Termination) -> + %% Safety check: would be nice to have but does not work with remote types + %% true = t_is_subtype(t_nil(), Termination), + ?list(Content, Termination, ?unknown_qual). + +-spec t_is_maybe_improper_list(erl_type()) -> boolean(). + +t_is_maybe_improper_list(Type) -> + t_is_maybe_improper_list(Type, 'universe'). + +-spec t_is_maybe_improper_list(erl_type(), opaques()) -> boolean(). + +t_is_maybe_improper_list(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_maybe_improper_list/1). + +is_maybe_improper_list(?list(_, _, _)) -> true; +is_maybe_improper_list(?nil) -> true; +is_maybe_improper_list(_) -> false. + +%% %% Should only be used if you know what you are doing. See t_cons/2 +%% -spec t_improper_list(erl_type(), erl_type()) -> erl_type(). +%% +%% t_improper_list(?unit, _Termination) -> ?none; +%% t_improper_list(_Content, ?unit) -> ?none; +%% t_improper_list(Content, Termination) -> +%% %% Safety check: would be nice to have but does not work with remote types +%% %% false = t_is_subtype(t_nil(), Termination), +%% ?list(Content, Termination, ?any). + +-spec lift_list_to_pos_empty(erl_type(), opaques()) -> erl_type(). + +lift_list_to_pos_empty(Type, Opaques) -> + do_opaque(Type, Opaques, fun lift_list_to_pos_empty/1). + +-spec lift_list_to_pos_empty(erl_type()) -> erl_type(). + +lift_list_to_pos_empty(?nil) -> ?nil; +lift_list_to_pos_empty(?list(Content, Termination, _)) -> + ?list(Content, Termination, ?unknown_qual). + +%%----------------------------------------------------------------------------- +%% Maps +%% +%% Representation: +%% ?map(Pairs, DefaultKey, DefaultValue) +%% +%% Pairs is a sorted dictionary of types with a mandatoriness tag on each pair +%% (t_map_dict()). DefaultKey and DefaultValue are plain types. +%% +%% A map M belongs to this type iff +%% For each pair {KT, mandatory, VT} in Pairs, there exists a pair {K, V} in M +%% such that K \in KT and V \in VT. +%% For each pair {KT, optional, VT} in Pairs, either there exists no key K in +%% M s.t. K in KT, or there exists a pair {K, V} in M such that K \in KT and +%% V \in VT. +%% For each remaining pair {K, V} in M (where remaining means that there is no +%% key KT in Pairs s.t. K \in KT), K \in DefaultKey and V \in DefaultValue. +%% +%% Invariants: +%% * The keys in Pairs are singleton types. +%% * The values of Pairs must not be unit, and may only be none if the +%% mandatoriness tag is 'optional'. +%% * Optional must contain no pair {K,V} s.t. K is a subtype of DefaultKey and +%% V is equal to DefaultKey. +%% * DefaultKey must be the empty type iff DefaultValue is the empty type. +%% * DefaultKey must not be a singleton type. +%% * For every key K in Pairs, DefaultKey - K must not be representable; i.e. +%% t_subtract(DefaultKey, K) must return DefaultKey. +%% * For every pair {K, 'optional', ?none} in Pairs, K must be a subtype of +%% DefaultKey. +%% * Pairs must be sorted and not contain any duplicate keys. +%% +%% These invariants ensure that equal map types are represented by equal terms. + +-define(mand, mandatory). +-define(opt, optional). + +-type t_map_mandatoriness() :: ?mand | ?opt. +-type t_map_pair() :: {erl_type(), t_map_mandatoriness(), erl_type()}. +-type t_map_dict() :: [t_map_pair()]. + +-spec t_map() -> erl_type(). + +t_map() -> + t_map([], t_any(), t_any()). + +-spec t_map([{erl_type(), erl_type()}]) -> erl_type(). + +t_map(L) -> + lists:foldl(fun t_map_put/2, t_map(), L). + +-spec t_map(t_map_dict(), erl_type(), erl_type()) -> erl_type(). + +t_map(Pairs0, DefK0, DefV0) -> + DefK1 = lists:foldl(fun({K,_,_},Acc)->t_subtract(Acc,K)end, DefK0, Pairs0), + {DefK2, DefV1} = + case t_is_none_or_unit(DefK1) orelse t_is_none_or_unit(DefV0) of + true -> {?none, ?none}; + false -> {DefK1, DefV0} + end, + {Pairs1, DefK, DefV} + = case is_singleton_type(DefK2) of + true -> {mapdict_insert({DefK2, ?opt, DefV1}, Pairs0), ?none, ?none}; + false -> {Pairs0, DefK2, DefV1} + end, + Pairs = normalise_map_optionals(Pairs1, DefK, DefV), + %% Validate invariants of the map representation. + %% Since we needed to iterate over the arguments in order to normalise anyway, + %% we might as well save us some future pain and do this even without + %% define(DEBUG, true). + try + validate_map_elements(Pairs) + catch error:badarg -> error(badarg, [Pairs0,DefK0,DefV0]); + error:{badarg, E} -> error({badarg, E}, [Pairs0,DefK0,DefV0]) + end, + ?map(Pairs, DefK, DefV). + +normalise_map_optionals([], _, _) -> []; +normalise_map_optionals([E={K,?opt,?none}|T], DefK, DefV) -> + Diff = t_subtract(DefK, K), + case t_is_subtype(K, DefK) andalso DefK =:= Diff of + true -> [E|normalise_map_optionals(T, DefK, DefV)]; + false -> normalise_map_optionals(T, Diff, DefV) + end; +normalise_map_optionals([E={K,?opt,V}|T], DefK, DefV) -> + case t_is_equal(V, DefV) andalso t_is_subtype(K, DefK) of + true -> normalise_map_optionals(T, DefK, DefV); + false -> [E|normalise_map_optionals(T, DefK, DefV)] + end; +normalise_map_optionals([E|T], DefK, DefV) -> + [E|normalise_map_optionals(T, DefK, DefV)]. + +validate_map_elements([{_,?mand,?none}|_]) -> error({badarg, none_in_mand}); +validate_map_elements([{K1,_,_}|Rest=[{K2,_,_}|_]]) -> + case is_singleton_type(K1) andalso K1 < K2 of + false -> error(badarg); + true -> validate_map_elements(Rest) + end; +validate_map_elements([{K,_,_}]) -> + case is_singleton_type(K) of + false -> error(badarg); + true -> true + end; +validate_map_elements([]) -> true. + +-spec t_is_map(erl_type()) -> boolean(). + +t_is_map(Type) -> + t_is_map(Type, 'universe'). + +-spec t_is_map(erl_type(), opaques()) -> boolean(). + +t_is_map(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_map1/1). + +is_map1(?map(_, _, _)) -> true; +is_map1(_) -> false. + +-spec t_map_entries(erl_type()) -> t_map_dict(). + +t_map_entries(M) -> + t_map_entries(M, 'universe'). + +-spec t_map_entries(erl_type(), opaques()) -> t_map_dict(). + +t_map_entries(M, Opaques) -> + do_opaque(M, Opaques, fun map_entries/1). + +map_entries(?map(Pairs,_,_)) -> + Pairs. + +-spec t_map_def_key(erl_type()) -> erl_type(). + +t_map_def_key(M) -> + t_map_def_key(M, 'universe'). + +-spec t_map_def_key(erl_type(), opaques()) -> erl_type(). + +t_map_def_key(M, Opaques) -> + do_opaque(M, Opaques, fun map_def_key/1). + +map_def_key(?map(_,DefK,_)) -> + DefK. + +-spec t_map_def_val(erl_type()) -> erl_type(). + +t_map_def_val(M) -> + t_map_def_val(M, 'universe'). + +-spec t_map_def_val(erl_type(), opaques()) -> erl_type(). + +t_map_def_val(M, Opaques) -> + do_opaque(M, Opaques, fun map_def_val/1). + +map_def_val(?map(_,_,DefV)) -> + DefV. + +-spec mapdict_store(t_map_pair(), t_map_dict()) -> t_map_dict(). + +mapdict_store(E={K,_,_}, [{K,_,_}|T]) -> [E|T]; +mapdict_store(E1={K1,_,_}, [E2={K2,_,_}|T]) when K1 > K2 -> + [E2|mapdict_store(E1, T)]; +mapdict_store(E={_,_,_}, T) -> [E|T]. + +-spec mapdict_insert(t_map_pair(), t_map_dict()) -> t_map_dict(). + +mapdict_insert(E={K,_,_}, D=[{K,_,_}|_]) -> error(badarg, [E, D]); +mapdict_insert(E1={K1,_,_}, [E2={K2,_,_}|T]) when K1 > K2 -> + [E2|mapdict_insert(E1, T)]; +mapdict_insert(E={_,_,_}, T) -> [E|T]. + +%% Merges the pairs of two maps together. Missing pairs become (?opt, DefV) or +%% (?opt, ?none), depending on whether K \in DefK. +-spec map_pairwise_merge(fun((erl_type(), + t_map_mandatoriness(), erl_type(), + t_map_mandatoriness(), erl_type()) + -> t_map_pair() | false), + erl_type(), erl_type()) -> t_map_dict(). +map_pairwise_merge(F, ?map(APairs, ADefK, ADefV), + ?map(BPairs, BDefK, BDefV)) -> + map_pairwise_merge(F, APairs, ADefK, ADefV, BPairs, BDefK, BDefV). + +map_pairwise_merge(_, [], _, _, [], _, _) -> []; +map_pairwise_merge(F, As0, ADefK, ADefV, Bs0, BDefK, BDefV) -> + {K1, AMNess1, AV1, As1, BMNess1, BV1, Bs1} = + case {As0, Bs0} of + {[{K,AMNess,AV}|As], [{K, BMNess,BV}|Bs]} -> + {K, AMNess, AV, As, BMNess, BV, Bs}; + {[{K,AMNess,AV}|As], [{BK,_, _ }|_]=Bs} when K < BK -> + {K, AMNess, AV, As, ?opt, mapmerge_otherv(K, BDefK, BDefV), Bs}; + {As, [{K, BMNess,BV}|Bs]} -> + {K, ?opt, mapmerge_otherv(K, ADefK, ADefV), As, BMNess, BV, Bs}; + {[{K,AMNess,AV}|As], []=Bs} -> + {K, AMNess, AV, As, ?opt, mapmerge_otherv(K, BDefK, BDefV), Bs} + end, + MK = K1, %% Rename to make clear that we are matching below + case F(K1, AMNess1, AV1, BMNess1, BV1) of + false -> map_pairwise_merge(F,As1,ADefK,ADefV,Bs1,BDefK,BDefV); + {MK,_,_}=M -> [M|map_pairwise_merge(F,As1,ADefK,ADefV,Bs1,BDefK,BDefV)] + end. + +%% Folds over the pairs in two maps simultaneously in reverse key order. Missing +%% pairs become (?opt, DefV) or (?opt, ?none), depending on whether K \in DefK. +-spec map_pairwise_merge_foldr(fun((erl_type(), + t_map_mandatoriness(), erl_type(), + t_map_mandatoriness(), erl_type(), + Acc) -> Acc), + Acc, erl_type(), erl_type()) -> Acc. + +map_pairwise_merge_foldr(F, AccIn, ?map(APairs, ADefK, ADefV), + ?map(BPairs, BDefK, BDefV)) -> + map_pairwise_merge_foldr(F, AccIn, APairs, ADefK, ADefV, BPairs, BDefK, BDefV). + +map_pairwise_merge_foldr(_, Acc, [], _, _, [], _, _) -> Acc; +map_pairwise_merge_foldr(F, AccIn, As0, ADefK, ADefV, Bs0, BDefK, BDefV) -> + {K1, AMNess1, AV1, As1, BMNess1, BV1, Bs1} = + case {As0, Bs0} of + {[{K,AMNess,AV}|As], [{K,BMNess,BV}|Bs]} -> + {K, AMNess, AV, As, BMNess, BV, Bs}; + {[{K,AMNess,AV}|As], [{BK,_, _ }|_]=Bs} when K < BK -> + {K, AMNess, AV, As, ?opt, mapmerge_otherv(K, BDefK, BDefV), Bs}; + {As, [{K,BMNess,BV}|Bs]} -> + {K, ?opt, mapmerge_otherv(K, ADefK, ADefV), As, BMNess, BV, Bs}; + {[{K,AMNess,AV}|As], []=Bs} -> + {K, AMNess, AV, As, ?opt, mapmerge_otherv(K, BDefK, BDefV), Bs} + end, + F(K1, AMNess1, AV1, BMNess1, BV1, + map_pairwise_merge_foldr(F,AccIn,As1,ADefK,ADefV,Bs1,BDefK,BDefV)). + +%% By observing that a missing pair in a map is equivalent to an optional pair, +%% with ?none or DefV value, depending on whether K \in DefK, we can simplify +%% merging by denormalising the map pairs temporarily, removing all 'false' +%% cases, at the cost of the creation of more tuples: +mapmerge_otherv(K, ODefK, ODefV) -> + case t_inf(K, ODefK) of + ?none -> ?none; + _KOrOpaque -> ODefV + end. + +-spec t_map_put({erl_type(), erl_type()}, erl_type()) -> erl_type(). + +t_map_put(KV, Map) -> + t_map_put(KV, Map, 'universe'). + +-spec t_map_put({erl_type(), erl_type()}, erl_type(), opaques()) -> erl_type(). + +t_map_put(KV, Map, Opaques) -> + do_opaque(Map, Opaques, fun(UM) -> map_put(KV, UM, Opaques) end). + +%% Key and Value are *not* unopaqued, but the map is +map_put(_, ?none, _) -> ?none; +map_put({Key, Value}, ?map(Pairs,DefK,DefV), Opaques) -> + case t_is_none_or_unit(Key) orelse t_is_none_or_unit(Value) of + true -> ?none; + false -> + case is_singleton_type(Key) of + true -> + t_map(mapdict_store({Key, ?mand, Value}, Pairs), DefK, DefV); + false -> + t_map([{K, MNess, case t_is_none(t_inf(K, Key, Opaques)) of + true -> V; + false -> t_sup(V, Value) + end} || {K, MNess, V} <- Pairs], + t_sup(DefK, Key), + t_sup(DefV, Value)) + end + end. + +-spec t_map_update({erl_type(), erl_type()}, erl_type()) -> erl_type(). + +t_map_update(KV, Map) -> + t_map_update(KV, Map, 'universe'). + +-spec t_map_update({erl_type(), erl_type()}, erl_type(), opaques()) -> erl_type(). + +t_map_update(_, ?none, _) -> ?none; +t_map_update(KV={Key, _}, M, Opaques) -> + case t_is_subtype(t_atom('true'), t_map_is_key(Key, M, Opaques)) of + false -> ?none; + true -> t_map_put(KV, M, Opaques) + end. + +-spec t_map_get(erl_type(), erl_type()) -> erl_type(). + +t_map_get(Key, Map) -> + t_map_get(Key, Map, 'universe'). + +-spec t_map_get(erl_type(), erl_type(), opaques()) -> erl_type(). + +t_map_get(Key, Map, Opaques) -> + do_opaque(Map, Opaques, + fun(UM) -> + do_opaque(Key, Opaques, fun(UK) -> map_get(UK, UM) end) + end). + +map_get(_, ?none) -> ?none; +map_get(Key, ?map(Pairs, DefK, DefV)) -> + DefRes = + case t_do_overlap(DefK, Key) of + false -> t_none(); + true -> DefV + end, + case is_singleton_type(Key) of + false -> + lists:foldl(fun({K, _, V}, Res) -> + case t_do_overlap(K, Key) of + false -> Res; + true -> t_sup(Res, V) + end + end, DefRes, Pairs); + true -> + case lists:keyfind(Key, 1, Pairs) of + false -> DefRes; + {_, _, ValType} -> ValType + end + end. + +-spec t_map_is_key(erl_type(), erl_type()) -> erl_type(). + +t_map_is_key(Key, Map) -> + t_map_is_key(Key, Map, 'universe'). + +-spec t_map_is_key(erl_type(), erl_type(), opaques()) -> erl_type(). + +t_map_is_key(Key, Map, Opaques) -> + do_opaque(Map, Opaques, + fun(UM) -> + do_opaque(Key, Opaques, fun(UK) -> map_is_key(UK, UM) end) + end). + +map_is_key(_, ?none) -> ?none; +map_is_key(Key, ?map(Pairs, DefK, _DefV)) -> + case is_singleton_type(Key) of + true -> + case lists:keyfind(Key, 1, Pairs) of + {Key, ?mand, _} -> t_atom(true); + {Key, ?opt, ?none} -> t_atom(false); + {Key, ?opt, _} -> t_boolean(); + false -> + case t_do_overlap(DefK, Key) of + false -> t_atom(false); + true -> t_boolean() + end + end; + false -> + case t_do_overlap(DefK, Key) + orelse lists:any(fun({_,_,?none}) -> false; + ({K,_,_}) -> t_do_overlap(K, Key) + end, Pairs) + of + true -> t_boolean(); + false -> t_atom(false) + end + end. + +%%----------------------------------------------------------------------------- +%% Tuples +%% + +-spec t_tuple() -> erl_type(). + +t_tuple() -> + ?tuple(?any, ?any, ?any). + +-spec t_tuple(non_neg_integer() | [erl_type()]) -> erl_type(). + +t_tuple(N) when is_integer(N), N > ?MAX_TUPLE_SIZE -> + t_tuple(); +t_tuple(N) when is_integer(N) -> + ?tuple(lists:duplicate(N, ?any), N, ?any); +t_tuple(List) -> + case any_none_or_unit(List) of + true -> t_none(); + false -> + Arity = length(List), + case get_tuple_tags(List) of + [Tag] -> ?tuple(List, Arity, Tag); %% Tag can also be ?any here + TagList -> + SortedTagList = lists:sort(TagList), + Tuples = [?tuple([T|tl(List)], Arity, T) || T <- SortedTagList], + ?tuple_set([{Arity, Tuples}]) + end + end. + +-spec get_tuple_tags([erl_type()]) -> [erl_type(),...]. + +get_tuple_tags([Tag|_]) -> + do_opaque(Tag, 'universe', fun tuple_tags/1); +get_tuple_tags(_) -> [?any]. + +tuple_tags(?atom(?any)) -> [?any]; +tuple_tags(?atom(Set)) -> + case set_size(Set) > ?TUPLE_TAG_LIMIT of + true -> [?any]; + false -> [t_atom(A) || A <- set_to_list(Set)] + end; +tuple_tags(_) -> [?any]. + +%% to be used for a tuple with known types for its arguments (not ?any) +-spec t_tuple_args(erl_type()) -> [erl_type()]. + +t_tuple_args(Type) -> + t_tuple_args(Type, 'universe'). + +%% to be used for a tuple with known types for its arguments (not ?any) +-spec t_tuple_args(erl_type(), opaques()) -> [erl_type()]. + +t_tuple_args(Type, Opaques) -> + do_opaque(Type, Opaques, fun tuple_args/1). + +tuple_args(?tuple(Args, _, _)) when is_list(Args) -> Args. + +%% to be used for a tuple with a known size (not ?any) +-spec t_tuple_size(erl_type()) -> non_neg_integer(). + +t_tuple_size(Type) -> + t_tuple_size(Type, 'universe'). + +%% to be used for a tuple with a known size (not ?any) +-spec t_tuple_size(erl_type(), opaques()) -> non_neg_integer(). + +t_tuple_size(Type, Opaques) -> + do_opaque(Type, Opaques, fun tuple_size1/1). + +tuple_size1(?tuple(_, Size, _)) when is_integer(Size) -> Size. + +-spec t_tuple_sizes(erl_type()) -> 'unknown' | [non_neg_integer(),...]. + +t_tuple_sizes(Type) -> + do_opaque(Type, 'universe', fun tuple_sizes/1). + +tuple_sizes(?tuple(?any, ?any, ?any)) -> unknown; +tuple_sizes(?tuple(_, Size, _)) when is_integer(Size) -> [Size]; +tuple_sizes(?tuple_set(List)) -> [Size || {Size, _} <- List]. + +-spec t_tuple_subtypes(erl_type(), opaques()) -> + 'unknown' | [erl_type(),...]. + +t_tuple_subtypes(Type, Opaques) -> + Fun = fun(?tuple_set(List)) -> + t_tuple_subtypes_tuple_list(List, Opaques); + (?opaque(_)) -> unknown; + (T) -> t_tuple_subtypes(T) + end, + do_opaque(Type, Opaques, Fun). + +t_tuple_subtypes_tuple_list(List, Opaques) -> + lists:append([t_tuple_subtypes_list(Tuples, Opaques) || + {_Size, Tuples} <- List]). + +t_tuple_subtypes_list(List, Opaques) -> + ListOfLists = [t_tuple_subtypes(E, Opaques) || E <- List, E =/= ?none], + lists:append([L || L <- ListOfLists, L =/= 'unknown']). + +-spec t_tuple_subtypes(erl_type()) -> 'unknown' | [erl_type(),...]. + +%% XXX. Not the same as t_tuple_subtypes(T, 'universe')... +t_tuple_subtypes(?tuple(?any, ?any, ?any)) -> unknown; +t_tuple_subtypes(?tuple(_, _, _) = T) -> [T]; +t_tuple_subtypes(?tuple_set(List)) -> + lists:append([Tuples || {_Size, Tuples} <- List]). + +-spec t_is_tuple(erl_type()) -> boolean(). + +t_is_tuple(Type) -> + t_is_tuple(Type, 'universe'). + +-spec t_is_tuple(erl_type(), opaques()) -> boolean(). + +t_is_tuple(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_tuple1/1). + +is_tuple1(?tuple(_, _, _)) -> true; +is_tuple1(?tuple_set(_)) -> true; +is_tuple1(_) -> false. + +%%----------------------------------------------------------------------------- +%% Non-primitive types, including some handy syntactic sugar types +%% + +-spec t_bitstrlist() -> erl_type(). + +t_bitstrlist() -> + t_iolist(1, t_bitstr()). + +-spec t_arity() -> erl_type(). + +t_arity() -> + t_from_range(0, 255). % was t_byte(). + +-spec t_pos_integer() -> erl_type(). + +t_pos_integer() -> + t_from_range(1, pos_inf). + +-spec t_non_neg_integer() -> erl_type(). + +t_non_neg_integer() -> + t_from_range(0, pos_inf). + +-spec t_is_non_neg_integer(erl_type()) -> boolean(). + +t_is_non_neg_integer(?integer(_) = T) -> + t_is_subtype(T, t_non_neg_integer()); +t_is_non_neg_integer(_) -> false. + +-spec t_neg_integer() -> erl_type(). + +t_neg_integer() -> + t_from_range(neg_inf, -1). + +-spec t_fixnum() -> erl_type(). + +t_fixnum() -> + t_integer(). % Gross over-approximation + +-spec t_pos_fixnum() -> erl_type(). + +t_pos_fixnum() -> + t_pos_integer(). % Gross over-approximation + +-spec t_non_neg_fixnum() -> erl_type(). + +t_non_neg_fixnum() -> + t_non_neg_integer(). % Gross over-approximation + +-spec t_mfa() -> erl_type(). + +t_mfa() -> + t_tuple([t_atom(), t_atom(), t_arity()]). + +-spec t_module() -> erl_type(). + +t_module() -> + t_atom(). + +-spec t_node() -> erl_type(). + +t_node() -> + t_atom(). + +-spec t_iodata() -> erl_type(). + +t_iodata() -> + t_sup(t_iolist(), t_binary()). + +-spec t_iolist() -> erl_type(). + +t_iolist() -> + t_iolist(1, t_binary()). + +%% Added a second argument which currently is t_binary() | t_bitstr() +-spec t_iolist(non_neg_integer(), erl_type()) -> erl_type(). + +t_iolist(N, T) when N > 0 -> + t_maybe_improper_list(t_sup([t_iolist(N-1, T), T, t_byte()]), + t_sup(T, t_nil())); +t_iolist(0, T) -> + t_maybe_improper_list(t_any(), t_sup(T, t_nil())). + +-spec t_timeout() -> erl_type(). + +t_timeout() -> + t_sup(t_non_neg_integer(), t_atom('infinity')). + +%%------------------------------------ + +%% ?none is allowed in products. A product of size 1 is not a product. + +-spec t_product([erl_type()]) -> erl_type(). + +t_product([T]) -> T; +t_product(Types) when is_list(Types) -> + ?product(Types). + +%% This function is intended to be the inverse of the one above. +%% It should NOT be used with ?any, ?none or ?unit as input argument. + +-spec t_to_tlist(erl_type()) -> [erl_type()]. + +t_to_tlist(?product(Types)) -> Types; +t_to_tlist(T) when T =/= ?any orelse T =/= ?none orelse T =/= ?unit -> [T]. + +%%------------------------------------ + +-spec t_var(atom() | integer()) -> erl_type(). + +t_var(Atom) when is_atom(Atom) -> ?var(Atom); +t_var(Int) when is_integer(Int) -> ?var(Int). + +-spec t_is_var(erl_type()) -> boolean(). + +t_is_var(?var(_)) -> true; +t_is_var(_) -> false. + +-spec t_var_name(erl_type()) -> atom() | integer(). + +t_var_name(?var(Id)) -> Id. + +-spec t_has_var(erl_type()) -> boolean(). + +t_has_var(?var(_)) -> true; +t_has_var(?function(Domain, Range)) -> + t_has_var(Domain) orelse t_has_var(Range); +t_has_var(?list(Contents, Termination, _)) -> + t_has_var(Contents) orelse t_has_var(Termination); +t_has_var(?product(Types)) -> t_has_var_list(Types); +t_has_var(?tuple(?any, ?any, ?any)) -> false; +t_has_var(?tuple(Elements, _, _)) -> + t_has_var_list(Elements); +t_has_var(?tuple_set(_) = T) -> + t_has_var_list(t_tuple_subtypes(T)); +t_has_var(?map(_, DefK, _)= Map) -> + t_has_var_list(map_all_values(Map)) orelse + t_has_var(DefK); +t_has_var(?opaque(Set)) -> + %% Assume variables in 'args' are also present i 'struct' + t_has_var_list([O#opaque.struct || O <- set_to_list(Set)]); +t_has_var(?union(List)) -> + t_has_var_list(List); +t_has_var(_) -> false. + +-spec t_has_var_list([erl_type()]) -> boolean(). + +t_has_var_list([T|Ts]) -> + t_has_var(T) orelse t_has_var_list(Ts); +t_has_var_list([]) -> false. + +-spec t_collect_vars(erl_type()) -> [erl_type()]. + +t_collect_vars(T) -> + t_collect_vars(T, []). + +-spec t_collect_vars(erl_type(), [erl_type()]) -> [erl_type()]. + +t_collect_vars(?var(_) = Var, Acc) -> + ordsets:add_element(Var, Acc); +t_collect_vars(?function(Domain, Range), Acc) -> + ordsets:union(t_collect_vars(Domain, Acc), t_collect_vars(Range, [])); +t_collect_vars(?list(Contents, Termination, _), Acc) -> + ordsets:union(t_collect_vars(Contents, Acc), t_collect_vars(Termination, [])); +t_collect_vars(?product(Types), Acc) -> + t_collect_vars_list(Types, Acc); +t_collect_vars(?tuple(?any, ?any, ?any), Acc) -> + Acc; +t_collect_vars(?tuple(Types, _, _), Acc) -> + t_collect_vars_list(Types, Acc); +t_collect_vars(?tuple_set(_) = TS, Acc) -> + t_collect_vars_list(t_tuple_subtypes(TS), Acc); +t_collect_vars(?map(_, DefK, _) = Map, Acc0) -> + Acc = t_collect_vars_list(map_all_values(Map), Acc0), + t_collect_vars(DefK, Acc); +t_collect_vars(?opaque(Set), Acc) -> + %% Assume variables in 'args' are also present i 'struct' + t_collect_vars_list([O#opaque.struct || O <- set_to_list(Set)], Acc); +t_collect_vars(?union(List), Acc) -> + t_collect_vars_list(List, Acc); +t_collect_vars(_, Acc) -> + Acc. + +t_collect_vars_list([T|Ts], Acc0) -> + Acc = t_collect_vars(T, Acc0), + t_collect_vars_list(Ts, Acc); +t_collect_vars_list([], Acc) -> Acc. + +%%============================================================================= +%% +%% Type construction from Erlang terms. +%% +%%============================================================================= + +%%----------------------------------------------------------------------------- +%% Make a type from a term. No type depth is enforced. +%% + +-spec t_from_term(term()) -> erl_type(). + +t_from_term([H|T]) -> t_cons(t_from_term(H), t_from_term(T)); +t_from_term([]) -> t_nil(); +t_from_term(T) when is_atom(T) -> t_atom(T); +t_from_term(T) when is_bitstring(T) -> t_bitstr(0, erlang:bit_size(T)); +t_from_term(T) when is_float(T) -> t_float(); +t_from_term(T) when is_function(T) -> + {arity, Arity} = erlang:fun_info(T, arity), + t_fun(Arity, t_any()); +t_from_term(T) when is_integer(T) -> t_integer(T); +t_from_term(T) when is_map(T) -> + Pairs = [{t_from_term(K), ?mand, t_from_term(V)} + || {K, V} <- maps:to_list(T)], + {Stons, Rest} = lists:partition(fun({K,_,_}) -> is_singleton_type(K) end, + Pairs), + {DefK, DefV} + = lists:foldl(fun({K,_,V},{AK,AV}) -> {t_sup(K,AK), t_sup(V,AV)} end, + {t_none(), t_none()}, Rest), + t_map(lists:keysort(1, Stons), DefK, DefV); +t_from_term(T) when is_pid(T) -> t_pid(); +t_from_term(T) when is_port(T) -> t_port(); +t_from_term(T) when is_reference(T) -> t_reference(); +t_from_term(T) when is_tuple(T) -> + t_tuple([t_from_term(E) || E <- tuple_to_list(T)]). + +%%----------------------------------------------------------------------------- +%% Integer types from a range. +%%----------------------------------------------------------------------------- + +%%-define(USE_UNSAFE_RANGES, true). + +-spec t_from_range(rng_elem(), rng_elem()) -> erl_type(). + +-ifdef(USE_UNSAFE_RANGES). + +t_from_range(X, Y) -> + t_from_range_unsafe(X, Y). + +-else. + +t_from_range(neg_inf, pos_inf) -> t_integer(); +t_from_range(neg_inf, Y) when is_integer(Y), Y < 0 -> ?integer_neg; +t_from_range(neg_inf, Y) when is_integer(Y), Y >= 0 -> t_integer(); +t_from_range(X, pos_inf) when is_integer(X), X >= 1 -> ?integer_pos; +t_from_range(X, pos_inf) when is_integer(X), X >= 0 -> ?integer_non_neg; +t_from_range(X, pos_inf) when is_integer(X), X < 0 -> t_integer(); +t_from_range(X, Y) when is_integer(X), is_integer(Y), X > Y -> t_none(); +t_from_range(X, Y) when is_integer(X), is_integer(Y) -> + case ((Y - X) < ?SET_LIMIT) of + true -> t_integers(lists:seq(X, Y)); + false -> + case X >= 0 of + false -> + if Y < 0 -> ?integer_neg; + true -> t_integer() + end; + true -> + if Y =< ?MAX_BYTE, X >= 1 -> ?int_range(1, ?MAX_BYTE); + Y =< ?MAX_BYTE -> t_byte(); + Y =< ?MAX_CHAR, X >= 1 -> ?int_range(1, ?MAX_CHAR); + Y =< ?MAX_CHAR -> t_char(); + X >= 1 -> ?integer_pos; + X >= 0 -> ?integer_non_neg + end + end + end; +t_from_range(pos_inf, neg_inf) -> t_none(). + +-endif. + +-spec t_from_range_unsafe(rng_elem(), rng_elem()) -> erl_type(). + +t_from_range_unsafe(neg_inf, pos_inf) -> t_integer(); +t_from_range_unsafe(neg_inf, Y) -> ?int_range(neg_inf, Y); +t_from_range_unsafe(X, pos_inf) -> ?int_range(X, pos_inf); +t_from_range_unsafe(X, Y) when is_integer(X), is_integer(Y), X =< Y -> + if (Y - X) < ?SET_LIMIT -> t_integers(lists:seq(X, Y)); + true -> ?int_range(X, Y) + end; +t_from_range_unsafe(X, Y) when is_integer(X), is_integer(Y) -> t_none(); +t_from_range_unsafe(pos_inf, neg_inf) -> t_none(). + +-spec t_is_fixnum(erl_type()) -> boolean(). + +t_is_fixnum(?int_range(neg_inf, _)) -> false; +t_is_fixnum(?int_range(_, pos_inf)) -> false; +t_is_fixnum(?int_range(From, To)) -> + is_fixnum(From) andalso is_fixnum(To); +t_is_fixnum(?int_set(Set)) -> + is_fixnum(set_min(Set)) andalso is_fixnum(set_max(Set)); +t_is_fixnum(_) -> false. + +-spec is_fixnum(integer()) -> boolean(). + +is_fixnum(N) when is_integer(N) -> + Bits = ?BITS, + (N =< ((1 bsl (Bits - 1)) - 1)) andalso (N >= -(1 bsl (Bits - 1))). + +infinity_geq(pos_inf, _) -> true; +infinity_geq(_, pos_inf) -> false; +infinity_geq(_, neg_inf) -> true; +infinity_geq(neg_inf, _) -> false; +infinity_geq(A, B) -> A >= B. + +-spec t_is_bitwidth(erl_type()) -> boolean(). + +t_is_bitwidth(?int_range(neg_inf, _)) -> false; +t_is_bitwidth(?int_range(_, pos_inf)) -> false; +t_is_bitwidth(?int_range(From, To)) -> + infinity_geq(From, 0) andalso infinity_geq(?BITS, To); +t_is_bitwidth(?int_set(Set)) -> + infinity_geq(set_min(Set), 0) andalso infinity_geq(?BITS, set_max(Set)); +t_is_bitwidth(_) -> false. + +-spec number_min(erl_type()) -> rng_elem(). + +number_min(Type) -> + number_min(Type, 'universe'). + +-spec number_min(erl_type(), opaques()) -> rng_elem(). + +number_min(Type, Opaques) -> + do_opaque(Type, Opaques, fun number_min2/1). + +number_min2(?int_range(From, _)) -> From; +number_min2(?int_set(Set)) -> set_min(Set); +number_min2(?number(?any, _Tag)) -> neg_inf. + +-spec number_max(erl_type()) -> rng_elem(). + +number_max(Type) -> + number_max(Type, 'universe'). + +-spec number_max(erl_type(), opaques()) -> rng_elem(). + +number_max(Type, Opaques) -> + do_opaque(Type, Opaques, fun number_max2/1). + +number_max2(?int_range(_, To)) -> To; +number_max2(?int_set(Set)) -> set_max(Set); +number_max2(?number(?any, _Tag)) -> pos_inf. + +%% -spec int_range(rgn_elem(), rng_elem()) -> erl_type(). +%% +%% int_range(neg_inf, pos_inf) -> t_integer(); +%% int_range(neg_inf, To) -> ?int_range(neg_inf, To); +%% int_range(From, pos_inf) -> ?int_range(From, pos_inf); +%% int_range(From, To) when From =< To -> t_from_range(From, To); +%% int_range(From, To) when To < From -> ?none. + +in_range(_, ?int_range(neg_inf, pos_inf)) -> true; +in_range(X, ?int_range(From, pos_inf)) -> X >= From; +in_range(X, ?int_range(neg_inf, To)) -> X =< To; +in_range(X, ?int_range(From, To)) -> (X >= From) andalso (X =< To). + +-spec min(rng_elem(), rng_elem()) -> rng_elem(). + +min(neg_inf, _) -> neg_inf; +min(_, neg_inf) -> neg_inf; +min(pos_inf, Y) -> Y; +min(X, pos_inf) -> X; +min(X, Y) when X =< Y -> X; +min(_, Y) -> Y. + +-spec max(rng_elem(), rng_elem()) -> rng_elem(). + +max(neg_inf, Y) -> Y; +max(X, neg_inf) -> X; +max(pos_inf, _) -> pos_inf; +max(_, pos_inf) -> pos_inf; +max(X, Y) when X =< Y -> Y; +max(X, _) -> X. + +expand_range_from_set(Range = ?int_range(From, To), Set) -> + Min = min(set_min(Set), From), + Max = max(set_max(Set), To), + if From =:= Min, To =:= Max -> Range; + true -> t_from_range(Min, Max) + end. + +%%============================================================================= +%% +%% Lattice operations +%% +%%============================================================================= + +%%----------------------------------------------------------------------------- +%% Supremum +%% + +-spec t_sup([erl_type()]) -> erl_type(). + +t_sup([]) -> ?none; +t_sup(Ts) -> + case lists:any(fun is_any/1, Ts) of + true -> ?any; + false -> + t_sup1(Ts, []) + end. + +t_sup1([H1, H2|T], L) -> + t_sup1(T, [t_sup(H1, H2)|L]); +t_sup1([T], []) -> subst_all_vars_to_any(T); +t_sup1(Ts, L) -> + t_sup1(Ts++L, []). + +-spec t_sup(erl_type(), erl_type()) -> erl_type(). + +t_sup(?any, _) -> ?any; +t_sup(_, ?any) -> ?any; +t_sup(?none, T) -> T; +t_sup(T, ?none) -> T; +t_sup(?unit, T) -> T; +t_sup(T, ?unit) -> T; +t_sup(T, T) -> subst_all_vars_to_any(T); +t_sup(?var(_), _) -> ?any; +t_sup(_, ?var(_)) -> ?any; +t_sup(?atom(Set1), ?atom(Set2)) -> + ?atom(set_union(Set1, Set2)); +t_sup(?bitstr(U1, B1), ?bitstr(U2, B2)) -> + t_bitstr(gcd(gcd(U1, U2), abs(B1-B2)), lists:min([B1, B2])); +t_sup(?function(Domain1, Range1), ?function(Domain2, Range2)) -> + %% The domain is either a product or any. + ?function(t_sup(Domain1, Domain2), t_sup(Range1, Range2)); +t_sup(?identifier(Set1), ?identifier(Set2)) -> + ?identifier(set_union(Set1, Set2)); +t_sup(?opaque(Set1), ?opaque(Set2)) -> + sup_opaque(set_to_list(ordsets:union(Set1, Set2))); +%%Disallow unions with opaque types +%%t_sup(T1=?opaque(_,_,_), T2) -> +%% io:format("Debug: t_sup executed with args ~w and ~w~n",[T1, T2]), ?none; +%%t_sup(T1, T2=?opaque(_,_,_)) -> +%% io:format("Debug: t_sup executed with args ~w and ~w~n",[T1, T2]), ?none; +t_sup(?matchstate(Pres1, Slots1), ?matchstate(Pres2, Slots2)) -> + ?matchstate(t_sup(Pres1, Pres2), t_sup(Slots1, Slots2)); +t_sup(?nil, ?nil) -> ?nil; +t_sup(?nil, ?list(Contents, Termination, _)) -> + ?list(Contents, t_sup(?nil, Termination), ?unknown_qual); +t_sup(?list(Contents, Termination, _), ?nil) -> + ?list(Contents, t_sup(?nil, Termination), ?unknown_qual); +t_sup(?list(Contents1, Termination1, Size1), + ?list(Contents2, Termination2, Size2)) -> + NewSize = + case {Size1, Size2} of + {?unknown_qual, ?unknown_qual} -> ?unknown_qual; + {?unknown_qual, ?nonempty_qual} -> ?unknown_qual; + {?nonempty_qual, ?unknown_qual} -> ?unknown_qual; + {?nonempty_qual, ?nonempty_qual} -> ?nonempty_qual + end, + NewContents = t_sup(Contents1, Contents2), + NewTermination = t_sup(Termination1, Termination2), + TmpList = t_cons(NewContents, NewTermination), + case NewSize of + ?nonempty_qual -> TmpList; + ?unknown_qual -> + ?list(FinalContents, FinalTermination, _) = TmpList, + ?list(FinalContents, FinalTermination, ?unknown_qual) + end; +t_sup(?number(_, _), ?number(?any, ?unknown_qual) = T) -> T; +t_sup(?number(?any, ?unknown_qual) = T, ?number(_, _)) -> T; +t_sup(?float, ?float) -> ?float; +t_sup(?float, ?integer(_)) -> t_number(); +t_sup(?integer(_), ?float) -> t_number(); +t_sup(?integer(?any) = T, ?integer(_)) -> T; +t_sup(?integer(_), ?integer(?any) = T) -> T; +t_sup(?int_set(Set1), ?int_set(Set2)) -> + case set_union(Set1, Set2) of + ?any -> + t_from_range(min(set_min(Set1), set_min(Set2)), + max(set_max(Set1), set_max(Set2))); + Set -> ?int_set(Set) + end; +t_sup(?int_range(From1, To1), ?int_range(From2, To2)) -> + t_from_range(min(From1, From2), max(To1, To2)); +t_sup(Range = ?int_range(_, _), ?int_set(Set)) -> + expand_range_from_set(Range, Set); +t_sup(?int_set(Set), Range = ?int_range(_, _)) -> + expand_range_from_set(Range, Set); +t_sup(?product(Types1), ?product(Types2)) -> + L1 = length(Types1), + L2 = length(Types2), + if L1 =:= L2 -> ?product(t_sup_lists(Types1, Types2)); + true -> ?any + end; +t_sup(?product(_), _) -> + ?any; +t_sup(_, ?product(_)) -> + ?any; +t_sup(?tuple(?any, ?any, ?any) = T, ?tuple(_, _, _)) -> T; +t_sup(?tuple(_, _, _), ?tuple(?any, ?any, ?any) = T) -> T; +t_sup(?tuple(?any, ?any, ?any) = T, ?tuple_set(_)) -> T; +t_sup(?tuple_set(_), ?tuple(?any, ?any, ?any) = T) -> T; +t_sup(?tuple(Elements1, Arity, Tag1) = T1, + ?tuple(Elements2, Arity, Tag2) = T2) -> + if Tag1 =:= Tag2 -> t_tuple(t_sup_lists(Elements1, Elements2)); + Tag1 =:= ?any -> t_tuple(t_sup_lists(Elements1, Elements2)); + Tag2 =:= ?any -> t_tuple(t_sup_lists(Elements1, Elements2)); + Tag1 < Tag2 -> ?tuple_set([{Arity, [T1, T2]}]); + Tag1 > Tag2 -> ?tuple_set([{Arity, [T2, T1]}]) + end; +t_sup(?tuple(_, Arity1, _) = T1, ?tuple(_, Arity2, _) = T2) -> + sup_tuple_sets([{Arity1, [T1]}], [{Arity2, [T2]}]); +t_sup(?tuple_set(List1), ?tuple_set(List2)) -> + sup_tuple_sets(List1, List2); +t_sup(?tuple_set(List1), T2 = ?tuple(_, Arity, _)) -> + sup_tuple_sets(List1, [{Arity, [T2]}]); +t_sup(?tuple(_, Arity, _) = T1, ?tuple_set(List2)) -> + sup_tuple_sets([{Arity, [T1]}], List2); +t_sup(?map(_, ADefK, ADefV) = A, ?map(_, BDefK, BDefV) = B) -> + Pairs = + map_pairwise_merge( + fun(K, MNess, V1, MNess, V2) -> {K, MNess, t_sup(V1, V2)}; + (K, _, V1, _, V2) -> {K, ?opt, t_sup(V1, V2)} + end, A, B), + t_map(Pairs, t_sup(ADefK, BDefK), t_sup(ADefV, BDefV)); +t_sup(T1, T2) -> + ?union(U1) = force_union(T1), + ?union(U2) = force_union(T2), + sup_union(U1, U2). + +sup_opaque([]) -> ?none; +sup_opaque(List) -> + L = sup_opaq(List), + ?opaque(ordsets:from_list(L)). + +sup_opaq(L0) -> + L1 = [{{Mod,Name,Args}, T} || + #opaque{mod = Mod, name = Name, args = Args}=T <- L0], + F = family(L1), + [supl(Ts) || {_, Ts} <- F]. + +supl([O]) -> O; +supl(Ts) -> supl(Ts, t_none()). + +supl([#opaque{struct = S}=O|L], S0) -> + S1 = t_sup(S, S0), + case L =:= [] of + true -> O#opaque{struct = S1}; + false -> supl(L, S1) + end. + +-spec t_sup_lists([erl_type()], [erl_type()]) -> [erl_type()]. + +t_sup_lists([T1|Left1], [T2|Left2]) -> + [t_sup(T1, T2)|t_sup_lists(Left1, Left2)]; +t_sup_lists([], []) -> + []. + +sup_tuple_sets(L1, L2) -> + TotalArities = ordsets:union([Arity || {Arity, _} <- L1], + [Arity || {Arity, _} <- L2]), + if length(TotalArities) > ?TUPLE_ARITY_LIMIT -> t_tuple(); + true -> + case sup_tuple_sets(L1, L2, []) of + [{_Arity, [OneTuple = ?tuple(_, _, _)]}] -> OneTuple; + List -> ?tuple_set(List) + end + end. + +sup_tuple_sets([{Arity, Tuples1}|Left1], [{Arity, Tuples2}|Left2], Acc) -> + NewAcc = [{Arity, sup_tuples_in_set(Tuples1, Tuples2)}|Acc], + sup_tuple_sets(Left1, Left2, NewAcc); +sup_tuple_sets([{Arity1, _} = T1|Left1] = L1, + [{Arity2, _} = T2|Left2] = L2, Acc) -> + if Arity1 < Arity2 -> sup_tuple_sets(Left1, L2, [T1|Acc]); + Arity1 > Arity2 -> sup_tuple_sets(L1, Left2, [T2|Acc]) + end; +sup_tuple_sets([], L2, Acc) -> lists:reverse(Acc, L2); +sup_tuple_sets(L1, [], Acc) -> lists:reverse(Acc, L1). + +sup_tuples_in_set([?tuple(_, _, ?any) = T], L) -> + [t_tuple(sup_tuple_elements([T|L]))]; +sup_tuples_in_set(L, [?tuple(_, _, ?any) = T]) -> + [t_tuple(sup_tuple_elements([T|L]))]; +sup_tuples_in_set(L1, L2) -> + FoldFun = fun(?tuple(_, _, Tag), AccTag) -> t_sup(Tag, AccTag) end, + TotalTag0 = lists:foldl(FoldFun, ?none, L1), + TotalTag = lists:foldl(FoldFun, TotalTag0, L2), + case TotalTag of + ?atom(?any) -> + %% We will reach the set limit. Widen now. + [t_tuple(sup_tuple_elements(L1 ++ L2))]; + ?atom(Set) -> + case set_size(Set) > ?TUPLE_TAG_LIMIT of + true -> + %% We will reach the set limit. Widen now. + [t_tuple(sup_tuple_elements(L1 ++ L2))]; + false -> + %% We can go on and build the tuple set. + sup_tuples_in_set(L1, L2, []) + end + end. + +sup_tuple_elements([?tuple(Elements, _, _)|L]) -> + lists:foldl(fun (?tuple(Es, _, _), Acc) -> t_sup_lists(Es, Acc) end, + Elements, L). + +sup_tuples_in_set([?tuple(Elements1, Arity, Tag1) = T1|Left1] = L1, + [?tuple(Elements2, Arity, Tag2) = T2|Left2] = L2, Acc) -> + if + Tag1 < Tag2 -> sup_tuples_in_set(Left1, L2, [T1|Acc]); + Tag1 > Tag2 -> sup_tuples_in_set(L1, Left2, [T2|Acc]); + Tag2 =:= Tag2 -> NewElements = t_sup_lists(Elements1, Elements2), + NewAcc = [?tuple(NewElements, Arity, Tag1)|Acc], + sup_tuples_in_set(Left1, Left2, NewAcc) + end; +sup_tuples_in_set([], L2, Acc) -> lists:reverse(Acc, L2); +sup_tuples_in_set(L1, [], Acc) -> lists:reverse(Acc, L1). + +sup_union(U1, U2) -> + sup_union(U1, U2, 0, []). + +sup_union([?none|Left1], [?none|Left2], N, Acc) -> + sup_union(Left1, Left2, N, [?none|Acc]); +sup_union([T1|Left1], [T2|Left2], N, Acc) -> + sup_union(Left1, Left2, N+1, [t_sup(T1, T2)|Acc]); +sup_union([], [], N, Acc) -> + if N =:= 0 -> ?none; + N =:= 1 -> + [Type] = [T || T <- Acc, T =/= ?none], + Type; + N =:= length(Acc) -> ?any; + true -> ?union(lists:reverse(Acc)) + end. + +force_union(T = ?atom(_)) -> ?atom_union(T); +force_union(T = ?bitstr(_, _)) -> ?bitstr_union(T); +force_union(T = ?function(_, _)) -> ?function_union(T); +force_union(T = ?identifier(_)) -> ?identifier_union(T); +force_union(T = ?list(_, _, _)) -> ?list_union(T); +force_union(T = ?nil) -> ?list_union(T); +force_union(T = ?number(_, _)) -> ?number_union(T); +force_union(T = ?opaque(_)) -> ?opaque_union(T); +force_union(T = ?map(_,_,_)) -> ?map_union(T); +force_union(T = ?tuple(_, _, _)) -> ?tuple_union(T); +force_union(T = ?tuple_set(_)) -> ?tuple_union(T); +force_union(T = ?matchstate(_, _)) -> ?matchstate_union(T); +force_union(T = ?union(_)) -> T. + +%%----------------------------------------------------------------------------- +%% An attempt to write the inverse operation of t_sup/1 -- XXX: INCOMPLETE !! +%% + +-spec t_elements(erl_type()) -> [erl_type()]. + +t_elements(?none) -> []; +t_elements(?unit) -> []; +t_elements(?any = T) -> [T]; +t_elements(?nil = T) -> [T]; +t_elements(?atom(?any) = T) -> [T]; +t_elements(?atom(Atoms)) -> + [t_atom(A) || A <- Atoms]; +t_elements(?bitstr(_, _) = T) -> [T]; +t_elements(?function(_, _) = T) -> [T]; +t_elements(?identifier(?any) = T) -> [T]; +t_elements(?identifier(IDs)) -> + [?identifier([T]) || T <- IDs]; +t_elements(?list(_, _, _) = T) -> [T]; +t_elements(?number(_, _) = T) -> + case T of + ?number(?any, ?unknown_qual) -> + [?float, ?integer(?any)]; + ?float -> [T]; + ?integer(?any) -> [T]; + ?int_range(_, _) -> [T]; + ?int_set(Set) -> + [t_integer(I) || I <- Set] + end; +t_elements(?opaque(_) = T) -> + do_elements(T); +t_elements(?map(_,_,_) = T) -> [T]; +t_elements(?tuple(_, _, _) = T) -> [T]; +t_elements(?tuple_set(_) = TS) -> + case t_tuple_subtypes(TS) of + unknown -> []; + Elems -> Elems + end; +t_elements(?union(_) = T) -> + do_elements(T); +t_elements(?var(_)) -> [?any]. %% yes, vars exist -- what else to do here? +%% t_elements(T) -> +%% io:format("T_ELEMENTS => ~p\n", [T]). + +do_elements(Type0) -> + case do_opaque(Type0, 'universe', fun(T) -> T end) of + ?union(List) -> lists:append([t_elements(T) || T <- List]); + Type -> t_elements(Type) + end. + +%%----------------------------------------------------------------------------- +%% Infimum +%% + +-spec t_inf([erl_type()]) -> erl_type(). + +t_inf([H1, H2|T]) -> + case t_inf(H1, H2) of + ?none -> ?none; + NewH -> t_inf([NewH|T]) + end; +t_inf([H]) -> H; +t_inf([]) -> ?none. + +-spec t_inf(erl_type(), erl_type()) -> erl_type(). + +t_inf(T1, T2) -> + t_inf(T1, T2, 'universe'). + +%% 'match' should be used from t_find_unknown_opaque() only +-type t_inf_opaques() :: opaques() | {'match', [erl_type() | 'universe']}. + +-spec t_inf(erl_type(), erl_type(), t_inf_opaques()) -> erl_type(). + +t_inf(?var(_), ?var(_), _Opaques) -> ?any; +t_inf(?var(_), T, _Opaques) -> subst_all_vars_to_any(T); +t_inf(T, ?var(_), _Opaques) -> subst_all_vars_to_any(T); +t_inf(?any, T, _Opaques) -> subst_all_vars_to_any(T); +t_inf(T, ?any, _Opaques) -> subst_all_vars_to_any(T); +t_inf(?none, _, _Opaques) -> ?none; +t_inf(_, ?none, _Opaques) -> ?none; +t_inf(?unit, _, _Opaques) -> ?unit; % ?unit cases should appear below ?none +t_inf(_, ?unit, _Opaques) -> ?unit; +t_inf(T, T, _Opaques) -> subst_all_vars_to_any(T); +t_inf(?atom(Set1), ?atom(Set2), _) -> + case set_intersection(Set1, Set2) of + ?none -> ?none; + NewSet -> ?atom(NewSet) + end; +t_inf(?bitstr(U1, B1), ?bitstr(0, B2), _Opaques) -> + if B2 >= B1 andalso (B2-B1) rem U1 =:= 0 -> t_bitstr(0, B2); + true -> ?none + end; +t_inf(?bitstr(0, B1), ?bitstr(U2, B2), _Opaques) -> + if B1 >= B2 andalso (B1-B2) rem U2 =:= 0 -> t_bitstr(0, B1); + true -> ?none + end; +t_inf(?bitstr(U1, B1), ?bitstr(U1, B1), _Opaques) -> + t_bitstr(U1, B1); +t_inf(?bitstr(U1, B1), ?bitstr(U2, B2), _Opaques) when U2 > U1 -> + inf_bitstr(U2, B2, U1, B1); +t_inf(?bitstr(U1, B1), ?bitstr(U2, B2), _Opaques) -> + inf_bitstr(U1, B1, U2, B2); +t_inf(?function(Domain1, Range1), ?function(Domain2, Range2), Opaques) -> + case t_inf(Domain1, Domain2, Opaques) of + ?none -> ?none; + Domain -> ?function(Domain, t_inf(Range1, Range2, Opaques)) + end; +t_inf(?identifier(Set1), ?identifier(Set2), _Opaques) -> + case set_intersection(Set1, Set2) of + ?none -> ?none; + Set -> ?identifier(Set) + end; +t_inf(?map(_, ADefK, ADefV) = A, ?map(_, BDefK, BDefV) = B, _Opaques) -> + %% Because it simplifies the anonymous function, we allow Pairs to temporarily + %% contain mandatory pairs with none values, since all such cases should + %% result in a none result. + Pairs = + map_pairwise_merge( + %% For optional keys in both maps, when the infinimum is none, we have + %% essentially concluded that K must not be a key in the map. + fun(K, ?opt, V1, ?opt, V2) -> {K, ?opt, t_inf(V1, V2)}; + %% When a key is optional in one map, but mandatory in another, it + %% becomes mandatory in the infinumum + (K, _, V1, _, V2) -> {K, ?mand, t_inf(V1, V2)} + end, A, B), + %% If the infinimum of any mandatory values is ?none, the entire map infinimum + %% is ?none. + case lists:any(fun({_,?mand,?none})->true; ({_,_,_}) -> false end, Pairs) of + true -> t_none(); + false -> t_map(Pairs, t_inf(ADefK, BDefK), t_inf(ADefV, BDefV)) + end; +t_inf(?matchstate(Pres1, Slots1), ?matchstate(Pres2, Slots2), _Opaques) -> + ?matchstate(t_inf(Pres1, Pres2), t_inf(Slots1, Slots2)); +t_inf(?nil, ?nil, _Opaques) -> ?nil; +t_inf(?nil, ?nonempty_list(_, _), _Opaques) -> + ?none; +t_inf(?nonempty_list(_, _), ?nil, _Opaques) -> + ?none; +t_inf(?nil, ?list(_Contents, Termination, _), Opaques) -> + t_inf(?nil, t_unopaque(Termination), Opaques); +t_inf(?list(_Contents, Termination, _), ?nil, Opaques) -> + t_inf(?nil, t_unopaque(Termination), Opaques); +t_inf(?list(Contents1, Termination1, Size1), + ?list(Contents2, Termination2, Size2), Opaques) -> + case t_inf(Termination1, Termination2, Opaques) of + ?none -> ?none; + Termination -> + case t_inf(Contents1, Contents2, Opaques) of + ?none -> + %% If none of the lists are nonempty, then the infimum is nil. + case (Size1 =:= ?unknown_qual) andalso (Size2 =:= ?unknown_qual) of + true -> t_nil(); + false -> ?none + end; + Contents -> + Size = + case {Size1, Size2} of + {?unknown_qual, ?unknown_qual} -> ?unknown_qual; + {?unknown_qual, ?nonempty_qual} -> ?nonempty_qual; + {?nonempty_qual, ?unknown_qual} -> ?nonempty_qual; + {?nonempty_qual, ?nonempty_qual} -> ?nonempty_qual + end, + ?list(Contents, Termination, Size) + end + end; +t_inf(?number(_, _) = T1, ?number(_, _) = T2, _Opaques) -> + case {T1, T2} of + {T, T} -> T; + {_, ?number(?any, ?unknown_qual)} -> T1; + {?number(?any, ?unknown_qual), _} -> T2; + {?float, ?integer(_)} -> ?none; + {?integer(_), ?float} -> ?none; + {?integer(?any), ?integer(_)} -> T2; + {?integer(_), ?integer(?any)} -> T1; + {?int_set(Set1), ?int_set(Set2)} -> + case set_intersection(Set1, Set2) of + ?none -> ?none; + Set -> ?int_set(Set) + end; + {?int_range(From1, To1), ?int_range(From2, To2)} -> + t_from_range(max(From1, From2), min(To1, To2)); + {Range = ?int_range(_, _), ?int_set(Set)} -> + %% io:format("t_inf range, set args ~p ~p ~n", [T1, T2]), + Ans2 = + case set_filter(fun(X) -> in_range(X, Range) end, Set) of + ?none -> ?none; + NewSet -> ?int_set(NewSet) + end, + %% io:format("Ans2 ~p ~n", [Ans2]), + Ans2; + {?int_set(Set), ?int_range(_, _) = Range} -> + case set_filter(fun(X) -> in_range(X, Range) end, Set) of + ?none -> ?none; + NewSet -> ?int_set(NewSet) + end + end; +t_inf(?product(Types1), ?product(Types2), Opaques) -> + L1 = length(Types1), + L2 = length(Types2), + if L1 =:= L2 -> ?product(t_inf_lists(Types1, Types2, Opaques)); + true -> ?none + end; +t_inf(?product(_), _, _Opaques) -> + ?none; +t_inf(_, ?product(_), _Opaques) -> + ?none; +t_inf(?tuple(?any, ?any, ?any), ?tuple(_, _, _) = T, _Opaques) -> + subst_all_vars_to_any(T); +t_inf(?tuple(_, _, _) = T, ?tuple(?any, ?any, ?any), _Opaques) -> + subst_all_vars_to_any(T); +t_inf(?tuple(?any, ?any, ?any), ?tuple_set(_) = T, _Opaques) -> + subst_all_vars_to_any(T); +t_inf(?tuple_set(_) = T, ?tuple(?any, ?any, ?any), _Opaques) -> + subst_all_vars_to_any(T); +t_inf(?tuple(Elements1, Arity, _Tag1), ?tuple(Elements2, Arity, _Tag2), Opaques) -> + case t_inf_lists_strict(Elements1, Elements2, Opaques) of + bottom -> ?none; + NewElements -> t_tuple(NewElements) + end; +t_inf(?tuple_set(List1), ?tuple_set(List2), Opaques) -> + inf_tuple_sets(List1, List2, Opaques); +t_inf(?tuple_set(List), ?tuple(_, Arity, _) = T, Opaques) -> + inf_tuple_sets(List, [{Arity, [T]}], Opaques); +t_inf(?tuple(_, Arity, _) = T, ?tuple_set(List), Opaques) -> + inf_tuple_sets(List, [{Arity, [T]}], Opaques); +%% be careful: here and in the next clause T can be ?opaque +t_inf(?union(U1), T, Opaques) -> + ?union(U2) = force_union(T), + inf_union(U1, U2, Opaques); +t_inf(T, ?union(U2), Opaques) -> + ?union(U1) = force_union(T), + inf_union(U1, U2, Opaques); +t_inf(?opaque(Set1), ?opaque(Set2), Opaques) -> + inf_opaque(Set1, Set2, Opaques); +t_inf(?opaque(_) = T1, T2, Opaques) -> + inf_opaque1(T2, T1, 1, Opaques); +t_inf(T1, ?opaque(_) = T2, Opaques) -> + inf_opaque1(T1, T2, 2, Opaques); +%% and as a result, the cases for ?opaque should appear *after* ?union +t_inf(#c{}, #c{}, _) -> + ?none. + +inf_opaque1(T1, ?opaque(Set2)=T2, Pos, Opaques) -> + case Opaques =:= 'universe' orelse inf_is_opaque_type(T2, Pos, Opaques) of + false -> ?none; + true -> + List2 = set_to_list(Set2), + case inf_collect(T1, List2, Opaques, []) of + [] -> ?none; + OpL -> ?opaque(ordsets:from_list(OpL)) + end + end. + +inf_is_opaque_type(T, Pos, {match, Opaques}) -> + is_opaque_type(T, Opaques) orelse throw({pos, [Pos]}); +inf_is_opaque_type(T, _Pos, Opaques) -> + is_opaque_type(T, Opaques). + +inf_collect(T1, [T2|List2], Opaques, OpL) -> + #opaque{struct = S2} = T2, + case t_inf(T1, S2, Opaques) of + ?none -> inf_collect(T1, List2, Opaques, OpL); + Inf -> + Op = T2#opaque{struct = Inf}, + inf_collect(T1, List2, Opaques, [Op|OpL]) + end; +inf_collect(_T1, [], _Opaques, OpL) -> + OpL. + +combine(S, T1, T2) -> + #opaque{mod = Mod1, name = Name1, args = Args1} = T1, + #opaque{mod = Mod2, name = Name2, args = Args2} = T2, + Comb1 = comb(Mod1, Name1, Args1, S, T1), + case is_compat_opaque_names({Mod1, Name1, Args1}, {Mod2, Name2, Args2}) of + true -> Comb1; + false -> Comb1 ++ comb(Mod2, Name2, Args2, S, T2) + end. + +comb(Mod, Name, Args, S, T) -> + case can_combine_opaque_names(Mod, Name, Args, S) of + true -> + ?opaque(Set) = S, + Set; + false -> + [T#opaque{struct = S}] + end. + +can_combine_opaque_names(Mod1, Name1, Args1, + ?opaque([#opaque{mod = Mod2, name = Name2, args = Args2}])) -> + is_compat_opaque_names({Mod1, Name1, Args1}, {Mod2, Name2, Args2}); +can_combine_opaque_names(_, _, _, _) -> false. + +%% Combining two lists this way can be very time consuming... +%% Note: two parameterized opaque types are not the same if their +%% actual parameters differ +inf_opaque(Set1, Set2, Opaques) -> + List1 = inf_look_up(Set1, Opaques), + List2 = inf_look_up(Set2, Opaques), + List0 = [combine(Inf, T1, T2) || + {Is1, ModNameArgs1, T1} <- List1, + {Is2, ModNameArgs2, T2} <- List2, + not t_is_none(Inf = inf_opaque_types(Is1, ModNameArgs1, T1, + Is2, ModNameArgs2, T2, + Opaques))], + List = lists:sort(lists:append(List0)), + sup_opaque(List). + +%% Optimization: do just one lookup. +inf_look_up(Set, Opaques) -> + [{Opaques =:= 'universe' orelse inf_is_opaque_type2(T, Opaques), + {M, N, Args}, T} || + #opaque{mod = M, name = N, args = Args} = T <- set_to_list(Set)]. + +inf_is_opaque_type2(T, {match, Opaques}) -> + is_opaque_type2(T, Opaques); +inf_is_opaque_type2(T, Opaques) -> + is_opaque_type2(T, Opaques). + +inf_opaque_types(IsOpaque1, ModNameArgs1, T1, + IsOpaque2, ModNameArgs2, T2, Opaques) -> + #opaque{struct = S1}=T1, + #opaque{struct = S2}=T2, + case + Opaques =:= 'universe' orelse + is_compat_opaque_names(ModNameArgs1, ModNameArgs2) + of + true -> t_inf(S1, S2, Opaques); + false -> + case {IsOpaque1, IsOpaque2} of + {true, true} -> t_inf(S1, S2, Opaques); + {true, false} -> t_inf(S1, ?opaque(set_singleton(T2)), Opaques); + {false, true} -> t_inf(?opaque(set_singleton(T1)), S2, Opaques); + {false, false} when element(1, Opaques) =:= match -> + throw({pos, [1, 2]}); + {false, false} -> t_none() + end + end. + +is_compat_opaque_names(ModNameArgs, ModNameArgs) -> true; +is_compat_opaque_names({Mod,Name,Args1}, {Mod,Name,Args2}) -> + is_compat_args(Args1, Args2); +is_compat_opaque_names(_, _) -> false. + +is_compat_args([A1|Args1], [A2|Args2]) -> + is_compat_arg(A1, A2) andalso is_compat_args(Args1, Args2); +is_compat_args([], []) -> true; +is_compat_args(_, _) -> false. + +is_compat_arg(A1, A2) -> + is_specialization(A1, A2) orelse is_specialization(A2, A1). + +-spec is_specialization(erl_type(), erl_type()) -> boolean(). + +%% Returns true if the first argument is a specialization of the +%% second argument in the sense that every type is a specialization of +%% any(). For example, {_,_} is a specialization of any(), but not of +%% tuple(). Does not handle variables, but any() and unions (sort of). + +is_specialization(T, T) -> true; +is_specialization(_, ?any) -> true; +is_specialization(?any, _) -> false; +is_specialization(?function(Domain1, Range1), ?function(Domain2, Range2)) -> + (is_specialization(Domain1, Domain2) andalso + is_specialization(Range1, Range2)); +is_specialization(?list(Contents1, Termination1, Size1), + ?list(Contents2, Termination2, Size2)) -> + (Size1 =:= Size2 andalso + is_specialization(Contents1, Contents2) andalso + is_specialization(Termination1, Termination2)); +is_specialization(?product(Types1), ?product(Types2)) -> + specialization_list(Types1, Types2); +is_specialization(?tuple(?any, ?any, ?any), ?tuple(_, _, _)) -> false; +is_specialization(?tuple(_, _, _), ?tuple(?any, ?any, ?any)) -> false; +is_specialization(?tuple(Elements1, Arity, _), + ?tuple(Elements2, Arity, _)) when Arity =/= ?any -> + specialization_list(Elements1, Elements2); +is_specialization(?tuple_set([{Arity, List}]), + ?tuple(Elements2, Arity, _)) when Arity =/= ?any -> + specialization_list(sup_tuple_elements(List), Elements2); +is_specialization(?tuple(Elements1, Arity, _), + ?tuple_set([{Arity, List}])) when Arity =/= ?any -> + specialization_list(Elements1, sup_tuple_elements(List)); +is_specialization(?tuple_set(List1), ?tuple_set(List2)) -> + try + specialization_list_list([sup_tuple_elements(T) || {_Arity, T} <- List1], + [sup_tuple_elements(T) || {_Arity, T} <- List2]) + catch _:_ -> false + end; +is_specialization(?union(List1)=T1, ?union(List2)=T2) -> + case specialization_union2(T1, T2) of + {yes, Type1, Type2} -> is_specialization(Type1, Type2); + no -> specialization_list(List1, List2) + end; +is_specialization(?union(List), T2) -> + case unify_union(List) of + {yes, Type} -> is_specialization(Type, T2); + no -> false + end; +is_specialization(T1, ?union(List)) -> + case unify_union(List) of + {yes, Type} -> is_specialization(T1, Type); + no -> false + end; +is_specialization(?opaque(_) = T1, T2) -> + is_specialization(t_opaque_structure(T1), T2); +is_specialization(T1, ?opaque(_) = T2) -> + is_specialization(T1, t_opaque_structure(T2)); +is_specialization(?var(_), _) -> exit(error); +is_specialization(_, ?var(_)) -> exit(error); +is_specialization(?none, _) -> false; +is_specialization(_, ?none) -> false; +is_specialization(?unit, _) -> false; +is_specialization(_, ?unit) -> false; +is_specialization(#c{}, #c{}) -> false. + +specialization_list_list(LL1, LL2) -> + length(LL1) =:= length(LL2) andalso specialization_list_list1(LL1, LL2). + +specialization_list_list1([], []) -> true; +specialization_list_list1([L1|LL1], [L2|LL2]) -> + specialization_list(L1, L2) andalso specialization_list_list1(LL1, LL2). + +specialization_list(L1, L2) -> + length(L1) =:= length(L2) andalso specialization_list1(L1, L2). + +specialization_list1([], []) -> true; +specialization_list1([T1|L1], [T2|L2]) -> + is_specialization(T1, T2) andalso specialization_list1(L1, L2). + +specialization_union2(?union(List1)=T1, ?union(List2)=T2) -> + case {unify_union(List1), unify_union(List2)} of + {{yes, Type1}, {yes, Type2}} -> {yes, Type1, Type2}; + {{yes, Type1}, no} -> {yes, Type1, T2}; + {no, {yes, Type2}} -> {yes, T1, Type2}; + {no, no} -> no + end. + +-spec t_inf_lists([erl_type()], [erl_type()]) -> [erl_type()]. + +t_inf_lists(L1, L2) -> + t_inf_lists(L1, L2, 'universe'). + +-spec t_inf_lists([erl_type()], [erl_type()], t_inf_opaques()) -> [erl_type()]. + +t_inf_lists(L1, L2, Opaques) -> + t_inf_lists(L1, L2, [], Opaques). + +-spec t_inf_lists([erl_type()], [erl_type()], [erl_type()], [erl_type()]) -> [erl_type()]. + +t_inf_lists([T1|Left1], [T2|Left2], Acc, Opaques) -> + t_inf_lists(Left1, Left2, [t_inf(T1, T2, Opaques)|Acc], Opaques); +t_inf_lists([], [], Acc, _Opaques) -> + lists:reverse(Acc). + +%% Infimum of lists with strictness. +%% If any element is the ?none type, the value 'bottom' is returned. + +-spec t_inf_lists_strict([erl_type()], [erl_type()], [erl_type()]) -> 'bottom' | [erl_type()]. + +t_inf_lists_strict(L1, L2, Opaques) -> + t_inf_lists_strict(L1, L2, [], Opaques). + +-spec t_inf_lists_strict([erl_type()], [erl_type()], [erl_type()], [erl_type()]) -> 'bottom' | [erl_type()]. + +t_inf_lists_strict([T1|Left1], [T2|Left2], Acc, Opaques) -> + case t_inf(T1, T2, Opaques) of + ?none -> bottom; + T -> t_inf_lists_strict(Left1, Left2, [T|Acc], Opaques) + end; +t_inf_lists_strict([], [], Acc, _Opaques) -> + lists:reverse(Acc). + +inf_tuple_sets(L1, L2, Opaques) -> + case inf_tuple_sets(L1, L2, [], Opaques) of + [] -> ?none; + [{_Arity, [?tuple(_, _, _) = OneTuple]}] -> OneTuple; + List -> ?tuple_set(List) + end. + +inf_tuple_sets([{Arity, Tuples1}|Ts1], [{Arity, Tuples2}|Ts2], Acc, Opaques) -> + case inf_tuples_in_sets(Tuples1, Tuples2, Opaques) of + [] -> inf_tuple_sets(Ts1, Ts2, Acc, Opaques); + [?tuple_set([{Arity, NewTuples}])] -> + inf_tuple_sets(Ts1, Ts2, [{Arity, NewTuples}|Acc], Opaques); + NewTuples -> inf_tuple_sets(Ts1, Ts2, [{Arity, NewTuples}|Acc], Opaques) + end; +inf_tuple_sets([{Arity1, _}|Ts1] = L1, [{Arity2, _}|Ts2] = L2, Acc, Opaques) -> + if Arity1 < Arity2 -> inf_tuple_sets(Ts1, L2, Acc, Opaques); + Arity1 > Arity2 -> inf_tuple_sets(L1, Ts2, Acc, Opaques) + end; +inf_tuple_sets([], _, Acc, _Opaques) -> lists:reverse(Acc); +inf_tuple_sets(_, [], Acc, _Opaques) -> lists:reverse(Acc). + +inf_tuples_in_sets([?tuple(Elements1, _, ?any)], L2, Opaques) -> + NewList = [t_inf_lists_strict(Elements1, Elements2, Opaques) + || ?tuple(Elements2, _, _) <- L2], + [t_tuple(Es) || Es <- NewList, Es =/= bottom]; +inf_tuples_in_sets(L1, [?tuple(Elements2, _, ?any)], Opaques) -> + NewList = [t_inf_lists_strict(Elements1, Elements2, Opaques) + || ?tuple(Elements1, _, _) <- L1], + [t_tuple(Es) || Es <- NewList, Es =/= bottom]; +inf_tuples_in_sets(L1, L2, Opaques) -> + inf_tuples_in_sets2(L1, L2, [], Opaques). + +inf_tuples_in_sets2([?tuple(Elements1, Arity, Tag)|Ts1], + [?tuple(Elements2, Arity, Tag)|Ts2], Acc, Opaques) -> + case t_inf_lists_strict(Elements1, Elements2, Opaques) of + bottom -> inf_tuples_in_sets2(Ts1, Ts2, Acc, Opaques); + NewElements -> + inf_tuples_in_sets2(Ts1, Ts2, [?tuple(NewElements, Arity, Tag)|Acc], + Opaques) + end; +inf_tuples_in_sets2([?tuple(_, _, Tag1)|Ts1] = L1, + [?tuple(_, _, Tag2)|Ts2] = L2, Acc, Opaques) -> + if Tag1 < Tag2 -> inf_tuples_in_sets2(Ts1, L2, Acc, Opaques); + Tag1 > Tag2 -> inf_tuples_in_sets2(L1, Ts2, Acc, Opaques) + end; +inf_tuples_in_sets2([], _, Acc, _Opaques) -> lists:reverse(Acc); +inf_tuples_in_sets2(_, [], Acc, _Opaques) -> lists:reverse(Acc). + +inf_union(U1, U2, Opaques) -> + OpaqueFun = + fun(Union1, Union2, InfFun) -> + [_,_,_,_,_,_,_,_,Opaque,_] = Union1, + [A,B,F,I,L,N,T,M,_,Map] = Union2, + List = [A,B,F,I,L,N,T,M,Map], + inf_union_collect(List, Opaque, InfFun, [], []) + end, + {O1, ThrowList1} = + OpaqueFun(U1, U2, fun(E, Opaque) -> t_inf(Opaque, E, Opaques) end), + {O2, ThrowList2} + = OpaqueFun(U2, U1, fun(E, Opaque) -> t_inf(E, Opaque, Opaques) end), + {Union, ThrowList3} = inf_union(U1, U2, 0, [], [], Opaques), + ThrowList = lists:merge3(ThrowList1, ThrowList2, ThrowList3), + case t_sup([O1, O2, Union]) of + ?none when ThrowList =/= [] -> throw({pos, lists:usort(ThrowList)}); + Sup -> Sup + end. + +inf_union_collect([], _Opaque, _InfFun, InfList, ThrowList) -> + {t_sup(InfList), lists:usort(ThrowList)}; +inf_union_collect([?none|L], Opaque, InfFun, InfList, ThrowList) -> + inf_union_collect(L, Opaque, InfFun, [?none|InfList], ThrowList); +inf_union_collect([E|L], Opaque, InfFun, InfList, ThrowList) -> + try InfFun(E, Opaque)of + Inf -> + inf_union_collect(L, Opaque, InfFun, [Inf|InfList], ThrowList) + catch throw:{pos, Ns} -> + inf_union_collect(L, Opaque, InfFun, InfList, Ns ++ ThrowList) + end. + +inf_union([?none|Left1], [?none|Left2], N, Acc, ThrowList, Opaques) -> + inf_union(Left1, Left2, N, [?none|Acc], ThrowList, Opaques); +inf_union([T1|Left1], [T2|Left2], N, Acc, ThrowList, Opaques) -> + try t_inf(T1, T2, Opaques) of + ?none -> inf_union(Left1, Left2, N, [?none|Acc], ThrowList, Opaques); + T -> inf_union(Left1, Left2, N+1, [T|Acc], ThrowList, Opaques) + catch throw:{pos, Ns} -> + inf_union(Left1, Left2, N, [?none|Acc], Ns ++ ThrowList, Opaques) + end; +inf_union([], [], N, Acc, ThrowList, _Opaques) -> + if N =:= 0 -> {?none, ThrowList}; + N =:= 1 -> + [Type] = [T || T <- Acc, T =/= ?none], + {Type, ThrowList}; + N >= 2 -> {?union(lists:reverse(Acc)), ThrowList} + end. + +inf_bitstr(U1, B1, U2, B2) -> + GCD = gcd(U1, U2), + case (B2-B1) rem GCD of + 0 -> + U = (U1*U2) div GCD, + B = findfirst(0, 0, U1, B1, U2, B2), + t_bitstr(U, B); + _ -> + ?none + end. + +findfirst(N1, N2, U1, B1, U2, B2) -> + Val1 = U1*N1+B1, + Val2 = U2*N2+B2, + if Val1 =:= Val2 -> + Val1; + Val1 > Val2 -> + findfirst(N1, N2+1, U1, B1, U2, B2); + Val1 < Val2 -> + findfirst(N1+1, N2, U1, B1, U2, B2) + end. + +%%----------------------------------------------------------------------------- +%% Substitution of variables +%% + +-type subst_table() :: #{any() => erl_type()}. + +-spec t_subst(erl_type(), subst_table()) -> erl_type(). + +t_subst(T, Map) -> + case t_has_var(T) of + true -> t_subst_aux(T, Map); + false -> T + end. + +-spec subst_all_vars_to_any(erl_type()) -> erl_type(). + +subst_all_vars_to_any(T) -> + t_subst(T, #{}). + +t_subst_aux(?var(Id), Map) -> + case maps:find(Id, Map) of + error -> ?any; + {ok, Type} -> Type + end; +t_subst_aux(?list(Contents, Termination, Size), Map) -> + case t_subst_aux(Contents, Map) of + ?none -> ?none; + NewContents -> + %% Be careful here to make the termination collapse if necessary. + case t_subst_aux(Termination, Map) of + ?nil -> ?list(NewContents, ?nil, Size); + ?any -> ?list(NewContents, ?any, Size); + Other -> + ?list(NewContents2, NewTermination, _) = t_cons(NewContents, Other), + ?list(NewContents2, NewTermination, Size) + end + end; +t_subst_aux(?function(Domain, Range), Map) -> + ?function(t_subst_aux(Domain, Map), t_subst_aux(Range, Map)); +t_subst_aux(?product(Types), Map) -> + ?product([t_subst_aux(T, Map) || T <- Types]); +t_subst_aux(?tuple(?any, ?any, ?any) = T, _Map) -> + T; +t_subst_aux(?tuple(Elements, _Arity, _Tag), Map) -> + t_tuple([t_subst_aux(E, Map) || E <- Elements]); +t_subst_aux(?tuple_set(_) = TS, Map) -> + t_sup([t_subst_aux(T, Map) || T <- t_tuple_subtypes(TS)]); +t_subst_aux(?map(Pairs, DefK, DefV), Map) -> + t_map([{K, MNess, t_subst_aux(V, Map)} || {K, MNess, V} <- Pairs], + t_subst_aux(DefK, Map), t_subst_aux(DefV, Map)); +t_subst_aux(?opaque(Es), Map) -> + List = [Opaque#opaque{args = [t_subst_aux(Arg, Map) || Arg <- Args], + struct = t_subst_aux(S, Map)} || + Opaque = #opaque{args = Args, struct = S} <- set_to_list(Es)], + ?opaque(ordsets:from_list(List)); +t_subst_aux(?union(List), Map) -> + ?union([t_subst_aux(E, Map) || E <- List]); +t_subst_aux(T, _Map) -> + T. + +%%----------------------------------------------------------------------------- +%% Unification +%% + +-type t_unify_ret() :: {erl_type(), [{_, erl_type()}]}. + +-spec t_unify(erl_type(), erl_type()) -> t_unify_ret(). + +t_unify(T1, T2) -> + {T, VarMap} = t_unify(T1, T2, #{}), + {t_subst(T, VarMap), lists:keysort(1, maps:to_list(VarMap))}. + +t_unify(?var(Id) = T, ?var(Id), VarMap) -> + {T, VarMap}; +t_unify(?var(Id1) = T, ?var(Id2), VarMap) -> + case maps:find(Id1, VarMap) of + error -> + case maps:find(Id2, VarMap) of + error -> {T, VarMap#{Id2 => T}}; + {ok, Type} -> t_unify(T, Type, VarMap) + end; + {ok, Type1} -> + case maps:find(Id2, VarMap) of + error -> {Type1, VarMap#{Id2 => T}}; + {ok, Type2} -> t_unify(Type1, Type2, VarMap) + end + end; +t_unify(?var(Id), Type, VarMap) -> + case maps:find(Id, VarMap) of + error -> {Type, VarMap#{Id => Type}}; + {ok, VarType} -> t_unify(VarType, Type, VarMap) + end; +t_unify(Type, ?var(Id), VarMap) -> + case maps:find(Id, VarMap) of + error -> {Type, VarMap#{Id => Type}}; + {ok, VarType} -> t_unify(VarType, Type, VarMap) + end; +t_unify(?function(Domain1, Range1), ?function(Domain2, Range2), VarMap) -> + {Domain, VarMap1} = t_unify(Domain1, Domain2, VarMap), + {Range, VarMap2} = t_unify(Range1, Range2, VarMap1), + {?function(Domain, Range), VarMap2}; +t_unify(?list(Contents1, Termination1, Size), + ?list(Contents2, Termination2, Size), VarMap) -> + {Contents, VarMap1} = t_unify(Contents1, Contents2, VarMap), + {Termination, VarMap2} = t_unify(Termination1, Termination2, VarMap1), + {?list(Contents, Termination, Size), VarMap2}; +t_unify(?product(Types1), ?product(Types2), VarMap) -> + {Types, VarMap1} = unify_lists(Types1, Types2, VarMap), + {?product(Types), VarMap1}; +t_unify(?tuple(?any, ?any, ?any) = T, ?tuple(?any, ?any, ?any), VarMap) -> + {T, VarMap}; +t_unify(?tuple(Elements1, Arity, _), + ?tuple(Elements2, Arity, _), VarMap) when Arity =/= ?any -> + {NewElements, VarMap1} = unify_lists(Elements1, Elements2, VarMap), + {t_tuple(NewElements), VarMap1}; +t_unify(?tuple_set([{Arity, _}]) = T1, + ?tuple(_, Arity, _) = T2, VarMap) when Arity =/= ?any -> + unify_tuple_set_and_tuple1(T1, T2, VarMap); +t_unify(?tuple(_, Arity, _) = T1, + ?tuple_set([{Arity, _}]) = T2, VarMap) when Arity =/= ?any -> + unify_tuple_set_and_tuple2(T1, T2, VarMap); +t_unify(?tuple_set(List1) = T1, ?tuple_set(List2) = T2, VarMap) -> + try + unify_lists(lists:append([T || {_Arity, T} <- List1]), + lists:append([T || {_Arity, T} <- List2]), VarMap) + of + {Tuples, NewVarMap} -> {t_sup(Tuples), NewVarMap} + catch _:_ -> throw({mismatch, T1, T2}) + end; +t_unify(?map(_, ADefK, ADefV) = A, ?map(_, BDefK, BDefV) = B, VarMap0) -> + {DefK, VarMap1} = t_unify(ADefK, BDefK, VarMap0), + {DefV, VarMap2} = t_unify(ADefV, BDefV, VarMap1), + {Pairs, VarMap} = + map_pairwise_merge_foldr( + fun(K, MNess, V1, MNess, V2, {Pairs0, VarMap3}) -> + %% We know that the keys unify and do not contain variables, or they + %% would not be singletons + %% TODO: Should V=?none (known missing keys) be handled special? + {V, VarMap4} = t_unify(V1, V2, VarMap3), + {[{K,MNess,V}|Pairs0], VarMap4}; + (K, _, V1, _, V2, {Pairs0, VarMap3}) -> + %% One mandatory and one optional; what should be done in this case? + {V, VarMap4} = t_unify(V1, V2, VarMap3), + {[{K,?mand,V}|Pairs0], VarMap4} + end, {[], VarMap2}, A, B), + {t_map(Pairs, DefK, DefV), VarMap}; +t_unify(?opaque(_) = T1, ?opaque(_) = T2, VarMap) -> + t_unify(t_opaque_structure(T1), t_opaque_structure(T2), VarMap); +t_unify(T1, ?opaque(_) = T2, VarMap) -> + t_unify(T1, t_opaque_structure(T2), VarMap); +t_unify(?opaque(_) = T1, T2, VarMap) -> + t_unify(t_opaque_structure(T1), T2, VarMap); +t_unify(T, T, VarMap) -> + {T, VarMap}; +t_unify(?union(_)=T1, ?union(_)=T2, VarMap) -> + {Type1, Type2} = unify_union2(T1, T2), + t_unify(Type1, Type2, VarMap); +t_unify(?union(_)=T1, T2, VarMap) -> + t_unify(unify_union1(T1, T1, T2), T2, VarMap); +t_unify(T1, ?union(_)=T2, VarMap) -> + t_unify(T1, unify_union1(T2, T1, T2), VarMap); +t_unify(T1, T2, _) -> + throw({mismatch, T1, T2}). + +unify_union2(?union(List1)=T1, ?union(List2)=T2) -> + case {unify_union(List1), unify_union(List2)} of + {{yes, Type1}, {yes, Type2}} -> {Type1, Type2}; + {{yes, Type1}, no} -> {Type1, T2}; + {no, {yes, Type2}} -> {T1, Type2}; + {no, no} -> throw({mismatch, T1, T2}) + end. + +unify_union1(?union(List), T1, T2) -> + case unify_union(List) of + {yes, Type} -> Type; + no -> throw({mismatch, T1, T2}) + end. + +unify_union(List) -> + [A,B,F,I,L,N,T,M,O,Map] = List, + if O =:= ?none -> no; + true -> + S = t_opaque_structure(O), + {yes, t_sup([A,B,F,I,L,N,T,M,S,Map])} + end. + +-spec is_opaque_type(erl_type(), [erl_type()]) -> boolean(). + +%% An opaque type is a union of types. Returns true iff any of the type +%% names (Module and Name) of the first argument (the opaque type to +%% check) occurs in any of the opaque types of the second argument. +is_opaque_type(?opaque(Elements), Opaques) -> + lists:any(fun(Opaque) -> is_opaque_type2(Opaque, Opaques) end, Elements). + +is_opaque_type2(#opaque{mod = Mod1, name = Name1, args = Args1}, Opaques) -> + F1 = fun(?opaque(Es)) -> + F2 = fun(#opaque{mod = Mod, name = Name, args = Args}) -> + is_type_name(Mod1, Name1, Args1, Mod, Name, Args) + end, + lists:any(F2, Es) + end, + lists:any(F1, Opaques). + +is_type_name(Mod, Name, Args1, Mod, Name, Args2) -> + length(Args1) =:= length(Args2); +is_type_name(_Mod1, _Name1, _Args1, _Mod2, _Name2, _Args2) -> + false. + +%% Two functions since t_unify is not symmetric. +unify_tuple_set_and_tuple1(?tuple_set([{Arity, List}]), + ?tuple(Elements2, Arity, _), VarMap) -> + %% Can only work if the single tuple has variables at correct places. + %% Collapse the tuple set. + {NewElements, VarMap1} = + unify_lists(sup_tuple_elements(List), Elements2, VarMap), + {t_tuple(NewElements), VarMap1}. + +unify_tuple_set_and_tuple2(?tuple(Elements2, Arity, _), + ?tuple_set([{Arity, List}]), VarMap) -> + %% Can only work if the single tuple has variables at correct places. + %% Collapse the tuple set. + {NewElements, VarMap1} = + unify_lists(Elements2, sup_tuple_elements(List), VarMap), + {t_tuple(NewElements), VarMap1}. + +unify_lists(L1, L2, VarMap) -> + unify_lists(L1, L2, VarMap, []). + +unify_lists([T1|Left1], [T2|Left2], VarMap, Acc) -> + {NewT, NewVarMap} = t_unify(T1, T2, VarMap), + unify_lists(Left1, Left2, NewVarMap, [NewT|Acc]); +unify_lists([], [], VarMap, Acc) -> + {lists:reverse(Acc), VarMap}. + +%%t_assign_variables_to_subtype(T1, T2) -> +%% try +%% Dict = assign_vars(T1, T2, dict:new()), +%% {ok, dict:map(fun(_Param, List) -> t_sup(List) end, Dict)} +%% catch +%% throw:error -> error +%% end. + +%%assign_vars(_, ?var(_), _Dict) -> +%% erlang:error("Variable in right hand side of assignment"); +%%assign_vars(?any, _, Dict) -> +%% Dict; +%%assign_vars(?var(_) = Var, Type, Dict) -> +%% store_var(Var, Type, Dict); +%%assign_vars(?function(Domain1, Range1), ?function(Domain2, Range2), Dict) -> +%% DomainList = +%% case Domain2 of +%% ?any -> []; +%% ?product(List) -> List +%% end, +%% case any_none([Range2|DomainList]) of +%% true -> throw(error); +%% false -> +%% Dict1 = assign_vars(Domain1, Domain2, Dict), +%% assign_vars(Range1, Range2, Dict1) +%% end; +%%assign_vars(?list(_Contents, _Termination, ?any), ?nil, Dict) -> +%% Dict; +%%assign_vars(?list(Contents1, Termination1, Size1), +%% ?list(Contents2, Termination2, Size2), Dict) -> +%% Dict1 = assign_vars(Contents1, Contents2, Dict), +%% Dict2 = assign_vars(Termination1, Termination2, Dict1), +%% case {Size1, Size2} of +%% {S, S} -> Dict2; +%% {?any, ?nonempty_qual} -> Dict2; +%% {_, _} -> throw(error) +%% end; +%%assign_vars(?product(Types1), ?product(Types2), Dict) -> +%% case length(Types1) =:= length(Types2) of +%% true -> assign_vars_lists(Types1, Types2, Dict); +%% false -> throw(error) +%% end; +%%assign_vars(?tuple(?any, ?any, ?any), ?tuple(?any, ?any, ?any), Dict) -> +%% Dict; +%%assign_vars(?tuple(?any, ?any, ?any), ?tuple(_, _, _), Dict) -> +%% Dict; +%%assign_vars(?tuple(Elements1, Arity, _), +%% ?tuple(Elements2, Arity, _), Dict) when Arity =/= ?any -> +%% assign_vars_lists(Elements1, Elements2, Dict); +%%assign_vars(?tuple_set(_) = T, ?tuple_set(List2), Dict) -> +%% %% All Rhs tuples must already be subtypes of Lhs, so we can take +%% %% each one separatly. +%% assign_vars_lists([T || _ <- List2], List2, Dict); +%%assign_vars(?tuple(?any, ?any, ?any), ?tuple_set(_), Dict) -> +%% Dict; +%%assign_vars(?tuple(_, Arity, _) = T1, ?tuple_set(List), Dict) -> +%% case reduce_tuple_tags(List) of +%% [Tuple = ?tuple(_, Arity, _)] -> assign_vars(T1, Tuple, Dict); +%% _ -> throw(error) +%% end; +%%assign_vars(?tuple_set(List), ?tuple(_, Arity, Tag) = T2, Dict) -> +%% case [T || ?tuple(_, Arity1, Tag1) = T <- List, +%% Arity1 =:= Arity, Tag1 =:= Tag] of +%% [] -> throw(error); +%% [T1] -> assign_vars(T1, T2, Dict) +%% end; +%%assign_vars(?union(U1), T2, Dict) -> +%% ?union(U2) = force_union(T2), +%% assign_vars_lists(U1, U2, Dict); +%%assign_vars(T, T, Dict) -> +%% Dict; +%%assign_vars(T1, T2, Dict) -> +%% case t_is_subtype(T2, T1) of +%% false -> throw(error); +%% true -> Dict +%% end. + +%%assign_vars_lists([T1|Left1], [T2|Left2], Dict) -> +%% assign_vars_lists(Left1, Left2, assign_vars(T1, T2, Dict)); +%%assign_vars_lists([], [], Dict) -> +%% Dict. + +%%store_var(?var(Id), Type, Dict) -> +%% case dict:find(Id, Dict) of +%% error -> dict:store(Id, [Type], Dict); +%% {ok, _VarType0} -> dict:update(Id, fun(X) -> [Type|X] end, Dict) +%% end. + +%%----------------------------------------------------------------------------- +%% Subtraction. +%% +%% Note that the subtraction is an approximation since we do not have +%% negative types. Also, tuples and products should be handled using +%% the cartesian product of the elements, but this is not feasible to +%% do. +%% +%% Example: {a|b,c|d}\{a,d} = {a,c}|{a,d}|{b,c}|{b,d} \ {a,d} = +%% = {a,c}|{b,c}|{b,d} = {a|b,c|d} +%% +%% Instead, we can subtract if all elements but one becomes none after +%% subtracting element-wise. +%% +%% Example: {a|b,c|d}\{a|b,d} = {a,c}|{a,d}|{b,c}|{b,d} \ {a,d}|{b,d} = +%% = {a,c}|{b,c} = {a|b,c} + +-spec t_subtract_list(erl_type(), [erl_type()]) -> erl_type(). + +t_subtract_list(T1, [T2|Left]) -> + t_subtract_list(t_subtract(T1, T2), Left); +t_subtract_list(T, []) -> + T. + +-spec t_subtract(erl_type(), erl_type()) -> erl_type(). + +t_subtract(_, ?any) -> ?none; +t_subtract(T, ?var(_)) -> T; +t_subtract(?any, _) -> ?any; +t_subtract(?var(_) = T, _) -> T; +t_subtract(T, ?unit) -> T; +t_subtract(?unit, _) -> ?unit; +t_subtract(?none, _) -> ?none; +t_subtract(T, ?none) -> T; +t_subtract(?atom(Set1), ?atom(Set2)) -> + case set_subtract(Set1, Set2) of + ?none -> ?none; + Set -> ?atom(Set) + end; +t_subtract(?bitstr(U1, B1), ?bitstr(U2, B2)) -> + subtract_bin(t_bitstr(U1, B1), t_inf(t_bitstr(U1, B1), t_bitstr(U2, B2))); +t_subtract(?function(_, _) = T1, ?function(_, _) = T2) -> + case t_is_subtype(T1, T2) of + true -> ?none; + false -> T1 + end; +t_subtract(?identifier(Set1), ?identifier(Set2)) -> + case set_subtract(Set1, Set2) of + ?none -> ?none; + Set -> ?identifier(Set) + end; +t_subtract(?opaque(_)=T1, ?opaque(_)=T2) -> + opaque_subtract(T1, t_opaque_structure(T2)); +t_subtract(?opaque(_)=T1, T2) -> + opaque_subtract(T1, T2); +t_subtract(T1, ?opaque(_)=T2) -> + t_subtract(T1, t_opaque_structure(T2)); +t_subtract(?matchstate(Pres1, Slots1), ?matchstate(Pres2, _Slots2)) -> + Pres = t_subtract(Pres1, Pres2), + case t_is_none(Pres) of + true -> ?none; + false -> ?matchstate(Pres, Slots1) + end; +t_subtract(?matchstate(Present, Slots), _) -> + ?matchstate(Present, Slots); +t_subtract(?nil, ?nil) -> + ?none; +t_subtract(?nil, ?nonempty_list(_, _)) -> + ?nil; +t_subtract(?nil, ?list(_, _, _)) -> + ?none; +t_subtract(?list(Contents, Termination, _Size) = T, ?nil) -> + case Termination =:= ?nil of + true -> ?nonempty_list(Contents, Termination); + false -> T + end; +t_subtract(?list(Contents1, Termination1, Size1) = T, + ?list(Contents2, Termination2, Size2)) -> + case t_is_subtype(Contents1, Contents2) of + true -> + case t_is_subtype(Termination1, Termination2) of + true -> + case {Size1, Size2} of + {?nonempty_qual, ?unknown_qual} -> ?none; + {?unknown_qual, ?nonempty_qual} -> ?nil; + {S, S} -> ?none + end; + false -> + %% If the termination is not covered by the subtracted type + %% we cannot really say anything about the result. + T + end; + false -> + %% All contents must be covered if there is going to be any + %% change to the list. + T + end; +t_subtract(?float, ?float) -> ?none; +t_subtract(?number(_, _) = T1, ?float) -> t_inf(T1, t_integer()); +t_subtract(?float, ?number(_Set, Tag)) -> + case Tag of + ?unknown_qual -> ?none; + _ -> ?float + end; +t_subtract(?number(_, _), ?number(?any, ?unknown_qual)) -> ?none; +t_subtract(?number(_, _) = T1, ?integer(?any)) -> t_inf(?float, T1); +t_subtract(?int_set(Set1), ?int_set(Set2)) -> + case set_subtract(Set1, Set2) of + ?none -> ?none; + Set -> ?int_set(Set) + end; +t_subtract(?int_range(From1, To1) = T1, ?int_range(_, _) = T2) -> + case t_inf(T1, T2) of + ?none -> T1; + ?int_range(From1, To1) -> ?none; + ?int_range(neg_inf, To) -> t_from_range(To + 1, To1); + ?int_range(From, pos_inf) -> t_from_range(From1, From - 1); + ?int_range(From, To) -> t_sup(t_from_range(From1, From - 1), + t_from_range(To + 1, To)) + end; +t_subtract(?int_range(From, To) = T1, ?int_set(Set)) -> + NewFrom = case set_is_element(From, Set) of + true -> From + 1; + false -> From + end, + NewTo = case set_is_element(To, Set) of + true -> To - 1; + false -> To + end, + if (NewFrom =:= From) and (NewTo =:= To) -> T1; + true -> t_from_range(NewFrom, NewTo) + end; +t_subtract(?int_set(Set), ?int_range(From, To)) -> + case set_filter(fun(X) -> not ((X =< From) orelse (X >= To)) end, Set) of + ?none -> ?none; + NewSet -> ?int_set(NewSet) + end; +t_subtract(?integer(?any) = T1, ?integer(_)) -> T1; +t_subtract(?number(_, _) = T1, ?number(_, _)) -> T1; +t_subtract(?tuple(_, _, _), ?tuple(?any, ?any, ?any)) -> ?none; +t_subtract(?tuple_set(_), ?tuple(?any, ?any, ?any)) -> ?none; +t_subtract(?tuple(?any, ?any, ?any) = T1, ?tuple_set(_)) -> T1; +t_subtract(?tuple(Elements1, Arity1, _Tag1) = T1, + ?tuple(Elements2, Arity2, _Tag2)) -> + if Arity1 =/= Arity2 -> T1; + Arity1 =:= Arity2 -> + NewElements = t_subtract_lists(Elements1, Elements2), + case [E || E <- NewElements, E =/= ?none] of + [] -> ?none; + [_] -> t_tuple(replace_nontrivial_element(Elements1, NewElements)); + _ -> T1 + end + end; +t_subtract(?tuple_set(List1) = T1, ?tuple(_, Arity, _) = T2) -> + case orddict:find(Arity, List1) of + error -> T1; + {ok, List2} -> + TuplesLeft0 = [Tuple || {_Arity, Tuple} <- orddict:erase(Arity, List1)], + TuplesLeft1 = lists:append(TuplesLeft0), + t_sup([t_subtract(L, T2) || L <- List2] ++ TuplesLeft1) + end; +t_subtract(?tuple(_, Arity, _) = T1, ?tuple_set(List1)) -> + case orddict:find(Arity, List1) of + error -> T1; + {ok, List2} -> t_inf([t_subtract(T1, L) || L <- List2]) + end; +t_subtract(?tuple_set(_) = T1, ?tuple_set(_) = T2) -> + t_sup([t_subtract(T, T2) || T <- t_tuple_subtypes(T1)]); +t_subtract(?product(Elements1) = T1, ?product(Elements2)) -> + Arity1 = length(Elements1), + Arity2 = length(Elements2), + if Arity1 =/= Arity2 -> T1; + Arity1 =:= Arity2 -> + NewElements = t_subtract_lists(Elements1, Elements2), + case [E || E <- NewElements, E =/= ?none] of + [] -> ?none; + [_] -> t_product(replace_nontrivial_element(Elements1, NewElements)); + _ -> T1 + end + end; +t_subtract(?map(APairs, ADefK, ADefV) = A, ?map(_, BDefK, BDefV) = B) -> + case t_is_subtype(ADefK, BDefK) andalso t_is_subtype(ADefV, BDefV) of + false -> A; + true -> + %% We fold over the maps to produce a list of constraints, where + %% constraints are additional key-value pairs to put in Pairs. Only one + %% constraint need to be applied to produce a type that excludes the + %% right-hand-side type, so if more than one constraint is produced, we + %% just return the left-hand-side argument. + %% + %% Each case of the fold may either conclude that + %% * The arguments constrain A at least as much as B, i.e. that A so far + %% is a subtype of B. In that case they return false + %% * That for the particular arguments, A being a subtype of B does not + %% hold, but the infinimum of A and B is nonempty, and by narrowing a + %% pair in A, we can create a type that excludes some elements in the + %% infinumum. In that case, they will return that pair. + %% * That for the particular arguments, A being a subtype of B does not + %% hold, and either the infinumum of A and B is empty, or it is not + %% possible with the current representation to create a type that + %% excludes elements from B without also excluding elements that are + %% only in A. In that case, it will return the pair from A unchanged. + case + map_pairwise_merge( + %% If V1 is a subtype of V2, the case that K does not exist in A + %% remain. + fun(K, ?opt, V1, ?mand, V2) -> {K, ?opt, t_subtract(V1, V2)}; + (K, _, V1, _, V2) -> + %% If we subtract an optional key, that leaves a mandatory key + case t_subtract(V1, V2) of + ?none -> false; + Partial -> {K, ?mand, Partial} + end + end, A, B) + of + %% We produce a list of keys that are constrained. As only one of + %% these should apply at a time, we can't represent the difference if + %% more than one constraint is produced. If we applied all of them, + %% that would make an underapproximation, which we must not do. + [] -> ?none; %% A is a subtype of B + [E] -> t_map(mapdict_store(E, APairs), ADefK, ADefV); + _ -> A + end + end; +t_subtract(?product(P1), _) -> + ?product(P1); +t_subtract(T, ?product(_)) -> + T; +t_subtract(?union(U1), ?union(U2)) -> + subtract_union(U1, U2); +t_subtract(T1, T2) -> + ?union(U1) = force_union(T1), + ?union(U2) = force_union(T2), + subtract_union(U1, U2). + +-spec opaque_subtract(erl_type(), erl_type()) -> erl_type(). + +opaque_subtract(?opaque(Set1), T2) -> + List = [T1#opaque{struct = Sub} || + #opaque{struct = S1}=T1 <- set_to_list(Set1), + not t_is_none(Sub = t_subtract(S1, T2))], + case List of + [] -> ?none; + _ -> ?opaque(ordsets:from_list(List)) + end. + +-spec t_subtract_lists([erl_type()], [erl_type()]) -> [erl_type()]. + +t_subtract_lists(L1, L2) -> + t_subtract_lists(L1, L2, []). + +-spec t_subtract_lists([erl_type()], [erl_type()], [erl_type()]) -> [erl_type()]. + +t_subtract_lists([T1|Left1], [T2|Left2], Acc) -> + t_subtract_lists(Left1, Left2, [t_subtract(T1, T2)|Acc]); +t_subtract_lists([], [], Acc) -> + lists:reverse(Acc). + +-spec subtract_union([erl_type(),...], [erl_type(),...]) -> erl_type(). + +subtract_union(U1, U2) -> + [A1,B1,F1,I1,L1,N1,T1,M1,O1,Map1] = U1, + [A2,B2,F2,I2,L2,N2,T2,M2,O2,Map2] = U2, + List1 = [A1,B1,F1,I1,L1,N1,T1,M1,?none,Map1], + List2 = [A2,B2,F2,I2,L2,N2,T2,M2,?none,Map2], + Sub1 = subtract_union(List1, List2, 0, []), + O = if O1 =:= ?none -> O1; + true -> t_subtract(O1, ?union(U2)) + end, + Sub2 = if O2 =:= ?none -> Sub1; + true -> t_subtract(Sub1, t_opaque_structure(O2)) + end, + t_sup(O, Sub2). + +-spec subtract_union([erl_type()], [erl_type()], non_neg_integer(), [erl_type()]) -> erl_type(). + +subtract_union([T1|Left1], [T2|Left2], N, Acc) -> + case t_subtract(T1, T2) of + ?none -> subtract_union(Left1, Left2, N, [?none|Acc]); + T -> subtract_union(Left1, Left2, N+1, [T|Acc]) + end; +subtract_union([], [], 0, _Acc) -> + ?none; +subtract_union([], [], 1, Acc) -> + [T] = [X || X <- Acc, X =/= ?none], + T; +subtract_union([], [], N, Acc) when is_integer(N), N > 1 -> + ?union(lists:reverse(Acc)). + +replace_nontrivial_element(El1, El2) -> + replace_nontrivial_element(El1, El2, []). + +replace_nontrivial_element([T1|Left1], [?none|Left2], Acc) -> + replace_nontrivial_element(Left1, Left2, [T1|Acc]); +replace_nontrivial_element([_|Left1], [T2|_], Acc) -> + lists:reverse(Acc) ++ [T2|Left1]. + +subtract_bin(?bitstr(U1, B1), ?bitstr(U1, B1)) -> + ?none; +subtract_bin(?bitstr(U1, B1), ?none) -> + t_bitstr(U1, B1); +subtract_bin(?bitstr(U1, B1), ?bitstr(0, B1)) -> + t_bitstr(U1, B1+U1); +subtract_bin(?bitstr(U1, B1), ?bitstr(U1, B2)) -> + if (B1+U1) =/= B2 -> t_bitstr(0, B1); + true -> t_bitstr(U1, B1) + end; +subtract_bin(?bitstr(U1, B1), ?bitstr(U2, B2)) -> + if (2 * U1) =:= U2 -> + if B1 =:= B2 -> + t_bitstr(U2, B1+U1); + (B1 + U1) =:= B2 -> + t_bitstr(U2, B1); + true -> + t_bitstr(U1, B1) + end; + true -> + t_bitstr(U1, B1) + end. + +%%----------------------------------------------------------------------------- +%% Relations +%% + +-spec t_is_equal(erl_type(), erl_type()) -> boolean(). + +t_is_equal(T, T) -> true; +t_is_equal(_, _) -> false. + +-spec t_is_subtype(erl_type(), erl_type()) -> boolean(). + +t_is_subtype(T1, T2) -> + Inf = t_inf(T1, T2), + subtype_is_equal(T1, Inf). + +%% The subtype relation has to behave correctly irrespective of opaque +%% types. +subtype_is_equal(T, T) -> true; +subtype_is_equal(T1, T2) -> + t_is_equal(case t_contains_opaque(T1) of + true -> t_unopaque(T1); + false -> T1 + end, + case t_contains_opaque(T2) of + true -> t_unopaque(T2); + false -> T2 + end). + +-spec t_is_instance(erl_type(), erl_type()) -> boolean(). + +%% XXX. To be removed. +t_is_instance(ConcreteType, Type) -> + t_is_subtype(ConcreteType, t_unopaque(Type)). + +-spec t_do_overlap(erl_type(), erl_type()) -> boolean(). + +t_do_overlap(TypeA, TypeB) -> + not (t_is_none_or_unit(t_inf(TypeA, TypeB))). + +-spec t_unopaque(erl_type()) -> erl_type(). + +t_unopaque(T) -> + t_unopaque(T, 'universe'). + +-spec t_unopaque(erl_type(), opaques()) -> erl_type(). + +t_unopaque(?opaque(_) = T, Opaques) -> + case Opaques =:= 'universe' orelse is_opaque_type(T, Opaques) of + true -> t_unopaque(t_opaque_structure(T), Opaques); + false -> T + end; +t_unopaque(?list(ElemT, Termination, Sz), Opaques) -> + ?list(t_unopaque(ElemT, Opaques), t_unopaque(Termination, Opaques), Sz); +t_unopaque(?tuple(?any, _, _) = T, _) -> T; +t_unopaque(?tuple(ArgTs, Sz, Tag), Opaques) when is_list(ArgTs) -> + NewArgTs = [t_unopaque(A, Opaques) || A <- ArgTs], + ?tuple(NewArgTs, Sz, Tag); +t_unopaque(?tuple_set(Set), Opaques) -> + NewSet = [{Sz, [t_unopaque(T, Opaques) || T <- Tuples]} + || {Sz, Tuples} <- Set], + ?tuple_set(NewSet); +t_unopaque(?product(Types), Opaques) -> + ?product([t_unopaque(T, Opaques) || T <- Types]); +t_unopaque(?function(Domain, Range), Opaques) -> + ?function(t_unopaque(Domain, Opaques), t_unopaque(Range, Opaques)); +t_unopaque(?union([A,B,F,I,L,N,T,M,O,Map]), Opaques) -> + UL = t_unopaque(L, Opaques), + UT = t_unopaque(T, Opaques), + UF = t_unopaque(F, Opaques), + UM = t_unopaque(M, Opaques), + UMap = t_unopaque(Map, Opaques), + {OF,UO} = case t_unopaque(O, Opaques) of + ?opaque(_) = O1 -> {O1, []}; + Type -> {?none, [Type]} + end, + t_sup([?union([A,B,UF,I,UL,N,UT,UM,OF,UMap])|UO]); +t_unopaque(?map(Pairs,DefK,DefV), Opaques) -> + t_map([{K, MNess, t_unopaque(V, Opaques)} || {K, MNess, V} <- Pairs], + t_unopaque(DefK, Opaques), + t_unopaque(DefV, Opaques)); +t_unopaque(T, _) -> + T. + +%%----------------------------------------------------------------------------- +%% K-depth abstraction. +%% +%% t_limit/2 is the exported function, which checks the type of the +%% second argument and calls the module local t_limit_k/2 function. +%% + +-spec t_limit(erl_type(), integer()) -> erl_type(). + +t_limit(Term, K) when is_integer(K) -> + t_limit_k(Term, K). + +t_limit_k(_, K) when K =< 0 -> ?any; +t_limit_k(?tuple(?any, ?any, ?any) = T, _K) -> T; +t_limit_k(?tuple(Elements, Arity, _), K) -> + if K =:= 1 -> t_tuple(Arity); + true -> t_tuple([t_limit_k(E, K-1) || E <- Elements]) + end; +t_limit_k(?tuple_set(_) = T, K) -> + t_sup([t_limit_k(Tuple, K) || Tuple <- t_tuple_subtypes(T)]); +t_limit_k(?list(Elements, Termination, Size), K) -> + NewTermination = + if K =:= 1 -> + %% We do not want to lose the termination information. + t_limit_k(Termination, K); + true -> t_limit_k(Termination, K - 1) + end, + NewElements = t_limit_k(Elements, K - 1), + TmpList = t_cons(NewElements, NewTermination), + case Size of + ?nonempty_qual -> TmpList; + ?unknown_qual -> + ?list(NewElements1, NewTermination1, _) = TmpList, + ?list(NewElements1, NewTermination1, ?unknown_qual) + end; +t_limit_k(?function(Domain, Range), K) -> + %% The domain is either a product or any() so we do not decrease the K. + ?function(t_limit_k(Domain, K), t_limit_k(Range, K-1)); +t_limit_k(?product(Elements), K) -> + ?product([t_limit_k(X, K - 1) || X <- Elements]); +t_limit_k(?union(Elements), K) -> + ?union([t_limit_k(X, K) || X <- Elements]); +t_limit_k(?opaque(Es), K) -> + List = [begin + NewS = t_limit_k(S, K), + Opaque#opaque{struct = NewS} + end || #opaque{struct = S} = Opaque <- set_to_list(Es)], + ?opaque(ordsets:from_list(List)); +t_limit_k(?map(Pairs0, DefK0, DefV0), K) -> + Fun = fun({EK, MNess, EV}, {Exact, DefK1, DefV1}) -> + LV = t_limit_k(EV, K - 1), + case t_limit_k(EK, K - 1) of + EK -> {[{EK,MNess,LV}|Exact], DefK1, DefV1}; + LK -> {Exact, t_sup(LK, DefK1), t_sup(LV, DefV1)} + end + end, + {Pairs, DefK2, DefV2} = lists:foldr(Fun, {[], DefK0, DefV0}, Pairs0), + t_map(Pairs, t_limit_k(DefK2, K - 1), t_limit_k(DefV2, K - 1)); +t_limit_k(T, _K) -> T. + +%%============================================================================ +%% +%% Abstract records. Used for comparing contracts. +%% +%%============================================================================ + +-spec t_abstract_records(erl_type(), type_table()) -> erl_type(). + +t_abstract_records(?list(Contents, Termination, Size), RecDict) -> + case t_abstract_records(Contents, RecDict) of + ?none -> ?none; + NewContents -> + %% Be careful here to make the termination collapse if necessary. + case t_abstract_records(Termination, RecDict) of + ?nil -> ?list(NewContents, ?nil, Size); + ?any -> ?list(NewContents, ?any, Size); + Other -> + ?list(NewContents2, NewTermination, _) = t_cons(NewContents, Other), + ?list(NewContents2, NewTermination, Size) + end + end; +t_abstract_records(?function(Domain, Range), RecDict) -> + ?function(t_abstract_records(Domain, RecDict), + t_abstract_records(Range, RecDict)); +t_abstract_records(?product(Types), RecDict) -> + ?product([t_abstract_records(T, RecDict) || T <- Types]); +t_abstract_records(?union(Types), RecDict) -> + t_sup([t_abstract_records(T, RecDict) || T <- Types]); +t_abstract_records(?tuple(?any, ?any, ?any) = T, _RecDict) -> + T; +t_abstract_records(?tuple(Elements, Arity, ?atom(_) = Tag), RecDict) -> + [TagAtom] = atom_vals(Tag), + case lookup_record(TagAtom, Arity - 1, RecDict) of + error -> t_tuple([t_abstract_records(E, RecDict) || E <- Elements]); + {ok, Fields} -> t_tuple([Tag|[T || {_Name, _Abstr, T} <- Fields]]) + end; +t_abstract_records(?tuple(Elements, _Arity, _Tag), RecDict) -> + t_tuple([t_abstract_records(E, RecDict) || E <- Elements]); +t_abstract_records(?tuple_set(_) = Tuples, RecDict) -> + t_sup([t_abstract_records(T, RecDict) || T <- t_tuple_subtypes(Tuples)]); +t_abstract_records(?opaque(_)=Type, RecDict) -> + t_abstract_records(t_opaque_structure(Type), RecDict); +t_abstract_records(T, _RecDict) -> + T. + +%% Map over types. Depth first. Used by the contract checker. ?list is +%% not fully implemented so take care when changing the type in Termination. + +-spec t_map(fun((erl_type()) -> erl_type()), erl_type()) -> erl_type(). + +t_map(Fun, ?list(Contents, Termination, Size)) -> + Fun(?list(t_map(Fun, Contents), t_map(Fun, Termination), Size)); +t_map(Fun, ?function(Domain, Range)) -> + Fun(?function(t_map(Fun, Domain), t_map(Fun, Range))); +t_map(Fun, ?product(Types)) -> + Fun(?product([t_map(Fun, T) || T <- Types])); +t_map(Fun, ?union(Types)) -> + Fun(t_sup([t_map(Fun, T) || T <- Types])); +t_map(Fun, ?tuple(?any, ?any, ?any) = T) -> + Fun(T); +t_map(Fun, ?tuple(Elements, _Arity, _Tag)) -> + Fun(t_tuple([t_map(Fun, E) || E <- Elements])); +t_map(Fun, ?tuple_set(_) = Tuples) -> + Fun(t_sup([t_map(Fun, T) || T <- t_tuple_subtypes(Tuples)])); +t_map(Fun, ?opaque(Set)) -> + L = [Opaque#opaque{struct = NewS} || + #opaque{struct = S} = Opaque <- set_to_list(Set), + not t_is_none(NewS = t_map(Fun, S))], + Fun(case L of + [] -> ?none; + _ -> ?opaque(ordsets:from_list(L)) + end); +t_map(Fun, ?map(Pairs,DefK,DefV)) -> + %% TODO: + Fun(t_map(Pairs, Fun(DefK), Fun(DefV))); +t_map(Fun, T) -> + Fun(T). + +%%============================================================================= +%% +%% Prettyprinter +%% +%%============================================================================= + +-spec t_to_string(erl_type()) -> string(). + +t_to_string(T) -> + t_to_string(T, dict:new()). + +-spec t_to_string(erl_type(), type_table()) -> string(). + +t_to_string(?any, _RecDict) -> + "any()"; +t_to_string(?none, _RecDict) -> + "none()"; +t_to_string(?unit, _RecDict) -> + "no_return()"; +t_to_string(?atom(?any), _RecDict) -> + "atom()"; +t_to_string(?atom(Set), _RecDict) -> + case set_size(Set) of + 2 -> + case set_is_element(true, Set) andalso set_is_element(false, Set) of + true -> "boolean()"; + false -> set_to_string(Set) + end; + _ -> + set_to_string(Set) + end; +t_to_string(?bitstr(0, 0), _RecDict) -> + "<<>>"; +t_to_string(?bitstr(8, 0), _RecDict) -> + "binary()"; +t_to_string(?bitstr(1, 0), _RecDict) -> + "bitstring()"; +t_to_string(?bitstr(0, B), _RecDict) -> + flat_format("<<_:~w>>", [B]); +t_to_string(?bitstr(U, 0), _RecDict) -> + flat_format("<<_:_*~w>>", [U]); +t_to_string(?bitstr(U, B), _RecDict) -> + flat_format("<<_:~w,_:_*~w>>", [B, U]); +t_to_string(?function(?any, ?any), _RecDict) -> + "fun()"; +t_to_string(?function(?any, Range), RecDict) -> + "fun((...) -> " ++ t_to_string(Range, RecDict) ++ ")"; +t_to_string(?function(?product(ArgList), Range), RecDict) -> + "fun((" ++ comma_sequence(ArgList, RecDict) ++ ") -> " + ++ t_to_string(Range, RecDict) ++ ")"; +t_to_string(?identifier(Set), _RecDict) -> + case Set of + ?any -> "identifier()"; + _ -> + string:join([flat_format("~w()", [T]) || T <- set_to_list(Set)], " | ") + end; +t_to_string(?opaque(Set), RecDict) -> + string:join([opaque_type(Mod, Name, Args, S, RecDict) || + #opaque{mod = Mod, name = Name, struct = S, args = Args} + <- set_to_list(Set)], + " | "); +t_to_string(?matchstate(Pres, Slots), RecDict) -> + flat_format("ms(~s,~s)", [t_to_string(Pres, RecDict), + t_to_string(Slots,RecDict)]); +t_to_string(?nil, _RecDict) -> + "[]"; +t_to_string(?nonempty_list(Contents, Termination), RecDict) -> + ContentString = t_to_string(Contents, RecDict), + case Termination of + ?nil -> + case Contents of + ?char -> "nonempty_string()"; + _ -> "["++ContentString++",...]" + end; + ?any -> + %% Just a safety check. + case Contents =:= ?any of + true -> ok; + false -> + %% XXX. See comment below. + %% erlang:error({illegal_list, ?nonempty_list(Contents, Termination)}) + ok + end, + "nonempty_maybe_improper_list()"; + _ -> + case t_is_subtype(t_nil(), Termination) of + true -> + "nonempty_maybe_improper_list("++ContentString++"," + ++t_to_string(Termination, RecDict)++")"; + false -> + "nonempty_improper_list("++ContentString++"," + ++t_to_string(Termination, RecDict)++")" + end + end; +t_to_string(?list(Contents, Termination, ?unknown_qual), RecDict) -> + ContentString = t_to_string(Contents, RecDict), + case Termination of + ?nil -> + case Contents of + ?char -> "string()"; + _ -> "["++ContentString++"]" + end; + ?any -> + %% Just a safety check. + %% XXX. Types such as "maybe_improper_list(integer(), any())" + %% are OK, but cannot be printed!? + case Contents =:= ?any of + true -> ok; + false -> + ok + %% L = ?list(Contents, Termination, ?unknown_qual), + %% erlang:error({illegal_list, L}) + end, + "maybe_improper_list()"; + _ -> + case t_is_subtype(t_nil(), Termination) of + true -> + "maybe_improper_list("++ContentString++"," + ++t_to_string(Termination, RecDict)++")"; + false -> + "improper_list("++ContentString++"," + ++t_to_string(Termination, RecDict)++")" + end + end; +t_to_string(?int_set(Set), _RecDict) -> + set_to_string(Set); +t_to_string(?byte, _RecDict) -> "byte()"; +t_to_string(?char, _RecDict) -> "char()"; +t_to_string(?integer_pos, _RecDict) -> "pos_integer()"; +t_to_string(?integer_non_neg, _RecDict) -> "non_neg_integer()"; +t_to_string(?integer_neg, _RecDict) -> "neg_integer()"; +t_to_string(?int_range(From, To), _RecDict) -> + flat_format("~w..~w", [From, To]); +t_to_string(?integer(?any), _RecDict) -> "integer()"; +t_to_string(?float, _RecDict) -> "float()"; +t_to_string(?number(?any, ?unknown_qual), _RecDict) -> "number()"; +t_to_string(?product(List), RecDict) -> + "<" ++ comma_sequence(List, RecDict) ++ ">"; +t_to_string(?map([],?any,?any), _RecDict) -> "map()"; +t_to_string(?map(Pairs0,DefK,DefV), RecDict) -> + {Pairs, ExtraEl} = + case {DefK, DefV} of + {?none, ?none} -> {Pairs0, []}; + _ -> {Pairs0 ++ [{DefK,?opt,DefV}], []} + end, + Tos = fun(T) -> case T of + ?any -> "_"; + _ -> t_to_string(T, RecDict) + end end, + StrMand = [{Tos(K),Tos(V)}||{K,?mand,V}<-Pairs], + StrOpt = [{Tos(K),Tos(V)}||{K,?opt,V}<-Pairs], + "#{" ++ string:join([K ++ ":=" ++ V||{K,V}<-StrMand] + ++ [K ++ "=>" ++ V||{K,V}<-StrOpt] + ++ ExtraEl, ", ") ++ "}"; +t_to_string(?tuple(?any, ?any, ?any), _RecDict) -> "tuple()"; +t_to_string(?tuple(Elements, _Arity, ?any), RecDict) -> + "{" ++ comma_sequence(Elements, RecDict) ++ "}"; +t_to_string(?tuple(Elements, Arity, Tag), RecDict) -> + [TagAtom] = atom_vals(Tag), + case lookup_record(TagAtom, Arity-1, RecDict) of + error -> "{" ++ comma_sequence(Elements, RecDict) ++ "}"; + {ok, FieldNames} -> + record_to_string(TagAtom, Elements, FieldNames, RecDict) + end; +t_to_string(?tuple_set(_) = T, RecDict) -> + union_sequence(t_tuple_subtypes(T), RecDict); +t_to_string(?union(Types), RecDict) -> + union_sequence([T || T <- Types, T =/= ?none], RecDict); +t_to_string(?var(Id), _RecDict) when is_atom(Id) -> + flat_format("~s", [atom_to_list(Id)]); +t_to_string(?var(Id), _RecDict) when is_integer(Id) -> + flat_format("var(~w)", [Id]). + + +record_to_string(Tag, [_|Fields], FieldNames, RecDict) -> + FieldStrings = record_fields_to_string(Fields, FieldNames, RecDict, []), + "#" ++ atom_to_string(Tag) ++ "{" ++ string:join(FieldStrings, ",") ++ "}". + +record_fields_to_string([F|Fs], [{FName, _Abstr, DefType}|FDefs], + RecDict, Acc) -> + NewAcc = + case + t_is_equal(F, t_any()) orelse + (t_is_any_atom('undefined', F) andalso + not t_is_none(t_inf(F, DefType))) + of + true -> Acc; + false -> + StrFV = atom_to_string(FName) ++ "::" ++ t_to_string(F, RecDict), + [StrFV|Acc] + end, + record_fields_to_string(Fs, FDefs, RecDict, NewAcc); +record_fields_to_string([], [], _RecDict, Acc) -> + lists:reverse(Acc). + +-spec record_field_diffs_to_string(erl_type(), type_table()) -> string(). + +record_field_diffs_to_string(?tuple([_|Fs], Arity, Tag), RecDict) -> + [TagAtom] = atom_vals(Tag), + {ok, FieldNames} = lookup_record(TagAtom, Arity-1, RecDict), + %% io:format("RecCElems = ~p\nRecTypes = ~p\n", [Fs, FieldNames]), + FieldDiffs = field_diffs(Fs, FieldNames, RecDict, []), + string:join(FieldDiffs, " and "). + +field_diffs([F|Fs], [{FName, _Abstr, DefType}|FDefs], RecDict, Acc) -> + %% Don't care about opaqueness for now. + NewAcc = + case not t_is_none(t_inf(F, DefType)) of + true -> Acc; + false -> + Str = atom_to_string(FName) ++ "::" ++ t_to_string(DefType, RecDict), + [Str|Acc] + end, + field_diffs(Fs, FDefs, RecDict, NewAcc); +field_diffs([], [], _, Acc) -> + lists:reverse(Acc). + +comma_sequence(Types, RecDict) -> + List = [case T =:= ?any of + true -> "_"; + false -> t_to_string(T, RecDict) + end || T <- Types], + string:join(List, ","). + +union_sequence(Types, RecDict) -> + List = [t_to_string(T, RecDict) || T <- Types], + string:join(List, " | "). + +-ifdef(DEBUG). +opaque_type(Mod, Name, _Args, S, RecDict) -> + ArgsString = comma_sequence(_Args, RecDict), + String = t_to_string(S, RecDict), + opaque_name(Mod, Name, ArgsString) ++ "[" ++ String ++ "]". +-else. +opaque_type(Mod, Name, Args, _S, RecDict) -> + ArgsString = comma_sequence(Args, RecDict), + opaque_name(Mod, Name, ArgsString). +-endif. + +opaque_name(Mod, Name, Extra) -> + S = mod_name(Mod, Name), + flat_format("~s(~s)", [S, Extra]). + +mod_name(Mod, Name) -> + flat_format("~w:~w", [Mod, Name]). + +%%============================================================================= +%% +%% Build a type from parse forms. +%% +%%============================================================================= + +-type type_names() :: [type_key() | record_key()]. + +-type mta() :: {module(), atom(), arity()}. +-type mra() :: {module(), atom(), arity()}. +-type site() :: {'type', mta()} | {'spec', mfa()} | {'record', mra()}. +-type cache_key() :: {module(), atom(), expand_depth(), + [erl_type()], type_names()}. +-opaque cache() :: #{cache_key() => {erl_type(), expand_limit()}}. + +-spec t_from_form(parse_form(), sets:set(mfa()), site(), mod_records(), + var_table(), cache()) -> {erl_type(), cache()}. + +t_from_form(Form, ExpTypes, Site, RecDict, VarTab, Cache) -> + t_from_form1(Form, ExpTypes, Site, RecDict, VarTab, Cache). + +%% Replace external types with with none(). +-spec t_from_form_without_remote(parse_form(), site(), type_table()) -> + {erl_type(), cache()}. + +t_from_form_without_remote(Form, Site, TypeTable) -> + Module = site_module(Site), + RecDict = dict:from_list([{Module, TypeTable}]), + ExpTypes = replace_by_none, + VarTab = var_table__new(), + Cache = cache__new(), + t_from_form1(Form, ExpTypes, Site, RecDict, VarTab, Cache). + +%% REC_TYPE_LIMIT is used for limiting the depth of recursive types. +%% EXPAND_LIMIT is used for limiting the size of types by +%% limiting the number of elements of lists within one type form. +%% EXPAND_DEPTH is used in conjunction with EXPAND_LIMIT to make the +%% types balanced (unions will otherwise collapse to any()) by limiting +%% the depth the same way as t_limit/2 does. + +-type expand_limit() :: integer(). + +-type expand_depth() :: integer(). + +-record(from_form, {site :: site(), + xtypes :: sets:set(mfa()) | 'replace_by_none', + mrecs :: mod_records(), + vtab :: var_table(), + tnames :: type_names()}). + +-spec t_from_form1(parse_form(), sets:set(mfa()) | 'replace_by_none', + site(), mod_records(), var_table(), cache()) -> + {erl_type(), cache()}. + +t_from_form1(Form, ET, Site, MR, V, C) -> + TypeNames = initial_typenames(Site), + State = #from_form{site = Site, + xtypes = ET, + mrecs = MR, + vtab = V, + tnames = TypeNames}, + L = ?EXPAND_LIMIT, + {T1, L1, C1} = from_form(Form, State, ?EXPAND_DEPTH, L, C), + if + L1 =< 0 -> + from_form_loop(Form, State, 1, L, C1); + true -> + {T1, C1} + end. + +initial_typenames({type, _MTA}=Site) -> [Site]; +initial_typenames({spec, _MFA}) -> []; +initial_typenames({record, _MRA}) -> []. + +from_form_loop(Form, State, D, Limit, C) -> + {T1, L1, C1} = from_form(Form, State, D, Limit, C), + Delta = Limit - L1, + if + %% Save some time by assuming next depth will exceed the limit. + Delta * 8 > Limit -> + {T1, C1}; + true -> + D1 = D + 1, + from_form_loop(Form, State, D1, Limit, C1) + end. + +-spec from_form(parse_form(), + #from_form{}, + expand_depth(), + expand_limit(), + cache()) -> {erl_type(), expand_limit(), cache()}. + +%% If there is something wrong with parse_form() +%% throw({error, io_lib:chars()} is called; +%% for unknown remote types +%% self() ! {self(), ext_types, {RemMod, Name, ArgsLen}} +%% is called, unless 'replace_by_none' is given. +%% +%% It is assumed that site_module(S) can be found in MR. + +from_form(_, _S, D, L, C) when D =< 0 ; L =< 0 -> + {t_any(), L, C}; +from_form({var, _L, '_'}, _S, _D, L, C) -> + {t_any(), L, C}; +from_form({var, _L, Name}, S, _D, L, C) -> + V = S#from_form.vtab, + case maps:find(Name, V) of + error -> {t_var(Name), L, C}; + {ok, Val} -> {Val, L, C} + end; +from_form({ann_type, _L, [_Var, Type]}, S, D, L, C) -> + from_form(Type, S, D, L, C); +from_form({paren_type, _L, [Type]}, S, D, L, C) -> + from_form(Type, S, D, L, C); +from_form({remote_type, _L, [{atom, _, Module}, {atom, _, Type}, Args]}, + S, D, L, C) -> + remote_from_form(Module, Type, Args, S, D, L, C); +from_form({atom, _L, Atom}, _S, _D, L, C) -> + {t_atom(Atom), L, C}; +from_form({integer, _L, Int}, _S, _D, L, C) -> + {t_integer(Int), L, C}; +from_form({op, _L, _Op, _Arg} = Op, _S, _D, L, C) -> + case erl_eval:partial_eval(Op) of + {integer, _, Val} -> + {t_integer(Val), L, C}; + _ -> throw({error, io_lib:format("Unable to evaluate type ~w\n", [Op])}) + end; +from_form({op, _L, _Op, _Arg1, _Arg2} = Op, _S, _D, L, C) -> + case erl_eval:partial_eval(Op) of + {integer, _, Val} -> + {t_integer(Val), L, C}; + _ -> throw({error, io_lib:format("Unable to evaluate type ~w\n", [Op])}) + end; +from_form({type, _L, any, []}, _S, _D, L, C) -> + {t_any(), L, C}; +from_form({type, _L, arity, []}, _S, _D, L, C) -> + {t_arity(), L, C}; +from_form({type, _L, atom, []}, _S, _D, L, C) -> + {t_atom(), L, C}; +from_form({type, _L, binary, []}, _S, _D, L, C) -> + {t_binary(), L, C}; +from_form({type, _L, binary, [Base, Unit]} = Type, _S, _D, L, C) -> + case {erl_eval:partial_eval(Base), erl_eval:partial_eval(Unit)} of + {{integer, _, B}, {integer, _, U}} when B >= 0, U >= 0 -> + {t_bitstr(U, B), L, C}; + _ -> throw({error, io_lib:format("Unable to evaluate type ~w\n", [Type])}) + end; +from_form({type, _L, bitstring, []}, _S, _D, L, C) -> + {t_bitstr(), L, C}; +from_form({type, _L, bool, []}, _S, _D, L, C) -> + {t_boolean(), L, C}; % XXX: Temporarily +from_form({type, _L, boolean, []}, _S, _D, L, C) -> + {t_boolean(), L, C}; +from_form({type, _L, byte, []}, _S, _D, L, C) -> + {t_byte(), L, C}; +from_form({type, _L, char, []}, _S, _D, L, C) -> + {t_char(), L, C}; +from_form({type, _L, float, []}, _S, _D, L, C) -> + {t_float(), L, C}; +from_form({type, _L, function, []}, _S, _D, L, C) -> + {t_fun(), L, C}; +from_form({type, _L, 'fun', []}, _S, _D, L, C) -> + {t_fun(), L, C}; +from_form({type, _L, 'fun', [{type, _, any}, Range]}, S, D, L, C) -> + {T, L1, C1} = from_form(Range, S, D - 1, L - 1, C), + {t_fun(T), L1, C1}; +from_form({type, _L, 'fun', [{type, _, product, Domain}, Range]}, + S, D, L, C) -> + {Dom1, L1, C1} = list_from_form(Domain, S, D, L, C), + {Ran1, L2, C2} = from_form(Range, S, D, L1, C1), + {t_fun(Dom1, Ran1), L2, C2}; +from_form({type, _L, identifier, []}, _S, _D, L, C) -> + {t_identifier(), L, C}; +from_form({type, _L, integer, []}, _S, _D, L, C) -> + {t_integer(), L, C}; +from_form({type, _L, iodata, []}, _S, _D, L, C) -> + {t_iodata(), L, C}; +from_form({type, _L, iolist, []}, _S, _D, L, C) -> + {t_iolist(), L, C}; +from_form({type, _L, list, []}, _S, _D, L, C) -> + {t_list(), L, C}; +from_form({type, _L, list, [Type]}, S, D, L, C) -> + {T, L1, C1} = from_form(Type, S, D - 1, L - 1, C), + {t_list(T), L1, C1}; +from_form({type, _L, map, any}, S, D, L, C) -> + builtin_type(map, t_map(), S, D, L, C); +from_form({type, _L, map, List}, S, D0, L, C) -> + {Pairs1, L5, C5} = + fun PairsFromForm(_, L1, C1) when L1 =< 0 -> {[{?any,?opt,?any}], L1, C1}; + PairsFromForm([], L1, C1) -> {[], L1, C1}; + PairsFromForm([{type, _, Oper, [KF, VF]}|T], L1, C1) -> + D = D0 - 1, + {Key, L2, C2} = from_form(KF, S, D, L1, C1), + {Val, L3, C3} = from_form(VF, S, D, L2, C2), + {Pairs0, L4, C4} = PairsFromForm(T, L3 - 1, C3), + case Oper of + map_field_assoc -> {[{Key,?opt, Val}|Pairs0], L4, C4}; + map_field_exact -> {[{Key,?mand,Val}|Pairs0], L4, C4} + end + end(List, L, C), + try + {Pairs, DefK, DefV} = map_from_form(Pairs1, [], [], [], ?none, ?none), + {t_map(Pairs, DefK, DefV), L5, C5} + catch none -> {t_none(), L5, C5} + end; +from_form({type, _L, mfa, []}, _S, _D, L, C) -> + {t_mfa(), L, C}; +from_form({type, _L, module, []}, _S, _D, L, C) -> + {t_module(), L, C}; +from_form({type, _L, nil, []}, _S, _D, L, C) -> + {t_nil(), L, C}; +from_form({type, _L, neg_integer, []}, _S, _D, L, C) -> + {t_neg_integer(), L, C}; +from_form({type, _L, non_neg_integer, []}, _S, _D, L, C) -> + {t_non_neg_integer(), L, C}; +from_form({type, _L, no_return, []}, _S, _D, L, C) -> + {t_unit(), L, C}; +from_form({type, _L, node, []}, _S, _D, L, C) -> + {t_node(), L, C}; +from_form({type, _L, none, []}, _S, _D, L, C) -> + {t_none(), L, C}; +from_form({type, _L, nonempty_list, []}, _S, _D, L, C) -> + {t_nonempty_list(), L, C}; +from_form({type, _L, nonempty_list, [Type]}, S, D, L, C) -> + {T, L1, C1} = from_form(Type, S, D, L - 1, C), + {t_nonempty_list(T), L1, C1}; +from_form({type, _L, nonempty_improper_list, [Cont, Term]}, S, D, L, C) -> + {T1, L1, C1} = from_form(Cont, S, D, L - 1, C), + {T2, L2, C2} = from_form(Term, S, D, L1, C1), + {t_cons(T1, T2), L2, C2}; +from_form({type, _L, nonempty_maybe_improper_list, []}, _S, _D, L, C) -> + {t_cons(?any, ?any), L, C}; +from_form({type, _L, nonempty_maybe_improper_list, [Cont, Term]}, + S, D, L, C) -> + {T1, L1, C1} = from_form(Cont, S, D, L - 1, C), + {T2, L2, C2} = from_form(Term, S, D, L1, C1), + {t_cons(T1, T2), L2, C2}; +from_form({type, _L, nonempty_string, []}, _S, _D, L, C) -> + {t_nonempty_string(), L, C}; +from_form({type, _L, number, []}, _S, _D, L, C) -> + {t_number(), L, C}; +from_form({type, _L, pid, []}, _S, _D, L, C) -> + {t_pid(), L, C}; +from_form({type, _L, port, []}, _S, _D, L, C) -> + {t_port(), L, C}; +from_form({type, _L, pos_integer, []}, _S, _D, L, C) -> + {t_pos_integer(), L, C}; +from_form({type, _L, maybe_improper_list, []}, _S, _D, L, C) -> + {t_maybe_improper_list(), L, C}; +from_form({type, _L, maybe_improper_list, [Content, Termination]}, + S, D, L, C) -> + {T1, L1, C1} = from_form(Content, S, D, L - 1, C), + {T2, L2, C2} = from_form(Termination, S, D, L1, C1), + {t_maybe_improper_list(T1, T2), L2, C2}; +from_form({type, _L, product, Elements}, S, D, L, C) -> + {Lst, L1, C1} = list_from_form(Elements, S, D - 1, L, C), + {t_product(Lst), L1, C1}; +from_form({type, _L, range, [From, To]} = Type, _S, _D, L, C) -> + case {erl_eval:partial_eval(From), erl_eval:partial_eval(To)} of + {{integer, _, FromVal}, {integer, _, ToVal}} -> + {t_from_range(FromVal, ToVal), L, C}; + _ -> throw({error, io_lib:format("Unable to evaluate type ~w\n", [Type])}) + end; +from_form({type, _L, record, [Name|Fields]}, S, D, L, C) -> + record_from_form(Name, Fields, S, D, L, C); +from_form({type, _L, reference, []}, _S, _D, L, C) -> + {t_reference(), L, C}; +from_form({type, _L, string, []}, _S, _D, L, C) -> + {t_string(), L, C}; +from_form({type, _L, term, []}, _S, _D, L, C) -> + {t_any(), L, C}; +from_form({type, _L, timeout, []}, _S, _D, L, C) -> + {t_timeout(), L, C}; +from_form({type, _L, tuple, any}, _S, _D, L, C) -> + {t_tuple(), L, C}; +from_form({type, _L, tuple, Args}, S, D, L, C) -> + {Lst, L1, C1} = list_from_form(Args, S, D - 1, L, C), + {t_tuple(Lst), L1, C1}; +from_form({type, _L, union, Args}, S, D, L, C) -> + {Lst, L1, C1} = list_from_form(Args, S, D, L, C), + {t_sup(Lst), L1, C1}; +from_form({user_type, _L, Name, Args}, S, D, L, C) -> + type_from_form(Name, Args, S, D, L, C); +from_form({type, _L, Name, Args}, S, D, L, C) -> + %% Compatibility: modules compiled before Erlang/OTP 18.0. + type_from_form(Name, Args, S, D, L, C); +from_form({opaque, _L, Name, {Mod, Args, Rep}}, _S, _D, L, C) -> + %% XXX. To be removed. + {t_opaque(Mod, Name, Args, Rep), L, C}. + +builtin_type(Name, Type, S, D, L, C) -> + #from_form{site = Site, mrecs = MR} = S, + M = site_module(Site), + case dict:find(M, MR) of + {ok, R} -> + case lookup_type(Name, 0, R) of + {_, {{_M, _FL, _F, _A}, _T}} -> + type_from_form(Name, [], S, D, L, C); + error -> + {Type, L, C} + end; + error -> + {Type, L, C} + end. + +type_from_form(Name, Args, S, D, L, C) -> + #from_form{site = Site, mrecs = MR, tnames = TypeNames} = S, + ArgsLen = length(Args), + Module = site_module(Site), + TypeName = {type, {Module, Name, ArgsLen}}, + case can_unfold_more(TypeName, TypeNames) of + true -> + {ok, R} = dict:find(Module, MR), + type_from_form1(Name, Args, ArgsLen, R, TypeName, TypeNames, + S, D, L, C); + false -> + {t_any(), L, C} + end. + +type_from_form1(Name, Args, ArgsLen, R, TypeName, TypeNames, S, D, L, C) -> + case lookup_type(Name, ArgsLen, R) of + {Tag, {{Module, _FileName, Form, ArgNames}, Type}} -> + NewTypeNames = [TypeName|TypeNames], + S1 = S#from_form{tnames = NewTypeNames}, + {ArgTypes, L1, C1} = list_from_form(Args, S1, D, L, C), + CKey = cache_key(Module, Name, ArgTypes, TypeNames, D), + case cache_find(CKey, C) of + {CachedType, DeltaL} -> + {CachedType, L1 - DeltaL, C}; + error -> + List = lists:zip(ArgNames, ArgTypes), + TmpV = maps:from_list(List), + S2 = S1#from_form{site = TypeName, vtab = TmpV}, + Fun = fun(DD, LL) -> from_form(Form, S2, DD, LL, C1) end, + {NewType, L3, C3} = + case Tag of + type -> + recur_limit(Fun, D, L1, TypeName, TypeNames); + opaque -> + {Rep, L2, C2} = recur_limit(Fun, D, L1, TypeName, TypeNames), + Rep1 = choose_opaque_type(Rep, Type), + Rep2 = case cannot_have_opaque(Rep1, TypeName, TypeNames) of + true -> Rep1; + false -> + ArgTypes2 = subst_all_vars_to_any_list(ArgTypes), + t_opaque(Module, Name, ArgTypes2, Rep1) + end, + {Rep2, L2, C2} + end, + C4 = cache_put(CKey, NewType, L1 - L3, C3), + {NewType, L3, C4} + end; + error -> + Msg = io_lib:format("Unable to find type ~w/~w\n", + [Name, ArgsLen]), + throw({error, Msg}) + end. + +remote_from_form(RemMod, Name, Args, S, D, L, C) -> + #from_form{xtypes = ET, mrecs = MR, tnames = TypeNames} = S, + if + ET =:= replace_by_none -> + {t_none(), L, C}; + true -> + ArgsLen = length(Args), + MFA = {RemMod, Name, ArgsLen}, + case dict:find(RemMod, MR) of + error -> + self() ! {self(), ext_types, MFA}, + {t_any(), L, C}; + {ok, RemDict} -> + case sets:is_element(MFA, ET) of + true -> + RemType = {type, MFA}, + case can_unfold_more(RemType, TypeNames) of + true -> + remote_from_form1(RemMod, Name, Args, ArgsLen, RemDict, + RemType, TypeNames, S, D, L, C); + false -> + {t_any(), L, C} + end; + false -> + self() ! {self(), ext_types, {RemMod, Name, ArgsLen}}, + {t_any(), L, C} + end + end + end. + +remote_from_form1(RemMod, Name, Args, ArgsLen, RemDict, RemType, TypeNames, + S, D, L, C) -> + case lookup_type(Name, ArgsLen, RemDict) of + {Tag, {{Mod, _FileLine, Form, ArgNames}, Type}} -> + NewTypeNames = [RemType|TypeNames], + S1 = S#from_form{tnames = NewTypeNames}, + {ArgTypes, L1, C1} = list_from_form(Args, S1, D, L, C), + CKey = cache_key(RemMod, Name, ArgTypes, TypeNames, D), + %% case error of + case cache_find(CKey, C) of + {CachedType, DeltaL} -> + {CachedType, L - DeltaL, C}; + error -> + List = lists:zip(ArgNames, ArgTypes), + TmpVarTab = maps:from_list(List), + S2 = S1#from_form{site = RemType, vtab = TmpVarTab}, + Fun = fun(DD, LL) -> from_form(Form, S2, DD, LL, C1) end, + {NewType, L3, C3} = + case Tag of + type -> + recur_limit(Fun, D, L1, RemType, TypeNames); + opaque -> + {NewRep, L2, C2} = recur_limit(Fun, D, L1, RemType, TypeNames), + NewRep1 = choose_opaque_type(NewRep, Type), + NewRep2 = + case cannot_have_opaque(NewRep1, RemType, TypeNames) of + true -> NewRep1; + false -> + ArgTypes2 = subst_all_vars_to_any_list(ArgTypes), + t_opaque(Mod, Name, ArgTypes2, NewRep1) + end, + {NewRep2, L2, C2} + end, + C4 = cache_put(CKey, NewType, L1 - L3, C3), + {NewType, L3, C4} + end; + error -> + Msg = io_lib:format("Unable to find remote type ~w:~w()\n", + [RemMod, Name]), + throw({error, Msg}) + end. + +subst_all_vars_to_any_list(Types) -> + [subst_all_vars_to_any(Type) || Type <- Types]. + +%% Opaque types (both local and remote) are problematic when it comes +%% to the limits (TypeNames, D, and L). The reason is that if any() is +%% substituted for a more specialized subtype of an opaque type, the +%% property stated along with decorate_with_opaque() (the type has to +%% be a subtype of the declared type) no longer holds. +%% +%% The less than perfect remedy: if the opaque type created from a +%% form is not a subset of the declared type, the declared type is +%% used instead, effectively bypassing the limits, and potentially +%% resulting in huge types. +choose_opaque_type(Type, DeclType) -> + case + t_is_subtype(subst_all_vars_to_any(Type), + subst_all_vars_to_any(DeclType)) + of + true -> Type; + false -> DeclType + end. + +record_from_form({atom, _, Name}, ModFields, S, D0, L0, C) -> + #from_form{site = Site, mrecs = MR, tnames = TypeNames} = S, + RecordType = {record, Name}, + case can_unfold_more(RecordType, TypeNames) of + true -> + M = site_module(Site), + {ok, R} = dict:find(M, MR), + case lookup_record(Name, R) of + {ok, DeclFields} -> + NewTypeNames = [RecordType|TypeNames], + Site1 = {record, {M, Name, length(DeclFields)}}, + S1 = S#from_form{site = Site1, tnames = NewTypeNames}, + Fun = fun(D, L) -> + {GetModRec, L1, C1} = + get_mod_record(ModFields, DeclFields, S1, D, L, C), + case GetModRec of + {error, FieldName} -> + throw({error, + io_lib:format("Illegal declaration of #~w{~w}\n", + [Name, FieldName])}); + {ok, NewFields} -> + S2 = S1#from_form{vtab = var_table__new()}, + {NewFields1, L2, C2} = + fields_from_form(NewFields, S2, D, L1, C1), + Rec = t_tuple( + [t_atom(Name)|[Type + || {_FieldName, Type} <- NewFields1]]), + {Rec, L2, C2} + end + end, + recur_limit(Fun, D0, L0, RecordType, TypeNames); + error -> + throw({error, io_lib:format("Unknown record #~w{}\n", [Name])}) + end; + false -> + {t_any(), L0, C} + end. + +get_mod_record([], DeclFields, _S, _D, L, C) -> + {{ok, DeclFields}, L, C}; +get_mod_record(ModFields, DeclFields, S, D, L, C) -> + DeclFieldsDict = lists:keysort(1, DeclFields), + {ModFieldsDict, L1, C1} = build_field_dict(ModFields, S, D, L, C), + case get_mod_record_types(DeclFieldsDict, ModFieldsDict, []) of + {error, _FieldName} = Error -> {Error, L1, C1}; + {ok, FinalKeyDict} -> + Fields = [lists:keyfind(FieldName, 1, FinalKeyDict) + || {FieldName, _, _} <- DeclFields], + {{ok, Fields}, L1, C1} + end. + +build_field_dict(FieldTypes, S, D, L, C) -> + build_field_dict(FieldTypes, S, D, L, C, []). + +build_field_dict([{type, _, field_type, [{atom, _, Name}, Type]}|Left], + S, D, L, C, Acc) -> + {T, L1, C1} = from_form(Type, S, D, L - 1, C), + NewAcc = [{Name, Type, T}|Acc], + build_field_dict(Left, S, D, L1, C1, NewAcc); +build_field_dict([], _S, _D, L, C, Acc) -> + {lists:keysort(1, Acc), L, C}. + +get_mod_record_types([{FieldName, _Abstr, _DeclType}|Left1], + [{FieldName, TypeForm, ModType}|Left2], + Acc) -> + get_mod_record_types(Left1, Left2, [{FieldName, TypeForm, ModType}|Acc]); +get_mod_record_types([{FieldName1, _Abstr, _DeclType} = DT|Left1], + [{FieldName2, _FormType, _ModType}|_] = List2, + Acc) when FieldName1 < FieldName2 -> + get_mod_record_types(Left1, List2, [DT|Acc]); +get_mod_record_types(Left1, [], Acc) -> + {ok, lists:keysort(1, Left1++Acc)}; +get_mod_record_types(_, [{FieldName2, _FormType, _ModType}|_], _Acc) -> + {error, FieldName2}. + +%% It is important to create a limited version of the record type +%% since nested record types can otherwise easily result in huge +%% terms. +fields_from_form([], _S, _D, L, C) -> + {[], L, C}; +fields_from_form([{Name, Abstr, _Type}|Tail], S, D, L, C) -> + {T, L1, C1} = from_form(Abstr, S, D, L, C), + {F, L2, C2} = fields_from_form(Tail, S, D, L1, C1), + {[{Name, T}|F], L2, C2}. + +list_from_form([], _S, _D, L, C) -> + {[], L, C}; +list_from_form([H|Tail], S, D, L, C) -> + {H1, L1, C1} = from_form(H, S, D, L - 1, C), + {T1, L2, C2} = list_from_form(Tail, S, D, L1, C1), + {[H1|T1], L2, C2}. + +%% Sorts, combines non-singleton pairs, and applies precendence and +%% mandatoriness rules. +map_from_form([], ShdwPs, MKs, Pairs, DefK, DefV) -> + verify_possible(MKs, ShdwPs), + {promote_to_mand(MKs, Pairs), DefK, DefV}; +map_from_form([{SKey,MNess,Val}|SPairs], ShdwPs0, MKs0, Pairs0, DefK0, DefV0) -> + Key = lists:foldl(fun({K,_},S)->t_subtract(S,K)end, SKey, ShdwPs0), + ShdwPs = case Key of ?none -> ShdwPs0; _ -> [{Key,Val}|ShdwPs0] end, + MKs = case MNess of ?mand -> [SKey|MKs0]; ?opt -> MKs0 end, + if MNess =:= ?mand, SKey =:= ?none -> throw(none); + true -> ok + end, + {Pairs, DefK, DefV} = + case is_singleton_type(Key) of + true -> + MNess1 = case Val =:= ?none of true -> ?opt; false -> MNess end, + {mapdict_insert({Key,MNess1,Val}, Pairs0), DefK0, DefV0}; + false -> + case Key =:= ?none orelse Val =:= ?none of + true -> {Pairs0, DefK0, DefV0}; + false -> {Pairs0, t_sup(DefK0, Key), t_sup(DefV0, Val)} + end + end, + map_from_form(SPairs, ShdwPs, MKs, Pairs, DefK, DefV). + +%% Verifies that all mandatory keys are possible, throws 'none' otherwise +verify_possible(MKs, ShdwPs) -> + lists:foreach(fun(M) -> verify_possible_1(M, ShdwPs) end, MKs). + +verify_possible_1(M, ShdwPs) -> + case lists:any(fun({K,_}) -> t_inf(M, K) =/= ?none end, ShdwPs) of + true -> ok; + false -> throw(none) + end. + +-spec promote_to_mand([erl_type()], t_map_dict()) -> t_map_dict(). + +promote_to_mand(_, []) -> []; +promote_to_mand(MKs, [E={K,_,V}|T]) -> + [case lists:any(fun(M) -> t_is_equal(K,M) end, MKs) of + true -> {K, ?mand, V}; + false -> E + end|promote_to_mand(MKs, T)]. + +-define(RECUR_EXPAND_LIMIT, 10). +-define(RECUR_EXPAND_DEPTH, 2). + +%% If more of the limited resources is spent on the non-recursive +%% forms, more warnings are found. And the analysis is also a bit +%% faster. +%% +%% Setting REC_TYPE_LIMIT to 1 would work also work well. + +recur_limit(Fun, D, L, _, _) when L =< ?RECUR_EXPAND_DEPTH, + D =< ?RECUR_EXPAND_LIMIT -> + Fun(D, L); +recur_limit(Fun, D, L, TypeName, TypeNames) -> + case is_recursive(TypeName, TypeNames) of + true -> + {T, L1, C1} = Fun(?RECUR_EXPAND_DEPTH, ?RECUR_EXPAND_LIMIT), + {T, L - L1, C1}; + false -> + Fun(D, L) + end. + +-spec t_check_record_fields(parse_form(), sets:set(mfa()), site(), + mod_records(), var_table(), cache()) -> cache(). + +t_check_record_fields(Form, ExpTypes, Site, RecDict, VarTable, Cache) -> + State = #from_form{site = Site, + xtypes = ExpTypes, + mrecs = RecDict, + vtab = VarTable, + tnames = []}, + check_record_fields(Form, State, Cache). + +-spec check_record_fields(parse_form(), #from_form{}, cache()) -> cache(). + +%% If there is something wrong with parse_form() +%% throw({error, io_lib:chars()} is called. + +check_record_fields({var, _L, _}, _S, C) -> C; +check_record_fields({ann_type, _L, [_Var, Type]}, S, C) -> + check_record_fields(Type, S, C); +check_record_fields({paren_type, _L, [Type]}, S, C) -> + check_record_fields(Type, S, C); +check_record_fields({remote_type, _L, [{atom, _, _}, {atom, _, _}, Args]}, + S, C) -> + list_check_record_fields(Args, S, C); +check_record_fields({atom, _L, _}, _S, C) -> C; +check_record_fields({integer, _L, _}, _S, C) -> C; +check_record_fields({op, _L, _Op, _Arg}, _S, C) -> C; +check_record_fields({op, _L, _Op, _Arg1, _Arg2}, _S, C) -> C; +check_record_fields({type, _L, tuple, any}, _S, C) -> C; +check_record_fields({type, _L, map, any}, _S, C) -> C; +check_record_fields({type, _L, binary, [_Base, _Unit]}, _S, C) -> C; +check_record_fields({type, _L, 'fun', [{type, _, any}, Range]}, S, C) -> + check_record_fields(Range, S, C); +check_record_fields({type, _L, range, [_From, _To]}, _S, C) -> C; +check_record_fields({type, _L, record, [Name|Fields]}, S, C) -> + check_record(Name, Fields, S, C); +check_record_fields({type, _L, _, Args}, S, C) -> + list_check_record_fields(Args, S, C); +check_record_fields({user_type, _L, _Name, Args}, S, C) -> + list_check_record_fields(Args, S, C). + +check_record({atom, _, Name}, ModFields, S, C) -> + #from_form{site = Site, mrecs = MR} = S, + M = site_module(Site), + {ok, R} = dict:find(M, MR), + {ok, DeclFields} = lookup_record(Name, R), + case check_fields(Name, ModFields, DeclFields, S, C) of + {error, FieldName} -> + throw({error, io_lib:format("Illegal declaration of #~w{~w}\n", + [Name, FieldName])}); + C1 -> C1 + end. + +check_fields(RecName, [{type, _, field_type, [{atom, _, Name}, Abstr]}|Left], + DeclFields, S, C) -> + #from_form{site = Site0, xtypes = ET, mrecs = MR, vtab = V} = S, + M = site_module(Site0), + Site = {record, {M, RecName, length(DeclFields)}}, + {Type, C1} = t_from_form(Abstr, ET, Site, MR, V, C), + {Name, _, DeclType} = lists:keyfind(Name, 1, DeclFields), + TypeNoVars = subst_all_vars_to_any(Type), + case t_is_subtype(TypeNoVars, DeclType) of + false -> {error, Name}; + true -> check_fields(RecName, Left, DeclFields, S, C1) + end; +check_fields(_RecName, [], _Decl, _S, C) -> + C. + +list_check_record_fields([], _S, C) -> + C; +list_check_record_fields([H|Tail], S, C) -> + C1 = check_record_fields(H, S, C), + list_check_record_fields(Tail, S, C1). + +site_module({_, {Module, _, _}}) -> + Module. + +-spec cache__new() -> cache(). + +cache__new() -> + maps:new(). + +-spec cache_key(module(), atom(), [erl_type()], + type_names(), expand_depth()) -> cache_key(). + +%% If TypeNames is left out from the key, the cache is smaller, and +%% the form-to-type translation is faster. But it would be a shame if, +%% for example, any() is used, where a more complex type should be +%% used. There is also a slight risk of creating unnecessarily big +%% types. + +cache_key(Module, Name, ArgTypes, TypeNames, D) -> + {Module, Name, D, ArgTypes, TypeNames}. + +-spec cache_find(cache_key(), cache()) -> + {erl_type(), expand_limit()} | 'error'. + +cache_find(Key, Cache) -> + case maps:find(Key, Cache) of + {ok, Value} -> + Value; + error -> + error + end. + +-spec cache_put(cache_key(), erl_type(), expand_limit(), cache()) -> cache(). + +cache_put(_Key, _Type, DeltaL, Cache) when DeltaL < 0 -> + %% The type is truncated; do not reuse it. + Cache; +cache_put(Key, Type, DeltaL, Cache) -> + maps:put(Key, {Type, DeltaL}, Cache). + +-spec t_var_names([erl_type()]) -> [atom()]. + +t_var_names([{var, _, Name}|L]) when L =/= '_' -> + [Name|t_var_names(L)]; +t_var_names([]) -> + []. + +-spec t_form_to_string(parse_form()) -> string(). + +t_form_to_string({var, _L, '_'}) -> "_"; +t_form_to_string({var, _L, Name}) -> atom_to_list(Name); +t_form_to_string({atom, _L, Atom}) -> + io_lib:write_string(atom_to_list(Atom), $'); % To quote or not to quote... ' +t_form_to_string({integer, _L, Int}) -> integer_to_list(Int); +t_form_to_string({op, _L, _Op, _Arg} = Op) -> + case erl_eval:partial_eval(Op) of + {integer, _, _} = Int -> t_form_to_string(Int); + _ -> io_lib:format("Badly formed type ~w", [Op]) + end; +t_form_to_string({op, _L, _Op, _Arg1, _Arg2} = Op) -> + case erl_eval:partial_eval(Op) of + {integer, _, _} = Int -> t_form_to_string(Int); + _ -> io_lib:format("Badly formed type ~w", [Op]) + end; +t_form_to_string({ann_type, _L, [Var, Type]}) -> + t_form_to_string(Var) ++ "::" ++ t_form_to_string(Type); +t_form_to_string({paren_type, _L, [Type]}) -> + flat_format("(~s)", [t_form_to_string(Type)]); +t_form_to_string({remote_type, _L, [{atom, _, Mod}, {atom, _, Name}, Args]}) -> + ArgString = "(" ++ string:join(t_form_to_string_list(Args), ",") ++ ")", + flat_format("~w:~w", [Mod, Name]) ++ ArgString; +t_form_to_string({type, _L, arity, []}) -> "arity()"; +t_form_to_string({type, _L, binary, []}) -> "binary()"; +t_form_to_string({type, _L, binary, [Base, Unit]} = Type) -> + case {erl_eval:partial_eval(Base), erl_eval:partial_eval(Unit)} of + {{integer, _, B}, {integer, _, U}} -> + %% the following mirrors the clauses of t_to_string/2 + case {U, B} of + {0, 0} -> "<<>>"; + {8, 0} -> "binary()"; + {1, 0} -> "bitstring()"; + {0, B} -> flat_format("<<_:~w>>", [B]); + {U, 0} -> flat_format("<<_:_*~w>>", [U]); + {U, B} -> flat_format("<<_:~w,_:_*~w>>", [B, U]) + end; + _ -> io_lib:format("Badly formed bitstr type ~w", [Type]) + end; +t_form_to_string({type, _L, bitstring, []}) -> "bitstring()"; +t_form_to_string({type, _L, 'fun', []}) -> "fun()"; +t_form_to_string({type, _L, 'fun', [{type, _, any}, Range]}) -> + "fun(...) -> " ++ t_form_to_string(Range); +t_form_to_string({type, _L, 'fun', [{type, _, product, Domain}, Range]}) -> + "fun((" ++ string:join(t_form_to_string_list(Domain), ",") ++ ") -> " + ++ t_form_to_string(Range) ++ ")"; +t_form_to_string({type, _L, iodata, []}) -> "iodata()"; +t_form_to_string({type, _L, iolist, []}) -> "iolist()"; +t_form_to_string({type, _L, list, [Type]}) -> + "[" ++ t_form_to_string(Type) ++ "]"; +t_form_to_string({type, _L, map, any}) -> "map()"; +t_form_to_string({type, _L, map, Args}) -> + "#{" ++ string:join(t_form_to_string_list(Args), ",") ++ "}"; +t_form_to_string({type, _L, map_field_assoc, [Key, Val]}) -> + t_form_to_string(Key) ++ "=>" ++ t_form_to_string(Val); +t_form_to_string({type, _L, map_field_exact, [Key, Val]}) -> + t_form_to_string(Key) ++ ":=" ++ t_form_to_string(Val); +t_form_to_string({type, _L, mfa, []}) -> "mfa()"; +t_form_to_string({type, _L, module, []}) -> "module()"; +t_form_to_string({type, _L, node, []}) -> "node()"; +t_form_to_string({type, _L, nonempty_list, [Type]}) -> + "[" ++ t_form_to_string(Type) ++ ",...]"; +t_form_to_string({type, _L, nonempty_string, []}) -> "nonempty_string()"; +t_form_to_string({type, _L, product, Elements}) -> + "<" ++ string:join(t_form_to_string_list(Elements), ",") ++ ">"; +t_form_to_string({type, _L, range, [From, To]} = Type) -> + case {erl_eval:partial_eval(From), erl_eval:partial_eval(To)} of + {{integer, _, FromVal}, {integer, _, ToVal}} -> + flat_format("~w..~w", [FromVal, ToVal]); + _ -> flat_format("Badly formed type ~w",[Type]) + end; +t_form_to_string({type, _L, record, [{atom, _, Name}]}) -> + flat_format("#~w{}", [Name]); +t_form_to_string({type, _L, record, [{atom, _, Name}|Fields]}) -> + FieldString = string:join(t_form_to_string_list(Fields), ","), + flat_format("#~w{~s}", [Name, FieldString]); +t_form_to_string({type, _L, field_type, [{atom, _, Name}, Type]}) -> + flat_format("~w::~s", [Name, t_form_to_string(Type)]); +t_form_to_string({type, _L, term, []}) -> "term()"; +t_form_to_string({type, _L, timeout, []}) -> "timeout()"; +t_form_to_string({type, _L, tuple, any}) -> "tuple()"; +t_form_to_string({type, _L, tuple, Args}) -> + "{" ++ string:join(t_form_to_string_list(Args), ",") ++ "}"; +t_form_to_string({type, _L, union, Args}) -> + string:join(t_form_to_string_list(Args), " | "); +t_form_to_string({type, _L, Name, []} = T) -> + try + M = mod, + D0 = dict:new(), + MR = dict:from_list([{M, D0}]), + Site = {type, {M,Name,0}}, + V = var_table__new(), + C = cache__new(), + State = #from_form{site = Site, + xtypes = sets:new(), + mrecs = MR, + vtab = V, + tnames = []}, + {T1, _, _} = from_form(T, State, _Deep=1000, _ALot=1000000, C), + t_to_string(T1) + catch throw:{error, _} -> atom_to_string(Name) ++ "()" + end; +t_form_to_string({user_type, _L, Name, List}) -> + flat_format("~w(~s)", + [Name, string:join(t_form_to_string_list(List), ",")]); +t_form_to_string({type, L, Name, List}) -> + %% Compatibility: modules compiled before Erlang/OTP 18.0. + t_form_to_string({user_type, L, Name, List}). + +t_form_to_string_list(List) -> + t_form_to_string_list(List, []). + +t_form_to_string_list([H|T], Acc) -> + t_form_to_string_list(T, [t_form_to_string(H)|Acc]); +t_form_to_string_list([], Acc) -> + lists:reverse(Acc). + +-spec atom_to_string(atom()) -> string(). + +atom_to_string(Atom) -> + flat_format("~w", [Atom]). + +%%============================================================================= +%% +%% Utilities +%% +%%============================================================================= + +-spec any_none([erl_type()]) -> boolean(). + +any_none([?none|_Left]) -> true; +any_none([_|Left]) -> any_none(Left); +any_none([]) -> false. + +-spec any_none_or_unit([erl_type()]) -> boolean(). + +any_none_or_unit([?none|_]) -> true; +any_none_or_unit([?unit|_]) -> true; +any_none_or_unit([_|Left]) -> any_none_or_unit(Left); +any_none_or_unit([]) -> false. + +-spec is_erl_type(any()) -> boolean(). + +is_erl_type(?any) -> true; +is_erl_type(?none) -> true; +is_erl_type(?unit) -> true; +is_erl_type(#c{}) -> true; +is_erl_type(_) -> false. + +-spec lookup_record(atom(), type_table()) -> + 'error' | {'ok', [{atom(), parse_form(), erl_type()}]}. + +lookup_record(Tag, RecDict) when is_atom(Tag) -> + case dict:find({record, Tag}, RecDict) of + {ok, {_FileLine, [{_Arity, Fields}]}} -> + {ok, Fields}; + {ok, {_FileLine, List}} when is_list(List) -> + %% This will have to do, since we do not know which record we + %% are looking for. + error; + error -> + error + end. + +-spec lookup_record(atom(), arity(), type_table()) -> + 'error' | {'ok', [{atom(), parse_form(), erl_type()}]}. + +lookup_record(Tag, Arity, RecDict) when is_atom(Tag) -> + case dict:find({record, Tag}, RecDict) of + {ok, {_FileLine, [{Arity, Fields}]}} -> {ok, Fields}; + {ok, {_FileLine, OrdDict}} -> orddict:find(Arity, OrdDict); + error -> error + end. + +-spec lookup_type(_, _, _) -> {'type' | 'opaque', type_value()} | 'error'. +lookup_type(Name, Arity, RecDict) -> + case dict:find({type, Name, Arity}, RecDict) of + error -> + case dict:find({opaque, Name, Arity}, RecDict) of + error -> error; + {ok, Found} -> {opaque, Found} + end; + {ok, Found} -> {type, Found} + end. + +-spec type_is_defined('type' | 'opaque', atom(), arity(), type_table()) -> + boolean(). + +type_is_defined(TypeOrOpaque, Name, Arity, RecDict) -> + dict:is_key({TypeOrOpaque, Name, Arity}, RecDict). + +cannot_have_opaque(Type, TypeName, TypeNames) -> + t_is_none(Type) orelse is_recursive(TypeName, TypeNames). + +is_recursive(TypeName, TypeNames) -> + lists:member(TypeName, TypeNames). + +can_unfold_more(TypeName, TypeNames) -> + Fun = fun(E, Acc) -> case E of TypeName -> Acc + 1; _ -> Acc end end, + lists:foldl(Fun, 0, TypeNames) < ?REC_TYPE_LIMIT. + +-spec do_opaque(erl_type(), opaques(), fun((_) -> T)) -> T. + +%% Probably a little faster than calling t_unopaque/2. +%% Unions that are due to opaque types are unopaqued. +do_opaque(?opaque(_) = Type, Opaques, Pred) -> + case Opaques =:= 'universe' orelse is_opaque_type(Type, Opaques) of + true -> do_opaque(t_opaque_structure(Type), Opaques, Pred); + false -> Pred(Type) + end; +do_opaque(?union(List) = Type, Opaques, Pred) -> + [A,B,F,I,L,N,T,M,O,Map] = List, + if O =:= ?none -> Pred(Type); + true -> + case Opaques =:= 'universe' orelse is_opaque_type(O, Opaques) of + true -> + S = t_opaque_structure(O), + do_opaque(t_sup([A,B,F,I,L,N,T,M,S,Map]), Opaques, Pred); + false -> Pred(Type) + end + end; +do_opaque(Type, _Opaques, Pred) -> + Pred(Type). + +map_all_values(?map(Pairs,_,DefV)) -> + [DefV|[V || {V, _, _} <- Pairs]]. + +map_all_keys(?map(Pairs,DefK,_)) -> + [DefK|[K || {_, _, K} <- Pairs]]. + +map_all_types(M) -> + map_all_keys(M) ++ map_all_values(M). + +%% Tests if a type has exactly one possible value. +-spec t_is_singleton(erl_type()) -> boolean(). + +t_is_singleton(Type) -> + t_is_singleton(Type, 'universe'). + +-spec t_is_singleton(erl_type(), opaques()) -> boolean(). + +t_is_singleton(Type, Opaques) -> + do_opaque(Type, Opaques, fun is_singleton_type/1). + +%% Incomplete; not all representable singleton types are included. +is_singleton_type(?nil) -> true; +is_singleton_type(?atom(?any)) -> false; +is_singleton_type(?atom(Set)) -> + ordsets:size(Set) =:= 1; +is_singleton_type(?int_range(V, V)) -> true; +is_singleton_type(?int_set(Set)) -> + ordsets:size(Set) =:= 1; +is_singleton_type(?tuple(Types, Arity, _)) when is_integer(Arity) -> + lists:all(fun is_singleton_type/1, Types); +is_singleton_type(?tuple_set([{Arity, [OnlyTuple]}])) when is_integer(Arity) -> + is_singleton_type(OnlyTuple); +is_singleton_type(?map(Pairs, ?none, ?none)) -> + lists:all(fun({_,MNess,V}) -> MNess =:= ?mand andalso is_singleton_type(V) + end, Pairs); +is_singleton_type(_) -> + false. + +%% Returns the only possible value of a singleton type. +-spec t_singleton_to_term(erl_type(), opaques()) -> term(). + +t_singleton_to_term(Type, Opaques) -> + do_opaque(Type, Opaques, fun singleton_type_to_term/1). + +singleton_type_to_term(?nil) -> []; +singleton_type_to_term(?atom(Set)) when Set =/= ?any -> + case ordsets:size(Set) of + 1 -> hd(ordsets:to_list(Set)); + _ -> error(badarg) + end; +singleton_type_to_term(?int_range(V, V)) -> V; +singleton_type_to_term(?int_set(Set)) -> + case ordsets:size(Set) of + 1 -> hd(ordsets:to_list(Set)); + _ -> error(badarg) + end; +singleton_type_to_term(?tuple(Types, Arity, _)) when is_integer(Arity) -> + lists:map(fun singleton_type_to_term/1, Types); +singleton_type_to_term(?tuple_set([{Arity, [OnlyTuple]}])) + when is_integer(Arity) -> + singleton_type_to_term(OnlyTuple); +singleton_type_to_term(?map(Pairs, ?none, ?none)) -> + maps:from_list([{singleton_type_to_term(K), singleton_type_to_term(V)} + || {K,?mand,V} <- Pairs]). + +%% ----------------------------------- +%% Set +%% + +set_singleton(Element) -> + ordsets:from_list([Element]). + +set_is_singleton(Element, Set) -> + set_singleton(Element) =:= Set. + +set_is_element(Element, Set) -> + ordsets:is_element(Element, Set). + +set_union(?any, _) -> ?any; +set_union(_, ?any) -> ?any; +set_union(S1, S2) -> + case ordsets:union(S1, S2) of + S when length(S) =< ?SET_LIMIT -> S; + _ -> ?any + end. + +%% The intersection and subtraction can return ?none. +%% This should always be handled right away since ?none is not a valid set. +%% However, ?any is considered a valid set. + +set_intersection(?any, S) -> S; +set_intersection(S, ?any) -> S; +set_intersection(S1, S2) -> + case ordsets:intersection(S1, S2) of + [] -> ?none; + S -> S + end. + +set_subtract(_, ?any) -> ?none; +set_subtract(?any, _) -> ?any; +set_subtract(S1, S2) -> + case ordsets:subtract(S1, S2) of + [] -> ?none; + S -> S + end. + +set_from_list(List) -> + case length(List) of + L when L =< ?SET_LIMIT -> ordsets:from_list(List); + L when L > ?SET_LIMIT -> ?any + end. + +set_to_list(Set) -> + ordsets:to_list(Set). + +set_filter(Fun, Set) -> + case ordsets:filter(Fun, Set) of + [] -> ?none; + NewSet -> NewSet + end. + +set_size(Set) -> + ordsets:size(Set). + +set_to_string(Set) -> + L = [case is_atom(X) of + true -> io_lib:write_string(atom_to_list(X), $'); % stupid emacs ' + false -> flat_format("~w", [X]) + end || X <- set_to_list(Set)], + string:join(L, " | "). + +set_min([H|_]) -> H. + +set_max(Set) -> + hd(lists:reverse(Set)). + +flat_format(F, S) -> + lists:flatten(io_lib:format(F, S)). + +%%============================================================================= +%% +%% Utilities for the binary type +%% +%%============================================================================= + +-spec gcd(integer(), integer()) -> integer(). + +gcd(A, B) when B > A -> + gcd1(B, A); +gcd(A, B) -> + gcd1(A, B). + +-spec gcd1(integer(), integer()) -> integer(). + +gcd1(A, 0) -> A; +gcd1(A, B) -> + case A rem B of + 0 -> B; + X -> gcd1(B, X) + end. + +-spec bitstr_concat(erl_type(), erl_type()) -> erl_type(). + +bitstr_concat(?none, _) -> ?none; +bitstr_concat(_, ?none) -> ?none; +bitstr_concat(?bitstr(U1, B1), ?bitstr(U2, B2)) -> + t_bitstr(gcd(U1, U2), B1+B2). + +-spec bitstr_match(erl_type(), erl_type()) -> erl_type(). + +bitstr_match(?none, _) -> ?none; +bitstr_match(_, ?none) -> ?none; +bitstr_match(?bitstr(0, B1), ?bitstr(0, B2)) when B1 =< B2 -> + t_bitstr(0, B2-B1); +bitstr_match(?bitstr(0, _B1), ?bitstr(0, _B2)) -> + ?none; +bitstr_match(?bitstr(0, B1), ?bitstr(U2, B2)) when B1 =< B2 -> + t_bitstr(U2, B2-B1); +bitstr_match(?bitstr(0, B1), ?bitstr(U2, B2)) -> + t_bitstr(U2, handle_base(U2, B2-B1)); +bitstr_match(?bitstr(_, B1), ?bitstr(0, B2)) when B1 > B2 -> + ?none; +bitstr_match(?bitstr(U1, B1), ?bitstr(U2, B2)) -> + GCD = gcd(U1, U2), + t_bitstr(GCD, handle_base(GCD, B2-B1)). + +-spec handle_base(integer(), integer()) -> integer(). + +handle_base(Unit, Pos) when Pos >= 0 -> + Pos rem Unit; +handle_base(Unit, Neg) -> + (Unit+(Neg rem Unit)) rem Unit. + +family(L) -> + R = sofs:relation(L), + F = sofs:relation_to_family(R), + sofs:to_external(F). + +%%============================================================================= +%% +%% Interface functions for abstract data types defined in this module +%% +%%============================================================================= + +-spec var_table__new() -> var_table(). + +var_table__new() -> + maps:new(). + +%%============================================================================= +%% Consistency-testing function(s) below +%%============================================================================= + +-ifdef(DO_ERL_TYPES_TEST). + +test() -> + Atom1 = t_atom(), + Atom2 = t_atom(foo), + Atom3 = t_atom(bar), + true = t_is_atom(Atom2), + + True = t_atom(true), + False = t_atom(false), + Bool = t_boolean(), + true = t_is_boolean(True), + true = t_is_boolean(Bool), + false = t_is_boolean(Atom1), + + Binary = t_binary(), + true = t_is_binary(Binary), + + Bitstr = t_bitstr(), + true = t_is_bitstr(Bitstr), + + Bitstr1 = t_bitstr(7, 3), + true = t_is_bitstr(Bitstr1), + false = t_is_binary(Bitstr1), + + Bitstr2 = t_bitstr(16, 8), + true = t_is_bitstr(Bitstr2), + true = t_is_binary(Bitstr2), + + ?bitstr(8, 16) = t_subtract(t_bitstr(4, 12), t_bitstr(8, 12)), + ?bitstr(8, 16) = t_subtract(t_bitstr(4, 12), t_bitstr(8, 12)), + + Int1 = t_integer(), + Int2 = t_integer(1), + Int3 = t_integer(16#ffffffff), + true = t_is_integer(Int2), + true = t_is_byte(Int2), + false = t_is_byte(Int3), + false = t_is_byte(t_from_range(-1, 1)), + true = t_is_byte(t_from_range(1, ?MAX_BYTE)), + + Tuple1 = t_tuple(), + Tuple2 = t_tuple(3), + Tuple3 = t_tuple([Atom1, Int1]), + Tuple4 = t_tuple([Tuple1, Tuple2]), + Tuple5 = t_tuple([Tuple3, Tuple4]), + Tuple6 = t_limit(Tuple5, 2), + Tuple7 = t_limit(Tuple5, 3), + true = t_is_tuple(Tuple1), + + Port = t_port(), + Pid = t_pid(), + Ref = t_reference(), + Identifier = t_identifier(), + false = t_is_reference(Port), + true = t_is_identifier(Port), + + Function1 = t_fun(), + Function2 = t_fun(Pid), + Function3 = t_fun([], Pid), + Function4 = t_fun([Port, Pid], Pid), + Function5 = t_fun([Pid, Atom1], Int2), + true = t_is_fun(Function3), + + List1 = t_list(), + List2 = t_list(t_boolean()), + List3 = t_cons(t_boolean(), List2), + List4 = t_cons(t_boolean(), t_atom()), + List5 = t_cons(t_boolean(), t_nil()), + List6 = t_cons_tl(List5), + List7 = t_sup(List4, List5), + List8 = t_inf(List7, t_list()), + List9 = t_cons(), + List10 = t_cons_tl(List9), + true = t_is_boolean(t_cons_hd(List5)), + true = t_is_list(List5), + false = t_is_list(List4), + + Product1 = t_product([Atom1, Atom2]), + Product2 = t_product([Atom3, Atom1]), + Product3 = t_product([Atom3, Atom2]), + + Union1 = t_sup(Atom2, Atom3), + Union2 = t_sup(Tuple2, Tuple3), + Union3 = t_sup(Int2, Atom3), + Union4 = t_sup(Port, Pid), + Union5 = t_sup(Union4, Int1), + Union6 = t_sup(Function1, Function2), + Union7 = t_sup(Function4, Function5), + Union8 = t_sup(True, False), + true = t_is_boolean(Union8), + Union9 = t_sup(Int2, t_integer(2)), + true = t_is_byte(Union9), + Union10 = t_sup(t_tuple([t_atom(true), ?any]), + t_tuple([t_atom(false), ?any])), + + ?any = t_sup(Product3, Function5), + + Atom3 = t_inf(Union3, Atom1), + Union2 = t_inf(Union2, Tuple1), + Int2 = t_inf(Int1, Union3), + Union4 = t_inf(Union4, Identifier), + Port = t_inf(Union5, Port), + Function4 = t_inf(Union7, Function4), + ?none = t_inf(Product2, Atom1), + Product3 = t_inf(Product1, Product2), + Function5 = t_inf(Union7, Function5), + true = t_is_byte(t_inf(Union9, t_number())), + true = t_is_char(t_inf(Union9, t_number())), + + io:format("3? ~p ~n", [?int_set([3])]), + + RecDict = dict:store({foo, 2}, [bar, baz], dict:new()), + Record1 = t_from_term({foo, [1,2], {1,2,3}}), + + Types = [ + Atom1, + Atom2, + Atom3, + Binary, + Int1, + Int2, + Tuple1, + Tuple2, + Tuple3, + Tuple4, + Tuple5, + Tuple6, + Tuple7, + Ref, + Port, + Pid, + Identifier, + List1, + List2, + List3, + List4, + List5, + List6, + List7, + List8, + List9, + List10, + Function1, + Function2, + Function3, + Function4, + Function5, + Product1, + Product2, + Record1, + Union1, + Union2, + Union3, + Union4, + Union5, + Union6, + Union7, + Union8, + Union10, + t_inf(Union10, t_tuple([t_atom(true), t_integer()])) + ], + io:format("~p\n", [[t_to_string(X, RecDict) || X <- Types]]). + +-endif. diff --git a/lib/dialyzer/test/plt_SUITE.erl b/lib/dialyzer/test/plt_SUITE.erl index 6ebe23b54b..460d4e2240 100644 --- a/lib/dialyzer/test/plt_SUITE.erl +++ b/lib/dialyzer/test/plt_SUITE.erl @@ -8,13 +8,15 @@ -export([suite/0, all/0, build_plt/1, beam_tests/1, update_plt/1, local_fun_same_as_callback/1, - remove_plt/1, run_plt_check/1, run_succ_typings/1]). + remove_plt/1, run_plt_check/1, run_succ_typings/1, + bad_dialyzer_attr/1]). suite() -> [{timetrap, ?plt_timeout}]. all() -> [build_plt, beam_tests, update_plt, run_plt_check, - remove_plt, run_succ_typings, local_fun_same_as_callback]. + remove_plt, run_succ_typings, local_fun_same_as_callback, + bad_dialyzer_attr]. build_plt(Config) -> OutDir = ?config(priv_dir, Config), @@ -249,6 +251,30 @@ remove_plt(Config) -> {init_plt, Plt}] ++ Opts), ok. +bad_dialyzer_attr(Config) -> + PrivDir = ?config(priv_dir, Config), + + Prog1 = <<"-module(dial). + -dialyzer({no_return, [undef/0]}).">>, + {ok, Beam1} = compile(Config, Prog1, dial, []), + Plt = filename:join(PrivDir, "bad_attr.plt"), + {dialyzer_error, + "Analysis failed with error:\n" + "Could not scan the following file(s):\n" + " Unknown function undef/0 in line " ++ _} = + (catch run_dialyzer(plt_build, [Beam1], [])), + + Prog2 = <<"-module(dial). + -dialyzer({no_return, [{undef,1,2}]}).">>, + {ok, Beam2} = compile(Config, Prog2, dial, []), + {dialyzer_error, + "Analysis failed with error:\n" + "Could not scan the following file(s):\n" + " Bad function {undef,1,2} in line " ++ _} = + (catch run_dialyzer(plt_build, [Beam2], [])), + + ok. + compile(Config, Prog, Module, CompileOpts) -> Source = lists:concat([Module, ".erl"]), PrivDir = ?config(priv_dir,Config), diff --git a/lib/erl_docgen/src/docgen_edoc_xml_cb.erl b/lib/erl_docgen/src/docgen_edoc_xml_cb.erl index 4f3af1f767..13ff0a139d 100644 --- a/lib/erl_docgen/src/docgen_edoc_xml_cb.erl +++ b/lib/erl_docgen/src/docgen_edoc_xml_cb.erl @@ -111,7 +111,16 @@ root_attributes(Element, Opts) -> Enc -> Enc end, - [#xmlAttribute{name=encoding, value=Encoding}]. + [#xmlAttribute{name=encoding, value=reformat_encoding(Encoding)}]. + +%% epp:default_encoding/0 returns 'utf8' +reformat_encoding(utf8) -> "UTF-8"; +reformat_encoding(List) when is_list(List) -> + case string:to_lower(List) of + "utf8" -> "UTF-8"; + _ -> List + end; +reformat_encoding(Other) -> Other. layout_chapter(#xmlElement{name=overview, content=Es}) -> Title = get_text(title, Es), diff --git a/lib/erl_interface/doc/src/book.xml b/lib/erl_interface/doc/src/book.xml index c9194d96ff..94bfef7455 100644 --- a/lib/erl_interface/doc/src/book.xml +++ b/lib/erl_interface/doc/src/book.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,19 +19,19 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> - <title>Erlang Interface</title> + <title>Erl_Interface</title> <prepared>Gordon Beaton</prepared> <docno></docno> <date>1998-11-30</date> <rev>1.2</rev> - <file>book.sgml</file> + <file>book.xml</file> </header> <insidecover> </insidecover> - <pagetext>Erlang Interface</pagetext> + <pagetext>Erl_Interface</pagetext> <preamble> <contents level="2"></contents> </preamble> @@ -47,4 +47,3 @@ <listofterms></listofterms> <index></index> </book> - diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml index 1177954eb9..ddfb4d88a8 100644 --- a/lib/erl_interface/doc/src/ei.xml +++ b/lib/erl_interface/doc/src/ei.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -30,361 +30,508 @@ <checked></checked> <date>2000-11-27</date> <rev>PA1</rev> - <file>ei.sgml</file> + <file>ei.xml</file> </header> <lib>ei</lib> - <libsummary>routines for handling the erlang binary term format</libsummary> + <libsummary>Routines for handling the Erlang binary term format.</libsummary> <description> - <p>The library <c><![CDATA[ei]]></c> contains macros and functions to encode - and decode the erlang binary term format.</p> - <p>With <c><![CDATA[ei]]></c>, you can convert atoms, lists, numbers and + <p>The library <c>ei</c> contains macros and functions to encode + and decode the Erlang binary term format.</p> + + <p><c>ei</c> allows you to convert atoms, lists, numbers, and binaries to and from the binary format. This is useful when - writing port programs and drivers. <c><![CDATA[ei]]></c> uses a given - buffer, and no dynamic memory (with the exception of - <c><![CDATA[ei_decode_fun()]]></c>), and is often quite fast.</p> - <p>It also handles C-nodes, C-programs that talks erlang - distribution with erlang nodes (or other C-nodes) using the - erlang distribution format. The difference between <c><![CDATA[ei]]></c> and - <c><![CDATA[erl_interface]]></c> is that <c><![CDATA[ei]]></c> uses the binary format - directly when sending and receiving terms. It is also thread - safe, and using threads, one process can handle multiple - C-nodes. The <c><![CDATA[erl_interface]]></c> library is built on top of - <c><![CDATA[ei]]></c>, but of legacy reasons, it doesn't allow for multiple - C-nodes. In general, <c><![CDATA[ei]]></c> is the preferred way of doing - C-nodes.</p> - <p>The decode and encode functions use a buffer an index into the + writing port programs and drivers. <c>ei</c> uses a given + buffer, no dynamic memory (except + <c>ei_decode_fun()</c>) and is often quite fast.</p> + + <p><c>ei</c> also handles C-nodes, C-programs that talks Erlang + distribution with Erlang nodes (or other C-nodes) using the + Erlang distribution format. The difference between <c>ei</c> + and <c>erl_interface</c> is that <c>ei</c> uses + the binary format directly when sending and receiving terms. It is also + thread safe, and using threads, one process can handle multiple + C-nodes. The <c>erl_interface</c> library is built on top of + <c>ei</c>, but of legacy reasons, it does not allow for + multiple C-nodes. In general, <c>ei</c> is the preferred way + of doing C-nodes.</p> + + <p>The decode and encode functions use a buffer and an index into the buffer, which points at the point where to encode and decode. The index is updated to point right after the term encoded/decoded. No checking is done whether the term fits in the buffer or not. If encoding goes outside the buffer, the - program may crash.</p> - <p>All functions takes two parameter, <c><![CDATA[buf]]></c> is a pointer to - the buffer where the binary data is / will be, <c><![CDATA[index]]></c> is a - pointer to an index into the buffer. This parameter will be - incremented with the size of the term decoded / encoded. The - data is thus at <c><![CDATA[buf[*index]]]></c> when an <c><![CDATA[ei]]></c> function is - called.</p> - <p>The encode functions all assumes that the <c><![CDATA[buf]]></c> and - <c><![CDATA[index]]></c> parameters points to a buffer big enough for the - data. To get the size of an encoded term, without encoding it, - pass <c><![CDATA[NULL]]></c> instead of a buffer pointer. The <c><![CDATA[index]]></c> - parameter will be incremented, but nothing will be encoded. This - is the way in <c><![CDATA[ei]]></c> to "preflight" term encoding.</p> - <p>There are also encode-functions that uses a dynamic buffer. It + program can crash.</p> + + <p>All functions take two parameters:</p> + + <list type="bulleted"> + <item><p><c>buf</c> is a pointer to + the buffer where the binary data is or will be.</p> + </item> + <item><p><c>index</c> is a pointer to an index into the + buffer. This parameter is incremented with the size of the term + decoded/encoded.</p> + </item> + </list> + + <p>The data is thus at <c>buf[*index]</c> when an + <c>ei</c> function is called.</p> + + <p>All encode functions assume that the <c>buf</c> and + <c>index</c> parameters point to a buffer large enough for + the data. To get the size of an encoded term, without encoding it, + pass <c>NULL</c> instead of a buffer pointer. Parameter + <c>index</c> is incremented, but nothing will be encoded. This + is the way in <c>ei</c> to "preflight" term encoding.</p> + + <p>There are also encode functions that use a dynamic buffer. It is often more convenient to use these to encode data. All encode - functions comes in two versions: those starting with <c><![CDATA[ei_x]]></c>, - uses a dynamic buffer.</p> - <p>All functions return <c><![CDATA[0]]></c> if successful, and <c><![CDATA[-1]]></c> if - not. (For instance, if a term is not of the expected type, or - the data to decode is not a valid erlang term.)</p> - <p>Some of the decode-functions needs a preallocated buffer. This - buffer must be allocated big enough, and for non compound types - the <c><![CDATA[ei_get_type()]]></c> - function returns the size required (note that for strings an - extra byte is needed for the 0 string terminator).</p> + functions comes in two versions; those starting with + <c>ei_x</c> use a dynamic buffer.</p> + + <p>All functions return <c>0</c> if successful, otherwise + <c>-1</c> (for example, if a term is not of the expected + type, or the data to decode is an invalid Erlang term).</p> + + <p>Some of the decode functions need a pre-allocated buffer. This + buffer must be allocated large enough, and for non-compound types + the <c>ei_get_type()</c> + function returns the size required (notice that for strings an + extra byte is needed for the <c>NULL</c>-terminator).</p> </description> - <section> - <title>DATA TYPES</title> + <section> + <title>Data Types</title> <taglist> <tag><marker id="erlang_char_encoding"/>erlang_char_encoding</tag> <item> - <p/> <code type="none"> typedef enum { ERLANG_ASCII = 1, ERLANG_LATIN1 = 2, ERLANG_UTF8 = 4 -}erlang_char_encoding; -</code> - <p>The character encodings used for atoms. <c>ERLANG_ASCII</c> represents 7-bit ASCII. - Latin1 and UTF8 are different extensions of 7-bit ASCII. All 7-bit ASCII characters - are valid Latin1 and UTF8 characters. ASCII and Latin1 both represent each character - by one byte. A UTF8 character can consist of one to four bytes. Note that these - constants are bit-flags and can be combined with bitwise-or.</p> +} erlang_char_encoding;</code> + <p>The character encodings used for atoms. <c>ERLANG_ASCII</c> + represents 7-bit ASCII. Latin-1 and UTF-8 are different extensions + of 7-bit ASCII. All 7-bit ASCII characters are valid Latin-1 and + UTF-8 characters. ASCII and Latin-1 both represent each character + by one byte. An UTF-8 character can consist of 1-4 bytes. + Notice that these constants are bit-flags and can be combined with + bitwise OR.</p> </item> </taglist> </section> + <funcs> + <func> + <name><ret>int</ret><nametext>ei_decode_atom(const char *buf, int *index, char *p)</nametext></name> + <fsummary>Decode an atom.</fsummary> + <desc> + <p>Decodes an atom from the binary format. The <c>NULL</c>-terminated + name of the atom is placed at <c>p</c>. At most + <c>MAXATOMLEN</c> bytes can be placed in the buffer.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_decode_atom_as(const char *buf, int *index, char *p, int plen, erlang_char_encoding want, erlang_char_encoding* was, erlang_char_encoding* result)</nametext></name> + <fsummary>Decode an atom.</fsummary> + <desc> + <p>Decodes an atom from the binary format. The <c>NULL</c>-terminated + name of the atom is placed in buffer at <c>p</c> of length <c>plen</c> + bytes.</p> + <p>The wanted string encoding is specified by + <seealso marker="#erlang_char_encoding"><c>want</c></seealso>. + The original encoding used in the binary format (Latin-1 or UTF-8) can + be obtained from <c>*was</c>. The encoding of the resulting string + (7-bit ASCII, Latin-1, or UTF-8) can be obtained from <c>*result</c>. + Both <c>was</c> and <c>result</c> can be <c>NULL</c>. <c>*result</c> + can differ from <c>want</c> if <c>want</c> is a bitwise OR'd + combination like <c>ERLANG_LATIN1|ERLANG_UTF8</c> or if + <c>*result</c> turns out to be pure 7-bit ASCII + (compatible with both Latin-1 and UTF-8).</p> + <p>This function fails if the atom is too long for the buffer + or if it cannot be represented with encoding <c>want</c>.</p> + <p>This function was introduced in Erlang/OTP R16 as part of a first + step to support UTF-8 atoms.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_decode_bignum(const char *buf, int *index, mpz_t obj)</nametext></name> + <fsummary>Decode a GMP arbitrary precision integer.</fsummary> + <desc> + <p>Decodes an integer in the binary format to a GMP + <c>mpz_t</c> integer. To use this function, the <c>ei</c> + library must be configured and compiled to use the GMP library.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_decode_binary(const char *buf, int *index, void *p, long *len)</nametext></name> + <fsummary>Decode a binary.</fsummary> + <desc> + <p>Decodes a binary from the binary format. Parameter + <c>len</c> is set to the actual size of the + binary. Notice that <c>ei_decode_binary()</c> assumes that + there is enough room for the binary. The size required can be + fetched by <c>ei_get_type()</c>.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_decode_boolean(const char *buf, int *index, int *p)</nametext></name> + <fsummary>Decode a boolean.</fsummary> + <desc> + <p>Decodes a boolean value from the binary format. + A boolean is actually an atom, <c>true</c> decodes 1 + and <c>false</c> decodes 0.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_decode_char(const char *buf, int *index, char *p)</nametext></name> + <fsummary>Decode an 8-bit integer between 0-255.</fsummary> + <desc> + <p>Decodes a char (8-bit) integer between 0-255 from the binary format. + For historical reasons the returned integer is of + type <c>char</c>. Your C code is to consider the + returned value to be of type <c>unsigned char</c> even if + the C compilers and system can define <c>char</c> to be + signed.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_decode_double(const char *buf, int *index, double *p)</nametext></name> + <fsummary>Decode a double.</fsummary> + <desc> + <p>Decodes a double-precision (64-bit) floating + point number from the binary format.</p> + </desc> + </func> + <func> - <name><ret>void</ret><nametext>ei_set_compat_rel(release_number)</nametext></name> - <fsummary>Set the ei library in compatibility mode</fsummary> - <type> - <v>unsigned release_number;</v> - </type> + <name><ret>int</ret><nametext>ei_decode_ei_term(const char* buf, int* index, ei_term* term)</nametext></name> + <fsummary>Decode a term, without previous knowledge of type.</fsummary> + <desc> + <p>Decodes any term, or at least tries to. If the term + pointed at by <c>*index</c> in <c>buf</c> fits + in the <c>term</c> union, it is decoded, and the + appropriate field in <c>term->value</c> is set, and + <c>*index</c> is incremented by the term size.</p> + <p>The function returns <c>1</c> on successful decoding, <c>-1</c> on + error, and <c>0</c> if the term seems alright, but does not fit in the + <c>term</c> structure. If <c>1</c> is returned, the + <c>index</c> is incremented, and <c>term</c> + contains the decoded term.</p> + <p>The <c>term</c> structure contains the arity for a tuple + or list, size for a binary, string, or atom. It contains + a term if it is any of the following: integer, float, atom, + pid, port, or ref.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_decode_fun(const char *buf, int *index, erlang_fun *p)</nametext></name> + <name><ret>void</ret><nametext>free_fun(erlang_fun* f)</nametext></name> + <fsummary>Decode a fun.</fsummary> <desc> - <marker id="ei_set_compat_rel"></marker> - <p>By default, the <c><![CDATA[ei]]></c> library is only guaranteed - to be compatible with other Erlang/OTP components from the same - release as the <c><![CDATA[ei]]></c> library itself. For example, <c><![CDATA[ei]]></c> from - the OTP R10 release is not compatible with an Erlang emulator - from the OTP R9 release by default.</p> - <p>A call to <c><![CDATA[ei_set_compat_rel(release_number)]]></c> sets the - <c><![CDATA[ei]]></c> library in compatibility mode of release - <c><![CDATA[release_number]]></c>. Valid range of <c><![CDATA[release_number]]></c> - is [7, current release]. This makes it possible to - communicate with Erlang/OTP components from earlier releases.</p> - <note> - <p>If this function is called, it may only be called once - and must be called before any other functions in the <c><![CDATA[ei]]></c> - library is called.</p> - </note> - <warning> - <p>You may run into trouble if this feature is used - carelessly. Always make sure that all communicating - components are either from the same Erlang/OTP release, or - from release X and release Y where all components - from release Y are in compatibility mode of release X.</p> - </warning> + <p>Decodes a fun from the binary format. Parameter + <c>p</c> is to be <c>NULL</c> or point to an + <c>erlang_fun</c> structure. This is the only decode + function that allocates memory. When the <c>erlang_fun</c> + is no longer needed, it is to be freed with + <c>free_fun</c>. (This has to do with the arbitrary size + of the environment for a fun.)</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_version(char *buf, int *index)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_version(ei_x_buff* x)</nametext></name> - <fsummary>Encode version</fsummary> + <name><ret>int</ret><nametext>ei_decode_list_header(const char *buf, int *index, int *arity)</nametext></name> + <fsummary>Decode a list.</fsummary> <desc> - <p>Encodes a version magic number for the binary format. Must - be the first token in a binary term.</p> + <p>Decodes a list header from the binary + format. The number of elements is returned in + <c>arity</c>. The <c>arity+1</c> elements + follow (the last one is the tail of the list, normally an empty list). + If <c>arity</c> is <c>0</c>, it is an empty + list.</p> + <p>Notice that lists are encoded as strings if they consist + entirely of integers in the range 0..255. This function do + not decode such strings, use <c>ei_decode_string()</c> + instead.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_long(char *buf, int *index, long p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_long(ei_x_buff* x, long p)</nametext></name> - <fsummary>Encode integer</fsummary> + <name><ret>int</ret><nametext>ei_decode_long(const char *buf, int *index, long *p)</nametext></name> + <fsummary>Decode integer.</fsummary> <desc> - <p>Encodes a long integer in the binary format. - Note that if the code is 64 bits the function ei_encode_long() is - exactly the same as ei_encode_longlong().</p> + <p>Decodes a long integer from the binary format. + If the code is 64 bits, the function <c>ei_decode_long()</c> is + the same as <c>ei_decode_longlong()</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_ulong(char *buf, int *index, unsigned long p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_ulong(ei_x_buff* x, unsigned long p)</nametext></name> - <fsummary>Encode unsigned integer</fsummary> + <name><ret>int</ret><nametext>ei_decode_longlong(const char *buf, int *index, long long *p)</nametext></name> + <fsummary>Decode integer.</fsummary> <desc> - <p>Encodes an unsigned long integer in the binary format. - Note that if the code is 64 bits the function ei_encode_ulong() is - exactly the same as ei_encode_ulonglong().</p> + <p>Decodes a GCC <c>long long</c> or Visual C++ + <c>__int64</c> + (64-bit) integer from the binary format. This + function is missing in the VxWorks port.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_longlong(char *buf, int *index, long long p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_longlong(ei_x_buff* x, long long p)</nametext></name> - <fsummary>Encode integer</fsummary> + <name><ret>int</ret><nametext>ei_decode_map_header(const char *buf, int *index, int *arity)</nametext></name> + <fsummary>Decode a map.</fsummary> <desc> - <p>Encodes a GCC <c><![CDATA[long long]]></c> or Visual C++ <c><![CDATA[__int64]]></c> (64 bit) - integer in the binary format. Note that this function is missing - in the VxWorks port.</p> + <p>Decodes a map header from the binary + format. The number of key-value pairs is returned in + <c>*arity</c>. Keys and values follow in this order: + <c>K1, V1, K2, V2, ..., Kn, Vn</c>. This makes a total of + <c>arity*2</c> terms. If <c>arity</c> is zero, it is an empty map. + A correctly encoded map does not have duplicate keys.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_ulonglong(char *buf, int *index, unsigned long long p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_ulonglong(ei_x_buff* x, unsigned long long p)</nametext></name> - <fsummary>Encode unsigned integer</fsummary> + <name><ret>int</ret><nametext>ei_decode_pid(const char *buf, int *index, erlang_pid *p)</nametext></name> + <fsummary>Decode a <c>pid</c>.</fsummary> <desc> - <p>Encodes a GCC <c><![CDATA[unsigned long long]]></c> or Visual C++ <c><![CDATA[unsigned __int64]]></c> (64 bit) integer in the binary format. Note that - this function is missing in the VxWorks port.</p> + <p>Decodes a process identifier (pid) from the binary format.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_bignum(char *buf, int *index, mpz_t obj)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_bignum(ei_x_buff *x, mpz_t obj)</nametext></name> - <fsummary>Encode an arbitrary precision integer</fsummary> + <name><ret>int</ret><nametext>ei_decode_port(const char *buf, int *index, erlang_port *p)</nametext></name> + <fsummary>Decode a port.</fsummary> <desc> - <p>Encodes a GMP <c><![CDATA[mpz_t]]></c> integer to binary format. - To use this function the ei library needs to be configured and compiled - to use the GMP library. </p> + <p>Decodes a port identifier from the binary format.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_double(char *buf, int *index, double p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_double(ei_x_buff* x, double p)</nametext></name> - <fsummary>Encode a double float</fsummary> + <name><ret>int</ret><nametext>ei_decode_ref(const char *buf, int *index, erlang_ref *p)</nametext></name> + <fsummary>Decode a reference.</fsummary> <desc> - <p>Encodes a double-precision (64 bit) floating point number in - the binary format.</p> - <p> - The function returns <c><![CDATA[-1]]></c> if the floating point number is not finite. - </p> + <p>Decodes a reference from the binary format.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_boolean(char *buf, int *index, int p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_boolean(ei_x_buff* x, int p)</nametext></name> - <fsummary>Encode a boolean</fsummary> + <name><ret>int</ret><nametext>ei_decode_string(const char *buf, int *index, char *p)</nametext></name> + <fsummary>Decode a string.</fsummary> <desc> - <p>Encodes a boolean value, as the atom <c><![CDATA[true]]></c> if p is not - zero or <c><![CDATA[false]]></c> if p is zero.</p> + <p>Decodes a string from the binary format. A + string in Erlang is a list of integers between 0 and + 255. Notice that as the string is just a list, sometimes + lists are encoded as strings by <c>term_to_binary/1</c>, + even if it was not intended.</p> + <p>The string is copied to <c>p</c>, and enough space must + be allocated. The returned string is <c>NULL</c>-terminated, so you + must add an extra byte to the memory requirement.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_char(char *buf, int *index, char p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_char(ei_x_buff* x, char p)</nametext></name> - <fsummary>Encode an 8-bit integer between 0-255</fsummary> + <name><ret>int</ret><nametext>ei_decode_term(const char *buf, int *index, void *t)</nametext></name> + <fsummary>Decode a <c>ETERM</c>.</fsummary> + <desc> + <p>Decodes a term from the binary format. The term + is return in <c>t</c> as a <c>ETERM*</c>, so + <c>t</c> is actually an <c>ETERM**</c> (see + <seealso marker="erl_eterm"><c>erl_eterm</c></seealso>). + The term is later to be deallocated.</p> + <p>Notice that this function is located in the <c>Erl_Interface</c> + library.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_decode_trace(const char *buf, int *index, erlang_trace *p)</nametext></name> + <fsummary>Decode a trace token.</fsummary> <desc> - <p>Encodes a char (8-bit) as an integer between 0-255 in the binary format. - Note that for historical reasons the integer argument is of - type <c><![CDATA[char]]></c>. Your C code should consider the - given argument to be of type <c><![CDATA[unsigned char]]></c> even if - the C compilers and system may define <c><![CDATA[char]]></c> to be - signed.</p> + <p>Decodes an Erlang trace token from the binary format.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_string(char *buf, int *index, const char *p)</nametext></name> - <name><ret>int</ret><nametext>ei_encode_string_len(char *buf, int *index, const char *p, int len)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_string(ei_x_buff* x, const char *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_string_len(ei_x_buff* x, const char* s, int len)</nametext></name> - <fsummary>Encode a string</fsummary> + <name><ret>int</ret><nametext>ei_decode_tuple_header(const char *buf, int *index, int *arity)</nametext></name> + <fsummary>Decode a tuple.</fsummary> <desc> - <p>Encodes a string in the binary format. (A string in erlang - is a list, but is encoded as a character array in the binary - format.) The string should be zero-terminated, except for - the <c><![CDATA[ei_x_encode_string_len()]]></c> function.</p> + <p>Decodes a tuple header, the number of elements + is returned in <c>arity</c>. The tuple elements follow + in order in the buffer.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_decode_ulong(const char *buf, int *index, unsigned long *p)</nametext></name> + <fsummary>Decode unsigned integer.</fsummary> + <desc> + <p>Decodes an unsigned long integer from the binary format. + If the code is 64 bits, the function <c>ei_decode_ulong()</c> is + the same as <c>ei_decode_ulonglong()</c>.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_decode_ulonglong(const char *buf, int *index, unsigned long long *p)</nametext></name> + <fsummary>Decode unsigned integer.</fsummary> + <desc> + <p>Decodes a GCC <c>unsigned long long</c> or Visual C++ + <c>unsigned __int64</c> (64-bit) integer from the binary + format. This function is missing in the VxWorks port.</p> </desc> </func> + + <func> + <name><ret>int</ret><nametext>ei_decode_version(const char *buf, int *index, int *version)</nametext></name> + <fsummary>Decode an empty list (<c>nil</c>).</fsummary> + <desc> + <p>Decodes the version magic number for the + Erlang binary term format. It must be the first token in a + binary term.</p> + </desc> + </func> + <func> <name><ret>int</ret><nametext>ei_encode_atom(char *buf, int *index, const char *p)</nametext></name> <name><ret>int</ret><nametext>ei_encode_atom_len(char *buf, int *index, const char *p, int len)</nametext></name> <name><ret>int</ret><nametext>ei_x_encode_atom(ei_x_buff* x, const char *p)</nametext></name> <name><ret>int</ret><nametext>ei_x_encode_atom_len(ei_x_buff* x, const char *p, int len)</nametext></name> - <fsummary>Encode an atom</fsummary> + <fsummary>Encode an atom.</fsummary> <desc> - <p>Encodes an atom in the binary format. The <c><![CDATA[p]]></c> parameter - is the name of the atom in latin1 encoding. Only upto <c>MAXATOMLEN-1</c> bytes - are encoded. The name should be zero-terminated, except for - the <c><![CDATA[ei_x_encode_atom_len()]]></c> function.</p> + <p>Encodes an atom in the binary format. Parameter <c>p</c> + is the name of the atom in Latin-1 encoding. Only up to + <c>MAXATOMLEN-1</c> bytes + are encoded. The name is to be <c>NULL</c>-terminated, except for + the <c>ei_x_encode_atom_len()</c> function.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_encode_atom_as(char *buf, int *index, const char *p, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> <name><ret>int</ret><nametext>ei_encode_atom_len_as(char *buf, int *index, const char *p, int len, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> <name><ret>int</ret><nametext>ei_x_encode_atom_as(ei_x_buff* x, const char *p, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> <name><ret>int</ret><nametext>ei_x_encode_atom_len_as(ei_x_buff* x, const char *p, int len, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> - <fsummary>Encode an atom</fsummary> + <fsummary>Encode an atom.</fsummary> <desc> <p>Encodes an atom in the binary format with character encoding - <seealso marker="#erlang_char_encoding"><c>to_enc</c></seealso> (latin1 or utf8). - The <c>p</c> parameter is the name of the atom with character encoding - <seealso marker="#erlang_char_encoding"><c>from_enc</c></seealso> (ascii, latin1 or utf8). - The name must either be zero-terminated or a function variant with a <c>len</c> - parameter must be used. If <c>to_enc</c> is set to the bitwise-or'd combination - <c>(ERLANG_LATIN1|ERLANG_UTF8)</c>, utf8 encoding is only used if the atom string - can not be represented in latin1 encoding.</p> - <p>The encoding will fail if <c>p</c> is not a valid string in encoding <c>from_enc</c>, - if the string is too long or if it can not be represented with character encoding <c>to_enc</c>.</p> - <p>These functions were introduced in R16 release of Erlang/OTP as part of a first step - to support UTF8 atoms. Atoms encoded with <c>ERLANG_UTF8</c> - can not be decoded by earlier releases than R16.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_encode_binary(char *buf, int *index, const void *p, long len)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_binary(ei_x_buff* x, const void *p, long len)</nametext></name> - <fsummary>Encode a binary</fsummary> - <desc> - <p>Encodes a binary in the binary format. The data is at - <c><![CDATA[p]]></c>, of <c><![CDATA[len]]></c> bytes length.</p> + <seealso marker="#erlang_char_encoding"><c>to_enc</c></seealso> + (Latin-1 or UTF-8). Parameter <c>p</c> is the name of the atom with + character encoding + <seealso marker="#erlang_char_encoding"><c>from_enc</c></seealso> + (ASCII, Latin-1, or UTF-8). The name must either be <c>NULL</c>-terminated or + a function variant with a <c>len</c> parameter must be used. + If <c>to_enc</c> is set to the bitwise OR'd combination + <c>(ERLANG_LATIN1|ERLANG_UTF8)</c>, UTF-8 encoding is only used if the + atom string cannot be represented in Latin-1 encoding.</p> + <p>The encoding fails if <c>p</c> is an invalid string in encoding + <c>from_enc</c>, if the string is too long, or if it cannot be + represented with character encoding <c>to_enc</c>.</p> + <p>These functions were introduced in Erlang/OTP R16 as part of a first + step to support UTF-8 atoms. Atoms encoded with <c>ERLANG_UTF8</c> + cannot be decoded by earlier releases than R16.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_pid(char *buf, int *index, const erlang_pid *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_pid(ei_x_buff* x, const erlang_pid *p)</nametext></name> - <fsummary>Encode a pid</fsummary> + <name><ret>int</ret><nametext>ei_encode_bignum(char *buf, int *index, mpz_t obj)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_bignum(ei_x_buff *x, mpz_t obj)</nametext></name> + <fsummary>Encode an arbitrary precision integer.</fsummary> <desc> - <p>Encodes an erlang process identifier, pid, in the binary - format. The <c><![CDATA[p]]></c> parameter points to an - <c><![CDATA[erlang_pid]]></c> structure (which should have been obtained - earlier with <c><![CDATA[ei_decode_pid()]]></c>).</p> + <p>Encodes a GMP <c>mpz_t</c> integer to binary format. + To use this function, the <c>ei</c> library must be configured and + compiled to use the GMP library.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_fun(char *buf, int *index, const erlang_fun *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun)</nametext></name> - <fsummary>Encode a fun</fsummary> + <name><ret>int</ret><nametext>ei_encode_binary(char *buf, int *index, const void *p, long len)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_binary(ei_x_buff* x, const void *p, long len)</nametext></name> + <fsummary>Encode a binary.</fsummary> <desc> - <p>Encodes a fun in the binary format. The <c><![CDATA[p]]></c> parameter - points to an <c><![CDATA[erlang_fun]]></c> structure. The - <c><![CDATA[erlang_fun]]></c> is not freed automatically, the - <c><![CDATA[free_fun]]></c> should be called if the fun is not needed - after encoding.</p> + <p>Encodes a binary in the binary format. The data is at + <c>p</c>, of <c>len</c> bytes length.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_port(char *buf, int *index, const erlang_port *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_port(ei_x_buff* x, const erlang_port *p)</nametext></name> - <fsummary>Encodes a port</fsummary> + <name><ret>int</ret><nametext>ei_encode_boolean(char *buf, int *index, int p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_boolean(ei_x_buff* x, int p)</nametext></name> + <fsummary>Encode a boolean.</fsummary> <desc> - <p>Encodes an erlang port in the binary format. The <c><![CDATA[p]]></c> - parameter points to a <c><![CDATA[erlang_port]]></c> structure (which - should have been obtained earlier with - <c><![CDATA[ei_decode_port()]]></c>.</p> + <p>Encodes a boolean value as the atom <c>true</c> if + <c>p</c> is not zero, or <c>false</c> if <c>p</c> is + zero.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_ref(char *buf, int *index, const erlang_ref *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_ref(ei_x_buff* x, const erlang_ref *p)</nametext></name> - <fsummary>Encodes a ref</fsummary> + <name><ret>int</ret><nametext>ei_encode_char(char *buf, int *index, char p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_char(ei_x_buff* x, char p)</nametext></name> + <fsummary>Encode an 8-bit integer between 0-255.</fsummary> <desc> - <p>Encodes an erlang reference in the binary format. The - <c><![CDATA[p]]></c> parameter points to a <c><![CDATA[erlang_ref]]></c> structure - (which should have been obtained earlier with - <c><![CDATA[ei_decode_ref()]]></c>.</p> + <p>Encodes a char (8-bit) as an integer between 0-255 in the binary + format. For historical reasons the integer argument is of + type <c>char</c>. Your C code is to consider the specified + argument to be of type <c>unsigned char</c> even if + the C compilers and system may define <c>char</c> to be + signed.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_term(char *buf, int *index, void *t)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_term(ei_x_buff* x, void *t)</nametext></name> - <fsummary>Encode an <c><![CDATA[erl_interface]]></c>term</fsummary> + <name><ret>int</ret><nametext>ei_encode_double(char *buf, int *index, double p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_double(ei_x_buff* x, double p)</nametext></name> + <fsummary>Encode a double float.</fsummary> <desc> - <p>This function encodes an <c><![CDATA[ETERM]]></c>, as obtained from - <c><![CDATA[erl_interface]]></c>. The <c><![CDATA[t]]></c> parameter is actually an - <c><![CDATA[ETERM]]></c> pointer. This function doesn't free the - <c><![CDATA[ETERM]]></c>.</p> + <p>Encodes a double-precision (64-bit) floating point number in + the binary format.</p> + <p>Returns <c>-1</c> if the floating point + number is not finite.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_trace(char *buf, int *index, const erlang_trace *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_trace(ei_x_buff* x, const erlang_trace *p)</nametext></name> - <fsummary>Encode a trace token</fsummary> + <name><ret>int</ret><nametext>ei_encode_empty_list(char* buf, int* index)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_empty_list(ei_x_buff* x)</nametext></name> + <fsummary>Encode an empty list (<c>nil</c>).</fsummary> <desc> - <p>This function encodes an erlang trace token in the binary - format. The <c><![CDATA[p]]></c> parameter points to a - <c><![CDATA[erlang_trace]]></c> structure (which should have been - obtained earlier with <c><![CDATA[ei_decode_trace()]]></c>.</p> + <p>Encodes an empty list. It is often used at the tail of a list.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_tuple_header(char *buf, int *index, int arity)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_tuple_header(ei_x_buff* x, int arity)</nametext></name> - <fsummary>Encode a tuple</fsummary> + <name><ret>int</ret><nametext>ei_encode_fun(char *buf, int *index, const erlang_fun *p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun)</nametext></name> + <fsummary>Encode a fun.</fsummary> <desc> - <p>This function encodes a tuple header, with a specified - arity. The next <c><![CDATA[arity]]></c> terms encoded will be the - elements of the tuple. Tuples and lists are encoded - recursively, so that a tuple may contain another tuple or - list.</p> - <p>E.g. to encode the tuple <c><![CDATA[{a, {b, {}}}]]></c>:</p> - <pre> -ei_encode_tuple_header(buf, &i, 2); -ei_encode_atom(buf, &i, "a"); -ei_encode_tuple_header(buf, &i, 2); -ei_encode_atom(buf, &i, "b"); -ei_encode_tuple_header(buf, &i, 0); - </pre> + <p>Encodes a fun in the binary format. Parameter <c>p</c> + points to an <c>erlang_fun</c> structure. The + <c>erlang_fun</c> is not freed automatically, the + <c>free_fun</c> is to be called if the fun is not needed + after encoding.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_encode_list_header(char *buf, int *index, int arity)</nametext></name> <name><ret>int</ret><nametext>ei_x_encode_list_header(ei_x_buff* x, int arity)</nametext></name> - <fsummary>Encode a list</fsummary> + <fsummary>Encode a list.</fsummary> <desc> - <p>This function encodes a list header, with a specified - arity. The next <c><![CDATA[arity+1]]></c> terms are the elements - (actually its <c><![CDATA[arity]]></c> cons cells) and the tail of the + <p>Encodes a list header, with a specified + arity. The next <c>arity+1</c> terms are the elements + (actually its <c>arity</c> cons cells) and the tail of the list. Lists and tuples are encoded recursively, so that a - list may contain another list or tuple.</p> - <p>E.g. to encode the list <c><![CDATA[[c, d, [e | f]]]]></c>:</p> + list can contain another list or tuple.</p> + <p>For example, to encode the list + <c>[c, d, [e | f]]</c>:</p> <pre> ei_encode_list_header(buf, &i, 3); ei_encode_atom(buf, &i, "c"); @@ -392,14 +539,13 @@ ei_encode_atom(buf, &i, "d"); ei_encode_list_header(buf, &i, 1); ei_encode_atom(buf, &i, "e"); ei_encode_atom(buf, &i, "f"); -ei_encode_empty_list(buf, &i); - </pre> +ei_encode_empty_list(buf, &i);</pre> <note> <p>It may seem that there is no way to create a list without knowing the number of elements in advance. But indeed - there is a way. Note that the list <c><![CDATA[[a, b, c]]]></c> can be - written as <c><![CDATA[[a | [b | [c]]]]]></c>. Using this, a list can - be written as conses.</p> + there is a way. Notice that the list <c>[a, b, c]</c> + can be written as <c>[a | [b | [c]]]</c>. + Using this, a list can be written as conses.</p> </note> <p>To encode a list, without knowing the arity in advance:</p> <pre> @@ -407,425 +553,350 @@ while (something()) { ei_x_encode_list_header(&x, 1); ei_x_encode_ulong(&x, i); /* just an example */ } -ei_x_encode_empty_list(&x); - </pre> +ei_x_encode_empty_list(&x);</pre> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_encode_empty_list(char* buf, int* index)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_empty_list(ei_x_buff* x)</nametext></name> - <fsummary>Encode an empty list (<c><![CDATA[nil]]></c>)</fsummary> + <name><ret>int</ret><nametext>ei_encode_long(char *buf, int *index, long p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_long(ei_x_buff* x, long p)</nametext></name> + <fsummary>Encode integer.</fsummary> <desc> - <p>This function encodes an empty list. It's often used at the - tail of a list.</p> + <p>Encodes a long integer in the binary format. + If the code is 64 bits, the function <c>ei_encode_long()</c> is + the same as <c>ei_encode_longlong()</c>.</p> </desc> </func> + + <func> + <name><ret>int</ret><nametext>ei_encode_longlong(char *buf, int *index, long long p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_longlong(ei_x_buff* x, long long p)</nametext></name> + <fsummary>Encode integer.</fsummary> + <desc> + <p>Encodes a GCC <c>long long</c> or Visual C++ + <c>__int64</c> (64-bit) integer in the binary format. + This function is missing in the VxWorks port.</p> + </desc> + </func> + <func> <name><ret>int</ret><nametext>ei_encode_map_header(char *buf, int *index, int arity)</nametext></name> <name><ret>int</ret><nametext>ei_x_encode_map_header(ei_x_buff* x, int arity)</nametext></name> - <fsummary>Encode a map</fsummary> + <fsummary>Encode a map.</fsummary> <desc> - <p>This function encodes a map header, with a specified arity. The next + <p>Encodes a map header, with a specified arity. The next <c>arity*2</c> terms encoded will be the keys and values of the map encoded in the following order: <c>K1, V1, K2, V2, ..., Kn, Vn</c>. </p> - <p>E.g. to encode the map <c>#{a => "Apple", b => "Banana"}</c>:</p> + <p>For example, to encode the map <c>#{a => "Apple", b => + "Banana"}</c>:</p> <pre> ei_x_encode_map_header(&x, 2); ei_x_encode_atom(&x, "a"); ei_x_encode_string(&x, "Apple"); ei_x_encode_atom(&x, "b"); -ei_x_encode_string(&x, "Banana"); - </pre> - <p>A correctly encoded map can not have duplicate keys.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_get_type(const char *buf, const int *index, int *type, int *size)</nametext></name> - <fsummary>Fetch the type and size of an encoded term</fsummary> - <desc> - <p>This function returns the type in <c><![CDATA[type]]></c> and size in - <c><![CDATA[size]]></c> of the encoded term. - For strings and atoms, size - is the number of characters <em>not</em> including the - terminating 0. For binaries, <c><![CDATA[size]]></c> is the number of - bytes. For lists and tuples, <c><![CDATA[size]]></c> is the arity of the - object. For other types, <c><![CDATA[size]]></c> is 0. In all cases, - <c><![CDATA[index]]></c> is left unchanged.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_version(const char *buf, int *index, int *version)</nametext></name> - <fsummary>Encode an empty list (<c><![CDATA[nil]]></c>)</fsummary> - <desc> - <p>This function decodes the version magic number for the - erlang binary term format. It must be the first token in a - binary term.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_long(const char *buf, int *index, long *p)</nametext></name> - <fsummary>Decode integer</fsummary> - <desc> - <p>This function decodes a long integer from the binary format. - Note that if the code is 64 bits the function ei_decode_long() is - exactly the same as ei_decode_longlong().</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_ulong(const char *buf, int *index, unsigned long *p)</nametext></name> - <fsummary>Decode unsigned integer</fsummary> - <desc> - <p>This function decodes an unsigned long integer from - the binary format. - Note that if the code is 64 bits the function ei_decode_ulong() is - exactly the same as ei_decode_ulonglong().</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_longlong(const char *buf, int *index, long long *p)</nametext></name> - <fsummary>Decode integer</fsummary> - <desc> - <p>This function decodes a GCC <c><![CDATA[long long]]></c> or Visual C++ <c><![CDATA[__int64]]></c> - (64 bit) integer from the binary format. Note that this - function is missing in the VxWorks port.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_ulonglong(const char *buf, int *index, unsigned long long *p)</nametext></name> - <fsummary>Decode unsigned integer</fsummary> - <desc> - <p>This function decodes a GCC <c><![CDATA[unsigned long long]]></c> or Visual C++ - <c><![CDATA[unsigned __int64]]></c> (64 bit) integer from the binary format. - Note that this function is missing in the VxWorks port.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_bignum(const char *buf, int *index, mpz_t obj)</nametext></name> - <fsummary>Decode a GMP arbitrary precision integer</fsummary> - <desc> - <p>This function decodes an integer in the binary format to a GMP <c><![CDATA[mpz_t]]></c> integer. - To use this function the ei library needs to be configured and compiled - to use the GMP library. </p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_double(const char *buf, int *index, double *p)</nametext></name> - <fsummary>Decode a double</fsummary> - <desc> - <p>This function decodes an double-precision (64 bit) floating - point number from the binary format.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_boolean(const char *buf, int *index, int *p)</nametext></name> - <fsummary>Decode a boolean</fsummary> - <desc> - <p>This function decodes a boolean value from the binary - format. A boolean is actually an atom, <c><![CDATA[true]]></c> decodes 1 - and <c><![CDATA[false]]></c> decodes 0.</p> +ei_x_encode_string(&x, "Banana");</pre> + <p>A correctly encoded map cannot have duplicate keys.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_char(const char *buf, int *index, char *p)</nametext></name> - <fsummary>Decode an 8-bit integer between 0-255</fsummary> + <name><ret>int</ret><nametext>ei_encode_pid(char *buf, int *index, const erlang_pid *p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_pid(ei_x_buff* x, const erlang_pid *p)</nametext></name> + <fsummary>Encode a pid.</fsummary> <desc> - <p>This function decodes a char (8-bit) integer between 0-255 - from the binary format. - Note that for historical reasons the returned integer is of - type <c><![CDATA[char]]></c>. Your C code should consider the - returned value to be of type <c><![CDATA[unsigned char]]></c> even if - the C compilers and system may define <c><![CDATA[char]]></c> to be - signed.</p> + <p>Encodes an Erlang process identifier (pid) in the binary + format. Parameter <c>p</c> points to an + <c>erlang_pid</c> structure (which should have been + obtained earlier with <c>ei_decode_pid()</c>).</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_string(const char *buf, int *index, char *p)</nametext></name> - <fsummary>Decode a string</fsummary> + <name><ret>int</ret><nametext>ei_encode_port(char *buf, int *index, const erlang_port *p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_port(ei_x_buff* x, const erlang_port *p)</nametext></name> + <fsummary>Encode a port.</fsummary> <desc> - <p>This function decodes a string from the binary format. A - string in erlang is a list of integers between 0 and - 255. Note that since the string is just a list, sometimes - lists are encoded as strings by <c><![CDATA[term_to_binary/1]]></c>, - even if it was not intended.</p> - <p>The string is copied to <c><![CDATA[p]]></c>, and enough space must be - allocated. The returned string is null terminated so you - need to add an extra byte to the memory requirement.</p> + <p>Encodes an Erlang port in the binary format. Parameter + <c>p</c> points to a <c>erlang_port</c> + structure (which should have been obtained earlier with + <c>ei_decode_port()</c>).</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_atom(const char *buf, int *index, char *p)</nametext></name> - <fsummary>Decode an atom</fsummary> + <name><ret>int</ret><nametext>ei_encode_ref(char *buf, int *index, const erlang_ref *p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_ref(ei_x_buff* x, const erlang_ref *p)</nametext></name> + <fsummary>Encode a ref.</fsummary> <desc> - <p>This function decodes an atom from the binary format. The - null terminated name of the atom is placed at <c><![CDATA[p]]></c>. There can be at most - <c><![CDATA[MAXATOMLEN]]></c> bytes placed in the buffer.</p> + <p>Encodes an Erlang reference in the binary format. Parameter + <c>p</c> points to a <c>erlang_ref</c> + structure (which should have been obtained earlier with + <c>ei_decode_ref()</c>).</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_atom_as(const char *buf, int *index, char *p, int plen, erlang_char_encoding want, erlang_char_encoding* was, erlang_char_encoding* result)</nametext></name> - <fsummary>Decode an atom</fsummary> + <name><ret>int</ret><nametext>ei_encode_string(char *buf, int *index, const char *p)</nametext></name> + <name><ret>int</ret><nametext>ei_encode_string_len(char *buf, int *index, const char *p, int len)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_string(ei_x_buff* x, const char *p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_string_len(ei_x_buff* x, const char* s, int len)</nametext></name> + <fsummary>Encode a string.</fsummary> <desc> - <p>This function decodes an atom from the binary format. The - null terminated name of the atom is placed in buffer at <c>p</c> of length - <c>plen</c> bytes.</p> - <p>The wanted string encoding is specified by <seealso marker="#erlang_char_encoding"> - <c>want</c></seealso>. The original encoding used in the - binary format (latin1 or utf8) can be obtained from <c>*was</c>. The actual encoding of the resulting string - (7-bit ascii, latin1 or utf8) can be obtained from <c>*result</c>. Both <c>was</c> and <c>result</c> can be <c>NULL</c>. - - <c>*result</c> may differ from <c>want</c> if <c>want</c> is a bitwise-or'd combination like - <c>ERLANG_LATIN1|ERLANG_UTF8</c> or if <c>*result</c> turn out to be pure 7-bit ascii - (compatible with both latin1 and utf8).</p> - <p>This function fails if the atom is too long for the buffer - or if it can not be represented with encoding <c>want</c>.</p> - <p>This function was introduced in R16 release of Erlang/OTP as part of a first step - to support UTF8 atoms.</p> + <p>Encodes a string in the binary format. (A string in Erlang + is a list, but is encoded as a character array in the binary + format.) The string is to be <c>NULL</c>-terminated, except for + the <c>ei_x_encode_string_len()</c> function.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_binary(const char *buf, int *index, void *p, long *len)</nametext></name> - <fsummary>Decode a binary</fsummary> + <name><ret>int</ret><nametext>ei_encode_term(char *buf, int *index, void *t)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_term(ei_x_buff* x, void *t)</nametext></name> + <fsummary>Encode an <c>erl_interface</c> term.</fsummary> <desc> - <p>This function decodes a binary from the binary format. The - <c><![CDATA[len]]></c> parameter is set to the actual size of the - binary. Note that <c><![CDATA[ei_decode_binary()]]></c> assumes that there - are enough room for the binary. The size required can be - fetched by <c><![CDATA[ei_get_type()]]></c>.</p> + <p>Encodes an <c>ETERM</c>, as obtained from + <c>erl_interface</c>. Parameter <c>t</c> is + actually an <c>ETERM</c> pointer. This function + does not free the <c>ETERM</c>.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_decode_fun(const char *buf, int *index, erlang_fun *p)</nametext></name> - <name><ret>void</ret><nametext>free_fun(erlang_fun* f)</nametext></name> - <fsummary>Decode a fun</fsummary> + <name><ret>int</ret><nametext>ei_encode_trace(char *buf, int *index, const erlang_trace *p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_trace(ei_x_buff* x, const erlang_trace *p)</nametext></name> + <fsummary>Encode a trace token.</fsummary> <desc> - <p>This function decodes a fun from the binary format. The - <c><![CDATA[p]]></c> parameter should be NULL or point to an - <c><![CDATA[erlang_fun]]></c> structure. This is the only decode - function that allocates memory; when the <c><![CDATA[erlang_fun]]></c> - is no longer needed, it should be freed with - <c><![CDATA[free_fun]]></c>. (This has to do with the arbitrary size of - the environment for a fun.)</p> + <p>Encodes an Erlang trace token in the binary format. + Parameter <c>p</c> points to a + <c>erlang_trace</c> structure (which should have been + obtained earlier with <c>ei_decode_trace()</c>).</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_pid(const char *buf, int *index, erlang_pid *p)</nametext></name> - <fsummary>Decode a <c><![CDATA[pid]]></c></fsummary> + <name><ret>int</ret><nametext>ei_encode_tuple_header(char *buf, int *index, int arity)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_tuple_header(ei_x_buff* x, int arity)</nametext></name> + <fsummary>Encode a tuple.</fsummary> <desc> - <p>Decodes a pid, process identifier, from the binary format.</p> + <p>Encodes a tuple header, with a specified + arity. The next <c>arity</c> terms encoded will be the + elements of the tuple. Tuples and lists are encoded + recursively, so that a tuple can contain another tuple or list.</p> + <p>For example, to encode the tuple <c>{a, {b, {}}}</c>:</p> + <pre> +ei_encode_tuple_header(buf, &i, 2); +ei_encode_atom(buf, &i, "a"); +ei_encode_tuple_header(buf, &i, 2); +ei_encode_atom(buf, &i, "b"); +ei_encode_tuple_header(buf, &i, 0);</pre> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_port(const char *buf, int *index, erlang_port *p)</nametext></name> - <fsummary>Decode a port</fsummary> + <name><ret>int</ret><nametext>ei_encode_ulong(char *buf, int *index, unsigned long p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_ulong(ei_x_buff* x, unsigned long p)</nametext></name> + <fsummary>Encode unsigned integer.</fsummary> <desc> - <p>This function decodes a port identifier from the binary - format.</p> + <p>Encodes an unsigned long integer in the binary format. + If the code is 64 bits, the function <c>ei_encode_ulong()</c> is + the same as <c>ei_encode_ulonglong()</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_ref(const char *buf, int *index, erlang_ref *p)</nametext></name> - <fsummary>Decode a reference</fsummary> + <name><ret>int</ret><nametext>ei_encode_ulonglong(char *buf, int *index, unsigned long long p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_ulonglong(ei_x_buff* x, unsigned long long p)</nametext></name> + <fsummary>Encode unsigned integer.</fsummary> <desc> - <p>This function decodes a reference from the binary format.</p> + <p>Encodes a GCC <c>unsigned long long</c> or Visual C++ + <c>unsigned __int64</c> (64-bit) integer in the binary + format. This function is missing in the VxWorks port.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_trace(const char *buf, int *index, erlang_trace *p)</nametext></name> - <fsummary>Decode a trace token</fsummary> + <name><ret>int</ret><nametext>ei_encode_version(char *buf, int *index)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_version(ei_x_buff* x)</nametext></name> + <fsummary>Encode version.</fsummary> <desc> - <p>Decodes an erlang trace token from the binary format.</p> + <p>Encodes a version magic number for the binary format. Must + be the first token in a binary term.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_tuple_header(const char *buf, int *index, int *arity)</nametext></name> - <fsummary>Decode a tuple</fsummary> + <name><ret>int</ret><nametext>ei_get_type(const char *buf, const int *index, int *type, int *size)</nametext></name> + <fsummary>Fetch the type and size of an encoded term.</fsummary> <desc> - <p>This function decodes a tuple header, the number of elements - is returned in <c><![CDATA[arity]]></c>. The tuple elements follows in order in - the buffer.</p> + <p>Returns the type in <c>type</c> and size in + <c>size</c> of the encoded term. For strings and atoms, + size is the number of characters <em>not</em> including the + terminating <c>NULL</c>. For binaries, <c>size</c> is the number of + bytes. For lists and tuples, <c>size</c> is the arity of + the object. For other types, <c>size</c> is 0. In all + cases, <c>index</c> is left unchanged.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_list_header(const char *buf, int *index, int *arity)</nametext></name> - <fsummary>Decode a list</fsummary> - <desc> - <p>This function decodes a list header from the binary - format. The number of elements is returned in - <c><![CDATA[arity]]></c>. The <c><![CDATA[arity+1]]></c> elements follows (the last - one is the tail of the list, normally an empty list.) If - <c><![CDATA[arity]]></c> is <c><![CDATA[0]]></c>, it's an empty list.</p> - <p>Note that lists are encoded as strings, if they consist - entirely of integers in the range 0..255. This function will - not decode such strings, use <c><![CDATA[ei_decode_string()]]></c> - instead.</p> + <name><ret>int</ret><nametext>ei_print_term(FILE* fp, const char* buf, int* index)</nametext></name> + <name><ret>int</ret><nametext>ei_s_print_term(char** s, const char* buf, int* index)</nametext></name> + <fsummary>Print a term in clear text.</fsummary> + <desc> + <p>Prints a term, in clear text, to the file + specified by <c>fp</c>, or the buffer pointed to by + <c>s</c>. It + tries to resemble the term printing in the Erlang shell.</p> + <p>In <c>ei_s_print_term()</c>, parameter + <c>s</c> is to + point to a dynamically (malloc) allocated string of + <c>BUFSIZ</c> bytes or a <c>NULL</c> pointer. The string + can be reallocated (and <c>*s</c> can be updated) by this + function if the result is more than <c>BUFSIZ</c> + characters. The string returned is <c>NULL</c>-terminated.</p> + <p>The return value is the number of characters written to the file + or string, or <c>-1</c> if <c>buf[index]</c> does not + contain a valid term. + Unfortunately, I/O errors on <c>fp</c> is not checked.</p> + <p>Argument <c>index</c> is updated, that is, this function + can be viewed as a decode function that decodes a term into a + human-readable format.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_map_header(const char *buf, int *index, int *arity)</nametext></name> - <fsummary>Decode a map</fsummary> + <name><ret>void</ret><nametext>ei_set_compat_rel(release_number)</nametext></name> + <fsummary>Set the ei library in compatibility mode.</fsummary> + <type> + <v>unsigned release_number;</v> + </type> <desc> - <p>This function decodes a map header from the binary - format. The number of key-value pairs is returned in - <c>*arity</c>. Keys and values follow in the following order: - <c>K1, V1, K2, V2, ..., Kn, Vn</c>. This makes a total of - <c>arity*2</c> terms. If <c>arity</c> is zero, it's an empty map. - A correctly encoded map does not have duplicate keys.</p> + <marker id="ei_set_compat_rel"></marker> + <p>By default, the <c>ei</c> library is only guaranteed + to be compatible with other Erlang/OTP components from the same + release as the <c>ei</c> library itself. For example, + <c>ei</c> from + Erlang/OTP R10 is not compatible with an Erlang emulator + from Erlang/OTP R9 by default.</p> + <p>A call to <c>ei_set_compat_rel(release_number)</c> sets + the <c>ei</c> library in compatibility mode of release + <c>release_number</c>. Valid range of + <c>release_number</c> + is <c>[7, current release]</c>. This makes it possible to + communicate with Erlang/OTP components from earlier releases.</p> + <note> + <p>If this function is called, it can only be called once + and must be called before any other functions in the + <c>ei</c> library are called.</p> + </note> + <warning> + <p>You can run into trouble if this feature is used + carelessly. Always ensure that all communicating + components are either from the same Erlang/OTP release, or + from release X and release Y where all components + from release Y are in compatibility mode of release X.</p> + </warning> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_ei_term(const char* buf, int* index, ei_term* term)</nametext></name> - <fsummary>Decode a term, without prior knowledge of type</fsummary> + <name><ret>int</ret><nametext>ei_skip_term(const char* buf, int* index)</nametext></name> + <fsummary>Skip a term.</fsummary> <desc> - <p>This function decodes any term, or at least tries to. If the - term pointed at by <c><![CDATA[*index]]></c> in <c><![CDATA[buf]]></c> fits in the - <c><![CDATA[term]]></c> union, it is decoded, and the appropriate field - in <c><![CDATA[term->value]]></c> is set, and <c><![CDATA[*index]]></c> is - incremented by the term size.</p> - <p>The function returns 1 on successful decoding, -1 on error, - and 0 if the term seems alright, but does not fit in the - <c><![CDATA[term]]></c> structure. If it returns 1, the <c><![CDATA[index]]></c> - will be incremented, and the <c><![CDATA[term]]></c> contains the - decoded term.</p> - <p>The <c><![CDATA[term]]></c> structure will contain the arity for a tuple - or list, size for a binary, string or atom. It will contains - a term if it's any of the following: integer, float, atom, - pid, port or ref.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_term(const char *buf, int *index, void *t)</nametext></name> - <fsummary>Decode a <c><![CDATA[ETERM]]></c></fsummary> - <desc> - <p>This function decodes a term from the binary format. The - term is return in <c><![CDATA[t]]></c> as a <c><![CDATA[ETERM*]]></c>, so <c><![CDATA[t]]></c> - is actually an <c><![CDATA[ETERM**]]></c> (see - <c><![CDATA[erl_interface(3)]]></c>. The term should later be - deallocated.</p> - <p>Note that this function is located in the erl_interface - library.</p> + <p>Skips a term in the specified buffer; + recursively skips elements of lists and tuples, so that a + full term is skipped. This is a way to get the size of an + Erlang term.</p> + <p><c>buf</c> is the buffer.</p> + <p><c>index</c> is updated to point right after the term + in the buffer.</p> + <note> + <p>This can be useful when you want to hold arbitrary + terms: skip them and copy the binary term data to some + buffer.</p> + </note> + <p>Returns <c>0</c> on success, otherwise + <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_print_term(FILE* fp, const char* buf, int* index)</nametext></name> - <name><ret>int</ret><nametext>ei_s_print_term(char** s, const char* buf, int* index)</nametext></name> - <fsummary>Print a term in clear text</fsummary> + <name><ret>int</ret><nametext>ei_x_append(ei_x_buff* x, const ei_x_buff* x2)</nametext></name> + <name><ret>int</ret><nametext>ei_x_append_buf(ei_x_buff* x, const char* buf, int len)</nametext></name> + <fsummary>Append a buffer at the end.</fsummary> <desc> - <p>This function prints a term, in clear text, to the file - given by <c><![CDATA[fp]]></c>, or the buffer pointed to by <c><![CDATA[s]]></c>. It - tries to resemble the term printing in the erlang shell.</p> - <p>In <c><![CDATA[ei_s_print_term()]]></c>, the parameter <c><![CDATA[s]]></c> should - point to a dynamically (malloc) allocated string of - <c><![CDATA[BUFSIZ]]></c> bytes or a NULL pointer. The string may be - reallocated (and <c><![CDATA[*s]]></c> may be updated) by this function - if the result is more than <c><![CDATA[BUFSIZ]]></c> characters. The - string returned is zero-terminated.</p> - <p>The return value is the number of characters written to the - file or string, or -1 if <c><![CDATA[buf[index]]]></c> doesn't contain a - valid term. Unfortunately, I/O errors on <c><![CDATA[fp]]></c> is not - checked.</p> - <p>The argument <c><![CDATA[index]]></c> is updated, i.e. this function can - be viewed as en decode function that decodes a term into a - human readable format.</p> + <p>Appends data at the end of buffer <c>x</c>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_x_format(ei_x_buff* x, const char* fmt, ...)</nametext></name> <name><ret>int</ret><nametext>ei_x_format_wo_ver(ei_x_buff* x, const char *fmt, ... )</nametext></name> <fsummary>Format a term from a format string and parameters.</fsummary> <desc> - <p>Format a term, given as a string, to a buffer. This - functions works like a sprintf for erlang terms. The - <c><![CDATA[fmt]]></c> contains a format string, with arguments like - <c><![CDATA[~d]]></c>, to insert terms from variables. The following + <p>Formats a term, given as a string, to a buffer. + Works like a sprintf for Erlang terms. + <c>fmt</c> contains a format string, with arguments like + <c>~d</c>, to insert terms from variables. The following formats are supported (with the C types given):</p> - <p></p> <pre> -~a - an atom, char* -~c - a character, char -~s - a string, char* -~i - an integer, int -~l - a long integer, long int -~u - a unsigned long integer, unsigned long int -~f - a float, float -~d - a double float, double float -~p - an Erlang PID, erlang_pid* - </pre> - <p>For instance, to encode a tuple with some stuff:</p> +~a An atom, char* +~c A character, char +~s A string, char* +~i An integer, int +~l A long integer, long int +~u A unsigned long integer, unsigned long int +~f A float, float +~d A double float, double float +~p An Erlang pid, erlang_pid*</pre> + <p>For example, to encode a tuple with some stuff:</p> <pre> ei_x_format("{~a,~i,~d}", "numbers", 12, 3.14159) -encodes the tuple {numbers,12,3.14159} - </pre> - <p>The <c><![CDATA[ei_x_format_wo_ver()]]></c> formats into a buffer, without - the initial version byte.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_x_new(ei_x_buff* x)</nametext></name> - <name><ret>int</ret><nametext>ei_x_new_with_version(ei_x_buff* x)</nametext></name> - <fsummary>Allocate a new buffer</fsummary> - <desc> - <p>This function allocates a new <c><![CDATA[ei_x_buff]]></c> buffer. The - fields of the structure pointed to by <c><![CDATA[x]]></c> parameter is - filled in, and a default buffer is allocated. The - <c><![CDATA[ei_x_new_with_version()]]></c> also puts an initial version - byte, that is used in the binary format. (So that - <c><![CDATA[ei_x_encode_version()]]></c> won't be needed.)</p> +encodes the tuple {numbers,12,3.14159}</pre> + <p><c>ei_x_format_wo_ver()</c> formats into a buffer, + without the initial version byte.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_x_free(ei_x_buff* x)</nametext></name> - <fsummary>Frees a buffer</fsummary> - <desc> - <p>This function frees an <c><![CDATA[ei_x_buff]]></c> buffer. The memory - used by the buffer is returned to the OS.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_x_append(ei_x_buff* x, const ei_x_buff* x2)</nametext></name> - <name><ret>int</ret><nametext>ei_x_append_buf(ei_x_buff* x, const char* buf, int len)</nametext></name> - <fsummary>Appends a buffer at the end</fsummary> + <fsummary>Free a buffer.</fsummary> <desc> - <p>These functions appends data at the end of the buffer <c><![CDATA[x]]></c>.</p> + <p>Frees an <c>ei_x_buff</c> buffer. + The memory used by the buffer is returned to the OS.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_skip_term(const char* buf, int* index)</nametext></name> - <fsummary>skip a term</fsummary> + <name><ret>int</ret><nametext>ei_x_new(ei_x_buff* x)</nametext></name> + <name><ret>int</ret><nametext>ei_x_new_with_version(ei_x_buff* x)</nametext></name> + <fsummary>Allocate a new buffer.</fsummary> <desc> - <p>This function skips a term in the given buffer, it - recursively skips elements of lists and tuples, so that a - full term is skipped. This is a way to get the size of an - erlang term.</p> - <p><c><![CDATA[buf]]></c> is the buffer.</p> - <p><c><![CDATA[index]]></c> is updated to point right after the term in the - buffer.</p> - <note> - <p>This can be useful when you want to hold arbitrary - terms: just skip them and copy the binary term data to some - buffer.</p> - </note> - <p>The function returns <c><![CDATA[0]]></c> on success and <c><![CDATA[-1]]></c> on - failure.</p> + <p>Allocates a new <c>ei_x_buff</c> buffer. The + fields of the structure pointed to by parameter <c>x</c> + is filled in, and a default buffer is allocated. + <c>ei_x_new_with_version()</c> also puts an initial + version byte, which is used in the binary format (so that + <c>ei_x_encode_version()</c> will not be needed.)</p> </desc> </func> </funcs> <section> <title>Debug Information</title> - <p>Some tips on what to check when the emulator doesn't seem to - receive the terms that you send.</p> + <p>Some tips on what to check when the emulator does not seem to + receive the terms that you send:</p> + <list type="bulleted"> - <item>be careful with the version header, use - <c><![CDATA[ei_x_new_with_version()]]></c> when appropriate</item> - <item>turn on distribution tracing on the erlang node</item> - <item>check the result codes from ei_decode_-calls</item> + <item>Be careful with the version header, use + <c>ei_x_new_with_version()</c> when appropriate.</item> + <item>Turn on distribution tracing on the Erlang node.</item> + <item>Check the result codes from <c>ei_decode_-calls</c>.</item> </list> </section> <section> <title>See Also</title> - <p>erl_interface(3)</p> + <p><seealso marker="erl_eterm"><c>erl_eterm</c></seealso></p> </section> </cref> - diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml index 516357b6a3..607a7cbff4 100644 --- a/lib/erl_interface/doc/src/ei_connect.xml +++ b/lib/erl_interface/doc/src/ei_connect.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,100 +19,233 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>ei_connect</title> <prepared>Jakob Cederlund</prepared> <docno></docno> - <approved>?</approved> - <checked>?</checked> + <approved></approved> + <checked></checked> <date>2001-09-01</date> <rev>A</rev> - <file>ei_connect.sgml</file> + <file>ei_connect.xml</file> </header> <lib>ei_connect</lib> - <libsummary>Communicate with distributed erlang</libsummary> + <libsummary>Communicate with distributed Erlang.</libsummary> <description> - <p>This module enables C programs to communicate with erlang nodes, - using the erlang distribution over TCP/IP.</p> - <p>A C node appears to Erlang as a - <em>hidden node</em>. + <p>This module enables C-programs to communicate with Erlang nodes, + using the Erlang distribution over TCP/IP.</p> + + <p>A C-node appears to Erlang as a <em>hidden node</em>. That is, Erlang processes that know the name of the - C node are able to communicate with it in a normal manner, but - the node name will not appear in the listing provided by the - Erlang function <c><![CDATA[nodes/0]]></c>.</p> - <p>The environment variable <c><![CDATA[ERL_EPMD_PORT]]></c> can be used - to indicate which logical cluster a C node belongs to.</p> + C-node can communicate with it in a normal manner, but + the node name is not shown in the listing provided by + <seealso marker="erts:erlang#nodes/0"><c>erlang:nodes/0</c></seealso> + in <c>ERTS</c>.</p> + + <p>The environment variable <c>ERL_EPMD_PORT</c> can be used + to indicate which logical cluster a C-node belongs to.</p> </description> <section> - <title>Timeout functions</title> + <title>Time-Out Functions</title> <p>Most functions appear in a version with the suffix - <c><![CDATA[_tmo]]></c> appended to the function name. Those function take - an additional argument, a timeout in <em>milliseconds</em>. The - semantics is this; for each communication primitive involved in + <c>_tmo</c> appended to the function name. Those functions + take an extra argument, a time-out in <em>milliseconds</em>. The + semantics is this: for each communication primitive involved in the operation, if the primitive does not complete within the time - specified, the function will return an error and - <c><![CDATA[erl_errno]]></c> will be set to <c><![CDATA[ETIMEDOUT]]></c>. With - communication primitive is meant an operation on the socket, like - <c><![CDATA[connect]]></c>, <c><![CDATA[accept]]></c>, <c><![CDATA[recv]]></c> or <c><![CDATA[send]]></c>.</p> - <p>Obviously the timeouts are for implementing fault tolerance, - not to keep hard realtime promises. The <c><![CDATA[_tmo]]></c> functions + specified, the function returns an error and + <c>erl_errno</c> is set to <c>ETIMEDOUT</c>. + With communication primitive is meant an operation on the socket, like + <c>connect</c>, <c>accept</c>, + <c>recv</c>, or <c>send</c>.</p> + + <p>Clearly the time-outs are for implementing fault tolerance, + not to keep hard real-time promises. The <c>_tmo</c> functions are for detecting non-responsive peers and to avoid blocking on - socket operations. </p> - <p>A timeout value of <c><![CDATA[0]]></c> (zero), means that timeouts are - disabled. Calling a <c><![CDATA[_tmo]]></c>-function with the last argument as - <c><![CDATA[0]]></c> is therefore exactly the same thing as calling the - function without the <c><![CDATA[_tmo]]></c> suffix.</p> - <p>As with all other ei functions, you are <em>not</em> expected - to put the socket in non blocking mode yourself in the program. Every - use of non blocking mode is embedded inside the timeout + socket operations.</p> + + <p>A time-out value of <c>0</c> (zero) means that time-outs are + disabled. Calling a <c>_tmo</c> function with the last + argument as <c>0</c> is therefore the same thing as calling + the function without the <c>_tmo</c> suffix.</p> + + <p>As with all other functions starting with <c>ei_</c>, + you are <em>not</em> expected + to put the socket in non-blocking mode yourself in the program. Every + use of non-blocking mode is embedded inside the time-out functions. The socket will always be back in blocking mode after the operations are completed (regardless of the result). To - avoid problems, leave the socket options alone. Ei will handle + avoid problems, leave the socket options alone. <c>ei</c> handles any socket options that need modification.</p> - <p>In all other senses, the <c><![CDATA[_tmo]]></c> functions inherit all - the return values and the semantics from the functions without - the <c><![CDATA[_tmo]]></c> suffix.</p> + + <p>In all other senses, the <c>_tmo</c> functions inherit all + the return values and the semantics from the functions without + the <c>_tmo</c> suffix.</p> </section> + <funcs> <func> + <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr(const char *addr, int len, int type)</nametext></name> + <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr_r(const char *addr, int length, int type, struct hostent *hostp, char *buffer, int buflen, int *h_errnop)</nametext></name> + <name><ret>struct hostent</ret><nametext>*ei_gethostbyname(const char *name)</nametext></name> + <name><ret>struct hostent</ret><nametext>*ei_gethostbyname_r(const char *name, struct hostent *hostp, char *buffer, int buflen, int *h_errnop)</nametext></name> + <fsummary>Name lookup functions.</fsummary> + <desc> + <p>Convenience functions for some common name lookup functions.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_accept(ei_cnode *ec, int listensock, ErlConnect *conp)</nametext></name> + <fsummary>Accept a connection from another node.</fsummary> + <desc> + <p>Used by a server process to accept a + connection from a client process.</p> + <list type="bulleted"> + <item> + <p><c>ec</c> is the C-node structure.</p> + </item> + <item> + <p><c>listensock</c> is an open socket descriptor on + which <c>listen()</c> has previously been called.</p> + </item> + <item> + <p><c>conp</c> is a pointer to an + <c>ErlConnect</c> struct, described as follows:</p> + <code type="none"><![CDATA[ +typedef struct { + char ipadr[4]; + char nodename[MAXNODELEN]; +} ErlConnect; + ]]></code> + </item> + </list> + <p>On success, <c>conp</c> is filled in with the address and + node name of the connecting client and a file descriptor is + returned. On failure, <c>ERL_ERROR</c> is returned and + <c>erl_errno</c> is set to <c>EIO</c>.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_accept_tmo(ei_cnode *ec, int listensock, ErlConnect *conp, unsigned timeout_ms)</nametext></name> + <fsummary>Accept a connection from another node with optional + time-out.</fsummary> + <desc> + <p>Equivalent to + <c>ei_accept</c> with an optional time-out argument, + see the description at the beginning of this manual page.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_connect(ei_cnode* ec, char *nodename)</nametext></name> + <name><ret>int</ret><nametext>ei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename)</nametext></name> + <fsummary>Establish a connection to an Erlang node.</fsummary> + <desc> + <p>Sets up a connection to an Erlang node.</p> + <p><c>ei_xconnect()</c> requires the IP address of the + remote host and the alive name of the remote node to be + specified. <c>ei_connect()</c> provides an alternative + interface and determines the information from the node name + provided.</p> + <list type="bulleted"> + <item><c>addr</c> is the 32-bit IP address of the remote + host.</item> + <item><c>alive</c> is the alivename of the remote node. + </item> + <item><c>node</c> is the name of the remote node.</item> + </list> + <p>These functions return an open file descriptor on success, or + a negative value indicating that an error occurred. In the latter + case they set <c>erl_errno</c> to one of the + following:</p> + <taglist> + <tag><c>EHOSTUNREACH</c></tag> + <item>The remote host <c>node</c> is unreachable.</item> + <tag><c>ENOMEM</c></tag> + <item>No more memory is available.</item> + <tag><c>EIO</c></tag> + <item>I/O error.</item> + </taglist> + <p>Also, <c>errno</c> values from + <c>socket</c><em>(2)</em> and + <c>connect</c><em>(2)</em> + system calls may be propagated into <c>erl_errno</c>.</p> + <p><em>Example:</em></p> + <code type="none"><![CDATA[ +#define NODE "[email protected]" +#define ALIVE "madonna" +#define IP_ADDR "150.236.14.75" + +/*** Variant 1 ***/ +int fd = ei_connect(&ec, NODE); + +/*** Variant 2 ***/ +struct in_addr addr; +addr.s_addr = inet_addr(IP_ADDR); +fd = ei_xconnect(&ec, &addr, ALIVE); + ]]></code> + </desc> + </func> + + <func> <name><ret>int</ret><nametext>ei_connect_init(ei_cnode* ec, const char* this_node_name, const char *cookie, short creation)</nametext></name> <name><ret>int</ret><nametext>ei_connect_xinit(ei_cnode* ec, const char *thishostname, const char *thisalivename, const char *thisnodename, Erl_IpAddr thisipaddr, const char *cookie, short creation)</nametext></name> <fsummary>Initialize for a connection.</fsummary> <desc> - <p>These function initializes the <c><![CDATA[ec]]></c> structure, to + <p>Initializes the <c>ec</c> structure, to identify the node name and cookie of the server. One of them - has to be called before other functions that works on the - type <c><![CDATA[ei_cnode]]></c> or a file descriptor associated with a - connection to another node are used.</p> - <p><c><![CDATA[ec]]></c> is a structure containing information about the - C-node. It is used in other <c><![CDATA[ei]]></c> functions for - connecting and receiving data.</p> - <p><c><![CDATA[this_node_name]]></c> is the registered name of the process - (the name before '@').</p> - <p><c><![CDATA[cookie]]></c> is the cookie for the node.</p> - <p><c><![CDATA[creation]]></c> identifies a specific instance of a C - node. It can help prevent the node from receiving messages - sent to an earlier process with the same registered name.</p> - <p><c><![CDATA[thishostname]]></c> is the name of the machine we're running - on. If long names are to be used, it should be fully - qualified (i.e. <c><![CDATA[durin.erix.ericsson.se]]></c> instead of - <c><![CDATA[durin]]></c>).</p> - <p><c><![CDATA[thisalivename]]></c> is the registered name of the process.</p> - <p><c><![CDATA[thisnodename]]></c> is the full name of the node, - i.e. <c><![CDATA[einode@durin]]></c>.</p> - <p><c><![CDATA[thispaddr]]></c> if the IP address of the host.</p> - <p>A C node acting as a server will be assigned a creation - number when it calls <c><![CDATA[ei_publish()]]></c>.</p> - <p>A connection is closed by simply closing the socket. Refer - to system documentation to close the socket gracefully (when - there are outgoing packets before close).</p> - <p>This function return a negative value indicating that an error + must be called before other functions that works on the + <c>ei_cnode</c> type or a file descriptor associated with + a connection to another node is used.</p> + <list type="bulleted"> + <item> + <p><c>ec</c> is a structure containing information about + the C-node. It is used in other <c>ei</c> functions + for connecting and receiving data.</p> + </item> + <item> + <p><c>this_node_name</c> is the registered name of the + process (the name before '@').</p> + </item> + <item> + <p><c>cookie</c> is the cookie for the node.</p> + </item> + <item> + <p><c>creation</c> identifies a specific instance of a + C-node. It can help prevent the node from receiving messages + sent to an earlier process with the same registered name.</p> + </item> + <item> + <p><c>thishostname</c> is the name of the machine we are + running on. If long names are to be used, they are to be fully + qualified (that is, <c>durin.erix.ericsson.se</c> + instead of <c>durin</c>).</p> + </item> + <item> + <p><c>thisalivename</c> is the registered name of the + process.</p> + </item> + <item> + <p><c>thisnodename</c> is the full name of the node, + that is, <c>einode@durin</c>.</p> + </item> + <item> + <p><c>thispaddr</c> if the IP address of the host.</p> + </item> + </list> + <p>A C-node acting as a server is assigned a creation + number when it calls <c>ei_publish()</c>.</p> + <p>A connection is closed by simply closing the socket. + For information about how to close the socket gracefully (when + there are outgoing packets before close), see the relevant system + documentation.</p> + <p>These functions return a negative value indicating that an error occurred.</p> - <p>Example 1: - </p> + <p><em>Example 1:</em></p> <code type="none"><![CDATA[ int n = 0; struct in_addr addr; @@ -129,8 +262,7 @@ if (ei_connect_xinit(&ec, exit(-1); } ]]></code> - <p>Example 2: - </p> + <p><em>Example 2:</em></p> <code type="none"><![CDATA[ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { fprintf(stderr,"ERROR when initializing: %d",erl_errno); @@ -139,114 +271,184 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { ]]></code> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_connect(ei_cnode* ec, char *nodename)</nametext></name> - <name><ret>int</ret><nametext>ei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename)</nametext></name> - <fsummary>Establishe a connection to an Erlang node</fsummary> + <name><ret>int</ret><nametext>ei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms)</nametext></name> + <name><ret>int</ret><nametext>ei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename, unsigned timeout_ms)</nametext></name> + <fsummary>Establish a connection to an Erlang node with optional + time-out.</fsummary> <desc> - <p>These functions set up a connection to an Erlang node.</p> - <p><c><![CDATA[ei_xconnect()]]></c> requires the IP address of the remote - host and the alive name of the remote node - to be specified. <c><![CDATA[ei_connect()]]></c> provides an alternative - interface, and determines the information from the node name - provided.</p> - <p><c><![CDATA[addr]]></c> is the 32-bit IP address of the remote host.</p> - <p><c><![CDATA[alive]]></c> is the alivename of the remote node.</p> - <p><c><![CDATA[node]]></c> is the name of the remote node.</p> - <p>These functions return an open file descriptor on success, or - a negative value indicating that an error occurred --- in - which case they will set <c><![CDATA[erl_errno]]></c> to one of:</p> - <taglist> - <tag><c><![CDATA[EHOSTUNREACH]]></c></tag> - <item>The remote host <c><![CDATA[node]]></c> is unreachable</item> - <tag><c><![CDATA[ENOMEM]]></c></tag> - <item>No more memory available.</item> - <tag><c><![CDATA[EIO]]></c></tag> - <item>I/O error.</item> - </taglist> - <p>Additionally, <c><![CDATA[errno]]></c> values from - <c><![CDATA[socket]]></c><em>(2)</em> and <c><![CDATA[connect]]></c><em>(2)</em> - system calls may be propagated into <c><![CDATA[erl_errno]]></c>.</p> - <p>Example:</p> - <code type="none"><![CDATA[ -#define NODE "[email protected]" -#define ALIVE "madonna" -#define IP_ADDR "150.236.14.75" + <p>Equivalent to + <c>ei_connect</c> and <c>ei_xconnect</c> with an optional time-out + argument, see the description at the beginning of this manual + page.</p> + </desc> + </func> -/*** Variant 1 ***/ -int fd = ei_connect(&ec, NODE); + <func> + <name><ret>int</ret><nametext>ei_get_tracelevel(void)</nametext></name> + <name><ret>void</ret><nametext>ei_set_tracelevel(int level)</nametext></name> + <fsummary>Get and set functions for tracing.</fsummary> + <desc> + <p>Used to set tracing on the distribution. The levels are different + verbosity levels. A higher level means more information. See also + section <seealso marker="#debug_information"> + Debug Information</seealso>.</p> + <p>These functions are not thread safe.</p> + </desc> + </func> -/*** Variant 2 ***/ -struct in_addr addr; -addr.s_addr = inet_addr(IP_ADDR); -fd = ei_xconnect(&ec, &addr, ALIVE); - ]]></code> + <func> + <name><ret>int</ret><nametext>ei_publish(ei_cnode *ec, int port)</nametext></name> + <fsummary>Publish a node name.</fsummary> + <desc> + <p>Used by a server process to register + with the local name server EPMD, thereby allowing + other processes to send messages by using the registered name. + Before calling either of these functions, the process should + have called <c>bind()</c> and <c>listen()</c> + on an open socket.</p> + <list type="bulleted"> + <item> + <p><c>ec</c> is the C-node structure.</p> + </item> + <item> + <p><c>port</c> is the local name to register, and is to + be the same as the port number that was previously bound to the + socket.</p> + </item> + <item> + <p><c>addr</c> is the 32-bit IP address of the local + host.</p> + </item> + </list> + <p>To unregister with EPMD, simply close the returned descriptor. Do + not use <c>ei_unpublish()</c>, which is deprecated + anyway.</p> + <p>On success, the function returns a descriptor connecting the + calling process to EPMD. On failure, <c>-1</c> is returned and + <c>erl_errno</c> is set to <c>EIO</c>.</p> + <p>Also, <c>errno</c> values from + <c>socket</c><em>(2)</em> and + <c>connect</c><em>(2)</em> system calls may be propagated + into <c>erl_errno</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms)</nametext></name> - <name><ret>int</ret><nametext>ei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename, unsigned timeout_ms)</nametext></name> - <fsummary>Establish a connection to an Erlang node with optional timeout</fsummary> + <name><ret>int</ret><nametext>ei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms)</nametext></name> + <fsummary>Publish a node name with optional time-out.</fsummary> <desc> - <p>ei_connect and ei_xconnect with an optional timeout argument, - see the description at the beginning of this document.</p> + <p>Equivalent to + <c>ei_publish</c> with an optional time-out argument, + see the description at the beginning of this manual page.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_receive(int fd, unsigned char* bufp, int bufsize)</nametext></name> - <fsummary>Receive a message</fsummary> + <fsummary>Receive a message.</fsummary> <desc> - <p>This function receives a message consisting of a sequence + <p>Receives a message consisting of a sequence of bytes in the Erlang external format.</p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection. It - is obtained from a previous <c><![CDATA[ei_connect]]></c> or - <c><![CDATA[ei_accept]]></c>.</p> - <p><c><![CDATA[bufp]]></c> is a buffer large enough to hold the expected - message. </p> - <p><c><![CDATA[bufsize]]></c> indicates the size of <c><![CDATA[bufp]]></c>.</p> - <p>If a <em>tick</em> occurs, i.e., the Erlang node on the + <list type="bulleted"> + <item> + <p><c>fd</c> is an open descriptor to an Erlang + connection. It is obtained from a previous + <c>ei_connect</c> or <c>ei_accept</c>.</p> + </item> + <item> + <p><c>bufp</c> is a buffer large enough to hold the + expected message.</p> + </item> + <item> + <p><c>bufsize</c> indicates the size of + <c>bufp</c>.</p> + </item> + </list> + <p>If a <em>tick</em> occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it - is still alive, the function will return <c><![CDATA[ERL_TICK]]></c> and - no message will be placed in the buffer. Also, - <c><![CDATA[erl_errno]]></c> will be set to <c><![CDATA[EAGAIN]]></c>.</p> + is still alive, the function returns <c>ERL_TICK</c> and + no message is placed in the buffer. Also, + <c>erl_errno</c> is set to <c>EAGAIN</c>.</p> <p>On success, the message is placed in the specified buffer and the function returns the number of bytes actually read. On - failure, the function returns <c><![CDATA[ERL_ERROR]]></c> and will set - <c><![CDATA[erl_errno]]></c> to one of:</p> + failure, the function returns <c>ERL_ERROR</c> and sets + <c>erl_errno</c> to one of the following:</p> <taglist> - <tag><c><![CDATA[EAGAIN]]></c></tag> + <tag><c>EAGAIN</c></tag> <item>Temporary error: Try again.</item> - <tag><c><![CDATA[EMSGSIZE]]></c></tag> - <item>Buffer too small.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EMSGSIZE</c></tag> + <item>Buffer is too small.</item> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_receive_tmo(int fd, unsigned char* bufp, int bufsize, unsigned timeout_ms)</nametext></name> - <fsummary>Receive a message with optional timeout</fsummary> + <name><ret>int</ret><nametext>ei_receive_encoded(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen)</nametext></name> + <fsummary>Obsolete function for receiving a message.</fsummary> <desc> - <p>ei_receive with an optional timeout argument, - see the description at the beginning of this document.</p> + <p>This function is retained for compatibility with code + generated by the interface compiler and with code following + examples in the same application.</p> + <p>In essence, the function performs the same operation as + <c>ei_xreceive_msg</c>, but instead of using an + <c>ei_x_buff</c>, the function expects a pointer to a character + pointer (<c>mbufp</c>), where the character pointer + is to point to a memory area allocated by <c>malloc</c>. + Argument <c>bufsz</c> is to be a pointer to an integer + containing the exact size (in bytes) of the memory area. The function + may reallocate the memory area and will in such cases put the new + size in <c>*bufsz</c> and update + <c>*mbufp</c>.</p> + <p>Returns either <c>ERL_TICK</c> or the + <c>msgtype</c> field of the + <c>erlang_msg *msg</c>. The length + of the message is put in <c>*msglen</c>. On error + a value <c>< 0</c> is returned.</p> + <p>It is recommended to use <c>ei_xreceive_msg</c> instead when + possible, for the sake of readability. However, the function will + be retained in the interface for compatibility and + will <em>not</em> be removed in future releases without prior + notice.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_receive_encoded_tmo(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen, unsigned timeout_ms)</nametext></name> + <fsummary>Obsolete function for receiving a message with time-out. + </fsummary> + <desc> + <p>Equivalent to + <c>ei_receive_encoded</c> with an optional time-out argument, + see the description at the beginning of this manual page.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_receive_msg(int fd, erlang_msg* msg, ei_x_buff* x)</nametext></name> <name><ret>int</ret><nametext>ei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x)</nametext></name> - <fsummary>Receive a message</fsummary> + <fsummary>Receive a message.</fsummary> <desc> - <p>These functions receives a message to the buffer in - <c><![CDATA[x]]></c>. <c><![CDATA[ei_xreceive_msg]]></c> allows the buffer in - <c><![CDATA[x]]></c> to grow, but <c><![CDATA[ei_receive_msg]]></c> fails if the - message is bigger than the preallocated buffer in <c><![CDATA[x]]></c>.</p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> - <p><c><![CDATA[msg]]></c> is a pointer to an <c><![CDATA[erlang_msg]]></c> structure - and contains information on the message received.</p> - <p><c><![CDATA[x]]></c> is buffer obtained from <c><![CDATA[ei_x_new]]></c>.</p> - <p>On success, the function returns <c><![CDATA[ERL_MSG]]></c> and the - <c><![CDATA[msg]]></c> struct will be initialized. <c><![CDATA[erlang_msg]]></c> - is defined as follows:</p> + <p>Receives a message to the buffer in <c>x</c>. + <c>ei_xreceive_msg</c> allows the buffer in + <c>x</c> to grow, but <c>ei_receive_msg</c> + fails if the message is larger than the pre-allocated buffer in + <c>x</c>.</p> + <list type="bulleted"> + <item><c>fd</c> is an open descriptor to an Erlang + connection.</item> + <item><c>msg</c> is a pointer to an + <c>erlang_msg</c> structure + and contains information on the message received.</item> + <item><c>x</c> is buffer obtained from + <c>ei_x_new</c>.</item> + </list> + <p>On success, the functions return <c>ERL_MSG</c> and the + <c>msg</c> struct is initialized. + <c>erlang_msg</c> is defined as follows:</p> <code type="none"><![CDATA[ typedef struct { long msgtype; @@ -257,125 +459,82 @@ typedef struct { erlang_trace token; } erlang_msg; ]]></code> - <p><c><![CDATA[msgtype]]></c> identifies the type of message, and is one of - <c><![CDATA[ERL_SEND]]></c>, <c><![CDATA[ERL_REG_SEND]]></c>, <c><![CDATA[ERL_LINK]]></c>, - <c><![CDATA[ERL_UNLINK]]></c> and <c><![CDATA[ERL_EXIT]]></c>.</p> - <p>If <c><![CDATA[msgtype]]></c> is <c><![CDATA[ERL_SEND]]></c> this indicates that an - ordinary send operation has taken place, and <c><![CDATA[msg->to]]></c> - contains the Pid of the recipient (the C-node). If - <c><![CDATA[type]]></c> is <c><![CDATA[ERL_REG_SEND]]></c> then a registered send - operation took place, and <c><![CDATA[msg->from]]></c> contains the Pid - of the sender.</p> - <p>If <c><![CDATA[msgtype]]></c> is <c><![CDATA[ERL_LINK]]></c> or <c><![CDATA[ERL_UNLINK]]></c>, then - <c><![CDATA[msg->to]]></c> and <c><![CDATA[msg->from]]></c> contain the pids of the - sender and recipient of the link or unlink.</p> - <p>If <c><![CDATA[msgtype]]></c> is <c><![CDATA[ERL_EXIT]]></c>, then this indicates that - a link has been broken. In this case, <c><![CDATA[msg->to]]></c> and - <c><![CDATA[msg->from]]></c> contain the pids of the linked processes.</p> - <p>The return value is the same as for <c><![CDATA[ei_receive]]></c>, see - above.</p> + <p><c>msgtype</c> identifies the type of message, and is + one of the following:</p> + <taglist> + <tag><c>ERL_SEND</c></tag> + <item> + <p>Indicates that an ordinary send operation has occurred. + <c>msg->to</c> contains the pid of the recipient (the + C-node).</p> + </item> + <tag><c>ERL_REG_SEND</c></tag> + <item> + <p>A registered send operation occurred. + <c>msg->from</c> contains the pid of the sender.</p> + </item> + <tag><c>ERL_LINK</c> or + <c>ERL_UNLINK</c></tag> + <item> + <p><c>msg->to</c> and + <c>msg->from</c> contain the pids of the + sender and recipient of the link or unlink.</p> + </item> + <tag><c>ERL_EXIT</c></tag> + <item> + <p>Indicates a broken link. <c>msg->to</c> and + <c>msg->from</c> contain the pids of the linked + processes.</p> + </item> + </taglist> + <p>The return value is the same as for + <seealso marker="#ei_receive"><c>ei_receive</c></seealso>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_receive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned imeout_ms)</nametext></name> <name><ret>int</ret><nametext>ei_xreceive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned timeout_ms)</nametext></name> - <fsummary>Receive a message with optional timeout</fsummary> - <desc> - <p>ei_receive_msg and ei_xreceive_msg with an optional timeout argument, - see the description at the beginning of this document.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_receive_encoded(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen)</nametext></name> - <fsummary>Obsolete function for receiving a message</fsummary> - <desc> - <p>This function is retained for compatibility with code - generated by the interface compiler and with code following - examples in the same application.</p> - <p>In essence the function performs the same operation as - <c><![CDATA[ei_xreceive_msg]]></c>, but instead of using an ei_x_buff, the - function expects a pointer to a character pointer - (<c><![CDATA[mbufp]]></c>), where the character pointer should point to a - memory area allocated by <c><![CDATA[malloc]]></c>. The argument - <c><![CDATA[bufsz]]></c> should be a pointer to an integer containing the - exact size (in bytes) of the memory area. The function may - reallocate the memory area and will in such cases put the new - size in <c><![CDATA[*bufsz]]></c> and update <c><![CDATA[*mbufp]]></c>.</p> - <p>Furthermore the function returns either ERL_TICK or the - <c><![CDATA[msgtype]]></c> field of the <c><![CDATA[erlang_msg *msg]]></c>. The actual - length of the message is put in <c><![CDATA[*msglen]]></c>. On error it - will return a value <c><![CDATA[< 0]]></c>.</p> - <p>It is recommended to use ei_xreceive_msg instead when - possible, for the sake of readability. The function will - however be retained in the interface for compatibility and - will <em>not</em> be removed not be removed in future releases - without notice.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_receive_encoded_tmo(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen, unsigned timeout_ms)</nametext></name> - <fsummary>Obsolete function for receiving a message with timeout</fsummary> - <desc> - <p>ei_receive_encoded with an optional timeout argument, - see the description at the beginning of this document.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_send(int fd, erlang_pid* to, char* buf, int len)</nametext></name> - <fsummary>Send a message</fsummary> - <desc> - <p>This function sends an Erlang term to a process.</p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> - <p><c><![CDATA[to]]></c> is the Pid of the intended recipient of the - message.</p> - <p><c><![CDATA[buf]]></c> is the buffer containing the term in binary - format.</p> - <p><c><![CDATA[len]]></c> is the length of the message in bytes.</p> - <p>The function returns 0 if successful, otherwise -1, in the - latter case it will set <c><![CDATA[erl_errno]]></c> to <c><![CDATA[EIO]]></c>.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_send_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name> - <fsummary>Send a message with optional timeout</fsummary> + <fsummary>Receive a message with optional time-out.</fsummary> <desc> - <p>ei_send with an optional timeout argument, - see the description at the beginning of this document.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_send_encoded(int fd, erlang_pid* to, char* buf, int len)</nametext></name> - <fsummary>Obsolete function to send a message</fsummary> - <desc> - <p>Works exactly as ei_send, the alternative name retained for - backward compatibility. The function will <em>not</em> be - removed without notice.</p> + <p>Equivalent to <c>ei_receive_msg</c> and <c>ei_xreceive_msg</c> + with an optional time-out argument, + see the description at the beginning of this manual page.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name> - <fsummary>Obsolete function to send a message with optional timeout</fsummary> + <name><ret>int</ret><nametext>ei_receive_tmo(int fd, unsigned char* bufp, int bufsize, unsigned timeout_ms)</nametext></name> + <fsummary>Receive a message with optional time-out.</fsummary> <desc> - <p>ei_send_encoded with an optional timeout argument, - see the description at the beginning of this document.</p> + <p>Equivalent to + <c>ei_receive</c> with an optional time-out argument, + see the description at the beginning of this manual page.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_reg_send(ei_cnode* ec, int fd, char* server_name, char* buf, int len)</nametext></name> - <fsummary>Send a message to a registered name</fsummary> + <fsummary>Send a message to a registered name.</fsummary> <desc> - <p>This function sends an Erlang term to a registered process. - </p> - <p>This function sends an Erlang term to a process.</p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> - <p><c><![CDATA[server_name]]></c> is the registered name of the intended - recipient.</p> - <p><c><![CDATA[buf]]></c> is the buffer containing the term in binary - format.</p> - <p><c><![CDATA[len]]></c> is the length of the message in bytes.</p> - <p>The function returns 0 if successful, otherwise -1, in the - latter case it will set <c><![CDATA[erl_errno]]></c> to <c><![CDATA[EIO]]></c>.</p> - <p>Example, send the atom "ok" to the process "worker":</p> + <p>Sends an Erlang term to a registered process.</p> + <list type="bulleted"> + <item> + <p><c>fd</c> is an open descriptor to an Erlang + connection.</p> + </item> + <item><c>server_name</c> is the registered name of the + intended recipient.</item> + <item><c>buf</c> is the buffer containing the term in + binary format.</item> + <item><c>len</c> is the length of the message in bytes. + </item> + </list> + <p>Returns <c>0</c> if successful, otherwise <c>-1</c>. In + the latter case it sets <c>erl_errno</c> to + <c>EIO</c>.</p> + <p><em>Example:</em></p> + <p>Send the atom "ok" to the process "worker":</p> <code type="none"><![CDATA[ ei_x_buff x; ei_x_new_with_version(&x); @@ -385,96 +544,98 @@ if (ei_reg_send(&ec, fd, x.buff, x.index) < 0) ]]></code> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_reg_send_tmo(ei_cnode* ec, int fd, char* server_name, char* buf, int len, unsigned timeout_ms)</nametext></name> - <fsummary>Send a message to a registered name with optional timeout</fsummary> - <desc> - <p>ei_reg_send with an optional timeout argument, - see the description at the beginning of this document.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_send_reg_encoded(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name> - <fsummary>Obsolete function to send a message to a registered name</fsummary> - <desc> - <p>This function is retained for compatibility with code - generated by the interface compiler and with code following - examples in the same application.</p> - <p>The function works as <c><![CDATA[ei_reg_send]]></c> with one - exception. Instead of taking the <c><![CDATA[ei_cnode]]></c> as a first - argument, it takes a second argument, an <c><![CDATA[erlang_pid]]></c> - which should be the process identifier of the sending process - (in the erlang distribution protocol). </p> - <p>A suitable <c><![CDATA[erlang_pid]]></c> can be constructed from the - <c><![CDATA[ei_cnode]]></c> structure by the following example code:</p> - <code type="none"><![CDATA[ - ei_cnode ec; - erlang_pid *self; - int fd; /* the connection fd */ - ... - self = ei_self(&ec); - self->num = fd; - ]]></code> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name> - <fsummary>Obsolete function to send a message to a registered name with timeout</fsummary> + <fsummary>Send a message to a registered name with optional time-out + </fsummary> <desc> - <p>ei_send_reg_encoded with an optional timeout argument, - see the description at the beginning of this document.</p> + <p>Equivalent to + <c>ei_reg_send</c> with an optional time-out argument, + see the description at the beginning of this manual page.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_rpc(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen, ei_x_buff *x)</nametext></name> <name><ret>int</ret><nametext>ei_rpc_to(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen)</nametext></name> <name><ret>int</ret><nametext>ei_rpc_from(ei_cnode *ec, int fd, int timeout, erlang_msg *msg, ei_x_buff *x)</nametext></name> - <fsummary>Remote Procedure Call from C to Erlang</fsummary> + <fsummary>Remote Procedure Call from C to Erlang.</fsummary> <desc> - <p>These functions support calling Erlang functions on remote nodes. - <c><![CDATA[ei_rpc_to()]]></c> sends an rpc request to a remote node and - <c><![CDATA[ei_rpc_from()]]></c> receives the results of such a call. - <c><![CDATA[ei_rpc()]]></c> combines the functionality of these two functions - by sending an rpc request and waiting for the results. See also - <c><![CDATA[rpc:call/4]]></c>. </p> - <p><c><![CDATA[ec]]></c> is the C-node structure previously initiated by a - call to <c><![CDATA[ei_connect_init()]]></c> or - <c><![CDATA[ei_connect_xinit()]]></c></p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> - <p><c><![CDATA[timeout]]></c> is the maximum time (in ms) to wait for - results. Specify <c><![CDATA[ERL_NO_TIMEOUT]]></c> to wait forever. - <c><![CDATA[ei_rpc()]]></c> will wait infinitely for the answer, - i.e. the call will never time out.</p> - <p><c><![CDATA[mod]]></c> is the name of the module containing the function - to be run on the remote node.</p> - <p><c><![CDATA[fun]]></c> is the name of the function to run.</p> - <p><c><![CDATA[argbuf]]></c> is a pointer to a buffer with an encoded - Erlang list, without a version magic number, containing the - arguments to be passed to the function.</p> - <p><c><![CDATA[argbuflen]]></c> is the length of the buffer containing the - encoded Erlang list.</p> - <p><c><![CDATA[msg]]></c> structure of type <c><![CDATA[erlang_msg]]></c> and contains - information on the message received. See <c><![CDATA[ei_receive_msg()]]></c> - for a description of the <c><![CDATA[erlang_msg]]></c> format.</p> - <p><c><![CDATA[x]]></c> points to the dynamic buffer that receives the - result. For for <c><![CDATA[ei_rpc()]]></c> this will be the result - without the version magic number. For <c><![CDATA[ei_rpc_from()]]></c> - the result will return a version magic number and a 2-tuple - <c><![CDATA[{rex,Reply}]]></c>.</p> - <p><c><![CDATA[ei_rpc()]]></c> returns the number of bytes in the result - on success and -1 on failure. <c><![CDATA[ei_rpc_from()]]></c> returns - number of bytes or one of <c><![CDATA[ERL_TICK]]></c>, <c><![CDATA[ERL_TIMEOUT]]></c> - and <c><![CDATA[ERL_ERROR]]></c> otherwise. When failing, - all three functions set <c><![CDATA[erl_errno]]></c> to one of:</p> + <p>Supports calling Erlang functions on remote nodes. + <c>ei_rpc_to()</c> sends an RPC request to a remote node + and <c>ei_rpc_from()</c> receives the results of such a + call. <c>ei_rpc()</c> combines the functionality of these + two functions by sending an RPC request and waiting for the results. + See also <seealso marker="kernel:rpc#call/4"> + <c>rpc:call/4</c></seealso> in Kernel.</p> + <list type="bulleted"> + <item> + <p><c>ec</c> is the C-node structure previously + initiated by a call to <c>ei_connect_init()</c> or + <c>ei_connect_xinit()</c>.</p> + </item> + <item> + <p><c>fd</c> is an open descriptor to an Erlang + connection.</p> + </item> + <item> + <p><c>timeout</c> is the maximum time (in milliseconds) + to wait for results. Specify <c>ERL_NO_TIMEOUT</c> to + wait forever. + <c>ei_rpc()</c> waits infinitely for the answer, + that is, the call will never time out.</p> + </item> + <item> + <p><c>mod</c> is the name of the module containing the + function to be run on the remote node.</p> + </item> + <item> + <p><c>fun</c> is the name of the function to run.</p> + </item> + <item> + <p><c>argbuf</c> is a pointer to a buffer with an + encoded Erlang list, without a version magic number, containing + the arguments to be passed to the function.</p> + </item> + <item> + <p><c>argbuflen</c> is the length of the buffer + containing the encoded Erlang list.</p> + </item> + <item> + <p><c>msg</c> is structure of type + <c>erlang_msg</c> and contains information on the + message + received. For a description of the <c>erlang_msg</c> + format, see <seealso marker="#ei_receive_msg"> + <c>ei_receive_msg</c></seealso>.</p> + </item> + <item> + <p><c>x</c> points to the dynamic buffer that receives + the result. For <c>ei_rpc()</c> this is the result + without the version magic number. For + <c>ei_rpc_from()</c> the result returns a version + magic number and a 2-tuple <c>{rex,Reply}</c>.</p> + </item> + </list> + <p><c>ei_rpc()</c> returns the number of bytes in the + result on success and <c>-1</c> on failure. + <c>ei_rpc_from()</c> returns the + number of bytes, otherwise one of <c>ERL_TICK</c>, + <c>ERL_TIMEOUT</c>, + and <c>ERL_ERROR</c>. When failing, all three + functions set <c>erl_errno</c> to one of the + following:</p> <taglist> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EIO</c></tag> <item>I/O error.</item> - <tag><c><![CDATA[ETIMEDOUT]]></c></tag> - <item>Timeout expired.</item> - <tag><c><![CDATA[EAGAIN]]></c></tag> + <tag><c>ETIMEDOUT</c></tag> + <item>Time-out expired.</item> + <tag><c>EAGAIN</c></tag> <item>Temporary error: Try again.</item> </taglist> - <p>Example, check to see if an erlang process is alive:</p> + <p><em>Example:</em></p> + <p>Check to see if an Erlang process is alive:</p> <code type="none"><![CDATA[ int index = 0, is_alive; ei_x_buff args, result; @@ -495,170 +656,190 @@ if (ei_decode_version(result.buff, &index) < 0 ]]></code> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_publish(ei_cnode *ec, int port)</nametext></name> - <fsummary>Publish a node name</fsummary> + <name><ret>erlang_pid *</ret><nametext>ei_self(ei_cnode *ec)</nametext></name> + <fsummary>Retrieve the pid of the C-node.</fsummary> <desc> - <p>These functions are used by a server process to register - with the local name server <em>epmd</em>, thereby allowing - other processes to send messages by using the registered name. - Before calling either of these functions, the process should - have called <c><![CDATA[bind()]]></c> and <c><![CDATA[listen()]]></c> on an open socket.</p> - <p><c><![CDATA[ec]]></c> is the C-node structure.</p> - <p><c><![CDATA[port]]></c> is the local name to register, and should be the - same as the port number that was previously bound to the socket.</p> - <p><c><![CDATA[addr]]></c> is the 32-bit IP address of the local host.</p> - <p>To unregister with epmd, simply close the returned - descriptor. Do not use <c><![CDATA[ei_unpublish()]]></c>, which is deprecated anyway.</p> - <p>On success, the functions return a descriptor connecting the - calling process to epmd. On failure, they return -1 and set - <c><![CDATA[erl_errno]]></c> to <c><![CDATA[EIO]]></c>.</p> - <p>Additionally, <c><![CDATA[errno]]></c> values from <c><![CDATA[socket]]></c><em>(2)</em> - and <c><![CDATA[connect]]></c><em>(2)</em> system calls may be propagated - into <c><![CDATA[erl_errno]]></c>.</p> + <p>Retrieves the pid of the C-node. Every C-node + has a (pseudo) pid used in <c>ei_send_reg</c>, + <c>ei_rpc</c>, + and others. This is contained in a field in the <c>ec</c> + structure. It will be safe for a long time to fetch this + field directly from the <c>ei_cnode</c> structure.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms)</nametext></name> - <fsummary>Publish a node name with optional timeout</fsummary> + <name><ret>int</ret><nametext>ei_send(int fd, erlang_pid* to, char* buf, int len)</nametext></name> + <fsummary>Send a message.</fsummary> <desc> - <p>ei_publish with an optional timeout argument, - see the description at the beginning of this document.</p> + <p>Sends an Erlang term to a process.</p> + <list type="bulleted"> + <item><c>fd</c> is an open descriptor to an Erlang + connection.</item> + <item><c>to</c> is the pid of the intended recipient of + the message.</item> + <item><c>buf</c> is the buffer containing the term in + binary format.</item> + <item><c>len</c> is the length of the message in bytes. + </item> + </list> + <p>Returns <c>0</c> if successful, otherwise <c>-1</c>. In + the latter case it sets <c>erl_errno</c> to + <c>EIO</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_accept(ei_cnode *ec, int listensock, ErlConnect *conp)</nametext></name> - <fsummary>Accept a connection from another node</fsummary> + <name><ret>int</ret><nametext>ei_send_encoded(int fd, erlang_pid* to, char* buf, int len)</nametext></name> + <fsummary>Obsolete function to send a message.</fsummary> <desc> - <p>This function is used by a server process to accept a - connection from a client process.</p> - <p><c><![CDATA[ec]]></c> is the C-node structure.</p> - <p><c><![CDATA[listensock]]></c> is an open socket descriptor on which - <c><![CDATA[listen()]]></c> has previously been called.</p> - <p><c><![CDATA[conp]]></c> is a pointer to an <c><![CDATA[ErlConnect]]></c> struct, - described as follows:</p> - <code type="none"><![CDATA[ -typedef struct { - char ipadr[4]; - char nodename[MAXNODELEN]; -} ErlConnect; - ]]></code> - <p>On success, <c><![CDATA[conp]]></c> is filled in with the address and - node name of the connecting client and a file descriptor is - returned. On failure, <c><![CDATA[ERL_ERROR]]></c> is returned and - <c><![CDATA[erl_errno]]></c> is set to <c><![CDATA[EIO]]></c>.</p> + <p>Works exactly as <c>ei_send</c>, the alternative name is retained for + backward compatibility. The function will <em>not</em> be + removed without prior notice.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_accept_tmo(ei_cnode *ec, int listensock, ErlConnect *conp, unsigned timeout_ms)</nametext></name> - <fsummary>Accept a connection from another node with optional timeout</fsummary> + <name><ret>int</ret><nametext>ei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name> + <fsummary>Obsolete function to send a message with optional time-out. + </fsummary> <desc> - <p>ei_accept with an optional timeout argument, - see the description at the beginning of this document.</p> + <p>Equivalent to + <c>ei_send_encoded</c> with an optional time-out argument, + see the description at the beginning of this manual page.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_unpublish(ei_cnode *ec)</nametext></name> - <fsummary>Forcefully unpublish a node name</fsummary> + <name><ret>int</ret><nametext>ei_send_reg_encoded(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name> + <fsummary>Obsolete function to send a message to a registered name. + </fsummary> <desc> - <p>This function can be called by a process to unregister a - specified node from epmd on the localhost. This is however usually not - allowed, unless epmd was started with the -relaxed_command_check - flag, which it normally isn't.</p> - - <p>To unregister a node you have published, you should - close the descriptor that was returned by - <c><![CDATA[ei_publish()]]></c>.</p> + <p>This function is retained for compatibility with code + generated by the interface compiler and with code following + examples in the same application.</p> + <p>The function works as <c>ei_reg_send</c> with one + exception. Instead of taking <c>ei_cnode</c> as first + argument, it takes a second argument, an + <c>erlang_pid</c>, + which is to be the process identifier of the sending process + (in the Erlang distribution protocol).</p> + <p>A suitable <c>erlang_pid</c> can be constructed from the + <c>ei_cnode</c> structure by the following example + code:</p> + <code type="none"><![CDATA[ +ei_cnode ec; +erlang_pid *self; +int fd; /* the connection fd */ +... +self = ei_self(&ec); +self->num = fd; + ]]></code> + </desc> + </func> - <warning> - <p>This function is deprecated and will be removed in a future - release.</p> - </warning> - <p><c><![CDATA[ec]]></c> is the node structure of the node to unregister.</p> - <p>If the node was successfully unregistered from epmd, the - function returns 0. Otherwise, it returns -1 and sets - <c><![CDATA[erl_errno]]></c> is to <c><![CDATA[EIO]]></c>.</p> + <func> + <name><ret>int</ret><nametext>ei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name> + <fsummary>Obsolete function to send a message to a registered name with + time-out.</fsummary> + <desc> + <p>Equivalent to + <c>ei_send_reg_encoded</c> with an optional time-out argument, + see the description at the beginning of this manual page.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms)</nametext></name> - <fsummary>Unpublish a node name with optional timeout</fsummary> + <name><ret>int</ret><nametext>ei_send_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name> + <fsummary>Send a message with optional time-out.</fsummary> <desc> - <p>ei_unpublish with an optional timeout argument, - see the description at the beginning of this document.</p> + <p>Equivalent to + <c>ei_send</c> with an optional time-out argument, + see the description at the beginning of this manual page.</p> </desc> </func> + <func> <name><ret>const char *</ret><nametext>ei_thisnodename(ei_cnode *ec)</nametext></name> <name><ret>const char *</ret><nametext>ei_thishostname(ei_cnode *ec)</nametext></name> <name><ret>const char *</ret><nametext>ei_thisalivename(ei_cnode *ec)</nametext></name> - <fsummary>Retrieve some values</fsummary> + <fsummary>Retrieve some values.</fsummary> <desc> - <p>These functions can be used to retrieve information about - the C Node. These values are initially set with - <c><![CDATA[ei_connect_init()]]></c> or <c><![CDATA[ei_connect_xinit()]]></c>.</p> - <p>They simply fetches the appropriate field from the <c><![CDATA[ec]]></c> + <p>Can be used to retrieve information about + the C-node. These values are initially set with + <c>ei_connect_init()</c> or + <c>ei_connect_xinit()</c>.</p> + <p>These function simply fetch the appropriate field from the + <c>ec</c> structure. Read the field directly will probably be safe for a long time, so these functions are not really needed.</p> </desc> </func> + <func> - <name><ret>erlang_pid *</ret><nametext>ei_self(ei_cnode *ec)</nametext></name> - <fsummary>Retrieve the Pid of the C-node</fsummary> - <desc> - <p>This function retrieves the Pid of the C-node. Every C-node - has a (pseudo) pid used in <c><![CDATA[ei_send_reg]]></c>, <c><![CDATA[ei_rpc]]></c> - and others. This is contained in a field in the <c><![CDATA[ec]]></c> - structure. It will be safe for a long time to fetch this - field directly from the <c><![CDATA[ei_cnode]]></c> structure.</p> - </desc> - </func> - <func> - <name><ret>struct hostent</ret><nametext>*ei_gethostbyname(const char *name)</nametext></name> - <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr(const char *addr, int len, int type)</nametext></name> - <name><ret>struct hostent</ret><nametext>*ei_gethostbyname_r(const char *name, struct hostent *hostp, char *buffer, int buflen, int *h_errnop)</nametext></name> - <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr_r(const char *addr, int length, int type, struct hostent *hostp, char *buffer, int buflen, int *h_errnop)</nametext></name> - <fsummary>Name lookup functions</fsummary> + <name><ret>int</ret><nametext>ei_unpublish(ei_cnode *ec)</nametext></name> + <fsummary>Forcefully unpublish a node name.</fsummary> <desc> - <p>These are convenience functions for some common name lookup functions.</p> + <p>Can be called by a process to unregister a + specified node from EPMD on the local host. This is, however, usually + not allowed, unless EPMD was started with flag + <c>-relaxed_command_check</c>, which it normally is not.</p> + <p>To unregister a node you have published, you should + close the descriptor that was returned by + <c>ei_publish()</c>.</p> + <warning> + <p>This function is deprecated and will be removed in a future + release.</p> + </warning> + <p><c>ec</c> is the node structure of the node to + unregister.</p> + <p>If the node was successfully unregistered from EPMD, the + function returns <c>0</c>. Otherwise, <c>-1</c> is returned and + <c>erl_errno</c> is set to <c>EIO</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_get_tracelevel(void)</nametext></name> - <name><ret>void</ret><nametext>ei_set_tracelevel(int level)</nametext></name> - <fsummary>Get and set functions for tracing.</fsummary> + <name><ret>int</ret><nametext>ei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms)</nametext></name> + <fsummary>Unpublish a node name with optional time-out.</fsummary> <desc> - <p>These functions are used to set tracing on the distribution. The levels are different verbosity levels. A higher level means more information. - See also Debug Information and <c><![CDATA[EI_TRACELEVEL]]></c> below. </p> - <p> <c><![CDATA[ei_set_tracelevel]]></c> and <c><![CDATA[ei_get_tracelevel]]></c> are not thread safe. </p> + <p>Equivalent to + <c>ei_unpublish</c> with an optional time-out argument, + see the description at the beginning of this manual page.</p> </desc> </func> </funcs> <section> + <marker id="debug_information"></marker> <title>Debug Information</title> <p>If a connection attempt fails, the following can be checked:</p> + <list type="bulleted"> - <item><c><![CDATA[erl_errno]]></c></item> - <item>that the right cookie was used</item> - <item>that <em>epmd</em> is running</item> - <item>the remote Erlang node on the other side is running the - same version of Erlang as the <c><![CDATA[ei]]></c> - library.</item> - <item>the environment variable <c><![CDATA[ERL_EPMD_PORT]]></c> - is set correctly.</item> + <item><c>erl_errno</c>.</item> + <item>That the correct cookie was used</item> + <item>That EPMD is running</item> + <item>That the remote Erlang node on the other side is running the + same version of Erlang as the <c>ei</c> library</item> + <item>That environment variable <c>ERL_EPMD_PORT</c> + is set correctly</item> </list> - <p>The connection attempt can be traced by setting a tracelevel by either using - <c><![CDATA[ei_set_tracelevel]]></c> or by setting the environment variable <c><![CDATA[EI_TRACELEVEL]]></c>. - The different tracelevels has the following messages:</p> + + <p>The connection attempt can be traced by setting a trace level by either + using <c>ei_set_tracelevel</c> or by setting environment + variable <c>EI_TRACELEVEL</c>. + The trace levels have the following messages:</p> + <list> - <item>1: Verbose error messages</item> - <item>2: Above messages and verbose warning messages </item> - <item>3: Above messages and progress reports for connection handling</item> - <item>4: Above messages and progress reports for communication</item> - <item>5: Above messages and progress reports for data conversion</item> + <item>1: Verbose error messages</item> + <item>2: Above messages and verbose warning messages</item> + <item>3: Above messages and progress reports for connection handling + </item> + <item>4: Above messages and progress reports for communication</item> + <item>5: Above messages and progress reports for data conversion</item> </list> </section> </cref> - diff --git a/lib/erl_interface/doc/src/ei_users_guide.xml b/lib/erl_interface/doc/src/ei_users_guide.xml index 4b9809aee4..0eed50b50b 100644 --- a/lib/erl_interface/doc/src/ei_users_guide.xml +++ b/lib/erl_interface/doc/src/ei_users_guide.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,10 +19,10 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> - <title>The El Library User's Guide</title> + <title>Erl_Interface User's Guide</title> <prepared>Kent Boortz</prepared> <responsible>Kent Boortz</responsible> <docno></docno> @@ -32,100 +32,158 @@ <rev></rev> <file>ei_users_guide.xml</file> </header> - <p>The Erl_Interface library contains functions. which help you - integrate programs written in C and Erlang. The functions in - Erl_Interface support the following:</p> - <list type="bulleted"> - <item>manipulation of data represented as Erlang data types</item> - <item>conversion of data between C and Erlang formats</item> - <item>encoding and decoding of Erlang data types for transmission or storage</item> - <item>communication between C nodes and Erlang processes</item> - <item>backup and restore of C node state to and from Mnesia</item> - </list> - <p>In the following sections, these topics are described:</p> - <list type="bulleted"> - <item>compiling your code for use with Erl_Interface</item> - <item>initializing Erl_Interface</item> - <item>encoding, decoding, and sending Erlang terms</item> - <item>building terms and patterns</item> - <item>pattern matching</item> - <item>connecting to a distributed Erlang node</item> - <item>using EPMD</item> - <item>sending and receiving Erlang messages</item> - <item>remote procedure calls</item> - <item>global names</item> - <item>the registry</item> - </list> + + <section> + <title>Introduction</title> + <p>The <c>Erl_Interface</c> library contains functions that help you + integrate programs written in C and Erlang. The functions in + <c>Erl_Interface</c> support the following:</p> + <list type="bulleted"> + <item>Manipulation of data represented as Erlang data types</item> + <item>Conversion of data between C and Erlang formats</item> + <item>Encoding and decoding of Erlang data types for transmission or + storage</item> + <item>Communication between C nodes and Erlang processes</item> + <item>Backup and restore of C node state to and from + <seealso marker="mnesia:mnesia">Mnesia</seealso></item> + </list> + <note> + <p>By default, the <c>Erl_Interface</c> libraries are only guaranteed + to be compatible with other Erlang/OTP components from the same + release as the libraries themselves. For information about how to + communicate with Erlang/OTP components from earlier releases, see + function <seealso marker="ei#ei_set_compat_rel"> + <c>ei:ei_set_compat_rel</c></seealso> and + <seealso marker="erl_eterm#erl_set_compat_rel"> + <c>erl_eterm:erl_set_compat_rel</c></seealso>.</p> + </note> + + <section> + <title>Scope</title> + <p>In the following sections, these topics are described:</p> + <list type="bulleted"> + <item>Compiling your code for use with <c>Erl_Interface</c></item> + <item>Initializing <c>Erl_Interface</c></item> + <item>Encoding, decoding, and sending Erlang terms</item> + <item>Building terms and patterns</item> + <item>Pattern matching</item> + <item>Connecting to a distributed Erlang node</item> + <item>Using the Erlang Port Mapper Daemon (EPMD)</item> + <item>Sending and receiving Erlang messages</item> + <item>Remote procedure calls</item> + <item>Using global names</item> + <item>Using the registry</item> + </list> + </section> + + <section> + <title>Prerequisites</title> + <p>It is assumed that the reader is familiar with the Erlang programming + language.</p> + </section> + </section> <section> <title>Compiling and Linking Your Code</title> - <p>In order to use any of the Erl_Interface functions, include the + <p>To use any of the <c>Erl_Interface</c> functions, include the following lines in your code:</p> + <code type="none"><![CDATA[ #include "erl_interface.h" #include "ei.h" ]]></code> - <p>Determine where the top directory of your OTP installation is. You - can find this out by starting Erlang and entering the following + + <p>Determine where the top directory of your OTP installation is. + To find this, start Erlang and enter the following command at the Eshell prompt:</p> + <code type="none"><![CDATA[ Eshell V4.7.4 (abort with ^G) 1> code:root_dir(). /usr/local/otp ]]></code> - <p>To compile your code, make sure that your C compiler knows where - to find <c><![CDATA[erl_interface.h]]></c> by specifying an appropriate <c><![CDATA[-I]]></c> - argument on the command line, or by adding it to the <c><![CDATA[CFLAGS]]></c> - definition in your <c><![CDATA[Makefile]]></c>. The correct value for this path is - <c><![CDATA[$OTPROOT/lib/erl_interface]]></c><em>Vsn</em><c><![CDATA[/include]]></c>, where <c><![CDATA[$OTPROOT]]></c> is the path - reported by <c><![CDATA[code:root_dir/0]]></c> in the above example, and <em>Vsn</em> is - the version of the Erl_interface application, for example - <c><![CDATA[erl_interface-3.2.3]]></c></p> + + <p>To compile your code, ensure that your C compiler knows where + to find <c>erl_interface.h</c> by specifying an appropriate + <c>-I</c> argument on the command line, or add it to + the <c>CFLAGS</c> definition in your + <c>Makefile</c>. The correct value for this path is + <c>$OTPROOT/lib/erl_interface-$EIVSN/include</c>, + where:</p> + + <list type="bulleted"> + <item> + <p><c>$OTPROOT</c> is the path reported by + <c>code:root_dir/0</c> in the example above.</p> + </item> + <item> + <p><c>$EIVSN</c> is the version of the <c>Erl_Interface</c> application, + for example, <c>erl_interface-3.2.3</c>.</p> + </item> + </list> + + <p>Compiling the code:</p> + <code type="none"><![CDATA[ $ cc -c -I/usr/local/otp/lib/erl_interface-3.2.3/include myprog.c ]]></code> - <p>When linking, you will need to specify the path to - <c><![CDATA[liberl_interface.a]]></c> and <c><![CDATA[libei.a]]></c> with - <c><![CDATA[-L$OTPROOT/lib/erl_interface-3.2.3/lib]]></c>, and you will need to specify the - name of the libraries with <c><![CDATA[-lerl_interface -lei]]></c>. You can do - this on the command line or by adding the flags to the <c><![CDATA[LDFLAGS]]></c> - definition in your <c><![CDATA[Makefile]]></c>.</p> + + <p>When linking:</p> + + <list type="bulleted"> + <item>Specify the path to <c>liberl_interface.a</c> and + <c>libei.a</c> with + <c>-L$OTPROOT/lib/erl_interface-3.2.3/lib</c>.</item> + <item>Specify the name of the libraries with + <c>-lerl_interface -lei</c>.</item> + </list> + + <p>Do this on the command line or add the flags to the + <c>LDFLAGS</c> definition in your + <c>Makefile</c>.</p> + + <p>Linking the code:</p> + <code type="none"><![CDATA[ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ lib myprog.o -lerl_interface -lei -o myprog ]]></code> - <p>Also, on some systems it may be necessary to link with some - additional libraries (e.g. <c><![CDATA[libnsl.a]]></c> and <c><![CDATA[libsocket.a]]></c> on - Solaris, or <c><![CDATA[wsock32.lib]]></c> on Windows) in order to use the - communication facilities of Erl_Interface.</p> - <p>If you are using Erl_Interface functions in a threaded + + <p>On some systems it can be necessary to link with some more + libraries (for example, <c>libnsl.a</c> and + <c>libsocket.a</c> on Solaris, or + <c>wsock32.lib</c> on Windows) to use the + communication facilities of <c>Erl_Interface</c>.</p> + + <p>If you use the <c>Erl_Interface</c> functions in a threaded application based on POSIX threads or Solaris threads, then - Erl_Interface needs access to some of the synchronization - facilities in your threads package, and you will need to specify - additional compiler flags in order to indicate which of the packages - you are using. Define <c><![CDATA[_REENTRANT]]></c> and either <c><![CDATA[STHREADS]]></c> or - <c><![CDATA[PTHREADS]]></c>. The default is to use POSIX threads if - <c><![CDATA[_REENTRANT]]></c> is specified.</p> + <c>Erl_Interface</c> needs access to some of the synchronization + facilities in your threads package. You must specify extra + compiler flags to indicate which of the packages you use. Define + <c>_REENTRANT</c> and either <c>STHREADS</c> or + <c>PTHREADS</c>. The default is to use POSIX threads if + <c>_REENTRANT</c> is specified.</p> </section> <section> - <title>Initializing the erl_interface Library</title> - <p>Before calling any of the other Erl_Interface functions, you - must call <c><![CDATA[erl_init()]]></c> exactly once to initialize the library. - <c><![CDATA[erl_init()]]></c> takes two arguments, however the arguments are no - longer used by Erl_Interface, and should therefore be specified - as <c><![CDATA[erl_init(NULL,0)]]></c>.</p> + <title>Initializing the Erl_Interface Library</title> + <p>Before calling any of the other <c>Erl_Interface</c> functions, call + <c>erl_init()</c> exactly once to initialize the library. + <c>erl_init()</c> takes two arguments. However, the arguments + are no longer used by <c>Erl_Interface</c> and are therefore to be + specified as <c>erl_init(NULL,0)</c>.</p> </section> <section> - <title>Encoding, Decoding and Sending Erlang Terms</title> + <title>Encoding, Decoding, and Sending Erlang Terms</title> <p>Data sent between distributed Erlang nodes is encoded in the - Erlang external format. Consequently, you have to encode and decode + Erlang external format. You must therefore encode and decode Erlang terms into byte streams if you want to use the distribution - protocol to communicate between a C program and Erlang. </p> - <p>The Erl_Interface library supports this activity. It has a - number of C functions which create and manipulate Erlang data + protocol to communicate between a C program and Erlang.</p> + + <p>The <c>Erl_Interface</c> library supports this activity. It has + several C functions that create and manipulate Erlang data structures. The library also contains an encode and a decode function. - The example below shows how to create and encode an Erlang tuple - <c><![CDATA[{tobbe,3928}]]></c>:</p> - <code type="none"><![CDATA[ + The following example shows how to create and encode an Erlang tuple + <c>{tobbe,3928}</c>:</p> + <code type="none"><![CDATA[ ETERM *arr[2], *tuple; char buf[BUFSIZ]; int i; @@ -134,58 +192,70 @@ arr[0] = erl_mk_atom("tobbe"); arr[1] = erl_mk_integer(3928); tuple = erl_mk_tuple(arr, 2); i = erl_encode(tuple, buf); ]]></code> - <p>Alternatively, you can use <c><![CDATA[erl_send()]]></c> and - <c><![CDATA[erl_receive_msg]]></c>, which handle the encoding and decoding of - messages transparently.</p> - <p>Refer to the Reference Manual for a complete description of the - following modules:</p> + + <p>Alternatively, you can use <c>erl_send()</c> and + <c>erl_receive_msg</c>, which handle the encoding and + decoding of messages transparently.</p> + + <p>For a complete description, see the following modules:</p> <list type="bulleted"> - <item>the <c><![CDATA[erl_eterm]]></c> module for creating Erlang terms</item> - <item>the <c><![CDATA[erl_marshal]]></c> module for encoding and decoding routines.</item> + <item><seealso marker="erl_eterm"><c>erl_eterm</c></seealso> + for creating Erlang terms</item> + <item><seealso marker="erl_marshal"><c>erl_marshal</c></seealso> + for encoding and decoding routines</item> </list> </section> <section> + <marker id="building_terms_and_patterns"/> <title>Building Terms and Patterns</title> - <p>The previous example can be simplified by using - <c><![CDATA[erl_format()]]></c> to create an Erlang term.</p> - <code type="none"><![CDATA[ + <p>The previous example can be simplified by using the + <seealso marker="erl_format"><c>erl_format</c></seealso> module + to create an Erlang term:</p> + <code type="none"><![CDATA[ ETERM *ep; ep = erl_format("{~a,~i}", "tobbe", 3928); ]]></code> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_format]]></c> module, for a - full description of the different format directives. The following - example is more complex:</p> - <code type="none"><![CDATA[ + <p>For a complete description of the different format directives, see + the <seealso marker="erl_format"><c>erl_format</c></seealso> module.</p> + + <p>The following example is more complex:</p> + + <code type="none"><![CDATA[ ETERM *ep; ep = erl_format("[{name,~a},{age,~i},{data,~w}]", "madonna", 21, erl_format("[{adr,~s,~i}]", "E-street", 42)); erl_free_compound(ep); ]]></code> - <p>As in previous examples, it is your responsibility to free the - memory allocated for Erlang terms. In this example, - <c><![CDATA[erl_free_compound()]]></c> ensures that the complete term pointed to - by <c><![CDATA[ep]]></c> is released. This is necessary, because the pointer from - the second call to <c><![CDATA[erl_format()]]></c> is lost. </p> - <p>The following - example shows a slightly different solution:</p> - <code type="none"><![CDATA[ + <p>As in the previous examples, it is your responsibility to free the + memory allocated for Erlang terms. In this example, + <c>erl_free_compound()</c> ensures that the complete term + pointed to by <c>ep</c> is released. This is necessary + because the pointer from the second call to <c>erl_format</c> is lost.</p> + + <p>The following example shows a slightly different solution:</p> + + <code type="none"><![CDATA[ ETERM *ep,*ep2; ep2 = erl_format("[{adr,~s,~i}]","E-street",42); ep = erl_format("[{name,~a},{age,~i},{data,~w}]", "madonna", 21, ep2); erl_free_term(ep); erl_free_term(ep2); ]]></code> + <p>In this case, you free the two terms independently. The order in - which you free the terms <c><![CDATA[ep]]></c> and <c><![CDATA[ep2]]></c> is not important, - because the Erl_Interface library uses reference counting to - determine when it is safe to actually remove objects. </p> - <p>If you are not sure whether you have freed the terms properly, you + which you free the terms <c>ep</c> and <c>ep2</c> + is not important, + because the <c>Erl_Interface</c> library uses reference counting to + determine when it is safe to remove objects.</p> + + <p>If you are unsure whether you have freed the terms properly, you can use the following function to see the status of the fixed term allocator:</p> + <code type="none"><![CDATA[ long allocated, freed; @@ -196,36 +266,49 @@ printf("length of freelist: %ld\n",freed); /* really free the freelist */ erl_eterm_release(); ]]></code> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_malloc]]></c> module for more - information.</p> + + <p>For more information, see the + <seealso marker="erl_malloc"><c>erl_malloc</c></seealso> module.</p> </section> <section> <title>Pattern Matching</title> - <p>An Erlang pattern is a term that may contain unbound variables or - <c><![CDATA["do not care"]]></c> symbols. Such a pattern can be matched against a + <p>An Erlang pattern is a term that can contain unbound variables or + <c>"do not care"</c> symbols. Such a pattern can be matched + against a term and, if the match is successful, any unbound variables in the pattern will be bound as a side effect. The content of a bound - variable can then be retrieved.</p> - <code type="none"><![CDATA[ + variable can then be retrieved:</p> + <code type="none"><![CDATA[ ETERM *pattern; pattern = erl_format("{madonna,Age,_}"); ]]></code> - <p><c><![CDATA[erl_match()]]></c> is used to perform pattern matching. It takes a + + <p>The <seealso marker="erl_format#erl_match"> + <c>erl_format:erl_match</c></seealso> function + performs pattern matching. It takes a pattern and a term and tries to match them. As a side effect any unbound - variables in the pattern will be bound. In the following example, we - create a pattern with a variable <em>Age</em> which appears at two + variables in the pattern will be bound. In the following example, a + pattern is created with a variable <c>Age</c>, which is included at two positions in the tuple. The pattern match is performed as follows:</p> - <list type="ordered"> - <item><c><![CDATA[erl_match()]]></c> will bind the contents of - <em>Age</em> to <em>21</em> the first time it reaches the variable</item> - <item>the second occurrence of <em>Age</em> will cause a test for - equality between the terms since <em>Age</em> is already bound to - <em>21</em>. Since <em>Age</em> is bound to 21, the equality test will - succeed and the match continues until the end of the pattern.</item> - <item>if the end of the pattern is reached, the match succeeds and you - can retrieve the contents of the variable</item> + + <list type="bulleted"> + <item> + <p><c>erl_match</c> binds the contents of <c>Age</c> to <c>21</c> + the first time it reaches the variable.</p> + </item> + <item> + <p>The second occurrence of <c>Age</c> causes a test for + equality between the terms, as <c>Age</c> is already bound to + <c>21</c>. As <c>Age</c> is bound to <c>21</c>, the equality test + succeeds and the match continues until the end of the pattern.</p> + </item> + <item> + <p>If the end of the pattern is reached, the match succeeds and you + can retrieve the contents of the variable.</p> + </item> </list> + <code type="none"><![CDATA[ ETERM *pattern,*term; pattern = erl_format("{madonna,Age,Age}"); @@ -239,99 +322,136 @@ if (erl_match(pattern, term)) { } erl_free_term(pattern); erl_free_term(term); ]]></code> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_match()]]></c> function for - more information.</p> + + <p>For more information, see the + <seealso marker="erl_format#erl_match"> + <c>erl_format:erl_match</c></seealso> function.</p> </section> <section> <title>Connecting to a Distributed Erlang Node</title> - <p>In order to connect to a distributed Erlang node you need to first - initialize the connection routine with <c><![CDATA[erl_connect_init()]]></c>, - which stores information such as the host name, node name, and IP + <p>To connect to a distributed Erlang node, you must first + initialize the connection routine with + <seealso marker="erl_connect#erl_connect_init"> + <c>erl_connect:erl_connect_init</c></seealso>, + which stores information, such as the hostname, node name, and IP address for later use:</p> + <code type="none"><![CDATA[ int identification_number = 99; int creation=1; char *cookie="a secret cookie string"; /* An example */ erl_connect_init(identification_number, cookie, creation); ]]></code> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_connect]]></c> module for more information.</p> + + <p>For more information, see the + <seealso marker="erl_connect"><c>erl_connect</c></seealso> module.</p> + <p>After initialization, you set up the connection to the Erlang node. - Use <c><![CDATA[erl_connect()]]></c> to specify the Erlang node you want to - connect to. The following example sets up the connection and should - result in a valid socket file descriptor:</p> + To specify the Erlang node you want to connect to, use + <c>erl_connect()</c>. The following example sets up the + connection and is to result in a valid socket file descriptor:</p> + <code type="none"><![CDATA[ int sockfd; char *nodename="[email protected]"; /* An example */ if ((sockfd = erl_connect(nodename)) < 0) erl_err_quit("ERROR: erl_connect failed"); ]]></code> - <p><c><![CDATA[erl_err_quit()]]></c> prints the specified string and terminates - the program. Refer to the Reference Manual, the <c><![CDATA[erl_error()]]></c> - function for more information.</p> + + <p><c>erl_err_quit()</c> prints the specified string and + terminates the program. For more information, see the + <seealso marker="erl_error"><c>erl_error</c></seealso> module.</p> </section> <section> <title>Using EPMD</title> - <p><c><![CDATA[Epmd]]></c> is the Erlang Port Mapper Daemon. Distributed Erlang nodes - register with <c><![CDATA[epmd]]></c> on the localhost to indicate to other nodes that - they exist and can accept connections. <c><![CDATA[Epmd]]></c> maintains a register of + <p><seealso marker="erts:epmd"><c>erts:epmd</c></seealso> + is the Erlang Port Mapper Daemon. Distributed + Erlang nodes register with <c>epmd</c> on the local host to + indicate to other nodes that they exist and can accept connections. + <c>epmd</c> maintains a register of node and port number information, and when a node wishes to connect to - another node, it first contacts <c><![CDATA[epmd]]></c> in order to find out the correct - port number to connect to.</p> - <p>When you use <c><![CDATA[erl_connect()]]></c> to connect to an Erlang node, a - connection is first made to <c><![CDATA[epmd]]></c> and, if the node is known, a + another node, it first contacts <c>epmd</c> to find the + correct port number to connect to.</p> + + <p>When you use + <seealso marker="erl_connect"><c>erl_connect</c></seealso> + to connect to an Erlang node, a connection is first made to + <c>epmd</c> and, if the node is known, a connection is then made to the Erlang node.</p> - <p>C nodes can also register themselves with <c><![CDATA[epmd]]></c> if they want other + + <p>C nodes can also register themselves with <c>epmd</c> + if they want other nodes in the system to be able to find and connect to them.</p> - <p>Before registering with <c><![CDATA[epmd]]></c>, you need to first create a listen socket - and bind it to a port. Then:</p> + + <p>Before registering with <c>epmd</c>, you must first + create a listen socket and bind it to a port. Then:</p> + <code type="none"><![CDATA[ int pub; pub = erl_publish(port); ]]></code> - <p><c><![CDATA[pub]]></c> is a file descriptor now connected to <c><![CDATA[epmd]]></c>. <c><![CDATA[Epmd]]></c> - monitors the other end of the connection, and if it detects that the - connection has been closed, the node will be unregistered. So, if you - explicitly close the descriptor or if your node fails, it will be - unregistered from <c><![CDATA[epmd]]></c>.</p> - <p>Be aware that on some systems (such as VxWorks), a failed node will - not be detected by this mechanism since the operating system does not + + <p><c>pub</c> is a file descriptor now connected to + <c>epmd</c>. <c>epmd</c> + monitors the other end of the connection. If it detects that the + connection has been closed, the node becomes unregistered. So, if you + explicitly close the descriptor or if your node fails, it becomes + unregistered from <c>epmd</c>.</p> + + <p>Notice that on some systems (such as VxWorks), a failed node is + not detected by this mechanism, as the operating system does not automatically close descriptors that were left open when the node - failed. If a node has failed in this way, <c><![CDATA[epmd]]></c> will prevent you from - registering a new node with the old name, since it thinks that the old + failed. If a node has failed in this way, <c>epmd</c> + prevents you from + registering a new node with the old name, as it thinks that the old name is still in use. In this case, you must unregister the name explicitly:</p> + <code type="none"><![CDATA[ erl_unpublish(node); ]]></code> - <p>This will cause <c><![CDATA[epmd]]></c> to close the connection from the far end. Note + + <p>This causes <c>epmd</c> to close the connection from the + far end. Notice that if the name was in fact still in use by a node, the results of this operation are unpredictable. Also, doing this does not cause the - local end of the connection to close, so resources may be consumed.</p> + local end of the connection to close, so resources can be consumed.</p> </section> <section> <title>Sending and Receiving Erlang Messages</title> <p>Use one of the following two functions to send messages:</p> + <list type="bulleted"> - <item><c><![CDATA[erl_send()]]></c></item> - <item><c><![CDATA[erl_reg_send()]]></c></item> + <item><seealso marker="erl_connect#erl_send"> + <c>erl_connect:erl_send</c></seealso></item> + <item><seealso marker="erl_connect#erl_reg_send"> + <c>erl_connect:erl_reg_send</c></seealso></item> </list> - <p>As in Erlang, it is possible to send messages to a - <em>Pid</em> or to a registered name. It is easier to send a - message to a registered name because it avoids the problem of finding - a suitable <em>Pid</em>.</p> + + <p>As in Erlang, messages can be sent to a + pid or to a registered name. It is easier to send a + message to a registered name, as it avoids the problem of finding + a suitable pid.</p> + <p>Use one of the following two functions to receive messages:</p> + <list type="bulleted"> - <item><c><![CDATA[erl_receive()]]></c></item> - <item><c><![CDATA[erl_receive_msg()]]></c></item> + <item><seealso marker="erl_connect#erl_receive"> + <c>erl_connect:erl_receive</c></seealso></item> + <item><seealso marker="erl_connect#erl_receive_msg"> + <c>erl_connect:erl_receive_msg</c></seealso></item> </list> - <p><c><![CDATA[erl_receive()]]></c> receives the message into a buffer, while - <c><![CDATA[erl_receive_msg()]]></c> decodes the message into an Erlang term. </p> + + <p><c>erl_receive()</c> receives the message into a buffer, + while <c>erl_receive_msg()</c> decodes the message into an + Erlang term.</p> <section> <title>Example of Sending Messages</title> - <p>In the following example, <c><![CDATA[{Pid, hello_world}]]></c> is - sent to a registered process <c><![CDATA[my_server]]></c>. The message is encoded - by <c><![CDATA[erl_send()]]></c>:</p> + <p>In the following example, <c>{Pid, hello_world}</c> is + sent to a registered process <c>my_server</c>. The message + is encoded by <c>erl_send()</c>:</p> + <code type="none"><![CDATA[ extern const char *erl_thisnodename(void); extern short erl_thiscreation(void); @@ -345,16 +465,19 @@ emsg = erl_mk_tuple(arr, 2); erl_reg_send(sockfd, "my_server", emsg); erl_free_term(emsg); ]]></code> + <p>The first element of the tuple that is sent is your own - <em>Pid</em>. This enables <c><![CDATA[my_server]]></c> to reply. Refer to the - Reference Manual, the <c><![CDATA[erl_connect]]></c> module for more information - about send primitives.</p> + pid. This enables <c>my_server</c> to reply. + For more information about the primitives, see the + <seealso marker="erl_connect"><c>erl_connect</c></seealso> module.</p> </section> <section> <title>Example of Receiving Messages</title> - <p>In this example <c><![CDATA[{Pid, Something}]]></c> is received. The - received Pid is then used to return <c><![CDATA[{goodbye,Pid}]]></c></p> + <p>In this example, <c>{Pid, Something}</c> is received. The + received pid is then used to return + <c>{goodbye,Pid}</c>.</p> + <code type="none"><![CDATA[ ETERM *arr[2], *answer; int sockfd,rc; @@ -370,22 +493,25 @@ if ((rc = erl_receive_msg(sockfd , buf, BUFSIZE, &emsg)) == ERL_MSG) { erl_free_term(emsg.msg); erl_free_term(emsg.to); } ]]></code> - <p>In order to provide robustness, a distributed Erlang node - occasionally polls all its connected neighbours in an attempt to - detect failed nodes or communication links. A node which receives such - a message is expected to respond immediately with an <c><![CDATA[ERL_TICK]]></c> message. - This is done automatically by <c><![CDATA[erl_receive()]]></c>, however when this - has occurred <c><![CDATA[erl_receive]]></c> returns <c><![CDATA[ERL_TICK]]></c> to the caller - without storing a message into the <c><![CDATA[ErlMessage]]></c> structure.</p> + + <p>To provide robustness, a distributed Erlang node + occasionally polls all its connected neighbors in an attempt to + detect failed nodes or communication links. A node that receives such + a message is expected to respond immediately with an + <c>ERL_TICK</c> message. This is done automatically by + <c>erl_receive()</c>. However, when this has occurred, + <c>erl_receive</c> returns <c>ERL_TICK</c> to + the caller without storing a message into the + <c>ErlMessage</c> structure.</p> + <p>When a message has been received, it is the caller's responsibility - to free the received message <c><![CDATA[emsg.msg]]></c> as well as <c><![CDATA[emsg.to]]></c> - or <c><![CDATA[emsg.from]]></c>, depending on the type of message received.</p> - <p>Refer to the Reference Manual for additional information about the - following modules:</p> - <list type="bulleted"> - <item><c><![CDATA[erl_connect]]></c></item> - <item><c><![CDATA[erl_eterm]]></c>.</item> - </list> + to free the received message <c>emsg.msg</c> and + <c>emsg.to</c> or <c>emsg.from</c>, + depending on the type of message received.</p> + + <p>For more information, see the + <seealso marker="erl_connect"><c>erl_connect</c></seealso> and + <seealso marker="erl_eterm"><c>erl_eterm</c></seealso> modules.</p> </section> </section> @@ -394,10 +520,12 @@ if ((rc = erl_receive_msg(sockfd , buf, BUFSIZE, &emsg)) == ERL_MSG) { <p>An Erlang node acting as a client to another Erlang node typically sends a request and waits for a reply. Such a request is included in a function call at a remote node and is called a remote - procedure call. The following example shows how the - Erl_Interface library supports remote procedure calls:</p> - <code type="none"><![CDATA[ + procedure call.</p> + <p>The following example shows how the + <c>Erl_Interface</c> library supports remote procedure calls:</p> + + <code type="none"><![CDATA[ char modname[]=THE_MODNAME; ETERM *reply,*ep; ep = erl_format("[~a,[]]", modname); @@ -409,26 +537,34 @@ if (!erl_match(ep, reply)) erl_err_msg("<ERROR> compiler errors !\n"); erl_free_term(ep); erl_free_term(reply); ]]></code> - <p><c><![CDATA[c:c/1]]></c> is called to compile the specified module on the - remote node. <c><![CDATA[erl_match()]]></c> checks that the compilation was - successful by testing for the expected <c><![CDATA[ok]]></c>.</p> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_connect]]></c> module for - more information about <c><![CDATA[erl_rpc()]]></c>, and its companions - <c><![CDATA[erl_rpc_to()]]></c> and <c><![CDATA[erl_rpc_from()]]></c>.</p> + + <p><c>c:c/1</c> is called to compile the specified module on + the remote node. <c>erl_match()</c> checks that the + compilation was + successful by testing for the expected <c>ok</c>.</p> + + <p>For more information about <c>erl_rpc()</c> and its + companions <c>erl_rpc_to()</c> and + <c>erl_rpc_from()</c>, see the + <seealso marker="erl_connect"><c>erl_connect</c></seealso> module.</p> </section> <section> <title>Using Global Names</title> - <p>A C node has access to names registered through the Erlang Global - module. Names can be looked up, allowing the C node to send messages + <p>A C node has access to names registered through the + <seealso marker="kernel:global"><c>global</c></seealso> + module in Kernel. Names can be looked up, allowing the C node to send messages to named Erlang services. C nodes can also register global names, allowing them to provide named services to Erlang processes or other C - nodes. </p> - <p>Erl_Interface does not provide a native implementation of the global - service. Instead it uses the global services provided by a "nearby" - Erlang node. In order to use the services described in this section, + nodes.</p> + + <p><c>Erl_Interface</c> does not provide a native implementation of the + global service. Instead it uses the global services provided by a "nearby" + Erlang node. To use the services described in this section, it is necessary to first open a connection to an Erlang node.</p> + <p>To see what names there are:</p> + <code type="none"><![CDATA[ char **names; int count; @@ -441,71 +577,102 @@ if (names) printf("%s\n",names[i]); free(names); ]]></code> - <p><c><![CDATA[erl_global_names()]]></c> allocates and returns a buffer containing - all the names known to global. <c><![CDATA[count]]></c> will be initialized to - indicate how many names are in the array. The array of strings in - names is terminated by a NULL pointer, so it is not necessary to use - <c><![CDATA[count]]></c> to determine when the last name is reached.</p> + + <p><seealso marker="erl_global#erl_global_names"> + <c>erl_global:erl_global_names</c></seealso> + allocates and returns a buffer containing + all the names known to the <c>global</c> module in <c>Kernel</c>. + <c>count</c> is initialized to + indicate the number of names in the array. The array of strings in names + is terminated by a <c>NULL</c> pointer, so it is not necessary to use + <c>count</c> to determine when the last name is reached.</p> + <p>It is the caller's responsibility to free the array. - <c><![CDATA[erl_global_names()]]></c> allocates the array and all of the strings - using a single call to <c><![CDATA[malloc()]]></c>, so <c><![CDATA[free(names)]]></c> is all - that is necessary.</p> + <c>erl_global_names</c> allocates the array and all the strings + using a single call to <c>malloc()</c>, so + <c>free(names)</c> is all that is necessary.</p> + <p>To look up one of the names:</p> + <code type="none"><![CDATA[ ETERM *pid; char node[256]; pid = erl_global_whereis(fd,"schedule",node); ]]></code> - <p>If <c><![CDATA["schedule"]]></c> is known to global, an Erlang pid is returned - that can be used to send messages to the schedule service. - Additionally, <c><![CDATA[node]]></c> will be initialized to contain the name of + + <p>If <c>"schedule"</c> is known to the + <c>global</c> module in <c>Kernel</c>, an Erlang pid is + returned that can be used to send messages to the schedule service. + Also, <c>node</c> is initialized to contain the name of the node where the service is registered, so that you can make a - connection to it by simply passing the variable to <c><![CDATA[erl_connect()]]></c>.</p> + connection to it by simply passing the variable to + <seealso marker="erl_connect"><c>erl_connect</c></seealso>.</p> + <p>Before registering a name, you should already have registered your - port number with <c><![CDATA[epmd]]></c>. This is not strictly necessary, but if you + port number with <c>epmd</c>. This is not strictly necessary, + but if you neglect to do so, then other nodes wishing to communicate with your - service will be unable to find or connect to your process.</p> + service cannot find or connect to your process.</p> + <p>Create a pid that Erlang processes can use to communicate with your service:</p> + <code type="none"><![CDATA[ ETERM *pid; pid = erl_mk_pid(thisnode,14,0,0); erl_global_register(fd,servicename,pid); ]]></code> - <p>After registering the name, you should use <c><![CDATA[erl_accept()]]></c> to wait for - incoming connections.</p> - <p>Do not forget to free <c><![CDATA[pid]]></c> later with <c><![CDATA[erl_free_term()]]></c>!</p> + + <p>After registering the name, use + <seealso marker="erl_connect#erl_accept"> + <c>erl_connect:erl_accept</c></seealso> + to wait for incoming connections.</p> + + <note> + <p>Remember to free <c>pid</c> later with + <seealso marker="erl_malloc#erl_free_term"> + <c>erl_malloc:erl_free_term</c></seealso>.</p> + </note> + <p>To unregister a name:</p> + <code type="none"><![CDATA[ erl_global_unregister(fd,servicename); ]]></code> </section> <section> - <title>The Registry</title> + <title>Using the Registry</title> <p>This section describes the use of the registry, a simple mechanism for storing key-value pairs in a C-node, as well as backing them up or - restoring them from a Mnesia table on an Erlang node. More detailed - information about the individual API functions can be found in the - Reference Manual.</p> - <p>Keys are strings, i.e. 0-terminated arrays of characters, and values - are arbitrary objects. Although integers and floating point numbers + restoring them from an <c>Mnesia</c> table on an Erlang node. For more + detailed information about the individual API functions, see the + <seealso marker="registry"><c>registry</c></seealso> module.</p> + + <p>Keys are strings, that is, <c>NULL</c>-terminated arrays of characters, and + values are arbitrary objects. Although integers and floating point numbers are treated specially by the registry, you can store strings or binary objects of any type as pointers.</p> - <p>To start, you need to open a registry:</p> + + <p>To start, open a registry:</p> + <code type="none"><![CDATA[ ei_reg *reg; reg = ei_reg_open(45); ]]></code> - <p>The number 45 in the example indicates the approximate number of + + <p>The number <c>45</c> in the example indicates the approximate number of objects that you expect to store in the registry. Internally the registry uses hash tables with collision chaining, so there is no absolute upper limit on the number of objects that the registry can - contain, but if performance or memory usage are important, then you - should choose a number accordingly. The registry can be resized later.</p> + contain, but if performance or memory usage is important, then you + are to choose a number accordingly. The registry can be resized later.</p> + <p>You can open as many registries as you like (if memory permits).</p> - <p>Objects are stored and retrieved through set and get functions. In - the following examples you see how to store integers, floats, strings + + <p>Objects are stored and retrieved through set and get functions. + The following example shows how to store integers, floats, strings, and arbitrary binary objects:</p> + <code type="none"><![CDATA[ struct bonk *b = malloc(sizeof(*b)); char *name = malloc(7); @@ -519,13 +686,16 @@ ei_reg_setsval(reg,"name",name); b->l = 42; b->m = 12; ei_reg_setpval(reg,"jox",b,sizeof(*b)); ]]></code> - <p>If you attempt to store an object in the registry and there is an - existing object with the same key, the new value will replace the old + + <p>If you try to store an object in the registry and there is an + existing object with the same key, the new value replaces the old one. This is done regardless of whether the new object and the old one have the same type, so you can, for example, replace a string with an - integer. If the existing value is a string or binary, it will be freed + integer. If the existing value is a string or binary, it is freed before the new value is assigned.</p> + <p>Stored values are retrieved from the registry as follows:</p> + <code type="none"><![CDATA[ long i; double f; @@ -537,77 +707,100 @@ i = ei_reg_getival(reg,"age"); f = ei_reg_getfval(reg,"height"); s = ei_reg_getsval(reg,"name"); b = ei_reg_getpval(reg,"jox",&size); ]]></code> - <p>In all of the above examples, the object must exist and it must be of + + <p>In all the above examples, the object must exist and it must be of the right type for the specified operation. If you do not know the - type of a given object, you can ask:</p> + type of an object, you can ask:</p> + <code type="none"><![CDATA[ struct ei_reg_stat buf; ei_reg_stat(reg,"name",&buf); ]]></code> - <p>Buf will be initialized to contain object attributes.</p> + + <p>Buf is initialized to contain object attributes.</p> + <p>Objects can be removed from the registry:</p> + <code type="none"><![CDATA[ ei_reg_delete(reg,"name"); ]]></code> + <p>When you are finished with a registry, close it to remove all the objects and free the memory back to the system:</p> + <code type="none"><![CDATA[ ei_reg_close(reg); ]]></code> <section> <title>Backing Up the Registry to Mnesia</title> - <p>The contents of a registry can be backed up to Mnesia on a "nearby" - Erlang node. You need to provide an open connection to the Erlang node - (see <c><![CDATA[erl_connect()]]></c>). Also, Mnesia 3.0 or later must be running + <p>The contents of a registry can be backed up to + <seealso marker="mnesia:mnesia"><c>Mnesia</c></seealso> on a "nearby" Erlang + node. You must provide an open connection to the Erlang node + (see <seealso marker="erl_connect"><c>erl_connect</c></seealso>). + Also, <c>Mnesia</c> 3.0 or later must be running on the Erlang node before the backup is initiated:</p> + <code type="none"><![CDATA[ ei_reg_dump(fd, reg, "mtab", dumpflags); ]]></code> - <p>The example above will backup the contents of the registry to the - specified Mnesia table <c><![CDATA["mtab"]]></c>. Once a registry has been backed - up to Mnesia in this manner, additional backups will only affect - objects that have been modified since the most recent backup, i.e. - objects that have been created, changed or deleted. The backup - operation is done as a single atomic transaction, so that the entire - backup will be performed or none of it will.</p> - <p>In the same manner, a registry can be restored from a Mnesia table:</p> + + <p>This example back up the contents of the registry to the + specified <c>Mnesia</c> table <c>"mtab"</c>. + Once a registry has been backed + up to <c>Mnesia</c> like this, more backups only affect + objects that have been modified since the most recent backup, that is, + objects that have been created, changed, or deleted. The backup + operation is done as a single atomic transaction, so that either the + entire backup is performed or none of it.</p> + + <p>Likewise, a registry can be restored from a <c>Mnesia</c> table:</p> + <code type="none"><![CDATA[ ei_reg_restore(fd, reg, "mtab"); ]]></code> - <p>This will read the entire contents of <c><![CDATA["mtab"]]></c> into the specified - registry. After the restore, all of the objects in the registry will - be marked as unmodified, so a subsequent backup will only affect + + <p>This reads the entire contents of <c>"mtab"</c> into the + specified registry. After the restore, all the objects in the registry + are marked as unmodified, so a later backup only affects objects that you have modified since the restore.</p> - <p>Note that if you restore to a non-empty registry, objects in the - table will overwrite objects in the registry with the same keys. Also, + + <p>Notice that if you restore to a non-empty registry, objects in the + table overwrite objects in the registry with the same keys. Also, the <em>entire</em> contents of the registry is marked as unmodified after the restore, including any modified objects that were not - overwritten by the restore operation. This may not be your intention.</p> + overwritten by the restore operation. This may not be your + intention.</p> </section> <section> <title>Storing Strings and Binaries</title> <p>When string or binary objects are stored in the registry it is - important that a number of simple guidelines are followed. </p> + important that some simple guidelines are followed.</p> + <p>Most importantly, the object must have been created with a single call - to <c><![CDATA[malloc()]]></c> (or similar), so that it can later be removed by a - single call to <c><![CDATA[free()]]></c>. Objects will be freed by the registry + to <c>malloc()</c> (or similar), so that it can later be + removed by a single call to <c>free()</c>. + Objects are freed by the registry when it is closed, or when you assign a new value to an object that previously contained a string or binary.</p> - <p>You should also be aware that if you store binary objects that are - context-dependent (e.g. containing pointers or open file descriptors), - they will lose their meaning if they are backed up to a Mnesia table - and subsequently restored in a different context.</p> + + <p>Notice that if you store binary objects that are context-dependent + (for example, containing pointers or open file descriptors), + they lose their meaning if they are backed up to a <c>Mnesia</c> table + and later restored in a different context.</p> + <p>When you retrieve a stored string or binary value from the registry, the registry maintains a pointer to the object and you are passed a copy of that pointer. You should never free an object retrieved in this manner because when the registry later attempts to free it, a - runtime error will occur that will likely cause the C-node to crash.</p> + runtime error occurs that likely causes the C-node to crash.</p> + <p>You are free to modify the contents of an object retrieved this way. - However when you do so, the registry will not be aware of the changes - you make, possibly causing it to be missed the next time you make a - Mnesia backup of the registry contents. This can be avoided if you - mark the object as dirty after any such changes with - <c><![CDATA[ei_reg_markdirty()]]></c>, or pass appropriate flags to - <c><![CDATA[ei_reg_dump()]]></c>.</p> + However, when you do so, the registry is not aware of your changes, + possibly causing it to be missed the next time you make an + <c>Mnesia</c> backup of the registry contents. This can be avoided if + you mark the object as dirty after any such changes with + <seealso marker="registry#ei_reg_markdirty"> + <c>registry:ei_reg_markdirty</c></seealso>, or pass appropriate flags to + <seealso marker="registry#ei_reg_dump"> + <c>registry:ei_reg_dump</c></seealso>.</p> </section> </section> </chapter> - diff --git a/lib/erl_interface/doc/src/erl_call.xml b/lib/erl_interface/doc/src/erl_call.xml index 46015621ac..f1e52b1889 100644 --- a/lib/erl_interface/doc/src/erl_call.xml +++ b/lib/erl_interface/doc/src/erl_call.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -28,135 +28,146 @@ <docno></docno> <approved>Bjarne Däcker</approved> <checked>Torbjörn Törnkvist</checked> - <date>97-05-16</date> + <date>1997-05-16</date> <rev>B</rev> - <file>erl_call.sgml</file> + <file>erl_call.xml</file> </header> <com>erl_call</com> - <comsummary>Call/Start a Distributed Erlang Node</comsummary> + <comsummary>Call/start a distributed Erlang node.</comsummary> <description> - <p><c><![CDATA[erl_call]]></c> makes it possible to start and/or communicate with - a distributed Erlang node. It is built upon the <c><![CDATA[erl_interface]]></c> - library as an example application. Its purpose is to use an Unix shell script to interact with a distributed Erlang node. It performs all - communication with the Erlang <em>rex server</em>, using the standard Erlang RPC facility. It does not require any special - software to be run at the Erlang target node.</p> + <p><c>erl_call</c> makes it possible to start and/or + communicate with a distributed Erlang node. It is built upon the + <c>Erl_Interface</c> library as an example application. + Its purpose is to use a Unix shell script to interact with a distributed + Erlang node. It performs all communication with the Erlang + <em>rex server</em>, using the standard Erlang RPC facility. It does not + require any special software to be run at the Erlang target node.</p> + <p>The main use is to either start a distributed Erlang node or to make an ordinary function call. However, it is also - possible to pipe an Erlang module to <c><![CDATA[erl_call]]></c> and have it - compiled, or to pipe a sequence of Erlang expressions to be evaluated + possible to pipe an Erlang module to <c>erl_call</c> and have + it compiled, or to pipe a sequence of Erlang expressions to be evaluated (similar to the Erlang shell).</p> - <p>Options, which cause <c><![CDATA[stdin]]></c> to be read, can be used with - advantage - as scripts from within (Unix) shell scripts. Another - nice use of <c><![CDATA[erl_call]]></c> could be from (http) CGI-bin scripts.</p> + + <p>Options, which cause <c>stdin</c> to be read, can be used + with advantage, + as scripts from within (Unix) shell scripts. Another nice use + of <c>erl_call</c> could be from (HTTP) CGI-bin scripts.</p> </description> + <funcs> <func> <name>erl_call <options></name> - <fsummary>Start/Call Erlang</fsummary> + <fsummary>Start/call Erlang.</fsummary> <desc> - <p>Each option flag is described below with its name, type and - meaning. </p> + <p>Starts/calls Erlang.</p> + <p>Each option flag is described below with its name, type, and + meaning.</p> <taglist> - <tag>-a [Mod [Fun [Args]]]]</tag> + <tag><c>-a [Mod [Fun [Args]]]]</c></tag> <item> - <p>(<em>optional</em>): Applies the specified function - and returns the result. <c><![CDATA[Mod]]></c> must be specified, however - <c>start</c> and <c>[]</c> are assumed for unspecified <c><![CDATA[Fun]]></c> and <c><![CDATA[Args]]></c>, respectively. <c><![CDATA[Args]]></c> should - be in the same format as for <c><![CDATA[erlang:apply/3]]></c>. Note - that this flag takes exactly one argument, so quoting - may be necessary in order to group <c><![CDATA[Mod]]></c>, <c><![CDATA[Fun]]></c> - and <c><![CDATA[Args]]></c>, in a manner dependent on the behavior - of your command shell.</p> - <p></p> + <p>(<em>Optional.</em>) Applies the specified function + and returns the result. <c>Mod</c> must be specified. + However, <c>start</c> and <c>[]</c> are assumed for unspecified + <c>Fun</c> and <c>Args</c>, respectively. + <c>Args</c> is to be in the same format as for + <seealso marker="erts:erlang#apply/3"> + <c>erlang:apply/3</c></seealso> in <c>ERTS</c>.</p> + <p>Notice that this flag takes exactly one argument, so quoting + can be necessary to group <c>Mod</c>, + <c>Fun</c>, and <c>Args</c> in a manner + dependent on the behavior of your command shell.</p> </item> - <tag>-c Cookie</tag> + <tag><c>-c Cookie</c></tag> <item> - <p>(<em>optional</em>): Use this option to specify a certain cookie. If no cookie is specified, the <c><![CDATA[~/.erlang.cookie]]></c> file is read and its content are used as cookie. The Erlang node we want to communicate with must have the same cookie.</p> + <p>(<em>Optional.</em>) Use this option to specify a certain cookie. + If no cookie is specified, the <c>~/.erlang.cookie</c> + file is read and its content is used as cookie. The Erlang node + we want to communicate with must have the same cookie.</p> </item> - <tag>-d</tag> + <tag><c>-d</c></tag> <item> - <p>(<em>optional</em>): Debug mode. This causes all IO to be output - to the file <c><![CDATA[~/.erl_call.out.Nodename]]></c>, where <c><![CDATA[Nodename]]></c> + <p>(<em>Optional.</em>) Debug mode. This causes all I/O to be output + to the <c>~/.erl_call.out.Nodename</c> file, where + <c>Nodename</c> is the node name of the Erlang node in question.</p> - <p></p> </item> - <tag>-e</tag> + <tag><c>-e</c></tag> <item> - <p>(<em>optional</em>): Reads a sequence of Erlang expressions, separated - by '<em>,</em>' and ended with a '<em>.</em>', from <c><![CDATA[stdin]]></c> until - EOF (Control-D). Evaluates the expressions and returns the result from - the last expression. Returns <c><![CDATA[{ok,Result}]]></c> if successful.</p> - <p></p> + <p>(<em>Optional.</em>) Reads a sequence of Erlang expressions, + separated by comma (,) and ended with a full stop (.), from + <c>stdin</c> until EOF (Control-D). Evaluates the + expressions and returns the result from the last expression. + Returns <c>{ok,Result}</c> on success.</p> </item> - <tag>-h HiddenName</tag> + <tag><c>-h HiddenName</c></tag> <item> - <p>(<em>optional</em>): Specifies the name of the hidden node - that <c><![CDATA[erl_call]]></c> represents.</p> - <p></p> + <p>(<em>Optional.</em>) Specifies the name of the hidden node + that <c>erl_call</c> represents.</p> </item> - <tag>-m</tag> + <tag><c>-m</c></tag> <item> - <p>(<em>optional</em>): Reads an Erlang module from <c><![CDATA[stdin]]></c> and - compiles it.</p> - <p></p> + <p>(<em>Optional.</em>) Reads an Erlang module from + <c>stdin</c> and compiles it.</p> </item> - <tag>-n Node</tag> + <tag><c>-n Node</c></tag> <item> - <p>(one of <c><![CDATA[-n, -name, -sname]]></c> is required): - Has the same meaning as <c><![CDATA[-name]]></c> and can still be used for - backwards compatibility reasons.</p> - <p></p> + <p>(One of <c>-n, -name, -sname</c> is required.) + Has the same meaning as <c>-name</c> and can still be + used for backward compatibility reasons.</p> </item> - <tag>-name Node</tag> + <tag><c>-name Node</c></tag> <item> - <p>(one of <c><![CDATA[-n, -name, -sname]]></c> is required): <c><![CDATA[Node]]></c> is the name of the node to be - started or communicated with. It is assumed that - <c><![CDATA[Node]]></c> is started with <c><![CDATA[erl -name]]></c>, which means that fully - qualified long node names are used. - If the <c><![CDATA[-s]]></c> option is given, an Erlang node will (if necessary) - be started with <c><![CDATA[erl -name]]></c>.</p> - <p></p> + <p>(One of <c>-n, -name, -sname</c> is required.) + <c>Node</c> is the name of the node to be + started or communicated with. It is assumed that + <c>Node</c> is started with + <c>erl -name</c>, which means that fully + qualified long node names are used. If option + <c>-s</c> is specified, an Erlang node will (if + necessary) be started with <c>erl -name</c>.</p> </item> - <tag>-q</tag> + <tag><c>-q</c></tag> <item> - <p>(<em>optional</em>): Halts the Erlang node specified - with the -n switch. This switch overrides the -s switch.</p> - <p></p> + <p>(<em>Optional.</em>) Halts the Erlang node specified + with switch <c>-n</c>. This switch overrides switch <c>-s</c>.</p> </item> - <tag>-r</tag> + <tag><c>-r</c></tag> <item> - <p>(<em>optional</em>): Generates a random name of the hidden node - that <c><![CDATA[erl_call]]></c> represents.</p> - <p></p> + <p>(<em>Optional.</em>) Generates a random name of the hidden node + that <c>erl_call</c> represents.</p> </item> - <tag>-s</tag> + <tag><c>-s</c></tag> <item> - <p>(<em>optional</em>): Starts a distributed Erlang node if necessary. - This means that in a sequence of calls, where the '<c><![CDATA[-s]]></c>' - and '<c><![CDATA[-n Node]]></c>' are constant, only the first call will start - the Erlang node. This makes the rest of the communication - very fast. This flag is currently only available on the Unix platform.</p> - <p></p> + <p>(<em>Optional.</em>) Starts a distributed Erlang node if + necessary. This means that in a sequence of calls, where + '<c>-s</c>' and '<c>-n Node</c>' are + constant, only the first call starts the Erlang node. This makes + the rest of the communication very fast. This flag is currently + only available on Unix-like platforms (Linux, Mac OS X, Solaris, + and so on).</p> </item> - <tag>-sname Node</tag> + <tag><c>-sname Node</c></tag> <item> - <p>(one of <c><![CDATA[-n, -name, -sname]]></c> is required): <c><![CDATA[Node]]></c> is the name of the node to - be started or communicated with. It is assumed that <c><![CDATA[Node]]></c> is started with <c><![CDATA[erl -sname]]></c> which means that short node names are used. - If <c><![CDATA[-s]]></c> option is given, an Erlang node will be started (if necessary) with <c><![CDATA[erl -sname]]></c>.</p> - <p></p> + <p>(One of <c>-n, -name, -sname</c> is required.) + <c>Node</c> is the name of the node to be started + or communicated with. It is assumed that <c>Node</c> + is started with <c>erl -sname</c>, which means that + short node names are used. If option <c>-s</c> is + specified, an Erlang node is started (if necessary) with + <c>erl -sname</c>.</p> </item> - <tag>-v</tag> + <tag><c>-v</c></tag> <item> - <p>(<em>optional</em>): Prints a lot of <c><![CDATA[verbose]]></c> information. - This is only useful for the developer and maintainer of <c><![CDATA[erl_call]]></c>.</p> - <p></p> + <p>(<em>Optional.</em>) Prints a lot of <c>verbose</c> + information. This is only useful for the developer and maintainer + of <c>erl_call</c>.</p> </item> - <tag>-x ErlScript</tag> + <tag><c>-x ErlScript</c></tag> <item> - <p>(<em>optional</em>): Specifies another name of the Erlang start-up script - to be used. If not specified, the standard <c><![CDATA[erl]]></c> start-up script - is used.</p> + <p>(<em>Optional.</em>) Specifies another name of the Erlang + startup script to be used. If not specified, the standard + <c>erl</c> startup script is used.</p> </item> </taglist> </desc> @@ -165,20 +176,29 @@ <section> <title>Examples</title> - <p>Starts an Erlang node and calls <c><![CDATA[erlang:time/0]]></c>.</p> + <p>To start an Erlang node and call <c>erlang:time/0</c>:</p> + <code type="none"><![CDATA[ erl_call -s -a 'erlang time' -n madonna {18,27,34} ]]></code> - <p>Terminates an Erlang node by calling <c><![CDATA[erlang:halt/0]]></c>.</p> + + <p>To terminate an Erlang node by calling + <c>erlang:halt/0</c>:</p> + <code type="none"><![CDATA[ erl_call -s -a 'erlang halt' -n madonna ]]></code> - <p>An apply with several arguments.</p> + + <p>To apply with many arguments:</p> + <code type="none"><![CDATA[ erl_call -s -a 'lists map [{math,sqrt},[1,4,9,16,25]]' -n madonna ]]></code> - <p>Evaluates a couple of expressions. <em>The input ends with EOF (Control-D)</em>.</p> + + <p>To evaluate some expressions + (<em>the input ends with EOF (Control-D)</em>):</p> + <code type="none"><![CDATA[ erl_call -s -e -n madonna statistics(runtime), @@ -189,10 +209,14 @@ Y=2, ^D {ok,{3,0}} ]]></code> - <p>Compiles a module and runs it. <em>Again, the input ends with EOF (Control-D)</em>. (In the example shown, the output has been formatted afterwards).</p> + + <p>To compile a module and run it (<em>again, the input ends with EOF + (Control-D)</em>):</p> + <p>(In the example, the output has been formatted afterwards.)</p> + <code type="none"><![CDATA[ -erl_call -s -m -a lolita -n madonna --module(lolita). +erl_call -s -m -a procnames -n madonna +-module(procnames). -compile(export_all). start() -> P = processes(), @@ -238,4 +262,3 @@ start() -> ]]></code> </section> </comref> - diff --git a/lib/erl_interface/doc/src/erl_connect.xml b/lib/erl_interface/doc/src/erl_connect.xml index 0fad98cd17..76ef6588c2 100644 --- a/lib/erl_interface/doc/src/erl_connect.xml +++ b/lib/erl_interface/doc/src/erl_connect.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>erl_connect</title> @@ -28,127 +28,110 @@ <docno></docno> <approved>Bjarne Däcker</approved> <checked>Torbjörn Törnkvist</checked> - <date>980703</date> + <date>1998-07-03</date> <rev>A</rev> - <file>erl_connect.sgml</file> + <file>erl_connect.xml</file> </header> <lib>erl_connect</lib> - <libsummary>Communicate with Distributed Erlang</libsummary> + <libsummary>Communicate with distributed Erlang.</libsummary> <description> <p>This module provides support for communication between distributed - Erlang nodes and C nodes, in a manner that is transparent to Erlang + Erlang nodes and C-nodes, in a manner that is transparent to Erlang processes.</p> - <p>A C node appears to Erlang as a - <em>hidden node</em>. + + <p>A C-node appears to Erlang as a <em>hidden node</em>. That is, Erlang processes that know the name of the - C node are able to communicate with it in a normal manner, but - the node name will not appear in the listing provided by the - Erlang function <c><![CDATA[nodes/0]]></c>.</p> + C-node can communicate with it in a normal manner, but + the node name does not appear in the listing provided by + <seealso marker="erts:erlang#nodes/0"><c>erlang:nodes/0</c></seealso> + in <c>ERTS</c>.</p> </description> + <funcs> <func> - <name><ret>int</ret><nametext>erl_connect_init(number, cookie, creation)</nametext></name> - <name><ret>int</ret><nametext>erl_connect_xinit(host, alive, node, addr, cookie, creation)</nametext></name> - <fsummary>Initialize communication</fsummary> + <name><ret>int</ret><nametext>erl_accept(listensock, conp)</nametext></name> + <fsummary>Accept a connection.</fsummary> <type> - <v>int number;</v> - <v>char *cookie;</v> - <v>short creation;</v> - <v>char *host,*alive,*node;</v> - <v>struct in_addr *addr;</v> + <v>int listensock;</v> + <v>ErlConnect *conp;</v> </type> <desc> - <p>These functions initialize the <c><![CDATA[erl_connect]]></c> - module. In particular, they are used to identify the name of the - C-node from which they are called. One of these functions must - be called before any of the other functions in the erl_connect - module are used.</p> - <p><c><![CDATA[erl_connect_xinit()]]></c> stores for later use information about - the node's host name <c><![CDATA[host]]></c>, alive name <c><![CDATA[alive]]></c>, node - name <c><![CDATA[node]]></c>, IP address <c><![CDATA[addr]]></c>, cookie <c><![CDATA[cookie]]></c>, - and creation number <c><![CDATA[creation]]></c>. <c><![CDATA[erl_connect_init()]]></c> - provides an alternative interface which does not require as much - information from the caller. Instead, <c><![CDATA[erl_connect_init()]]></c> - uses <c><![CDATA[gethostbyname()]]></c> to obtain default values. - </p> - <p>If you use <c><![CDATA[erl_connect_init()]]></c> your node will have a - short name, i.e., it will not be fully qualified. If you need to - use fully qualified (a.k.a. long) names, use - <c><![CDATA[erl_connect_xinit()]]></c> instead. - </p> - <p><c><![CDATA[host]]></c> is the name of the host on which the node is running.</p> - <p><c><![CDATA[alive]]></c> is the alivename of the node.</p> - <p><c><![CDATA[node]]></c> is the name of the node. The nodename should - be of the form <em>alivename@hostname</em>.</p> - <p><c><![CDATA[addr]]></c> is the 32-bit IP address of <c><![CDATA[host]]></c>.</p> - <p><c><![CDATA[cookie]]></c> is the authorization string required for access - to the remote node. If NULL the user HOME directory is - searched for a cookie file <c><![CDATA[.erlang.cookie]]></c>. The path to - the home directory is retrieved from the environment variable - <c><![CDATA[HOME]]></c> on Unix and from the <c><![CDATA[HOMEDRIVE]]></c> and - <c><![CDATA[HOMEPATH]]></c> variables on Windows. Refer to the <c><![CDATA[auth]]></c> - module for more details.</p> - <p><c><![CDATA[creation]]></c> helps identify a particular instance of a C - node. In particular, it can help prevent us from receiving - messages sent to an earlier process with the same registered - name.</p> - <p>A C node acting as a server will be assigned a creation number - when it calls <c><![CDATA[erl_publish()]]></c>.</p> - <p><c><![CDATA[number]]></c> is used by <c><![CDATA[erl_connect_init()]]></c> to - construct the actual node name. In the second example shown - below, <em>"[email protected]"</em> will be the resulting node - name.</p> - <p>Example 1:</p> - <code type="none"><![CDATA[ -struct in_addr addr; -addr = inet_addr("150.236.14.75"); -if (!erl_connect_xinit("chivas", - "madonna", - "[email protected]", - &addr; - "samplecookiestring..."), - 0) - erl_err_quit("<ERROR> when initializing !"); - ]]></code> - <p>Example 2:</p> + <p>This function is used by a server process to accept a + connection from a client process.</p> + <list type="bulleted"> + <item><c>listensock</c> is an open socket descriptor on + which <c>listen()</c> has previously been called.</item> + <item><c>conp</c> is a pointer to an + <c>ErlConnect</c> struct, described as follows:</item> + </list> <code type="none"><![CDATA[ -if (!erl_connect_init(17, "samplecookiestring...", 0)) - erl_err_quit("<ERROR> when initializing !"); +typedef struct { + char ipadr[4]; + char nodename[MAXNODELEN]; +} ErlConnect; ]]></code> + <p>On success, <c>conp</c> is filled in with the address and + node name of the connecting client and a file descriptor is + returned. On failure, <c>ERL_ERROR</c> is returned and + <c>erl_errno</c> is set to <c>EIO</c>.</p> </desc> </func> + + <func> + <name><ret>int</ret><nametext>erl_close_connection(fd)</nametext></name> + <fsummary>Close a connection to an Erlang node.</fsummary> + <type> + <v>int fd;</v> + </type> + <desc> + <p>Closes an open connection to an Erlang node.</p> + <p><c>Fd</c> is a file descriptor obtained from + <c>erl_connect()</c> or + <c>erl_xconnect()</c>.</p> + <p>Returns <c>0</c> on success. If the call fails, a non-zero value + is returned, and the reason for the error can be obtained with the + appropriate platform-dependent call.</p> + </desc> + </func> + <func> <name><ret>int</ret><nametext>erl_connect(node)</nametext></name> <name><ret>int</ret><nametext>erl_xconnect(addr, alive)</nametext></name> - <fsummary>Establishe a connection to an Erlang node</fsummary> + <fsummary>Establish a connection to an Erlang node.</fsummary> <type> <v>char *node, *alive;</v> <v>struct in_addr *addr;</v> </type> <desc> - <p>These functions set up a connection to an Erlang node.</p> - <p><c><![CDATA[erl_xconnect()]]></c> requires the IP address of the remote - host and the alive name of the remote node - to be specified. <c><![CDATA[erl_connect()]]></c> provides an alternative + <p>Sets up a connection to an Erlang node.</p> + <p><c>erl_xconnect()</c> requires the IP address of the + remote host and the alivename of the remote node to be + specified. <c>erl_connect()</c> provides an alternative interface, and determines the information from the node name provided.</p> - <p><c><![CDATA[addr]]></c> is the 32-bit IP address of the remote host.</p> - <p><c><![CDATA[alive]]></c> is the alivename of the remote node.</p> - <p><c><![CDATA[node]]></c> is the name of the remote node.</p> - <p>These functions return an open file descriptor on success, or - a negative value indicating that an error occurred --- in - which case they will set <c><![CDATA[erl_errno]]></c> to one of:</p> + <list type="bulleted"> + <item><c>addr</c> is the 32-bit IP address of the remote + host.</item> + <item><c>alive</c> is the alivename of the remote node. + </item> + <item><c>node</c> is the name of the remote node.</item> + </list> + <p>Returns an open file descriptor on success, otherwise a negative + value. In the latter case <c>erl_errno</c> is set to one + of:</p> <taglist> - <tag><c><![CDATA[EHOSTUNREACH]]></c></tag> - <item>The remote host <c><![CDATA[node]]></c> is unreachable</item> - <tag><c><![CDATA[ENOMEM]]></c></tag> - <item>No more memory available.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EHOSTUNREACH</c></tag> + <item>The remote host <c>node</c> is unreachable.</item> + <tag><c>ENOMEM</c></tag> + <item>No more memory is available.</item> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> - <p>Additionally, <c><![CDATA[errno]]></c> values from - <c><![CDATA[socket]]></c><em>(2)</em> and <c><![CDATA[connect]]></c><em>(2)</em> - system calls may be propagated into <c><![CDATA[erl_errno]]></c>.</p> + <p>Also, <c>errno</c> values from + <c>socket</c><em>(2)</em> and + <c>connect</c><em>(2)</em> + system calls can be propagated into <c>erl_errno</c>.</p> + <p><em>Example:</em></p> <code type="none"><![CDATA[ #define NODE "[email protected]" #define ALIVE "madonna" @@ -164,59 +147,177 @@ erl_xconnect( &addr , ALIVE ); ]]></code> </desc> </func> + <func> - <name><ret>int</ret><nametext>erl_close_connection(fd)</nametext></name> - <fsummary>Close a connection to an Erlang node</fsummary> + <name><ret>int</ret><nametext>erl_connect_init(number, cookie, creation)</nametext></name> + <name><ret>int</ret><nametext>erl_connect_xinit(host, alive, node, addr, cookie, creation)</nametext></name> + <fsummary>Initialize communication.</fsummary> <type> - <v>int fd;</v> + <v>int number;</v> + <v>char *cookie;</v> + <v>short creation;</v> + <v>char *host,*alive,*node;</v> + <v>struct in_addr *addr;</v> + </type> + <desc> + <p>Initializes the <c>erl_connect</c> module. + In particular, these functions are used to identify the name of the + C-node from which they are called. One of these functions must + be called before any of the other functions in the <c>erl_connect</c> + module are used.</p> + <p><c>erl_connect_xinit()</c> stores for later use + information about:</p> + <list type="bulleted"> + <item>Hostname of the node, <c>host</c></item> + <item>Alivename, <c>alive</c></item> + <item>Node name, <c>node</c></item> + <item>IP address, <c>addr</c></item> + <item>Cookie, <c>cookie</c></item> + <item>Creation number, <c>creation</c></item> + </list> + <p><c>erl_connect_init()</c> + provides an alternative interface that does not require as much + information from the caller. Instead, + <c>erl_connect_init()</c> + uses <c>gethostbyname()</c> to obtain default values.</p> + <p>If you use <c>erl_connect_init()</c>, your node will + have a short name, that is, it will not be fully qualified. If you + need to use fully qualified (long) names, use + <c>erl_connect_xinit()</c> instead.</p> + <list type="bulleted"> + <item> + <p><c>host</c> is the name of the host on which the node + is running.</p> + </item> + <item> + <p><c>alive</c> is the alivename of the node.</p> + </item> + <item> + <p><c>node</c> is the node name. It is to + be of the form <em>alivename@hostname</em>.</p> + </item> + <item> + <p><c>addr</c> is the 32-bit IP address of + <c>host</c>.</p> + </item> + <item> + <p><c>cookie</c> is the authorization string required + for access to the remote node. If <c>NULL</c>, the user + <c>HOME</c> directory is searched for a cookie file + <c>.erlang.cookie</c>. The path to + the home directory is retrieved from environment variable + <c>HOME</c> on Unix and from the + <c>HOMEDRIVE</c> and + <c>HOMEPATH</c> variables on Windows. For more + details, see the <seealso marker="kernel:auth"> + <c>auth</c></seealso> module in Kernel.</p> + </item> + <item> + <p><c>creation</c> helps identifying a particular + instance of a C-node. In particular, it can help prevent us from + receiving messages sent to an earlier process with the same + registered name.</p> + </item> + </list> + <p>A C-node acting as a server is assigned a creation number + when it calls <c>erl_publish()</c>.</p> + <p><c>number</c> is used by + <c>erl_connect_init()</c> to + construct the actual node name. In Example 2 + below, <em>"[email protected]"</em> is the resulting node name.</p> + <p><em>Example 1:</em></p> + <code type="none"><![CDATA[ +struct in_addr addr; +addr = inet_addr("150.236.14.75"); +if (!erl_connect_xinit("chivas", + "madonna", + "[email protected]", + &addr; + "samplecookiestring..."), + 0) + erl_err_quit("<ERROR> when initializing !"); + ]]></code> + <p><em>Example 2:</em></p> + <code type="none"><![CDATA[ +if (!erl_connect_init(17, "samplecookiestring...", 0)) + erl_err_quit("<ERROR> when initializing !"); + ]]></code> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>erl_publish(port)</nametext></name> + <fsummary>Publish a node name.</fsummary> + <type> + <v>int port;</v> </type> <desc> - <p>This function closes an open connection to an Erlang node.</p> - <p><c><![CDATA[Fd]]></c> is a file descriptor obtained from - <c><![CDATA[erl_connect()]]></c> or <c><![CDATA[erl_xconnect()]]></c>.</p> - <p>On success, 0 is returned. If the call fails, a non-zero value - is returned, and the reason for - the error can be obtained with the appropriate platform-dependent - call.</p> + <p>This function is used by a server process to register + with the local name server EPMD, thereby allowing + other processes to send messages by using the registered name. + Before calling this function, the process should + have called <c>bind()</c> and <c>listen()</c> + on an open socket.</p> + <p><c>port</c> is the local name to register, and is to be + the same as the port number that was previously bound to the + socket.</p> + <p>To unregister with EPMD, simply close the returned descriptor.</p> + <p>On success, a descriptor connecting the calling process to EPMD is + returned. On failure, <c>-1</c> is returned and + <c>erl_errno</c> is set to:</p> + <taglist> + <tag><c>EIO</c></tag> + <item>I/O error.</item> + </taglist> + <p>Also, <c>errno</c> values from + <c>socket</c><em>(2)</em> + and <c>connect</c><em>(2)</em> system calls can be + propagated into <c>erl_errno</c>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_receive(fd, bufp, bufsize)</nametext></name> - <fsummary>Receive a message</fsummary> + <fsummary>Receive a message.</fsummary> <type> <v>int fd;</v> <v>char *bufp;</v> <v>int bufsize;</v> </type> <desc> - <p>This function receives a message consisting of a sequence + <p>Receives a message consisting of a sequence of bytes in the Erlang external format.</p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> - <p><c><![CDATA[bufp]]></c> is a buffer large enough to hold the expected - message. </p> - <p><c><![CDATA[bufsize]]></c> indicates the size of <c><![CDATA[bufp]]></c>.</p> - <p>If a <em>tick</em> occurs, i.e., the Erlang node on the + <list type="bulleted"> + <item><c>fd</c> is an open descriptor to an Erlang + connection.</item> + <item><c>bufp</c> is a buffer large enough to hold the + expected message.</item> + <item><c>bufsize</c> indicates the size of + <c>bufp</c>.</item> + </list> + <p>If a <em>tick</em> occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it - is still alive, the function will return <c><![CDATA[ERL_TICK]]></c> and - no message will be placed in the buffer. Also, - <c><![CDATA[erl_errno]]></c> will be set to <c><![CDATA[EAGAIN]]></c>.</p> + is still alive, the function returns <c>ERL_TICK</c> and + no message is placed in the buffer. Also, + <c>erl_errno</c> is set to <c>EAGAIN</c>.</p> <p>On success, the message is placed in the specified buffer and the function returns the number of bytes actually read. On - failure, the function returns a negative value and will set - <c><![CDATA[erl_errno]]></c> to one of:</p> + failure, the function returns a negative value and sets + <c>erl_errno</c> to one of:</p> <taglist> - <tag><c><![CDATA[EAGAIN]]></c></tag> + <tag><c>EAGAIN</c></tag> <item>Temporary error: Try again.</item> - <tag><c><![CDATA[EMSGSIZE]]></c></tag> - <item>Buffer too small.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EMSGSIZE</c></tag> + <item>Buffer is too small.</item> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_receive_msg(fd, bufp, bufsize, emsg)</nametext></name> - <fsummary>Receive and decodes a message</fsummary> + <fsummary>Receive and decode a message.</fsummary> <type> <v>int fd;</v> <v>unsigned char *bufp;</v> @@ -224,14 +325,20 @@ erl_xconnect( &addr , ALIVE ); <v>ErlMessage *emsg;</v> </type> <desc> - <p>This function receives the message into the specified buffer, - and decodes into the <c><![CDATA[(ErlMessage *) emsg]]></c>.</p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> - <p><c><![CDATA[bufp]]></c> is a buffer large enough to hold the expected message.</p> - <p><c><![CDATA[bufsize]]></c> indicates the size of <c><![CDATA[bufp]]></c>.</p> - <p><c><![CDATA[emsg]]></c> is a pointer to an <c><![CDATA[ErlMessage]]></c> structure, - into which the message will be decoded. <c><![CDATA[ErlMessage]]></c> is - defined as follows:</p> + <p>Receives the message into the specified buffer + and decodes into <c>(ErlMessage *) emsg</c>.</p> + <list type="bulleted"> + <item><c>fd</c> is an open descriptor to an Erlang + connection.</item> + <item><c>bufp</c> is a buffer large enough to hold the + expected message.</item> + <item><c>bufsize</c> indicates the size of + <c>bufp</c>.</item> + <item>><c>emsg</c> is a pointer to an + <c>ErlMessage</c> structure + into which the message will be decoded. + <c>ErlMessage</c> is defined as follows:</item> + </list> <code type="none"><![CDATA[ typedef struct { int type; @@ -242,144 +349,100 @@ typedef struct { } ErlMessage; ]]></code> <note> - <p>The definition of <c><![CDATA[ErlMessage]]></c> has changed since - earlier versions of Erl_Interface.</p> + <p>The definition of <c>ErlMessage</c> has changed since + earlier versions of <c>Erl_Interface</c>.</p> </note> - <p><c><![CDATA[type]]></c> identifies the type of message, one of - <c><![CDATA[ERL_SEND]]></c>, <c><![CDATA[ERL_REG_SEND]]></c>, <c><![CDATA[ERL_LINK]]></c>, - <c><![CDATA[ERL_UNLINK]]></c> and <c><![CDATA[ERL_EXIT]]></c>. - </p> - <p>If <c><![CDATA[type]]></c> contains <c><![CDATA[ERL_SEND]]></c> - this indicates that an ordinary send operation has taken - place, and <c><![CDATA[emsg->to]]></c> contains the Pid of the - recipient. If <c><![CDATA[type]]></c> contains <c><![CDATA[ERL_REG_SEND]]></c> then a - registered send operation took place, and <c><![CDATA[emsg->from]]></c> - contains the Pid of the sender. In both cases, the actual - message will be in <c><![CDATA[emsg->msg]]></c>. - </p> - <p>If <c><![CDATA[type]]></c> contains one of <c><![CDATA[ERL_LINK]]></c> or - <c><![CDATA[ERL_UNLINK]]></c>, then <c><![CDATA[emsg->to]]></c> and <c><![CDATA[emsg->from]]></c> - contain the pids of the sender and recipient of the link or unlink. - <c><![CDATA[emsg->msg]]></c> is not used in these cases. - </p> - <p>If <c><![CDATA[type]]></c> contains <c><![CDATA[ERL_EXIT]]></c>, then this - indicates that a link has been broken. In this case, - <c><![CDATA[emsg->to]]></c> and <c><![CDATA[emsg->from]]></c> contain the pids of the - linked processes, and <c><![CDATA[emsg->msg]]></c> contains the reason for - the exit. - </p> + <p><c>type</c> identifies the type of message, one of the + following:</p> + <taglist> + <tag><c>ERL_SEND</c></tag> + <item> + <p>An ordinary send operation has occurred and + <c>emsg->to</c> contains the pid of the recipient. + The message is in <c>emsg->msg</c>.</p> + </item> + <tag><c>ERL_REG_SEND</c></tag> + <item> + <p>A registered send operation has occurred and + <c>emsg->from</c> contains the pid of the sender. + The message is in <c>emsg->msg</c>.</p> + </item> + <tag><c>ERL_LINK</c> or <c>ERL_UNLINK</c> + </tag> + <item> + <p><c>emsg->to</c> and <c>emsg->from</c> + contain the pids of the sender and recipient of the link or + unlink. <c>emsg->msg</c> is not used.</p> + </item> + <tag><c>ERL_EXIT</c></tag> + <item> + <p>A link is broken. <c>emsg->to</c> and + <c>emsg->from</c> contain the pids of the linked + processes, and <c>emsg->msg</c> contains the reason + for the exit.</p> + </item> + </taglist> <note> <p>It is the caller's responsibility to release the - memory pointed to by <c><![CDATA[emsg->msg]]></c>, <c><![CDATA[emsg->to]]></c> and - <c><![CDATA[emsg->from]]></c>.</p> + memory pointed to by <c>emsg->msg</c>, + <c>emsg->to</c>, and + <c>emsg->from</c>.</p> </note> - <p>If a <em>tick</em> occurs, i.e., the Erlang node on the + <p>If a <em>tick</em> occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it - is still alive, the function will return <c><![CDATA[ERL_TICK]]></c> + is still alive, the function returns <c>ERL_TICK</c> indicating that the tick has been received and responded to, - but no message will be placed in the buffer. In this case you - should call <c><![CDATA[erl_receive_msg()]]></c> again.</p> - <p>On success, the function returns <c><![CDATA[ERL_MSG]]></c> and the - <c><![CDATA[Emsg]]></c> struct will be initialized as described above, or - <c><![CDATA[ERL_TICK]]></c>, in which case no message is returned. On - failure, the function returns <c><![CDATA[ERL_ERROR]]></c> and will set - <c><![CDATA[erl_errno]]></c> to one of:</p> + but no message is placed in the buffer. In this case you + are to call <c>erl_receive_msg()</c> again.</p> + <p>On success, the function returns <c>ERL_MSG</c> and the + <c>Emsg</c> struct is initialized as described above, or + <c>ERL_TICK</c>, in which case no message is returned. On + failure, the function returns <c>ERL_ERROR</c> and sets + <c>erl_errno</c> to one of:</p> <taglist> - <tag><c><![CDATA[EMSGSIZE]]></c></tag> - <item>Buffer too small.</item> - <tag><c><![CDATA[ENOMEM]]></c></tag> - <item>No more memory available.</item> - <tag><c><![CDATA[EIO]]></c></tag> - <item>I/O error.</item> - </taglist> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>erl_xreceive_msg(fd, bufpp, bufsizep, emsg)</nametext></name> - <fsummary>Receive and decodes a message</fsummary> - <type> - <v>int fd;</v> - <v>unsigned char **bufpp;</v> - <v>int *bufsizep;</v> - <v>ErlMessage *emsg;</v> - </type> - <desc> - <p>This function is similar to <c><![CDATA[erl_receive_msg]]></c>. The - difference is that <c><![CDATA[erl_xreceive_msg]]></c> expects the buffer to - have been allocated by <c><![CDATA[malloc]]></c>, and reallocates it if the received - message does not fit into the original buffer. For that reason, - both buffer and buffer length are given as pointers - their values - may change by the call. - </p> - <p>On success, the function returns <c><![CDATA[ERL_MSG]]></c> and the - <c><![CDATA[Emsg]]></c> struct will be initialized as described above, or - <c><![CDATA[ERL_TICK]]></c>, in which case no message is returned. On - failure, the function returns <c><![CDATA[ERL_ERROR]]></c> and will set - <c><![CDATA[erl_errno]]></c> to one of:</p> - <taglist> - <tag><c><![CDATA[EMSGSIZE]]></c></tag> - <item>Buffer too small.</item> - <tag><c><![CDATA[ENOMEM]]></c></tag> - <item>No more memory available.</item> - <tag><c><![CDATA[EIO]]></c></tag> - <item>I/O error.</item> - </taglist> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>erl_send(fd, to, msg)</nametext></name> - <fsummary>Send a message</fsummary> - <type> - <v>int fd;</v> - <v>ETERM *to, *msg;</v> - </type> - <desc> - <p>This function sends an Erlang term to a process.</p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> - <p><c><![CDATA[to]]></c> is an Erlang term containing the Pid of the - intended recipient of the message.</p> - <p><c><![CDATA[msg]]></c> is the Erlang term to be sent.</p> - <p>The function returns 1 if successful, otherwise 0 --- in - which case it will set <c><![CDATA[erl_errno]]></c> to one of:</p> - <taglist> - <tag><c><![CDATA[EINVAL]]></c></tag> - <item>Invalid argument: <c><![CDATA[to]]></c> is not a valid Erlang pid.</item> - <tag><c><![CDATA[ENOMEM]]></c></tag> - <item>No more memory available.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EMSGSIZE</c></tag> + <item>Buffer is too small.</item> + <tag><c>ENOMEM</c></tag> + <item>No more memory is available.</item> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_reg_send(fd, to, msg)</nametext></name> - <fsummary>Send a message to a registered name</fsummary> + <fsummary>Send a message to a registered name.</fsummary> <type> <v>int fd;</v> <v>char *to;</v> <v>ETERM *msg;</v> </type> <desc> - <p>This function sends an Erlang term to a registered process.</p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> - <p><c><![CDATA[to]]></c> is a string containing the registered name of - the intended recipient of the message.</p> - <p><c><![CDATA[msg]]></c> is the Erlang term to be sent.</p> - <p>The function returns 1 if successful, otherwise 0 --- in - which case it will set <c><![CDATA[erl_errno]]></c> to one of:</p> + <p>Sends an Erlang term to a registered process.</p> + <list type="bulleted"> + <item><c>fd</c> is an open descriptor to an Erlang + connection.</item> + <item><c>to</c> is a string containing the registered name + of the intended recipient of the message.</item> + <item><c>msg</c> is the Erlang term to be sent.</item> + </list> + <p>Returns <c>1</c> on success, otherwise <c>0</c>. In + the latter case <c>erl_errno</c> is set to one of:</p> <taglist> - <tag><c><![CDATA[ENOMEM]]></c></tag> - <item>No more memory available.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>ENOMEM</c></tag> + <item>No more memory is available.</item> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_rpc(fd, mod, fun, args)</nametext></name> - <name><ret>int</ret><nametext>erl_rpc_to(fd, mod, fun, args)</nametext></name> <name><ret>int</ret><nametext>erl_rpc_from(fd, timeout, emsg)</nametext></name> - <fsummary>Remote Procedure Call</fsummary> + <name><ret>int</ret><nametext>erl_rpc_to(fd, mod, fun, args)</nametext></name> + <fsummary>Remote Procedure Call.</fsummary> <type> <v>int fd, timeout;</v> <v>char *mod, *fun;</v> @@ -387,158 +450,178 @@ typedef struct { <v>ErlMessage *emsg;</v> </type> <desc> - <p>These functions support calling Erlang functions on remote nodes. - <c><![CDATA[erl_rpc_to()]]></c> sends an rpc request to a remote node and - <c><![CDATA[erl_rpc_from()]]></c> receives the results of such a call. - <c><![CDATA[erl_rpc()]]></c> combines the functionality of these two functions - by sending an rpc request and waiting for the results. See also - <c><![CDATA[rpc:call/4]]></c>. </p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> - <p><c><![CDATA[timeout]]></c> is the maximum time (in ms) to wait for - results. Specify <c><![CDATA[ERL_NO_TIMEOUT]]></c> to wait forever. - When erl_rpc() calls erl_rpc_from(), the call will never - timeout.</p> - <p><c><![CDATA[mod]]></c> is the name of the module containing the function - to be run on the remote node.</p> - <p><c><![CDATA[fun]]></c> is the name of the function to run.</p> - <p><c><![CDATA[args]]></c> is an Erlang list, containing the arguments to be - passed to the function. </p> - <p><c><![CDATA[emsg]]></c> is a message containing the result of the - function call.</p> - <p>The actual message returned by the rpc server - is a 2-tuple <c><![CDATA[{rex,Reply}]]></c>. If you are using - <c><![CDATA[erl_rpc_from()]]></c> in your code then this is the message you - will need to parse. If you are using <c><![CDATA[erl_rpc()]]></c> then the + <p>Supports calling Erlang functions on remote nodes. + <c>erl_rpc_to()</c> sends an RPC request to a remote node + and <c>erl_rpc_from()</c> receives the results of such a + call. <c>erl_rpc()</c> combines the functionality of + these two functions by sending an RPC request and waiting for the + results. See also <seealso marker="kernel:rpc#call/4"> + <c>rpc:call/4</c></seealso> in <c>Kernel</c>.</p> + <list type="bulleted"> + <item><c>fd</c> is an open descriptor to an Erlang + connection.</item> + <item><c>timeout</c> is the maximum time (in milliseconds) + to wait for + results. To wait forever, specify <c>ERL_NO_TIMEOUT</c>. + When <c>erl_rpc()</c> calls <c>erl_rpc_from()</c>, the call will + never timeout.</item> + <item><c>mod</c> is the name of the module containing the + function to be run on the remote node.</item> + <item><c>fun</c> is the name of the function to run. + </item> + <item><c>args</c> is an Erlang list, containing the + arguments to be passed to the function.</item> + <item><c>emsg</c> is a message containing the result of + the function call.</item> + </list> + <p>The actual message returned by the RPC server + is a 2-tuple <c>{rex,Reply}</c>. If you use + <c>erl_rpc_from()</c> in your code, this is the message + you will need to parse. If you use <c>erl_rpc()</c>, the tuple itself is parsed for you, and the message returned to your - program is the erlang term containing <c><![CDATA[Reply]]></c> only. Replies - to rpc requests are always ERL_SEND messages. - </p> + program is the Erlang term containing <c>Reply</c> only. + Replies to RPC requests are always <c>ERL_SEND</c> messages.</p> <note> <p>It is the caller's responsibility to free the returned - <c><![CDATA[ETERM]]></c> structure as well as the memory pointed to by - <c><![CDATA[emsg->msg]]></c> and <c><![CDATA[emsg->to]]></c>. </p> + <c>ETERM</c> structure and the memory pointed to by + <c>emsg->msg</c> and <c>emsg->to</c>.</p> </note> - <p><c><![CDATA[erl_rpc()]]></c> returns the remote function's return value (or - <c><![CDATA[NULL]]></c> if it failed). <c><![CDATA[erl_rpc_to()]]></c> returns 0 on - success, and a negative number on failure. <c><![CDATA[erl_rcp_from()]]></c> - returns <c><![CDATA[ERL_MSG]]></c> when successful (with <c><![CDATA[Emsg]]></c> now - containing the reply tuple), and one of <c><![CDATA[ERL_TICK]]></c>, - <c><![CDATA[ERL_TIMEOUT]]></c> and <c><![CDATA[ERL_ERROR]]></c> otherwise. When failing, - all three functions set <c><![CDATA[erl_errno]]></c> to one of:</p> + <p><c>erl_rpc()</c> returns the remote function's return + value on success, otherwise <c>NULL</c>.</p> + <p><c>erl_rpc_to()</c> returns <c>0</c> on + success, otherwise a negative number.</p> + <p><c>erl_rcp_from()</c> returns <c>ERL_MSG</c> + on success (with <c>Emsg</c> now + containing the reply tuple), otherwise one of + <c>ERL_TICK</c>, <c>ERL_TIMEOUT</c>, or + <c>ERL_ERROR</c>.</p> + <p>When failing, + all three functions set <c>erl_errno</c> to one of:</p> <taglist> - <tag><c><![CDATA[ENOMEM]]></c></tag> - <item>No more memory available.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>ENOMEM</c></tag> + <item>No more memory is available.</item> + <tag><c>EIO</c></tag> <item>I/O error.</item> - <tag><c><![CDATA[ETIMEDOUT]]></c></tag> - <item>Timeout expired.</item> - <tag><c><![CDATA[EAGAIN]]></c></tag> + <tag><c>ETIMEDOUT</c></tag> + <item>Timeout has expired.</item> + <tag><c>EAGAIN</c></tag> <item>Temporary error: Try again.</item> </taglist> </desc> </func> + <func> - <name><ret>int</ret><nametext>erl_publish(port)</nametext></name> - <fsummary>Publish a node name</fsummary> + <name><ret>int</ret><nametext>erl_send(fd, to, msg)</nametext></name> + <fsummary>Send a message.</fsummary> <type> - <v>int port;</v> + <v>int fd;</v> + <v>ETERM *to, *msg;</v> </type> <desc> - <p>These functions are used by a server process to register - with the local name server <em>epmd</em>, thereby allowing - other processes to send messages by using the registered name. - Before calling either of these functions, the process should - have called <c><![CDATA[bind()]]></c> and <c><![CDATA[listen()]]></c> on an open socket.</p> - <p><c><![CDATA[port]]></c> is the local name to register, and should be the - same as the port number that was previously bound to the socket.</p> - <p>To unregister with epmd, simply close the returned - descriptor. - </p> - <p>On success, the functions return a descriptor connecting the - calling process to epmd. On failure, they return -1 and set - <c><![CDATA[erl_errno]]></c> to:</p> + <p>Sends an Erlang term to a process.</p> + <list type="bulleted"> + <item><c>fd</c> is an open descriptor to an Erlang + connection.</item> + <item><c>to</c> is an Erlang term containing the pid of + the intended recipient of the message.</item> + <item>><c>msg</c> is the Erlang term to be sent.</item> + </list> + <p>Returns <c>1</c> on success, otherwise <c>0</c>. In + the latter case <c>erl_errno</c> is set to one of:</p> <taglist> - <tag><c><![CDATA[EIO]]></c></tag> - <item>I/O error</item> + <tag><c>EINVAL</c></tag> + <item>Invalid argument: <c>to</c> is not a valid Erlang + pid.</item> + <tag><c>ENOMEM</c></tag> + <item>No more memory is available.</item> + <tag><c>EIO</c></tag> + <item>I/O error.</item> </taglist> - <p>Additionally, <c><![CDATA[errno]]></c> values from <c><![CDATA[socket]]></c><em>(2)</em> - and <c><![CDATA[connect]]></c><em>(2)</em> system calls may be propagated - into <c><![CDATA[erl_errno]]></c>. - </p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>erl_accept(listensock, conp)</nametext></name> - <fsummary>Accept a connection</fsummary> - <type> - <v>int listensock;</v> - <v>ErlConnect *conp;</v> - </type> - <desc> - <p>This function is used by a server process to accept a - connection from a client process.</p> - <p><c><![CDATA[listensock]]></c> is an open socket descriptor on which - <c><![CDATA[listen()]]></c> has previously been called.</p> - <p><c><![CDATA[conp]]></c> is a pointer to an <c><![CDATA[ErlConnect]]></c> struct, - described as follows:</p> - <code type="none"><![CDATA[ -typedef struct { - char ipadr[4]; - char nodename[MAXNODELEN]; -} ErlConnect; - ]]></code> - <p>On success, <c><![CDATA[conp]]></c> is filled in with the address and - node name of the connecting client and a file descriptor is - returned. On failure, <c><![CDATA[ERL_ERROR]]></c> is returned and - <c><![CDATA[erl_errno]]></c> is set to <c><![CDATA[EIO]]></c>.</p> </desc> </func> + <func> - <name><ret>const char *</ret><nametext>erl_thiscookie()</nametext></name> - <name><ret>const char *</ret><nametext>erl_thisnodename()</nametext></name> - <name><ret>const char *</ret><nametext>erl_thishostname()</nametext></name> <name><ret>const char *</ret><nametext>erl_thisalivename()</nametext></name> + <name><ret>const char *</ret><nametext>erl_thiscookie()</nametext></name> <name><ret>short</ret><nametext>erl_thiscreation()</nametext></name> - <fsummary>Retrieve some values</fsummary> + <name><ret>const char *</ret><nametext>erl_thishostname()</nametext></name> + <name><ret>const char *</ret><nametext>erl_thisnodename()</nametext></name> + <fsummary>Retrieve some values.</fsummary> <desc> - <p>These functions can be used to retrieve information about - the C Node. These values are initially set with - <c><![CDATA[erl_connect_init()]]></c> or <c><![CDATA[erl_connect_xinit()]]></c>.</p> + <p>Retrieves information about + the C-node. These values are initially set with + <c>erl_connect_init()</c> or + <c>erl_connect_xinit()</c>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_unpublish(alive)</nametext></name> - <fsummary>Forcefully unpublish a node name</fsummary> + <fsummary>Forcefully unpublish a node name.</fsummary> <type> <v>char *alive;</v> </type> <desc> <p>This function can be called by a process to unregister a - specified node from epmd on the localhost. This is however usually not - allowed, unless epmd was started with the -relaxed_command_check - flag, which it normally isn't.</p> - - <p>To unregister a node you have published, you should instead - close the descriptor that was returned by - <c><![CDATA[ei_publish()]]></c>.</p> - + specified node from EPMD on the local host. This is, however, usually + not allowed, unless EPMD was started with flag + <c>-relaxed_command_check</c>, which it normally is not.</p> + <p>To unregister a node you have published, you should instead + close the descriptor that was returned by + <c>ei_publish()</c>.</p> <warning> - <p>This function is deprecated and will be removed in a future - release.</p> + <p>This function is deprecated and will be removed in a future + release.</p> </warning> - <p><c><![CDATA[alive]]></c> is the name of the node to unregister, i.e., the - first component of the nodename, without the <c><![CDATA[@hostname]]></c>.</p> - <p>If the node was successfully unregistered from epmd, the - function returns 0. Otherwise, it returns -1 and sets - <c><![CDATA[erl_errno]]></c> is to <c><![CDATA[EIO]]></c>.</p> + <p><c>alive</c> is the name of the node to unregister, that + is, the first component of the node name, without + <c>@hostname</c>.</p> + <p>If the node was successfully unregistered from EPMD, <c>0</c> is + returned, otherwise <c>-1</c> is returned and + <c>erl_errno</c> is set to <c>EIO</c>.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>erl_xreceive_msg(fd, bufpp, bufsizep, emsg)</nametext></name> + <fsummary>Receive and decode a message.</fsummary> + <type> + <v>int fd;</v> + <v>unsigned char **bufpp;</v> + <v>int *bufsizep;</v> + <v>ErlMessage *emsg;</v> + </type> + <desc> + <p>Similar to <c>erl_receive_msg</c>. The difference is + that <c>erl_xreceive_msg</c> expects the buffer to + have been allocated by <c>malloc</c>, and reallocates it + if the received + message does not fit into the original buffer. Therefore + both buffer and buffer length are given as pointers; their values + can change by the call.</p> + <p>On success, the function returns <c>ERL_MSG</c> and the + <c>Emsg</c> struct is initialized as described above, or + <c>ERL_TICK</c>, in which case no message is returned. On + failure, the function returns <c>ERL_ERROR</c> and sets + <c>erl_errno</c> to one of:</p> + <taglist> + <tag><c>EMSGSIZE</c></tag> + <item>Buffer is too small.</item> + <tag><c>ENOMEM</c></tag> + <item>No more memory is available.</item> + <tag><c>EIO</c></tag> + <item>I/O error.</item> + </taglist> </desc> </func> + <func> - <name><ret>struct hostent</ret><nametext>*erl_gethostbyname(name)</nametext></name> <name><ret>struct hostent</ret><nametext>*erl_gethostbyaddr(addr, length, type)</nametext></name> - <name><ret>struct hostent</ret><nametext>*erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop)</nametext></name> <name><ret>struct hostent</ret><nametext>*erl_gethostbyaddr_r(addr, length, type, hostp, buffer, buflen, h_errnop)</nametext></name> - <fsummary>Name lookup functions</fsummary> + <name><ret>struct hostent</ret><nametext>*erl_gethostbyname(name)</nametext></name> + <name><ret>struct hostent</ret><nametext>*erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop)</nametext></name> + + <fsummary>Name lookup functions.</fsummary> <type> <v>const char *name;</v> <v>const char *addr;</v> @@ -550,7 +633,7 @@ typedef struct { <v>int *h_errnop;</v> </type> <desc> - <p>These are convenience functions for some common name lookup functions.</p> + <p>Convenience functions for some common name lookup functions.</p> </desc> </func> </funcs> @@ -558,13 +641,13 @@ typedef struct { <section> <title>Debug Information</title> <p>If a connection attempt fails, the following can be checked:</p> + <list type="bulleted"> - <item><c><![CDATA[erl_errno]]></c></item> - <item>that the right cookie was used</item> - <item>that <em>epmd</em> is running</item> - <item>the remote Erlang node on the other side is running the same - version of Erlang as the <c><![CDATA[erl_interface]]></c> library.</item> + <item><c>erl_errno</c></item> + <item>That the correct cookie was used</item> + <item>That EPMD is running</item> + <item>That the remote Erlang node on the other side is running the same + version of Erlang as the <c>erl_interface</c> library</item> </list> </section> </cref> - diff --git a/lib/erl_interface/doc/src/erl_error.xml b/lib/erl_interface/doc/src/erl_error.xml index abe84780e1..8139c9b343 100644 --- a/lib/erl_interface/doc/src/erl_error.xml +++ b/lib/erl_interface/doc/src/erl_error.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>erl_error</title> @@ -28,61 +28,66 @@ <docno></docno> <approved>Bjarne Däcker</approved> <checked>Torbjörn Törnkvist</checked> - <date>961014</date> + <date>1996-10-14</date> <rev>A</rev> - <file>erl_error.sgml</file> + <file>erl_error.xml</file> </header> <lib>erl_error</lib> - <libsummary>Error Print Routines</libsummary> + <libsummary>Error print routines.</libsummary> <description> <p>This module contains some error printing routines taken - from <em>Advanced Programming in the UNIX Environment</em> - by W. Richard Stevens. </p> + from "Advanced Programming in the UNIX Environment" + by W. Richard Stevens.</p> + <p>These functions are all called in the same manner as - <c><![CDATA[printf()]]></c>, i.e. with a string containing format specifiers - followed by a list of corresponding arguments. All output from - these functions is to <c><![CDATA[stderr]]></c>.</p> + <c>printf()</c>, that is, with a string containing format + specifiers followed by a list of corresponding arguments. All output from + these functions is to <c>stderr</c>.</p> </description> + <funcs> <func> <name><ret>void</ret><nametext>erl_err_msg(FormatStr, ... )</nametext></name> - <fsummary>Non-fatal error, and not system call error</fsummary> + <fsummary>Non-fatal error, and not system call error.</fsummary> <type> <v>const char *FormatStr;</v> </type> <desc> <p>The message provided by the caller is printed. This - function is simply a wrapper for <c><![CDATA[fprintf()]]></c>.</p> + function is simply a wrapper for <c>fprintf()</c>.</p> </desc> </func> + <func> <name><ret>void</ret><nametext>erl_err_quit(FormatStr, ... )</nametext></name> - <fsummary>Fatal error, but not system call error</fsummary> + <fsummary>Fatal error, but not system call error.</fsummary> <type> <v>const char *FormatStr;</v> </type> <desc> <p>Use this function when a fatal error has occurred that - is not due to a system call. The message provided by the - caller is printed and the process terminates with an exit - value of 1. The function does not return.</p> + is not because of a system call. The message provided by the + caller is printed and the process terminates with exit + value <c>1</c>. This function does not return.</p> </desc> </func> + <func> <name><ret>void</ret><nametext>erl_err_ret(FormatStr, ... )</nametext></name> - <fsummary>Non-fatal system call error</fsummary> + <fsummary>Non-fatal system call error.</fsummary> <type> <v>const char *FormatStr;</v> </type> <desc> <p>Use this function after a failed system call. The message provided by the caller is printed followed by a string - describing the reason for failure. </p> + describing the reason for failure.</p> </desc> </func> + <func> <name><ret>void</ret><nametext>erl_err_sys(FormatStr, ... )</nametext></name> - <fsummary>Fatal system call error</fsummary> + <fsummary>Fatal system call error.</fsummary> <type> <v>const char *FormatStr;</v> </type> @@ -90,7 +95,7 @@ <p>Use this function after a failed system call. The message provided by the caller is printed followed by a string describing the reason for failure, and the process - terminates with an exit value of 1. The function does not + terminates with exit value <c>1</c>. This function does not return.</p> </desc> </func> @@ -98,40 +103,43 @@ <section> <title>Error Reporting</title> - <p>Most functions in erl_interface report failures to the caller by - returning some otherwise meaningless value (typically <c><![CDATA[NULL]]></c> + <p>Most functions in <c>Erl_Interface</c> report failures to the caller by + returning some otherwise meaningless value (typically + <c>NULL</c> or a negative number). As this only tells you that things did not - go well, you will have to examine the error code in - <c><![CDATA[erl_errno]]></c> if you want to find out more about the failure.</p> + go well, examine the error code in <c>erl_errno</c> if you + want to find out more about the failure.</p> </section> + <funcs> <func> <name><ret>volatile int</ret><nametext>erl_errno</nametext></name> - <fsummary>The variable <c><![CDATA[erl_errno]]></c>contains the erl_interface error number. You can change the value if you wish. </fsummary> + <fsummary>Variable <c>erl_errno</c> contains the + Erl_Interface error number. You can change the value if you wish. + </fsummary> <desc> - <p><c><![CDATA[erl_errno]]></c> is initially (at program startup) zero and - is then set by many erl_interface functions on failure to a - non-zero error code to indicate what kind of error it - encountered. A successful function call might change - <c><![CDATA[erl_errno]]></c> (by calling some other function that - fails), but no function will ever set it to zero. This means - that you cannot use <c><![CDATA[erl_errno]]></c> to see <em>if</em> a + <p><c>erl_errno</c> is initially (at program startup) zero + and is then set by many <c>Erl_Interface</c> functions on failure to + a non-zero error code to indicate what kind of error it + encountered. A successful function call can change + <c>erl_errno</c> (by calling some other function that + fails), but no function does never set it to zero. This means + that you cannot use <c>erl_errno</c> to see <em>if</em> a function call failed. Instead, each function reports failure in its own way (usually by returning a negative number or - <c><![CDATA[NULL]]></c>), in which case you can examine <c><![CDATA[erl_errno]]></c> - for details.</p> - <p><c><![CDATA[erl_errno]]></c> uses the error codes defined in your - system's <c><![CDATA[<errno.h>]]></c>.</p> + <c>NULL</c>), in which case you can examine + <c>erl_errno</c> for details.</p> + <p><c>erl_errno</c> uses the error codes defined in your + system's <c><errno.h></c>.</p> <note> - <p>Actually, <c><![CDATA[erl_errno]]></c> is a "modifiable lvalue" (just - like ISO C defines <c><![CDATA[errno]]></c> to be) rather than a - variable. This means it might be implemented as a macro - (expanding to, e.g., <c><![CDATA[*_erl_errno()]]></c>). For reasons of - thread- (or task-)safety, this is exactly what we do on most - platforms.</p> + <p><c>erl_errno</c> is a "modifiable lvalue" (just + like ISO C defines <c>errno</c> to be) rather than a + variable. This means it can be implemented as a macro + (expanding to, for example, <c>*_erl_errno()</c>). + For reasons of thread safety (or task safety), this is exactly what + we do on most platforms.</p> </note> </desc> </func> </funcs> </cref> - diff --git a/lib/erl_interface/doc/src/erl_eterm.xml b/lib/erl_interface/doc/src/erl_eterm.xml index 800f8a3207..9a05196a70 100644 --- a/lib/erl_interface/doc/src/erl_eterm.xml +++ b/lib/erl_interface/doc/src/erl_eterm.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>erl_eterm</title> @@ -28,131 +28,145 @@ <docno></docno> <approved>Bjarne Däcker</approved> <checked>Torbjörn Törnkvist</checked> - <date>980703</date> + <date>1998-07-03</date> <rev>A</rev> - <file>erl_eterm.sgml</file> + <file>erl_eterm.xml</file> </header> <lib>erl_eterm</lib> - <libsummary>Functions for Erlang Term Construction</libsummary> + <libsummary>Functions for Erlang term construction.</libsummary> <description> - <p>This module contains functions for creating and manipulating - Erlang terms. </p> + <p>This module provides functions for creating and manipulating + Erlang terms.</p> + <p>An Erlang term is represented by a C structure of type - <c><![CDATA[ETERM]]></c>. Applications should not reference any fields in this - structure directly, because it may be changed in future releases + <c>ETERM</c>. Applications should not reference any fields + in this structure directly, as it can be changed in future releases to provide faster and more compact term storage. Instead, - applications should us the macros and functions provided. </p> - <p>The following macros each take a single ETERM pointer as an - argument. They return a non-zero value if the test is true, and 0 - otherwise:</p> + applications should use the macros and functions provided.</p> + + <p>Each of the following macros takes a single <c>ETERM</c> pointer as an + argument. The macros return a non-zero value if the test is true, + otherwise <c>0</c>.</p> + <taglist> - <tag><c><![CDATA[ERL_IS_INTEGER(t)]]></c></tag> - <item>True if <c><![CDATA[t]]></c> is an integer.</item> - <tag><c><![CDATA[ERL_IS_UNSIGNED_INTEGER(t)]]></c></tag> - <item>True if <c><![CDATA[t]]></c> is an integer.</item> - <tag><c><![CDATA[ERL_IS_FLOAT(t)]]></c></tag> - <item>True if <c><![CDATA[t]]></c> is a floating point number.</item> - <tag><c><![CDATA[ERL_IS_ATOM(t)]]></c></tag> - <item>True if <c><![CDATA[t]]></c> is an atom.</item> - <tag><c><![CDATA[ERL_IS_PID(t)]]></c></tag> - <item>True if <c><![CDATA[t]]></c> is a Pid (process identifier).</item> - <tag><c><![CDATA[ERL_IS_PORT(t)]]></c></tag> - <item>True if <c><![CDATA[t]]></c> is a port.</item> - <tag><c><![CDATA[ERL_IS_REF(t)]]></c></tag> - <item>True if <c><![CDATA[t]]></c> is a reference.</item> - <tag><c><![CDATA[ERL_IS_TUPLE(t)]]></c></tag> - <item>True if <c><![CDATA[t]]></c> is a tuple.</item> - <tag><c><![CDATA[ERL_IS_BINARY(t)]]></c></tag> - <item>True if <c><![CDATA[t]]></c> is a binary.</item> - <tag><c><![CDATA[ERL_IS_LIST(t)]]></c></tag> - <item>True if <c><![CDATA[t]]></c> is a list with zero or more elements.</item> - <tag><c><![CDATA[ERL_IS_EMPTY_LIST(t)]]></c></tag> - <item>True if <c><![CDATA[t]]></c> is an empty list.</item> - <tag><c><![CDATA[ERL_IS_CONS(t)]]></c></tag> - <item>True if <c><![CDATA[t]]></c> is a list with at least one element.</item> + <tag><c>ERL_IS_INTEGER(t)</c></tag> + <item>True if <c>t</c> is an integer.</item> + <tag><c>ERL_IS_UNSIGNED_INTEGER(t)</c></tag> + <item>True if <c>t</c> is an integer.</item> + <tag><c>ERL_IS_FLOAT(t)</c></tag> + <item>True if <c>t</c> is a floating point number.</item> + <tag><c>ERL_IS_ATOM(t)</c></tag> + <item>True if <c>t</c> is an atom.</item> + <tag><c>ERL_IS_PID(t)</c></tag> + <item>True if <c>t</c> is a pid (process identifier).</item> + <tag><c>ERL_IS_PORT(t)</c></tag> + <item>True if <c>t</c> is a port.</item> + <tag><c>ERL_IS_REF(t)</c></tag> + <item>True if <c>t</c> is a reference.</item> + <tag><c>ERL_IS_TUPLE(t)</c></tag> + <item>True if <c>t</c> is a tuple.</item> + <tag><c>ERL_IS_BINARY(t)</c></tag> + <item>True if <c>t</c> is a binary.</item> + <tag><c>ERL_IS_LIST(t)</c></tag> + <item>True if <c>t</c> is a list with zero or more + elements.</item> + <tag><c>ERL_IS_EMPTY_LIST(t)</c></tag> + <item>True if <c>t</c> is an empty list.</item> + <tag><c>ERL_IS_CONS(t)</c></tag> + <item>True if <c>t</c> is a list with at least one + element.</item> </taglist> + <p>The following macros can be used for retrieving parts of Erlang - terms. None of these do any type checking; results are undefined - if you pass an ETERM* containing the wrong type. For example, - passing a tuple to ERL_ATOM_PTR() will likely result in garbage. - </p> + terms. None of these do any type checking. Results are undefined + if you pass an <c>ETERM*</c> containing the wrong type. For example, + passing a tuple to <c>ERL_ATOM_PTR()</c> likely results in garbage.</p> + <taglist> - <tag><c><![CDATA[char *ERL_ATOM_PTR(t)]]></c></tag> - <item/> - <tag><c><![CDATA[char *ERL_ATOM_PTR_UTF8(t)]]></c></tag> - <item>A string representing atom <c><![CDATA[t]]></c>. - </item> - <tag><c><![CDATA[int ERL_ATOM_SIZE(t)]]></c></tag> - <item/> - <tag><c><![CDATA[int ERL_ATOM_SIZE_UTF8(t)]]></c></tag> - <item>The length (in bytes) of atom t.</item> - <tag><c><![CDATA[void *ERL_BIN_PTR(t)]]></c></tag> - <item>A pointer to the contents of <c><![CDATA[t]]></c></item> - <tag><c><![CDATA[int ERL_BIN_SIZE(t)]]></c></tag> - <item>The length (in bytes) of binary object <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[int ERL_INT_VALUE(t)]]></c></tag> - <item>The integer of <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[unsigned int ERL_INT_UVALUE(t)]]></c></tag> - <item>The unsigned integer value of <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[double ERL_FLOAT_VALUE(t)]]></c></tag> - <item>The floating point value of <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[ETERM *ERL_PID_NODE(t)]]></c></tag> - <item/> - <tag><c><![CDATA[ETERM *ERL_PID_NODE_UTF8(t)]]></c></tag> - <item>The Node in pid <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[int ERL_PID_NUMBER(t)]]></c></tag> - <item>The sequence number in pid <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[int ERL_PID_SERIAL(t)]]></c></tag> - <item>The serial number in pid <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[int ERL_PID_CREATION(t)]]></c></tag> - <item>The creation number in pid <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[int ERL_PORT_NUMBER(t)]]></c></tag> - <item>The sequence number in port <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[int ERL_PORT_CREATION(t)]]></c></tag> - <item>The creation number in port <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[ETERM *ERL_PORT_NODE(t)]]></c></tag> - <item/> - <tag><c><![CDATA[ETERM *ERL_PORT_NODE_UTF8(t)]]></c></tag> - <item>The node in port <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[int ERL_REF_NUMBER(t)]]></c></tag> - <item>The first part of the reference number in ref <c><![CDATA[t]]></c>. Use - only for compatibility.</item> - <tag><c><![CDATA[int ERL_REF_NUMBERS(t)]]></c></tag> - <item>Pointer to the array of reference numbers in ref <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[int ERL_REF_LEN(t)]]></c></tag> - <item>The number of used reference numbers in ref <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[int ERL_REF_CREATION(t)]]></c></tag> - <item>The creation number in ref <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[int ERL_TUPLE_SIZE(t)]]></c></tag> - <item>The number of elements in tuple <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[ETERM *ERL_CONS_HEAD(t)]]></c></tag> - <item>The head element of list <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[ETERM *ERL_CONS_TAIL(t)]]></c></tag> - <item>A List representing the tail elements of list <c><![CDATA[t]]></c>.</item> + <tag><c>char *ERL_ATOM_PTR(t)</c></tag> + <item></item> + <tag><c>char *ERL_ATOM_PTR_UTF8(t)</c></tag> + <item>A string representing atom <c>t</c>.</item> + <tag><c>int ERL_ATOM_SIZE(t)</c></tag> + <item></item> + <tag><c>int ERL_ATOM_SIZE_UTF8(t)</c></tag> + <item>The length (in bytes) of atom <c>t</c>.</item> + <tag><c>void *ERL_BIN_PTR(t)</c></tag> + <item>A pointer to the contents of <c>t</c>.</item> + <tag><c>int ERL_BIN_SIZE(t)</c></tag> + <item>The length (in bytes) of binary object <c>t</c>.</item> + <tag><c>int ERL_INT_VALUE(t)</c></tag> + <item>The integer of <c>t</c>.</item> + <tag><c>unsigned int ERL_INT_UVALUE(t)</c></tag> + <item>The unsigned integer value of <c>t</c>.</item> + <tag><c>double ERL_FLOAT_VALUE(t)</c></tag> + <item>The floating point value of <c>t</c>.</item> + <tag><c>ETERM *ERL_PID_NODE(t)</c></tag> + <item></item> + <tag><c>ETERM *ERL_PID_NODE_UTF8(t)</c></tag> + <item>The node in pid <c>t</c>.</item> + <tag><c>int ERL_PID_NUMBER(t)</c></tag> + <item>The sequence number in pid <c>t</c>.</item> + <tag><c>int ERL_PID_SERIAL(t)</c></tag> + <item>The serial number in pid <c>t</c>.</item> + <tag><c>int ERL_PID_CREATION(t)</c></tag> + <item>The creation number in pid <c>t</c>.</item> + <tag><c>int ERL_PORT_NUMBER(t)</c></tag> + <item>The sequence number in port <c>t</c>.</item> + <tag><c>int ERL_PORT_CREATION(t)</c></tag> + <item>The creation number in port <c>t</c>.</item> + <tag><c>ETERM *ERL_PORT_NODE(t)</c></tag> + <item></item> + <tag><c>ETERM *ERL_PORT_NODE_UTF8(t)</c></tag> + <item>The node in port <c>t</c>.</item> + <tag><c>int ERL_REF_NUMBER(t)</c></tag> + <item>The first part of the reference number in ref <c>t</c>. + Use only for compatibility.</item> + <tag><c>int ERL_REF_NUMBERS(t)</c></tag> + <item>Pointer to the array of reference numbers in ref + <c>t</c>.</item> + <tag><c>int ERL_REF_LEN(t)</c></tag> + <item>The number of used reference numbers in ref + <c>t</c>.</item> + <tag><c>int ERL_REF_CREATION(t)</c></tag> + <item>The creation number in ref <c>t</c>.</item> + <tag><c>int ERL_TUPLE_SIZE(t)</c></tag> + <item>The number of elements in tuple <c>t</c>.</item> + <tag><c>ETERM *ERL_CONS_HEAD(t)</c></tag> + <item>The head element of list <c>t</c>.</item> + <tag><c>ETERM *ERL_CONS_TAIL(t)</c></tag> + <item>A list representing the tail elements of list + <c>t</c>.</item> </taglist> </description> + <funcs> <func> <name><ret>ETERM *</ret><nametext>erl_cons(head, tail)</nametext></name> - <fsummary>Prepends a term to the head of a list.</fsummary> + <fsummary>Prepend a term to the head of a list.</fsummary> <type> <v>ETERM *head;</v> <v>ETERM *tail;</v> </type> <desc> - <p>This function concatenates two Erlang terms, prepending - <c><![CDATA[head]]></c> onto <c><![CDATA[tail]]></c> and thereby creating a <c><![CDATA[cons]]></c> cell. - To make a proper list, <c><![CDATA[tail]]></c> should always be a - list or an empty list. Note that NULL is not a valid list.</p> - <p><c><![CDATA[head]]></c> is the new term to be added.</p> - <p><c><![CDATA[tail]]></c> is the existing list to which <c><![CDATA[head]]></c> will - be concatenated.</p> + <p>Concatenates two Erlang terms, prepending <c>head</c> + onto <c>tail</c> and thereby creating a + <c>cons</c> cell. + To make a proper list, <c>tail</c> is always to be a list + or an empty list. Notice that <c>NULL</c> is not a valid list.</p> + <list type="bulleted"> + <item><c>head</c> is the new term to be added.</item> + <item><c>tail</c> is the existing list to which + <c>head</c> is concatenated.</item> + </list> <p>The function returns a new list.</p> - <p><c><![CDATA[ERL_CONS_HEAD(list)]]></c> and <c><![CDATA[ERL_CONS_TAIL(list)]]></c> + <p><c>ERL_CONS_HEAD(list)</c> and + <c>ERL_CONS_TAIL(list)</c> can be used to retrieve the head and tail components - from the list. <c><![CDATA[erl_hd(list)]]></c> and <c><![CDATA[erl_tl(list)]]></c> will do + from the list. <c>erl_hd(list)</c> and + <c>erl_tl(list)</c> do the same thing, but check that the argument really is a list.</p> - <p>For example:</p> + <p><em>Example:</em></p> <code type="none"><![CDATA[ ETERM *list,*anAtom,*anInt; anAtom = erl_mk_atom("madonna"); @@ -165,79 +179,102 @@ erl_free_compound(list); ]]></code> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_copy_term(term)</nametext></name> - <fsummary>Creates a copy of an Erlang term</fsummary> + <fsummary>Create a copy of an Erlang term.</fsummary> <type> <v>ETERM *term;</v> </type> <desc> - <p>This function creates and returns a copy of the Erlang term - <c><![CDATA[term]]></c>.</p> + <p>Creates and returns a copy of the Erlang term + <c>term</c>.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_element(position, tuple)</nametext></name> - <fsummary>Extracts an element from an Erlang tuple</fsummary> + <fsummary>Extract an element from an Erlang tuple.</fsummary> <type> <v>int position;</v> <v>ETERM *tuple;</v> </type> <desc> - <p>This function extracts a specified element from an Erlang - tuple. </p> - <p><c><![CDATA[position]]></c> specifies which element to retrieve from - <c><![CDATA[tuple]]></c>. The elements are numbered starting from 1.</p> - <p><c><![CDATA[tuple]]></c> is an Erlang term containing at least - <c><![CDATA[position]]></c> elements.</p> - <p>The function returns a new Erlang term corresponding to the - requested element, or NULL if <c><![CDATA[position]]></c> was greater than - the arity of <c><![CDATA[tuple]]></c>.</p> + <p>Extracts a specified element from an Erlang tuple.</p> + <list type="bulleted"> + <item><c>position</c> specifies which element to retrieve + from <c>tuple</c>. The elements are numbered starting + from 1.</item> + <item><c>tuple</c> is an Erlang term containing at least + <c>position</c> elements.</item> + </list> + <p>Returns a new Erlang term corresponding to the requested element, or + <c>NULL</c> if <c>position</c> was greater + than the arity of <c>tuple</c>.</p> + </desc> + </func> + + <func> + <name><ret>ETERM *</ret><nametext>erl_hd(list)</nametext></name> + <fsummary>Extract the first element from a list.</fsummary> + <type> + <v>ETERM *list;</v> + </type> + <desc> + <p>Extracts the first element from a list.</p> + <p><c>list</c> is an Erlang term containing a list.</p> + <p>Returns an Erlang term corresponding to the head + head element in the list, or a <c>NULL</c> pointer if + <c>list</c> was not a list.</p> </desc> </func> + <func> <name><ret>void</ret><nametext>erl_init(NULL, 0)</nametext></name> - <fsummary>Initialization routine</fsummary> + <fsummary>Initialization routine.</fsummary> <type> <v>void *NULL;</v> <v>int 0;</v> </type> <desc> - <marker id="erl_init"></marker> - <p>This function must be called before any of the others in - the <c><![CDATA[erl_interface]]></c> library in order to initialize the - library functions. The arguments must be specified as - <c><![CDATA[erl_init(NULL,0)]]></c>.</p> + <p>This function must be called before any of the others in the + <c>Erl_Interface</c> library to initialize the + library functions. The arguments must be specified as + <c>erl_init(NULL,0)</c>.</p> </desc> </func> + <func> - <name><ret>ETERM *</ret><nametext>erl_hd(list)</nametext></name> - <fsummary>Extracts the first element from a list</fsummary> + <name><ret>int</ret><nametext>erl_iolist_length(list)</nametext></name> + <fsummary>Return the length of an I/O list.</fsummary> <type> <v>ETERM *list;</v> </type> <desc> - <p>Extracts the first element from a list.</p> - <p><c><![CDATA[list]]></c> is an Erlang term containing a list.</p> - <p>The function returns an Erlang term corresponding to the - head element in the list, or a NULL pointer if <c><![CDATA[list]]></c> was - not a list.</p> + <p>Returns the length of an I/O list.</p> + <p><c>list</c> is an Erlang term containing an I/O list.</p> + <p>Returns the length of <c>list</c>, or + <c>-1</c> if <c>list</c> is not an I/O list.</p> + <p>For the definition of an I/O list, see + <seealso marker="#erl_iolist_to_binary"> + <c>erl_iolist_to_binary</c></seealso>.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_iolist_to_binary(term)</nametext></name> - <fsummary>Converts an IO list to a binary</fsummary> + <fsummary>Convert an I/O list to a binary.</fsummary> <type> <v>ETERM *list;</v> </type> <desc> - <p>This function converts an IO list to a binary term.</p> - <p><c><![CDATA[list]]></c> is an Erlang term containing a list.</p> - <p>This function an Erlang binary term, or NULL if <c><![CDATA[list]]></c> - was not an IO list. </p> - <p>Informally, an IO list is a deep list of characters and - binaries which can be sent to an Erlang port. In BNF, an IO - list is formally defined as follows: </p> + <p>Converts an I/O list to a binary term.</p> + <p><c>list</c> is an Erlang term containing a list.</p> + <p>Returns an Erlang binary term, or <c>NULL</c> if + <c>list</c> was not an I/O list.</p> + <p>Informally, an I/O list is a deep list of characters and + binaries that can be sent to an Erlang port. In BNF, an I/O + list is formally defined as follows:</p> <code type="none"><![CDATA[ iolist ::= [] | Binary @@ -250,158 +287,164 @@ iohead ::= Binary ]]></code> </desc> </func> + <func> <name><ret>char *</ret><nametext>erl_iolist_to_string(list)</nametext></name> - <fsummary>Converts an IO list to a zero terminated string</fsummary> + <fsummary>Convert an I/O list to a <c>NULL</c>-terminated string.</fsummary> <type> <v>ETERM *list;</v> </type> <desc> - <p>This function converts an IO list to a '\0' terminated C - string. </p> - <p><c><![CDATA[list]]></c> is an Erlang term containing an IO list. The IO - list must not contain the integer 0, since C strings may not + <p>Converts an I/O list to a <c>NULL</c>-terminated C string.</p> + <p><c>list</c> is an Erlang term containing an I/O list. + The I/O list must not contain the integer 0, as C strings may not contain this value except as a terminating marker.</p> - <p>This function returns a pointer to a dynamically allocated - buffer containing a string. If <c><![CDATA[list]]></c> is not an IO list, - or if <c><![CDATA[list]]></c> contains the integer 0, NULL is returned. It - is the caller's responsibility free the allocated buffer - with <c><![CDATA[erl_free()]]></c>. </p> - <p>Refer to <c><![CDATA[erl_iolist_to_binary()]]></c> for the definition of an - IO list. </p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>erl_iolist_length(list)</nametext></name> - <fsummary>Return the length of an IO list</fsummary> - <type> - <v>ETERM *list;</v> - </type> - <desc> - <p>Returns the length of an IO list. - </p> - <p><c><![CDATA[list]]></c> is an Erlang term containing an IO list. </p> - <p>The function returns the length of <c><![CDATA[list]]></c>, or -1 if - <c><![CDATA[list]]></c> is not an IO list.</p> - <p>Refer to <c><![CDATA[erl_iolist_to_binary()]]></c> for the definition of - an IO list. </p> + <p>Returns a pointer to a dynamically allocated + buffer containing a string. If <c>list</c> is not an I/O + list, or if <c>list</c> contains the integer 0, + <c>NULL</c> is returned. It + is the caller's responsibility to free the allocated buffer + with <c>erl_free()</c>.</p> + <p>For the definition of an I/O list, see + <seealso marker="#erl_iolist_to_binary"> + <c>erl_iolist_to_binary</c></seealso>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_length(list)</nametext></name> - <fsummary>Determines the length of a list</fsummary> + <fsummary>Determine the length of a list.</fsummary> <type> <v>ETERM *list;</v> </type> <desc> <p>Determines the length of a proper list.</p> - <p><c><![CDATA[list]]></c> is an Erlang term containing proper list. In a - proper list, all tails except the last point to another list + <p><c>list</c> is an Erlang term containing a proper list. + In a proper list, all tails except the last point to another list cell, and the last tail points to an empty list.</p> - <p>Returns -1 if <c><![CDATA[list]]></c> is not a proper list.</p> + <p>Returns <c>-1</c> if <c>list</c> is not a proper + list.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_atom(string)</nametext></name> - <fsummary>Creates an atom</fsummary> + <fsummary>Create an atom.</fsummary> <type> <v>const char *string;</v> </type> <desc> <p>Creates an atom.</p> - <p><c><![CDATA[string]]></c> is the sequence of characters that will be + <p><c>string</c> is the sequence of characters that will be used to create the atom.</p> - <p>Returns an Erlang term containing an atom. Note that it is - the callers responsibility to make sure that <c><![CDATA[string]]></c> + <p>Returns an Erlang term containing an atom. Notice that it is + the caller's responsibility to ensure that <c>string</c> contains a valid name for an atom.</p> - <p><c><![CDATA[ERL_ATOM_PTR(atom)]]></c> and <c><![CDATA[ERL_ATOM_PTR_UTF8(atom)]]></c> - can be used to retrieve the atom name (as a null terminated string). <c><![CDATA[ERL_ATOM_SIZE(atom)]]></c> - and <c><![CDATA[ERL_ATOM_SIZE_UTF8(atom)]]></c> returns the length of the atom name.</p> - <note><p>Note that the UTF8 variants were introduced in Erlang/OTP releases R16 - and the string returned by <c>ERL_ATOM_PTR(atom)</c> was not null terminated on older releases.</p> + <p><c>ERL_ATOM_PTR(atom)</c> and + <c>ERL_ATOM_PTR_UTF8(atom)</c> + can be used to retrieve the atom name (as a <c>NULL</c>-terminated string). + <c>ERL_ATOM_SIZE(atom)</c> + and <c>ERL_ATOM_SIZE_UTF8(atom)</c> return the length + of the atom name.</p> + <note> + <p>The UTF-8 variants were introduced in Erlang/OTP R16 and the + string returned by <c>ERL_ATOM_PTR(atom)</c> was not + <c>NULL</c>-terminated on older releases.</p> </note> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_binary(bptr, size)</nametext></name> - <fsummary>Creates a binary object</fsummary> + <fsummary>Create a binary object.</fsummary> <type> <v>char *bptr;</v> <v>int size;</v> </type> <desc> - <p>This function produces an Erlang binary object from a + <p>Produces an Erlang binary object from a buffer containing a sequence of bytes.</p> - <p><c><![CDATA[bptr]]></c> is a pointer to a buffer containing data to be converted.</p> - <p><c><![CDATA[size]]></c> indicates the length of <c><![CDATA[bptr]]></c>.</p> - <p>The function returns an Erlang binary object.</p> - <p><c><![CDATA[ERL_BIN_PTR(bin)]]></c> retrieves a pointer to - the binary data. <c><![CDATA[ERL_BIN_SIZE(bin)]]></c> retrieves the - size. </p> + <list type="bulleted"> + <item><c>bptr</c> is a pointer to a buffer containing + data to be converted.</item> + <item><c>size</c> indicates the length of + <c>bptr</c>.</item> + </list> + <p>Returns an Erlang binary object.</p> + <p><c>ERL_BIN_PTR(bin)</c> retrieves a pointer to + the binary data. <c>ERL_BIN_SIZE(bin)</c> retrieves the + size.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_empty_list()</nametext></name> - <fsummary>Creates an empty Erlang list</fsummary> + <fsummary>Create an empty Erlang list.</fsummary> <desc> - <p>This function creates and returns an empty Erlang list. - Note that NULL is not used to represent an empty list; + <p>Creates and returns an empty Erlang list. + Notice that <c>NULL</c> is not used to represent an empty list; Use this function instead.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_estring(string, len)</nametext></name> - <fsummary>Creates an Erlang string</fsummary> + <fsummary>Create an Erlang string.</fsummary> <type> <v>char *string;</v> <v>int len;</v> </type> <desc> - <p>This function creates a list from a sequence of bytes.</p> - <p><c><![CDATA[string]]></c> is a buffer containing a sequence of - bytes. The buffer does not need to be zero-terminated.</p> - <p><c><![CDATA[len]]></c> is the length of <c><![CDATA[string]]></c>.</p> - <p>The function returns an Erlang list object corresponding to - the character sequence in <c><![CDATA[string]]></c>.</p> + <p>Creates a list from a sequence of bytes.</p> + <list type="bulleted"> + <item><c>string</c> is a buffer containing a sequence of + bytes. The buffer does not need to be <c>NULL</c>-terminated.</item> + <item><c>len</c> is the length of + <c>string</c>.</item> + </list> + <p>Returns an Erlang list object corresponding to + the character sequence in <c>string</c>.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_float(f)</nametext></name> - <fsummary>Creates an Erlang float</fsummary> + <fsummary>Create an Erlang float.</fsummary> <type> <v>double f;</v> </type> <desc> <p>Creates an Erlang float.</p> - <p><c><![CDATA[f]]></c> is a value to be converted to an Erlang float.</p> - <p></p> - <p>The function returns an Erlang float object with the value - specified in <c><![CDATA[f]]></c> or <c><![CDATA[NULL]]></c> if - <c><![CDATA[f]]></c> is not finite. - </p> - <p><c><![CDATA[ERL_FLOAT_VALUE(t)]]></c> can be used to retrieve the - value from an Erlang float.</p> + <p><c>f</c> is a value to be converted to an Erlang + float.</p> + <p>Returns an Erlang float object with the value + specified in <c>f</c> or <c>NULL</c> if + <c>f</c> is not finite.</p> + <p><c>ERL_FLOAT_VALUE(t)</c> can be used to retrieve the + value from an Erlang float.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_int(n)</nametext></name> - <fsummary>Creates an Erlang integer</fsummary> + <fsummary>Create an Erlang integer.</fsummary> <type> <v>int n;</v> </type> <desc> <p>Creates an Erlang integer.</p> - <p><c><![CDATA[n]]></c> is a value to be converted to an Erlang integer.</p> - <p></p> - <p>The function returns an Erlang integer object with the - value specified in <c><![CDATA[n]]></c>.</p> - <p><c><![CDATA[ERL_INT_VALUE(t)]]></c> can be used to retrieve the value + <p><c>n</c> is a value to be converted to an Erlang + integer.</p> + <p>Returns an Erlang integer object with the + value specified in <c>n</c>.</p> + <p><c>ERL_INT_VALUE(t)</c> can be used to retrieve the value from an Erlang integer.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_list(array, arrsize)</nametext></name> - <fsummary>Creates a list from an array</fsummary> + <fsummary>Create a list from an array.</fsummary> <type> <v>ETERM **array;</v> <v>int arrsize;</v> @@ -409,280 +452,316 @@ iohead ::= Binary <desc> <p>Creates an Erlang list from an array of Erlang terms, such that each element in the list corresponds to one element in - the array. </p> - <p><c><![CDATA[array]]></c> is an array of Erlang terms.</p> - <p><c><![CDATA[arrsize]]></c> is the number of elements in <c><![CDATA[array]]></c>.</p> + the array.</p> + <list type="bulleted"> + <item><c>array</c> is an array of Erlang terms.</item> + <item><c>arrsize</c> is the number of elements in + <c>array</c>.</item> + </list> <p>The function creates an Erlang list object, whose length - <c><![CDATA[arrsize]]></c> and whose elements are taken from the terms in - <c><![CDATA[array]]></c>.</p> + <c>arrsize</c> and whose elements are taken from the + terms in <c>array</c>.</p> </desc> </func> + <func> - <name><ret>ETERM *</ret><nametext>erl_mk_pid(node, number, serial, creation)</nametext></name> - <fsummary>Creates a process identifier</fsummary> + <name><ret>ETERM *</ret><nametext>erl_mk_long_ref(node, n1, n2, n3, creation)</nametext></name> + <fsummary>Create an Erlang reference.</fsummary> <type> <v>const char *node;</v> - <v>unsigned int number;</v> - <v>unsigned int serial;</v> + <v>unsigned int n1, n2, n3;</v> <v>unsigned int creation;</v> </type> <desc> - <p>This function creates an Erlang process identifier. The - resulting pid can be used by Erlang processes wishing to - communicate with the C node.</p> - <p><c><![CDATA[node]]></c> is the name of the C node.</p> - <p><c><![CDATA[number]]></c>, <c><![CDATA[serial]]></c> and <c><![CDATA[creation]]></c> are - arbitrary numbers. Note though, that these are limited in - precision, so only the low 15, 3 and 2 bits of these numbers - are actually used.</p> - <p>The function returns an Erlang pid object.</p> - <p><c><![CDATA[ERL_PID_NODE(pid)]]></c>, <c><![CDATA[ERL_PID_NUMBER(pid)]]></c>, - <c><![CDATA[ERL_PID_SERIAL(pid)]]></c> and <c><![CDATA[ERL_PID_CREATION(pid)]]></c> - can be used to retrieve the four values used to create the pid.</p> + <p>Creates an Erlang reference, with 82 bits.</p> + <list type="bulleted"> + <item><c>node</c> is the name of the C-node.</item> + <item><c>n1</c>, <c>n2</c>, and + <c>n3</c> can be seen as one big number + <c>n1*2^64+n2*2^32+n3</c>, which is to be chosen + uniquely for each reference created for a given C-node.</item> + <item><c>creation</c> is an arbitrary number.</item> + </list> + <p>Notice that <c>n3</c> and <c>creation</c> + are limited in precision, so only the low 18 and 2 bits of these + numbers are used.</p> + <p>Returns an Erlang reference object.</p> + <p><c>ERL_REF_NODE(ref)</c>, + <c>ERL_REF_NUMBERS(ref)</c>, + <c>ERL_REF_LEN(ref)</c>, and + <c>ERL_REF_CREATION(ref)</c> can be used to retrieve the + values used to create the reference.</p> </desc> </func> + <func> - <name><ret>ETERM *</ret><nametext>erl_mk_port(node, number, creation)</nametext></name> - <fsummary>Creates a port identifier</fsummary> + <name><ret>ETERM *</ret><nametext>erl_mk_pid(node, number, serial, creation)</nametext></name> + <fsummary>Create a process identifier.</fsummary> <type> <v>const char *node;</v> <v>unsigned int number;</v> + <v>unsigned int serial;</v> <v>unsigned int creation;</v> </type> <desc> - <p>This function creates an Erlang port identifier. </p> - <p><c><![CDATA[node]]></c> is the name of the C node.</p> - <p><c><![CDATA[number]]></c> and <c><![CDATA[creation]]></c> are arbitrary numbers. - Note though, that these are limited in - precision, so only the low 18 and 2 bits of these numbers - are actually used.</p> - <p>The function returns an Erlang port object.</p> - <p><c><![CDATA[ERL_PORT_NODE(port)]]></c>, <c><![CDATA[ERL_PORT_NUMBER(port)]]></c> - and <c><![CDATA[ERL_PORT_CREATION]]></c> can be used to retrieve the three - values used to create the port. </p> + <p>Creates an Erlang process identifier (pid). The + resulting pid can be used by Erlang processes wishing to + communicate with the C-node.</p> + <list type="bulleted"> + <item><c>node</c> is the name of the C-node.</item> + <item><c>number</c>, <c>serial</c>, and + <c>creation</c> are + arbitrary numbers. Notice that these are limited in + precision, so only the low 15, 3, and 2 bits of these numbers + are used.</item> + </list> + <p>Returns an Erlang pid object.</p> + <p><c>ERL_PID_NODE(pid)</c>, + <c>ERL_PID_NUMBER(pid)</c>, + <c>ERL_PID_SERIAL(pid)</c>, and + <c>ERL_PID_CREATION(pid)</c> + can be used to retrieve the four values used to create the pid.</p> </desc> </func> + <func> - <name><ret>ETERM *</ret><nametext>erl_mk_ref(node, number, creation)</nametext></name> - <fsummary>Creates an old Erlang reference</fsummary> + <name><ret>ETERM *</ret><nametext>erl_mk_port(node, number, creation)</nametext></name> + <fsummary>Create a port identifier.</fsummary> <type> <v>const char *node;</v> <v>unsigned int number;</v> <v>unsigned int creation;</v> </type> <desc> - <p>This function creates an old Erlang reference, with - only 18 bits - use <c><![CDATA[erl_mk_long_ref]]></c> instead.</p> - <p><c><![CDATA[node]]></c> is the name of the C node.</p> - <p><c><![CDATA[number]]></c> should be chosen uniquely for each reference - created for a given C node.</p> - <p><c><![CDATA[creation]]></c> is an arbitrary number.</p> - <p>Note that <c><![CDATA[number]]></c> and <c><![CDATA[creation]]></c> are limited in - precision, so only the low 18 and 2 bits of these numbers - are actually used. - </p> - <p>The function returns an Erlang reference object.</p> - <p><c><![CDATA[ERL_REF_NODE(ref)]]></c>, <c><![CDATA[ERL_REF_NUMBER(ref)]]></c>, and - <c><![CDATA[ERL_REF_CREATION(ref)]]></c> to retrieve the three values used - to create the reference. </p> + <p>Creates an Erlang port identifier.</p> + <list type="bulleted"> + <item><c>node</c> is the name of the C-node.</item> + <item><c>number</c> and <c>creation</c> are + arbitrary numbers. Notice that these are limited in + precision, so only the low 18 and 2 bits of these numbers + are used.</item> + </list> + <p>Returns an Erlang port object.</p> + <p><c>ERL_PORT_NODE(port)</c>, + <c>ERL_PORT_NUMBER(port)</c>, + and <c>ERL_PORT_CREATION</c> can be used to retrieve the + three values used to create the port.</p> </desc> </func> + <func> - <name><ret>ETERM *</ret><nametext>erl_mk_long_ref(node, n1, n2, n3, creation)</nametext></name> - <fsummary>Creates an Erlang reference</fsummary> + <name><ret>ETERM *</ret><nametext>erl_mk_ref(node, number, creation)</nametext></name> + <fsummary>Create an old Erlang reference.</fsummary> <type> <v>const char *node;</v> - <v>unsigned int n1, n2, n3;</v> + <v>unsigned int number;</v> <v>unsigned int creation;</v> </type> <desc> - <p>This function creates an Erlang reference, with 82 bits.</p> - <p><c><![CDATA[node]]></c> is the name of the C node.</p> - <p><c><![CDATA[n1]]></c>, <c><![CDATA[n2]]></c> and <c><![CDATA[n3]]></c> can be seen as one big number - <c><![CDATA[n1*2^64+n2*2^32+n3]]></c> which should be chosen uniquely for - each reference - created for a given C node.</p> - <p><c><![CDATA[creation]]></c> is an arbitrary number.</p> - <p>Note that <c><![CDATA[n3]]></c> and <c><![CDATA[creation]]></c> are limited in - precision, so only the low 18 and 2 bits of these numbers - are actually used. - </p> - <p>The function returns an Erlang reference object.</p> - <p><c><![CDATA[ERL_REF_NODE(ref)]]></c>, <c><![CDATA[ERL_REF_NUMBERS(ref)]]></c>, - <c><![CDATA[ERL_REF_LEN(ref)]]></c> and - <c><![CDATA[ERL_REF_CREATION(ref)]]></c> to retrieve the values used - to create the reference. </p> + <p>Creates an old Erlang reference, with + only 18 bits - use <c>erl_mk_long_ref</c> instead.</p> + <list type="bulleted"> + <item><c>node</c> is the name of the C-node.</item> + <item><c>number</c> is to be chosen uniquely for each + reference created for a given C-node.</item> + <item><c>creation</c> is an arbitrary number.</item> + </list> + <p>Notice that <c>number</c> and <c>creation</c> + are limited in precision, so only the low 18 and 2 bits of these + numbers are used.</p> + <p>Returns an Erlang reference object.</p> + <p><c>ERL_REF_NODE(ref)</c>, + <c>ERL_REF_NUMBER(ref)</c>, and + <c>ERL_REF_CREATION(ref)</c> can be used to retrieve the + three values used to create the reference.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_string(string)</nametext></name> - <fsummary>Creates a string</fsummary> + <fsummary>Create a string.</fsummary> <type> <v>char *string;</v> </type> <desc> - <p>This function creates a list from a zero terminated string.</p> - <p><c><![CDATA[string]]></c> is the zero-terminated sequence of characters - (i.e. a C string) from which the list will be created.</p> - <p>The function returns an Erlang list.</p> + <p>Creates a list from a <c>NULL</c>-terminated string.</p> + <p><c>string</c> is a <c>NULL</c>-terminated sequence of + characters + (that is, a C string) from which the list will be created.</p> + <p>Returns an Erlang list.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_tuple(array, arrsize)</nametext></name> - <fsummary>Creates an Erlang tuple from an array</fsummary> + <fsummary>Create an Erlang tuple from an array.</fsummary> <type> <v>ETERM **array;</v> <v>int arrsize;</v> </type> <desc> <p>Creates an Erlang tuple from an array of Erlang terms.</p> - <p><c><![CDATA[array]]></c> is an array of Erlang terms.</p> - <p><c><![CDATA[arrsize]]></c> is the number of elements in <c><![CDATA[array]]></c>.</p> + <list type="bulleted"> + <item><c>array</c> is an array of Erlang terms.</item> + <item><c>arrsize</c> is the number of elements in + <c>array</c>.</item> + </list> <p>The function creates an Erlang tuple, whose arity is - <c><![CDATA[size]]></c> and whose elements are taken from the terms in - <c><![CDATA[array]]></c>.</p> - <p>To retrieve the size of a tuple, either use the - <c><![CDATA[erl_size]]></c> function (which checks the type of the checked - term and works for a binary as well as for a tuple), or the - <c><![CDATA[ERL_TUPLE_SIZE(tuple)]]></c> returns the arity of a tuple. - <c><![CDATA[erl_size()]]></c> will do the same thing, but it checks that - the argument really is a tuple. - <c><![CDATA[erl_element(index,tuple)]]></c> returns the element - corresponding to a given position in the tuple. </p> + <c>size</c> and whose elements are taken from the terms + in <c>array</c>.</p> + <p>To retrieve the size of a tuple, either use function + <c>erl_size</c> (which checks the type of the + checked term and works for a binary as well as for a tuple) or + <c>ERL_TUPLE_SIZE(tuple)</c> returns the arity of a tuple. + <c>erl_size()</c> does the same thing, but it checks + that the argument is a tuple. + <c>erl_element(index,tuple)</c> returns the element + corresponding to a given position in the tuple.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_uint(n)</nametext></name> - <fsummary>Creates an unsigned integer</fsummary> + <fsummary>Create an unsigned integer.</fsummary> <type> <v>unsigned int n;</v> </type> <desc> <p>Creates an Erlang unsigned integer.</p> - <p><c><![CDATA[n]]></c> is a value to be converted to an Erlang + <p><c>n</c> is a value to be converted to an Erlang unsigned integer.</p> - <p></p> - <p>The function returns an Erlang unsigned integer object with - the value specified in <c><![CDATA[n]]></c>.</p> - <p><c><![CDATA[ERL_INT_UVALUE(t)]]></c> can be used to retrieve the + <p>Returns an Erlang unsigned integer object with + the value specified in <c>n</c>.</p> + <p><c>ERL_INT_UVALUE(t)</c> can be used to retrieve the value from an Erlang unsigned integer.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_var(name)</nametext></name> - <fsummary>Creates an Erlang variable</fsummary> + <fsummary>Create an Erlang variable.</fsummary> <type> <v>char *name;</v> </type> <desc> - <p>This function creates an unbound Erlang variable. The - variable can later be bound through pattern matching or assignment.</p> - <p><c><![CDATA[name]]></c> specifies a name for the variable.</p> - <p>The function returns an Erlang variable object with the - name <c><![CDATA[name]]></c>. </p> + <p>Creates an unbound Erlang variable. The variable can later be bound + through pattern matching or assignment.</p> + <p><c>name</c> specifies a name for the variable.</p> + <p>Returns an Erlang variable object with the + name <c>name</c>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_print_term(stream, term)</nametext></name> - <fsummary>Prints an Erlang term</fsummary> + <fsummary>Print an Erlang term.</fsummary> <type> <v>FILE *stream;</v> <v>ETERM *term;</v> </type> <desc> - <p>This function prints the specified Erlang term to the given - output stream.</p> - <p><c><![CDATA[stream]]></c> indicates where the function should send its - output.</p> - <p><c><![CDATA[term]]></c> is the Erlang term to print.</p> - <p>The function returns the number of characters written, or a - negative value if there was an error.</p> + <p>Prints the specified Erlang term to the specified output stream.</p> + <list type="bulleted"> + <item><c>stream</c> indicates where the function is to + send its output.</item> + <item><c>term</c> is the Erlang term to print.</item> + </list> + <p>Returns the number of characters written on success, otherwise a + negative value.</p> </desc> </func> + <func> <name><ret>void</ret><nametext>erl_set_compat_rel(release_number)</nametext></name> - <fsummary>Set the erl_interface library in compatibility mode</fsummary> + <fsummary>Set the Erl_Interface library in compatibility mode.</fsummary> <type> <v>unsigned release_number;</v> </type> <desc> - <marker id="erl_set_compat_rel"></marker> - <p>By default, the <c><![CDATA[erl_interface]]></c> library is only guaranteed - to be compatible with other Erlang/OTP components from the same - release as the <c><![CDATA[erl_interface]]></c> library itself. For example, - <c><![CDATA[erl_interface]]></c> from the OTP R10 release is not compatible - with an Erlang emulator from the OTP R9 release by default.</p> - <p>A call to <c><![CDATA[erl_set_compat_rel(release_number)]]></c> sets the - <c><![CDATA[erl_interface]]></c> library in compatibility mode of release - <c><![CDATA[release_number]]></c>. Valid range of <c><![CDATA[release_number]]></c> + <p>By default, the <c>Erl_Interface</c> library is only + guaranteed to be compatible with other Erlang/OTP components from the + same release as the <c>Erl_Interface</c> library itself. + For example, <c>Erl_Interface</c> from Erlang/OTP R10 + is not compatible + with an Erlang emulator from Erlang/OTP R9 by default.</p> + <p>A call to <c>erl_set_compat_rel(release_number)</c> sets + the <c>Erl_Interface</c> library in compatibility mode of + release <c>release_number</c>. Valid range of + <c>release_number</c> is [7, current release]. This makes it possible to communicate with Erlang/OTP components from earlier releases.</p> <note> <p>If this function is called, it may only be called once - directly after the call to the - <seealso marker="#erl_init">erl_init()</seealso> function.</p> + directly after the call to function + <seealso marker="#erl_init">erl_init()</seealso>.</p> </note> <warning> <p>You may run into trouble if this feature is used - carelessly. Always make sure that all communicating + carelessly. Always ensure that all communicating components are either from the same Erlang/OTP release, or from release X and release Y where all components from release Y are in compatibility mode of release X.</p> </warning> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_size(term)</nametext></name> - <fsummary>Return the arity of a tuple or binary</fsummary> + <fsummary>Return the arity of a tuple or binary.</fsummary> <type> <v>ETERM *term;</v> </type> <desc> - <p>Returns the arity of an Erlang tuple, or the - number of bytes in an Erlang binary object. </p> - <p><c><![CDATA[term]]></c> is an Erlang tuple or an Erlang binary object.</p> - <p>The function returns the size of <c><![CDATA[term]]></c> as described - above, or -1 if <c><![CDATA[term]]></c> is not one of the two supported - types. </p> + <p>Returns either the arity of an Erlang tuple or the + number of bytes in an Erlang binary object.</p> + <p><c>term</c> is an Erlang tuple or an Erlang binary + object.</p> + <p>Returns the size of <c>term</c> as described + above, or <c>-1</c> if <c>term</c> is not one of the two + supported types.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_tl(list)</nametext></name> - <fsummary>Extracts the tail from a list</fsummary> + <fsummary>Extract the tail from a list.</fsummary> <type> <v>ETERM *list;</v> </type> <desc> <p>Extracts the tail from a list.</p> - <p><c><![CDATA[list]]></c> is an Erlang term containing a list.</p> - <p>The function returns an Erlang list corresponding to the - original list minus the first element, or NULL pointer if - <c><![CDATA[list]]></c> was not a list.</p> + <p><c>list</c> is an Erlang term containing a list.</p> + <p>Returns an Erlang list corresponding to the + original list minus the first element, or <c>NULL</c> pointer if + <c>list</c> was not a list.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_var_content(term, name)</nametext></name> - <fsummary>Extracts the content of a variable</fsummary> + <fsummary>Extract the content of a variable.</fsummary> <type> <v>ETERM *term;</v> <v>char *name;</v> </type> <desc> - <p>This function returns the contents of the specified - variable in an Erlang term. - </p> - <p><c><![CDATA[term]]></c> is an Erlang term. In order for this function - to succeed, <c><![CDATA[term]]></c> must be an Erlang variable with the - specified name, or it must be an Erlang list or tuple - containing a variable with the specified name. Other Erlang - types cannot contain variables.</p> - <p><c><![CDATA[name]]></c> is the name of an Erlang variable.</p> + <p>Returns the contents of the specified variable in an Erlang term.</p> + <list type="bulleted"> + <item><c>term</c> is an Erlang term. In order for this + function to succeed, + <c>term</c> must either be an Erlang variable with + the specified name, or it must be an Erlang list or tuple + containing a variable with the specified name. Other Erlang + types cannot contain variables.</item> + <item><c>name</c> is the name of an Erlang variable. + </item> + </list> <p>Returns the Erlang object corresponding to the value of - <c><![CDATA[name]]></c> in <c><![CDATA[term]]></c>. If no variable with the name - <c><![CDATA[name]]></c> was found in <c><![CDATA[term]]></c>, or if <c><![CDATA[term]]></c> is - not a valid Erlang term, NULL is returned.</p> + <c>name</c> in <c>term</c>. If no variable + with the name <c>name</c> is found in + <c>term</c>, or if <c>term</c> is + not a valid Erlang term, <c>NULL</c> is returned.</p> </desc> </func> </funcs> </cref> - diff --git a/lib/erl_interface/doc/src/erl_format.xml b/lib/erl_interface/doc/src/erl_format.xml index 6e3ac4f0c9..5b8b7b5e78 100644 --- a/lib/erl_interface/doc/src/erl_format.xml +++ b/lib/erl_interface/doc/src/erl_format.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>erl_format</title> @@ -28,51 +28,42 @@ <docno></docno> <approved>Bjarne Däcker</approved> <checked>Torbjörn Törnkvist</checked> - <date>961016</date> + <date>1996-10-16</date> <rev>A</rev> - <file>erl_format.sgml</file> + <file>erl_format.xml</file> </header> <lib>erl_format</lib> - <libsummary>Create and Match Erlang Terms</libsummary> + <libsummary>Create and match Erlang terms.</libsummary> <description> - <p>This module contains two routines - one general function for + <p>This module contains two routines: one general function for creating Erlang terms and one for pattern matching Erlang terms.</p> </description> + <funcs> <func> - <name><ret>ETERM *</ret><nametext>erl_format(FormatStr, ... )</nametext></name> - <fsummary>Creates an Erlang term</fsummary> + <name><ret>ETERM *</ret><nametext>erl_format(FormatStr, ...)</nametext></name> + <fsummary>Create an Erlang term.</fsummary> <type> <v>char *FormatStr;</v> </type> <desc> - <p>This is a general function for creating Erlang terms using + <p>A general function for creating Erlang terms using a format specifier and a corresponding set of arguments, much - in the way <c><![CDATA[printf()]]></c> works.</p> - <p><c><![CDATA[FormatStr]]></c> is a format specification string. The set - of valid format specifiers is as follows:</p> + in the way <c>printf()</c> works.</p> + <p><c>FormatStr</c> is a format specification string. + The valid format specifiers are as follows:</p> <list type="bulleted"> - <item> - <p>~i - Integer</p> - </item> - <item> - <p>~f - Floating point</p> - </item> - <item> - <p>~a - Atom</p> - </item> - <item> - <p>~s - String</p> - </item> - <item> - <p>~w - Arbitrary Erlang term</p> - </item> + <item><c>~i</c> - Integer</item> + <item><c>~f</c> - Floating point</item> + <item><c>~a</c> - Atom</item> + <item><c>~s</c> - String</item> + <item><c>~w</c> - Arbitrary Erlang term</item> </list> - <p>For each format specifier that appears in <c><![CDATA[FormatStr]]></c>, + <p>For each format specifier included in <c>FormatStr</c>, there must be a corresponding argument following - <c><![CDATA[FormatStr]]></c>. An Erlang term is built according to the - <c><![CDATA[FormatStr]]></c> with values and Erlang terms substituted from - the corresponding arguments and according to the individual + <c>FormatStr</c>. An Erlang term is built according to + <c>FormatStr</c> with values and Erlang terms substituted + from the corresponding arguments, and according to the individual format specifiers. For example:</p> <code type="none"><![CDATA[ erl_format("[{name,~a},{age,~i},{data,~w}]", @@ -80,34 +71,40 @@ erl_format("[{name,~a},{age,~i},{data,~w}]", 21, erl_format("[{adr,~s,~i}]","E-street",42)); ]]></code> - <p>This will create an <c><![CDATA[(ETERM *)]]></c> structure corresponding - to the Erlang term: - <c><![CDATA[[{name,madonna},{age,21},{data,[{adr,"E-street",42}]}]]]></c></p> - <p>The function returns an Erlang term, or NULL if - <c><![CDATA[FormatStr]]></c> does not describe a valid Erlang term.</p> + <p>This creates an <c>(ETERM *)</c> structure corresponding + to the Erlang term + <c>[{name,madonna},{age,21},{data,[{adr,"E-street",42}]}]</c></p> + <p>The function returns an Erlang term, or <c>NULL</c> if + <c>FormatStr</c> does not describe a valid Erlang + term.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_match(Pattern, Term)</nametext></name> - <fsummary>Performs pattern matching</fsummary> + <fsummary>Perform pattern matching.</fsummary> <type> <v>ETERM *Pattern,*Term;</v> </type> <desc> <p>This function is used to perform pattern matching similar - to that done in Erlang. Refer to an Erlang manual for matching - rules and more examples.</p> - <p><c><![CDATA[Pattern]]></c> is an Erlang term, possibly containing unbound - variables. </p> - <p><c><![CDATA[Term]]></c> is an Erlang term that we wish to match against - <c><![CDATA[Pattern]]></c>.</p> - <p><c><![CDATA[Term]]></c> and <c><![CDATA[Pattern]]></c> are compared, and any - unbound variables in <c><![CDATA[Pattern]]></c> are bound to corresponding - values in <c><![CDATA[Term]]></c>. </p> - <p>If <c><![CDATA[Term]]></c> and <c><![CDATA[Pattern]]></c> can be matched, the - function returns a non-zero value and binds any unbound - variables in <c><![CDATA[Pattern]]></c>. If <c><![CDATA[Term]]></c> <c><![CDATA[Pattern]]></c> do - not match, the function returns 0. For example:</p> + to that done in Erlang. For matching rules and more examples, see + section <seealso marker="doc/reference_manual:patterns"> + Pattern Matching</seealso> in the Erlang Reference Manual.</p> + <list type="bulleted"> + <item><c>Pattern</c> is an Erlang term, possibly + containing unbound variables.</item> + <item><c>Term</c> is an Erlang term that we wish to match + against <c>Pattern</c>.</item> + </list> + <p><c>Term</c> and <c>Pattern</c> are compared + and any unbound variables in <c>Pattern</c> are bound to + corresponding values in <c>Term</c>.</p> + <p>If <c>Term</c> and <c>Pattern</c> can be + matched, the function returns a non-zero value and binds any unbound + variables in <c>Pattern</c>. If <c>Term</c> + and <c>Pattern</c> do + not match, <c>0</c> is returned. For example:</p> <code type="none"><![CDATA[ ETERM *term, *pattern, *pattern2; term1 = erl_format("{14,21}"); @@ -132,11 +129,10 @@ if (erl_match(pattern2, term2)) { ... } ]]></code> - <p><c><![CDATA[erl_var_content()]]></c> can be used to retrieve the + <p><c>erl_var_content()</c> can be used to retrieve the content of any variables bound as a result of a call to - <c><![CDATA[erl_match()]]></c>.</p> + <c>erl_match()</c>.</p> </desc> </func> </funcs> </cref> - diff --git a/lib/erl_interface/doc/src/erl_global.xml b/lib/erl_interface/doc/src/erl_global.xml index d6bfffc69d..2fa0045adf 100644 --- a/lib/erl_interface/doc/src/erl_global.xml +++ b/lib/erl_interface/doc/src/erl_global.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>erl_global</title> @@ -28,115 +28,125 @@ <docno></docno> <approved>Gordon Beaton</approved> <checked>Gordon Beaton</checked> - <date>980703</date> + <date>1998-07-03</date> <rev>A</rev> - <file>erl_global.sgml</file> + <file>erl_global.xml</file> </header> <lib>erl_global</lib> - <libsummary>Access globally registered names</libsummary> + <libsummary>Access globally registered names.</libsummary> <description> <p>This module provides support for registering, looking - up and unregistering names in the Erlang Global module. For more - information, see the description of Global in the reference manual.</p> - <p>Note that the functions below perform an RPC using an open file - descriptor provided by the caller. This file descriptor must - not be used for other traffic during the global operation or the - function may receive unexpected data and fail.</p> + up, and unregistering names in the <c>global</c> module. + For more information, see + <seealso marker="kernel:global"><c>kernel:global</c></seealso>.</p> + + <p>Notice that the functions below perform an RPC using an open file + descriptor provided by the caller. This file descriptor must + not be used for other traffic during the global operation, as the + function can then receive unexpected data and fail.</p> </description> + <funcs> <func> <name><ret>char **</ret><nametext>erl_global_names(fd,count)</nametext></name> - <fsummary>Obtain list of Global names</fsummary> + <fsummary>Obtain list of global names.</fsummary> <type> <v>int fd;</v> <v>int *count;</v> </type> <desc> - <p>Retrieve a list of all known global names. - </p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection. - </p> - <p><c><![CDATA[count]]></c> is the address of an integer, or NULL. If - <c><![CDATA[count]]></c> is not NULL, it will be set by the function to - the number of names found. - </p> + <p>Retrieves a list of all known global names.</p> + <list type="bulleted"> + <item><c>fd</c> is an open descriptor to an Erlang + connection.</item> + <item><c>count</c> is the address of an integer, or + <c>NULL</c>. If <c>count</c> is not <c>NULL</c>, it is + set by the function to the number of names found.</item> + </list> <p>On success, the function returns an array of strings, each - containing a single registered name, and sets <c><![CDATA[count]]></c> to + containing a single registered name, and sets + <c>count</c> to the number of names found. The array is terminated - by a single NULL pointer. On failure, the function returns - NULL and <c><![CDATA[count]]></c> is not modified. - </p> + by a single <c>NULL</c> pointer. On failure, the function returns + <c>NULL</c> and <c>count</c> is not modified.</p> <note> <p>It is the caller's responsibility to free the array afterwards. It has been allocated by the function with a - single call to <c><![CDATA[malloc()]]></c>, so a single <c><![CDATA[free()]]></c> is - all that is necessary.</p> + single call to <c>malloc()</c>, so a single + <c>free()</c> is all that is necessary.</p> </note> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_global_register(fd,name,pid)</nametext></name> - <fsummary>Register a name in Global</fsummary> + <fsummary>Register a name in global.</fsummary> <type> <v>int fd;</v> <v>const char *name;</v> <v>ETERM *pid;</v> </type> <desc> - <p>This function registers a name in Global. - </p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection. - </p> - <p><c><![CDATA[name]]></c> is the name to register in Global. - </p> - <p><c><![CDATA[pid]]></c> is the pid that should be associated with - <c><![CDATA[name]]></c>. This is the value that Global will return when - processes request the location of <c><![CDATA[name]]></c>. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> + <p>Registers a name in <c>global</c>.</p> + <list type="bulleted"> + <item><c>fd</c> is an open descriptor to an Erlang + connection.</item> + <item><c>name</c> is the name to register in + <c>global</c>.</item> + <item><c>pid</c> is the pid that is to be associated with + <c>name</c>. This value is returned by <c>global</c> + when processes request the location of <c>name</c>. + </item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_global_unregister(fd,name)</nametext></name> - <fsummary>Unregister a name in Global</fsummary> + <fsummary>Unregister a name from global.</fsummary> <type> <v>int fd;</v> <v>const char *name;</v> </type> <desc> - <p>This function unregisters a name from Global. - </p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection. - </p> - <p><c><![CDATA[name]]></c> is the name to unregister from Global. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> + <p>Unregisters a name from <c>global</c>.</p> + <list type="bulleted"> + <item><c>fd</c> is an open descriptor to an Erlang + connection.</item> + <item><c>name</c> is the name to unregister from + <c>global</c>.</item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_global_whereis(fd,name,node)</nametext></name> - <fsummary>Look up a name in global</fsummary> + <fsummary>Look up a name in global.</fsummary> <type> <v>int fd;</v> <v>const char *name;</v> <v>char *node;</v> </type> <desc> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection. - </p> - <p><c><![CDATA[name]]></c> is the name that is to be looked up in Global. - </p> - <p>If <c><![CDATA[node]]></c> is not NULL, it is a pointer to a buffer - where the function can fill in the name of the node where - <c><![CDATA[name]]></c> is found. <c><![CDATA[node]]></c> can be passed directly to - <c><![CDATA[erl_connect()]]></c> if necessary. - </p> - <p>On success, the function returns an Erlang Pid containing the address - of the given name, and node will be initialized to - the nodename where <c><![CDATA[name]]></c> is found. On failure NULL will be - returned and <c><![CDATA[node]]></c> will not be modified.</p> + <p>Looks up a name in <c>global</c>.</p> + <list type="bulleted"> + <item><c>fd</c> is an open descriptor to an Erlang + connection.</item> + <item><c>name</c> is the name that is to be looked up in + <c>global</c>.</item> + </list> + <p>If <c>node</c> is not <c>NULL</c>, it is a pointer to a + buffer where the function can fill in the name of the node where + <c>name</c> is found. <c>node</c> can be + passed directly to <c>erl_connect()</c> if necessary.</p> + <p>On success, the function returns an Erlang pid containing the address + of the specified name, and the node is initialized to + the node name where <c>name</c> is found. On failure, + <c>NULL</c> is returned and <c>node</c> is not + modified.</p> </desc> </func> </funcs> </cref> - diff --git a/lib/erl_interface/doc/src/erl_interface.xml b/lib/erl_interface/doc/src/erl_interface.xml index a9d421bbeb..4e66655b39 100644 --- a/lib/erl_interface/doc/src/erl_interface.xml +++ b/lib/erl_interface/doc/src/erl_interface.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>The Erl_Interface Library</title> @@ -72,51 +72,51 @@ Eshell V4.7.4 (abort with ^G) 1> code:root_dir(). /usr/local/otp ]]></code> <p>To compile your code, make sure that your C compiler knows where - to find <c><![CDATA[erl_interface.h]]></c> by specifying an appropriate <c><![CDATA[-I]]></c> - argument on the command line, or by adding it to the <c><![CDATA[CFLAGS]]></c> - definition in your <c><![CDATA[Makefile]]></c>. The correct value for this path is - <c><![CDATA[$OTPROOT/lib/erl_interface]]></c><em>Vsn</em><c><![CDATA[/include]]></c>, where <c><![CDATA[$OTPROOT]]></c> is the path - reported by <c><![CDATA[code:root_dir/0]]></c> in the above example, and <em>Vsn</em> is + to find <c>erl_interface.h</c> by specifying an appropriate <c>-I</c> + argument on the command line, or by adding it to the <c>CFLAGS</c> + definition in your <c>Makefile</c>. The correct value for this path is + <c>$OTPROOT/lib/erl_interface</c><em>Vsn</em><c>/include</c>, where <c>$OTPROOT</c> is the path + reported by <c>code:root_dir/0</c> in the above example, and <em>Vsn</em> is the version of the Erl_interface application, for example - <c><![CDATA[erl_interface-3.2.3]]></c></p> + <c>erl_interface-3.2.3</c></p> <code type="none"><![CDATA[ $ cc -c -I/usr/local/otp/lib/erl_interface-3.2.3/include myprog.c ]]></code> <p>When linking, you will need to specify the path to - <c><![CDATA[liberl_interface.a]]></c> and <c><![CDATA[libei.a]]></c> with - <c><![CDATA[-L$OTPROOT/lib/erl_interface-3.2.3/lib]]></c>, and you will need to specify the - name of the libraries with <c><![CDATA[-lerl_interface -lei]]></c>. You can do - this on the command line or by adding the flags to the <c><![CDATA[LDFLAGS]]></c> - definition in your <c><![CDATA[Makefile]]></c>.</p> + <c>liberl_interface.a</c> and <c>libei.a</c> with + <c>-L$OTPROOT/lib/erl_interface-3.2.3/lib</c>, and you will need to specify the + name of the libraries with <c>-lerl_interface -lei</c>. You can do + this on the command line or by adding the flags to the <c>LDFLAGS</c> + definition in your <c>Makefile</c>.</p> <code type="none"><![CDATA[ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ lib myprog.o -lerl_interface -lei -o myprog ]]></code> <p>Also, on some systems it may be necessary to link with some - additional libraries (e.g. <c><![CDATA[libnsl.a]]></c> and <c><![CDATA[libsocket.a]]></c> on - Solaris, or <c><![CDATA[wsock32.lib]]></c> on Windows) in order to use the + additional libraries (e.g. <c>libnsl.a</c> and <c>libsocket.a</c> on + Solaris, or <c>wsock32.lib</c> on Windows) in order to use the communication facilities of Erl_Interface.</p> <p>If you are using Erl_Interface functions in a threaded application based on POSIX threads or Solaris threads, then Erl_Interface needs access to some of the synchronization facilities in your threads package, and you will need to specify additional compiler flags in order to indicate which of the packages - you are using. Define <c><![CDATA[_REENTRANT]]></c> and either <c><![CDATA[STHREADS]]></c> or - <c><![CDATA[PTHREADS]]></c>. The default is to use POSIX threads if - <c><![CDATA[_REENTRANT]]></c> is specified.</p> + you are using. Define <c>_REENTRANT</c> and either <c>STHREADS</c> or + <c>PTHREADS</c>. The default is to use POSIX threads if + <c>_REENTRANT</c> is specified.</p> <p>Note that both single threaded and default versions of the Erl_interface and Ei libraries are provided. (The single threaded versions are named - <c><![CDATA[liberl_interface_st]]></c> and <c><![CDATA[libei_st]]></c>). Whether the default + <c>liberl_interface_st</c> and <c>libei_st</c>). Whether the default versions of the libraries have support for threads or not is determined by if the platform in question has support for POSIX or Solaris threads. To check this, - have a look in the <c><![CDATA[eidefs.mk]]></c> file in the erl_interface src directory.</p> + have a look in the <c>eidefs.mk</c> file in the erl_interface src directory.</p> </section> <section> <title>Initializing the erl_interface Library</title> <p>Before calling any of the other Erl_Interface functions, you - must call <c><![CDATA[erl_init()]]></c> exactly once to initialize the library. - <c><![CDATA[erl_init()]]></c> takes two arguments, however the arguments are no + must call <c>erl_init()</c> exactly once to initialize the library. + <c>erl_init()</c> takes two arguments, however the arguments are no longer used by Erl_Interface, and should therefore be specified - as <c><![CDATA[erl_init(NULL,0)]]></c>.</p> + as <c>erl_init(NULL,0)</c>.</p> </section> <section> @@ -129,7 +129,7 @@ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ number of C functions which create and manipulate Erlang data structures. The library also contains an encode and a decode function. The example below shows how to create and encode an Erlang tuple - <c><![CDATA[{tobbe,3928}]]></c>:</p> + <c>{tobbe,3928}</c>:</p> <code type="none"><![CDATA[ ETERM *arr[2], *tuple; @@ -140,26 +140,26 @@ arr[0] = erl_mk_atom("tobbe"); arr[1] = erl_mk_integer(3928); tuple = erl_mk_tuple(arr, 2); i = erl_encode(tuple, buf); ]]></code> - <p>Alternatively, you can use <c><![CDATA[erl_send()]]></c> and - <c><![CDATA[erl_receive_msg]]></c>, which handle the encoding and decoding of + <p>Alternatively, you can use <c>erl_send()</c> and + <c>erl_receive_msg</c>, which handle the encoding and decoding of messages transparently.</p> <p>Refer to the Reference Manual for a complete description of the following modules:</p> <list type="bulleted"> - <item>the <c><![CDATA[erl_eterm]]></c> module for creating Erlang terms</item> - <item>the <c><![CDATA[erl_marshal]]></c> module for encoding and decoding routines.</item> + <item>the <c>erl_eterm</c> module for creating Erlang terms</item> + <item>the <c>erl_marshal</c> module for encoding and decoding routines.</item> </list> </section> <section> <title>Building Terms and Patterns</title> - <p>The previous example can be simplified by using - <c><![CDATA[erl_format()]]></c> to create an Erlang term.</p> + <p>The previous example can be simplified by using + <c>erl_format()</c> to create an Erlang term.</p> <code type="none"><![CDATA[ ETERM *ep; ep = erl_format("{~a,~i}", "tobbe", 3928); ]]></code> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_format]]></c> module, for a + <p>Refer to the Reference Manual, the <c>erl_format</c> module, for a full description of the different format directives. The following example is more complex:</p> <code type="none"><![CDATA[ @@ -171,10 +171,10 @@ ep = erl_format("[{name,~a},{age,~i},{data,~w}]", erl_format("[{adr,~s,~i}]", "E-street", 42)); erl_free_compound(ep); ]]></code> <p>As in previous examples, it is your responsibility to free the - memory allocated for Erlang terms. In this example, - <c><![CDATA[erl_free_compound()]]></c> ensures that the complete term pointed to - by <c><![CDATA[ep]]></c> is released. This is necessary, because the pointer from - the second call to <c><![CDATA[erl_format()]]></c> is lost. </p> + memory allocated for Erlang terms. In this example, + <c>erl_free_compound()</c> ensures that the complete term pointed to + by <c>ep</c> is released. This is necessary, because the pointer from + the second call to <c>erl_format()</c> is lost. </p> <p>The following example shows a slightly different solution:</p> <code type="none"><![CDATA[ @@ -186,7 +186,7 @@ ep = erl_format("[{name,~a},{age,~i},{data,~w}]", erl_free_term(ep); erl_free_term(ep2); ]]></code> <p>In this case, you free the two terms independently. The order in - which you free the terms <c><![CDATA[ep]]></c> and <c><![CDATA[ep2]]></c> is not important, + which you free the terms <c>ep</c> and <c>ep2</c> is not important, because the Erl_Interface library uses reference counting to determine when it is safe to actually remove objects. </p> <p>If you are not sure whether you have freed the terms properly, you @@ -204,14 +204,14 @@ printf("length of freelist: %ld\ /* really free the freelist */ erl_eterm_release(); ]]></code> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_malloc]]></c> module for more + <p>Refer to the Reference Manual, the <c>erl_malloc</c> module for more information.</p> </section> <section> <title>Pattern Matching</title> <p>An Erlang pattern is a term that may contain unbound variables or - <c><![CDATA["do not care"]]></c> symbols. Such a pattern can be matched against a + <c>"do not care"</c> symbols. Such a pattern can be matched against a term and, if the match is successful, any unbound variables in the pattern will be bound as a side effect. The content of a bound variable can then be retrieved.</p> @@ -219,13 +219,13 @@ erl_eterm_release(); ETERM *pattern; pattern = erl_format("{madonna,Age,_}"); ]]></code> - <p><c><![CDATA[erl_match()]]></c> is used to perform pattern matching. It takes a + <p><c>erl_match()</c> is used to perform pattern matching. It takes a pattern and a term and tries to match them. As a side effect any unbound variables in the pattern will be bound. In the following example, we create a pattern with a variable <em>Age</em> which appears at two positions in the tuple. The pattern match is performed as follows:</p> <list type="ordered"> - <item><c><![CDATA[erl_match()]]></c> will bind the contents of + <item><c>erl_match()</c> will bind the contents of <em>Age</em> to <em>21</em> the first time it reaches the variable</item> <item>the second occurrence of <em>Age</em> will cause a test for equality between the terms since <em>Age</em> is already bound to @@ -248,14 +248,14 @@ if (erl_match(pattern, term)) { } erl_free_term(pattern); erl_free_term(term); ]]></code> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_match()]]></c> function for + <p>Refer to the Reference Manual, the <c>erl_match()</c> function for more information.</p> </section> <section> <title>Connecting to a Distributed Erlang Node</title> <p>In order to connect to a distributed Erlang node you need to first - initialize the connection routine with <c><![CDATA[erl_connect_init()]]></c>, + initialize the connection routine with <c>erl_connect_init()</c>, which stores information such as the host name, node name, and IP address for later use:</p> <code type="none"><![CDATA[ @@ -263,9 +263,9 @@ int identification_number = 99; int creation=1; char *cookie="a secret cookie string"; /* An example */ erl_connect_init(identification_number, cookie, creation); ]]></code> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_connect]]></c> module for more information.</p> + <p>Refer to the Reference Manual, the <c>erl_connect</c> module for more information.</p> <p>After initialization, you set up the connection to the Erlang node. - Use <c><![CDATA[erl_connect()]]></c> to specify the Erlang node you want to + Use <c>erl_connect()</c> to specify the Erlang node you want to connect to. The following example sets up the connection and should result in a valid socket file descriptor:</p> <code type="none"><![CDATA[ @@ -273,45 +273,45 @@ int sockfd; char *nodename="[email protected]"; /* An example */ if ((sockfd = erl_connect(nodename)) < 0) erl_err_quit("ERROR: erl_connect failed"); ]]></code> - <p><c><![CDATA[erl_err_quit()]]></c> prints the specified string and terminates - the program. Refer to the Reference Manual, the <c><![CDATA[erl_error()]]></c> + <p><c>erl_err_quit()</c> prints the specified string and terminates + the program. Refer to the Reference Manual, the <c>erl_error()</c> function for more information.</p> </section> <section> <title>Using EPMD</title> - <p><c><![CDATA[Epmd]]></c> is the Erlang Port Mapper Daemon. Distributed Erlang nodes - register with <c><![CDATA[epmd]]></c> on the localhost to indicate to other nodes that - they exist and can accept connections. <c><![CDATA[Epmd]]></c> maintains a register of + <p><c>Epmd</c> is the Erlang Port Mapper Daemon. Distributed Erlang nodes + register with <c>epmd</c> on the localhost to indicate to other nodes that + they exist and can accept connections. <c>Epmd</c> maintains a register of node and port number information, and when a node wishes to connect to - another node, it first contacts <c><![CDATA[epmd]]></c> in order to find out the correct + another node, it first contacts <c>epmd</c> in order to find out the correct port number to connect to.</p> - <p>When you use <c><![CDATA[erl_connect()]]></c> to connect to an Erlang node, a - connection is first made to <c><![CDATA[epmd]]></c> and, if the node is known, a + <p>When you use <c>erl_connect()</c> to connect to an Erlang node, a + connection is first made to <c>epmd</c> and, if the node is known, a connection is then made to the Erlang node.</p> - <p>C nodes can also register themselves with <c><![CDATA[epmd]]></c> if they want other + <p>C nodes can also register themselves with <c>epmd</c> if they want other nodes in the system to be able to find and connect to them.</p> - <p>Before registering with <c><![CDATA[epmd]]></c>, you need to first create a listen socket + <p>Before registering with <c>epmd</c>, you need to first create a listen socket and bind it to a port. Then:</p> <code type="none"><![CDATA[ int pub; pub = erl_publish(port); ]]></code> - <p><c><![CDATA[pub]]></c> is a file descriptor now connected to <c><![CDATA[epmd]]></c>. <c><![CDATA[Epmd]]></c> + <p><c>pub</c> is a file descriptor now connected to <c>epmd</c>. <c>Epmd</c> monitors the other end of the connection, and if it detects that the connection has been closed, the node will be unregistered. So, if you explicitly close the descriptor or if your node fails, it will be - unregistered from <c><![CDATA[epmd]]></c>.</p> + unregistered from <c>epmd</c>.</p> <p>Be aware that on some systems (such as VxWorks), a failed node will not be detected by this mechanism since the operating system does not automatically close descriptors that were left open when the node - failed. If a node has failed in this way, <c><![CDATA[epmd]]></c> will prevent you from + failed. If a node has failed in this way, <c>epmd</c> will prevent you from registering a new node with the old name, since it thinks that the old name is still in use. In this case, you must unregister the name explicitly:</p> <code type="none"><![CDATA[ erl_unpublish(node); ]]></code> - <p>This will cause <c><![CDATA[epmd]]></c> to close the connection from the far end. Note + <p>This will cause <c>epmd</c> to close the connection from the far end. Note that if the name was in fact still in use by a node, the results of this operation are unpredictable. Also, doing this does not cause the local end of the connection to close, so resources may be consumed.</p> @@ -321,8 +321,8 @@ erl_unpublish(node); ]]></code> <title>Sending and Receiving Erlang Messages</title> <p>Use one of the following two functions to send messages:</p> <list type="bulleted"> - <item><c><![CDATA[erl_send()]]></c></item> - <item><c><![CDATA[erl_reg_send()]]></c></item> + <item><c>erl_send()</c></item> + <item><c>erl_reg_send()</c></item> </list> <p>As in Erlang, it is possible to send messages to a <em>Pid</em> or to a registered name. It is easier to send a @@ -330,17 +330,17 @@ erl_unpublish(node); ]]></code> a suitable <em>Pid</em>.</p> <p>Use one of the following two functions to receive messages:</p> <list type="bulleted"> - <item><c><![CDATA[erl_receive()]]></c></item> - <item><c><![CDATA[erl_receive_msg()]]></c></item> + <item><c>erl_receive()</c></item> + <item><c>erl_receive_msg()</c></item> </list> - <p><c><![CDATA[erl_receive()]]></c> receives the message into a buffer, while - <c><![CDATA[erl_receive_msg()]]></c> decodes the message into an Erlang term. </p> + <p><c>erl_receive()</c> receives the message into a buffer, while + <c>erl_receive_msg()</c> decodes the message into an Erlang term. </p> <section> <title>Example of Sending Messages</title> - <p>In the following example, <c><![CDATA[{Pid, hello_world}]]></c> is - sent to a registered process <c><![CDATA[my_server]]></c>. The message is encoded - by <c><![CDATA[erl_send()]]></c>:</p> + <p>In the following example, <c>{Pid, hello_world}</c> is + sent to a registered process <c>my_server</c>. The message is encoded + by <c>erl_send()</c>:</p> <code type="none"><![CDATA[ extern const char *erl_thisnodename(void); extern short erl_thiscreation(void); @@ -355,15 +355,15 @@ emsg = erl_mk_tuple(arr, 2); erl_reg_send(sockfd, "my_server", emsg); erl_free_term(emsg); ]]></code> <p>The first element of the tuple that is sent is your own - <em>Pid</em>. This enables <c><![CDATA[my_server]]></c> to reply. Refer to the - Reference Manual, the <c><![CDATA[erl_connect]]></c> module for more information + <em>Pid</em>. This enables <c>my_server</c> to reply. Refer to the + Reference Manual, the <c>erl_connect</c> module for more information about send primitives.</p> </section> <section> <title>Example of Receiving Messages</title> - <p>In this example <c><![CDATA[{Pid, Something}]]></c> is received. The - received Pid is then used to return <c><![CDATA[{goodbye,Pid}]]></c></p> + <p>In this example <c>{Pid, Something}</c> is received. The + received Pid is then used to return <c>{goodbye,Pid}</c></p> <code type="none"><![CDATA[ ETERM *arr[2], *answer; int sockfd,rc; @@ -383,18 +383,18 @@ if ((rc = erl_receive_msg(sockfd , buf, BUFSIZE, &emsg)) == ERL_MSG) { <p>In order to provide robustness, a distributed Erlang node occasionally polls all its connected neighbours in an attempt to detect failed nodes or communication links. A node which receives such - a message is expected to respond immediately with an <c><![CDATA[ERL_TICK]]></c> message. - This is done automatically by <c><![CDATA[erl_receive()]]></c>, however when this - has occurred <c><![CDATA[erl_receive]]></c> returns <c><![CDATA[ERL_TICK]]></c> to the caller - without storing a message into the <c><![CDATA[ErlMessage]]></c> structure.</p> + a message is expected to respond immediately with an <c>ERL_TICK</c> message. + This is done automatically by <c>erl_receive()</c>, however when this + has occurred <c>erl_receive</c> returns <c>ERL_TICK</c> to the caller + without storing a message into the <c>ErlMessage</c> structure.</p> <p>When a message has been received, it is the caller's responsibility - to free the received message <c><![CDATA[emsg.msg]]></c> as well as <c><![CDATA[emsg.to]]></c> - or <c><![CDATA[emsg.from]]></c>, depending on the type of message received.</p> + to free the received message <c>emsg.msg</c> as well as <c>emsg.to</c> + or <c>emsg.from</c>, depending on the type of message received.</p> <p>Refer to the Reference Manual for additional information about the following modules:</p> <list type="bulleted"> - <item><c><![CDATA[erl_connect]]></c></item> - <item><c><![CDATA[erl_eterm]]></c>.</item> + <item><c>erl_connect</c></item> + <item><c>erl_eterm</c>.</item> </list> </section> </section> @@ -421,12 +421,12 @@ if (!erl_match(ep, reply)) "); erl_free_term(ep); erl_free_term(reply); ]]></code> - <p><c><![CDATA[c:c/1]]></c> is called to compile the specified module on the - remote node. <c><![CDATA[erl_match()]]></c> checks that the compilation was - successful by testing for the expected <c><![CDATA[ok]]></c>.</p> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_connect]]></c> module for - more information about <c><![CDATA[erl_rpc()]]></c>, and its companions - <c><![CDATA[erl_rpc_to()]]></c> and <c><![CDATA[erl_rpc_from()]]></c>.</p> + <p><c>c:c/1</c> is called to compile the specified module on the + remote node. <c>erl_match()</c> checks that the compilation was + successful by testing for the expected <c>ok</c>.</p> + <p>Refer to the Reference Manual, the <c>erl_connect</c> module for + more information about <c>erl_rpc()</c>, and its companions + <c>erl_rpc_to()</c> and <c>erl_rpc_from()</c>.</p> </section> <section> @@ -454,14 +454,14 @@ if (names) ",names[i]); free(names); ]]></code> - <p><c><![CDATA[erl_global_names()]]></c> allocates and returns a buffer containing - all the names known to global. <c><![CDATA[count]]></c> will be initialized to + <p><c>erl_global_names()</c> allocates and returns a buffer containing + all the names known to global. <c>count</c> will be initialized to indicate how many names are in the array. The array of strings in names is terminated by a NULL pointer, so it is not necessary to use - <c><![CDATA[count]]></c> to determine when the last name is reached.</p> + <c>count</c> to determine when the last name is reached.</p> <p>It is the caller's responsibility to free the array. - <c><![CDATA[erl_global_names()]]></c> allocates the array and all of the strings - using a single call to <c><![CDATA[malloc()]]></c>, so <c><![CDATA[free(names)]]></c> is all + <c>erl_global_names()</c> allocates the array and all of the strings + using a single call to <c>malloc()</c>, so <c>free(names)</c> is all that is necessary.</p> <p>To look up one of the names:</p> <code type="none"><![CDATA[ @@ -469,13 +469,13 @@ ETERM *pid; char node[256]; pid = erl_global_whereis(fd,"schedule",node); ]]></code> - <p>If <c><![CDATA["schedule"]]></c> is known to global, an Erlang pid is returned + <p>If <c>"schedule"</c> is known to global, an Erlang pid is returned that can be used to send messages to the schedule service. - Additionally, <c><![CDATA[node]]></c> will be initialized to contain the name of + Additionally, <c>node</c> will be initialized to contain the name of the node where the service is registered, so that you can make a - connection to it by simply passing the variable to <c><![CDATA[erl_connect()]]></c>.</p> + connection to it by simply passing the variable to <c>erl_connect()</c>.</p> <p>Before registering a name, you should already have registered your - port number with <c><![CDATA[epmd]]></c>. This is not strictly necessary, but if you + port number with <c>epmd</c>. This is not strictly necessary, but if you neglect to do so, then other nodes wishing to communicate with your service will be unable to find or connect to your process.</p> <p>Create a pid that Erlang processes can use to communicate with your @@ -485,9 +485,9 @@ ETERM *pid; pid = erl_mk_pid(thisnode,14,0,0); erl_global_register(fd,servicename,pid); ]]></code> - <p>After registering the name, you should use <c><![CDATA[erl_accept()]]></c> to wait for + <p>After registering the name, you should use <c>erl_accept()</c> to wait for incoming connections.</p> - <p>Do not forget to free <c><![CDATA[pid]]></c> later with <c><![CDATA[erl_free_term()]]></c>!</p> + <p>Do not forget to free <c>pid</c> later with <c>erl_free_term()</c>!</p> <p>To unregister a name:</p> <code type="none"><![CDATA[ erl_global_unregister(fd,servicename); ]]></code> @@ -500,7 +500,7 @@ erl_global_unregister(fd,servicename); ]]></code> restoring them from a Mnesia table on an Erlang node. More detailed information about the individual API functions can be found in the Reference Manual.</p> - <p>Keys are strings, i.e. 0-terminated arrays of characters, and values + <p>Keys are strings, i.e. <c>NULL</c>-terminated arrays of characters, and values are arbitrary objects. Although integers and floating point numbers are treated specially by the registry, you can store strings or binary objects of any type as pointers.</p> @@ -570,12 +570,12 @@ ei_reg_close(reg); ]]></code> <title>Backing Up the Registry to Mnesia</title> <p>The contents of a registry can be backed up to Mnesia on a "nearby" Erlang node. You need to provide an open connection to the Erlang node - (see <c><![CDATA[erl_connect()]]></c>). Also, Mnesia 3.0 or later must be running + (see <c>erl_connect()</c>). Also, Mnesia 3.0 or later must be running on the Erlang node before the backup is initiated:</p> <code type="none"><![CDATA[ ei_reg_dump(fd, reg, "mtab", dumpflags); ]]></code> <p>The example above will backup the contents of the registry to the - specified Mnesia table <c><![CDATA["mtab"]]></c>. Once a registry has been backed + specified Mnesia table <c>"mtab"</c>. Once a registry has been backed up to Mnesia in this manner, additional backups will only affect objects that have been modified since the most recent backup, i.e. objects that have been created, changed or deleted. The backup @@ -584,7 +584,7 @@ ei_reg_dump(fd, reg, "mtab", dumpflags); ]]></code> <p>In the same manner, a registry can be restored from a Mnesia table:</p> <code type="none"><![CDATA[ ei_reg_restore(fd, reg, "mtab"); ]]></code> - <p>This will read the entire contents of <c><![CDATA["mtab"]]></c> into the specified + <p>This will read the entire contents of <c>"mtab"</c> into the specified registry. After the restore, all of the objects in the registry will be marked as unmodified, so a subsequent backup will only affect objects that you have modified since the restore.</p> @@ -600,8 +600,8 @@ ei_reg_restore(fd, reg, "mtab"); ]]></code> <p>When string or binary objects are stored in the registry it is important that a number of simple guidelines are followed. </p> <p>Most importantly, the object must have been created with a single call - to <c><![CDATA[malloc()]]></c> (or similar), so that it can later be removed by a - single call to <c><![CDATA[free()]]></c>. Objects will be freed by the registry + to <c>malloc()</c> (or similar), so that it can later be removed by a + single call to <c>free()</c>. Objects will be freed by the registry when it is closed, or when you assign a new value to an object that previously contained a string or binary.</p> <p>You should also be aware that if you store binary objects that are @@ -618,9 +618,8 @@ ei_reg_restore(fd, reg, "mtab"); ]]></code> you make, possibly causing it to be missed the next time you make a Mnesia backup of the registry contents. This can be avoided if you mark the object as dirty after any such changes with - <c><![CDATA[ei_reg_markdirty()]]></c>, or pass appropriate flags to - <c><![CDATA[ei_reg_dump()]]></c>.</p> + <c>ei_reg_markdirty()</c>, or pass appropriate flags to + <c>ei_reg_dump()</c>.</p> </section> </section> </chapter> - diff --git a/lib/erl_interface/doc/src/erl_malloc.xml b/lib/erl_interface/doc/src/erl_malloc.xml index 799c903b1a..c0eebc29e9 100644 --- a/lib/erl_interface/doc/src/erl_malloc.xml +++ b/lib/erl_interface/doc/src/erl_malloc.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>erl_malloc</title> @@ -28,174 +28,177 @@ <docno></docno> <approved>Bjarne Däcker</approved> <checked>Torbjörn Törnkvist</checked> - <date>980703</date> + <date>1998-07-03</date> <rev>A</rev> - <file>erl_malloc.sgml</file> + <file>erl_malloc.xml</file> </header> <lib>erl_malloc</lib> - <libsummary>Memory Allocation Functions</libsummary> + <libsummary>Memory allocation functions.</libsummary> <description> <p>This module provides functions for allocating and deallocating memory.</p> </description> + <funcs> <func> <name><ret>ETERM *</ret><nametext>erl_alloc_eterm(etype)</nametext></name> - <fsummary>Allocates an ETERM structure</fsummary> + <fsummary>Allocate an ETERM structure.</fsummary> <type> <v>unsigned char etype;</v> </type> <desc> - <p>This function allocates an <c><![CDATA[(ETERM)]]></c> structure. - Specify <c><![CDATA[etype]]></c> as one of the following constants:</p> + <p>Allocates an <c>(ETERM)</c> structure.</p> + <p>Specify <c>etype</c> as one of the following + constants:</p> <list type="bulleted"> - <item> - <p>ERL_INTEGER</p> + <item><c>ERL_INTEGER</c> </item> - <item> - <p>ERL_U_INTEGER <c><![CDATA[/* unsigned integer */]]></c></p> + <item><c>ERL_U_INTEGER</c> (unsigned integer) </item> - <item> - <p>ERL_ATOM</p> + <item><c>ERL_ATOM</c> </item> - <item> - <p>ERL_PID <c><![CDATA[/* Erlang process identifier */]]></c></p> + <item><c>ERL_PID</c> (Erlang process identifier) </item> - <item> - <p>ERL_PORT</p> + <item><c>ERL_PORT</c> </item> - <item> - <p>ERL_REF <c><![CDATA[/* Erlang reference */]]></c></p> + <item><c>ERL_REF</c> (Erlang reference) </item> - <item> - <p>ERL_LIST</p> + <item><c>ERL_LIST</c> </item> - <item> - <p>ERL_EMPTY_LIST</p> + <item><c>ERL_EMPTY_LIST</c> </item> - <item> - <p>ERL_TUPLE</p> + <item><c>ERL_TUPLE</c> </item> - <item> - <p>ERL_BINARY</p> + <item><c>ERL_BINARY</c> </item> - <item> - <p>ERL_FLOAT</p> + <item><c>ERL_FLOAT</c> </item> - <item> - <p>ERL_VARIABLE</p> + <item><c>ERL_VARIABLE</c> </item> - <item> - <p>ERL_SMALL_BIG <c><![CDATA[/* bignum */]]></c></p> + <item><c>ERL_SMALL_BIG</c> (bignum) </item> - <item> - <p>ERL_U_SMALL_BIG <c><![CDATA[/* bignum */]]></c></p> + <item><c>ERL_U_SMALL_BIG</c> (bignum) </item> </list> - <p><c><![CDATA[ERL_SMALL_BIG]]></c> and <c><![CDATA[ERL_U_SMALL_BIG]]></c> are for - creating Erlang <c><![CDATA[bignums]]></c>, which can contain integers of - arbitrary size. The size of an integer in Erlang is machine - dependent, but in general any integer larger than 2^28 - requires a bignum.</p> + <p><c>ERL_SMALL_BIG</c> and + <c>ERL_U_SMALL_BIG</c> are for + creating Erlang <c>bignums</c>, which can contain integers + of any size. The size of an integer in Erlang is machine-dependent, + but any integer > 2^28 requires a bignum.</p> </desc> </func> + <func> <name><ret>void</ret><nametext>erl_eterm_release(void)</nametext></name> - <fsummary>Clears the ETERM freelist</fsummary> + <fsummary>Clear the ETERM freelist.</fsummary> <desc> - <p>Clears the - freelist, where blocks are placed when they are - released by <c><![CDATA[erl_free_term()]]></c> and - <c><![CDATA[erl_free_compound()]]></c>. </p> + <p>Clears the freelist, where blocks are placed when they are + released by <c>erl_free_term()</c> and + <c>erl_free_compound()</c>.</p> </desc> </func> + <func> <name><ret>void</ret><nametext>erl_eterm_statistics(allocated, freed)</nametext></name> - <fsummary>Reports term allocation statistics</fsummary> + <fsummary>Report term allocation statistics.</fsummary> <type> <v>long *allocated;</v> <v>long *freed;</v> </type> <desc> - <p><c><![CDATA[allocated]]></c> and <c><![CDATA[freed]]></c> are initialized to + <p>Reports term allocation statistics.</p> + <p><c>allocated</c> and <c>freed</c> are + initialized to contain information about the fix-allocator used to allocate - ETERM components. <c><![CDATA[allocated]]></c> is the number of blocks - currently allocated to ETERM objects. <c><![CDATA[freed]]></c> is the - length of the freelist, where blocks are placed when they are - released by <c><![CDATA[erl_free_term()]]></c> and - <c><![CDATA[erl_free_compound()]]></c>. </p> + <c>ETERM</c> components.</p> + <list type="bulleted"> + <item> + <p><c>allocated</c> is the number of blocks currently + allocated to <c>ETERM</c> objects.</p> + </item> + <item> + <p><c>freed</c> is the length of the freelist, where + blocks are placed when they are + released by <c>erl_free_term()</c> and + <c>erl_free_compound()</c>.</p> + </item> + </list> </desc> </func> + <func> - <name><ret>void</ret><nametext>erl_free_array(array, size)</nametext></name> - <fsummary>Frees an array of ETERM structures</fsummary> + <name><ret>void</ret><nametext>erl_free(ptr)</nametext></name> + <fsummary>Free some memory.</fsummary> <type> - <v>ETERM **array;</v> - <v>int size;</v> + <v>void *ptr;</v> </type> <desc> - <p>This function frees an array of Erlang terms.</p> - <p><c><![CDATA[array]]></c> is an array of ETERM* objects. - </p> - <p><c><![CDATA[size]]></c> is the number of terms in the array.</p> + <p>Calls the standard + <c>free()</c> function.</p> </desc> </func> + <func> - <name><ret>void</ret><nametext>erl_free_term(t)</nametext></name> - <fsummary>Frees an ETERM structure</fsummary> + <name><ret>void</ret><nametext>erl_free_array(array, size)</nametext></name> + <fsummary>Free an array of ETERM structures.</fsummary> <type> - <v>ETERM *t;</v> + <v>ETERM **array;</v> + <v>int size;</v> </type> <desc> - <p>Use this function to free an Erlang term.</p> + <p>Frees an array of Erlang terms.</p> + <list type="bulleted"> + <item><c>array</c> is an array of ETERM* objects.</item> + <item><c>size</c> is the number of terms in the array. + </item> + </list> </desc> </func> + <func> <name><ret>void</ret><nametext>erl_free_compound(t)</nametext></name> - <fsummary>Frees an array of ETERM structures</fsummary> + <fsummary>Free an array of ETERM structures.</fsummary> <type> <v>ETERM *t;</v> </type> <desc> <p>Normally it is the programmer's responsibility to free each Erlang term that has been returned from any of the - <c><![CDATA[erl_interface]]></c> functions. However since many of the + <c>Erl_Interface</c> functions. However, as many of the functions that build new Erlang terms in fact share objects - with other existing terms, it may be difficult for the - programmer to maintain pointers to all such terms in order to - free them individually. - </p> - <p><c><![CDATA[erl_free_compound()]]></c> will recursively free all of the - sub-terms associated with a given Erlang term, regardless of - whether we are still holding pointers to the sub-terms. - </p> - <p>There is an example in the User Manual under "Building - Terms and Patterns" - </p> + with other existing terms, it can be difficult for the + programmer to maintain pointers to all such terms to + free them individually.</p> + <p><c>erl_free_compound()</c> recursively frees all of the + subterms associated with a specified Erlang term, regardless of + whether we are still holding pointers to the subterms.</p> + <p>For an example, see section + <seealso marker="ei_users_guide#building_terms_and_patterns">Building Terms and Patterns</seealso> + in the User's Guide.</p> </desc> </func> + <func> - <name><ret>void</ret><nametext>erl_malloc(size)</nametext></name> - <fsummary>Allocates some memory</fsummary> + <name><ret>void</ret><nametext>erl_free_term(t)</nametext></name> + <fsummary>Free an ETERM structure.</fsummary> <type> - <v>long size;</v> + <v>ETERM *t;</v> </type> <desc> - <p>This function calls the standard - <c><![CDATA[malloc()]]></c> function. </p> + <p>Frees an Erlang term.</p> </desc> </func> + <func> - <name><ret>void</ret><nametext>erl_free(ptr)</nametext></name> - <fsummary>Frees some memory</fsummary> + <name><ret>void</ret><nametext>erl_malloc(size)</nametext></name> + <fsummary>Allocate some memory.</fsummary> <type> - <v>void *ptr;</v> + <v>long size;</v> </type> <desc> - <p>This function calls the standard - <c><![CDATA[free()]]></c> function. </p> + <p>Calls the standard + <c>malloc()</c> function.</p> </desc> </func> </funcs> </cref> - diff --git a/lib/erl_interface/doc/src/erl_marshal.xml b/lib/erl_interface/doc/src/erl_marshal.xml index 7c56089016..2ad658f78b 100644 --- a/lib/erl_interface/doc/src/erl_marshal.xml +++ b/lib/erl_interface/doc/src/erl_marshal.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>erl_marshal</title> @@ -28,246 +28,241 @@ <docno></docno> <approved>Bjarne Däcker</approved> <checked>Torbjörn Törnkvist</checked> - <date>980703</date> + <date>1998-07-03</date> <rev>A</rev> - <file>erl_marshal.sgml</file> + <file>erl_marshal.xml</file> </header> <lib>erl_marshal</lib> - <libsummary>Encoding and Decoding of Erlang terms</libsummary> + <libsummary>Encoding and decoding of Erlang terms.</libsummary> <description> <p>This module contains functions for encoding Erlang terms into a sequence of bytes, and for decoding Erlang terms from a sequence of bytes.</p> </description> + <funcs> <func> <name><ret>int</ret><nametext>erl_compare_ext(bufp1, bufp2)</nametext></name> - <fsummary>Compares encoded byte sequences</fsummary> + <fsummary>Compare encoded byte sequences.</fsummary> <type> <v>unsigned char *bufp1,*bufp2;</v> </type> <desc> - <p>This function compares two encoded terms. - </p> - <p><c><![CDATA[bufp1]]></c> is a buffer containing an encoded Erlang - term term1. - </p> - <p><c><![CDATA[bufp2]]></c> is a buffer containing an encoded Erlang - term term2. - </p> - <p>The function returns 0 if the terms are equal, -1 if term1 - is less than term2, or 1 if term2 is less than term1. - </p> + <p>Compares two encoded terms.</p> + <list type="bulleted"> + <item><c>bufp1</c> is a buffer containing an encoded + Erlang term term1.</item> + <item><c>bufp2</c> is a buffer containing an encoded + Erlang term term2.</item> + </list> + <p>Returns <c>0</c> if the terms are equal, <c>-1</c> if + <c>term1</c> < <c>term2</c>, or <c>1</c> if <c>term2</c> < + <c>term1</c>.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_decode(bufp)</nametext></name> <name><ret>ETERM *</ret><nametext>erl_decode_buf(bufpp)</nametext></name> - <fsummary>Converts a term from Erlang external format</fsummary> + <fsummary>Convert a term from Erlang external format.</fsummary> <type> <v>unsigned char *bufp;</v> <v>unsigned char **bufpp;</v> </type> <desc> - <p><c><![CDATA[erl_decode()]]></c> and <c><![CDATA[erl_decode_buf()]]></c> decode + <p><c>erl_decode()</c> and + <c>erl_decode_buf()</c> decode the contents of a buffer and return the corresponding - Erlang term. <c><![CDATA[erl_decode_buf()]]></c> provides a simple + Erlang term. <c>erl_decode_buf()</c> provides a simple mechanism for dealing with several encoded terms stored consecutively in the buffer.</p> - <p><c><![CDATA[bufp]]></c> is a pointer to a buffer containing one or - more encoded Erlang terms. - </p> - <p><c><![CDATA[bufpp]]></c> is the address of a buffer pointer. The buffer - contains one or more consecutively encoded Erlang terms. - Following a successful call to <c><![CDATA[erl_decode_buf()]]></c>, - <c><![CDATA[bufpp]]></c> will be updated so that it points to the next - encoded term. - </p> - <p><c><![CDATA[erl_decode()]]></c> returns an Erlang term - corresponding to the contents of <c><![CDATA[bufp]]></c> on success, or - NULL on failure. <c><![CDATA[erl_decode_buf()]]></c> returns an Erlang + <list type="bulleted"> + <item> + <p><c>bufp</c> is a pointer to a buffer containing one + or more encoded Erlang terms.</p> + </item> + <item> + <p><c>bufpp</c> is the address of a buffer pointer. The + buffer contains one or more consecutively encoded Erlang terms. + Following a successful call to + <c>erl_decode_buf()</c>, <c>bufpp</c> is + updated so that it points to the next encoded term.</p> + </item> + </list> + <p><c>erl_decode()</c> returns an Erlang term + corresponding to the contents of <c>bufp</c> on success, + otherwise <c>NULL</c>. <c>erl_decode_buf()</c> + returns an Erlang term corresponding to the first of the consecutive terms in - <c><![CDATA[bufpp]]></c> and moves <c><![CDATA[bufpp]]></c> forward to point to the + <c>bufpp</c> and moves <c>bufpp</c> forward + to point to the next term in the buffer. On failure, each of the functions - returns NULL. - </p> + return <c>NULL</c>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_encode(term, bufp)</nametext></name> <name><ret>int</ret><nametext>erl_encode_buf(term, bufpp)</nametext></name> - <fsummary>Converts a term into Erlang external format</fsummary> + <fsummary>Convert a term into Erlang external format.</fsummary> <type> <v>ETERM *term;</v> <v>unsigned char *bufp;</v> <v>unsigned char **bufpp;</v> </type> <desc> - <p><c><![CDATA[erl_encode()]]></c> and <c><![CDATA[erl_encode_buf()]]></c> encode + <p><c>erl_encode()</c> and + <c>erl_encode_buf()</c> encode Erlang terms into external format for storage or transmission. - <c><![CDATA[erl_encode_buf()]]></c> provides a simple mechanism for - encoding several terms consecutively in the same - buffer. - </p> - <p><c>term</c> is an Erlang term to be encoded. - </p> - <p><c>bufp</c> is a pointer to a buffer containing one or - more encoded Erlang terms. - </p> - <p><c>bufpp</c> is a pointer to a pointer to a buffer - containing one or more consecutively encoded Erlang terms. - Following a successful call to <c><![CDATA[erl_encode_buf()]]></c>, - <c>bufpp</c> will be updated so that it points to the - position for the next encoded term. - </p> - <p> - These functions returns the number of bytes written to buffer - if successful, otherwise returns 0. - </p> - <p>Note that no bounds checking is done on the buffer. It is - the caller's responsibility to make sure that the buffer is + <c>erl_encode_buf()</c> provides a simple mechanism for + encoding several terms consecutively in the same buffer.</p> + <list type="bulleted"> + <item> + <p><c>term</c> is an Erlang term to be encoded.</p> + </item> + <item> + <p><c>bufp</c> is a pointer to a buffer containing one or + more encoded Erlang terms.</p> + </item> + <item> + <p><c>bufpp</c> is a pointer to a pointer to a buffer + containing one or more consecutively encoded Erlang terms. + Following a successful call to + <c>erl_encode_buf()</c>, <c>bufpp</c> is updated so + that it points to the + position for the next encoded term.</p> + </item> + </list> + <p>These functions return the number of bytes written to buffer + on success, otherwise <c>0</c>.</p> + <p>Notice that no bounds checking is done on the buffer. It is + the caller's responsibility to ensure that the buffer is large enough to hold the encoded terms. You can either use a - static buffer that is large enough to hold the terms you - expect to need in your program, or use <c><![CDATA[erl_term_len()]]></c> - to determine the exact requirements for a given term. - </p> + static buffer that is large enough to hold the terms you expect + to need in your program, or use <c>erl_term_len()</c> + to determine the exact requirements for a given term.</p> <p>The following can help you estimate the buffer - requirements for a term. Note that this information is - implementation specific, and may change in future versions. - If you are unsure, use <c><![CDATA[erl_term_len()]]></c>. - </p> + requirements for a term. Notice that this information is + implementation-specific, and can change in future versions. + If you are unsure, use <c>erl_term_len()</c>.</p> <p>Erlang terms are encoded with a 1 byte tag that identifies the type of object, a 2- or 4-byte length field, - and then the data itself. Specifically: - </p> + and then the data itself. Specifically:</p> <taglist> - <tag><c><![CDATA[Tuples]]></c></tag> - <item>need 5 bytes, plus the space for each element.</item> - <tag><c><![CDATA[Lists]]></c></tag> - <item>need 5 bytes, plus the space for each element, and 1 - additional byte for the empty list at the end.</item> - <tag><c><![CDATA[Strings and atoms]]></c></tag> - <item>need 3 bytes, plus 1 byte for each character (the - terminating 0 is not encoded). Really long strings (more - than 64k characters) are encoded as lists. Atoms cannot - contain more than 256 characters.</item> - <tag><c><![CDATA[Integers]]></c></tag> - <item>need 5 bytes.</item> - <tag><c><![CDATA[Characters]]></c></tag> - <item>(integers < 256) need 2 bytes.</item> - <tag><c><![CDATA[Floating point numbers]]></c></tag> - <item>need 32 bytes.</item> - <tag><c><![CDATA[Pids]]></c></tag> - <item>need 10 bytes, plus the space for the node name, which - is an atom.</item> - <tag><c><![CDATA[Ports and Refs]]></c></tag> - <item>need 6 bytes, plus the space for the node name, which - is an atom.</item> + <tag><c>Tuples</c></tag> + <item>Need 5 bytes, plus the space for each element.</item> + <tag><c>Lists</c></tag> + <item>Need 5 bytes, plus the space for each element, and 1 + more byte for the empty list at the end.</item> + <tag><c>Strings and atoms</c></tag> + <item>Need 3 bytes, plus 1 byte for each character (the + terminating 0 is not encoded). Really long strings (more + than 64k characters) are encoded as lists. Atoms cannot + contain more than 256 characters.</item> + <tag><c>Integers</c></tag> + <item>Need 5 bytes.</item> + <tag><c>Characters</c></tag> + <item>(Integers < 256) need 2 bytes.</item> + <tag><c>Floating point numbers</c></tag> + <item>Need 32 bytes.</item> + <tag><c>Pids</c></tag> + <item>Need 10 bytes, plus the space for the node name, which + is an atom.</item> + <tag><c>Ports and Refs</c></tag> + <item>Need 6 bytes, plus the space for the node name, which + is an atom.</item> </taglist> - <p>The total space required will be the result calculated - from the information above, plus 1 additional byte for a - version identifier. - </p> + <p>The total space required is the result calculated + from the information above, plus 1 more byte for a + version identifier.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_ext_size(bufp)</nametext></name> - <fsummary>Counts elements in encoded term</fsummary> + <fsummary>Count elements in encoded term.</fsummary> <type> <v>unsigned char *bufp;</v> </type> <desc> - <p>This function returns the number of elements in an - encoded term.</p> + <p>Returns the number of elements in an encoded term.</p> </desc> </func> + <func> <name><ret>unsigned char</ret><nametext>erl_ext_type(bufp)</nametext></name> - <fsummary>Determines type of an encoded byte sequence</fsummary> + <fsummary>Determine type of an encoded byte sequence.</fsummary> <type> <v>unsigned char *bufp;</v> </type> <desc> - <p>This function identifies and returns the type of Erlang term encoded - in a buffer. It will skip a trailing <em>magic</em> identifier. - Returns <c><![CDATA[0]]></c> if the type can't be determined or one of</p> + <p>Identifies and returns the type of Erlang term encoded + in a buffer. It skips a trailing <em>magic</em> identifier.</p> + <p>Returns <c>0</c> if the type cannot be determined or + one of:</p> <list type="bulleted"> - <item> - <p>ERL_INTEGER</p> + <item><c>ERL_INTEGER</c> </item> - <item> - <p>ERL_ATOM</p> + <item><c>ERL_ATOM</c> </item> - <item> - <p>ERL_PID <c><![CDATA[/* Erlang process identifier */]]></c></p> + <item><c>ERL_PID</c> (Erlang process identifier) </item> - <item> - <p>ERL_PORT</p> + <item><c>ERL_PORT</c> </item> - <item> - <p>ERL_REF <c><![CDATA[/* Erlang reference */]]></c></p> + <item><c>ERL_REF</c> (Erlang reference) </item> - <item> - <p>ERL_EMPTY_LIST</p> + <item><c>ERL_EMPTY_LIST</c> </item> - <item> - <p>ERL_LIST</p> + <item><c>ERL_LIST</c> </item> - <item> - <p>ERL_TUPLE</p> + <item><c>ERL_TUPLE</c> </item> - <item> - <p>ERL_FLOAT</p> + <item><c>ERL_FLOAT</c> </item> - <item> - <p>ERL_BINARY</p> + <item><c>ERL_BINARY</c> </item> - <item> - <p>ERL_FUNCTION</p> + <item><c>ERL_FUNCTION</c> </item> </list> </desc> </func> + <func> <name><ret>unsigned char *</ret><nametext>erl_peek_ext(bufp, pos)</nametext></name> - <fsummary>Steps over encoded term</fsummary> + <fsummary>Step over encoded term.</fsummary> <type> <v>unsigned char *bufp;</v> <v>int pos;</v> </type> <desc> <p>This function is used for stepping over one or more - encoded terms in a buffer, in order to directly access a - later term. - </p> - <p><c><![CDATA[bufp]]></c> is a pointer to a buffer containing one or - more encoded Erlang terms. - </p> - <p><c><![CDATA[pos]]></c> indicates how many terms to step over in the - buffer. - </p> - <p>The function returns a pointer to a sub-term that can be - used in a subsequent call to <c><![CDATA[erl_decode()]]></c> in order to retrieve - the term at that position. If there is no term, or <c><![CDATA[pos]]></c> - would exceed the size of the terms in the buffer, NULL is returned. - </p> + encoded terms in a buffer, to directly access later term.</p> + <list type="bulleted"> + <item><c>bufp</c> is a pointer to a buffer containing one + or more encoded Erlang terms.</item> + <item><c>pos</c> indicates how many terms to step over in + the buffer.</item> + </list> + <p>Returns a pointer to a subterm that can be + used in a later call to <c>erl_decode()</c> to retrieve + the term at that position. If there is no term, or + <c>pos</c> would exceed the size of the terms in the + buffer, <c>NULL</c> is returned.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_term_len(t)</nametext></name> - <fsummary>Determines encoded size of term</fsummary> + <fsummary>Determine encoded size of term.</fsummary> <type> <v>ETERM *t;</v> </type> <desc> - <p>This function determines the buffer space that would be - needed by <c><![CDATA[t]]></c> if it were encoded into Erlang external - format by <c><![CDATA[erl_encode()]]></c>. - </p> - <p>The size in bytes is returned. - </p> + <p>Determines the buffer space that would be + needed by <c>t</c> if it were encoded into Erlang external + format by <c>erl_encode()</c>.</p> + <p>Returns the size in bytes.</p> </desc> </func> </funcs> </cref> - diff --git a/lib/erl_interface/doc/src/fascicules.xml b/lib/erl_interface/doc/src/fascicules.xml deleted file mode 100644 index f7edd8a973..0000000000 --- a/lib/erl_interface/doc/src/fascicules.xml +++ /dev/null @@ -1,24 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> - -<fascicules> - <fascicule file="part_ei" href="part_ei_frame.html" entry="no"> - EI User's Guide - </fascicule> - <fascicule file="ref_man_ei" href="ref_man_ei_frame.html" entry="yes"> - EI Library Reference - </fascicule> - <fascicule file="ref_man_erl_interface" href="ref_man_erl_interface_frame.html" entry="no"> - Erl_interface Library Reference - </fascicule> - <fascicule file="ref_man" href="ref_man_frame.html" entry="no"> - Command Reference - </fascicule> - <fascicule file="part_notes" href="part_notes_frame.html" entry="no"> - Release Notes - </fascicule> - <fascicule file="" href="../../../../doc/print.html" entry="no"> - Off-Print - </fascicule> -</fascicules> - diff --git a/lib/erl_interface/doc/src/part.xml b/lib/erl_interface/doc/src/part.xml index d044e2b981..3b761df221 100644 --- a/lib/erl_interface/doc/src/part.xml +++ b/lib/erl_interface/doc/src/part.xml @@ -22,7 +22,7 @@ </legalnotice> - <title>EI User's Guide</title> + <title>Erl_Interface User's Guide</title> <prepared>Gordon Beaton</prepared> <docno></docno> <date>1998-11-30</date> diff --git a/lib/erl_interface/doc/src/part_erl_interface.xml b/lib/erl_interface/doc/src/part_erl_interface.xml index 2abe7ecd60..e256cfa193 100644 --- a/lib/erl_interface/doc/src/part_erl_interface.xml +++ b/lib/erl_interface/doc/src/part_erl_interface.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>Erl_Interface User's Guide</title> @@ -31,4 +31,3 @@ </header> <xi:include href="erl_interface.xml"/> </part> - diff --git a/lib/erl_interface/doc/src/ref_man.xml b/lib/erl_interface/doc/src/ref_man.xml index 0cf060829b..1e20637cb7 100644 --- a/lib/erl_interface/doc/src/ref_man.xml +++ b/lib/erl_interface/doc/src/ref_man.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,9 +19,9 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> - <title>Erl_Interface Command Reference</title> + <title>Erl_Interface Reference Manual</title> <prepared>Gordon Beaton</prepared> <docno></docno> <date>1998-11.30</date> @@ -29,17 +29,6 @@ <file>ref_man.xml</file> </header> <description> - <p>The <c>ei</c> and <c>erl_interface</c> are <c>C</c> interface libraries for - communication with <c>Erlang</c>.</p> - <note> - <p>By default, the <c>ei</c> and <c>erl_interface</c> libraries are only guaranteed - to be compatible with other Erlang/OTP components from the same - release as the libraries themself. See the documentation of the - <seealso marker="ei#ei_set_compat_rel">ei_set_compat_rel()</seealso> and - <seealso marker="erl_eterm#erl_set_compat_rel">erl_set_compat_rel()</seealso> - functions on how to communicate with Erlang/OTP components from earlier - releases.</p> - </note> </description> <xi:include href="ei.xml"/> <xi:include href="ei_connect.xml"/> @@ -53,4 +42,3 @@ <xi:include href="erl_marshal.xml"/> <xi:include href="erl_call.xml"/> </application> - diff --git a/lib/erl_interface/doc/src/ref_man_ei.xml b/lib/erl_interface/doc/src/ref_man_ei.xml index d24828c394..92ff9ed328 100644 --- a/lib/erl_interface/doc/src/ref_man_ei.xml +++ b/lib/erl_interface/doc/src/ref_man_ei.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>EI Library Reference</title> @@ -30,12 +30,12 @@ <file>ref_man_ei.xml</file> </header> <description> - <p>The <c><![CDATA[ei]]></c> library is a <c><![CDATA[C]]></c> interface library for - communication with <c><![CDATA[Erlang]]></c>.</p> + <p>The <c>ei</c> library is a <c>C</c> interface library for + communication with <c>Erlang</c>.</p> <note> - <p>By default, the <c><![CDATA[ei]]></c> library is only guaranteed + <p>By default, the <c>ei</c> library is only guaranteed to be compatible with other Erlang/OTP components from the same - release as the <c><![CDATA[ei]]></c> library itself. See the documentation of the + release as the <c>ei</c> library itself. See the documentation of the <seealso marker="ei#ei_set_compat_rel">ei_set_compat_rel()</seealso> function on how to communicate with Erlang/OTP components from earlier releases.</p> @@ -45,4 +45,3 @@ <xi:include href="ei_connect.xml"/> <xi:include href="registry.xml"/> </application> - diff --git a/lib/erl_interface/doc/src/ref_man_erl_interface.xml b/lib/erl_interface/doc/src/ref_man_erl_interface.xml index fb39c5a7e4..4b1d0e9981 100644 --- a/lib/erl_interface/doc/src/ref_man_erl_interface.xml +++ b/lib/erl_interface/doc/src/ref_man_erl_interface.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>Erl_Interface Library Reference</title> @@ -50,4 +50,3 @@ <xi:include href="erl_malloc.xml"/> <xi:include href="erl_marshal.xml"/> </application> - diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml index 285a2402b8..6d70fb3475 100644 --- a/lib/erl_interface/doc/src/registry.xml +++ b/lib/erl_interface/doc/src/registry.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>registry</title> @@ -28,457 +28,585 @@ <docno></docno> <approved>Gordon Beaton</approved> <checked>Gordon Beaton</checked> - <date>980707</date> + <date>1998-07-07</date> <rev>A</rev> - <file>registry.sgml</file> + <file>registry.xml</file> </header> <lib>registry</lib> - <libsummary>Store and backup key-value pairs</libsummary> + <libsummary>Store and back up key-value pairs.</libsummary> <description> <p>This module provides support for storing key-value pairs in a table known as a registry, backing up registries to - Mnesia in an atomic manner, and later restoring the contents of a - registry from Mnesia.</p> + <seealso marker="mnesia:mnesia">Mnesia</seealso> + in an atomic manner, and later restoring the contents of a + registry from <c>Mnesia</c>.</p> </description> + <funcs> <func> - <name><ret>ei_reg *</ret><nametext>ei_reg_open(size)</nametext></name> - <fsummary>Create and open a registry</fsummary> + <name><ret>int</ret><nametext>ei_reg_close(reg)</nametext></name> + <fsummary>Close a registry.</fsummary> <type> - <v>int size;</v> + <v>ei_reg *reg;</v> </type> <desc> - <p>Open (create) a registry. The registry will be - initially empty. Use <c><![CDATA[ei_reg_close()]]></c> to close the registry - later. - </p> - <p><c><![CDATA[size]]></c> is the approximate number of objects you intend - to store in the registry. Since the registry uses a hash table - with collision chaining, there is no absolute upper limit on the - number of objects that can be stored in it. However for reasons - of efficiency, it is a good idea to choose a number that is - appropriate for your needs. It is possible to use - <c><![CDATA[ei_reg_resize()]]></c> to change the size later. Note that the - number you provide will be increased to the nearest larger prime - number. - </p> - <p>On success, an empty registry will be returned. On failure, NULL - will be returned.</p> + <p>A registry that has previously been created with + <c>ei_reg_open()</c> is closed, and all the objects it + contains are freed.</p> + <p><c>reg</c> is the registry to close.</p> + <p>Returns <c>0</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_resize(reg,newsize)</nametext></name> - <fsummary>Resize a registry</fsummary> + <name><ret>int</ret><nametext>ei_reg_delete(reg,key)</nametext></name> + <fsummary>Delete an object from the registry.</fsummary> <type> <v>ei_reg *reg;</v> - <v>int newsize;</v> + <v>const char *key;</v> </type> <desc> - <p>Change the size of a registry. - </p> - <p><c><![CDATA[newsize]]></c> is the new size to make the registry. The - number will be increased to the nearest larger prime number. - </p> - <p>On success, the registry will be resized, all contents - rehashed, and the function will return 0. On failure, the - registry will be left unchanged and the function will return -1.</p> + <p>Deletes an object from the registry. The object is not + removed from the registry, it is only marked for later + removal so that on later backups to <c>Mnesia</c>, the + corresponding object can be removed from the <c>Mnesia</c> table as + well. If another object is later created with the same key, the + object will be reused. </p> + <p>The object is removed from the registry after a call to + <c>ei_reg_dump()</c> or <c>ei_reg_purge()</c>. + </p> + <list type="bulleted"> + <item><c>reg</c> is the registry containing + <c>key</c>.</item> + <item><c>key</c> is the object to remove.</item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_close(reg)</nametext></name> - <fsummary>Close a registry </fsummary> + <name><ret>int</ret><nametext>ei_reg_dump(fd,reg,mntab,flags)</nametext></name> + <fsummary>Back up a registry to Mnesia.</fsummary> <type> + <v>int fd;</v> <v>ei_reg *reg;</v> + <v>const char *mntab;</v> + <v>int flags;</v> </type> <desc> - <p>A registry that has previously been created with - <c><![CDATA[ei_reg_open()]]></c> is closed, and all the objects it contains - are freed. - </p> - <p><c><![CDATA[reg]]></c> is the registry to close. - </p> - <p>The function returns 0.</p> + <p>Dumps the contents of a registry to a <c>Mnesia</c> table in an + atomic manner, that is, either all data or no data is updated. + If any errors are encountered while backing up + the data, the entire operation is aborted.</p> + <list type="bulleted"> + <item><c>fd</c> is an open connection to Erlang. + <c>Mnesia</c> 3.0 or later must be running on the Erlang node. + </item> + <item><c>reg</c> is the registry to back up.</item> + <item><c>mntab</c> is the name of the <c>Mnesia</c> table + where the backed up data is to be placed. If the table does not + exist, it is created automatically using configurable defaults. + For information about configuring this behavior, see + <seealso marker="mnesia:mnesia"><c>Mnesia</c></seealso>.</item> + </list> + <p>If <c>flags</c> is <c>0</c>, the backup includes only + those objects that have been created, modified, or deleted since the + last backup or restore (that is, an incremental backup). After the + backup, any objects that were marked dirty are now clean, and any + objects that had been marked for deletion are deleted.</p> + <p>Alternatively, setting flags to <c>EI_FORCE</c> causes a full + backup to be done, and <c>EI_NOPURGE</c> causes the deleted objects + to be left in the registry afterwards. These can be bitwise OR'ed + together if both behaviors are desired. If <c>EI_NOPURGE</c> was + specified, <c>ei_reg_purge()</c> can be used to + explicitly remove the deleted items from the registry later.</p> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_setival(reg,key,i)</nametext></name> - <fsummary>Assign an integer object</fsummary> + <name><ret>double</ret><nametext>ei_reg_getfval(reg,key)</nametext></name> + <fsummary>Get a floating point object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> - <v>int i;</v> </type> <desc> - <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> and integer - value <c><![CDATA[i]]></c>. If an object already existed with the same - <c><![CDATA[key]]></c>, the new value replaces the old one. If the previous - value was a binary or string, it is freed with <c><![CDATA[free()]]></c>. - </p> - <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. - </p> - <p><c><![CDATA[key]]></c> is the name of the object. - </p> - <p><c><![CDATA[i]]></c> is the integer value to assign. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> + <p>Gets the value associated with <c>key</c> in the + registry. The value must be a floating point type.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object will be + looked up.</item> + <item><c>key</c> is the name of the object to look up. + </item> + </list> + <p>On success, the function returns the value associated with + <c>key</c>. + If the object is not found or if it is not a floating point + object, <c>-1.0</c> is returned. To avoid problems with in-band error + reporting (that is, if you cannot distinguish between <c>-1.0</c> and + a valid result), use the more general function + <c>ei_reg_getval()</c> instead.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_setfval(reg,key,f)</nametext></name> - <fsummary>Assign a floating point object</fsummary> + <name><ret>int</ret><nametext>ei_reg_getival(reg,key)</nametext></name> + <fsummary>Get an integer object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> - <v>double f;</v> </type> <desc> - <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> and - floating point value <c><![CDATA[f]]></c>. If an object already existed with - the same <c><![CDATA[key]]></c>, the new value replaces the old one. If the - previous value was a binary or string, it is freed with <c><![CDATA[free()]]></c>. - </p> - <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. - </p> - <p><c><![CDATA[key]]></c> is the name of the object. - </p> - <p><c><![CDATA[f]]></c> is the floating point value to assign. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> + <p>Gets the value associated with <c>key</c> in the + registry. The value must be an integer.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object will be + looked up.</item> + <item><c>key</c> is the name of the object to look up. + </item> + </list> + <p>On success, the function returns the value associated with + <c>key</c>. + If the object is not found or if it is not an integer + object, <c>-1</c> is returned. To avoid problems with in-band error + reporting (that is, if you cannot distinguish between <c>-1</c> and a + valid result), use the more general function + <c>ei_reg_getval()</c> instead.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_setsval(reg,key,s)</nametext></name> - <fsummary>Assign a string object</fsummary> + <name><ret>const void *</ret><nametext>ei_reg_getpval(reg,key,size)</nametext></name> + <fsummary>Get a binary object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> - <v>const char *s;</v> + <v>int size;</v> </type> <desc> - <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> whose - "value" is the specified string <c><![CDATA[s]]></c>. If an object already - existed with the same <c><![CDATA[key]]></c>, the new value replaces the old - one. If the previous value was a binary or string, it is freed - with <c><![CDATA[free()]]></c>. - </p> - <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. - </p> - <p><c><![CDATA[key]]></c> is the name of the object. - </p> - <p><c><![CDATA[s]]></c> is the string to assign. The string itself - must have been created through a single call to <c><![CDATA[malloc()]]></c> or - similar function, so that the registry can later delete it if - necessary by calling <c><![CDATA[free()]]></c>. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> + <p>Gets the value associated with <c>key</c> in the + registry. The value must be a binary (pointer) type.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object will be + looked up.</item> + <item><c>key</c> is the name of the object to look up. + </item> + <item><c>size</c> is initialized to contain the length in + bytes of the object, if it is found.</item> + </list> + <p>On success, the function returns the value associated with + <c>key</c> and indicates its length in + <c>size</c>. + If the object is not found or if it is not a binary object, + <c>NULL</c> is returned. To avoid problems with in-band error + reporting (that is, if you cannot distinguish between <c>NULL</c> and + a valid result), use the more general function + <c>ei_reg_getval()</c> instead.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_setpval(reg,key,p,size)</nametext></name> - <fsummary>Assign a binary object</fsummary> + <name><ret>const char *</ret><nametext>ei_reg_getsval(reg,key)</nametext></name> + <fsummary>Get a string object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> - <v>const void *p;</v> - <v>int size;</v> </type> <desc> - <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> whose - "value" is the binary object pointed to by <c><![CDATA[p]]></c>. If an - object already existed with the same <c><![CDATA[key]]></c>, the new value - replaces the old one. If the previous value was a binary or - string, it is freed with <c><![CDATA[free()]]></c>. - </p> - <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. - </p> - <p><c><![CDATA[key]]></c> is the name of the object. - </p> - <p><c><![CDATA[p]]></c> is a pointer to the binary object. The object itself - must have been created through a single call to <c><![CDATA[malloc()]]></c> or - similar function, so that the registry can later delete it if - necessary by calling <c><![CDATA[free()]]></c>. - </p> - <p><c><![CDATA[size]]></c> is the length in bytes of the binary object. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> + <p>Gets the value associated with <c>key</c> in the + registry. The value must be a string.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object will be + looked up.</item> + <item><c>key</c> is the name of the object to look up. + </item> + </list> + <p>On success, the function returns the value associated with + <c>key</c>. If the object is not found or if it is not a + string, <c>NULL</c> is returned. To avoid problems with in-band error + reporting (that is, if you cannot distinguish between <c>NULL</c> and + a valid result), use the more general function + <c>ei_reg_getval()</c> instead.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_setval(reg,key,flags,v,...)</nametext></name> - <fsummary>Assign a value to any object type</fsummary> + <name><ret>int</ret><nametext>ei_reg_getval(reg,key,flags,v,...)</nametext></name> + <fsummary>Get any object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> <v>int flags;</v> - <v>v (see below)</v> + <v>void *v (see below)</v> </type> <desc> - <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> whose - value is specified by <c><![CDATA[v]]></c>. If an object already - existed with the same <c><![CDATA[key]]></c>, the new value replaces the old - one. If the previous value was a binary or string, it is freed - with <c><![CDATA[free()]]></c>. - </p> - <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. - </p> - <p><c><![CDATA[key]]></c> is the name of the object. - </p> - <p><c><![CDATA[flags]]></c> indicates the type of the object specified by - <c><![CDATA[v]]></c>. Flags must be one of EI_INT, EI_FLT, EI_STR and - EI_BIN, indicating whether <c><![CDATA[v]]></c> is <c><![CDATA[int]]></c>, <c><![CDATA[double]]></c>, - <c><![CDATA[char*]]></c> or <c><![CDATA[void*]]></c>. If <c><![CDATA[flags]]></c> is EI_BIN, then a - fifth argument <c><![CDATA[size]]></c> is required, indicating the size - in bytes of the object pointed to by <c><![CDATA[v]]></c>. - </p> - <p>If you wish to store an arbitrary pointer in the registry, - specify a <c><![CDATA[size]]></c> of 0. In this case, the object itself will - not be transferred by an <c><![CDATA[ei_reg_dump()]]></c> operation, just - the pointer value. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> + <p>A general function for retrieving any kind of + object from the registry.</p> + <list type="bulleted"> + <item> + <p><c>reg</c> is the registry where the object will be + looked up.</p> + </item> + <item> + <p><c>key</c> is the name of the object to look up.</p> + </item> + <item> + <p><c>flags</c> indicates the type of object that you + are looking for. If <c>flags</c> is <c>0</c>, any + kind of object is returned. + If <c>flags</c> is <c>EI_INT</c>, <c>EI_FLT</c>, + <c>EI_STR</c>, or <c>EI_BIN</c>, then only values of + that kind are returned.</p> + <p>The buffer pointed to by <c>v</c> + must be large enough to hold the return data, that is, it must be + a pointer to one of <c>int</c>, + <c>double</c>, <c>char*</c>, or + <c>void*</c>, respectively.</p> + <p>If <c>flags</c> is <c>EI_BIN</c>, a fifth argument + <c>int *size</c> is required, so that the size of the + object can be returned.</p> + </item> + </list> + <p>On success, <c>v</c> (and <c>size</c> if the + object is binary) is initialized with the value associated + with <c>key</c>, and the function returns <c>EI_INT</c>, + <c>EI_FLT</c>, <c>EI_STR</c>, or <c>EI_BIN</c>, indicating the type + of object. On failure, <c>-1</c> is returned and the + arguments are not updated.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_getival(reg,key)</nametext></name> - <fsummary>Get an integer object</fsummary> + <name><ret>int</ret><nametext>ei_reg_markdirty(reg,key)</nametext></name> + <fsummary>Mark an object as dirty.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> </type> <desc> - <p>Get the value associated with <c><![CDATA[key]]></c> in the - registry. The value must be an integer. - </p> - <p><c><![CDATA[reg]]></c> is the registry where the object will be looked - up. - </p> - <p><c><![CDATA[key]]></c> is the name of the object to look up. - </p> - <p>On success, the function returns the value associated with <c><![CDATA[key]]></c>. - If the object was not found or it was not an integer - object, -1 is returned. To avoid problems with in-band error - reporting (i.e. if you cannot distinguish between -1 and a - valid result) use the more general function <c><![CDATA[ei_reg_getval()]]></c> - instead.</p> + <p>Marks a registry object as dirty. This ensures that + it is included in the next backup to <c>Mnesia</c>. Normally this + operation is not necessary, as all of the normal registry + 'set' functions do this automatically. However, if you have + retrieved the value of a string or binary object from the + registry and modified the contents, then the change is + invisible to the registry and the object is assumed to be + unmodified. This function allows you to make such modifications + and then let the registry know about them.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry containing the object. + </item> + <item><c>key</c> is the name of the object to mark. + </item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>double</ret><nametext>ei_reg_getfval(reg,key)</nametext></name> - <fsummary>Get a floating point object</fsummary> + <name><ret>ei_reg *</ret><nametext>ei_reg_open(size)</nametext></name> + <fsummary>Create and open a registry.</fsummary> + <type> + <v>int size;</v> + </type> + <desc> + <p>Opens (creates) a registry, which initially is empty. To + close the registry later, use <c>ei_reg_close()</c>.</p> + <p><c>size</c> is the approximate number of objects you + intend to store in the registry. As the registry uses a hash table + with collision chaining, no absolute upper limit exists on the + number of objects that can be stored in it. However, for reasons + of efficiency, it is a good idea to choose a number that is + appropriate for your needs. To change the size later, use + <c>ei_reg_resize()</c>. Notice that the number + you provide is increased to the nearest larger prime number.</p> + <p>Returns an empty registry on success, otherwise <c>NULL</c>.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_reg_purge(reg)</nametext></name> + <fsummary>Remove deleted objects.</fsummary> <type> <v>ei_reg *reg;</v> - <v>const char *key;</v> </type> <desc> - <p>Get the value associated with <c><![CDATA[key]]></c> in the - registry. The value must be a floating point type. - </p> - <p><c><![CDATA[reg]]></c> is the registry where the object will be looked - up. - </p> - <p><c><![CDATA[key]]></c> is the name of the object to look up. - </p> - <p>On success, the function returns the value associated with <c><![CDATA[key]]></c>. - If the object was not found or it was not a floating point - object, -1.0 is returned. To avoid problems with in-band error - reporting (i.e. if you cannot distinguish between -1.0 and a - valid result) use the more general function <c><![CDATA[ei_reg_getval()]]></c> - instead.</p> + <p>Removes all objects marked for deletion. When objects + are deleted with <c>ei_reg_delete()</c> they are not + removed from the registry, only marked for later removal. + On a later backup to <c>Mnesia</c>, the + objects can also be removed from the <c>Mnesia</c> table. If you are + not backing up to <c>Mnesia</c>, you may wish to remove the objects + manually with this function.</p> + <p><c>reg</c> is a registry containing objects marked for + deletion.</p> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>const char *</ret><nametext>ei_reg_getsval(reg,key)</nametext></name> - <fsummary>Get a string object</fsummary> + <name><ret>int</ret><nametext>ei_reg_resize(reg,newsize)</nametext></name> + <fsummary>Resize a registry.</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>int newsize;</v> + </type> + <desc> + <p>Changes the size of a registry.</p> + <p><c>newsize</c> is the new size to make the registry. The + number is increased to the nearest larger prime number.</p> + <p>On success, the registry is resized, all contents + rehashed, and <c>0</c> is returned. On failure, the + registry is left unchanged and <c>-1</c> is returned.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_reg_restore(fd,reg,mntab)</nametext></name> + <fsummary>Restore a registry from Mnesia.</fsummary> + <type> + <v>int fd;</v> + <v>ei_reg *reg;</v> + <v>const char *mntab;</v> + </type> + <desc> + <p>The contents of a <c>Mnesia</c> table are read into the registry.</p> + <list type="bulleted"> + <item><c>fd</c> is an open connection to Erlang. + <c>Mnesia</c> 3.0 or later must be running on the Erlang node. + </item> + <item><c>reg</c> is the registry where the data is to be + placed.</item> + <item><c>mntab</c> is the name of the <c>Mnesia</c> table + to read data from.</item> + </list> + <p>Notice that only tables of a certain format can be + restored, that is, those that have been created and backed up to + with <c>ei_reg_dump()</c>. If the registry was not empty + before the operation, the contents of the table are added to the + contents of the registry. If the table contains objects with the + same keys as those already in the registry, the registry objects + are overwritten with the new values. If the registry + contains objects that were not in the table, they are + unchanged by this operation.</p> + <p>After the restore operation, the entire contents of the + registry is marked as unmodified. Notice that this includes any + objects that were modified before the restore and not + overwritten by the restore.</p> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> + </desc> + </func> + + <func> + <name><ret>int</ret><nametext>ei_reg_setfval(reg,key,f)</nametext></name> + <fsummary>Assign a floating point object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> + <v>double f;</v> </type> <desc> - <p>Get the value associated with <c><![CDATA[key]]></c> in the - registry. The value must be a string. - </p> - <p><c><![CDATA[reg]]></c> is the registry where the object will be looked - up. - </p> - <p><c><![CDATA[key]]></c> is the name of the object to look up. - </p> - <p>On success, the function returns the value associated with - <c><![CDATA[key]]></c>. If the object was not found or it was not a string, - NULL is returned. To avoid problems with in-band error - reporting (i.e. if you cannot distinguish between NULL and a - valid result) use the more general function <c><![CDATA[ei_reg_getval()]]></c> - instead.</p> + <p>Creates a key-value pair with the specified <c>key</c> + and floating point value <c>f</c>. If an object already + exists with the same <c>key</c>, the new value replaces + the old one. If the previous value was a binary or string, it is + freed with <c>free()</c>.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object is to be + placed.</item> + <item><c>key</c> is the object name.</item> + <item><c>f</c> is the floating point value to assign. + </item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>const void *</ret><nametext>ei_reg_getpval(reg,key,size)</nametext></name> - <fsummary>Get a binary object</fsummary> + <name><ret>int</ret><nametext>ei_reg_setival(reg,key,i)</nametext></name> + <fsummary>Assign an integer object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> - <v>int size;</v> + <v>int i;</v> </type> <desc> - <p>Get the value associated with <c><![CDATA[key]]></c> in the - registry. The value must be a binary (pointer) type. - </p> - <p><c><![CDATA[reg]]></c> is the registry where the object will be looked - up. - </p> - <p><c><![CDATA[key]]></c> is the name of the object to look up. - </p> - <p><c><![CDATA[size]]></c> will be initialized to contain the length in - bytes of the object, if it is found. - </p> - <p>On success, the function returns the value associated with - <c><![CDATA[key]]></c> and indicates its length in <c><![CDATA[size]]></c>. - If the object was not found or it was not a binary object, - NULL is returned. To avoid problems with in-band error - reporting (i.e. if you cannot distinguish between NULL and a - valid result) use the more general function <c><![CDATA[ei_reg_getval()]]></c> - instead.</p> + <p>Creates a key-value pair with the specified <c>key</c> + and integer value <c>i</c>. If an object already exists + with the same <c>key</c>, the new value replaces the old + one. If the previous value was a binary or string, it is freed with + <c>free()</c>.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object is to be + placed.</item> + <item><c>key</c> is the object name.</item> + <item><c>i</c> is the integer value to assign.</item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_getval(reg,key,flags,v,...)</nametext></name> - <fsummary>Get any object</fsummary> + <name><ret>int</ret><nametext>ei_reg_setpval(reg,key,p,size)</nametext></name> + <fsummary>Assign a binary object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> - <v>int flags;</v> - <v>void *v (see below)</v> + <v>const void *p;</v> + <v>int size;</v> </type> <desc> - <p>This is a general function for retrieving any kind of - object from the registry. - </p> - <p><c><![CDATA[reg]]></c> is the registry where the object will be looked - up. - </p> - <p><c><![CDATA[key]]></c> is the name of the object to look up. - </p> - <p><c><![CDATA[flags]]></c> indicates the type of object that you are - looking for. If <c><![CDATA[flags]]></c> is 0, then any kind of object will - be returned. If <c><![CDATA[flags]]></c> is one of EI_INT, EI_FLT, EI_STR or - EI_BIN, then only values of that kind will be returned. The - buffer pointed to by <c><![CDATA[v]]></c> must be large enough to hold the return - data, i.e. it must be a pointer to one of <c><![CDATA[int]]></c>, - <c><![CDATA[double]]></c>, <c><![CDATA[char*]]></c> or <c><![CDATA[void*]]></c>, respectively. Also, - if <c><![CDATA[flags]]></c> is EI_BIN, then a fifth argument <c><![CDATA[int *size]]></c> is required, so that the size of the object can be - returned. - </p> - <p>If the function succeeds, <c><![CDATA[v]]></c> (and <c><![CDATA[size]]></c> if the - object is binary) will be initialized with the value associated - with <c><![CDATA[key]]></c>, and the function will return one of EI_INT, - EI_FLT, EI_STR or EI_BIN, indicating the type of object. On failure the - function will return -1 and the arguments will not be updated.</p> + <p>Creates a key-value pair with the specified <c>key</c> + whose "value" is the binary object pointed to by <c>p</c>. + If an object already exists with the same <c>key</c>, + the new value replaces the old one. If the previous value was a + binary or string, it is freed with <c>free()</c>.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object is to be + placed.</item> + <item><c>key</c> is the object name.</item> + <item><c>p</c> is a pointer to the binary object. The + object itself must have been created through a single call to + <c>malloc()</c> or a similar function, so that the + registry can later delete it if necessary by calling + <c>free()</c>.</item> + <item><c>size</c> is the length in bytes of the binary + object.</item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_markdirty(reg,key)</nametext></name> - <fsummary>Mark an object as dirty </fsummary> + <name><ret>int</ret><nametext>ei_reg_setsval(reg,key,s)</nametext></name> + <fsummary>Assign a string object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> + <v>const char *s;</v> </type> <desc> - <p>Mark a registry object as dirty. This will ensure that - it is included in the next backup to Mnesia. Normally this - operation will not be necessary since all of the normal registry - 'set' functions do this automatically. However if you have - retrieved the value of a string or binary object from the - registry and modified the contents, then the change will be - invisible to the registry and the object will be assumed to be - unmodified. This function allows you to make such modifications - and then let the registry know about them. - </p> - <p><c><![CDATA[reg]]></c> is the registry containing the object. - </p> - <p><c><![CDATA[key]]></c> is the name of the object to mark. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> + <p>Creates a key-value pair with the specified <c>key</c> + whose "value" is the specified string <c>s</c>. If an + object already exists with the same <c>key</c>, the new + value replaces the old one. If the previous value was a binary or + string, it is freed with <c>free()</c>.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object is to be + placed.</item> + <item><c>key</c> is the object name.</item> + <item><c>s</c> is the string to assign. The string itself + must have been created through a single call to + <c>malloc()</c> or similar a function, + so that the registry can later delete it if + necessary by calling <c>free()</c>.</item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_delete(reg,key)</nametext></name> - <fsummary>Delete an object from the registry</fsummary> + <name><ret>int</ret><nametext>ei_reg_setval(reg,key,flags,v,...)</nametext></name> + <fsummary>Assign a value to any object type.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> + <v>int flags;</v> + <v>v (see below)</v> </type> <desc> - <p>Delete an object from the registry. The object is not - actually removed from the registry, it is only marked for later - removal so that on subsequent backups to Mnesia, the - corresponding object can be removed from the Mnesia table as - well. If another object is later created with the same key, the - object will be reused. - </p> - <p>The object will be removed from the registry after a call to - <c><![CDATA[ei_reg_dump()]]></c> or <c><![CDATA[ei_reg_purge()]]></c>. - </p> - <p><c><![CDATA[reg]]></c> is the registry containing <c><![CDATA[key]]></c>. - </p> - <p><c><![CDATA[key]]></c> is the object to remove. - </p> - <p>If the object was found, the function returns 0 indicating - success. Otherwise the function returns -1.</p> + <p>Creates a key-value pair with the specified <c>key</c> + whose value is specified by <c>v</c>. If an object already + exists with the same <c>key</c>, the new value replaces + the old one. If the previous value was a binary or string, it is freed + with <c>free()</c>.</p> + <list type="bulleted"> + <item> + <p><c>reg</c> is the registry where the object is to be + placed.</p> + </item> + <item> + <p><c>key</c> is the object name.</p> + </item> + <item> + <p><c>flags</c> indicates the type of the object + specified by <c>v</c>. Flags must be one of + <c>EI_INT</c>, <c>EI_FLT</c>, <c>EI_STR</c>, and <c>EI_BIN</c>, + indicating whether + <c>v</c> is <c>int</c>, + <c>double</c>, <c>char*</c>, or + <c>void*</c>.</p> + <p>If <c>flags</c> is <c>EI_BIN</c>, a fifth argument + <c>size</c> is required, indicating the size + in bytes of the object pointed to by <c>v</c>.</p> + </item> + </list> + <p>If you wish to store an arbitrary pointer in the registry, + specify a <c>size</c> of <c>0</c>. In this case, the + object itself is not transferred by an + <c>ei_reg_dump()</c> operation, only the pointer + value.</p> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_reg_stat(reg,key,obuf)</nametext></name> - <fsummary>Get object information</fsummary> + <fsummary>Get object information.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> <v>struct ei_reg_stat *obuf;</v> </type> <desc> - <p>Return information about an object. - </p> - <p><c><![CDATA[reg]]></c> is the registry containing the object. - </p> - <p><c><![CDATA[key]]></c> is the name of the object. - </p> - <p><c><![CDATA[obuf]]></c> is a pointer to an <c><![CDATA[ei_reg_stat]]></c> structure, - defined below: - </p> + <p>Returns information about an object.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry containing the object. + </item> + <item><c>key</c> is the object name.</item> + <item><c>obuf</c> is a pointer to an + <c>ei_reg_stat</c> structure, defined as follows:</item> + </list> <code type="none"><![CDATA[ struct ei_reg_stat { int attr; int size; }; ]]></code> - <p>In <c><![CDATA[attr]]></c> the object's attributes are stored as the logical - OR of its type (one of EI_INT, EI_FLT, EI_BIN and EI_STR), - whether it is marked for deletion (EI_DELET) and whether it has - been modified since the last backup to Mnesia (EI_DIRTY). - </p> - <p>The <c><![CDATA[size]]></c> field indicates the size in bytes required to store - EI_STR (including the terminating 0) and EI_BIN objects, or 0 - for EI_INT and EI_FLT. - </p> - <p>The function returns 0 and initializes <c><![CDATA[obuf]]></c> on - success, or returns -1 on failure.</p> + <p>In <c>attr</c> the attributes of the object are stored + as the logical <em>OR</em> of its type (one of <c>EI_INT</c>, + <c>EI_FLT</c>, <c>EI_BIN</c>, and <c>EI_STR</c>), + whether it is marked for deletion (<c>EI_DELET</c>), and whether it + has been modified since the last backup to <c>Mnesia</c> + (<c>EI_DIRTY</c>).</p> + <p>Field <c>size</c> indicates the size in bytes required + to store <c>EI_STR</c> (including the terminating <c>0</c>) and + <c>EI_BIN</c> objects, or <c>0</c> for <c>EI_INT</c> and + <c>EI_FLT</c>.</p> + <p>Returns <c>0</c> and initializes <c>obuf</c> on success, + otherwise <c>-1</c>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_reg_tabstat(reg,obuf)</nametext></name> - <fsummary>Get registry information</fsummary> + <fsummary>Get registry information.</fsummary> <type> <v>ei_reg *reg;</v> <v>struct ei_reg_tabstat *obuf;</v> </type> <desc> - <p>Return information about a registry. Using information + <p>Returns information about a registry. Using information returned by this function, you can see whether the size of the - registry is suitable for the amount of data it contains. - </p> - <p><c><![CDATA[reg]]></c> is the registry to return information about. - </p> - <p><c><![CDATA[obuf]]></c> is a pointer to an <c><![CDATA[ei_reg_tabstat]]></c> structure, - defined below: - </p> + registry is suitable for the amount of data it contains.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry to return information + about.</item> + <item><c>obuf</c> is a pointer to an + <c>ei_reg_tabstat</c> structure, defined as follows: + </item> + </list> <code type="none"><![CDATA[ struct ei_reg_tabstat { int size; @@ -487,126 +615,23 @@ struct ei_reg_tabstat { int collisions; }; ]]></code> - <p>The <c><![CDATA[size]]></c> field indicates the number of hash positions + <p>Field <c>size</c> indicates the number of hash positions in the registry. This is the number you provided when you created or last resized the registry, rounded up to the nearest - prime. - </p> - <p><c><![CDATA[nelem]]></c> indicates the number of elements stored in the - registry. It includes objects that are deleted but not purged. - </p> - <p><c><![CDATA[npos]]></c> indicates the number of unique positions that are - occupied in the registry. - </p> - <p><c><![CDATA[collisions]]></c> indicates how many elements are sharing - positions in the registry. - </p> - <p>On success, the function returns 0 and <c><![CDATA[obuf]]></c> is - initialized to contain table statistics. On failure, the function - returns -1.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_reg_dump(fd,reg,mntab,flags)</nametext></name> - <fsummary>Back up a registry to Mnesia</fsummary> - <type> - <v>int fd;</v> - <v>ei_reg *reg;</v> - <v>const char *mntab;</v> - <v>int flags;</v> - </type> - <desc> - <p>Dump the contents of a registry to a Mnesia table in an - atomic manner, i.e. either all data will be updated, or none of - it will. If any errors are encountered while backing up - the data, the entire operation is aborted. - </p> - <p><c><![CDATA[fd]]></c> is an open connection to Erlang. - Mnesia 3.0 or later must be running on the Erlang node. - </p> - <p><c><![CDATA[reg]]></c> is the registry to back up. - </p> - <p><c><![CDATA[mntab]]></c> is the name of the Mnesia table where the backed - up data should be placed. If the table does not exist, it will - be created automatically using configurable defaults. See your - Mnesia documentation for information about configuring this - behaviour. - </p> - <p>If <c><![CDATA[flags]]></c> is 0, the backup will include only those - objects which have been created, modified or deleted since the - last backup or restore (i.e. an incremental backup). After the - backup, any objects that were marked dirty are now clean, and any - objects that had been marked for deletion are deleted. - </p> - <p>Alternatively, setting flags to EI_FORCE will cause a full - backup to be done, and EI_NOPURGE will cause the deleted objects - to be left in the registry afterwards. These can be bitwise ORed - together if both behaviours are desired. If EI_NOPURGE was - specified, you can use <c><![CDATA[ei_reg_purge()]]></c> to explicitly remove - the deleted items from the registry later. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_reg_restore(fd,reg,mntab)</nametext></name> - <fsummary>Restore a registry from Mnesia</fsummary> - <type> - <v>int fd;</v> - <v>ei_reg *reg;</v> - <v>const char *mntab;</v> - </type> - <desc> - <p>The contents of a Mnesia table are read into the - registry. - </p> - <p><c><![CDATA[fd]]></c> is an open connection to Erlang. - Mnesia 3.0 or later must be running on the Erlang node. - </p> - <p><c><![CDATA[reg]]></c> is the registry where the data should be placed. - </p> - <p><c><![CDATA[mntab]]></c> is the name of the Mnesia table to read data - from. - </p> - <p>Note that only tables of a certain format can be - restored, i.e. those that have been created and backed up to - with <c><![CDATA[ei_reg_dump()]]></c>. If the registry was not empty before - the operation, then the contents of the table are added to the - contents of the registry. If the table contains objects with the - same keys as those already in the registry, the registry objects - will be overwritten with the new values. If the registry - contains objects that were not in the table, they will be - unchanged by this operation. - </p> - <p>After the restore operation, the entire contents of the - registry is marked as unmodified. Note that this includes any - objects that were modified before the restore and not - overwritten by the restore. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_reg_purge(reg)</nametext></name> - <fsummary>Remove deleted objects</fsummary> - <type> - <v>ei_reg *reg;</v> - </type> - <desc> - <p>Remove all objects marked for deletion. When objects - are deleted with <c><![CDATA[ei_reg_delete()]]></c> they are not actually - removed from the registry, only marked for later removal. This - is so that on a subsequent backup to Mnesia, the - objects can also be removed from the Mnesia table. If you are - not backing up to Mnesia then you may wish to remove the objects - manually with this function. - </p> - <p><c><![CDATA[reg]]></c> is a registry containing objects marked for - deletion. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> + prime number.</p> + <list type="bulleted"> + <item><c>nelem</c> indicates the number of elements stored + in the registry. It includes objects that are deleted but not + purged.</item> + <item><c>npos</c> indicates the number of unique positions + that are occupied in the registry.</item> + <item><c>collisions</c> indicates how many elements are + sharing positions in the registry.</item> + </list> + <p>On success, <c>0</c> is returned and + <c>obuf</c> is initialized to contain table statistics, + otherwise <c>-1</c> is returned.</p> </desc> </func> </funcs> </cref> - diff --git a/lib/erl_interface/src/connect/ei_connect.c b/lib/erl_interface/src/connect/ei_connect.c index 624100ad49..c193fd804a 100644 --- a/lib/erl_interface/src/connect/ei_connect.c +++ b/lib/erl_interface/src/connect/ei_connect.c @@ -423,7 +423,7 @@ int ei_connect_xinit(ei_cnode* ec, const char *thishostname, } #endif /* _REENTRANT */ - ec->creation = creation; + ec->creation = creation & 0x3; /* 2 bits */ if (cookie) { if (strlen(cookie) >= sizeof(ec->ei_connect_cookie)) { @@ -462,7 +462,7 @@ int ei_connect_xinit(ei_cnode* ec, const char *thishostname, strcpy(ec->self.node,thisnodename); ec->self.num = 0; ec->self.serial = 0; - ec->self.creation = creation; + ec->self.creation = creation & 0x3; /* 2 bits */ if ((dbglevel = getenv("EI_TRACELEVEL")) != NULL || (dbglevel = getenv("ERL_DEBUG_DIST")) != NULL) diff --git a/lib/hipe/cerl/erl_types.erl b/lib/hipe/cerl/erl_types.erl index 15f7b793a1..9ef119ba46 100644 --- a/lib/hipe/cerl/erl_types.erl +++ b/lib/hipe/cerl/erl_types.erl @@ -611,9 +611,13 @@ t_decorate_with_opaque(T1, T2, Opaques) -> false -> T1; true -> R = decorate(T1, T, Opaques), - ?debug(case catch t_is_equal(t_unopaque(R), t_unopaque(T1)) of - true -> ok; - false -> + ?debug(case catch + not t_is_equal(t_unopaque(R), t_unopaque(T1)) + orelse + t_is_equal(T1, T) andalso not t_is_equal(T1, R) + of + false -> ok; + _ -> io:format("T1 = ~p,\n", [T1]), io:format("T2 = ~p,\n", [T2]), io:format("O = ~p,\n", [Opaques]), @@ -642,7 +646,6 @@ decorate(?tuple_set(List), ?tuple_set(L), Opaques) -> decorate(?union(List), T, Opaques) when T =/= ?any -> ?union(L) = force_union(T), union_decorate(List, L, Opaques); -decorate(?opaque(_)=T, _, _Opaques) -> T; decorate(T, ?union(L), Opaques) when T =/= ?any -> ?union(List) = force_union(T), union_decorate(List, L, Opaques); @@ -656,7 +659,7 @@ decorate_with_opaque(Type, ?opaque(Set2), Opaques) -> case decoration(set_to_list(Set2), Type, Opaques, [], false) of {[], false} -> Type; {List, All} when List =/= [] -> - NewType = ?opaque(ordsets:from_list(List)), + NewType = sup_opaque(List), case All of true -> NewType; false -> t_sup(NewType, Type) @@ -670,9 +673,10 @@ decoration([#opaque{struct = S} = Opaque|OpaqueTypes], Type, Opaques, case not IsOpaque orelse t_is_none(I) of true -> decoration(OpaqueTypes, Type, Opaques, NewOpaqueTypes0, All); false -> - NewOpaque = Opaque#opaque{struct = decorate(I, S, Opaques)}, + NewI = decorate(I, S, Opaques), + NewOpaque = combine(NewI, [Opaque]), NewAll = All orelse t_is_equal(I, Type), - NewOpaqueTypes = [NewOpaque|NewOpaqueTypes0], + NewOpaqueTypes = NewOpaque ++ NewOpaqueTypes0, decoration(OpaqueTypes, Type, Opaques, NewOpaqueTypes, NewAll) end; decoration([], _Type, _Opaques, NewOpaqueTypes, All) -> @@ -2991,27 +2995,21 @@ inf_collect(_T1, [], _Opaques, OpL) -> OpL. combine(S, T1, T2) -> - #opaque{mod = Mod1, name = Name1, args = Args1} = T1, - #opaque{mod = Mod2, name = Name2, args = Args2} = T2, - Comb1 = comb(Mod1, Name1, Args1, S, T1), - case is_compat_opaque_names({Mod1, Name1, Args1}, {Mod2, Name2, Args2}) of - true -> Comb1; - false -> Comb1 ++ comb(Mod2, Name2, Args2, S, T2) + case is_compat_opaque_names(T1, T2) of + true -> combine(S, [T1]); + false -> combine(S, [T1, T2]) end. -comb(Mod, Name, Args, S, T) -> - case can_combine_opaque_names(Mod, Name, Args, S) of - true -> - ?opaque(Set) = S, - Set; - false -> - [T#opaque{struct = S}] - end. +combine(?opaque(Set), Ts) -> + [comb2(O, T) || O <- Set, T <- Ts]; +combine(S, Ts) -> + [T#opaque{struct = S} || T <- Ts]. -can_combine_opaque_names(Mod1, Name1, Args1, - ?opaque([#opaque{mod = Mod2, name = Name2, args = Args2}])) -> - is_compat_opaque_names({Mod1, Name1, Args1}, {Mod2, Name2, Args2}); -can_combine_opaque_names(_, _, _, _) -> false. +comb2(O, T) -> + case is_compat_opaque_names(O, T) of + true -> O; + false -> T#opaque{struct = ?opaque(set_singleton(O))} + end. %% Combining two lists this way can be very time consuming... %% Note: two parameterized opaque types are not the same if their @@ -3020,32 +3018,27 @@ inf_opaque(Set1, Set2, Opaques) -> List1 = inf_look_up(Set1, Opaques), List2 = inf_look_up(Set2, Opaques), List0 = [combine(Inf, T1, T2) || - {Is1, ModNameArgs1, T1} <- List1, - {Is2, ModNameArgs2, T2} <- List2, - not t_is_none(Inf = inf_opaque_types(Is1, ModNameArgs1, T1, - Is2, ModNameArgs2, T2, - Opaques))], - List = lists:sort(lists:append(List0)), + {Is1, T1} <- List1, + {Is2, T2} <- List2, + not t_is_none(Inf = inf_opaque_types(Is1, T1, Is2, T2, Opaques))], + List = lists:append(List0), sup_opaque(List). %% Optimization: do just one lookup. inf_look_up(Set, Opaques) -> - [{Opaques =:= 'universe' orelse inf_is_opaque_type2(T, Opaques), - {M, N, Args}, T} || - #opaque{mod = M, name = N, args = Args} = T <- set_to_list(Set)]. + [{Opaques =:= 'universe' orelse inf_is_opaque_type2(T, Opaques), T} || + T <- set_to_list(Set)]. inf_is_opaque_type2(T, {match, Opaques}) -> is_opaque_type2(T, Opaques); inf_is_opaque_type2(T, Opaques) -> is_opaque_type2(T, Opaques). -inf_opaque_types(IsOpaque1, ModNameArgs1, T1, - IsOpaque2, ModNameArgs2, T2, Opaques) -> +inf_opaque_types(IsOpaque1, T1, IsOpaque2, T2, Opaques) -> #opaque{struct = S1}=T1, #opaque{struct = S2}=T2, case - Opaques =:= 'universe' orelse - is_compat_opaque_names(ModNameArgs1, ModNameArgs2) + Opaques =:= 'universe' orelse is_compat_opaque_names(T1, T2) of true -> t_inf(S1, S2, Opaques); false -> @@ -3059,10 +3052,15 @@ inf_opaque_types(IsOpaque1, ModNameArgs1, T1, end end. -is_compat_opaque_names(ModNameArgs, ModNameArgs) -> true; -is_compat_opaque_names({Mod,Name,Args1}, {Mod,Name,Args2}) -> - is_compat_args(Args1, Args2); -is_compat_opaque_names(_, _) -> false. +is_compat_opaque_names(Opaque1, Opaque2) -> + #opaque{mod = Mod1, name = Name1, args = Args1} = Opaque1, + #opaque{mod = Mod2, name = Name2, args = Args2} = Opaque2, + case {{Mod1, Name1, Args1}, {Mod2, Name2, Args2}} of + {ModNameArgs, ModNameArgs} -> true; + {{Mod, Name, Args1}, {Mod, Name, Args2}} -> + is_compat_args(Args1, Args2); + _ -> false + end. is_compat_args([A1|Args1], [A2|Args2]) -> is_compat_arg(A1, A2) andalso is_compat_args(Args1, Args2); @@ -3109,6 +3107,10 @@ is_specialization(?tuple_set(List1), ?tuple_set(List2)) -> [sup_tuple_elements(T) || {_Arity, T} <- List2]) catch _:_ -> false end; +is_specialization(?opaque(_) = T1, T2) -> + is_specialization(t_opaque_structure(T1), T2); +is_specialization(T1, ?opaque(_) = T2) -> + is_specialization(T1, t_opaque_structure(T2)); is_specialization(?union(List1)=T1, ?union(List2)=T2) -> case specialization_union2(T1, T2) of {yes, Type1, Type2} -> is_specialization(Type1, Type2); @@ -3124,10 +3126,6 @@ is_specialization(T1, ?union(List)) -> {yes, Type} -> is_specialization(T1, Type); no -> false end; -is_specialization(?opaque(_) = T1, T2) -> - is_specialization(t_opaque_structure(T1), T2); -is_specialization(T1, ?opaque(_) = T2) -> - is_specialization(T1, t_opaque_structure(T2)); is_specialization(?var(_), _) -> exit(error); is_specialization(_, ?var(_)) -> exit(error); is_specialization(?none, _) -> false; @@ -4482,28 +4480,31 @@ t_from_form1(Form, ET, Site, MR, V, C) -> vtab = V, tnames = TypeNames}, L = ?EXPAND_LIMIT, - {T1, L1, C1} = from_form(Form, State, ?EXPAND_DEPTH, L, C), + {T0, L0, C0} = from_form(Form, State, ?EXPAND_DEPTH, L, C), if - L1 =< 0 -> - from_form_loop(Form, State, 1, L, C1); + L0 =< 0 -> + {T1, _, C1} = from_form(Form, State, 1, L, C0), + from_form_loop(Form, State, 2, L, C1, T1); true -> - {T1, C1} + {T0, C0} end. initial_typenames({type, _MTA}=Site) -> [Site]; initial_typenames({spec, _MFA}) -> []; initial_typenames({record, _MRA}) -> []. -from_form_loop(Form, State, D, Limit, C) -> +from_form_loop(Form, State, D, Limit, C, T0) -> {T1, L1, C1} = from_form(Form, State, D, Limit, C), Delta = Limit - L1, if - %% Save some time by assuming next depth will exceed the limit. + L1 =< 0 -> + {T0, C1}; Delta * 8 > Limit -> + %% Save some time by assuming next depth will exceed the limit. {T1, C1}; true -> D1 = D + 1, - from_form_loop(Form, State, D1, Limit, C1) + from_form_loop(Form, State, D1, Limit, C1, T1) end. -spec from_form(parse_form(), diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml index 13471aab2c..705afec022 100644 --- a/lib/inets/doc/src/httpc.xml +++ b/lib/inets/doc/src/httpc.xml @@ -68,7 +68,7 @@ this module:</p> <p><c>boolean() = true | false</c></p> <p><c>string()</c> = list of ASCII characters</p> - <p><c>request_id() = ref()</c></p> + <p><c>request_id() = reference()</c></p> <p><c>profile() = atom()</c></p> <p><c>path() = string()</c> representing a file path or directory path</p> <p><c>ip_address()</c> = See the diff --git a/lib/inets/doc/src/mod_esi.xml b/lib/inets/doc/src/mod_esi.xml index 006fca1bdf..46cc796c8a 100644 --- a/lib/inets/doc/src/mod_esi.xml +++ b/lib/inets/doc/src/mod_esi.xml @@ -67,7 +67,7 @@ <tag><c>{remote_adress, inet:ip_address()} </c></tag> <item><p>The clients ip address.</p></item> - <tag><c>{peer_cert, undefined | no_peercert | DER:binary()</c></tag> + <tag><c>{peer_cert, undefined | no_peercert | DER:binary()}</c></tag> <item> <p>For TLS connections where client certificates are used this will be an ASN.1 DER-encoded X509-certificate as an Erlang binary. diff --git a/lib/inets/src/ftp/ftp.erl b/lib/inets/src/ftp/ftp.erl index 8bad91bf98..6868b75eff 100644 --- a/lib/inets/src/ftp/ftp.erl +++ b/lib/inets/src/ftp/ftp.erl @@ -108,6 +108,7 @@ -define(DBG(F,A), 'n/a'). %%-define(DBG(F,A), io:format(F,A)). +%%-define(DBG(F,A), if is_list(F) -> ct:pal(F,A); is_atom(F)->ct:pal(atom_to_list(F),A) end). %%%========================================================================= %%% API - CLIENT FUNCTIONS @@ -2361,14 +2362,17 @@ send_message({ssl, Socket}, Message) -> activate_ctrl_connection(#state{csock = Socket, ctrl_data = {<<>>, _, _}}) -> activate_connection(Socket); activate_ctrl_connection(#state{csock = Socket}) -> + activate_connection(Socket), %% We have already received at least part of the next control message, %% that has been saved in ctrl_data, process this first. - self() ! {tcp, unwrap_socket(Socket), <<>>}. + self() ! {socket_type(Socket), unwrap_socket(Socket), <<>>}. unwrap_socket({tcp,Socket}) -> Socket; unwrap_socket({ssl,Socket}) -> Socket; unwrap_socket(Socket) -> Socket. +socket_type({tcp,_Socket}) -> tcp; +socket_type({ssl,_Socket}) -> ssl. activate_data_connection(#state{dsock = Socket} = State) -> activate_connection(Socket), diff --git a/lib/inets/src/ftp/ftp_response.erl b/lib/inets/src/ftp/ftp_response.erl index 7533bc4550..d54d97dc91 100644 --- a/lib/inets/src/ftp/ftp_response.erl +++ b/lib/inets/src/ftp/ftp_response.erl @@ -90,19 +90,23 @@ parse_lines(<<C1, C2, C3, ?WHITE_SPACE, Bin/binary>>, Lines, start) -> parse_lines(Bin, [?WHITE_SPACE, C3, C2, C1 | Lines], finish); %% Last line found -parse_lines(<<C1, C2, C3, ?WHITE_SPACE, Rest/binary>>, Lines, {C1, C2, C3}) -> - parse_lines(Rest, [?WHITE_SPACE, C3, C2, C1 | Lines], finish); +parse_lines(<<?CR, ?LF, C1, C2, C3, ?WHITE_SPACE, Rest/binary>>, Lines, {C1, C2, C3}) -> + parse_lines(Rest, [?WHITE_SPACE, C3, C2, C1, ?LF, ?CR | Lines], finish); %% Potential end found wait for more data -parse_lines(<<C1, C2, C3>> = Bin, Lines, {C1, C2, C3}) -> +parse_lines(<<?CR, ?LF, C1, C2, C3>> = Bin, Lines, {C1, C2, C3}) -> {continue, {Bin, Lines, {C1, C2, C3}}}; %% Intermidate line begining with status code -parse_lines(<<C1, C2, C3, Rest/binary>>, Lines, {C1, C2, C3}) -> - parse_lines(Rest, [C3, C2, C1 | Lines], {C1, C2, C3}); +parse_lines(<<?CR, ?LF, C1, C2, C3, Rest/binary>>, Lines, {C1, C2, C3}) -> + parse_lines(Rest, [C3, C2, C1, ?LF, ?CR | Lines], {C1, C2, C3}); %% Potential last line wait for more data -parse_lines(<<C1, C2>> = Data, Lines, {C1, C2, _} = StatusCode) -> +parse_lines(<<?CR, ?LF, C1, C2>> = Data, Lines, {C1, C2, _} = StatusCode) -> {continue, {Data, Lines, StatusCode}}; -parse_lines(<<C1>> = Data, Lines, {C1, _, _} = StatusCode) -> +parse_lines(<<?CR, ?LF, C1>> = Data, Lines, {C1, _, _} = StatusCode) -> + {continue, {Data, Lines, StatusCode}}; +parse_lines(<<?CR, ?LF>> = Data, Lines, {_,_,_} = StatusCode) -> + {continue, {Data, Lines, StatusCode}}; +parse_lines(<<?LF>> = Data, Lines, {_,_,_} = StatusCode) -> {continue, {Data, Lines, StatusCode}}; parse_lines(<<>> = Data, Lines, {_,_,_} = StatusCode) -> {continue, {Data, Lines, StatusCode}}; diff --git a/lib/inets/src/http_client/httpc_handler.erl b/lib/inets/src/http_client/httpc_handler.erl index d1c52dcc78..59cb1299e9 100644 --- a/lib/inets/src/http_client/httpc_handler.erl +++ b/lib/inets/src/http_client/httpc_handler.erl @@ -45,28 +45,30 @@ -record(timers, { - request_timers = [], % [ref()] - queue_timer % ref() + request_timers = [] :: [reference()], + queue_timer :: reference() | 'undefined' }). +-type session_failed() :: {'connect_failed',term()} | {'send_failed',term()}. + -record(state, { - request, % #request{} - session, % #session{} + request :: request() | 'undefined', + session :: session() | session_failed() | 'undefined', status_line, % {Version, StatusCode, ReasonPharse} - headers, % #http_response_h{} - body, % binary() + headers :: http_response_h() | 'undefined', + body :: binary() | 'undefined', mfa, % {Module, Function, Args} - pipeline = queue:new(), % queue:queue() - keep_alive = queue:new(), % queue:queue() + pipeline = queue:new() :: queue:queue(), + keep_alive = queue:new() :: queue:queue(), status, % undefined | new | pipeline | keep_alive | close | {ssl_tunnel, Request} canceled = [], % [RequestId] - max_header_size = nolimit, % nolimit | integer() - max_body_size = nolimit, % nolimit | integer() - options, % #options{} - timers = #timers{}, % #timers{} - profile_name, % atom() - id of httpc_manager process. - once = inactive % inactive | once + max_header_size = nolimit :: nolimit | integer(), + max_body_size = nolimit :: nolimit | integer(), + options :: options(), + timers = #timers{} :: #timers{}, + profile_name :: atom(), % id of httpc_manager process. + once = inactive :: 'inactive' | 'once' }). @@ -113,7 +115,7 @@ send(Request, Pid) -> %%-------------------------------------------------------------------- %% Function: cancel(RequestId, Pid) -> ok -%% RequestId = ref() +%% RequestId = reference() %% Pid = pid() - the pid of the http-request handler process. %% %% Description: Cancels a request. Intended to be called by the httpc @@ -789,47 +791,6 @@ deliver_answer(Request) -> %% Purpose: Convert process state when code is changed %%-------------------------------------------------------------------- -code_change(_, - #state{session = OldSession, - profile_name = ProfileName} = State, - upgrade_from_pre_5_8_1) -> - case OldSession of - {session, - Id, ClientClose, Scheme, Socket, SocketType, QueueLen, Type} -> - NewSession = #session{id = Id, - client_close = ClientClose, - scheme = Scheme, - socket = Socket, - socket_type = SocketType, - queue_length = QueueLen, - type = Type}, - insert_session(NewSession, ProfileName), - {ok, State#state{session = NewSession}}; - _ -> - {ok, State} - end; - -code_change(_, - #state{session = OldSession, - profile_name = ProfileName} = State, - downgrade_to_pre_5_8_1) -> - case OldSession of - #session{id = Id, - client_close = ClientClose, - scheme = Scheme, - socket = Socket, - socket_type = SocketType, - queue_length = QueueLen, - type = Type} -> - NewSession = {session, - Id, ClientClose, Scheme, Socket, SocketType, - QueueLen, Type}, - insert_session(NewSession, ProfileName), - {ok, State#state{session = NewSession}}; - _ -> - {ok, State} - end; - code_change(_, State, _) -> {ok, State}. @@ -934,8 +895,7 @@ connect_and_send_first_request(Address, Request, #state{options = Options} = Sta TmpState = State#state{request = Request, session = Session, mfa = init_mfa(Request, State), - status_line = - init_status_line(Request), + status_line = init_status_line(Request), headers = undefined, body = undefined, status = new}, @@ -947,8 +907,7 @@ connect_and_send_first_request(Address, Request, #state{options = Options} = Sta self() ! {init_error, error_sending, httpc_response:error(Request, Reason)}, {ok, State#state{request = Request, - session = - #session{socket = Socket}}} + session = #session{socket = Socket}}} end; {error, Reason} -> self() ! {init_error, error_connecting, @@ -1796,7 +1755,7 @@ tls_tunnel_request(#request{headers = Headers, URI = Host ++":" ++ integer_to_list(Port), #request{ - id = make_ref(), + id = make_ref(), from = self(), scheme = http, %% Use tcp-first and then upgrade! address = Adress, @@ -1887,10 +1846,13 @@ update_session(ProfileName, #session{id = SessionId} = Session, Pos, Value) -> httpc_manager:update_session(ProfileName, SessionId, Pos, Value) end catch - error:undef -> % This could happen during code upgrade + error:undef -> %% This could happen during code upgrade Session2 = erlang:setelement(Pos, Session, Value), insert_session(Session2, ProfileName); - T:E -> + error:badarg -> + exit(normal); %% Manager has been shutdown + T:E -> + %% Unexpected this must be an error! Stacktrace = erlang:get_stacktrace(), error_logger:error_msg("Failed updating session: " "~n ProfileName: ~p" @@ -1922,8 +1884,8 @@ update_session(ProfileName, #session{id = SessionId} = Session, Pos, Value) -> %% --------------------------------------------------------------------- call(Msg, Pid) -> - Timeout = infinity, - call(Msg, Pid, Timeout). + call(Msg, Pid, infinity). + call(Msg, Pid, Timeout) -> gen_server:call(Pid, Msg, Timeout). diff --git a/lib/inets/src/http_client/httpc_internal.hrl b/lib/inets/src/http_client/httpc_internal.hrl index f4e69cc1fa..5f8c70f28d 100644 --- a/lib/inets/src/http_client/httpc_internal.hrl +++ b/lib/inets/src/http_client/httpc_internal.hrl @@ -43,32 +43,32 @@ %%% HTTP Client per request settings -record(http_options, { - %% string() - "HTTP/1.1" | "HTTP/1.0" | "HTTP/0.9" - version, + %% "HTTP/1.1" | "HTTP/1.0" | "HTTP/0.9" + version :: 'undefined' | string(), - %% integer() | infinity - ms before a request times out - timeout = ?HTTP_REQUEST_TIMEOUT, + %% ms before a request times out + timeout = ?HTTP_REQUEST_TIMEOUT :: timeout(), - %% bool() - true if auto redirect on 30x response - autoredirect = true, + %% true if auto redirect on 30x response + autoredirect = true :: boolean(), %% ssl socket options - ssl = [], + ssl = [], %% {User, Password} = {string(), string()} proxy_auth, - %% bool() - true if not strictly std compliant - relaxed = false, + %% true if not strictly std compliant + relaxed = false :: boolean(), %% integer() - ms before a connect times out - connect_timeout = ?HTTP_REQUEST_CTIMEOUT, - - %% bool() - Use %-encoding rfc 2396 - url_encode + connect_timeout = ?HTTP_REQUEST_CTIMEOUT :: timeout(), + %% Use %-encoding rfc 2396 + url_encode :: 'undefined' | boolean() } ). +-type http_options() :: #http_options{}. %%% HTTP Client per profile setting. -record(options, @@ -82,18 +82,19 @@ keep_alive_timeout = ?HTTP_KEEP_ALIVE_TIMEOUT, % Used when pipeline_timeout = 0 max_sessions = ?HTTP_MAX_TCP_SESSIONS, cookies = disabled, % enabled | disabled | verify - verbose = false, + verbose = false, % boolean(), ipfamily = inet, % inet | inet6 | inet6fb4 ip = default, % specify local interface port = default, % specify local port socket_opts = [] % other socket options } ). +-type options() :: #options{}. %%% All data associated to a specific HTTP request -record(request, { - id, % ref() - Request Id + id :: 'undefined' | reference(), % Request Id from, % pid() - Caller redircount = 0,% Number of redirects made for this request scheme, % http | https @@ -103,7 +104,7 @@ method, % atom() - HTTP request Method headers, % #http_request_h{} content, % {ContentType, Body} - Current HTTP request - settings, % #http_options{} - User defined settings + settings :: http_options(), % User defined settings abs_uri, % string() ex: "http://www.erlang.org" userinfo, % string() - optinal "<userinfo>@<host>:<port>" stream, % boolean() - stream async reply? @@ -112,20 +113,19 @@ % for testing purposes. started, % integer() > 0 - When we started processing the % request - timer, % undefined | ref() + timer :: undefined | reference(), socket_opts, % undefined | [socket_option()] ipv6_host_with_brackets % boolean() } - ). - + ). +-type request() :: #request{}. -record(session, { %% {{Host, Port}, HandlerPid} id, - %% true | false - client_close, + client_close :: 'undefined' | boolean(), %% http (HTTP/TCP) | https (HTTP/SSL/TCP) scheme, @@ -140,14 +140,13 @@ queue_length = 1, %% pipeline | keep_alive (wait for response before sending new request) - type, + type :: 'undefined' | 'pipeline' | 'keep_alive', - %% true | false %% This will be true, when a response has been received for %% the first request. See type above. - available = false + available = false :: boolean() }). - +-type session() :: #session{}. -record(http_cookie, { @@ -162,7 +161,7 @@ secure = false, version = "0" }). - +-type http_cookie() :: #http_cookie{}. %% -record(parsed_uri, %% { diff --git a/lib/inets/src/http_client/httpc_manager.erl b/lib/inets/src/http_client/httpc_manager.erl index 4cb6f005ad..a63864493f 100644 --- a/lib/inets/src/http_client/httpc_manager.erl +++ b/lib/inets/src/http_client/httpc_manager.erl @@ -137,7 +137,7 @@ redirect_request(Request, ProfileName) -> %%-------------------------------------------------------------------- %% Function: cancel_request(RequestId, ProfileName) -> ok -%% RequestId - ref() +%% RequestId - reference() %% ProfileName = atom() %% %% Description: Cancels the request with <RequestId>. @@ -148,7 +148,7 @@ cancel_request(RequestId, ProfileName) -> %%-------------------------------------------------------------------- %% Function: request_done(RequestId, ProfileName) -> ok -%% RequestId - ref() +%% RequestId - reference() %% ProfileName = atom() %% %% Description: Inform tha manager that a request has been completed. diff --git a/lib/inets/src/http_lib/http_internal.hrl b/lib/inets/src/http_lib/http_internal.hrl index ae92b5df8f..991417cb36 100644 --- a/lib/inets/src/http_lib/http_internal.hrl +++ b/lib/inets/src/http_lib/http_internal.hrl @@ -71,7 +71,7 @@ 'last-modified', other=[] % list() - Key/Value list with other headers }). - +-type http_response_h() :: #http_response_h{}. %%% Request headers -record(http_request_h,{ @@ -118,5 +118,6 @@ 'last-modified', other=[] % list() - Key/Value list with other headers }). +-type http_request_h() :: #http_request_h{}. -endif. % -ifdef(http_internal_hrl). diff --git a/lib/inets/src/http_server/httpd_request_handler.erl b/lib/inets/src/http_server/httpd_request_handler.erl index 071fa94ef6..7e20a9ba67 100644 --- a/lib/inets/src/http_server/httpd_request_handler.erl +++ b/lib/inets/src/http_server/httpd_request_handler.erl @@ -37,18 +37,19 @@ -include("httpd_internal.hrl"). -define(HANDSHAKE_TIMEOUT, 5000). + -record(state, {mod, %% #mod{} manager, %% pid() status, %% accept | busy | blocked mfa, %% {Module, Function, Args} max_keep_alive_request = infinity, %% integer() | infinity - response_sent = false, %% true | false - timeout, %% infinity | integer() > 0 - timer, %% ref() - Request timer - headers, %% #http_request_h{} + response_sent = false :: boolean(), + timeout, %% infinity | integer() > 0 + timer :: 'undefined' | reference(), % Request timer + headers, %% #http_request_h{} body, %% binary() data, %% The total data received in bits, checked after 10s - byte_limit %% Bit limit per second before kick out + byte_limit %% Bit limit per second before kick out }). %%==================================================================== diff --git a/lib/inets/test/ftp_format_SUITE.erl b/lib/inets/test/ftp_format_SUITE.erl index a33b31f46f..95d594a44b 100644 --- a/lib/inets/test/ftp_format_SUITE.erl +++ b/lib/inets/test/ftp_format_SUITE.erl @@ -38,8 +38,8 @@ all() -> groups() -> [{ftp_response, [], [ftp_150, ftp_200, ftp_220, ftp_226, ftp_257, ftp_331, - ftp_425, ftp_other_status_codes, ftp_multiple_lines, - ftp_multipel_ctrl_messages]}]. + ftp_425, ftp_other_status_codes, ftp_multiple_lines_status_in_msg, + ftp_multiple_lines, ftp_multipel_ctrl_messages]}]. init_per_suite(Config) -> Config. @@ -141,6 +141,15 @@ ftp_425(Config) when is_list(Config) -> {trans_neg_compl, _} = ftp_response:interpret(Msg), ok. +ftp_multiple_lines_status_in_msg() -> + [{doc, "check that multiple lines gets parsed correct, even if we have " + " the status code within the msg being sent"}]. +ftp_multiple_lines_status_in_msg(Config) when is_list(Config) -> + ML = "230-User usr-230 is logged in\r\n" ++ + "230 OK. Current directory is /\r\n", + {ok, ML, <<>>} = ftp_response:parse_lines(list_to_binary(ML), [], start), + ok. + ftp_multiple_lines() -> [{doc, "Especially check multiple lines devided in significant places"}]. ftp_multiple_lines(Config) when is_list(Config) -> diff --git a/lib/mnesia/src/mnesia_controller.erl b/lib/mnesia/src/mnesia_controller.erl index 4791e2e290..17b47c059e 100644 --- a/lib/mnesia/src/mnesia_controller.erl +++ b/lib/mnesia/src/mnesia_controller.erl @@ -1703,9 +1703,10 @@ add_active_replica(Tab, Node, Cs = #cstruct{}) -> block_table(Tab) -> Var = {Tab, where_to_commit}, - Old = val(Var), - New = {blocked, Old}, - set(Var, New). % where_to_commit + case is_tab_blocked(val(Var)) of + {true, _} -> ok; + {false, W2C} -> set(Var, mark_blocked_tab(true, W2C)) + end. unblock_table(Tab) -> call({unblock_table, Tab}). diff --git a/lib/mnesia/src/mnesia_loader.erl b/lib/mnesia/src/mnesia_loader.erl index 71e5829c87..c710470a2c 100644 --- a/lib/mnesia/src/mnesia_loader.erl +++ b/lib/mnesia/src/mnesia_loader.erl @@ -342,9 +342,12 @@ spawned_receiver(ReplyTo,Tab,Storage,Cs, SenderPid,TabSize,DetsData, Init) -> Done = do_init_table(Tab,Storage,Cs, SenderPid,TabSize,DetsData, ReplyTo, Init), - ReplyTo ! {self(),Done}, - unlink(ReplyTo), - unlink(whereis(mnesia_controller)), + try + ReplyTo ! {self(),Done}, + unlink(ReplyTo), + unlink(whereis(mnesia_controller)) + catch _:_ -> ok %% avoid error reports when stopping down mnesia + end, exit(normal). wait_on_load_complete(Pid) -> @@ -916,9 +919,15 @@ send_packet(_N, _Pid, _Chunk, DataState) -> finish_copy(Pid, Tab, Storage, RemoteS, NeedLock) -> RecNode = node(Pid), DatBin = dat2bin(Tab, Storage, RemoteS), + Node = node(Pid), Trans = fun() -> NeedLock andalso mnesia:read_lock_table(Tab), + %% Check that receiver is still alive + receive {copier_done, Node} -> + throw(receiver_died) + after 0 -> ok + end, A = val({Tab, access_mode}), mnesia_controller:sync_and_block_table_whereabouts(Tab, RecNode, RemoteS, A), cleanup_tab_copier(Pid, Storage, Tab), @@ -927,7 +936,7 @@ finish_copy(Pid, Tab, Storage, RemoteS, NeedLock) -> receive {Pid, no_more} -> % Dont bother about the spurious 'more' message no_more; - {copier_done, Node} when Node == node(Pid)-> + {copier_done, Node} -> verbose("Tab receiver ~p crashed (more): ~p~n", [Tab, Node]), receiver_died end diff --git a/lib/mnesia/src/mnesia_tm.erl b/lib/mnesia/src/mnesia_tm.erl index b116b48312..388b42cf15 100644 --- a/lib/mnesia/src/mnesia_tm.erl +++ b/lib/mnesia/src/mnesia_tm.erl @@ -950,7 +950,7 @@ return_abort(Fun, Args, Reason) -> if Level == 1 -> mnesia_locker:async_release_tid(Nodes, Tid), - ?MODULE ! {delete_transaction, Tid}, + ?SAFE(?MODULE ! {delete_transaction, Tid}), erase(mnesia_activity_state), flush_downs(), ?SAFE(unlink(whereis(?MODULE))), diff --git a/lib/ssh/doc/src/notes.xml b/lib/ssh/doc/src/notes.xml index a4897668e4..f5a67bc00e 100644 --- a/lib/ssh/doc/src/notes.xml +++ b/lib/ssh/doc/src/notes.xml @@ -30,6 +30,54 @@ <file>notes.xml</file> </header> +<section><title>Ssh 4.3.6</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Re-negotiation problems with OpenSSH client solved.</p> + <p> + Own Id: OTP-13972</p> + </item> + </list> + </section> + +</section> + +<section><title>Ssh 4.3.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + If a client illegaly sends an info-line and then + immediatly closes the TCP-connection, a badmatch + exception was raised.</p> + <p> + Own Id: OTP-13966</p> + </item> + </list> + </section> + +</section> + +<section><title>Ssh 4.3.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Intermittent ssh ERROR REPORT mentioning + nonblocking_sender</p> + <p> + Own Id: OTP-13953 Aux Id: seq13199 </p> + </item> + </list> + </section> + +</section> + <section><title>Ssh 4.3.3</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/ssh/src/ssh_connection_handler.erl b/lib/ssh/src/ssh_connection_handler.erl index facf6b561a..dd414894d4 100644 --- a/lib/ssh/src/ssh_connection_handler.erl +++ b/lib/ssh/src/ssh_connection_handler.erl @@ -339,7 +339,6 @@ renegotiate_data(ConnectionHandler) -> ssh_params :: #ssh{} | undefined, socket :: inet:socket(), - sender :: pid() | undefined, decrypted_data_buffer = <<>> :: binary(), encrypted_data_buffer = <<>> :: binary(), undecrypted_packet_length :: undefined | non_neg_integer(), @@ -368,10 +367,9 @@ init_connection_handler(Role, Socket, Opts) -> {Protocol, Callback, CloseTag} = proplists:get_value(transport, Opts, ?DefaultTransport), S0#data{ssh_params = init_ssh_record(Role, Socket, Opts), - sender = spawn_link(fun() -> nonblocking_sender(Socket, Callback) end), - transport_protocol = Protocol, - transport_cb = Callback, - transport_close_tag = CloseTag + transport_protocol = Protocol, + transport_cb = Callback, + transport_close_tag = CloseTag } of S -> @@ -547,6 +545,7 @@ handle_event(_, {info_line,_Line}, {hello,Role}, D) -> case Role of client -> %% The server may send info lines to the client before the version_exchange + %% RFC4253/4.2 inet:setopts(D#data.socket, [{active, once}]), keep_state_and_data; server -> @@ -672,8 +671,9 @@ handle_event(_, #ssh_msg_newkeys{} = Msg, {new_keys,Role,init}, D) -> {next_state, {service_request,Role}, D#data{ssh_params=Ssh}}; %% Subsequent key exchange rounds (renegotiation): -handle_event(_, #ssh_msg_newkeys{}, {new_keys,Role,renegotiate}, D) -> - {next_state, {connected,Role}, D}; +handle_event(_, #ssh_msg_newkeys{} = Msg, {new_keys,Role,renegotiate}, D) -> + {ok, Ssh} = ssh_transport:handle_new_keys(Msg, D#data.ssh_params), + {next_state, {connected,Role}, D#data{ssh_params=Ssh}}; %%% ######## {service_request, client|server} @@ -1447,15 +1447,18 @@ start_the_connection_child(UserPid, Role, Socket, Options) -> %% Stopping -type finalize_termination_result() :: ok . -finalize_termination(_StateName, D) -> - case D#data.connection_state of +finalize_termination(_StateName, #data{transport_cb = Transport, + connection_state = Connection, + socket = Socket}) -> + case Connection of #connection{system_supervisor = SysSup, sub_system_supervisor = SubSysSup} when is_pid(SubSysSup) -> ssh_system_sup:stop_subsystem(SysSup, SubSysSup); _ -> do_nothing end, - close_transport(D). + (catch Transport:close(Socket)), + ok. %%-------------------------------------------------------------------- %% "Invert" the Role @@ -1510,34 +1513,10 @@ send_msg(Msg, State=#data{ssh_params=Ssh0}) when is_tuple(Msg) -> send_bytes(Bytes, State), State#data{ssh_params=Ssh}. -send_bytes(Bytes, #data{sender = Sender}) -> - Sender ! {send,Bytes}, - ok. - -close_transport(D) -> - D#data.sender ! close, +send_bytes(Bytes, #data{socket = Socket, transport_cb = Transport}) -> + _ = Transport:send(Socket, Bytes), ok. - -nonblocking_sender(Socket, Callback) -> - receive - {send, Bytes} -> - case Callback:send(Socket, Bytes) of - ok -> - nonblocking_sender(Socket, Callback); - E = {error,_} -> - exit({shutdown,E}) - end; - - close -> - case Callback:close(Socket) of - ok -> - ok; - E = {error,_} -> - exit({shutdown,E}) - end - end. - handle_version({2, 0} = NumVsn, StrVsn, Ssh0) -> Ssh = counterpart_versions(NumVsn, StrVsn, Ssh0), {ok, Ssh}; diff --git a/lib/ssh/test/Makefile b/lib/ssh/test/Makefile index 6ce6d6f537..3fca78237c 100644 --- a/lib/ssh/test/Makefile +++ b/lib/ssh/test/Makefile @@ -52,7 +52,8 @@ MODULES= \ ssh_echo_server \ ssh_peername_sockname_server \ ssh_test_cli \ - ssh_relay + ssh_relay \ + ssh_eqc_event_handler HRL_FILES_NEEDED_IN_TEST= \ $(ERL_TOP)/lib/ssh/test/ssh_test_lib.hrl \ diff --git a/lib/ssh/test/property_test/ssh_eqc_client_info_timing.erl b/lib/ssh/test/property_test/ssh_eqc_client_info_timing.erl new file mode 100644 index 0000000000..c07140dc43 --- /dev/null +++ b/lib/ssh/test/property_test/ssh_eqc_client_info_timing.erl @@ -0,0 +1,92 @@ +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2004-2016. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% +%% +%% + +-module(ssh_eqc_client_info_timing). + +-compile(export_all). + +-proptest(eqc). +-proptest([triq,proper]). + +-ifndef(EQC). +-ifndef(PROPER). +-ifndef(TRIQ). +-define(EQC,true). +%%-define(PROPER,true). +%%-define(TRIQ,true). +-endif. +-endif. +-endif. + +-ifdef(EQC). +-include_lib("eqc/include/eqc.hrl"). +-define(MOD_eqc,eqc). + +-else. +-ifdef(PROPER). +-include_lib("proper/include/proper.hrl"). +-define(MOD_eqc,proper). + +-else. +-ifdef(TRIQ). +-define(MOD_eqc,triq). +-include_lib("triq/include/triq.hrl"). + +-endif. +-endif. +-endif. + + +%%% Properties: + +prop_seq(_Config) -> + {ok,Pid} = ssh_eqc_event_handler:add_report_handler(), + {_, _, Port} = init_daemon(), + numtests(1000, + ?FORALL(Delay, choose(0,100),%% Micro seconds + try + send_bad_sequence(Port, Delay, Pid), + not any_relevant_error_report(Pid) + catch + C:E -> io:format('~p:~p~n',[C,E]), + false + end + )). + +send_bad_sequence(Port, Delay, Pid) -> + {ok,S} = gen_tcp:connect("localhost",Port,[]), + gen_tcp:send(S,"Illegal info-string\r\n"), + ssh_test_lib:sleep_microsec(Delay), + gen_tcp:close(S). + +any_relevant_error_report(Pid) -> + {ok, Reports} = ssh_eqc_event_handler:get_reports(Pid), + lists:any(fun({error_report,_,{_,supervisor_report,L}}) when is_list(L) -> + lists:member({reason,{badmatch,{error,closed}}}, L); + (_) -> + false + end, Reports). + +%%%================================================================ +init_daemon() -> + ok = begin ssh:stop(), ssh:start() end, + ssh_test_lib:daemon([]). + diff --git a/lib/ssh/test/ssh_eqc_event_handler.erl b/lib/ssh/test/ssh_eqc_event_handler.erl new file mode 100644 index 0000000000..233965012a --- /dev/null +++ b/lib/ssh/test/ssh_eqc_event_handler.erl @@ -0,0 +1,43 @@ +-module(ssh_eqc_event_handler). + +-compile(export_all). + +-behaviour(gen_event). + +add_report_handler() -> + error_logger:add_report_handler(?MODULE, [self(),Ref=make_ref()]), + receive + {event_handler_started,HandlerPid,Ref} -> + {ok,HandlerPid} + end. + +get_reports(Pid) -> + Pid ! {get_reports,self(),Ref=make_ref()}, + receive + {reports,Reports,Ref} -> + {ok,Reports} + end. + +%%%================================================================ + +-record(state, { + reports = [] + }). + +%% error_logger:add_report_handler(ssh_eqc_event_handler, [self()]). + +init([CallerPid,Ref]) -> + CallerPid ! {event_handler_started,self(),Ref}, + {ok, #state{}}. + +handle_event(Event, State) -> + {ok, State#state{reports = [Event|State#state.reports]}}. + +handle_info({get_reports,From,Ref}, State) -> + From ! {reports, lists:reverse(State#state.reports), Ref}, + {ok, State#state{reports=[]}}. + +handle_call(_Request, State) -> {ok,reply,State}. +terminate(_Arg, _State) -> stop. + +code_change(_OldVsn, State, _Extra) -> {ok, State}. diff --git a/lib/ssh/test/ssh_property_test_SUITE.erl b/lib/ssh/test/ssh_property_test_SUITE.erl index c8aabcedb7..7ba2732a88 100644 --- a/lib/ssh/test/ssh_property_test_SUITE.erl +++ b/lib/ssh/test/ssh_property_test_SUITE.erl @@ -38,6 +38,7 @@ -include_lib("common_test/include/ct.hrl"). all() -> [{group, messages}, + client_sends_info_timing, {group, client_server} ]. @@ -106,3 +107,9 @@ client_server_parallel_multi(Config) -> ssh_eqc_client_server:prop_parallel_multi(Config), Config ). + +client_sends_info_timing(Config) -> + ct_property_test:quickcheck( + ssh_eqc_client_info_timing:prop_seq(Config), + Config + ). diff --git a/lib/ssh/test/ssh_protocol_SUITE.erl b/lib/ssh/test/ssh_protocol_SUITE.erl index 4fac1f718a..93d0bc2eb0 100644 --- a/lib/ssh/test/ssh_protocol_SUITE.erl +++ b/lib/ssh/test/ssh_protocol_SUITE.erl @@ -48,6 +48,7 @@ suite() -> all() -> [{group,tool_tests}, + client_info_line, {group,kex}, {group,service_requests}, {group,authentication}, @@ -575,6 +576,36 @@ client_handles_keyboard_interactive_0_pwds(Config) -> ). + +%%%-------------------------------------------------------------------- +client_info_line(_Config) -> + %% A client must not send an info-line. If it does, the server should handle + %% handle this gracefully + {ok,Pid} = ssh_eqc_event_handler:add_report_handler(), + {_, _, Port} = ssh_test_lib:daemon([]), + + %% Fake client: + {ok,S} = gen_tcp:connect("localhost",Port,[]), + gen_tcp:send(S,"An illegal info-string\r\n"), + gen_tcp:close(S), + + %% wait for server to react: + timer:sleep(1000), + + %% check if a badmatch was received: + {ok, Reports} = ssh_eqc_event_handler:get_reports(Pid), + case lists:any(fun({error_report,_,{_,supervisor_report,L}}) when is_list(L) -> + lists:member({reason,{badmatch,{error,closed}}}, L); + (_) -> + false + end, Reports) of + true -> + ct:fail("Bad error report on info_line from client"); + false -> + ok + end. + + %%%================================================================ %%%==== Internal functions ======================================== %%%================================================================ diff --git a/lib/ssh/test/ssh_test_lib.erl b/lib/ssh/test/ssh_test_lib.erl index 6233680dce..6fd401d182 100644 --- a/lib/ssh/test/ssh_test_lib.erl +++ b/lib/ssh/test/ssh_test_lib.erl @@ -208,6 +208,16 @@ reply(TestCase, Result) -> rcv_expected(Expect, SshPort, Timeout) -> receive + {SshPort, Recvd} when is_function(Expect) -> + case Expect(Recvd) of + true -> + ct:log("Got expected ~p from ~p",[Recvd,SshPort]), + catch port_close(SshPort), + rcv_lingering(50); + false -> + ct:log("Got UNEXPECTED ~p~n",[Recvd]), + rcv_expected(Expect, SshPort, Timeout) + end; {SshPort, Expect} -> ct:log("Got expected ~p from ~p",[Expect,SshPort]), catch port_close(SshPort), @@ -767,3 +777,28 @@ open_port(Arg1, ExtraOpts) -> use_stdio, overlapped_io, hide %only affects windows | ExtraOpts]). + +%%%---------------------------------------------------------------- +%%% Sleeping + +%%% Milli sec +sleep_millisec(Nms) -> receive after Nms -> ok end. + +%%% Micro sec +sleep_microsec(Nus) -> + busy_wait(Nus, erlang:system_time(microsecond)). + +busy_wait(Nus, T0) -> + T = erlang:system_time(microsecond) - T0, + Tleft = Nus - T, + if + Tleft > 2000 -> + sleep_millisec((Tleft-1500) div 1000), % μs -> ms + busy_wait(Nus,T0); + Tleft > 1 -> + busy_wait(Nus, T0); + true -> + T + end. + +%%%---------------------------------------------------------------- diff --git a/lib/ssh/test/ssh_to_openssh_SUITE.erl b/lib/ssh/test/ssh_to_openssh_SUITE.erl index a914938c41..f481e9c1ce 100644 --- a/lib/ssh/test/ssh_to_openssh_SUITE.erl +++ b/lib/ssh/test/ssh_to_openssh_SUITE.erl @@ -58,7 +58,8 @@ groups() -> erlang_client_openssh_server_nonexistent_subsystem ]}, {erlang_server, [], [erlang_server_openssh_client_public_key_dsa, - erlang_server_openssh_client_public_key_rsa + erlang_server_openssh_client_public_key_rsa, + erlang_server_openssh_client_renegotiate ]} ]. @@ -386,6 +387,41 @@ erlang_server_openssh_client_public_key_X(Config, PubKeyAlg) -> ssh:stop_daemon(Pid). %%-------------------------------------------------------------------- +%% Test that the Erlang/OTP server can renegotiate with openSSH +erlang_server_openssh_client_renegotiate(Config) -> + PubKeyAlg = ssh_rsa, + SystemDir = proplists:get_value(data_dir, Config), + PrivDir = proplists:get_value(priv_dir, Config), + KnownHosts = filename:join(PrivDir, "known_hosts"), + {Pid, Host, Port} = ssh_test_lib:daemon([{system_dir, SystemDir}, + {public_key_alg, PubKeyAlg}, + {failfun, fun ssh_test_lib:failfun/2}]), + + ct:sleep(500), + + DataFile = filename:join(PrivDir, "renegotiate_openssh_client.data"), + Data = lists:duplicate(32000, $a), + ok = file:write_file(DataFile, Data), + + Cmd = "ssh -p " ++ integer_to_list(Port) ++ + " -o UserKnownHostsFile=" ++ KnownHosts ++ + " -o RekeyLimit=20K" ++ + " " ++ Host ++ " < " ++ DataFile, + OpenSsh = ssh_test_lib:open_port({spawn, Cmd}), + + Expect = fun({data,R}) -> + try lists:prefix(binary_to_list(R), Data) + catch + _:_ -> false + end; + (_) -> + false + end, + + ssh_test_lib:rcv_expected(Expect, OpenSsh, ?TIMEOUT), + ssh:stop_daemon(Pid). + +%%-------------------------------------------------------------------- erlang_client_openssh_server_password() -> [{doc, "Test client password option"}]. erlang_client_openssh_server_password(Config) when is_list(Config) -> diff --git a/lib/ssh/vsn.mk b/lib/ssh/vsn.mk index 09e707ad07..c023429056 100644 --- a/lib/ssh/vsn.mk +++ b/lib/ssh/vsn.mk @@ -1,5 +1,5 @@ #-*-makefile-*- ; force emacs to enter makefile-mode -SSH_VSN = 4.3.3 +SSH_VSN = 4.3.6 APP_VSN = "ssh-$(SSH_VSN)" diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index abba5aaf59..68f2f97b6e 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -155,7 +155,7 @@ <tag><c>cipher() =</c></tag> <item><p><c>rc4_128 | des_cbc | '3des_ede_cbc' - | aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm</c></p></item> + | aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm | chacha20_poly1305</c></p></item> <tag><c>hash() =</c></tag> <item><p><c>md5 | sha | sha224 | sha256 | sha348 | sha512</c></p></item> diff --git a/lib/ssl/src/ssl_cipher.erl b/lib/ssl/src/ssl_cipher.erl index 02873ce522..605bbd859a 100644 --- a/lib/ssl/src/ssl_cipher.erl +++ b/lib/ssl/src/ssl_cipher.erl @@ -46,9 +46,9 @@ erl_cipher_suite/0, openssl_cipher_suite/0, hash/0, key_algo/0, sign_algo/0]). --type cipher() :: null |rc4_128 | idea_cbc | des40_cbc | des_cbc | '3des_ede_cbc' +-type cipher() :: null |rc4_128 | des_cbc | '3des_ede_cbc' | aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm | chacha20_poly1305. --type hash() :: null | sha | md5 | sha224 | sha256 | sha384 | sha512. +-type hash() :: null | md5 | sha | sha224 | sha256 | sha384 | sha512. -type sign_algo() :: rsa | dsa | ecdsa. -type key_algo() :: null | rsa | dhe_rsa | dhe_dss | ecdhe_ecdsa| ecdh_ecdsa | ecdh_rsa| srp_rsa| srp_dss | psk | dhe_psk | rsa_psk | dh_anon | ecdh_anon | srp_anon. @@ -1447,28 +1447,60 @@ filter_suites(Suites) -> is_acceptable_prf(Prf, Hashs) end, Suites). -is_acceptable_keyexchange(KeyExchange, Algos) - when KeyExchange == ecdh_ecdsa; - KeyExchange == ecdhe_ecdsa; - KeyExchange == ecdh_rsa; - KeyExchange == ecdhe_rsa; - KeyExchange == ecdh_anon -> +is_acceptable_keyexchange(KeyExchange, _Algos) when KeyExchange == psk; + KeyExchange == null -> + true; +is_acceptable_keyexchange(KeyExchange, Algos) when KeyExchange == dh_anon; + KeyExchange == dhe_psk -> + proplists:get_bool(dh, Algos); +is_acceptable_keyexchange(dhe_dss, Algos) -> + proplists:get_bool(dh, Algos) andalso + proplists:get_bool(dss, Algos); +is_acceptable_keyexchange(dhe_rsa, Algos) -> + proplists:get_bool(dh, Algos) andalso + proplists:get_bool(rsa, Algos); +is_acceptable_keyexchange(ecdh_anon, Algos) -> proplists:get_bool(ecdh, Algos); -is_acceptable_keyexchange(_, _) -> - true. - +is_acceptable_keyexchange(KeyExchange, Algos) when KeyExchange == ecdh_ecdsa; + KeyExchange == ecdhe_ecdsa -> + proplists:get_bool(ecdh, Algos) andalso + proplists:get_bool(ecdsa, Algos); +is_acceptable_keyexchange(KeyExchange, Algos) when KeyExchange == ecdh_rsa; + KeyExchange == ecdhe_rsa -> + proplists:get_bool(ecdh, Algos) andalso + proplists:get_bool(rsa, Algos); +is_acceptable_keyexchange(KeyExchange, Algos) when KeyExchange == rsa; + KeyExchange == rsa_psk -> + proplists:get_bool(rsa, Algos); +is_acceptable_keyexchange(srp_anon, Algos) -> + proplists:get_bool(srp, Algos); +is_acceptable_keyexchange(srp_dss, Algos) -> + proplists:get_bool(srp, Algos) andalso + proplists:get_bool(dss, Algos); +is_acceptable_keyexchange(srp_rsa, Algos) -> + proplists:get_bool(srp, Algos) andalso + proplists:get_bool(rsa, Algos); +is_acceptable_keyexchange(_KeyExchange, _Algos) -> + false. + +is_acceptable_cipher(null, _Algos) -> + true; +is_acceptable_cipher(rc4_128, Algos) -> + proplists:get_bool(rc4, Algos); +is_acceptable_cipher(des_cbc, Algos) -> + proplists:get_bool(des_cbc, Algos); +is_acceptable_cipher('3des_ede_cbc', Algos) -> + proplists:get_bool(des3_cbc, Algos); +is_acceptable_cipher(aes_128_cbc, Algos) -> + proplists:get_bool(aes_cbc128, Algos); +is_acceptable_cipher(aes_256_cbc, Algos) -> + proplists:get_bool(aes_cbc256, Algos); is_acceptable_cipher(Cipher, Algos) when Cipher == aes_128_gcm; Cipher == aes_256_gcm -> proplists:get_bool(aes_gcm, Algos); -is_acceptable_cipher(Cipher, Algos) - when Cipher == chacha20_poly1305 -> - proplists:get_bool(Cipher, Algos); -is_acceptable_cipher(Cipher, Algos) - when Cipher == rc4_128 -> - proplists:get_bool(rc4, Algos); -is_acceptable_cipher(_, _) -> - true. +is_acceptable_cipher(Cipher, Algos) -> + proplists:get_bool(Cipher, Algos). is_acceptable_hash(null, _Algos) -> true; diff --git a/lib/ssl/test/ssl_basic_SUITE.erl b/lib/ssl/test/ssl_basic_SUITE.erl index 322f93b94c..1be43c56c4 100644 --- a/lib/ssl/test/ssl_basic_SUITE.erl +++ b/lib/ssl/test/ssl_basic_SUITE.erl @@ -364,6 +364,16 @@ init_per_testcase(TestCase, Config) when TestCase == psk_cipher_suites; ct:timetrap({seconds, 60}), Config; +init_per_testcase(version_option, Config) -> + ssl_test_lib:ct_log_supported_protocol_versions(Config), + ct:timetrap({seconds, 10}), + Config; + +init_per_testcase(reuse_session, Config) -> + ssl_test_lib:ct_log_supported_protocol_versions(Config), + ct:timetrap({seconds, 10}), + Config; + init_per_testcase(rizzo, Config) -> ssl_test_lib:ct_log_supported_protocol_versions(Config), ct:timetrap({seconds, 40}), diff --git a/lib/ssl/test/ssl_crl_SUITE.erl b/lib/ssl/test/ssl_crl_SUITE.erl index bc2822f0c4..e293d183f7 100644 --- a/lib/ssl/test/ssl_crl_SUITE.erl +++ b/lib/ssl/test/ssl_crl_SUITE.erl @@ -99,32 +99,37 @@ init_per_group(check_peer, Config) -> init_per_group(check_best_effort, Config) -> [{crl_check, best_effort} | Config]; init_per_group(Group, Config0) -> - case is_idp(Group) of - true -> - [{idp_crl, true} | Config0]; - false -> - DataDir = proplists:get_value(data_dir, Config0), - CertDir = filename:join(proplists:get_value(priv_dir, Config0), Group), - {CertOpts, Config} = init_certs(CertDir, Group, Config0), - {ok, _} = make_certs:all(DataDir, CertDir, CertOpts), - case Group of - crl_hash_dir -> - CrlDir = filename:join(CertDir, "crls"), - %% Copy CRLs to their hashed filenames. - %% Find the hashes with 'openssl crl -noout -hash -in crl.pem'. - populate_crl_hash_dir(CertDir, CrlDir, - [{"erlangCA", "d6134ed3"}, - {"otpCA", "d4c8d7e5"}], - replace), - CrlCacheOpts = [{crl_cache, - {ssl_crl_hash_dir, - {internal, [{dir, CrlDir}]}}}]; - _ -> - CrlCacheOpts = [] - end, - [{crl_cache_opts, CrlCacheOpts}, - {cert_dir, CertDir}, - {idp_crl, false} | Config] + try + case is_idp(Group) of + true -> + [{idp_crl, true} | Config0]; + false -> + DataDir = proplists:get_value(data_dir, Config0), + CertDir = filename:join(proplists:get_value(priv_dir, Config0), Group), + {CertOpts, Config} = init_certs(CertDir, Group, Config0), + {ok, _} = make_certs:all(DataDir, CertDir, CertOpts), + CrlCacheOpts = case Group of + crl_hash_dir -> + CrlDir = filename:join(CertDir, "crls"), + %% Copy CRLs to their hashed filenames. + %% Find the hashes with 'openssl crl -noout -hash -in crl.pem'. + populate_crl_hash_dir(CertDir, CrlDir, + [{"erlangCA", "d6134ed3"}, + {"otpCA", "d4c8d7e5"}], + replace), + [{crl_cache, + {ssl_crl_hash_dir, + {internal, [{dir, CrlDir}]}}}]; + _ -> + [] + end, + [{crl_cache_opts, CrlCacheOpts}, + {cert_dir, CertDir}, + {idp_crl, false} | Config] + end + catch + _:_ -> + {skip, "Unable to create crls"} end. end_per_group(_GroupName, Config) -> @@ -187,7 +192,7 @@ crl_verify_valid(Config) when is_list(Config) -> {crl_cache, {ssl_crl_cache, {internal, [{http, 5000}]}}}, {verify, verify_peer}]; false -> - ?config(crl_cache_opts, Config) ++ + proplists:get_value(crl_cache_opts, Config) ++ [{cacertfile, filename:join([PrivDir, "server", "cacerts.pem"])}, {crl_check, Check}, {verify, verify_peer}] @@ -220,7 +225,7 @@ crl_verify_revoked(Config) when is_list(Config) -> {crl_check, Check}, {verify, verify_peer}]; false -> - ?config(crl_cache_opts, Config) ++ + proplists:get_value(crl_cache_opts, Config) ++ [{cacertfile, filename:join([PrivDir, "revoked", "cacerts.pem"])}, {crl_check, Check}, {verify, verify_peer}] @@ -279,8 +284,8 @@ crl_verify_no_crl(Config) when is_list(Config) -> crl_hash_dir_collision() -> [{doc,"Verify ssl_crl_hash_dir behaviour with hash collisions"}]. crl_hash_dir_collision(Config) when is_list(Config) -> - PrivDir = ?config(cert_dir, Config), - Check = ?config(crl_check, Config), + PrivDir = proplists:get_value(cert_dir, Config), + Check = proplists:get_value(crl_check, Config), %% Create two CAs whose names hash to the same value CA1 = "hash-collision-0000000000", @@ -307,13 +312,17 @@ crl_hash_dir_collision(Config) when is_list(Config) -> {CA2, "b68fc624"}], replace), - ClientOpts = ?config(crl_cache_opts, Config) ++ - [{cacertfile, filename:join([PrivDir, "erlangCA", "cacerts.pem"])}, + NewCA = new_ca(filename:join([PrivDir, "new_ca"]), + filename:join([PrivDir, "erlangCA", "cacerts.pem"]), + filename:join([PrivDir, "server", "cacerts.pem"])), + + ClientOpts = proplists:get_value(crl_cache_opts, Config) ++ + [{cacertfile, NewCA}, {crl_check, Check}, {verify, verify_peer}], - + {ClientNode, ServerNode, Hostname} = ssl_test_lib:run_where(Config), - + %% Neither certificate revoked; both succeed. crl_verify_valid(Hostname, ServerNode, ServerOpts1, ClientNode, ClientOpts), crl_verify_valid(Hostname, ServerNode, ServerOpts2, ClientNode, ClientOpts), @@ -346,8 +355,8 @@ crl_hash_dir_collision(Config) when is_list(Config) -> crl_hash_dir_expired() -> [{doc,"Verify ssl_crl_hash_dir behaviour with expired CRLs"}]. crl_hash_dir_expired(Config) when is_list(Config) -> - PrivDir = ?config(cert_dir, Config), - Check = ?config(crl_check, Config), + PrivDir = proplists:get_value(cert_dir, Config), + Check = proplists:get_value(crl_check, Config), CA = "CRL-maybe-expired-CA", %% Add "issuing distribution point", to ensure that verification @@ -362,7 +371,7 @@ crl_hash_dir_expired(Config) when is_list(Config) -> ServerOpts = [{keyfile, filename:join([PrivDir, EndUser, "key.pem"])}, {certfile, filename:join([PrivDir, EndUser, "cert.pem"])}, {cacertfile, filename:join([PrivDir, EndUser, "cacerts.pem"])}], - ClientOpts = ?config(crl_cache_opts, Config) ++ + ClientOpts = proplists:get_value(crl_cache_opts, Config) ++ [{cacertfile, filename:join([PrivDir, CA, "cacerts.pem"])}, {crl_check, Check}, {verify, verify_peer}], @@ -492,3 +501,12 @@ find_free_name(CrlDir, Hash, N) -> false -> Name end. + +new_ca(FileName, CA1, CA2) -> + {ok, P1} = file:read_file(CA1), + E1 = public_key:pem_decode(P1), + {ok, P2} = file:read_file(CA2), + E2 = public_key:pem_decode(P2), + Pem = public_key:pem_encode(E1 ++E2), + file:write_file(FileName, Pem), + FileName. diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 3322571b2c..64267c2af5 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -54,7 +54,8 @@ <p> This is a new behavior in Erlang/OTP 19.0. It has been thoroughly reviewed, is stable enough - to be used by at least two heavy OTP applications, and is here to stay. + to be used by at least two heavy OTP applications, + and is here to stay. Depending on user feedback, we do not expect but can find it necessary to make minor not backward compatible changes into Erlang/OTP 20.0. @@ -70,6 +71,7 @@ <item>The state can be any term.</item> <item>Events can be postponed.</item> <item>Events can be self-generated.</item> + <item>Automatic state enter code can be called.</item> <item>A reply can be sent from a later state.</item> <item>There can be multiple <c>sys</c> traceable replies.</item> </list> @@ -125,9 +127,9 @@ erlang:'!' -----> Module:StateName/3 is not regarded as an error but as a valid return from all callback functions. </p> - <marker id="state_function"/> + <marker id="state callback"/> <p> - The "<em>state function</em>" for a specific + The "<em>state callback</em>" for a specific <seealso marker="#type-state">state</seealso> in a <c>gen_statem</c> is the callback function that is called for all events in this state. It is selected depending on which @@ -139,7 +141,7 @@ erlang:'!' -----> Module:StateName/3 When the <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> is <c>state_functions</c>, the state must be an atom and - is used as the state function name; see + is used as the state callback name; see <seealso marker="#Module:StateName/3"><c>Module:StateName/3</c></seealso>. This gathers all code for a specific state in one function as the <c>gen_statem</c> engine @@ -152,7 +154,7 @@ erlang:'!' -----> Module:StateName/3 When the <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> is <c>handle_event_function</c>, the state can be any term - and the state function name is + and the state callback name is <seealso marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seealso>. This makes it easy to branch depending on state or event as you desire. Be careful about which events you handle in which @@ -162,8 +164,8 @@ erlang:'!' -----> Module:StateName/3 <p> The <c>gen_statem</c> enqueues incoming events in order of arrival and presents these to the - <seealso marker="#state_function">state function</seealso> - in that order. The state function can postpone an event + <seealso marker="#state callback">state callback</seealso> + in that order. The state callback can postpone an event so it is not retried in the current state. After a state change the queue restarts with the postponed events. </p> @@ -175,12 +177,12 @@ erlang:'!' -----> Module:StateName/3 to entering a new receive statement. </p> <p> - The <seealso marker="#state_function">state function</seealso> + The <seealso marker="#state callback">state callback</seealso> can insert events using the <seealso marker="#type-action"><c>action()</c></seealso> <c>next_event</c> and such an event is inserted as the next to present - to the state function. That is, as if it is + to the state callback. That is, as if it is the oldest incoming event. A dedicated <seealso marker="#type-event_type"><c>event_type()</c></seealso> <c>internal</c> can be used for such events making them impossible @@ -193,9 +195,19 @@ erlang:'!' -----> Module:StateName/3 <seealso marker="gen_fsm"><c>gen_fsm</c></seealso> to force processing an inserted event before others. </p> + <p> + The <c>gen_statem</c> engine can automatically + make a specialized call to the + <seealso marker="#state callback">state callback</seealso> + whenever a new state is entered; see + <seealso marker="#type-state_enter"><c>state_enter()</c></seealso>. + This is for writing code common to all state entries. + Another way to do it is to insert events at state transitions, + but you have to do so everywhere it is needed. + </p> <note> <p>If you in <c>gen_statem</c>, for example, postpone - an event in one state and then call another state function + an event in one state and then call another state callback of yours, you have not changed states and hence the postponed event is not retried, which is logical but can be confusing. </p> @@ -224,7 +236,7 @@ erlang:'!' -----> Module:StateName/3 The <c>gen_statem</c> process can go into hibernation; see <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>. It is done when a - <seealso marker="#state_function">state function</seealso> or + <seealso marker="#state callback">state callback</seealso> or <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> specifies <c>hibernate</c> in the returned <seealso marker="#type-action"><c>Actions</c></seealso> @@ -282,7 +294,7 @@ init([]) -> {ok,State,Data}. callback_mode() -> state_functions. -%%% State function(s) +%%% state callback(s) off({call,From}, push, Data) -> %% Go to 'on', increment count and reply @@ -336,7 +348,7 @@ ok <code type="erl"> callback_mode() -> handle_event_function. -%%% State function(s) +%%% state callback(s) handle_event({call,From}, push, off, Data) -> %% Go to 'on', increment count and reply @@ -470,6 +482,10 @@ handle_event(_, _, State, Data) -> <name name="state"/> <desc> <p> + If the + <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + is <c>handle_event_function</c>, + the state can be any term. After a state change (<c>NextState =/= State</c>), all postponed events are retried. </p> @@ -483,6 +499,8 @@ handle_event(_, _, State, Data) -> <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> is <c>state_functions</c>, the state must be of this type. + After a state change (<c>NextState =/= State</c>), + all postponed events are retried. </p> </desc> </datatype> @@ -515,7 +533,22 @@ handle_event(_, _, State, Data) -> Type <c>info</c> originates from regular process messages sent to the <c>gen_statem</c>. Also, the state machine implementation can generate events of types - <c>timeout</c> and <c>internal</c> to itself. + <c>timeout</c>, <c>state_timeout</c>, <c>enter</c>, + and <c>internal</c> to itself. + </p> + </desc> + </datatype> + <datatype> + <name name="callback_mode_result"/> + <desc> + <p> + This is the return type from + <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> + and selects + <seealso marker="#type-callback_mode">callback mode</seealso> + and whether to do + <seealso marker="#type-state_enter">state enter calls</seealso>, + or not. </p> </desc> </datatype> @@ -551,13 +584,58 @@ handle_event(_, _, State, Data) -> </desc> </datatype> <datatype> + <name name="state_enter"/> + <desc> + <p> + If the state machine should use <em>state enter calls</em> + is selected when starting the <c>gen_statem</c> + and after code change using the return value from + <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>. + </p> + <p> + If + <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> + returns a list containing <c>state_enter</c>, + the <c>gen_statem</c> engine will, at every state change, + call the + <seealso marker="#state callback">state callback</seealso> + with arguments <c>(enter, OldState, Data)</c>. + This may look like an event but is really a call + performed after the previous state callback returned + and before any event is delivered to the new state callback. + See + <seealso marker="#Module:StateName/3"><c>Module:StateName/3</c></seealso> + and + <seealso marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seealso>. + </p> + <p> + If + <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> + does not return such a list, no state enter calls are done. + </p> + <p> + If + <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso> + should transform the state to a state with a different + name it is still regarded as the same state so this + does not cause a state enter call. + </p> + <p> + Note that a state enter call <em>will</em> be done + right before entering the initial state even though this + formally is not a state change. + In this case <c>OldState</c> will be the same as <c>State</c>, + which can not happen for a subsequent state change. + </p> + </desc> + </datatype> + <datatype> <name name="transition_option"/> <desc> <p> Transition options can be set by <seealso marker="#type-action">actions</seealso> - and they modify the following in how - the state transition is done: + and they modify how the state transition is done: </p> <list type="ordered"> <item> @@ -586,27 +664,46 @@ handle_event(_, _, State, Data) -> All events stored with <seealso marker="#type-action"><c>action()</c></seealso> <c>next_event</c> - are inserted in the queue to be processed before - all other events. + are inserted to be processed before the other queued events. + </p> + </item> + <item> + <p> + If the state changes or is the initial state, and + <seealso marker="#type-state_enter"><em>state enter calls</em></seealso> + are used, the <c>gen_statem</c> calls + the new state callback with arguments + <seealso marker="#type-state_enter">(enter, OldState, Data)</seealso>. + Any + <seealso marker="#type-enter_action"><c>actions</c></seealso> + returned from this call are handled as if they were + appended to the actions + returned by the state callback that changed states. </p> </item> <item> <p> - If an + If there are enqueued events the (possibly new) + <seealso marker="#state callback">state callback</seealso> + is called with the oldest enqueued event, + and we start again from the top of this list. + </p> + </item> + <item> + <p> + Timeout timers + <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso> + and <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso> - is set through - <seealso marker="#type-action"><c>action()</c></seealso> - <c>timeout</c>, - an event timer can be started or a time-out zero event - can be enqueued. + are handled. This may lead to a time-out zero event + being generated to the + <seealso marker="#state callback">state callback</seealso> + and we start again from the top of this list. </p> </item> <item> <p> - The (possibly new) - <seealso marker="#state_function">state function</seealso> - is called with the oldest enqueued event if there is any, - otherwise the <c>gen_statem</c> goes into <c>receive</c> + Otherwise the <c>gen_statem</c> goes into <c>receive</c> or hibernation (if <seealso marker="#type-hibernate"><c>hibernate()</c></seealso> @@ -614,8 +711,11 @@ handle_event(_, _, State, Data) -> to wait for the next message. In hibernation the next non-system event awakens the <c>gen_statem</c>, or rather the next incoming message awakens the <c>gen_statem</c>, - but if it is a system event - it goes right back into hibernation. + but if it is a system event it goes right back into hibernation. + When a new message arrives the + <seealso marker="#state callback">state callback</seealso> + is called with the corresponding event, + and we start again from the top of this list. </p> </item> </list> @@ -657,34 +757,65 @@ handle_event(_, _, State, Data) -> <seealso marker="#type-event_type"><c>event_type()</c></seealso> <c>timeout</c> after this time (in milliseconds) unless another - event arrives in which case this time-out is cancelled. - Notice that a retried or inserted event - counts like a new in this respect. + event arrives or has arrived + in which case this time-out is cancelled. + Note that a retried, inserted or state time-out zero + events counts as arrived. </p> <p> If the value is <c>infinity</c>, no timer is started, as - it never triggers anyway. + it never would trigger anyway. </p> <p> - If the value is <c>0</c>, the time-out event is immediately enqueued - unless there already are enqueued events, as the - time-out is then immediately cancelled. - This is a feature ensuring that a time-out <c>0</c> event - is processed before any not yet received external event. + If the value is <c>0</c> no timer is actually started, + instead the the time-out event is enqueued to ensure + that it gets processed before any not yet + received external event. </p> <p> - Notice that it is not possible or needed to cancel this time-out, + Note that it is not possible or needed to cancel this time-out, as it is cancelled automatically by any other event. </p> </desc> </datatype> <datatype> + <name name="state_timeout"/> + <desc> + <p> + Generates an event of + <seealso marker="#type-event_type"><c>event_type()</c></seealso> + <c>state_timeout</c> + after this time (in milliseconds) unless the <c>gen_statem</c> + changes states (<c>NewState =/= OldState</c>) + which case this time-out is cancelled. + </p> + <p> + If the value is <c>infinity</c>, no timer is started, as + it never would trigger anyway. + </p> + <p> + If the value is <c>0</c> no timer is actually started, + instead the the time-out event is enqueued to ensure + that it gets processed before any not yet + received external event. + </p> + <p> + Setting this timer while it is running will restart it with + the new time-out value. Therefore it is possible to cancel + this timeout by setting it to <c>infinity</c>. + </p> + </desc> + </datatype> + <datatype> <name name="action"/> <desc> <p> These state transition actions can be invoked by returning them from the - <seealso marker="#state_function">state function</seealso>, from + <seealso marker="#state callback">state callback</seealso> + when it is called with an + <seealso marker="#type-event_type">event</seealso>, + from <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> or by giving them to <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>. @@ -698,8 +829,8 @@ handle_event(_, _, State, Data) -> override any previous of the same type, so the last in the containing list wins. For example, the last - <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso> - overrides any other <c>event_timeout()</c> in the list. + <seealso marker="#type-postpone"><c>postpone()</c></seealso> + overrides any previous <c>postpone()</c> in the list. </p> <taglist> <tag><c>postpone</c></tag> @@ -716,6 +847,53 @@ handle_event(_, _, State, Data) -> as there is no event to postpone in those cases. </p> </item> + <tag><c>next_event</c></tag> + <item> + <p> + Stores the specified <c><anno>EventType</anno></c> + and <c><anno>EventContent</anno></c> for insertion after all + actions have been executed. + </p> + <p> + The stored events are inserted in the queue as the next to process + before any already queued events. The order of these stored events + is preserved, so the first <c>next_event</c> in the containing + list becomes the first to process. + </p> + <p> + An event of type + <seealso marker="#type-event_type"><c>internal</c></seealso> + is to be used when you want to reliably distinguish + an event inserted this way from any external event. + </p> + </item> + </taglist> + </desc> + </datatype> + <datatype> + <name name="enter_action"/> + <desc> + <p> + These state transition actions can be invoked by + returning them from the + <seealso marker="#state callback">state callback</seealso>, from + <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + or by giving them to + <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>. + </p> + <p> + Actions are executed in the containing list order. + </p> + <p> + Actions that set + <seealso marker="#type-transition_option">transition options</seealso> + override any previous of the same type, + so the last in the containing list wins. + For example, the last + <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso> + overrides any previous <c>event_timeout()</c> in the list. + </p> + <taglist> <tag><c>hibernate</c></tag> <item> <p> @@ -731,7 +909,7 @@ handle_event(_, _, State, Data) -> Short for <c>{timeout,Timeout,Timeout}</c>, that is, the time-out message is the time-out time. This form exists to make the - <seealso marker="#state_function">state function</seealso> + <seealso marker="#state callback">state callback</seealso> return value <c>{next_state,NextState,NewData,Timeout}</c> allowed like for <c>gen_fsm</c>'s <seealso marker="gen_fsm#Module:StateName/2"><c>Module:StateName/2</c></seealso>. @@ -746,30 +924,13 @@ handle_event(_, _, State, Data) -> to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c>. </p> </item> - <tag><c>reply_action()</c></tag> - <item> - <p> - Replies to a caller. - </p> - </item> - <tag><c>next_event</c></tag> + <tag><c>state_timeout</c></tag> <item> <p> - Stores the specified <c><anno>EventType</anno></c> - and <c><anno>EventContent</anno></c> for insertion after all - actions have been executed. - </p> - <p> - The stored events are inserted in the queue as the next to process - before any already queued events. The order of these stored events - is preserved, so the first <c>next_event</c> in the containing - list becomes the first to process. - </p> - <p> - An event of type - <seealso marker="#type-event_type"><c>internal</c></seealso> - is to be used when you want to reliably distinguish - an event inserted this way from any external event. + Sets the + <seealso marker="#type-transition_option"><c>transition_option()</c></seealso> + <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso> + to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c>. </p> </item> </taglist> @@ -779,39 +940,70 @@ handle_event(_, _, State, Data) -> <name name="reply_action"/> <desc> <p> - Replies to a caller waiting for a reply in + This state transition action can be invoked by + returning it from the + <seealso marker="#state callback">state callback</seealso>, from + <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + or by giving it to + <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>. + </p> + <p> + It replies to a caller waiting for a reply in <seealso marker="#call/2"><c>call/2</c></seealso>. <c><anno>From</anno></c> must be the term from argument <seealso marker="#type-event_type"><c>{call,<anno>From</anno>}</c></seealso> - to the - <seealso marker="#state_function">state function</seealso>. + in a call to a + <seealso marker="#state callback">state callback</seealso>. + </p> + <p> + Note that using this action from + <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + or + <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso> + would be weird on the border of whichcraft + since there has been no earlier call to a + <seealso marker="#state callback">state callback</seealso> + in this server. </p> </desc> </datatype> <datatype> - <name name="state_function_result"/> + <name name="state_enter_result"/> <desc> + <p> + <c><anno>State</anno></c> is the current state + and it can not be changed since the state callback + was called with a + <seealso marker="#type-state_enter"><em>state enter call</em></seealso>. + </p> <taglist> <tag><c>next_state</c></tag> <item> <p> The <c>gen_statem</c> does a state transition to - <c><anno>NextStateName</anno></c> - (which can be the same as the current state), + <c><anno>State</anno></c>, which has to be + the current state, sets <c><anno>NewData</anno></c>, and executes all <c><anno>Actions</anno></c>. </p> </item> </taglist> - <p> - All these terms are tuples or atoms and this property - will hold in any future version of <c>gen_statem</c>. - </p> </desc> </datatype> <datatype> - <name name="handle_event_result"/> + <name name="event_handler_result"/> <desc> + <p> + <c><anno>StateType</anno></c> is + <seealso marker="#type-state_name"><c>state_name()</c></seealso> + if + <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + is <c>state_functions</c>, or + <seealso marker="#type-state"><c>state()</c></seealso> + if + <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + is <c>handle_event_function</c>. + </p> <taglist> <tag><c>next_state</c></tag> <item> @@ -824,35 +1016,21 @@ handle_event(_, _, State, Data) -> </p> </item> </taglist> - <p> - All these terms are tuples or atoms and this property - will hold in any future version of <c>gen_statem</c>. - </p> </desc> </datatype> <datatype> - <name name="common_state_callback_result"/> + <name name="state_callback_result"/> <desc> + <p> + <c><anno>ActionType</anno></c> is + <seealso marker="#type-enter_action"><c>enter_action()</c></seealso> + if the state callback was called with a + <seealso marker="#type-state_enter"><em>state enter call</em></seealso> + and + <seealso marker="#type-action"><c>action()</c></seealso> + if the state callback was called with an event. + </p> <taglist> - <tag><c>stop</c></tag> - <item> - <p> - Terminates the <c>gen_statem</c> by calling - <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> - with <c>Reason</c> and - <c><anno>NewData</anno></c>, if specified. - </p> - </item> - <tag><c>stop_and_reply</c></tag> - <item> - <p> - Sends all <c><anno>Replies</anno></c>, - then terminates the <c>gen_statem</c> by calling - <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> - with <c>Reason</c> and - <c><anno>NewData</anno></c>, if specified. - </p> - </item> <tag><c>keep_state</c></tag> <item> <p> @@ -875,6 +1053,25 @@ handle_event(_, _, State, Data) -> <c>{next_state,CurrentState,CurrentData,<anno>Actions</anno>}</c>. </p> </item> + <tag><c>stop</c></tag> + <item> + <p> + Terminates the <c>gen_statem</c> by calling + <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> + with <c>Reason</c> and + <c><anno>NewData</anno></c>, if specified. + </p> + </item> + <tag><c>stop_and_reply</c></tag> + <item> + <p> + Sends all <c><anno>Replies</anno></c>, + then terminates the <c>gen_statem</c> by calling + <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> + with <c>Reason</c> and + <c><anno>NewData</anno></c>, if specified. + </p> + </item> </taglist> <p> All these terms are tuples or atoms and this property @@ -896,14 +1093,14 @@ handle_event(_, _, State, Data) -> by sending a request and waiting until its reply arrives. The <c>gen_statem</c> calls the - <seealso marker="#state_function">state function</seealso> with + <seealso marker="#state callback">state callback</seealso> with <seealso marker="#type-event_type"><c>event_type()</c></seealso> <c>{call,From}</c> and event content <c><anno>Request</anno></c>. </p> <p> A <c><anno>Reply</anno></c> is generated when a - <seealso marker="#state_function">state function</seealso> + <seealso marker="#state callback">state callback</seealso> returns with <c>{reply,From,<anno>Reply</anno>}</c> as one <seealso marker="#type-action"><c>action()</c></seealso>, @@ -919,18 +1116,40 @@ handle_event(_, _, State, Data) -> </p> <note> <p> - For <c><anno>Timeout</anno> =/= infinity</c>, + For <c><anno>Timeout</anno> < infinity</c>, to avoid getting a late reply in the caller's - inbox, this function spawns a proxy process that + inbox if the caller should catch exceptions, + this function spawns a proxy process that does the call. A late reply gets delivered to the dead proxy process, hence gets discarded. This is less efficient than using - <c><anno>Timeout</anno> =:= infinity</c>. + <c><anno>Timeout</anno> == infinity</c>. </p> </note> <p> - The call can fail, for example, if the <c>gen_statem</c> dies - before or during this function call. + <c><anno>Timeout</anno></c> can also be a tuple + <c>{clean_timeout,<anno>T</anno>}</c> or + <c>{dirty_timeout,<anno>T</anno>}</c>, where + <c><anno>T</anno></c> is the timeout time. + <c>{clean_timeout,<anno>T</anno>}</c> works like + just <c>T</c> described in the note above + and uses a proxy process for <c>T < infinity</c>, + while <c>{dirty_timeout,<anno>T</anno>}</c> + bypasses the proxy process which is more lightweight. + </p> + <note> + <p> + If you combine catching exceptions from this function + with <c>{dirty_timeout,<anno>T</anno>}</c> + to avoid that the calling process dies when the call + times out, you will have to be prepared to handle + a late reply. + So why not just allow the calling process to die? + </p> + </note> + <p> + The call can also fail, for example, if the <c>gen_statem</c> + dies before or during this function call. </p> </desc> </func> @@ -946,7 +1165,7 @@ handle_event(_, _, State, Data) -> ignoring if the destination node or <c>gen_statem</c> does not exist. The <c>gen_statem</c> calls the - <seealso marker="#state_function">state function</seealso> with + <seealso marker="#state callback">state callback</seealso> with <seealso marker="#type-event_type"><c>event_type()</c></seealso> <c>cast</c> and event content <c><anno>Msg</anno></c>. @@ -1060,17 +1279,18 @@ handle_event(_, _, State, Data) -> <seealso marker="#call/2"><c>call/2</c></seealso> when the reply cannot be defined in the return value of a - <seealso marker="#state_function">state function</seealso>. + <seealso marker="#state callback">state callback</seealso>. </p> <p> <c><anno>From</anno></c> must be the term from argument <seealso marker="#type-event_type"><c>{call,<anno>From</anno>}</c></seealso> to the - <seealso marker="#state_function">state function</seealso>. - <c><anno>From</anno></c> and <c><anno>Reply</anno></c> - can also be specified using a - <seealso marker="#type-reply_action"><c>reply_action()</c></seealso> - and multiple replies with a list of them. + <seealso marker="#state callback">state callback</seealso>. + A reply or multiple replies canalso be sent + using one or several + <seealso marker="#type-reply_action"><c>reply_action()</c></seealso>s + from a + <seealso marker="#state callback">state callback</seealso>. </p> <note> <p> @@ -1266,7 +1486,9 @@ handle_event(_, _, State, Data) -> <type> <v> CallbackMode = - <seealso marker="#type-callback_mode">callback_mode()</seealso> + <seealso marker="#type-callback_mode">callback_mode()</seealso> | + [ <seealso marker="#type-callback_mode">callback_mode()</seealso> + | <seealso marker="#type-state_enter">state_enter()</seealso> ] </v> </type> <desc> @@ -1278,8 +1500,9 @@ handle_event(_, _, State, Data) -> for efficiency reasons, so this function is only called once after server start and after code change, but before the first - <seealso marker="#state_function">state function</seealso> - is called. More occasions may be added in future versions + <seealso marker="#state callback">state callback</seealso> + in the current code version is called. + More occasions may be added in future versions of <c>gen_statem</c>. </p> <p> @@ -1291,12 +1514,18 @@ handle_event(_, _, State, Data) -> <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso> returns. </p> + <p> + The <c>CallbackMode</c> is either just + <seealso marker="#type-callback_mode"><c>callback_mode()</c></seealso> + or a list containing + <seealso marker="#type-callback_mode"><c>callback_mode()</c></seealso> + and possibly the atom + <seealso marker="#type-state_enter"><c>state_enter</c></seealso>. + </p> <note> <p> - If this function's body does not consist of solely one of two - possible - <seealso marker="#type-callback_mode">atoms</seealso> - the callback module is doing something strange. + If this function's body does not return an inline constant + value the callback module is doing something strange. </p> </note> </desc> @@ -1416,7 +1645,7 @@ handle_event(_, _, State, Data) -> The <seealso marker="#type-action"><c>Actions</c></seealso> are executed when entering the first <seealso marker="#type-state">state</seealso> just as for a - <seealso marker="#state_function">state function</seealso>. + <seealso marker="#state callback">state callback</seealso>. </p> <p> If the initialization fails, @@ -1512,7 +1741,8 @@ handle_event(_, _, State, Data) -> </p> <p> The function is to return <c>Status</c>, a term that - changes the details of the current state and status of + contains the appropriate details + of the current state and status of the <c>gen_statem</c>. There are no restrictions on the form <c>Status</c> can take, but for the <seealso marker="sys#get_status/1"><c>sys:get_status/1,2</c></seealso> @@ -1536,11 +1766,17 @@ handle_event(_, _, State, Data) -> </func> <func> + <name>Module:StateName(enter, OldState, Data) -> + StateEnterResult(StateName) + </name> <name>Module:StateName(EventType, EventContent, Data) -> StateFunctionResult </name> - <name>Module:handle_event(EventType, EventContent, - State, Data) -> HandleEventResult + <name>Module:handle_event(enter, OldState, State, Data) -> + StateEnterResult + </name> + <name>Module:handle_event(EventType, EventContent, State, Data) -> + HandleEventResult </name> <fsummary>Handle an event.</fsummary> <type> @@ -1558,12 +1794,20 @@ handle_event(_, _, State, Data) -> <seealso marker="#type-data">data()</seealso> </v> <v> + StateEnterResult(StateName) = + <seealso marker="#type-state_enter_result">state_enter_result(StateName)</seealso> + </v> + <v> StateFunctionResult = - <seealso marker="#type-state_function_result">state_function_result()</seealso> + <seealso marker="#type-event_handler_result">event_handler_result</seealso>(<seealso marker="#type-state_name">state_name()</seealso>) + </v> + <v> + StateEnterResult = + <seealso marker="#type-state_enter_result">state_enter_result</seealso>(<seealso marker="#type-state">state()</seealso>) </v> <v> HandleEventResult = - <seealso marker="#type-handle_event_result">handle_event_result()</seealso> + <seealso marker="#type-event_handler_result">event_handler_result</seealso>(<seealso marker="#type-state">state()</seealso>) </v> </type> <desc> @@ -1582,7 +1826,7 @@ handle_event(_, _, State, Data) -> <seealso marker="#type-event_type"><c>{call,From}</c></seealso>, the caller waits for a reply. The reply can be sent from this or from any other - <seealso marker="#state_function">state function</seealso> + <seealso marker="#state callback">state callback</seealso> by returning with <c>{reply,From,Reply}</c> in <seealso marker="#type-action"><c>Actions</c></seealso>, in <seealso marker="#type-reply_action"><c>Replies</c></seealso>, @@ -1606,6 +1850,24 @@ handle_event(_, _, State, Data) -> see <seealso marker="#type-action"><c>action()</c></seealso>. </p> <p> + When the <c>gen_statem</c> runs with + <seealso marker="#type-state_enter">state enter calls</seealso>, + these functions are also called with arguments + <c>(enter, OldState, ...)</c> whenever the state changes. + In this case there are some restrictions on the + <seealso marker="#type-enter_action">actions</seealso> + that may be returned: + <seealso marker="#type-postpone"><c>postpone()</c></seealso> + and + <seealso marker="#type-action"><c>{next_event,_,_}</c></seealso> + are not allowed. + You may also not change states from this call. + Should you return <c>{next_state,NextState, ...}</c> + with <c>NextState =/= State</c> the <c>gen_statem</c> crashes. + You are advised to use <c>{keep_state,...}</c> or + <c>keep_state_and_data</c>. + </p> + <p> Note the fact that you can use <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso> to return the result, which can be useful. diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl index 3b3477b282..17d1ebecec 100644 --- a/lib/stdlib/src/gen_statem.erl +++ b/lib/stdlib/src/gen_statem.erl @@ -44,15 +44,20 @@ -export( [wakeup_from_hibernate/3]). -%% Type exports for templates +%% Type exports for templates and callback modules -export_type( [event_type/0, - callback_mode/0, + init_result/0, + callback_mode_result/0, state_function_result/0, handle_event_result/0, + state_enter_result/1, + event_handler_result/1, + reply_action/0, + enter_action/0, action/0]). -%% Fix problem for doc build +%% Type that is exported just to be documented -export_type([transition_option/0]). %%%========================================================================== @@ -63,7 +68,7 @@ {To :: pid(), Tag :: term()}. % Reply-to specifier for call -type state() :: - state_name() | % For StateName/3 callback functios + state_name() | % For StateName/3 callback functions term(). % For handle_event/4 callback function -type state_name() :: atom(). @@ -72,9 +77,12 @@ -type event_type() :: {'call',From :: from()} | 'cast' | - 'info' | 'timeout' | 'internal'. + 'info' | 'timeout' | 'state_timeout' | 'internal'. +-type callback_mode_result() :: + callback_mode() | [callback_mode() | state_enter()]. -type callback_mode() :: 'state_functions' | 'handle_event_function'. +-type state_enter() :: 'state_enter'. -type transition_option() :: postpone() | hibernate() | event_timeout(). @@ -89,6 +97,10 @@ %% Generate a ('timeout', EventContent, ...) event after Time %% unless some other event is delivered Time :: timeout(). +-type state_timeout() :: + %% Generate a ('state_timeout', EventContent, ...) event after Time + %% unless the state is changed + Time :: timeout(). -type action() :: %% During a state change: @@ -108,44 +120,67 @@ 'postpone' | % Set the postpone option {'postpone', Postpone :: postpone()} | %% + %% All 'next_event' events are kept in a list and then + %% inserted at state changes so the first in the + %% action() list is the first to be delivered. + {'next_event', % Insert event as the next to handle + EventType :: event_type(), + EventContent :: term()} | + enter_action(). +-type enter_action() :: 'hibernate' | % Set the hibernate option {'hibernate', Hibernate :: hibernate()} | %% (Timeout :: event_timeout()) | % {timeout,Timeout} - {'timeout', % Set the event timeout option + {'timeout', % Set the event_timeout option Time :: event_timeout(), EventContent :: term()} | + {'state_timeout', % Set the state_timeout option + Time :: state_timeout(), EventContent :: term()} | %% - reply_action() | - %% - %% All 'next_event' events are kept in a list and then - %% inserted at state changes so the first in the - %% action() list is the first to be delivered. - {'next_event', % Insert event as the next to handle - EventType :: event_type(), - EventContent :: term()}. + reply_action(). -type reply_action() :: {'reply', % Reply to a caller From :: from(), Reply :: term()}. +-type init_result() :: + {ok, state(), data()} | + {ok, state(), data(), [action()] | action()} | + 'ignore' | + {'stop', Reason :: term()}. + +%% Old, not advertised -type state_function_result() :: - {'next_state', % {next_state,NextStateName,NewData,[]} - NextStateName :: state_name(), + event_handler_result(state_name()). +-type handle_event_result() :: + event_handler_result(state()). +%% +-type state_enter_result(StateType) :: + {'next_state', % {next_state,NextState,NewData,[]} + State :: StateType, NewData :: data()} | {'next_state', % State transition, maybe to the same state - NextStateName :: state_name(), + State :: StateType, NewData :: data(), - Actions :: [action()] | action()} | - common_state_callback_result(). --type handle_event_result() :: + Actions :: [enter_action()] | enter_action()} | + state_callback_result(enter_action()). +-type event_handler_result(StateType) :: {'next_state', % {next_state,NextState,NewData,[]} - NextState :: state(), + NextState :: StateType, NewData :: data()} | {'next_state', % State transition, maybe to the same state - NextState :: state(), + NextState :: StateType, NewData :: data(), Actions :: [action()] | action()} | - common_state_callback_result(). --type common_state_callback_result() :: + state_callback_result(action()). +-type state_callback_result(ActionType) :: + {'keep_state', % {keep_state,NewData,[]} + NewData :: data()} | + {'keep_state', % Keep state, change data + NewData :: data(), + Actions :: [ActionType] | ActionType} | + 'keep_state_and_data' | % {keep_state_and_data,[]} + {'keep_state_and_data', % Keep state and data -> only actions + Actions :: [ActionType] | ActionType} | 'stop' | % {stop,normal} {'stop', % Stop the server Reason :: term()} | @@ -158,32 +193,20 @@ {'stop_and_reply', % Reply then stop the server Reason :: term(), Replies :: [reply_action()] | reply_action(), - NewData :: data()} | - {'keep_state', % {keep_state,NewData,[]} - NewData :: data()} | - {'keep_state', % Keep state, change data - NewData :: data(), - Actions :: [action()] | action()} | - 'keep_state_and_data' | % {keep_state_and_data,[]} - {'keep_state_and_data', % Keep state and data -> only actions - Actions :: [action()] | action()}. + NewData :: data()}. %% The state machine init function. It is called only once and %% the server is not running until this function has returned %% an {ok, ...} tuple. Thereafter the state callbacks are called %% for all events to this server. --callback init(Args :: term()) -> - {ok, state(), data()} | - {ok, state(), data(), [action()] | action()} | - 'ignore' | - {'stop', Reason :: term()}. +-callback init(Args :: term()) -> init_result(). %% This callback shall return the callback mode of the callback module. %% %% It is called once after init/0 and code_change/4 but before %% the first state callback StateName/3 or handle_event/4. --callback callback_mode() -> callback_mode(). +-callback callback_mode() -> callback_mode_result(). %% Example state callback for StateName = 'state_name' %% when callback_mode() =:= state_functions. @@ -194,19 +217,28 @@ %% StateName/3 callbacks and terminate/3, so the state name %% 'terminate' is unusable in this mode. -callback state_name( - event_type(), + 'enter', + OldStateName :: state_name(), + Data :: data()) -> + state_enter_result('state_name'); + (event_type(), EventContent :: term(), Data :: data()) -> - state_function_result(). + event_handler_result(state_name()). %% %% State callback for all states %% when callback_mode() =:= handle_event_function. -callback handle_event( - event_type(), + 'enter', + OldState :: state(), + State :: state(), % Current state + Data :: data()) -> + state_enter_result(state()); + (event_type(), EventContent :: term(), State :: state(), % Current state Data :: data()) -> - handle_event_result(). + event_handler_result(state()). %% Clean up before the server terminates. -callback terminate( @@ -385,53 +417,79 @@ call(ServerRef, Request) -> -spec call( ServerRef :: server_ref(), Request :: term(), - Timeout :: timeout()) -> + Timeout :: + timeout() | + {'clean_timeout',T :: timeout()} | + {'dirty_timeout',T :: timeout()}) -> Reply :: term(). -call(ServerRef, Request, infinity) -> - try gen:call(ServerRef, '$gen_call', Request, infinity) of - {ok,Reply} -> - Reply - catch - Class:Reason -> - erlang:raise( - Class, - {Reason,{?MODULE,call,[ServerRef,Request,infinity]}}, - erlang:get_stacktrace()) - end; call(ServerRef, Request, Timeout) -> - %% Call server through proxy process to dodge any late reply - Ref = make_ref(), - Self = self(), - Pid = spawn( - fun () -> - Self ! - try gen:call( - ServerRef, '$gen_call', Request, Timeout) of - Result -> - {Ref,Result} - catch Class:Reason -> - {Ref,Class,Reason,erlang:get_stacktrace()} - end - end), - Mref = monitor(process, Pid), - receive - {Ref,Result} -> - demonitor(Mref, [flush]), - case Result of + case parse_timeout(Timeout) of + {dirty_timeout,T} -> + try gen:call(ServerRef, '$gen_call', Request, T) of {ok,Reply} -> Reply + catch + Class:Reason -> + erlang:raise( + Class, + {Reason,{?MODULE,call,[ServerRef,Request,Timeout]}}, + erlang:get_stacktrace()) + end; + {clean_timeout,T} -> + %% Call server through proxy process to dodge any late reply + Ref = make_ref(), + Self = self(), + Pid = spawn( + fun () -> + Self ! + try gen:call( + ServerRef, '$gen_call', Request, T) of + Result -> + {Ref,Result} + catch Class:Reason -> + {Ref,Class,Reason, + erlang:get_stacktrace()} + end + end), + Mref = monitor(process, Pid), + receive + {Ref,Result} -> + demonitor(Mref, [flush]), + case Result of + {ok,Reply} -> + Reply + end; + {Ref,Class,Reason,Stacktrace} -> + demonitor(Mref, [flush]), + erlang:raise( + Class, + {Reason,{?MODULE,call,[ServerRef,Request,Timeout]}}, + Stacktrace); + {'DOWN',Mref,_,_,Reason} -> + %% There is a theoretical possibility that the + %% proxy process gets killed between try--of and ! + %% so this clause is in case of that + exit(Reason) end; - {Ref,Class,Reason,Stacktrace} -> - demonitor(Mref, [flush]), - erlang:raise( - Class, - {Reason,{?MODULE,call,[ServerRef,Request,Timeout]}}, - Stacktrace); - {'DOWN',Mref,_,_,Reason} -> - %% There is a theoretical possibility that the - %% proxy process gets killed between try--of and ! - %% so this clause is in case of that - exit(Reason) + Error when is_atom(Error) -> + erlang:error(Error, [ServerRef,Request,Timeout]) + end. + +parse_timeout(Timeout) -> + case Timeout of + {clean_timeout,infinity} -> + {dirty_timeout,infinity}; + {clean_timeout,_} -> + Timeout; + {dirty_timeout,_} -> + Timeout; + {_,_} -> + %% Be nice and throw a badarg for speling errors + badarg; + infinity -> + {dirty_timeout,infinity}; + T -> + {clean_timeout,T} end. %% Reply from a state machine callback to whom awaits in call/2 @@ -517,8 +575,9 @@ enter(Module, Opts, State, Data, Server, Actions, Parent) -> %% The values should already have been type checked Name = gen:get_proc_name(Server), Debug = gen:debug_options(Name, Opts), - P = Events = [], - Event = {internal,initial_state}, + Events = [], + P = [], + Event = {internal,init_state}, %% We enforce {postpone,false} to ensure that %% our fake Event gets discarded, thought it might get logged NewActions = @@ -530,19 +589,31 @@ enter(Module, Opts, State, Data, Server, Actions, Parent) -> end, S = #{ callback_mode => undefined, + state_enter => false, module => Module, name => Name, - %% All fields below will be replaced according to the arguments to - %% loop_event_actions/10 when it finally loops back to loop/3 state => State, data => Data, postponed => P, - hibernate => false, - timer => undefined}, + %% The rest of the fields are set from to the arguments to + %% loop_event_actions/9 when it finally loops back to loop/3 + %% in loop_events_done/9 + %% + %% Marker for initial state, cleared immediately when used + init_state => true + }, NewDebug = sys_debug(Debug, S, State, {enter,Event,State}), - loop_event_actions( - Parent, NewDebug, S, Events, - State, Data, P, Event, State, NewActions). + case call_callback_mode(S) of + {ok,NewS} -> + StateTimer = undefined, + loop_event_actions( + Parent, NewDebug, NewS, StateTimer, + Events, Event, State, Data, NewActions); + {Class,Reason,Stacktrace} -> + terminate( + Class, Reason, Stacktrace, + NewDebug, S, [Event|Events]) + end. %%%========================================================================== %%% gen callbacks @@ -563,7 +634,9 @@ init_it(Starter, Parent, ServerRef, Module, Args, Opts) -> proc_lib:init_ack(Starter, {error,Reason}), error_info( Class, Reason, Stacktrace, - #{name => Name, callback_mode => undefined}, + #{name => Name, + callback_mode => undefined, + state_enter => false}, [], [], undefined), erlang:raise(Class, Reason, Stacktrace) end. @@ -594,7 +667,9 @@ init_result(Starter, Parent, ServerRef, Module, Result, Opts) -> proc_lib:init_ack(Starter, {error,Error}), error_info( error, Error, ?STACKTRACE(), - #{name => Name, callback_mode => undefined}, + #{name => Name, + callback_mode => undefined, + state_enter => false}, [], [], undefined), exit(Error) end. @@ -605,12 +680,10 @@ init_result(Starter, Parent, ServerRef, Module, Result, Opts) -> system_continue(Parent, Debug, S) -> loop(Parent, Debug, S). -system_terminate( - Reason, _Parent, Debug, - #{state := State, data := Data, postponed := P} = S) -> +system_terminate(Reason, _Parent, Debug, S) -> terminate( exit, Reason, ?STACKTRACE(), - Debug, S, [], State, Data, P). + Debug, S, []). system_code_change( #{module := Module, @@ -647,7 +720,7 @@ system_replace_state( format_status( Opt, [PDict,SysState,Parent,Debug, - #{name := Name, postponed := P, state := State, data := Data} = S]) -> + #{name := Name, postponed := P} = S]) -> Header = gen:format_status_header("Status for state machine", Name), Log = sys:get_debug(log, Debug, []), [{header,Header}, @@ -656,7 +729,7 @@ format_status( {"Parent",Parent}, {"Logged Events",Log}, {"Postponed",P}]} | - case format_status(Opt, PDict, S, State, Data) of + case format_status(Opt, PDict, S) of L when is_list(L) -> L; T -> [T] end]. @@ -732,7 +805,8 @@ loop(Parent, Debug, #{hibernate := Hibernate} = S) -> end. %% Entry point for wakeup_from_hibernate/3 -loop_receive(Parent, Debug, #{timer := Timer} = S) -> +loop_receive( + Parent, Debug, #{timer := Timer, state_timer := StateTimer} = S) -> receive Msg -> case Msg of @@ -743,34 +817,23 @@ loop_receive(Parent, Debug, #{timer := Timer} = S) -> sys:handle_system_msg( Req, Pid, Parent, ?MODULE, Debug, S, Hibernate); {'EXIT',Parent,Reason} = EXIT -> - #{state := State, data := Data, postponed := P} = S, %% EXIT is not a 2-tuple and therefore %% not an event and has no event_type(), %% but this will stand out in the crash report... terminate( - exit, Reason, ?STACKTRACE(), - Debug, S, [EXIT], State, Data, P); - {timeout,Timer,Content} when Timer =/= undefined -> + exit, Reason, ?STACKTRACE(), Debug, S, [EXIT]); + {timeout,Timer,Content} + when Timer =/= undefined -> loop_receive_result( - Parent, Debug, S, {timeout,Content}); + Parent, Debug, S, StateTimer, + {timeout,Content}); + {timeout,StateTimer,Content} + when StateTimer =/= undefined -> + loop_receive_result( + Parent, Debug, S, undefined, + {state_timeout,Content}); _ -> - %% Cancel Timer if running - case Timer of - undefined -> - ok; - _ -> - case erlang:cancel_timer(Timer) of - TimeLeft when is_integer(TimeLeft) -> - ok; - false -> - receive - {timeout,Timer,_} -> - ok - after 0 -> - ok - end - end - end, + cancel_timer(Timer), Event = case Msg of {'$gen_call',From,Request} -> @@ -780,112 +843,185 @@ loop_receive(Parent, Debug, #{timer := Timer} = S) -> _ -> {info,Msg} end, - loop_receive_result(Parent, Debug, S, Event) + loop_receive_result( + Parent, Debug, S, StateTimer, Event) end end. -loop_receive_result( - Parent, Debug, - #{state := State, - data := Data, - postponed := P} = S, - Event) -> - %% The engine state map S is now dismantled - %% and will not be restored until we return to loop/3. - %% - %% The fields 'callback_mode', 'module', and 'name' are still valid. - %% The fields 'state', 'data', and 'postponed' are held in arguments. - %% The fields 'timer' and 'hibernate' will be recalculated. +loop_receive_result(Parent, Debug, #{state := State} = S, StateTimer, Event) -> + %% The fields 'timer', 'state_timer' and 'hibernate' + %% are now invalid in state map S - they will be recalculated + %% and restored when we return to loop/3 %% NewDebug = sys_debug(Debug, S, State, {in,Event}), %% Here the queue of not yet handled events is created Events = [], Hibernate = false, - loop_event( - Parent, NewDebug, S, Events, State, Data, P, Event, Hibernate). + loop_event(Parent, NewDebug, S, StateTimer, Events, Event, Hibernate). %% Process the event queue, or if it is empty %% loop back to loop/3 to receive a new event loop_events( - Parent, Debug, S, [Event|Events], - State, Data, P, Hibernate, _Timeout) -> + Parent, Debug, S, StateTimeout, + [Event|Events], _Timeout, State, Data, P, Hibernate) -> %% - %% If there was a state timer requested we just ignore that + %% If there was an event timer requested we just ignore that %% since we have events to handle which cancels the timer loop_event( - Parent, Debug, S, Events, State, Data, P, Event, Hibernate); + Parent, Debug, S, StateTimeout, + Events, Event, State, Data, P, Hibernate); loop_events( - Parent, Debug, S, [], - State, Data, P, Hibernate, Timeout) -> + Parent, Debug, S, {state_timeout,Time,EventContent}, + [] = Events, Timeout, State, Data, P, Hibernate) -> + if + Time =:= 0 -> + %% Simulate an immediate timeout + %% so we do not get the timeout message + %% after any received event + %% + %% This faked event will cancel + %& any not yet started event timer + Event = {state_timeout,EventContent}, + StateTimer = undefined, + loop_event( + Parent, Debug, S, StateTimer, + Events, Event, State, Data, P, Hibernate); + true -> + StateTimer = erlang:start_timer(Time, self(), EventContent), + loop_events( + Parent, Debug, S, StateTimer, + Events, Timeout, State, Data, P, Hibernate) + end; +loop_events( + Parent, Debug, S, StateTimer, + [] = Events, Timeout, State, Data, P, Hibernate) -> case Timeout of {timeout,0,EventContent} -> - %% Immediate timeout - simulate it + %% Simulate an immediate timeout %% so we do not get the timeout message %% after any received event + %% + Event = {timeout,EventContent}, loop_event( - Parent, Debug, S, [], - State, Data, P, {timeout,EventContent}, Hibernate); + Parent, Debug, S, StateTimer, + Events, Event, State, Data, P, Hibernate); {timeout,Time,EventContent} -> - %% Actually start a timer Timer = erlang:start_timer(Time, self(), EventContent), loop_events_done( - Parent, Debug, S, Timer, State, Data, P, Hibernate); + Parent, Debug, S, StateTimer, + State, Data, P, Hibernate, Timer); undefined -> - %% No state timeout has been requested + %% No event timeout has been requested Timer = undefined, loop_events_done( - Parent, Debug, S, Timer, State, Data, P, Hibernate) + Parent, Debug, S, StateTimer, + State, Data, P, Hibernate, Timer) end. -%% -loop_events_done(Parent, Debug, S, Timer, State, Data, P, Hibernate) -> + +%% Back to the top +loop_events_done( + Parent, Debug, S, StateTimer, + State, Data, P, Hibernate, Timer) -> NewS = S#{ state := State, data := Data, postponed := P, - hibernate := Hibernate, - timer := Timer}, + hibernate => Hibernate, + timer => Timer, + state_timer => StateTimer}, loop(Parent, Debug, NewS). -loop_event( - Parent, Debug, + + +call_callback_mode(#{module := Module} = S) -> + try Module:callback_mode() of + CallbackMode -> + callback_mode_result(S, CallbackMode) + catch + CallbackMode -> + callback_mode_result(S, CallbackMode); + error:undef -> + %% Process undef to check for the simple mistake + %% of calling a nonexistent state function + %% to make the undef more precise + case erlang:get_stacktrace() of + [{Module,callback_mode,[]=Args,_} + |Stacktrace] -> + {error, + {undef_callback,{Module,callback_mode,Args}}, + Stacktrace}; + Stacktrace -> + {error,undef,Stacktrace} + end; + Class:Reason -> + {Class,Reason,erlang:get_stacktrace()} + end. + +callback_mode_result(S, CallbackMode) -> + case + parse_callback_mode( + if + is_atom(CallbackMode) -> + [CallbackMode]; + true -> + CallbackMode + end, undefined, false) + of + {undefined,_} -> + {error, + {bad_return_from_callback_mode,CallbackMode}, + ?STACKTRACE()}; + {CBMode,StateEnter} -> + {ok, + S#{ + callback_mode := CBMode, + state_enter := StateEnter}} + end. + +parse_callback_mode([], CBMode, StateEnter) -> + {CBMode,StateEnter}; +parse_callback_mode([H|T], CBMode, StateEnter) -> + case callback_mode(H) of + true -> + parse_callback_mode(T, H, StateEnter); + false -> + case H of + state_enter -> + parse_callback_mode(T, CBMode, true); + _ -> + {undefined,StateEnter} + end + end; +parse_callback_mode(_, _CBMode, StateEnter) -> + {undefined,StateEnter}. + +call_state_function( + #{callback_mode := undefined} = S, + Type, Content, State, Data) -> + case call_callback_mode(S) of + {ok,NewS} -> + call_state_function(NewS, Type, Content, State, Data); + Error -> + Error + end; +call_state_function( #{callback_mode := CallbackMode, module := Module} = S, - Events, - State, Data, P, {Type,Content} = Event, Hibernate) -> - %% - %% If Hibernate is true here it can only be - %% because it was set from an event action - %% and we did not go into hibernation since there - %% were events in queue, so we do what the user - %% might depend on i.e collect garbage which - %% would have happened if we actually hibernated - %% and immediately was awakened - Hibernate andalso garbage_collect(), - %% + Type, Content, State, Data) -> try case CallbackMode of - undefined -> - Module:callback_mode(); state_functions -> erlang:apply(Module, State, [Type,Content,Data]); handle_event_function -> Module:handle_event(Type, Content, State, Data) end of - Result when CallbackMode =:= undefined -> - loop_event_callback_mode( - Parent, Debug, S, Events, State, Data, P, Event, Result); Result -> - loop_event_result( - Parent, Debug, S, Events, State, Data, P, Event, Result) + {ok,Result,S} catch - Result when CallbackMode =:= undefined -> - loop_event_callback_mode( - Parent, Debug, S, Events, State, Data, P, Event, Result); Result -> - loop_event_result( - Parent, Debug, S, Events, State, Data, P, Event, Result); + {ok,Result,S}; error:badarg -> case erlang:get_stacktrace() of [{erlang,apply, @@ -895,329 +1031,425 @@ loop_event( when CallbackMode =:= state_functions -> %% We get here e.g if apply fails %% due to State not being an atom - terminate( - error, - {undef_state_function,{Module,State,Args}}, - Stacktrace, - Debug, S, [Event|Events], State, Data, P); + {error, + {undef_state_function,{Module,State,Args}}, + Stacktrace}; Stacktrace -> - terminate( - error, badarg, Stacktrace, - Debug, S, [Event|Events], State, Data, P) + {error,badarg,Stacktrace} end; error:undef -> %% Process undef to check for the simple mistake %% of calling a nonexistent state function %% to make the undef more precise case erlang:get_stacktrace() of - [{Module,callback_mode,[]=Args,_} - |Stacktrace] - when CallbackMode =:= undefined -> - terminate( - error, - {undef_callback,{Module,callback_mode,Args}}, - Stacktrace, - Debug, S, [Event|Events], State, Data, P); [{Module,State,[Type,Content,Data]=Args,_} |Stacktrace] when CallbackMode =:= state_functions -> - terminate( - error, - {undef_state_function,{Module,State,Args}}, - Stacktrace, - Debug, S, [Event|Events], State, Data, P); + {error, + {undef_state_function,{Module,State,Args}}, + Stacktrace}; [{Module,handle_event,[Type,Content,State,Data]=Args,_} |Stacktrace] when CallbackMode =:= handle_event_function -> - terminate( - error, - {undef_state_function,{Module,handle_event,Args}}, - Stacktrace, - Debug, S, [Event|Events], State, Data, P); + {error, + {undef_state_function,{Module,handle_event,Args}}, + Stacktrace}; Stacktrace -> - terminate( - error, undef, Stacktrace, - Debug, S, [Event|Events], State, Data, P) + {error,undef,Stacktrace} end; Class:Reason -> - Stacktrace = erlang:get_stacktrace(), - terminate( - Class, Reason, Stacktrace, - Debug, S, [Event|Events], State, Data, P) + {Class,Reason,erlang:get_stacktrace()} end. -%% Interpret callback_mode() result -loop_event_callback_mode( - Parent, Debug, S, Events, State, Data, P, Event, CallbackMode) -> - case callback_mode(CallbackMode) of - true -> - Hibernate = false, % We have already GC:ed recently - loop_event( - Parent, Debug, - S#{callback_mode := CallbackMode}, - Events, - State, Data, P, Event, Hibernate); - false -> +%% Update S and continue +loop_event( + Parent, Debug, S, StateTimer, + Events, Event, State, Data, P, Hibernate) -> + NewS = + S#{ + state := State, + data := Data, + postponed := P}, + loop_event(Parent, Debug, NewS, StateTimer, Events, Event, Hibernate). + +loop_event( + Parent, Debug, #{state := State, data := Data} = S, StateTimer, + Events, {Type,Content} = Event, Hibernate) -> + %% + %% If Hibernate is true here it can only be + %% because it was set from an event action + %% and we did not go into hibernation since there + %% were events in queue, so we do what the user + %% might rely on i.e collect garbage which + %% would have happened if we actually hibernated + %% and immediately was awakened + Hibernate andalso garbage_collect(), + case call_state_function(S, Type, Content, State, Data) of + {ok,Result,NewS} -> + {NewData,NextState,Actions} = + parse_event_result( + true, Debug, NewS, Result, + Events, Event, State, Data), + loop_event_actions( + Parent, Debug, S, StateTimer, + Events, Event, NextState, NewData, Actions); + {Class,Reason,Stacktrace} -> terminate( - error, - {bad_return_from_callback_mode,CallbackMode}, - ?STACKTRACE(), - Debug, S, [Event|Events], State, Data, P) + Class, Reason, Stacktrace, Debug, S, [Event|Events]) end. %% Interpret all callback return variants -loop_event_result( - Parent, Debug, S, Events, State, Data, P, Event, Result) -> +parse_event_result( + AllowStateChange, Debug, S, Result, Events, Event, State, Data) -> case Result of stop -> terminate( - exit, normal, ?STACKTRACE(), - Debug, S, [Event|Events], State, Data, P); + exit, normal, ?STACKTRACE(), Debug, S, [Event|Events]); {stop,Reason} -> terminate( - exit, Reason, ?STACKTRACE(), - Debug, S, [Event|Events], State, Data, P); + exit, Reason, ?STACKTRACE(), Debug, S, [Event|Events]); {stop,Reason,NewData} -> terminate( exit, Reason, ?STACKTRACE(), - Debug, S, [Event|Events], State, NewData, P); + Debug, S#{data := NewData}, [Event|Events]); {stop_and_reply,Reason,Replies} -> Q = [Event|Events], reply_then_terminate( exit, Reason, ?STACKTRACE(), - Debug, S, Q, State, Data, P, Replies); + Debug, S, Q, Replies); {stop_and_reply,Reason,Replies,NewData} -> Q = [Event|Events], reply_then_terminate( exit, Reason, ?STACKTRACE(), - Debug, S, Q, State, NewData, P, Replies); - {next_state,NextState,NewData} -> - loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P, Event, NextState, []); - {next_state,NextState,NewData,Actions} -> - loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P, Event, NextState, Actions); + Debug, S#{data := NewData}, Q, Replies); + {next_state,State,NewData} -> + {NewData,State,[]}; + {next_state,NextState,NewData} when AllowStateChange -> + {NewData,NextState,[]}; + {next_state,State,NewData,Actions} -> + {NewData,State,Actions}; + {next_state,NextState,NewData,Actions} when AllowStateChange -> + {NewData,NextState,Actions}; {keep_state,NewData} -> - loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P, Event, State, []); + {NewData,State,[]}; {keep_state,NewData,Actions} -> - loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P, Event, State, Actions); + {NewData,State,Actions}; keep_state_and_data -> - loop_event_actions( - Parent, Debug, S, Events, - State, Data, P, Event, State, []); + {Data,State,[]}; {keep_state_and_data,Actions} -> - loop_event_actions( - Parent, Debug, S, Events, - State, Data, P, Event, State, Actions); + {Data,State,Actions}; _ -> terminate( error, {bad_return_from_state_function,Result}, ?STACKTRACE(), - Debug, S, [Event|Events], State, Data, P) + Debug, S, [Event|Events]) end. -loop_event_actions( - Parent, Debug, S, Events, State, NewData, P, Event, NextState, Actions) -> - Postpone = false, % Shall we postpone this event; boolean() +parse_enter_actions( + Debug, S, State, Actions, + Hibernate, Timeout, StateTimeout) -> + Postpone = forbidden, + NextEvents = forbidden, + parse_actions( + Debug, S, State, listify(Actions), + Hibernate, Timeout, StateTimeout, Postpone, NextEvents). + +parse_actions(Debug, S, State, Actions) -> Hibernate = false, Timeout = undefined, + StateTimeout = undefined, + Postpone = false, NextEvents = [], - loop_event_actions( - Parent, Debug, S, Events, State, NewData, P, Event, NextState, - if - is_list(Actions) -> - Actions; - true -> - [Actions] - end, - Postpone, Hibernate, Timeout, NextEvents). + parse_actions( + Debug, S, State, listify(Actions), + Hibernate, Timeout, StateTimeout, Postpone, NextEvents). %% -%% Process all actions -loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P, Event, NextState, [Action|Actions], - Postpone, Hibernate, Timeout, NextEvents) -> +parse_actions( + Debug, _S, _State, [], + Hibernate, Timeout, StateTimeout, Postpone, NextEvents) -> + {ok,Debug,Hibernate,Timeout,StateTimeout,Postpone,NextEvents}; +parse_actions( + Debug, S, State, [Action|Actions], + Hibernate, Timeout, StateTimeout, Postpone, NextEvents) -> case Action of %% Actual actions {reply,From,Reply} -> case from(From) of true -> NewDebug = do_reply(Debug, S, State, From, Reply), - loop_event_actions( - Parent, NewDebug, S, Events, - State, NewData, P, Event, NextState, Actions, - Postpone, Hibernate, Timeout, NextEvents); + parse_actions( + NewDebug, S, State, Actions, + Hibernate, Timeout, StateTimeout, + Postpone, NextEvents); false -> - terminate( - error, - {bad_action_from_state_function,Action}, - ?STACKTRACE(), - Debug, S, [Event|Events], State, NewData, P) - end; - {next_event,Type,Content} -> - case event_type(Type) of - true -> - NewDebug = - sys_debug(Debug, S, State, {in,{Type,Content}}), - loop_event_actions( - Parent, NewDebug, S, Events, - State, NewData, P, Event, NextState, Actions, - Postpone, Hibernate, Timeout, - [{Type,Content}|NextEvents]); - false -> - terminate( - error, - {bad_action_from_state_function,Action}, - ?STACKTRACE(), - Debug, S, [Event|Events], State, NewData, P) + {error, + {bad_action_from_state_function,Action}, + ?STACKTRACE()} end; %% Actions that set options - {postpone,NewPostpone} when is_boolean(NewPostpone) -> - loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P, Event, NextState, Actions, - NewPostpone, Hibernate, Timeout, NextEvents); - {postpone,_} -> - terminate( - error, - {bad_action_from_state_function,Action}, - ?STACKTRACE(), - Debug, S, [Event|Events], State, NewData, P); - postpone -> - loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P, Event, NextState, Actions, - true, Hibernate, Timeout, NextEvents); {hibernate,NewHibernate} when is_boolean(NewHibernate) -> - loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P, Event, NextState, Actions, - Postpone, NewHibernate, Timeout, NextEvents); + parse_actions( + Debug, S, State, Actions, + NewHibernate, Timeout, StateTimeout, Postpone, NextEvents); {hibernate,_} -> - terminate( - error, - {bad_action_from_state_function,Action}, - ?STACKTRACE(), - Debug, S, [Event|Events], State, NewData, P); + {error, + {bad_action_from_state_function,Action}, + ?STACKTRACE()}; hibernate -> - loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P, Event, NextState, Actions, - Postpone, true, Timeout, NextEvents); + parse_actions( + Debug, S, State, Actions, + true, Timeout, StateTimeout, Postpone, NextEvents); + {state_timeout,Time,_} = NewStateTimeout + when is_integer(Time), Time >= 0; + Time =:= infinity -> + parse_actions( + Debug, S, State, Actions, + Hibernate, Timeout, NewStateTimeout, Postpone, NextEvents); + {state_timeout,_,_} -> + {error, + {bad_action_from_state_function,Action}, + ?STACKTRACE()}; {timeout,infinity,_} -> % Clear timer - it will never trigger - loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P, Event, NextState, Actions, - Postpone, Hibernate, undefined, NextEvents); + parse_actions( + Debug, S, State, Actions, + Hibernate, undefined, StateTimeout, Postpone, NextEvents); {timeout,Time,_} = NewTimeout when is_integer(Time), Time >= 0 -> - loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P, Event, NextState, Actions, - Postpone, Hibernate, NewTimeout, NextEvents); + parse_actions( + Debug, S, State, Actions, + Hibernate, NewTimeout, StateTimeout, Postpone, NextEvents); {timeout,_,_} -> - terminate( - error, - {bad_action_from_state_function,Action}, - ?STACKTRACE(), - Debug, S, [Event|Events], State, NewData, P); + {error, + {bad_action_from_state_function,Action}, + ?STACKTRACE()}; infinity -> % Clear timer - it will never trigger - loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P, Event, NextState, Actions, - Postpone, Hibernate, undefined, NextEvents); + parse_actions( + Debug, S, State, Actions, + Hibernate, undefined, StateTimeout, Postpone, NextEvents); Time when is_integer(Time), Time >= 0 -> NewTimeout = {timeout,Time,Time}, - loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P, Event, NextState, Actions, - Postpone, Hibernate, NewTimeout, NextEvents); + parse_actions( + Debug, S, State, Actions, + Hibernate, NewTimeout, StateTimeout, Postpone, NextEvents); + {postpone,NewPostpone} + when is_boolean(NewPostpone), Postpone =/= forbidden -> + parse_actions( + Debug, S, State, Actions, + Hibernate, Timeout, StateTimeout, NewPostpone, NextEvents); + {postpone,_} -> + {error, + {bad_action_from_state_function,Action}, + ?STACKTRACE()}; + postpone when Postpone =/= forbidden -> + parse_actions( + Debug, S, State, Actions, + Hibernate, Timeout, StateTimeout, true, NextEvents); + {next_event,Type,Content} -> + case event_type(Type) of + true when NextEvents =/= forbidden -> + NewDebug = + sys_debug(Debug, S, State, {in,{Type,Content}}), + parse_actions( + NewDebug, S, State, Actions, + Hibernate, Timeout, StateTimeout, + Postpone, [{Type,Content}|NextEvents]); + _ -> + {error, + {bad_action_from_state_function,Action}, + ?STACKTRACE()} + end; _ -> - terminate( - error, - {bad_action_from_state_function,Action}, - ?STACKTRACE(), - Debug, S, [Event|Events], State, NewData, P) - end; -%% -%% End of actions list + {error, + {bad_action_from_state_function,Action}, + ?STACKTRACE()} + end. + loop_event_actions( - Parent, Debug, S, Events, - State, NewData, P0, Event, NextState, [], - Postpone, Hibernate, Timeout, NextEvents) -> + Parent, Debug, + #{state := State, state_enter := StateEnter} = S, StateTimer, + Events, Event, NextState, NewData, Actions) -> + case parse_actions(Debug, S, State, Actions) of + {ok,NewDebug,Hibernate,Timeout,StateTimeout,Postpone,NextEvents} -> + if + StateEnter, NextState =/= State -> + loop_event_enter( + Parent, NewDebug, S, StateTimer, + Events, Event, NextState, NewData, + Hibernate, Timeout, StateTimeout, Postpone, NextEvents); + StateEnter -> + case maps:is_key(init_state, S) of + true -> + %% Avoid infinite loop in initial state + %% with state entry events + NewS = maps:remove(init_state, S), + loop_event_enter( + Parent, NewDebug, NewS, StateTimer, + Events, Event, NextState, NewData, + Hibernate, Timeout, StateTimeout, + Postpone, NextEvents); + false -> + loop_event_result( + Parent, NewDebug, S, StateTimer, + Events, Event, NextState, NewData, + Hibernate, Timeout, StateTimeout, + Postpone, NextEvents) + end; + true -> + loop_event_result( + Parent, NewDebug, S, StateTimer, + Events, Event, NextState, NewData, + Hibernate, Timeout, StateTimeout, Postpone, NextEvents) + end; + {Class,Reason,Stacktrace} -> + terminate( + Class, Reason, Stacktrace, + Debug, S#{data := NewData}, [Event|Events]) + end. + +loop_event_enter( + Parent, Debug, #{state := State} = S, StateTimer, + Events, Event, NextState, NewData, + Hibernate, Timeout, StateTimeout, Postpone, NextEvents) -> + case call_state_function(S, enter, State, NextState, NewData) of + {ok,Result,NewS} -> + {NewerData,_,Actions} = + parse_event_result( + false, Debug, NewS, Result, + Events, Event, NextState, NewData), + loop_event_enter_actions( + Parent, Debug, NewS, StateTimer, + Events, Event, NextState, NewerData, + Hibernate, Timeout, StateTimeout, Postpone, NextEvents, Actions); + {Class,Reason,Stacktrace} -> + terminate( + Class, Reason, Stacktrace, + Debug, S#{state := NextState, data := NewData}, + [Event|Events]) + end. + +loop_event_enter_actions( + Parent, Debug, S, StateTimer, + Events, Event, NextState, NewData, + Hibernate, Timeout, StateTimeout, Postpone, NextEvents, Actions) -> + case + parse_enter_actions( + Debug, S, NextState, Actions, + Hibernate, Timeout, StateTimeout) + of + {ok,NewDebug,NewHibernate,NewTimeout,NewStateTimeout,_,_} -> + loop_event_result( + Parent, NewDebug, S, StateTimer, + Events, Event, NextState, NewData, + NewHibernate, NewTimeout, NewStateTimeout, Postpone, NextEvents); + {Class,Reason,Stacktrace} -> + terminate( + Class, Reason, Stacktrace, + Debug, S#{state := NextState, data := NewData}, + [Event|Events]) + end. + +loop_event_result( + Parent, Debug, + #{state := State, postponed := P_0} = S, StateTimer, + Events, Event, NextState, NewData, + Hibernate, Timeout, StateTimeout, Postpone, NextEvents) -> %% %% All options have been collected and next_events are buffered. %% Do the actual state transition. %% - P1 = % Move current event to postponed if Postpone + NewStateTimeout = + case StateTimeout of + {state_timeout,Time,_} -> + %% New timeout -> cancel timer + case StateTimer of + {state_timeout,_,_} -> + ok; + _ -> + cancel_timer(StateTimer) + end, + case Time of + infinity -> + undefined; + _ -> + StateTimeout + end; + undefined when NextState =/= State -> + %% State change -> cancel timer + case StateTimer of + {state_timeout,_,_} -> + ok; + _ -> + cancel_timer(StateTimer) + end, + undefined; + undefined -> + StateTimer + end, + %% + P_1 = % Move current event to postponed if Postpone case Postpone of true -> - [Event|P0]; + [Event|P_0]; false -> - P0 + P_0 end, - {Q2,P} = % Move all postponed events to queue if state change + {Events_1,NewP} = % Move all postponed events to queue if state change if NextState =:= State -> - {Events,P1}; + {Events,P_1}; true -> - {lists:reverse(P1, Events),[]} + {lists:reverse(P_1, Events),[]} end, %% Place next events first in queue - Q = lists:reverse(NextEvents, Q2), + NewEvents = lists:reverse(NextEvents, Events_1), %% NewDebug = sys_debug( Debug, S, State, case Postpone of true -> - {postpone,Event,NextState}; + {postpone,Event,State}; false -> - {consume,Event,NextState} + {consume,Event,State} end), + %% loop_events( - Parent, NewDebug, S, Q, NextState, NewData, P, Hibernate, Timeout). + Parent, NewDebug, S, NewStateTimeout, + NewEvents, Timeout, NextState, NewData, NewP, Hibernate). %%--------------------------------------------------------------------------- %% Server helpers reply_then_terminate( Class, Reason, Stacktrace, - Debug, S, Q, State, Data, P, Replies) -> + Debug, #{state := State} = S, Q, Replies) -> if is_list(Replies) -> do_reply_then_terminate( Class, Reason, Stacktrace, - Debug, S, Q, State, Data, P, Replies); + Debug, S, Q, Replies, State); true -> do_reply_then_terminate( Class, Reason, Stacktrace, - Debug, S, Q, State, Data, P, [Replies]) + Debug, S, Q, [Replies], State) end. %% do_reply_then_terminate( - Class, Reason, Stacktrace, Debug, S, Q, State, Data, P, []) -> - terminate(Class, Reason, Stacktrace, Debug, S, Q, State, Data, P); + Class, Reason, Stacktrace, Debug, S, Q, [], _State) -> + terminate(Class, Reason, Stacktrace, Debug, S, Q); do_reply_then_terminate( - Class, Reason, Stacktrace, Debug, S, Q, State, Data, P, [R|Rs]) -> + Class, Reason, Stacktrace, Debug, S, Q, [R|Rs], State) -> case R of {reply,{_To,_Tag}=From,Reply} -> NewDebug = do_reply(Debug, S, State, From, Reply), do_reply_then_terminate( - Class, Reason, Stacktrace, - NewDebug, S, Q, State, Data, P, Rs); + Class, Reason, Stacktrace, NewDebug, S, Q, Rs, State); _ -> terminate( error, {bad_reply_action_from_state_function,R}, ?STACKTRACE(), - Debug, S, Q, State, Data, P) + Debug, S, Q) end. do_reply(Debug, S, State, From, Reply) -> @@ -1227,7 +1459,9 @@ do_reply(Debug, S, State, From, Reply) -> terminate( Class, Reason, Stacktrace, - Debug, #{module := Module} = S, Q, State, Data, P) -> + Debug, + #{module := Module, state := State, data := Data, postponed := P} = S, + Q) -> try Module:terminate(Reason, State, Data) of _ -> ok catch @@ -1236,7 +1470,7 @@ terminate( ST = erlang:get_stacktrace(), error_info( C, R, ST, S, Q, P, - format_status(terminate, get(), S, State, Data)), + format_status(terminate, get(), S)), sys:print_log(Debug), erlang:raise(C, R, ST) end, @@ -1247,7 +1481,7 @@ terminate( _ -> error_info( Class, Reason, Stacktrace, S, Q, P, - format_status(terminate, get(), S, State, Data)), + format_status(terminate, get(), S)), sys:print_log(Debug) end, case Stacktrace of @@ -1259,7 +1493,9 @@ terminate( error_info( Class, Reason, Stacktrace, - #{name := Name, callback_mode := CallbackMode}, + #{name := Name, + callback_mode := CallbackMode, + state_enter := StateEnter}, Q, P, FmtData) -> {FixedReason,FixedStacktrace} = case Stacktrace of @@ -1286,6 +1522,13 @@ error_info( end; _ -> {Reason,Stacktrace} end, + CBMode = + case StateEnter of + true -> + [CallbackMode,state_enter]; + false -> + CallbackMode + end, error_logger:format( "** State machine ~p terminating~n" ++ case Q of @@ -1312,8 +1555,9 @@ error_info( [] -> []; [Event|_] -> [Event] end] ++ - [FmtData,Class,FixedReason, - CallbackMode] ++ + [FmtData, + Class,FixedReason, + CBMode] ++ case Q of [_|[_|_] = Events] -> [Events]; _ -> [] @@ -1329,7 +1573,9 @@ error_info( %% Call Module:format_status/2 or return a default value -format_status(Opt, PDict, #{module := Module}, State, Data) -> +format_status( + Opt, PDict, + #{module := Module, state := State, data := Data}) -> case erlang:function_exported(Module, format_status, 2) of true -> try Module:format_status(Opt, [PDict,State,Data]) @@ -1353,3 +1599,24 @@ format_status_default(Opt, State, Data) -> _ -> [{data,[{"State",StateData}]}] end. + +listify(Item) when is_list(Item) -> + Item; +listify(Item) -> + [Item]. + +cancel_timer(undefined) -> + ok; +cancel_timer(TRef) -> + case erlang:cancel_timer(TRef) of + false -> + %% We have to assume that TRef is the ref of a running timer + %% and if so the timer has expired + %% hence we must wait for the timeout message + receive + {timeout,TRef,_} -> + ok + end; + _TimeLeft -> + ok + end. diff --git a/lib/stdlib/src/ms_transform.erl b/lib/stdlib/src/ms_transform.erl index c0eea652e7..98745b13f3 100644 --- a/lib/stdlib/src/ms_transform.erl +++ b/lib/stdlib/src/ms_transform.erl @@ -451,6 +451,8 @@ check_type(_,[{record,_,_,_}],ets) -> ok; check_type(_,[{cons,_,_,_}],dbg) -> ok; +check_type(_,[{nil,_}],dbg) -> + ok; check_type(Line0,[{match,_,{var,_,_},X}],Any) -> check_type(Line0,[X],Any); check_type(Line0,[{match,_,X,{var,_,_}}],Any) -> diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl index 1d1417c2e6..28f9ab81fe 100644 --- a/lib/stdlib/test/gen_statem_SUITE.erl +++ b/lib/stdlib/test/gen_statem_SUITE.erl @@ -37,7 +37,8 @@ all() -> {group, stop_handle_event}, {group, abnormal}, {group, abnormal_handle_event}, - shutdown, stop_and_reply, event_order, code_change, + shutdown, stop_and_reply, state_enter, event_order, + state_timeout, code_change, {group, sys}, hibernate, enter_loop]. @@ -57,7 +58,7 @@ tcs(start) -> tcs(stop) -> [stop1, stop2, stop3, stop4, stop5, stop6, stop7, stop8, stop9, stop10]; tcs(abnormal) -> - [abnormal1, abnormal2]; + [abnormal1, abnormal1clean, abnormal1dirty, abnormal2]; tcs(sys) -> [sys1, call_format_status, error_format_status, terminate_crash_format, @@ -451,8 +452,52 @@ abnormal1(Config) -> gen_statem:call(Name, {delayed_answer,1000}, 10), Reason), ok = gen_statem:stop(Name), + ?t:sleep(1100), ok = verify_empty_msgq(). +%% Check that time outs in calls work +abnormal1clean(Config) -> + Name = abnormal1clean, + LocalSTM = {local,Name}, + + {ok, _Pid} = + gen_statem:start(LocalSTM, ?MODULE, start_arg(Config, []), []), + + %% timeout call. + delayed = + gen_statem:call(Name, {delayed_answer,1}, {clean_timeout,100}), + {timeout,_} = + ?EXPECT_FAILURE( + gen_statem:call( + Name, {delayed_answer,1000}, {clean_timeout,10}), + Reason), + ok = gen_statem:stop(Name), + ?t:sleep(1100), + ok = verify_empty_msgq(). + +%% Check that time outs in calls work +abnormal1dirty(Config) -> + Name = abnormal1dirty, + LocalSTM = {local,Name}, + + {ok, _Pid} = + gen_statem:start(LocalSTM, ?MODULE, start_arg(Config, []), []), + + %% timeout call. + delayed = + gen_statem:call(Name, {delayed_answer,1}, {dirty_timeout,100}), + {timeout,_} = + ?EXPECT_FAILURE( + gen_statem:call( + Name, {delayed_answer,1000}, {dirty_timeout,10}), + Reason), + ok = gen_statem:stop(Name), + ?t:sleep(1100), + case flush() of + [{Ref,delayed}] when is_reference(Ref) -> + ok + end. + %% Check that bad return values makes the stm crash. Note that we must %% trap exit since we must link to get the real bad_return_ error abnormal2(Config) -> @@ -512,7 +557,8 @@ stop_and_reply(_Config) -> {stop_and_reply,Reason, [R1,{reply,From2,Reply2}]} end}, - {ok,STM} = gen_statem:start_link(?MODULE, {map_statem,Machine}, []), + {ok,STM} = + gen_statem:start_link(?MODULE, {map_statem,Machine,[]}, []), Self = self(), Tag1 = make_ref(), @@ -537,6 +583,61 @@ stop_and_reply(_Config) -> +state_enter(_Config) -> + process_flag(trap_exit, true), + Self = self(), + + Machine = + %% Abusing the internal format of From... + #{init => + fun () -> + {ok,start,1} + end, + start => + fun (enter, Prev, N) -> + Self ! {enter,start,Prev,N}, + {keep_state,N + 1}; + (internal, Prev, N) -> + Self ! {internal,start,Prev,N}, + {keep_state,N + 1}; + ({call,From}, echo, N) -> + {next_state,wait,N + 1,{reply,From,{echo,start,N}}}; + ({call,From}, {stop,Reason}, N) -> + {stop_and_reply,Reason,[{reply,From,{stop,N}}],N + 1} + end, + wait => + fun (enter, Prev, N) -> + Self ! {enter,wait,Prev,N}, + {keep_state,N + 1}; + ({call,From}, echo, N) -> + {next_state,start,N + 1, + [{next_event,internal,wait}, + {reply,From,{echo,wait,N}}]} + end}, + {ok,STM} = + gen_statem:start_link( + ?MODULE, {map_statem,Machine,[state_enter]}, []), + + [{enter,start,start,1}] = flush(), + {echo,start,2} = gen_statem:call(STM, echo), + [{enter,wait,start,3}] = flush(), + {wait,[4|_]} = sys:get_state(STM), + {echo,wait,4} = gen_statem:call(STM, echo), + [{enter,start,wait,5},{internal,start,wait,6}] = flush(), + {stop,7} = gen_statem:call(STM, {stop,bye}), + [{'EXIT',STM,bye}] = flush(), + + {noproc,_} = + ?EXPECT_FAILURE(gen_statem:call(STM, hej), Reason), + case flush() of + [] -> + ok; + Other2 -> + ct:fail({unexpected,Other2}) + end. + + + event_order(_Config) -> process_flag(trap_exit, true), @@ -579,7 +680,7 @@ event_order(_Config) -> Result end}, - {ok,STM} = gen_statem:start_link(?MODULE, {map_statem,Machine}, []), + {ok,STM} = gen_statem:start_link(?MODULE, {map_statem,Machine,[]}, []), Self = self(), Tag1 = make_ref(), gen_statem:cast(STM, {reply,{Self,Tag1},ok1}), @@ -609,6 +710,83 @@ event_order(_Config) -> +state_timeout(_Config) -> + process_flag(trap_exit, true), + + Machine = + #{init => + fun () -> + {ok,start,0} + end, + start => + fun + ({call,From}, {go,Time}, 0) -> + self() ! message_to_self, + {next_state, state1, {Time,From}, + %% Verify that internal events goes before external + [{state_timeout,Time,1}, + {next_event,internal,1}]} + end, + state1 => + fun + (internal, 1, Data) -> + %% Verify that a state change cancels timeout 1 + {next_state, state2, Data, + [{timeout,0,2}, + {state_timeout,0,2}, + {next_event,internal,2}]} + end, + state2 => + fun + (internal, 2, Data) -> + %% Verify that {state_timeout,0,_} + %% comes after next_event and that + %% {timeout,0,_} is cancelled by + %% {state_timeout,0,_} + {keep_state, {ok,2,Data}, + [{timeout,0,3}]}; + (state_timeout, 2, {ok,2,{Time,From}}) -> + {next_state, state3, 3, + [{reply,From,ok}, + {state_timeout,Time,3}]} + end, + state3 => + fun + (info, message_to_self, 3) -> + {keep_state, '3'}; + ({call,From}, check, '3') -> + {keep_state, From}; + (state_timeout, 3, From) -> + {stop_and_reply, normal, + {reply,From,ok}} + end}, + + {ok,STM} = gen_statem:start_link(?MODULE, {map_statem,Machine,[]}, []), + TRef = erlang:start_timer(1000, self(), kull), + ok = gen_statem:call(STM, {go,500}), + ok = gen_statem:call(STM, check), + receive + {timeout,TRef,kull} -> + ct:fail(late_timeout) + after 0 -> + receive + {timeout,TRef,kull} -> + ok + after 1000 -> + ct:fail(no_check_timeout) + end + end, + receive + {'EXIT',STM,normal} -> + ok + after 500 -> + ct:fail(did_not_stop) + end, + + verify_empty_msgq(). + + + sys1(Config) -> {ok,Pid} = gen_statem:start(?MODULE, start_arg(Config, []), []), {status, Pid, {module,gen_statem}, _} = sys:get_status(Pid), @@ -1271,9 +1449,9 @@ init({callback_mode,CallbackMode,Arg}) -> ets:new(?MODULE, [named_table,private]), ets:insert(?MODULE, {callback_mode,CallbackMode}), init(Arg); -init({map_statem,#{init := Init}=Machine}) -> +init({map_statem,#{init := Init}=Machine,Modes}) -> ets:new(?MODULE, [named_table,private]), - ets:insert(?MODULE, {callback_mode,handle_event_function}), + ets:insert(?MODULE, {callback_mode,[handle_event_function|Modes]}), case Init() of {ok,State,Data,Ops} -> {ok,State,[Data|Machine],Ops}; diff --git a/lib/stdlib/test/ms_transform_SUITE.erl b/lib/stdlib/test/ms_transform_SUITE.erl index 1c5faa960b..f35013b1b2 100644 --- a/lib/stdlib/test/ms_transform_SUITE.erl +++ b/lib/stdlib/test/ms_transform_SUITE.erl @@ -296,6 +296,8 @@ basic_dbg(Config) when is_list(Config) -> compile_and_run(<<"dbg:fun2ms(fun([A,B]) -> bindings() end)">>), [{['$1','$2'],[],['$_']}] = compile_and_run(<<"dbg:fun2ms(fun([A,B]) -> object() end)">>), + [{[],[],[{return_trace}]}] = + compile_and_run(<<"dbg:fun2ms(fun([]) -> return_trace() end)">>), ok. %% Test calling of ets/dbg:fun2ms from the shell. diff --git a/lib/tools/emacs/erlang-skels.el b/lib/tools/emacs/erlang-skels.el index 0284c9d686..eeba7f34e9 100644 --- a/lib/tools/emacs/erlang-skels.el +++ b/lib/tools/emacs/erlang-skels.el @@ -904,7 +904,7 @@ Please see the function `tempo-define-template'.") "%% @doc" n "%% Define the callback_mode() for this callback module." n (erlang-skel-separator-end 2) - "-spec callback_mode() -> gen_statem:callback_mode()." n + "-spec callback_mode() -> gen_statem:callback_mode_result()." n "callback_mode() -> state_functions." n n (erlang-skel-separator-start 2) @@ -931,14 +931,16 @@ Please see the function `tempo-define-template'.") "%% Whenever a gen_statem receives an event, the function " n "%% with the name of the current state (StateName) " n "%% is called to handle the event." n - "%%" n - "%% NOTE: If there is an exported function handle_event/4, it is called" n - "%% instead of StateName/3 functions like this!" n (erlang-skel-separator-end 2) - "-spec state_name(" n> - "gen_statem:event_type(), Msg :: term()," n> + "-spec state_name('enter'," n> + "OldState :: atom()," n> + "Data :: term()) ->" n> + "gen_statem:state_enter_result('state_name');" n> + "(gen_statem:event_type()," n> + "Msg :: term()," n> "Data :: term()) ->" n> - "gen_statem:state_function_result()." n + "gen_statem:event_handler_result(atom())." n + ;; "state_name({call,Caller}, _Msg, Data) ->" n> "{next_state, state_name, Data, [{reply,Caller,ok}]}." n n @@ -1015,7 +1017,7 @@ Please see the function `tempo-define-template'.") "%% @doc" n "%% Define the callback_mode() for this callback module." n (erlang-skel-separator-end 2) - "-spec callback_mode() -> gen_statem:callback_mode()." n + "-spec callback_mode() -> gen_statem:callback_mode_result()." n "callback_mode() -> handle_event_function." n n (erlang-skel-separator-start 2) @@ -1039,14 +1041,18 @@ Please see the function `tempo-define-template'.") "%% @private" n "%% @doc" n "%% This function is called for every event a gen_statem receives." n - "%%" n - "%% NOTE: If there is no exported function handle_event/4," n - "%% StateName/3 functions are called instead!" n (erlang-skel-separator-end 2) - "-spec handle_event(" n> - "gen_statem:event_type(), Msg :: term()," n> - "State :: term(), Data :: term()) ->" n> - "gen_statem:handle_event_result()." n + "-spec handle_event('enter'," n> + "OldState :: term()," n> + "State :: term()," n> + "Data :: term()) ->" n> + "gen_statem:state_enter_result(term());" n> + "(gen_statem:event_type()," n> + "Msg :: term()," n> + "State :: term()," n> + "Data :: term()) ->" n> + "gen_statem:event_handler_result(term())." n + ;; "handle_event({call,From}, _Msg, State, Data) ->" n> "{next_state, State, Data, [{reply,From,ok}]}." n n diff --git a/lib/tools/emacs/erlang.el b/lib/tools/emacs/erlang.el index 67e88bac30..cc22903e7f 100644 --- a/lib/tools/emacs/erlang.el +++ b/lib/tools/emacs/erlang.el @@ -59,7 +59,7 @@ ;; Please state as exactly as possible: ;; - Version number of Erlang Mode (see the menu), Emacs, Erlang, -;; and of any other relevant software. +;; and of any other relevant software. ;; - What the expected result was. ;; - What you did, preferably in a repeatable step-by-step form. ;; - A description of the unexpected result. @@ -95,20 +95,20 @@ Erlang mode menu.") (eval-and-compile (defconst erlang-emacs-major-version (if (boundp 'emacs-major-version) - emacs-major-version + emacs-major-version (string-match "\\([0-9]+\\)\\.\\([0-9]+\\)" emacs-version) (erlang-string-to-int (substring emacs-version - (match-beginning 1) (match-end 1)))) + (match-beginning 1) (match-end 1)))) "Major version number of Emacs.")) (eval-and-compile (defconst erlang-emacs-minor-version - (if (boundp 'emacs-minor-version) - emacs-minor-version - (string-match "\\([0-9]+\\)\\.\\([0-9]+\\)" emacs-version) - (erlang-string-to-int (substring emacs-version - (match-beginning 2) (match-end 2)))) - "Minor version number of Emacs.")) + (if (boundp 'emacs-minor-version) + emacs-minor-version + (string-match "\\([0-9]+\\)\\.\\([0-9]+\\)" emacs-version) + (erlang-string-to-int (substring emacs-version + (match-beginning 2) (match-end 2)))) + "Minor version number of Emacs.")) (defconst erlang-xemacs-p (string-match "Lucid\\|XEmacs" emacs-version) "Non-nil when running under XEmacs or Lucid Emacs.") @@ -123,12 +123,12 @@ buffers in Erlang mode, just like under GNU Emacs. Never EVER set this variable!") (defvar erlang-menu-items '(erlang-menu-base-items - erlang-menu-skel-items - erlang-menu-shell-items - erlang-menu-compile-items - erlang-menu-man-items - erlang-menu-personal-items - erlang-menu-version-items) + erlang-menu-skel-items + erlang-menu-shell-items + erlang-menu-compile-items + erlang-menu-man-items + erlang-menu-personal-items + erlang-menu-version-items) "*List of menu item list to combine to create Erlang mode menu. External programs which temporarily add menu items to the Erlang mode @@ -174,7 +174,7 @@ variable.") ("TAGS" (("Find Tag" find-tag) ("Find Next Tag" erlang-find-next-tag) - ;("Find Regexp" find-tag-regexp) + ;("Find Regexp" find-tag-regexp) ("Complete Word" erlang-complete-tag) ("Tags Apropos" tags-apropos) ("Search Files" tags-search)))) @@ -562,35 +562,35 @@ This is an elisp list of options. Each option can be either: Supporting \_< and \_> This is determined by checking the version of Emacs used.")) (eval-and-compile - (defconst erlang-atom-quoted-regexp + (defconst erlang-atom-quoted-regexp "'\\(?:[^\\']\\|\\(?:\\\\.\\)\\)*'" "Regexp describing a single-quoted atom")) (eval-and-compile (defconst erlang-atom-regular-regexp (if erlang-regexp-modern-p - "\\_<[[:lower:]]\\(?:\\sw\\|\\s_\\)*\\_>" + "\\_<[[:lower:]]\\(?:\\sw\\|\\s_\\)*\\_>" "\\<[[:lower:]]\\(?:\\sw\\|\\s_\\)*\\>") "Regexp describing a regular (non-quoted) atom")) (eval-and-compile - (defconst erlang-atom-regexp - (concat "\\(" erlang-atom-quoted-regexp "\\|" - erlang-atom-regular-regexp "\\)") + (defconst erlang-atom-regexp + (concat "\\(" erlang-atom-quoted-regexp "\\|" + erlang-atom-regular-regexp "\\)") "Regexp describing an Erlang atom.")) (eval-and-compile (defconst erlang-atom-regexp-matches 1 "Number of regexp parenthesis pairs in `erlang-atom-regexp'. - + This is used to determine parenthesis matches in complex regexps which contains `erlang-atom-regexp'.")) (eval-and-compile - (defconst erlang-variable-regexp - (if erlang-regexp-modern-p - "\\_<\\([[:upper:]_]\\(?:\\sw\\|\\s_\\)*\\)\\_>" + (defconst erlang-variable-regexp + (if erlang-regexp-modern-p + "\\_<\\([[:upper:]_]\\(?:\\sw\\|\\s_\\)*\\)\\_>" "\\<\\([[:upper:]_]\\(?:\\sw\\|\\s_\\)*\\)\\>") "Regexp which should match an Erlang variable. @@ -609,13 +609,13 @@ This is used to determine matches in complex regexps which contains "Like `regexp-opt', except if PAREN is `symbols', then the resulting regexp is surrounded by \\_< and \\_>." (if (eq paren 'symbols) - (if erlang-regexp-modern-p - (concat "\\_<" (regexp-opt strings t) "\\_>") - (concat "\\<" (regexp-opt strings t) "\\>")) + (if erlang-regexp-modern-p + (concat "\\_<" (regexp-opt strings t) "\\_>") + (concat "\\<" (regexp-opt strings t) "\\>")) (regexp-opt strings paren)))) -(eval-and-compile +(eval-and-compile (defvar erlang-keywords '("after" "begin" @@ -634,7 +634,7 @@ resulting regexp is surrounded by \\_< and \\_>." (eval-and-compile (defconst erlang-keywords-regexp (erlang-regexp-opt erlang-keywords 'symbols))) - + (eval-and-compile (defvar erlang-operators '("and" @@ -657,7 +657,7 @@ resulting regexp is surrounded by \\_< and \\_>." (eval-and-compile (defconst erlang-operators-regexp (erlang-regexp-opt erlang-operators 'symbols))) - + (eval-and-compile (defvar erlang-guards @@ -680,7 +680,7 @@ resulting regexp is surrounded by \\_< and \\_>." "binary" "bitstring" "boolean" - ;;"float" ; Not included to avoid clashes with the bif float/1 + ;;"float" ; Not included to avoid clashes with the bif float/1 "function" "integer" "list" @@ -726,7 +726,7 @@ resulting regexp is surrounded by \\_< and \\_>." "Erlang type specs types")) (eval-and-compile - (defconst erlang-predefined-types-regexp + (defconst erlang-predefined-types-regexp (erlang-regexp-opt erlang-predefined-types 'symbols))) @@ -846,7 +846,7 @@ resulting regexp is surrounded by \\_< and \\_>." (eval-and-compile (defconst erlang-int-bif-regexp (erlang-regexp-opt erlang-int-bifs 'symbols))) - + (eval-and-compile (defvar erlang-ext-bifs @@ -1001,8 +1001,8 @@ behaviour.") (let ((map (make-sparse-keymap))) (unless (boundp 'indent-line-function) (define-key map "\t" 'erlang-indent-command)) - (define-key map ";" 'erlang-electric-semicolon) - (define-key map "," 'erlang-electric-comma) + (define-key map ";" 'erlang-electric-semicolon) + (define-key map "," 'erlang-electric-comma) (define-key map "<" 'erlang-electric-lt) (define-key map ">" 'erlang-electric-gt) (define-key map "\C-m" 'erlang-electric-newline) @@ -1014,7 +1014,7 @@ behaviour.") (unless (boundp 'beginning-of-defun-function) (define-key map "\M-\C-a" 'erlang-beginning-of-function) (define-key map "\M-\C-e" 'erlang-end-of-function) - (define-key map '(meta control h) 'erlang-mark-function)) ; Xemacs + (define-key map '(meta control h) 'erlang-mark-function)) ; Xemacs (define-key map "\M-\t" 'erlang-complete-tag) (define-key map "\C-c\M-\t" 'tempo-complete-tag) (define-key map "\M-+" 'erlang-find-next-tag) @@ -1068,7 +1068,7 @@ behaviour.") (defvar erlang-font-lock-keywords-function-header (list (list (concat "^" erlang-atom-regexp "\\s-*(") - 1 'font-lock-function-name-face t)) + 1 'font-lock-function-name-face t)) "Font lock keyword highlighting a function header.") (defface erlang-font-lock-exported-function-name-face @@ -1090,7 +1090,7 @@ behaviour.") (defvar erlang-font-lock-keywords-exported-function-header (list (list #'erlang-match-next-exported-function - 1 'erlang-font-lock-exported-function-name-face t)) + 1 'erlang-font-lock-exported-function-name-face t)) "Font lock keyword highlighting an exported function header.") (defvar erlang-font-lock-keywords-int-bifs @@ -1102,8 +1102,8 @@ behaviour.") (defvar erlang-font-lock-keywords-ext-bifs (list (list (concat "\\<\\(erlang\\)\\s-*:\\s-*" erlang-ext-bif-regexp "\\s-*(") - '(1 'font-lock-builtin-face) - '(2 'font-lock-builtin-face))) + '(1 'font-lock-builtin-face) + '(2 'font-lock-builtin-face))) "Font lock keyword highlighting built in functions.") (defvar erlang-font-lock-keywords-int-function-calls @@ -1117,7 +1117,7 @@ behaviour.") (list (concat erlang-atom-regexp "\\s-*:\\s-*" erlang-atom-regexp "\\s-*(") '(1 'font-lock-type-face) - '(2 'font-lock-type-face))) + '(2 'font-lock-type-face))) "Font lock keyword highlighting an external function call.") (defvar erlang-font-lock-keywords-fun-n @@ -1135,7 +1135,7 @@ behaviour.") (defvar erlang-font-lock-keywords-dollar (list (list "\\(\\$\\([^\\]\\|\\\\\\([^0-7^\n]\\|[0-7]+\\|\\^[a-zA-Z]\\)\\)\\)" - 1 'font-lock-constant-face)) + 1 'font-lock-constant-face)) "Font lock keyword highlighting numbers in ASCII form (e.g. $A).") (defvar erlang-font-lock-keywords-arrow @@ -1155,18 +1155,18 @@ behaviour.") (defvar erlang-font-lock-keywords-attr (list - (list (concat "^\\(-" erlang-atom-regexp "\\)\\(\\s-\\|\\.\\|(\\)") - 1 (if (boundp 'font-lock-preprocessor-face) - 'font-lock-preprocessor-face - 'font-lock-constant-face))) + (list (concat "^\\(-" erlang-atom-regexp "\\)\\(\\s-\\|\\.\\|(\\)") + 1 (if (boundp 'font-lock-preprocessor-face) + 'font-lock-preprocessor-face + 'font-lock-constant-face))) "Font lock keyword highlighting attributes.") (defvar erlang-font-lock-keywords-quotes (list (list "`\\([-+a-zA-Z0-9_:*][-+a-zA-Z0-9_:*]+\\)'" - 1 - 'font-lock-keyword-face - t)) + 1 + 'font-lock-keyword-face + t)) "Font lock keyword highlighting words in single quotes in comments. This is not the highlighting of Erlang strings and atoms, which @@ -1175,27 +1175,27 @@ are highlighted by syntactic analysis.") (defvar erlang-font-lock-keywords-guards (list (list (concat "[^:]" erlang-guards-regexp "\\s-*(") - 1 'font-lock-builtin-face)) + 1 'font-lock-builtin-face)) "Font lock keyword highlighting guards.") (defvar erlang-font-lock-keywords-predefined-types (list (list (concat "[^:]" erlang-predefined-types-regexp "\\s-*(") - 1 'font-lock-builtin-face)) + 1 'font-lock-builtin-face)) "Font lock keyword highlighting predefined types.") (defvar erlang-font-lock-keywords-macros (list (list (concat "?\\s-*\\(" erlang-atom-regexp - "\\|" erlang-variable-regexp "\\)") - 1 'font-lock-constant-face) + "\\|" erlang-variable-regexp "\\)") + 1 'font-lock-constant-face) (list (concat "^\\(-\\(?:define\\|ifn?def\\)\\)\\s-*(\\s-*\\(" erlang-atom-regexp - "\\|" erlang-variable-regexp "\\)") - (if (boundp 'font-lock-preprocessor-face) - (list 1 'font-lock-preprocessor-face t) - (list 1 'font-lock-constant-face t)) - (list 3 'font-lock-type-face t t)) + "\\|" erlang-variable-regexp "\\)") + (if (boundp 'font-lock-preprocessor-face) + (list 1 'font-lock-preprocessor-face t) + (list 1 'font-lock-constant-face t)) + (list 3 'font-lock-type-face t t)) (list "^-e\\(lse\\|ndif\\)\\>" 0 'font-lock-preprocessor-face t)) "Font lock keyword highlighting macros. This must be placed in front of `erlang-font-lock-keywords-vars'.") @@ -1206,8 +1206,8 @@ This must be placed in front of `erlang-font-lock-keywords-vars'.") 1 'font-lock-type-face) ;; Don't highlight numerical constants. (list (if erlang-regexp-modern-p - "\\_<[0-9]+#\\([0-9a-zA-Z]+\\)" - "\\<[0-9]+#\\([0-9a-zA-Z]+\\)") + "\\_<[0-9]+#\\([0-9a-zA-Z]+\\)" + "\\<[0-9]+#\\([0-9a-zA-Z]+\\)") 1 nil t) (list (concat "^-record\\s-*(\\s-*" erlang-atom-regexp) 1 'font-lock-type-face)) @@ -1216,8 +1216,8 @@ This must be placed in front of `erlang-font-lock-keywords-vars'.") (defvar erlang-font-lock-keywords-vars (list - (list (concat "[^#]" erlang-variable-regexp) ; no numerical constants - 1 'font-lock-variable-name-face)) + (list (concat "[^#]" erlang-variable-regexp) ; no numerical constants + 1 'font-lock-variable-name-face)) "Font lock keyword highlighting Erlang variables. Must be preceded by `erlang-font-lock-keywords-macros' to work properly.") @@ -1240,32 +1240,32 @@ Example: (defvar erlang-font-lock-keywords-1 (append erlang-font-lock-keywords-function-header - erlang-font-lock-keywords-dollar - erlang-font-lock-keywords-arrow - erlang-font-lock-keywords-keywords - ) + erlang-font-lock-keywords-dollar + erlang-font-lock-keywords-arrow + erlang-font-lock-keywords-keywords + ) ;; DocStringOrig: erlang-font-lock-keywords erlang-font-lock-descr-string) (defvar erlang-font-lock-keywords-2 (append erlang-font-lock-keywords-1 - erlang-font-lock-keywords-int-bifs - erlang-font-lock-keywords-ext-bifs - erlang-font-lock-keywords-attr - erlang-font-lock-keywords-quotes - erlang-font-lock-keywords-guards - ) + erlang-font-lock-keywords-int-bifs + erlang-font-lock-keywords-ext-bifs + erlang-font-lock-keywords-attr + erlang-font-lock-keywords-quotes + erlang-font-lock-keywords-guards + ) ;; DocStringCopy: erlang-font-lock-keywords erlang-font-lock-descr-string) (defvar erlang-font-lock-keywords-3 (append erlang-font-lock-keywords-2 - erlang-font-lock-keywords-operators - erlang-font-lock-keywords-macros - erlang-font-lock-keywords-records - erlang-font-lock-keywords-vars - erlang-font-lock-keywords-predefined-types - ) + erlang-font-lock-keywords-operators + erlang-font-lock-keywords-macros + erlang-font-lock-keywords-records + erlang-font-lock-keywords-vars + erlang-font-lock-keywords-predefined-types + ) ;; DocStringCopy: erlang-font-lock-keywords erlang-font-lock-descr-string) @@ -1273,10 +1273,10 @@ Example: (append erlang-font-lock-keywords-3 erlang-font-lock-keywords-exported-function-header erlang-font-lock-keywords-int-function-calls - erlang-font-lock-keywords-ext-function-calls - erlang-font-lock-keywords-fun-n + erlang-font-lock-keywords-ext-function-calls + erlang-font-lock-keywords-fun-n erlang-font-lock-keywords-lc - ) + ) ;; DocStringCopy: erlang-font-lock-keywords erlang-font-lock-descr-string) @@ -1337,17 +1337,17 @@ replaced by `erlang-etags-tags-completion-table'.") (eval-when-compile (if (or (featurep 'bytecomp) - (featurep 'byte-compile)) + (featurep 'byte-compile)) (progn - (cond ((string-match "Lucid\\|XEmacs" emacs-version) - (put 'comment-indent-hook 'byte-obsolete-variable nil) - ;; Do not warn for unused variables - ;; when compiling under XEmacs. - (setq byte-compile-warnings - '(free-vars unresolved callargs redefine)))) - (require 'comint) - (require 'tempo) - (require 'compile)))) + (cond ((string-match "Lucid\\|XEmacs" emacs-version) + (put 'comment-indent-hook 'byte-obsolete-variable nil) + ;; Do not warn for unused variables + ;; when compiling under XEmacs. + (setq byte-compile-warnings + '(free-vars unresolved callargs redefine)))) + (require 'comint) + (require 'tempo) + (require 'compile)))) (defun erlang-version () @@ -1355,7 +1355,7 @@ replaced by `erlang-etags-tags-completion-table'.") (interactive) (if (erlang-interactive-p) (message "Erlang mode version %s, written by Anders Lindgren" - erlang-version)) + erlang-version)) erlang-version) (defun erlang-interactive-p () @@ -1393,7 +1393,7 @@ useful commands: C-c C-q - Indent current function. M-; - Create a comment at the end of the line. M-q - Fill a comment, i.e. wrap lines so that they (hopefully) - will look better. + will look better. M-a - Goto the beginning of an Erlang clause. M-C-a - Ditto for function. M-e - Goto the end of an Erlang clause. @@ -1452,35 +1452,35 @@ Other commands: (defun erlang-syntax-table-init () (if (null erlang-mode-syntax-table) (let ((table (make-syntax-table))) - (modify-syntax-entry ?\n ">" table) - (modify-syntax-entry ?\" "\"" table) - (modify-syntax-entry ?# "." table) -;; (modify-syntax-entry ?$ "\\" table) ;; Creates problems with indention afterwards -;; (modify-syntax-entry ?$ "'" table) ;; Creates syntax highlighting and indention problems - (modify-syntax-entry ?$ "/" table) ;; Misses the corner case "string that ends with $" - ;; we have to live with that for now..it is the best alternative - ;; that can be worked around with "string hat ends with \$" - (modify-syntax-entry ?% "<" table) - (modify-syntax-entry ?& "." table) - (modify-syntax-entry ?\' "\"" table) - (modify-syntax-entry ?* "." table) - (modify-syntax-entry ?+ "." table) - (modify-syntax-entry ?- "." table) - (modify-syntax-entry ?/ "." table) - (modify-syntax-entry ?: "." table) - (modify-syntax-entry ?< "." table) - (modify-syntax-entry ?= "." table) - (modify-syntax-entry ?> "." table) - (modify-syntax-entry ?\\ "\\" table) - (modify-syntax-entry ?_ "_" table) - (modify-syntax-entry ?| "." table) - (modify-syntax-entry ?^ "'" table) - - ;; Pseudo bit-syntax: Latin1 double angle quotes as parens. - ;;(modify-syntax-entry ?\253 "(?\273" table) - ;;(modify-syntax-entry ?\273 ")?\253" table) - - (setq erlang-mode-syntax-table table))) + (modify-syntax-entry ?\n ">" table) + (modify-syntax-entry ?\" "\"" table) + (modify-syntax-entry ?# "." table) + ;; (modify-syntax-entry ?$ "\\" table) ;; Creates problems with indention afterwards + ;; (modify-syntax-entry ?$ "'" table) ;; Creates syntax highlighting and indention problems + (modify-syntax-entry ?$ "/" table) ;; Misses the corner case "string that ends with $" + ;; we have to live with that for now..it is the best alternative + ;; that can be worked around with "string hat ends with \$" + (modify-syntax-entry ?% "<" table) + (modify-syntax-entry ?& "." table) + (modify-syntax-entry ?\' "\"" table) + (modify-syntax-entry ?* "." table) + (modify-syntax-entry ?+ "." table) + (modify-syntax-entry ?- "." table) + (modify-syntax-entry ?/ "." table) + (modify-syntax-entry ?: "." table) + (modify-syntax-entry ?< "." table) + (modify-syntax-entry ?= "." table) + (modify-syntax-entry ?> "." table) + (modify-syntax-entry ?\\ "\\" table) + (modify-syntax-entry ?_ "_" table) + (modify-syntax-entry ?| "." table) + (modify-syntax-entry ?^ "'" table) + + ;; Pseudo bit-syntax: Latin1 double angle quotes as parens. + ;;(modify-syntax-entry ?\253 "(?\273" table) + ;;(modify-syntax-entry ?\273 ")?\253" table) + + (setq erlang-mode-syntax-table table))) (set-syntax-table erlang-mode-syntax-table)) @@ -1490,12 +1490,12 @@ Other commands: ;; delsel/pending-del mode. Also, set up text properties for bit ;; syntax handling. (mapc #'(lambda (cmd) - (put cmd 'delete-selection t) ;for delsel (Emacs) - (put cmd 'pending-delete t)) ;for pending-del (XEmacs) - '(erlang-electric-semicolon - erlang-electric-comma - erlang-electric-gt)) - + (put cmd 'delete-selection t) ;for delsel (Emacs) + (put cmd 'pending-delete t)) ;for pending-del (XEmacs) + '(erlang-electric-semicolon + erlang-electric-comma + erlang-electric-gt)) + (put 'bitsyntax-open-outer 'syntax-table '(4 . ?>)) (put 'bitsyntax-open-outer 'rear-nonsticky '(category)) (put 'bitsyntax-open-inner 'rear-nonsticky '(category)) @@ -1554,9 +1554,9 @@ Other commands: "Initialize Font Lock for Erlang mode." (or erlang-font-lock-syntax-table (setq erlang-font-lock-syntax-table - (let ((table (copy-syntax-table erlang-mode-syntax-table))) - (modify-syntax-entry ?_ "w" table) - table))) + (let ((table (copy-syntax-table erlang-mode-syntax-table))) + (modify-syntax-entry ?_ "w" table) + table))) (set (make-local-variable 'font-lock-syntax-table) erlang-font-lock-syntax-table) (set (make-local-variable (if (boundp 'syntax-begin-function) @@ -1565,23 +1565,23 @@ Other commands: 'erlang-beginning-of-clause) (make-local-variable 'font-lock-keywords) (let ((level (cond ((boundp 'font-lock-maximum-decoration) - (symbol-value 'font-lock-maximum-decoration)) - ((boundp 'font-lock-use-maximal-decoration) - (symbol-value 'font-lock-use-maximal-decoration)) - (t nil)))) + (symbol-value 'font-lock-maximum-decoration)) + ((boundp 'font-lock-use-maximal-decoration) + (symbol-value 'font-lock-use-maximal-decoration)) + (t nil)))) (if (consp level) - (setq level (cdr-safe (or (assq 'erlang-mode level) - (assq t level))))) + (setq level (cdr-safe (or (assq 'erlang-mode level) + (assq t level))))) ;; `level' can here be: ;; A number - The fontification level ;; nil - Use the default ;; t - Use maximum (cond ((eq level nil) - (set 'font-lock-keywords erlang-font-lock-keywords)) - ((eq level 1) - (set 'font-lock-keywords erlang-font-lock-keywords-1)) - ((eq level 2) - (set 'font-lock-keywords erlang-font-lock-keywords-2)) + (set 'font-lock-keywords erlang-font-lock-keywords)) + ((eq level 1) + (set 'font-lock-keywords erlang-font-lock-keywords-1)) + ((eq level 2) + (set 'font-lock-keywords erlang-font-lock-keywords-2)) ((eq level 3) (set 'font-lock-keywords erlang-font-lock-keywords-3)) (t @@ -1590,11 +1590,11 @@ Other commands: ;; Modern font-locks can handle the above much more elegantly: (set (make-local-variable 'font-lock-defaults) '((erlang-font-lock-keywords erlang-font-lock-keywords-1 - erlang-font-lock-keywords-2 - erlang-font-lock-keywords-3 - erlang-font-lock-keywords-4) - nil nil ((?_ . "w")) erlang-beginning-of-clause - (font-lock-mark-block-function . erlang-mark-clause) + erlang-font-lock-keywords-2 + erlang-font-lock-keywords-3 + erlang-font-lock-keywords-4) + nil nil ((?_ . "w")) erlang-beginning-of-clause + (font-lock-mark-block-function . erlang-mark-clause) (font-lock-syntactic-keywords ;; A dollar sign right before the double quote that ends a ;; string is not a character escape. @@ -1608,8 +1608,8 @@ Other commands: ;; know whether matching started inside a string: limiting ;; search to a single line keeps things sane. . (("\\(?:^\\|[^$]\\)\"\\(?:[^\"\n]\\|\\\\\"\\)*\\(\\$\\)\"" 1 "w") - ;; Likewise for atoms - ("\\(?:^\\|[^$]\\)'\\(?:[^'\n]\\|\\\\'\\)*\\(\\$\\)'" 1 "w") + ;; Likewise for atoms + ("\\(?:^\\|[^$]\\)'\\(?:[^'\n]\\|\\\\'\\)*\\(\\$\\)'" 1 "w") ;; And the dollar sign in $\" or $\' escapes two ;; characters, not just one. ("\\(\\$\\)\\\\[\"']" 1 "'")))))) @@ -1655,17 +1655,17 @@ For a more elaborate example, please see the beginning of the file (let ((res '())) (while ks (let* ((regexp (car (car ks))) - (number (car (cdr (car ks)))) - (new-face (if (and faces (car faces)) - (car faces) - (car (cdr (cdr (car ks)))))) - (overwrite (car (cdr (cdr (cdr (car ks)))))) - (new-keyword (list regexp number new-face))) - (if overwrite (nconc new-keyword (list overwrite))) - (setq res (cons new-keyword res)) - (setq ks (cdr ks)) - (if (and faces (cdr faces)) - (setq faces (cdr faces))))) + (number (car (cdr (car ks)))) + (new-face (if (and faces (car faces)) + (car faces) + (car (cdr (cdr (car ks)))))) + (overwrite (car (cdr (cdr (cdr (car ks)))))) + (new-keyword (list regexp number new-face))) + (if overwrite (nconc new-keyword (list overwrite))) + (setq res (cons new-keyword res)) + (setq ks (cdr ks)) + (if (and faces (cdr faces)) + (setq faces (cdr faces))))) (nreverse res))) @@ -1757,57 +1757,57 @@ variable, i.e. it will popup when pressing the right mouse button. Please see the variable `erlang-menu-base-items'." (cond (erlang-xemacs-p - (let ((menu (erlang-menu-xemacs name items keymap))) - ;; We add the menu to the global menubar. - ;;(funcall (symbol-function 'set-buffer-menubar) - ;; (symbol-value 'current-menubar)) - (funcall (symbol-function 'add-submenu) nil menu) - (setcdr erlang-xemacs-popup-menu (cdr menu)) - (if (and popup (boundp 'mode-popup-menu)) - (funcall (symbol-function 'set) - 'mode-popup-menu erlang-xemacs-popup-menu)))) - ((>= erlang-emacs-major-version 19) - (define-key keymap (vector 'menu-bar (intern name)) - (erlang-menu-make-keymap name items))) - (t nil))) + (let ((menu (erlang-menu-xemacs name items keymap))) + ;; We add the menu to the global menubar. + ;;(funcall (symbol-function 'set-buffer-menubar) + ;; (symbol-value 'current-menubar)) + (funcall (symbol-function 'add-submenu) nil menu) + (setcdr erlang-xemacs-popup-menu (cdr menu)) + (if (and popup (boundp 'mode-popup-menu)) + (funcall (symbol-function 'set) + 'mode-popup-menu erlang-xemacs-popup-menu)))) + ((>= erlang-emacs-major-version 19) + (define-key keymap (vector 'menu-bar (intern name)) + (erlang-menu-make-keymap name items))) + (t nil))) (defun erlang-menu-make-keymap (name items) "Build a menu for Emacs 19." (let ((menumap (funcall (symbol-function 'make-sparse-keymap) - name)) - (count 0) - id def first second third) + name)) + (count 0) + id def first second third) (setq items (reverse items)) (while items ;; Replace any occurrence of atoms by their value. (while (and items (atom (car items)) (not (null (car items)))) - (if (and (boundp (car items)) - (listp (symbol-value (car items)))) - (setq items (append (reverse (symbol-value (car items))) - (cdr items))) - (setq items (cdr items)))) + (if (and (boundp (car items)) + (listp (symbol-value (car items)))) + (setq items (append (reverse (symbol-value (car items))) + (cdr items))) + (setq items (cdr items)))) (setq first (car-safe (car items))) (setq second (car-safe (cdr-safe (car items)))) (setq third (car-safe (cdr-safe (cdr-safe (car items))))) (cond ((null first) - (setq count (+ count 1)) - (setq id (intern (format "separator-%d" count))) - (setq def '("--" . nil))) - ((and (consp second) (eq (car second) 'lambda)) - (setq count (+ count 1)) - (setq id (intern (format "lambda-%d" count))) - (setq def (cons first second))) - ((symbolp second) - (setq id second) - (setq def (cons first second))) - (t - (setq count (+ count 1)) - (setq id (intern (format "submenu-%d" count))) - (setq def (erlang-menu-make-keymap first second)))) + (setq count (+ count 1)) + (setq id (intern (format "separator-%d" count))) + (setq def '("--" . nil))) + ((and (consp second) (eq (car second) 'lambda)) + (setq count (+ count 1)) + (setq id (intern (format "lambda-%d" count))) + (setq def (cons first second))) + ((symbolp second) + (setq id second) + (setq def (cons first second))) + (t + (setq count (+ count 1)) + (setq id (intern (format "submenu-%d" count))) + (setq def (erlang-menu-make-keymap first second)))) (define-key menumap (vector id) def) (if third - (put id 'menu-enable third)) + (put id 'menu-enable third)) (setq items (cdr items))) (cons name menumap))) @@ -1815,30 +1815,30 @@ Please see the variable `erlang-menu-base-items'." (defun erlang-menu-xemacs (name items &optional keymap) "Build a menu for XEmacs." (let ((res '()) - first second third entry) + first second third entry) (while items ;; Replace any occurrence of atoms by their value. (while (and items (atom (car items)) (not (null (car items)))) - (if (and (boundp (car items)) - (listp (symbol-value (car items)))) - (setq items (append (reverse (symbol-value (car items))) - (cdr items))) - (setq items (cdr items)))) + (if (and (boundp (car items)) + (listp (symbol-value (car items)))) + (setq items (append (reverse (symbol-value (car items))) + (cdr items))) + (setq items (cdr items)))) (setq first (car-safe (car items))) (setq second (car-safe (cdr-safe (car items)))) (setq third (car-safe (cdr-safe (cdr-safe (car items))))) (cond ((null first) - (setq res (cons "------" res))) - ((symbolp second) - (setq res (cons (vector first second (or third t)) res))) - ((and (consp second) (eq (car second) 'lambda)) - (setq res (cons (vector first (list 'call-interactively second) - (or third t)) res))) - (t - (setq res (cons (cons first - (cdr (erlang-menu-xemacs - first second))) - res)))) + (setq res (cons "------" res))) + ((symbolp second) + (setq res (cons (vector first second (or third t)) res))) + ((and (consp second) (eq (car second) 'lambda)) + (setq res (cons (vector first (list 'call-interactively second) + (or third t)) res))) + (t + (setq res (cons (cons first + (cdr (erlang-menu-xemacs + first second))) + res)))) (setq items (cdr items))) (setq res (reverse res)) ;; When adding a menu to a minor-mode keymap under Emacs, @@ -1847,15 +1847,15 @@ Please see the variable `erlang-menu-base-items'." ;; (This could be expressed much clearer using backquotes, ;; but I don't want to pull in every package.) (if keymap - (let ((expr (list 'or - (list 'eq keymap 'global-map) - (list 'eq keymap (list 'current-local-map)) - (list 'symbol-value - (list 'car-safe - (list 'rassq - keymap - 'minor-mode-map-alist)))))) - (setq res (cons ':included (cons expr res))))) + (let ((expr (list 'or + (list 'eq keymap 'global-map) + (list 'eq keymap (list 'current-local-map)) + (list 'symbol-value + (list 'car-safe + (list 'rassq + keymap + 'minor-mode-map-alist)))))) + (setq res (cons ':included (cons expr res))))) (cons name res))) @@ -1870,13 +1870,13 @@ ALIST is list of pairs where the car is the old function and cdr the new." (setq first (car-safe (car items))) (setq second (car-safe (cdr-safe (car items)))) (cond ((null first)) - ((symbolp second) - (setq pair (and second (assq second alist))) - (if pair - (setcar (cdr (car items)) (cdr pair)))) - ((and (consp second) (eq (car second) 'lambda))) - (t - (erlang-menu-substitute second alist))) + ((symbolp second) + (setq pair (and second (assq second alist))) + (if pair + (setcar (cdr (car items)) (cdr pair)))) + ((and (consp second) (eq (car second) 'lambda))) + (t + (erlang-menu-substitute second alist))) (setq items (cdr items))))) @@ -1911,27 +1911,27 @@ Example: \(setq erlang-menu-items (erlang-menu-add-below 'my-erlang-menu-items - 'erlang-menu-base-items + 'erlang-menu-base-items erlang-menu-items))" (if (memq entry items) - items ; Return the original menu. + items ; Return the original menu. (let ((head '()) - (done nil) - res) + (done nil) + res) (while (not done) - (cond ((null items) - (setq res (append head (list entry))) - (setq done t)) - ((eq below (car items)) - (setq res - (if above-p - (append head (cons entry items)) - (append head (cons (car items) - (cons entry (cdr items)))))) - (setq done t)) - (t - (setq head (append head (list (car items)))) - (setq items (cdr items))))) + (cond ((null items) + (setq res (append head (list entry))) + (setq done t)) + ((eq below (car items)) + (setq res + (if above-p + (append head (cons entry items)) + (append head (cons (car items) + (cons entry (cdr items)))))) + (setq done t)) + (t + (setq head (append head (list (car items)))) + (setq items (cdr items))))) res))) (defun erlang-menu-delete (entry items) @@ -1952,16 +1952,16 @@ the location of the manual pages." (if erlang-man-inhibit () (setq erlang-menu-man-items - '(nil - ("Man - Function" erlang-man-function))) + '(nil + ("Man - Function" erlang-man-function))) (if erlang-man-dirs - (setq erlang-menu-man-items - (append erlang-menu-man-items - (erlang-man-make-top-menu erlang-man-dirs)))) + (setq erlang-menu-man-items + (append erlang-menu-man-items + (erlang-man-make-top-menu erlang-man-dirs)))) (setq erlang-menu-items - (erlang-menu-add-above 'erlang-menu-man-items - 'erlang-menu-version-items - erlang-menu-items)) + (erlang-menu-add-above 'erlang-menu-man-items + 'erlang-menu-version-items + erlang-menu-items)) (erlang-menu-init))) @@ -1969,7 +1969,7 @@ the location of the manual pages." "Remove the man pages from the Erlang mode." (interactive) (setq erlang-menu-items - (erlang-menu-delete 'erlang-menu-man-items erlang-menu-items)) + (erlang-menu-delete 'erlang-menu-man-items erlang-menu-items)) (erlang-menu-init)) @@ -1983,28 +1983,28 @@ the location of the manual pages." "Create one menu entry per element of DIR-LIST. The format is described in the documentation of `erlang-man-dirs'." (let ((menu '()) - dir) + dir) (while dir-list (setq dir (cond ((nth 2 (car dir-list)) - ;; Relative to `erlang-root-dir'. - (and (stringp erlang-root-dir) - (concat erlang-root-dir (nth 1 (car dir-list))))) - (t - ;; Absolute - (nth 1 (car dir-list))))) + ;; Relative to `erlang-root-dir'. + (and (stringp erlang-root-dir) + (concat erlang-root-dir (nth 1 (car dir-list))))) + (t + ;; Absolute + (nth 1 (car dir-list))))) (if (and dir - (file-readable-p dir)) - (setq menu (cons (list (car (car dir-list)) - (erlang-man-make-middle-menu - (erlang-man-get-files dir))) - menu))) + (file-readable-p dir)) + (setq menu (cons (list (car (car dir-list)) + (erlang-man-make-middle-menu + (erlang-man-get-files dir))) + menu))) (setq dir-list (cdr dir-list))) ;; Should no menus be found, generate a menu item which ;; will display a help text, when selected. (if menu - (nreverse menu) + (nreverse menu) '(("Man Pages" - (("Error! Why?" erlang-man-describe-error))))))) + (("Error! Why?" erlang-man-describe-error))))))) ;; Should the menu be to long, let's split it into a number of @@ -2018,32 +2018,32 @@ menus is created." (if (<= (length filelist) erlang-man-max-menu-size) (erlang-man-make-menu filelist) (let ((menu '()) - (filelist (copy-sequence filelist)) - segment submenu pair) + (filelist (copy-sequence filelist)) + segment submenu pair) (while filelist - (setq pair (nthcdr (- erlang-man-max-menu-size 1) filelist)) - (setq segment filelist) - (if (null pair) - (setq filelist nil) - (setq filelist (cdr pair)) - (setcdr pair nil)) - (setq submenu (erlang-man-make-menu segment)) - (setq menu (cons (list (concat (car (car submenu)) - " -- " - (car (car (reverse submenu)))) - submenu) - menu))) + (setq pair (nthcdr (- erlang-man-max-menu-size 1) filelist)) + (setq segment filelist) + (if (null pair) + (setq filelist nil) + (setq filelist (cdr pair)) + (setcdr pair nil)) + (setq submenu (erlang-man-make-menu segment)) + (setq menu (cons (list (concat (car (car submenu)) + " -- " + (car (car (reverse submenu)))) + submenu) + menu))) (nreverse menu)))) (defun erlang-man-make-menu (filelist) "Make a leaf menu based on FILELIST." (let ((menu '()) - item) + item) (while filelist (setq item (erlang-man-make-menu-item (car filelist))) (if item - (setq menu (cons item menu))) + (setq menu (cons item menu))) (setq filelist (cdr filelist))) (nreverse menu))) @@ -2052,11 +2052,11 @@ menus is created." "Create a menu item containing the name of the man page." (and (string-match ".+/\\([^/]+\\)\\.\\([124-9]\\|3\\(erl\\)?\\)\\(\\.gz\\)?$" file) (let ((page (substring file (match-beginning 1) (match-end 1)))) - (list (capitalize page) - (list 'lambda '() - '(interactive) - (list 'funcall 'erlang-man-display-function - file)))))) + (list (capitalize page) + (list 'lambda '() + '(interactive) + (list 'funcall 'erlang-man-display-function + file)))))) (defun erlang-man-get-files (dir) @@ -2069,33 +2069,33 @@ menus is created." This function is aware of imported functions." (interactive (list (let* ((mod (car-safe (erlang-get-function-under-point))) - (input (read-string - (format "Manual entry for module%s: " - (if (or (null mod) (string= mod "")) - "" - (format " (default %s)" mod)))))) - (if (string= input "") - mod - input)))) + (input (read-string + (format "Manual entry for module%s: " + (if (or (null mod) (string= mod "")) + "" + (format " (default %s)" mod)))))) + (if (string= input "") + mod + input)))) (or module (setq module (car (erlang-get-function-under-point)))) (if (or (null module) (string= module "")) (error "No Erlang module name given")) (let ((dir-list erlang-man-dirs) - (pat (concat "/" (regexp-quote module) "\\.\\([124-9]\\|3\\(erl\\)?\\)\\(\\.gz\\)?$")) - (file nil) - file-list) + (pat (concat "/" (regexp-quote module) "\\.\\([124-9]\\|3\\(erl\\)?\\)\\(\\.gz\\)?$")) + (file nil) + file-list) (while (and dir-list (null file)) (setq file-list (erlang-man-get-files - (if (nth 2 (car dir-list)) - (concat erlang-root-dir (nth 1 (car dir-list))) - (nth 1 (car dir-list))))) + (if (nth 2 (car dir-list)) + (concat erlang-root-dir (nth 1 (car dir-list))) + (nth 1 (car dir-list))))) (while (and file-list (null file)) - (if (string-match pat (car file-list)) - (setq file (car file-list))) - (setq file-list (cdr file-list))) + (if (string-match pat (car file-list)) + (setq file (car file-list))) + (setq file-list (cdr file-list))) (setq dir-list (cdr dir-list))) (if file - (funcall erlang-man-display-function file) + (funcall erlang-man-display-function file) (error "No manual page for module %s found" module)))) @@ -2117,55 +2117,55 @@ The entry for `function' is displayed. This function is aware of imported functions." (interactive (list (let* ((mod-func (erlang-get-function-under-point)) - (mod (car-safe mod-func)) - (func (nth 1 mod-func)) - (input (read-string - (format - "Manual entry for `module:func' or `module'%s: " - (if (or (null mod) (string= mod "")) - "" - (format " (default %s:%s)" mod func)))))) - (if (string= input "") - (if (and mod func) - (concat mod ":" func) - mod) - input)))) + (mod (car-safe mod-func)) + (func (nth 1 mod-func)) + (input (read-string + (format + "Manual entry for `module:func' or `module'%s: " + (if (or (null mod) (string= mod "")) + "" + (format " (default %s:%s)" mod func)))))) + (if (string= input "") + (if (and mod func) + (concat mod ":" func) + mod) + input)))) ;; Emacs 18 doesn't provide `man'... (condition-case nil (require 'man) (error nil)) (let ((modname nil) - (funcname nil)) + (funcname nil)) (cond ((null name) - (let ((mod-func (erlang-get-function-under-point))) - (setq modname (car-safe mod-func)) - (setq funcname (nth 1 mod-func)))) - ((string-match ":" name) - (setq modname (substring name 0 (match-beginning 0))) - (setq funcname (substring name (match-end 0) nil))) - ((stringp name) - (setq modname name))) + (let ((mod-func (erlang-get-function-under-point))) + (setq modname (car-safe mod-func)) + (setq funcname (nth 1 mod-func)))) + ((string-match ":" name) + (setq modname (substring name 0 (match-beginning 0))) + (setq funcname (substring name (match-end 0) nil))) + ((stringp name) + (setq modname name))) (if (or (null modname) (string= modname "")) - (error "No Erlang module name given")) + (error "No Erlang module name given")) (cond ((fboundp 'Man-notify-when-ready) - ;; Emacs 19: The man command could possibly start an - ;; asynchronous process, i.e. we must hook ourselves into - ;; the system to be activated when the man-process - ;; terminates. - (if (null funcname) - () - (erlang-man-patch-notify) - (setq erlang-man-function-name funcname)) - (condition-case nil - (erlang-man-module modname) - (error (setq erlang-man-function-name nil)))) - (t - (erlang-man-module modname) - (if funcname - (erlang-man-find-function - (or (get-buffer "*Manual Entry*") ; Emacs 18 - (current-buffer)) ; XEmacs - funcname)))))) + ;; Emacs 19: The man command could possibly start an + ;; asynchronous process, i.e. we must hook ourselves into + ;; the system to be activated when the man-process + ;; terminates. + (if (null funcname) + () + (erlang-man-patch-notify) + (setq erlang-man-function-name funcname)) + (condition-case nil + (erlang-man-module modname) + (error (setq erlang-man-function-name nil)))) + (t + (erlang-man-module modname) + (if funcname + (erlang-man-find-function + (or (get-buffer "*Manual Entry*") ; Emacs 18 + (current-buffer)) ; XEmacs + funcname)))))) ;; Should the defadvice be at the top level, the package `advice' would @@ -2183,14 +2183,14 @@ command is executed asynchronously." ;; This should never happened since this is only called when ;; running under Emacs 19. (error (error (concat "This command needs the package `advice', " - "please upgrade your Emacs.")))) + "please upgrade your Emacs.")))) (require 'man) (defadvice Man-notify-when-ready - (after erlang-Man-notify-when-ready activate) + (after erlang-Man-notify-when-ready activate) "Set point at the documentation of the function name in `erlang-man-function-name' when the man page is displayed." (if erlang-man-function-name - (erlang-man-find-function (ad-get-arg 0) erlang-man-function-name)) + (erlang-man-find-function (ad-get-arg 0) erlang-man-function-name)) (setq erlang-man-function-name nil))) @@ -2198,17 +2198,17 @@ command is executed asynchronously." "Find manual page for function in `erlang-man-function-name' in buffer BUF." (if func (let ((win (get-buffer-window buf))) - (if win - (progn - (set-buffer buf) - (goto-char (point-min)) - (if (re-search-forward - (concat "^[ \t]+" func " ?(") - (point-max) t) - (progn - (forward-word -1) - (set-window-point win (point))) - (message "Could not find function `%s'" func))))))) + (if win + (progn + (set-buffer buf) + (goto-char (point-min)) + (if (re-search-forward + (concat "^[ \t]+" func " ?(") + (point-max) t) + (progn + (forward-word -1) + (set-window-point win (point))) + (message "Could not find function `%s'" func))))))) (defun erlang-man-display (file) @@ -2222,25 +2222,25 @@ to be used." (error nil)) (if file (let ((process-environment (copy-sequence process-environment))) - (if (string-match "\\(.*\\)/man[^/]*/\\([^.]+\\)\\.\\([124-9]\\|3\\(erl\\)?\\)\\(\\.gz\\)?$" file) - (let ((dir (substring file (match-beginning 1) (match-end 1))) - (page (substring file (match-beginning 2) (match-end 2)))) - (if (fboundp 'setenv) - (setenv "MANPATH" dir) - ;; Emacs 18 - (setq process-environment (cons (concat "MANPATH=" dir) - process-environment))) - (cond ((not (and (not erlang-xemacs-p) - (= erlang-emacs-major-version 19) - (< erlang-emacs-minor-version 29))) - (manual-entry page)) - (t - ;; Emacs 19.28 and earlier versions of 19: - ;; The manual-entry command unconditionally prompts - ;; the user :-( - (funcall (symbol-function 'Man-getpage-in-background) - page)))) - (error "Can't find man page for %s\n" file))))) + (if (string-match "\\(.*\\)/man[^/]*/\\([^.]+\\)\\.\\([124-9]\\|3\\(erl\\)?\\)\\(\\.gz\\)?$" file) + (let ((dir (substring file (match-beginning 1) (match-end 1))) + (page (substring file (match-beginning 2) (match-end 2)))) + (if (fboundp 'setenv) + (setenv "MANPATH" dir) + ;; Emacs 18 + (setq process-environment (cons (concat "MANPATH=" dir) + process-environment))) + (cond ((not (and (not erlang-xemacs-p) + (= erlang-emacs-major-version 19) + (< erlang-emacs-minor-version 29))) + (manual-entry page)) + (t + ;; Emacs 19.28 and earlier versions of 19: + ;; The manual-entry command unconditionally prompts + ;; the user :-( + (funcall (symbol-function 'Man-getpage-in-background) + page)))) + (error "Can't find man page for %s\n" file))))) (defun erlang-man-describe-error () @@ -2283,43 +2283,43 @@ package not be present, this function does nothing." (error t)) (if (featurep 'tempo) (let ((skel erlang-skel) - (menu '())) - (while skel - (cond ((null (car skel)) - (setq menu (cons nil menu))) - (t - (funcall (symbol-function 'tempo-define-template) - (concat "erlang-" (nth 1 (car skel))) - ;; The tempo template used contains an `include' - ;; function call only, hence changes to the - ;; variables describing the templates take effect - ;; immdiately. - (list (list 'erlang-skel-include (nth 2 (car skel)))) - (nth 1 (car skel)) - (car (car skel)) - 'erlang-tempo-tags) - (setq menu (cons (erlang-skel-make-menu-item - (car skel)) menu)))) - (setq skel (cdr skel))) - (setq erlang-menu-skel-items - (list nil (list "Skeletons" (nreverse menu)))) - (setq erlang-menu-items - (erlang-menu-add-above 'erlang-menu-skel-items - 'erlang-menu-version-items - erlang-menu-items)) - (erlang-menu-init)))) + (menu '())) + (while skel + (cond ((null (car skel)) + (setq menu (cons nil menu))) + (t + (funcall (symbol-function 'tempo-define-template) + (concat "erlang-" (nth 1 (car skel))) + ;; The tempo template used contains an `include' + ;; function call only, hence changes to the + ;; variables describing the templates take effect + ;; immdiately. + (list (list 'erlang-skel-include (nth 2 (car skel)))) + (nth 1 (car skel)) + (car (car skel)) + 'erlang-tempo-tags) + (setq menu (cons (erlang-skel-make-menu-item + (car skel)) menu)))) + (setq skel (cdr skel))) + (setq erlang-menu-skel-items + (list nil (list "Skeletons" (nreverse menu)))) + (setq erlang-menu-items + (erlang-menu-add-above 'erlang-menu-skel-items + 'erlang-menu-version-items + erlang-menu-items)) + (erlang-menu-init)))) (defun erlang-skel-make-menu-item (skel) (let ((func (intern (concat "tempo-template-erlang-" (nth 1 skel))))) (cond ((null (nth 3 skel)) - (list (car skel) func)) - (t - (list (car skel) - (list 'lambda '() - '(interactive) - (list 'funcall - (list 'quote (nth 3 skel)) - (list 'quote func)))))))) + (list (car skel) func)) + (t + (list (car skel) + (list 'lambda '() + '(interactive) + (list 'funcall + (list 'quote (nth 3 skel)) + (list 'quote func)))))))) ;; Functions designed to be added to the skeleton menu. ;; (Not normally used) @@ -2352,12 +2352,12 @@ Technically, this function returns the `tempo' attribute`(l ...)' which can contain other `tempo' attributes. Please see the function `tempo-define-template' for a description of the `(l ...)' attribute." (let ((res '()) - entry) + entry) (while args (setq entry (car args)) (while entry - (setq res (cons (car entry) res)) - (setq entry (cdr entry))) + (setq res (cons (car entry) res)) + (setq entry (cdr entry))) (setq args (cdr args))) (cons 'l (nreverse res)))) @@ -2366,25 +2366,25 @@ can contain other `tempo' attributes. Please see the function (defun erlang-skel-separator (&optional percent) "Return a comment separator." (let ((percent (or percent 3))) - (concat (make-string percent ?%) - (make-string (- erlang-skel-separator-length percent) ?-) - "\n"))) + (concat (make-string percent ?%) + (make-string (- erlang-skel-separator-length percent) ?-) + "\n"))) (defun erlang-skel-double-separator (&optional percent) "Return a comment separator." (let ((percent (or percent 3))) - (concat (make-string percent ?%) - (make-string (- erlang-skel-separator-length percent) ?=) - "\n"))) + (concat (make-string percent ?%) + (make-string (- erlang-skel-separator-length percent) ?=) + "\n"))) (defun erlang-skel-dd-mmm-yyyy () "Return the current date as a string in \"DD Mon YYYY\" form. The first character of DD is space if the value is less than 10." (let ((date (current-time-string))) (format "%2d %s %s" - (erlang-string-to-int (substring date 8 10)) - (substring date 4 7) - (substring date -4)))) + (erlang-string-to-int (substring date 8 10)) + (substring date 4 7) + (substring date -4)))) ;; Indentation code: @@ -2397,23 +2397,23 @@ rigidly along with this one." ;; If arg, always indent this line as Erlang ;; and shift remaining lines of clause the same amount. (let ((shift-amt (erlang-indent-line)) - beg end) - (save-excursion - (if erlang-tab-always-indent - (beginning-of-line)) - (setq beg (point)) - (erlang-end-of-clause 1) - (setq end (point)) - (goto-char beg) - (forward-line 1) - (setq beg (point))) - (if (> end beg) - (indent-code-rigidly beg end shift-amt "\n"))) + beg end) + (save-excursion + (if erlang-tab-always-indent + (beginning-of-line)) + (setq beg (point)) + (erlang-end-of-clause 1) + (setq end (point)) + (goto-char beg) + (forward-line 1) + (setq beg (point))) + (if (> end beg) + (indent-code-rigidly beg end shift-amt "\n"))) (if (and (not erlang-tab-always-indent) - (save-excursion - (skip-chars-backward " \t") - (not (bolp)))) - (insert-tab) + (save-excursion + (skip-chars-backward " \t") + (not (bolp)))) + (insert-tab) (erlang-indent-line)))) @@ -2421,33 +2421,33 @@ rigidly along with this one." "Indent current line as Erlang code. Return the amount the indentation changed by." (let ((pos (- (point-max) (point))) - indent beg - shift-amt) + indent beg + shift-amt) (beginning-of-line 1) (setq beg (point)) (skip-chars-forward " \t") (cond ((looking-at "%") - (setq indent (funcall comment-indent-function)) - (setq shift-amt (- indent (current-column)))) - (t - (setq indent (erlang-calculate-indent)) - (cond ((null indent) - (setq indent (current-indentation))) - ((eq indent t) - ;; This should never occur here. - (error "Erlang mode error")) - ;;((= (char-syntax (following-char)) ?\)) - ;; (setq indent (1- indent))) - ) - (setq shift-amt (- indent (current-column))))) + (setq indent (funcall comment-indent-function)) + (setq shift-amt (- indent (current-column)))) + (t + (setq indent (erlang-calculate-indent)) + (cond ((null indent) + (setq indent (current-indentation))) + ((eq indent t) + ;; This should never occur here. + (error "Erlang mode error")) + ;;((= (char-syntax (following-char)) ?\)) + ;; (setq indent (1- indent))) + ) + (setq shift-amt (- indent (current-column))))) (if (zerop shift-amt) - nil + nil (delete-region beg (point)) (indent-to indent)) ;; If initial point was within line's indentation, position ;; after the indentation. Else stay at same point in text. (if (> (- (point-max) pos) (point)) - (goto-char (- (point-max) pos))) + (goto-char (- (point-max) pos))) (run-hooks 'erlang-indent-line-hook) shift-amt)) @@ -2459,11 +2459,11 @@ This is automagically called by the user level function `indent-region'." (interactive "r") (save-excursion (let ((case-fold-search nil) - (continue t) - (from-end (- (point-max) end)) - indent-point;; The beginning of the current line - indent;; The indent amount - state) + (continue t) + (from-end (- (point-max) end)) + indent-point;; The beginning of the current line + indent;; The indent amount + state) (goto-char beg) (beginning-of-line) (setq indent-point (point)) @@ -2477,39 +2477,39 @@ This is automagically called by the user level function `indent-region'." (error "Illegal syntax")))) ;; Indent every line in the region (while continue - (goto-char indent-point) - (skip-chars-forward " \t") - (cond ((looking-at "%") - ;; Do not use our stack to help the user to customize - ;; comment indentation. - (setq indent (funcall comment-indent-function))) - ((looking-at "$") - ;; Don't indent empty lines. - (setq indent 0)) - (t - (setq indent - (save-excursion - (erlang-calculate-stack-indent (point) state))) - (cond ((null indent) - (setq indent (current-indentation))) - ((eq indent t) - ;; This should never occur here. - (error "Erlang mode error")) - ;;((= (char-syntax (following-char)) ?\)) - ;; (setq indent (1- indent))) - ))) - (if (zerop (- indent (current-column))) - nil - (delete-region indent-point (point)) - (indent-to indent)) - ;; Find the next line in the region - (goto-char indent-point) - (save-excursion - (forward-line 1) - (setq indent-point (point))) - (if (>= from-end (- (point-max) indent-point)) - (setq continue nil) - (while (< (point) indent-point) + (goto-char indent-point) + (skip-chars-forward " \t") + (cond ((looking-at "%") + ;; Do not use our stack to help the user to customize + ;; comment indentation. + (setq indent (funcall comment-indent-function))) + ((looking-at "$") + ;; Don't indent empty lines. + (setq indent 0)) + (t + (setq indent + (save-excursion + (erlang-calculate-stack-indent (point) state))) + (cond ((null indent) + (setq indent (current-indentation))) + ((eq indent t) + ;; This should never occur here. + (error "Erlang mode error")) + ;;((= (char-syntax (following-char)) ?\)) + ;; (setq indent (1- indent))) + ))) + (if (zerop (- indent (current-column))) + nil + (delete-region indent-point (point)) + (indent-to indent)) + ;; Find the next line in the region + (goto-char indent-point) + (save-excursion + (forward-line 1) + (setq indent-point (point))) + (if (>= from-end (- (point-max) indent-point)) + (setq continue nil) + (while (< (point) indent-point) (let ((pt (point))) (setq state (erlang-partial-parse pt indent-point state)) @@ -2531,7 +2531,7 @@ This is automagically called by the user level function `indent-region'." (interactive) (save-excursion (let ((end (progn (erlang-end-of-function 1) (point))) - (beg (progn (erlang-beginning-of-function 1) (point)))) + (beg (progn (erlang-beginning-of-function 1) (point)))) (erlang-indent-region beg end)))) @@ -2540,7 +2540,7 @@ This is automagically called by the user level function `indent-region'." (interactive) (save-excursion (let ((end (progn (erlang-end-of-clause 1) (point))) - (beg (progn (erlang-beginning-of-clause 1) (point)))) + (beg (progn (erlang-beginning-of-clause 1) (point)))) (erlang-indent-region beg end)))) @@ -2555,11 +2555,11 @@ This is automagically called by the user level function `indent-region'." Return nil if line starts inside string, t if in a comment." (save-excursion (let ((indent-point (point)) - (case-fold-search nil) - (state nil)) + (case-fold-search nil) + (state nil)) (if parse-start - (goto-char parse-start) - (erlang-beginning-of-clause)) + (goto-char parse-start) + (erlang-beginning-of-clause)) (while (< (point) indent-point) (let ((pt (point))) (setq state (erlang-partial-parse pt indent-point state)) @@ -2574,25 +2574,25 @@ Return nil if line starts inside string, t if in a comment." (save-excursion (let ((starting-point (point)) - (case-fold-search nil) - (state nil)) + (case-fold-search nil) + (state nil)) (erlang-beginning-of-clause) (while (< (point) starting-point) - (setq state (erlang-partial-parse (point) starting-point state))) + (setq state (erlang-partial-parse (point) starting-point state))) (message "%S" state)))) (defun erlang-partial-parse (from to &optional state) "Parse Erlang syntax starting at FROM until TO, with an optional STATE. Value is list (stack token-start token-type in-what)." - (goto-char from) ; Start at the beginning + (goto-char from) ; Start at the beginning (erlang-skip-blank to) (let ((cs (char-syntax (following-char))) - (stack (car state)) - (token (point)) - in-what) - (cond - + (stack (car state)) + (token (point)) + in-what) + (cond + ;; Done: Return previous state. ((>= token to) (setq token (nth 1 state)) @@ -2602,230 +2602,230 @@ Value is list (stack token-start token-type in-what)." ;; Word constituent: check and handle keywords. ((= cs ?w) (cond ((looking-at "\\(end\\|after\\)[^_a-zA-Z0-9]") - ;; Must pop top icr layer, `after' will push a new - ;; layer next. - (progn - (while (and stack (eq (car (car stack)) '->)) - (erlang-pop stack)) - (if (and stack (memq (car (car stack)) '(icr begin fun try))) - (erlang-pop stack)))) - ((looking-at "catch\\b.*of") - t) - ((looking-at "catch\\b\\s *\\($\\|%\\|.*->\\)") - ;; Must pop top icr layer, `catch' in try/catch - ;;will push a new layer next. - (progn - (while (and stack (eq (car (car stack)) '->)) - (erlang-pop stack)) - (if (and stack (memq (car (car stack)) '(icr begin try))) - (erlang-pop stack)))) - ) + ;; Must pop top icr layer, `after' will push a new + ;; layer next. + (progn + (while (and stack (eq (car (car stack)) '->)) + (erlang-pop stack)) + (if (and stack (memq (car (car stack)) '(icr begin fun try))) + (erlang-pop stack)))) + ((looking-at "catch\\b.*of") + t) + ((looking-at "catch\\b\\s *\\($\\|%\\|.*->\\)") + ;; Must pop top icr layer, `catch' in try/catch + ;;will push a new layer next. + (progn + (while (and stack (eq (car (car stack)) '->)) + (erlang-pop stack)) + (if (and stack (memq (car (car stack)) '(icr begin try))) + (erlang-pop stack)))) + ) (cond ((looking-at "\\(if\\|case\\|receive\\)[^_a-zA-Z0-9]") - ;; Must push a new icr (if/case/receive) layer. - (erlang-push (list 'icr token (current-column)) stack)) - ((looking-at "\\(try\\|after\\)[^_a-zA-Z0-9]") - ;; Must handle separately, try catch or try X of -> catch - ;; same for `after', it could be - ;; receive after Time -> X end, or - ;; try after X end - (erlang-push (list 'try token (current-column)) stack)) - ((looking-at "\\(of\\)[^_a-zA-Z0-9]") - ;; Must handle separately, try X of -> catch - (if (and stack (eq (car (car stack)) 'try)) - (let ((try-column (nth 2 (car stack))) - (try-pos (nth 1 (car stack)))) - (erlang-pop stack) - (erlang-push (list 'icr try-pos try-column) stack)))) - - ((looking-at "\\(fun\\)[^_a-zA-Z0-9]") - ;; Push a new layer if we are defining a `fun' - ;; expression, not when we are refering an existing - ;; function. 'fun's defines are only indented one level now. - (if (save-excursion - (goto-char (match-end 1)) - (erlang-skip-blank to) - ;; Use erlang-variable-regexp here to look for an - ;; optional variable name to match EEP37 named funs. - (if (looking-at erlang-variable-regexp) - (progn - (goto-char (match-end 0)) - (erlang-skip-blank to))) - (eq (following-char) ?\()) - (erlang-push (list 'fun token (current-column)) stack))) - ((looking-at "\\(begin\\)[^_a-zA-Z0-9]") - (erlang-push (list 'begin token (current-column)) stack)) - ;; Normal when case - ;;((looking-at "when\\s ") - ;;((looking-at "when\\s *\\($\\|%\\)") - ((looking-at "when[^_a-zA-Z0-9]") - (erlang-push (list 'when token (current-column)) stack)) - ((looking-at "catch\\b.*of") - t) - ((looking-at "catch\\b\\s *\\($\\|%\\|.*->\\)") - (erlang-push (list 'icr token (current-column)) stack)) - ;;(erlang-push (list '-> token (current-column)) stack)) - ;;((looking-at "^of$") - ;; (erlang-push (list 'icr token (current-column)) stack) - ;;(erlang-push (list '-> token (current-column)) stack)) - ) + ;; Must push a new icr (if/case/receive) layer. + (erlang-push (list 'icr token (current-column)) stack)) + ((looking-at "\\(try\\|after\\)[^_a-zA-Z0-9]") + ;; Must handle separately, try catch or try X of -> catch + ;; same for `after', it could be + ;; receive after Time -> X end, or + ;; try after X end + (erlang-push (list 'try token (current-column)) stack)) + ((looking-at "\\(of\\)[^_a-zA-Z0-9]") + ;; Must handle separately, try X of -> catch + (if (and stack (eq (car (car stack)) 'try)) + (let ((try-column (nth 2 (car stack))) + (try-pos (nth 1 (car stack)))) + (erlang-pop stack) + (erlang-push (list 'icr try-pos try-column) stack)))) + + ((looking-at "\\(fun\\)[^_a-zA-Z0-9]") + ;; Push a new layer if we are defining a `fun' + ;; expression, not when we are refering an existing + ;; function. 'fun's defines are only indented one level now. + (if (save-excursion + (goto-char (match-end 1)) + (erlang-skip-blank to) + ;; Use erlang-variable-regexp here to look for an + ;; optional variable name to match EEP37 named funs. + (if (looking-at erlang-variable-regexp) + (progn + (goto-char (match-end 0)) + (erlang-skip-blank to))) + (eq (following-char) ?\()) + (erlang-push (list 'fun token (current-column)) stack))) + ((looking-at "\\(begin\\)[^_a-zA-Z0-9]") + (erlang-push (list 'begin token (current-column)) stack)) + ;; Normal when case + ;;((looking-at "when\\s ") + ;;((looking-at "when\\s *\\($\\|%\\)") + ((looking-at "when[^_a-zA-Z0-9]") + (erlang-push (list 'when token (current-column)) stack)) + ((looking-at "catch\\b.*of") + t) + ((looking-at "catch\\b\\s *\\($\\|%\\|.*->\\)") + (erlang-push (list 'icr token (current-column)) stack)) + ;;(erlang-push (list '-> token (current-column)) stack)) + ;;((looking-at "^of$") + ;; (erlang-push (list 'icr token (current-column)) stack) + ;;(erlang-push (list '-> token (current-column)) stack)) + ) (forward-sexp 1)) - ;; String: Try to skip over it. (Catch error if not complete.) - ((= cs ?\") - (condition-case nil - (progn - (forward-sexp 1) - (if (> (point) to) - (progn - (setq in-what 'string) - (goto-char to)))) - (error - (setq in-what 'string) - (goto-char to)))) + ;; String: Try to skip over it. (Catch error if not complete.) + ((= cs ?\") + (condition-case nil + (progn + (forward-sexp 1) + (if (> (point) to) + (progn + (setq in-what 'string) + (goto-char to)))) + (error + (setq in-what 'string) + (goto-char to)))) ;; Expression prefix e.i. $ or ^ (Note ^ can be in the character ;; literal $^ or part of string and $ outside of a string denotes ;; a character literal) ((= cs ?') - (cond + (cond ((= (following-char) ?\") ;; $ or ^ was the last char in a string - (forward-char 1)) + (forward-char 1)) (t - ;; Maybe a character literal, quote the next char to avoid - ;; situations as $" being seen as the begining of a string. - ;; Note the quoting something in the middle of a string is harmless. - (quote (following-char)) - (forward-char 1)))) + ;; Maybe a character literal, quote the next char to avoid + ;; situations as $" being seen as the begining of a string. + ;; Note the quoting something in the middle of a string is harmless. + (quote (following-char)) + (forward-char 1)))) ;; Symbol constituent or punctuation - + ((memq cs '(?. ?_)) - (cond - + (cond + ;; Clause end ((= (following-char) ?\;) - (if (eq (car (car (last stack))) 'spec) - (while (memq (car (car stack)) '(when ::)) - (erlang-pop stack))) - (if (and stack (eq (car (car stack)) '->)) - (erlang-pop stack)) - (forward-char 1)) - + (if (eq (car (car (last stack))) 'spec) + (while (memq (car (car stack)) '(when ::)) + (erlang-pop stack))) + (if (and stack (eq (car (car stack)) '->)) + (erlang-pop stack)) + (forward-char 1)) + ;; Parameter separator ((looking-at ",") - (forward-char 1) - (if (and stack (eq (car (car stack)) '::)) - ;; Type or spec - (erlang-pop stack))) + (forward-char 1) + (if (and stack (eq (car (car stack)) '::)) + ;; Type or spec + (erlang-pop stack))) ;; Function end ((looking-at "\\.\\(\\s \\|\n\\|\\s<\\)") - (setq stack nil) - (forward-char 1)) - + (setq stack nil) + (forward-char 1)) + ;; Function head ((looking-at "->") - (if (and stack (eq (car (car stack)) 'when)) - (erlang-pop stack)) - (erlang-push (list '-> token (current-column)) stack) - (forward-char 2)) - + (if (and stack (eq (car (car stack)) 'when)) + (erlang-pop stack)) + (erlang-push (list '-> token (current-column)) stack) + (forward-char 2)) + ;; List-comprehension divider ((looking-at "||") - (erlang-push (list '|| token (current-column)) stack) - (forward-char 2)) + (erlang-push (list '|| token (current-column)) stack) + (forward-char 2)) ;; Bit-syntax open. Note that map syntax allows "<<" to follow ":=" ;; or "=>" without intervening whitespace, so handle that case here ((looking-at "\\(:=\\|=>\\)?<<") - (erlang-push (list '<< token (current-column)) stack) - (forward-char (- (match-end 0) (match-beginning 0)))) - + (erlang-push (list '<< token (current-column)) stack) + (forward-char (- (match-end 0) (match-beginning 0)))) + ;; Bit-syntax close ((looking-at ">>") - (while (memq (car (car stack)) '(|| ->)) - (erlang-pop stack)) - (cond ((eq (car (car stack)) '<<) - (erlang-pop stack)) - ((memq (car (car stack)) '(icr begin fun)) - (error "Missing `end'")) - (t - (error "Unbalanced parentheses"))) - (forward-char 2)) - + (while (memq (car (car stack)) '(|| ->)) + (erlang-pop stack)) + (cond ((eq (car (car stack)) '<<) + (erlang-pop stack)) + ((memq (car (car stack)) '(icr begin fun)) + (error "Missing `end'")) + (t + (error "Unbalanced parentheses"))) + (forward-char 2)) + ;; Macro ((= (following-char) ??) - ;; Skip over the ? - (forward-char 1) - ) + ;; Skip over the ? + (forward-char 1) + ) ;; Type spec's ((looking-at "-type\\s \\|-opaque\\s ") - (if stack - (forward-char 1) - (erlang-push (list 'icr token (current-column)) stack) - (forward-char 6))) + (if stack + (forward-char 1) + (erlang-push (list 'icr token (current-column)) stack) + (forward-char 6))) ((looking-at "-spec\\s ") - (if stack - (forward-char 1) - (forward-char 6) - (skip-chars-forward "^(\n") - (erlang-push (list 'spec (point) (current-column)) stack) - )) + (if stack + (forward-char 1) + (forward-char 6) + (skip-chars-forward "^(\n") + (erlang-push (list 'spec (point) (current-column)) stack) + )) ;; Type spec delimiter ((looking-at "::") - (erlang-push (list ':: token (current-column)) stack) - (forward-char 2)) - - ;; Don't follow through in the clause below - ;; '|' don't need spaces around it + (erlang-push (list ':: token (current-column)) stack) + (forward-char 2)) + + ;; Don't follow through in the clause below + ;; '|' don't need spaces around it ((looking-at "|") - (forward-char 1)) - + (forward-char 1)) + ;; Other punctuation: Skip over it and any following punctuation ((= cs ?.) - ;; Skip over all characters in the operand. - (skip-syntax-forward ".")) - + ;; Skip over all characters in the operand. + (skip-syntax-forward ".")) + ;; Other char: Skip over it. (t - (forward-char 1)))) - + (forward-char 1)))) + ;; Open parenthesis ((= cs ?\() (erlang-push (list '\( token (current-column)) stack) (forward-char 1)) - + ;; Close parenthesis ((= cs ?\)) (while (memq (car (car stack)) '(|| -> :: when)) - (erlang-pop stack)) + (erlang-pop stack)) (cond ((eq (car (car stack)) '\() - (erlang-pop stack) - (if (and (eq (car (car stack)) 'fun) - (or (eq (car (car (last stack))) 'spec) - (eq (car (car (cdr stack))) '::))) ;; -type() - ;; Inside fun type def ') closes fun definition - (erlang-pop stack))) - ((eq (car (car stack)) 'icr) - (erlang-pop stack) - ;; Normal catch not try-catch might have caused icr - ;; and then incr should be removed and is not an error. - (if (eq (car (car stack)) '\() - (erlang-pop stack) - (error "Missing `end'") - )) - ((eq (car (car stack)) 'begin) - (error "Missing `end'")) - (t - (error "Unbalanced parenthesis")) - ) - (forward-char 1)) - + (erlang-pop stack) + (if (and (eq (car (car stack)) 'fun) + (or (eq (car (car (last stack))) 'spec) + (eq (car (car (cdr stack))) '::))) ;; -type() + ;; Inside fun type def ') closes fun definition + (erlang-pop stack))) + ((eq (car (car stack)) 'icr) + (erlang-pop stack) + ;; Normal catch not try-catch might have caused icr + ;; and then incr should be removed and is not an error. + (if (eq (car (car stack)) '\() + (erlang-pop stack) + (error "Missing `end'") + )) + ((eq (car (car stack)) 'begin) + (error "Missing `end'")) + (t + (error "Unbalanced parenthesis")) + ) + (forward-char 1)) + ;; Character quote: Skip it and the quoted char. ((= cs ?/) (forward-char 2)) - + ;; Character escape: Skip it and the escape sequence. ((= cs ?\\) (forward-char 1) @@ -2854,49 +2854,49 @@ Return nil if inside string, t if in a comment." ((eq (car stack-top) '\() ;; Element of list, tuple or part of an expression, (cond ((null erlang-argument-indent) - ;; indent to next column. - (1+ (nth 2 stack-top))) - ((= (char-syntax (following-char)) ?\)) - (goto-char (nth 1 stack-top)) - (cond ((looking-at "[({]\\s *\\($\\|%\\)") - ;; Line ends with parenthesis. - (let ((previous (erlang-indent-find-preceding-expr)) - (stack-pos (nth 2 stack-top))) - (if (>= previous stack-pos) stack-pos - (- (+ previous erlang-argument-indent) 1)))) - (t - (nth 2 stack-top)))) - ((= (following-char) ?,) - ;; a comma at the start of the line: line up with opening parenthesis. - (nth 2 stack-top)) - (t - (goto-char (nth 1 stack-top)) - (let ((base (cond ((looking-at "[({]\\s *\\($\\|%\\)") - ;; Line ends with parenthesis. - (erlang-indent-parenthesis (nth 2 stack-top))) - (t - ;; Indent to the same column as the first - ;; argument. - (goto-char (1+ (nth 1 stack-top))) - (skip-chars-forward " \t") - (current-column))))) - (erlang-indent-standard indent-point token base 't))))) - ;; - ((eq (car stack-top) '<<) - ;; Element of binary (possible comprehension) expression, - (cond ((null erlang-argument-indent) - ;; indent to next column. - (+ 2 (nth 2 stack-top))) - ((looking-at "\\(>>\\)[^_a-zA-Z0-9]") - (nth 2 stack-top)) - (t - (goto-char (nth 1 stack-top)) - ;; Indent to the same column as the first - ;; argument. - (goto-char (+ 2 (nth 1 stack-top))) - (skip-chars-forward " \t") - (current-column)))) - + ;; indent to next column. + (1+ (nth 2 stack-top))) + ((= (char-syntax (following-char)) ?\)) + (goto-char (nth 1 stack-top)) + (cond ((looking-at "[({]\\s *\\($\\|%\\)") + ;; Line ends with parenthesis. + (let ((previous (erlang-indent-find-preceding-expr)) + (stack-pos (nth 2 stack-top))) + (if (>= previous stack-pos) stack-pos + (- (+ previous erlang-argument-indent) 1)))) + (t + (nth 2 stack-top)))) + ((= (following-char) ?,) + ;; a comma at the start of the line: line up with opening parenthesis. + (nth 2 stack-top)) + (t + (goto-char (nth 1 stack-top)) + (let ((base (cond ((looking-at "[({]\\s *\\($\\|%\\)") + ;; Line ends with parenthesis. + (erlang-indent-parenthesis (nth 2 stack-top))) + (t + ;; Indent to the same column as the first + ;; argument. + (goto-char (1+ (nth 1 stack-top))) + (skip-chars-forward " \t") + (current-column))))) + (erlang-indent-standard indent-point token base 't))))) + ;; + ((eq (car stack-top) '<<) + ;; Element of binary (possible comprehension) expression, + (cond ((null erlang-argument-indent) + ;; indent to next column. + (+ 2 (nth 2 stack-top))) + ((looking-at "\\(>>\\)[^_a-zA-Z0-9]") + (nth 2 stack-top)) + (t + (goto-char (nth 1 stack-top)) + ;; Indent to the same column as the first + ;; argument. + (goto-char (+ 2 (nth 1 stack-top))) + (skip-chars-forward " \t") + (current-column)))) + ((memq (car stack-top) '(icr fun spec)) ;; The default indentation is the column of the option ;; directly following the keyword. (This does not apply to @@ -2907,156 +2907,156 @@ Return nil if inside string, t if in a comment." ;; `after' should be indented to the same level as the ;; corresponding receive. (cond ((looking-at "\\(after\\|of\\)\\($\\|[^_a-zA-Z0-9]\\)") - (nth 2 stack-top)) - ((looking-at "when[^_a-zA-Z0-9]") - ;; Handling one when part - (+ (nth 2 stack-top) erlang-indent-level erlang-indent-guard)) - (t - (save-excursion - (goto-char (nth 1 stack-top)) - (if (looking-at "case[^_a-zA-Z0-9]") - (+ (nth 2 stack-top) erlang-indent-level) - (skip-chars-forward "a-z") - (skip-chars-forward " \t") - (if (memq (following-char) '(?% ?\n)) - (+ (nth 2 stack-top) erlang-indent-level) - (current-column)))))) + (nth 2 stack-top)) + ((looking-at "when[^_a-zA-Z0-9]") + ;; Handling one when part + (+ (nth 2 stack-top) erlang-indent-level erlang-indent-guard)) + (t + (save-excursion + (goto-char (nth 1 stack-top)) + (if (looking-at "case[^_a-zA-Z0-9]") + (+ (nth 2 stack-top) erlang-indent-level) + (skip-chars-forward "a-z") + (skip-chars-forward " \t") + (if (memq (following-char) '(?% ?\n)) + (+ (nth 2 stack-top) erlang-indent-level) + (current-column)))))) ) - ((and (eq (car stack-top) '||) (looking-at "\\(]\\|>>\\)[^_a-zA-Z0-9]")) - (nth 2 (car (cdr stack)))) + ((and (eq (car stack-top) '||) (looking-at "\\(]\\|>>\\)[^_a-zA-Z0-9]")) + (nth 2 (car (cdr stack)))) ;; Real indentation, where operators create extra indentation etc. ((memq (car stack-top) '(-> || try begin)) - (if (looking-at "\\(of\\)[^_a-zA-Z0-9]") - (nth 2 stack-top) - (goto-char (nth 1 stack-top)) - ;; Check if there is more code after the '->' on the - ;; same line. If so use this indentation as base, else - ;; use parent indentation + 2 * level as base. - (let ((off erlang-indent-level) - (skip 2)) - (cond ((null (cdr stack))) ; Top level in function. - ((eq (car stack-top) 'begin) - (setq skip 5)) - ((eq (car stack-top) 'try) - (setq skip 5)) - ((eq (car stack-top) '->) - ;; If in fun definition use standard indent level not double - ;;(if (not (eq (car (car (cdr stack))) 'fun)) - ;; Removed it made multi clause fun's look to bad - (setq off (* 2 erlang-indent-level)))) ;; ) - (let ((base (erlang-indent-find-base stack indent-point off skip))) - ;; Special cases - (goto-char indent-point) - (cond ((looking-at "\\(end\\|after\\)\\($\\|[^_a-zA-Z0-9]\\)") - (if (eq (car stack-top) '->) - (erlang-pop stack)) - (if stack - (erlang-caddr (car stack)) - 0)) - ((looking-at "catch\\b\\($\\|[^_a-zA-Z0-9]\\)") - ;; Are we in a try - (let ((start (if (eq (car stack-top) '->) - (car (cdr stack)) - stack-top))) - (if (null start) nil - (goto-char (nth 1 start))) - (cond ((looking-at "try\\($\\|[^_a-zA-Z0-9]\\)") - (progn - (if (eq (car stack-top) '->) - (erlang-pop stack)) - (if stack - (erlang-caddr (car stack)) - 0))) - (t (erlang-indent-standard indent-point token base 'nil))))) ;; old catch - (t - (erlang-indent-standard indent-point token base 'nil) - )))) - )) - ((eq (car stack-top) 'when) - (goto-char (nth 1 stack-top)) - (if (looking-at "when\\s *\\($\\|%\\)") - (progn - (erlang-pop stack) - (if (and stack (memq (nth 0 (car stack)) '(icr fun))) - (progn - (goto-char (nth 1 (car stack))) - (+ (nth 2 (car stack)) erlang-indent-guard - ;; receive XYZ or receive - ;; XYZ - ;; This if thing does not seem to be needed - ;;(if (looking-at "[a-z]+\\s *\\($\\|%\\)") - ;; erlang-indent-level - ;; (* 2 erlang-indent-level)))) - (* 2 erlang-indent-level))) - ;;erlang-indent-level)) - (+ erlang-indent-level erlang-indent-guard))) + (if (looking-at "\\(of\\)[^_a-zA-Z0-9]") + (nth 2 stack-top) + (goto-char (nth 1 stack-top)) + ;; Check if there is more code after the '->' on the + ;; same line. If so use this indentation as base, else + ;; use parent indentation + 2 * level as base. + (let ((off erlang-indent-level) + (skip 2)) + (cond ((null (cdr stack))) ; Top level in function. + ((eq (car stack-top) 'begin) + (setq skip 5)) + ((eq (car stack-top) 'try) + (setq skip 5)) + ((eq (car stack-top) '->) + ;; If in fun definition use standard indent level not double + ;;(if (not (eq (car (car (cdr stack))) 'fun)) + ;; Removed it made multi clause fun's look to bad + (setq off (* 2 erlang-indent-level)))) ;; ) + (let ((base (erlang-indent-find-base stack indent-point off skip))) + ;; Special cases + (goto-char indent-point) + (cond ((looking-at "\\(end\\|after\\)\\($\\|[^_a-zA-Z0-9]\\)") + (if (eq (car stack-top) '->) + (erlang-pop stack)) + (if stack + (erlang-caddr (car stack)) + 0)) + ((looking-at "catch\\b\\($\\|[^_a-zA-Z0-9]\\)") + ;; Are we in a try + (let ((start (if (eq (car stack-top) '->) + (car (cdr stack)) + stack-top))) + (if (null start) nil + (goto-char (nth 1 start))) + (cond ((looking-at "try\\($\\|[^_a-zA-Z0-9]\\)") + (progn + (if (eq (car stack-top) '->) + (erlang-pop stack)) + (if stack + (erlang-caddr (car stack)) + 0))) + (t (erlang-indent-standard indent-point token base 'nil))))) ;; old catch + (t + (erlang-indent-standard indent-point token base 'nil) + )))) + )) + ((eq (car stack-top) 'when) + (goto-char (nth 1 stack-top)) + (if (looking-at "when\\s *\\($\\|%\\)") + (progn + (erlang-pop stack) + (if (and stack (memq (nth 0 (car stack)) '(icr fun))) + (progn + (goto-char (nth 1 (car stack))) + (+ (nth 2 (car stack)) erlang-indent-guard + ;; receive XYZ or receive + ;; XYZ + ;; This if thing does not seem to be needed + ;;(if (looking-at "[a-z]+\\s *\\($\\|%\\)") + ;; erlang-indent-level + ;; (* 2 erlang-indent-level)))) + (* 2 erlang-indent-level))) + ;;erlang-indent-level)) + (+ erlang-indent-level erlang-indent-guard))) ;; "when" is followed by code, let's indent to the same ;; column. (forward-char 4) ; Skip "when" (skip-chars-forward " \t") (current-column))) - ;; Type and Spec indentation - ((eq (car stack-top) '::) - (if (looking-at "[},)]") - ;; Closing function spec, record definition with types, + ;; Type and Spec indentation + ((eq (car stack-top) '::) + (if (looking-at "[},)]") + ;; Closing function spec, record definition with types, ;; or a comma at the start of the line - ;; pop stack and recurse - (erlang-calculate-stack-indent indent-point - (cons (erlang-pop stack) (cdr state))) - (cond ((null erlang-argument-indent) - ;; indent to next column. - (+ 2 (nth 2 stack-top))) - ((looking-at "::[^_a-zA-Z0-9]") - (nth 2 stack-top)) - (t - (let ((start-alternativ (if (looking-at "|") 2 0))) - (goto-char (nth 1 stack-top)) - (- (cond ((looking-at "::\\s *\\($\\|%\\)") - ;; Line ends with :: - (if (eq (car (car (last stack))) 'spec) - (+ (erlang-indent-find-preceding-expr 1) - erlang-argument-indent) - (+ (erlang-indent-find-preceding-expr 2) - erlang-argument-indent))) - (t - ;; Indent to the same column as the first - ;; argument. - (goto-char (+ 2 (nth 1 stack-top))) - (skip-chars-forward " \t") - (current-column))) start-alternativ)))))) - ))) + ;; pop stack and recurse + (erlang-calculate-stack-indent indent-point + (cons (erlang-pop stack) (cdr state))) + (cond ((null erlang-argument-indent) + ;; indent to next column. + (+ 2 (nth 2 stack-top))) + ((looking-at "::[^_a-zA-Z0-9]") + (nth 2 stack-top)) + (t + (let ((start-alternativ (if (looking-at "|") 2 0))) + (goto-char (nth 1 stack-top)) + (- (cond ((looking-at "::\\s *\\($\\|%\\)") + ;; Line ends with :: + (if (eq (car (car (last stack))) 'spec) + (+ (erlang-indent-find-preceding-expr 1) + erlang-argument-indent) + (+ (erlang-indent-find-preceding-expr 2) + erlang-argument-indent))) + (t + ;; Indent to the same column as the first + ;; argument. + (goto-char (+ 2 (nth 1 stack-top))) + (skip-chars-forward " \t") + (current-column))) start-alternativ)))))) + ))) (defun erlang-indent-standard (indent-point token base inside-parenthesis) "Standard indent when in blocks or tuple or arguments. Look at last thing to see in what state we are, move relative to the base." - (goto-char token) + (goto-char token) (cond ((looking-at "||\\|,\\|->\\||") - base) - ((erlang-at-keyword) - (+ (current-column) erlang-indent-level)) - ((or (= (char-syntax (following-char)) ?.) - (erlang-at-operator)) - (+ base erlang-indent-level)) - (t - (goto-char indent-point) - (cond ((memq (following-char) '(?\( )) - ;; Function application. - (+ (erlang-indent-find-preceding-expr) - erlang-argument-indent)) - ;; Empty line, or end; treat it as the end of - ;; the block. (Here we have a choice: should - ;; the user be forced to reindent continued - ;; lines, or should the "end" be reindented?) - - ;; Avoid treating comments a continued line. - ((= (following-char) ?%) - base) - ;; Continued line (e.g. line beginning - ;; with an operator.) - (t - (if (or (erlang-at-operator) (not inside-parenthesis)) - (+ base erlang-indent-level) - base)))))) + base) + ((erlang-at-keyword) + (+ (current-column) erlang-indent-level)) + ((or (= (char-syntax (following-char)) ?.) + (erlang-at-operator)) + (+ base erlang-indent-level)) + (t + (goto-char indent-point) + (cond ((memq (following-char) '(?\( )) + ;; Function application. + (+ (erlang-indent-find-preceding-expr) + erlang-argument-indent)) + ;; Empty line, or end; treat it as the end of + ;; the block. (Here we have a choice: should + ;; the user be forced to reindent continued + ;; lines, or should the "end" be reindented?) + + ;; Avoid treating comments a continued line. + ((= (following-char) ?%) + base) + ;; Continued line (e.g. line beginning + ;; with an operator.) + (t + (if (or (erlang-at-operator) (not inside-parenthesis)) + (+ base erlang-indent-level) + base)))))) (defun erlang-indent-find-base (stack indent-point &optional offset skip) "Find the base column for current stack." @@ -3066,21 +3066,21 @@ Return nil if inside string, t if in a comment." (let* ((stack-top (car stack))) (goto-char (nth 1 stack-top)) (if (< skip (- (point-max) (point))) - (progn - (forward-char skip) - (if (looking-at "\\s *\\($\\|%\\)") - (progn - (if (memq (car stack-top) '(-> ||)) - (erlang-pop stack)) - ;; Take parent identation + offset, - ;; else just erlang-indent-level if no parent - (if stack - (+ (erlang-caddr (car stack)) - offset) - erlang-indent-level)) - (erlang-skip-blank indent-point) - (current-column))) - (+ (current-column) skip))))) + (progn + (forward-char skip) + (if (looking-at "\\s *\\($\\|%\\)") + (progn + (if (memq (car stack-top) '(-> ||)) + (erlang-pop stack)) + ;; Take parent identation + offset, + ;; else just erlang-indent-level if no parent + (if stack + (+ (erlang-caddr (car stack)) + offset) + erlang-indent-level)) + (erlang-skip-blank indent-point) + (current-column))) + (+ (current-column) skip))))) ;; Does not handle `begin' .. `end'. @@ -3099,51 +3099,51 @@ This assumes that the preceding expression is either simple ;; where the call (forward-sexp -1) will fail when point is at the `#'. (or (ignore-errors - ;; Needed to match the colon in "'foo':'bar'". - (cond ((eq (preceding-char) ?:) - (backward-char 1) - (forward-sexp -1) - (current-column)) - ((eq (preceding-char) ?#) - ;; We may now be at: - ;; - either a construction of a new record - ;; - or update of a record, in which case we want - ;; the column of the expression to be updated. - ;; - ;; To see which of the two cases we are at, we first - ;; move an expression backwards, check for keywords, - ;; then immediately an expression forwards. Moving - ;; backwards skips past tokens like `,' or `->', but - ;; when moving forwards again, we won't skip past such - ;; tokens. We use this: if, after having moved - ;; forwards, we're back where we started, then it was - ;; a record update. - ;; The check for keywords is to detect cases like: - ;; case Something of #record_construction{...} - (backward-char 1) - (let ((record-start (point)) - (record-start-col (current-column))) - (forward-sexp -1) - (let ((preceding-expr-col (current-column)) - ;; white space definition according to erl_scan - (white-space "\000-\040\200-\240")) - (if (erlang-at-keyword) - ;; The (forward-sexp -1) call moved past a keyword - (1+ record-start-col) - (forward-sexp 1) - (skip-chars-forward white-space record-start) - ;; Are we back where we started? If so, it was an update. - (if (= (point) record-start) - preceding-expr-col - (goto-char record-start) - (1+ (current-column))))))) - (t col))) + ;; Needed to match the colon in "'foo':'bar'". + (cond ((eq (preceding-char) ?:) + (backward-char 1) + (forward-sexp -1) + (current-column)) + ((eq (preceding-char) ?#) + ;; We may now be at: + ;; - either a construction of a new record + ;; - or update of a record, in which case we want + ;; the column of the expression to be updated. + ;; + ;; To see which of the two cases we are at, we first + ;; move an expression backwards, check for keywords, + ;; then immediately an expression forwards. Moving + ;; backwards skips past tokens like `,' or `->', but + ;; when moving forwards again, we won't skip past such + ;; tokens. We use this: if, after having moved + ;; forwards, we're back where we started, then it was + ;; a record update. + ;; The check for keywords is to detect cases like: + ;; case Something of #record_construction{...} + (backward-char 1) + (let ((record-start (point)) + (record-start-col (current-column))) + (forward-sexp -1) + (let ((preceding-expr-col (current-column)) + ;; white space definition according to erl_scan + (white-space "\000-\040\200-\240")) + (if (erlang-at-keyword) + ;; The (forward-sexp -1) call moved past a keyword + (1+ record-start-col) + (forward-sexp 1) + (skip-chars-forward white-space record-start) + ;; Are we back where we started? If so, it was an update. + (if (= (point) record-start) + preceding-expr-col + (goto-char record-start) + (1+ (current-column))))))) + (t col))) col)))) -(defun erlang-indent-parenthesis (stack-position) +(defun erlang-indent-parenthesis (stack-position) (let ((previous (erlang-indent-find-preceding-expr))) (if (> previous stack-position) - (+ stack-position erlang-argument-indent) + (+ stack-position erlang-argument-indent) (+ previous erlang-argument-indent)))) (defun erlang-skip-blank (&optional lim) @@ -3152,20 +3152,20 @@ This assumes that the preceding expression is either simple (let (stop) (while (and (not stop) (< (point) lim)) (cond ((= (following-char) ?%) - (skip-chars-forward "^\n" lim)) - ((= (following-char) ?\n) - (skip-chars-forward "\n" lim)) - ((looking-at "\\s ") - (if (re-search-forward "\\S " lim 'move) - (forward-char -1))) - (t - (setq stop t)))) + (skip-chars-forward "^\n" lim)) + ((= (following-char) ?\n) + (skip-chars-forward "\n" lim)) + ((looking-at "\\s ") + (if (re-search-forward "\\S " lim 'move) + (forward-char -1))) + (t + (setq stop t)))) stop)) (defun erlang-at-keyword () "Are we looking at an Erlang keyword which will increase indentation?" (looking-at (concat "\\(when\\|if\\|fun\\|case\\|begin\\|" - "of\\|receive\\|after\\|catch\\|try\\)\\b"))) + "of\\|receive\\|after\\|catch\\|try\\)\\b"))) (defun erlang-at-operator () "Are we looking at an Erlang operator?" @@ -3178,14 +3178,14 @@ This assumes that the preceding expression is either simple Used both by `indent-for-comment' and the Erlang specific indentation commands." (cond ((looking-at "%%%") 0) - ((looking-at "%%") - (or (erlang-calculate-indent) - (current-indentation))) - (t - (save-excursion - (skip-chars-backward " \t") - (max (if (bolp) 0 (1+ (current-column))) - comment-column))))) + ((looking-at "%%") + (or (erlang-calculate-indent) + (current-indentation))) + (t + (save-excursion + (skip-chars-backward " \t") + (max (if (bolp) 0 (1+ (current-column))) + comment-column))))) ;;; Erlang movement commands @@ -3213,18 +3213,18 @@ Return t unless search stops due to end of buffer." ;; that the regexp below includes the last character of the ;; previous line. (if (bobp) - (or (looking-at "\n") - (forward-char 1)) - (forward-char -1) - (if (looking-at "\\`\n") - (forward-char 1)))) + (or (looking-at "\n") + (forward-char 1)) + (forward-char -1) + (if (looking-at "\\`\n") + (forward-char 1)))) ;; The regexp matches a function header that isn't ;; included in a string. (and (re-search-forward "\\(\\`\\|\\`\n\\|[^\\]\n\\)\\(-?[a-z]\\|'\\|-\\)" - nil 'move (- arg)) + nil 'move (- arg)) (let ((beg (match-beginning 2))) - (and beg (goto-char beg)) - t))) + (and beg (goto-char beg)) + t))) (defun erlang-end-of-clause (&optional arg) "Move to the end of the current clause. @@ -3270,22 +3270,22 @@ Return t unless search stops due to end of buffer." ;; Search backward ((> arg 0) (while (and (> arg 0) - (and (erlang-beginning-of-clause 1) - (let ((start (point)) - (name (erlang-name-of-function)) - (arity (erlang-get-function-arity))) - ;; Note: "arity" is nil for e.g. "-import", hence - ;; two "-import" clauses are not considered to - ;; be part of the same function. - (while (and (erlang-beginning-of-clause 1) - (string-equal name - (erlang-name-of-function)) - arity - (equal arity - (erlang-get-function-arity))) - (setq start (point))) - (goto-char start) - t))) + (and (erlang-beginning-of-clause 1) + (let ((start (point)) + (name (erlang-name-of-function)) + (arity (erlang-get-function-arity))) + ;; Note: "arity" is nil for e.g. "-import", hence + ;; two "-import" clauses are not considered to + ;; be part of the same function. + (while (and (erlang-beginning-of-clause 1) + (string-equal name + (erlang-name-of-function)) + arity + (equal arity + (erlang-get-function-arity))) + (setq start (point))) + (goto-char start) + t))) (setq arg (1- arg)))) ;; Search forward ((< arg 0) @@ -3293,19 +3293,19 @@ Return t unless search stops due to end of buffer." (erlang-beginning-of-clause 1) ;; Step -arg functions forward. (while (and (< arg 0) - ;; Step one function forward, or stop if the end of - ;; the buffer was reached. Return t if we found the - ;; function. - (let ((name (erlang-name-of-function)) - (arity (erlang-get-function-arity)) - (found (erlang-beginning-of-clause -1))) - (while (and found - (string-equal name (erlang-name-of-function)) - arity - (equal arity - (erlang-get-function-arity))) - (setq found (erlang-beginning-of-clause -1))) - found)) + ;; Step one function forward, or stop if the end of + ;; the buffer was reached. Return t if we found the + ;; function. + (let ((name (erlang-name-of-function)) + (arity (erlang-get-function-arity)) + (found (erlang-beginning-of-clause -1))) + (while (and found + (string-equal name (erlang-name-of-function)) + arity + (equal arity + (erlang-get-function-arity))) + (setq found (erlang-beginning-of-clause -1))) + found)) (setq arg (1+ arg))))) (zerop arg)) @@ -3321,35 +3321,35 @@ With negative argument go towards the beginning of the buffer." ;; Forward (while (and (> arg 0) (< (point) (point-max))) (let ((pos (point))) - (while (progn - (if (and first - (progn - (forward-char 1) - (erlang-beginning-of-clause 1))) - nil - (or (bobp) (forward-char -1)) - (erlang-beginning-of-clause -1)) - (setq first nil) - (erlang-pass-over-function) - (skip-chars-forward " \t") - (if (looking-at "[%\n]") - (forward-line 1)) - (<= (point) pos)))) + (while (progn + (if (and first + (progn + (forward-char 1) + (erlang-beginning-of-clause 1))) + nil + (or (bobp) (forward-char -1)) + (erlang-beginning-of-clause -1)) + (setq first nil) + (erlang-pass-over-function) + (skip-chars-forward " \t") + (if (looking-at "[%\n]") + (forward-line 1)) + (<= (point) pos)))) (setq arg (1- arg))) ;; Backward (while (< arg 0) (let ((pos (point))) - (erlang-beginning-of-clause 1) - (erlang-pass-over-function) - (forward-line 1) - (if (>= (point) pos) - (if (erlang-beginning-of-function 2) - (progn - (erlang-pass-over-function) - (skip-chars-forward " \t") - (if (looking-at "[%\n]") - (forward-line 1))) - (goto-char (point-min))))) + (erlang-beginning-of-clause 1) + (erlang-pass-over-function) + (forward-line 1) + (if (>= (point) pos) + (if (erlang-beginning-of-function 2) + (progn + (erlang-pass-over-function) + (skip-chars-forward " \t") + (if (looking-at "[%\n]") + (forward-line 1))) + (goto-char (point-min))))) (setq arg (1+ arg))))) (eval-and-compile @@ -3363,18 +3363,18 @@ With negative argument go towards the beginning of the buffer." ;; Sets the region. In Emacs 19 and XEmacs, we want to activate ;; the region. (condition-case nil - (push-mark (point) nil t) - (error (push-mark (point)))) + (push-mark (point) nil t) + (error (push-mark (point)))) (erlang-beginning-of-function 1) ;; The above function deactivates the mark. (if (boundp 'deactivate-mark) - (funcall (symbol-function 'set) 'deactivate-mark nil))))) + (funcall (symbol-function 'set) 'deactivate-mark nil))))) (defun erlang-pass-over-function () (while (progn - (erlang-skip-blank) - (and (not (looking-at "\\.\\(\\s \\|\n\\|\\s<\\)")) - (not (eobp)))) + (erlang-skip-blank) + (and (not (looking-at "\\.\\(\\s \\|\n\\|\\s<\\)")) + (not (eobp)))) (forward-sexp 1)) (if (not (eobp)) (forward-char 1))) @@ -3383,7 +3383,7 @@ With negative argument go towards the beginning of the buffer." (save-excursion ;; Skip over attribute leader. (if (looking-at "-[ \t]*") - (re-search-forward "-[ \t]*" nil 'move)) + (re-search-forward "-[ \t]*" nil 'move)) (let ((start (point))) (forward-sexp 1) (buffer-substring start (point))))) @@ -3398,54 +3398,54 @@ paragraph of it that point is in, preserving the comment's indentation and initial `%':s." (interactive "P") (let ((has-comment nil) - ;; If has-comment, the appropriate fill-prefix for the comment. - comment-fill-prefix) + ;; If has-comment, the appropriate fill-prefix for the comment. + comment-fill-prefix) ;; Figure out what kind of comment we are looking at. (save-excursion (beginning-of-line) (cond ;; Find the command prefix. ((looking-at (concat "\\s *" comment-start-skip)) - (setq has-comment t) - (setq comment-fill-prefix (buffer-substring (match-beginning 0) - (match-end 0)))) + (setq has-comment t) + (setq comment-fill-prefix (buffer-substring (match-beginning 0) + (match-end 0)))) ;; A line with some code, followed by a comment? Remember that the ;; % which starts the comment shouldn't be part of a string or ;; character. ((progn - (while (not (looking-at "%\\|$")) - (skip-chars-forward "^%\n\"\\\\") - (cond - ((eq (char-after (point)) ?\\) (forward-char 2)) - ((eq (char-after (point)) ?\") (forward-sexp 1)))) - (looking-at comment-start-skip)) - (setq has-comment t) - (setq comment-fill-prefix - (concat (make-string (current-column) ? ) - (buffer-substring (match-beginning 0) (match-end 0))))))) + (while (not (looking-at "%\\|$")) + (skip-chars-forward "^%\n\"\\\\") + (cond + ((eq (char-after (point)) ?\\) (forward-char 2)) + ((eq (char-after (point)) ?\") (forward-sexp 1)))) + (looking-at comment-start-skip)) + (setq has-comment t) + (setq comment-fill-prefix + (concat (make-string (current-column) ? ) + (buffer-substring (match-beginning 0) (match-end 0))))))) (if (not has-comment) - (fill-paragraph justify) + (fill-paragraph justify) ;; Narrow to include only the comment, and then fill the region. (save-restriction - (narrow-to-region - ;; Find the first line we should include in the region to fill. - (save-excursion - (while (and (zerop (forward-line -1)) - (looking-at "^\\s *%"))) - ;; We may have gone to far. Go forward again. - (or (looking-at "^\\s *%") - (forward-line 1)) - (point)) - ;; Find the beginning of the first line past the region to fill. - (save-excursion - (while (progn (forward-line 1) - (looking-at "^\\s *%"))) - (point))) - ;; Lines with only % on them can be paragraph boundaries. - (let ((paragraph-start (concat paragraph-start "\\|^[ \t%]*$")) - (paragraph-separate (concat paragraph-start "\\|^[ \t%]*$")) - (fill-prefix comment-fill-prefix)) - (fill-paragraph justify)))))) + (narrow-to-region + ;; Find the first line we should include in the region to fill. + (save-excursion + (while (and (zerop (forward-line -1)) + (looking-at "^\\s *%"))) + ;; We may have gone to far. Go forward again. + (or (looking-at "^\\s *%") + (forward-line 1)) + (point)) + ;; Find the beginning of the first line past the region to fill. + (save-excursion + (while (progn (forward-line 1) + (looking-at "^\\s *%"))) + (point))) + ;; Lines with only % on them can be paragraph boundaries. + (let ((paragraph-start (concat paragraph-start "\\|^[ \t%]*$")) + (paragraph-separate (concat paragraph-start "\\|^[ \t%]*$")) + (fill-prefix comment-fill-prefix)) + (fill-paragraph justify)))))) (defun erlang-uncomment-region (beg end) @@ -3464,22 +3464,22 @@ first parenthesis is preserved. The point is placed between the parentheses." (interactive) (let ((name (save-excursion - (and (erlang-beginning-of-clause) - (erlang-get-function-name t)))) - (arrow (save-excursion - (and (erlang-beginning-of-clause) - (erlang-get-function-arrow))))) + (and (erlang-beginning-of-clause) + (erlang-get-function-name t)))) + (arrow (save-excursion + (and (erlang-beginning-of-clause) + (erlang-get-function-arrow))))) (if (or (null arrow) (null name)) - (error "Can't find name of current Erlang function")) + (error "Can't find name of current Erlang function")) (if (and (bolp) (eolp)) - nil + nil (end-of-line) (newline)) (insert name) (save-excursion (insert ") " arrow)) (if erlang-new-clause-with-arguments - (erlang-clone-arguments)))) + (erlang-clone-arguments)))) (defun erlang-clone-arguments () @@ -3489,12 +3489,12 @@ The mark is set at the beginning of the inserted text, the point at the end." (interactive) (let ((args (save-excursion - (beginning-of-line) - (and (erlang-beginning-of-clause) - (erlang-get-function-arguments)))) - (p (point))) + (beginning-of-line) + (and (erlang-beginning-of-clause) + (erlang-get-function-arguments)))) + (p (point))) (if (null args) - (error "Can't clone argument list")) + (error "Can't clone argument list")) (insert args) (set-mark p))) @@ -3517,18 +3517,18 @@ Return nil if file contains no `-module' attribute." (widen) (goto-char (point-min)) (let ((md (match-data))) - (unwind-protect - (if (re-search-forward - (eval-when-compile - (concat "^-module\\s *(\\s *\\(\\(" - erlang-atom-regexp - "\\)?\\)\\s *)\\s *\\.")) - (point-max) t) - (erlang-remove-quotes - (erlang-buffer-substring (match-beginning 1) - (match-end 1))) - nil) - (store-match-data md)))))) + (unwind-protect + (if (re-search-forward + (eval-when-compile + (concat "^-module\\s *(\\s *\\(\\(" + erlang-atom-regexp + "\\)?\\)\\s *)\\s *\\.")) + (point-max) t) + (erlang-remove-quotes + (erlang-buffer-substring (match-beginning 1) + (match-end 1))) + nil) + (store-match-data md)))))) (defun erlang-get-module-from-file-name (&optional file) @@ -3548,7 +3548,7 @@ tags system could be used by files written in other languages." nil (setq file (file-name-nondirectory file)) (if (string-match erlang-file-name-extension-regexp file) - (substring file 0 (match-beginning 0)) + (substring file 0 (match-beginning 0)) nil))) @@ -3569,30 +3569,30 @@ corresponds to the order of the parsed Erlang list." (erlang-skip-blank) (forward-char 1) (if (not (eq (preceding-char) ?\[)) - '() ; Not looking at an Erlang list. - (while ; Note: `while' has no body. - (progn - (erlang-skip-blank) - (and (looking-at (eval-when-compile - (concat erlang-atom-regexp "/\\([0-9]+\\)\\>"))) - (progn - (setq res (cons - (cons - (erlang-remove-quotes - (erlang-buffer-substring - (match-beginning 1) (match-end 1))) - (erlang-string-to-int - (erlang-buffer-substring - (match-beginning - (+ 1 erlang-atom-regexp-matches)) - (match-end - (+ 1 erlang-atom-regexp-matches))))) - res)) - (goto-char (match-end 0)) - (erlang-skip-blank) - (forward-char 1) - ;; Test if there are more exported functions. - (eq (preceding-char) ?,)))))) + '() ; Not looking at an Erlang list. + (while ; Note: `while' has no body. + (progn + (erlang-skip-blank) + (and (looking-at (eval-when-compile + (concat erlang-atom-regexp "/\\([0-9]+\\)\\>"))) + (progn + (setq res (cons + (cons + (erlang-remove-quotes + (erlang-buffer-substring + (match-beginning 1) (match-end 1))) + (erlang-string-to-int + (erlang-buffer-substring + (match-beginning + (+ 1 erlang-atom-regexp-matches)) + (match-end + (+ 1 erlang-atom-regexp-matches))))) + res)) + (goto-char (match-end 0)) + (erlang-skip-blank) + (forward-char 1) + ;; Test if there are more exported functions. + (eq (preceding-char) ?,)))))) (nreverse res))) @@ -3604,14 +3604,14 @@ corresponds to the order of the parsed Erlang list." (save-excursion (goto-char (point-min)) (let ((md (match-data)) - (res '())) + (res '())) (unwind-protect - (progn - (while (re-search-forward "^-export\\s *(" (point-max) t) - (erlang-skip-blank) - (setq res (nconc res (erlang-get-function-arity-list)))) - res) - (store-match-data md))))) + (progn + (while (re-search-forward "^-export\\s *(" (point-max) t) + (erlang-skip-blank) + (setq res (nconc res (erlang-get-function-arity-list)))) + res) + (store-match-data md))))) (defun erlang-get-import () @@ -3622,30 +3622,30 @@ function and arity as cdr part." (save-excursion (goto-char (point-min)) (let ((md (match-data)) - (res '())) + (res '())) (unwind-protect - (progn - (while (re-search-forward "^-import\\s *(" (point-max) t) - (erlang-skip-blank) - (if (looking-at erlang-atom-regexp) - (let ((module (erlang-remove-quotes - (erlang-buffer-substring - (match-beginning 0) - (match-end 0))))) - (goto-char (match-end 0)) - (erlang-skip-blank) - (if (eq (following-char) ?,) - (progn - (forward-char 1) - (erlang-skip-blank) - (let ((funcs (erlang-get-function-arity-list)) - (pair (assoc module res))) - (if pair - (setcdr pair (nconc (cdr pair) funcs)) - (setq res (cons (cons module funcs) - res))))))))) - (nreverse res)) - (store-match-data md))))) + (progn + (while (re-search-forward "^-import\\s *(" (point-max) t) + (erlang-skip-blank) + (if (looking-at erlang-atom-regexp) + (let ((module (erlang-remove-quotes + (erlang-buffer-substring + (match-beginning 0) + (match-end 0))))) + (goto-char (match-end 0)) + (erlang-skip-blank) + (if (eq (following-char) ?,) + (progn + (forward-char 1) + (erlang-skip-blank) + (let ((funcs (erlang-get-function-arity-list)) + (pair (assoc module res))) + (if pair + (setcdr pair (nconc (cdr pair) funcs)) + (setq res (cons (cons module funcs) + res))))))))) + (nreverse res)) + (store-match-data md))))) (defun erlang-get-function-name (&optional arg) @@ -3657,12 +3657,12 @@ the first `(' is returned. Normally used in conjunction with `erlang-beginning-of-clause', e.g.: (save-excursion (if (not (eobp)) (forward-char 1)) - (and (erlang-beginning-of-clause) - (erlang-get-function-name t)))" + (and (erlang-beginning-of-clause) + (erlang-get-function-name t)))" (let ((n (if arg 0 1))) (and (looking-at (eval-when-compile - (concat "^" erlang-atom-regexp "\\s *("))) - (erlang-buffer-substring (match-beginning n) (match-end n))))) + (concat "^" erlang-atom-regexp "\\s *("))) + (erlang-buffer-substring (match-beginning n) (match-end n))))) (defun erlang-get-function-arrow () @@ -3671,9 +3671,9 @@ Normally used in conjunction with `erlang-beginning-of-clause', e.g.: Normally used in conjunction with `erlang-beginning-of-clause', e.g.: (save-excursion (if (not (eobp)) (forward-char 1)) - (and (erlang-beginning-of-clause) - (erlang-get-function-arrow)))" - (and + (and (erlang-beginning-of-clause) + (erlang-get-function-arrow)))" + (and (save-excursion (re-search-forward "->" (point-max) t) (erlang-buffer-substring (- (point) 2) (+ (point) 1))))) @@ -3681,33 +3681,33 @@ Normally used in conjunction with `erlang-beginning-of-clause', e.g.: (defun erlang-get-function-arity () "Return the number of arguments of function at point, or nil." (and (looking-at (eval-when-compile - (concat "^" erlang-atom-regexp "\\s *("))) + (concat "^" erlang-atom-regexp "\\s *("))) (save-excursion - (goto-char (match-end 0)) - (condition-case nil - (let ((res 0) - (cont t)) - (while cont - (cond ((eobp) - (setq res nil) - (setq cont nil)) - ((looking-at "\\s *)") - (setq cont nil)) - ((looking-at "\\s *\\($\\|%\\)") - (forward-line 1)) - ((looking-at "\\s *<<[^>]*?>>") - (when (zerop res) - (setq res (+ 1 res))) - (goto-char (match-end 0))) - ((looking-at "\\s *,") - (setq res (+ 1 res)) - (goto-char (match-end 0))) - (t - (when (zerop res) - (setq res (+ 1 res))) - (forward-sexp 1)))) - res) - (error nil))))) + (goto-char (match-end 0)) + (condition-case nil + (let ((res 0) + (cont t)) + (while cont + (cond ((eobp) + (setq res nil) + (setq cont nil)) + ((looking-at "\\s *)") + (setq cont nil)) + ((looking-at "\\s *\\($\\|%\\)") + (forward-line 1)) + ((looking-at "\\s *<<[^>]*?>>") + (when (zerop res) + (setq res (+ 1 res))) + (goto-char (match-end 0))) + ((looking-at "\\s *,") + (setq res (+ 1 res)) + (goto-char (match-end 0))) + (t + (when (zerop res) + (setq res (+ 1 res))) + (forward-sexp 1)))) + res) + (error nil))))) (defun erlang-get-function-name-and-arity () "Return the name and arity of the function at point, or nil. @@ -3719,15 +3719,15 @@ The return value is a string of the form \"foo/1\"." (defun erlang-get-function-arguments () "Return arguments of current function, or nil." (if (not (looking-at (eval-when-compile - (concat "^" erlang-atom-regexp "\\s *(")))) + (concat "^" erlang-atom-regexp "\\s *(")))) nil (save-excursion (condition-case nil - (let ((start (match-end 0))) - (goto-char (- start 1)) - (forward-sexp) - (erlang-buffer-substring start (- (point) 1))) - (error nil))))) + (let ((start (match-end 0))) + (goto-char (- start 1)) + (forward-sexp) + (erlang-buffer-substring start (- (point) 1))) + (error nil))))) (defun erlang-get-function-under-point () @@ -3744,37 +3744,37 @@ The following could be returned: In the future the list may contain more elements." (save-excursion (let ((md (match-data)) - (res nil)) + (res nil)) (if (eq (char-syntax (following-char)) ? ) - (skip-chars-backward " \t")) + (skip-chars-backward " \t")) (skip-chars-backward "a-zA-Z0-9_:'") (cond ((looking-at (eval-when-compile - (concat erlang-atom-regexp ":" erlang-atom-regexp))) - (setq res (list - (erlang-remove-quotes - (erlang-buffer-substring - (match-beginning 1) (match-end 1))) - (erlang-remove-quotes - (erlang-buffer-substring - (match-beginning (1+ erlang-atom-regexp-matches)) - (match-end (1+ erlang-atom-regexp-matches))))))) - ((looking-at erlang-atom-regexp) - (let ((fk (erlang-remove-quotes - (erlang-buffer-substring - (match-beginning 0) (match-end 0)))) - (mod nil) - (imports (erlang-get-import))) - (while (and imports (null mod)) - (if (assoc fk (cdr (car imports))) - (setq mod (car (car imports))) - (setq imports (cdr imports)))) - (cond ((eq (preceding-char) ?#) - (setq fk (concat "-record(" fk))) - ((eq (preceding-char) ??) - (setq fk (concat "-define(" fk))) - ((and (null mod) (not (member fk erlang-int-bifs))) - (setq mod (erlang-get-module)))) - (setq res (list mod fk))))) + (concat erlang-atom-regexp ":" erlang-atom-regexp))) + (setq res (list + (erlang-remove-quotes + (erlang-buffer-substring + (match-beginning 1) (match-end 1))) + (erlang-remove-quotes + (erlang-buffer-substring + (match-beginning (1+ erlang-atom-regexp-matches)) + (match-end (1+ erlang-atom-regexp-matches))))))) + ((looking-at erlang-atom-regexp) + (let ((fk (erlang-remove-quotes + (erlang-buffer-substring + (match-beginning 0) (match-end 0)))) + (mod nil) + (imports (erlang-get-import))) + (while (and imports (null mod)) + (if (assoc fk (cdr (car imports))) + (setq mod (car (car imports))) + (setq imports (cdr imports)))) + (cond ((eq (preceding-char) ?#) + (setq fk (concat "-record(" fk))) + ((eq (preceding-char) ??) + (setq fk (concat "-define(" fk))) + ((and (null mod) (not (member fk erlang-int-bifs))) + (setq mod (erlang-get-module)))) + (setq res (list mod fk))))) (store-match-data md) res))) @@ -3785,11 +3785,11 @@ In the future the list may contain more elements." "Return STR, possibly with quotes." (let ((case-fold-search nil)) ; force string matching to be case sensitive (if (and (stringp str) - (not (string-match (eval-when-compile - (concat "\\`" erlang-atom-regexp "\\'")) str))) - (progn (if (fboundp 'replace-regexp-in-string) - (setq str (replace-regexp-in-string "'" "\\'" str t t ))) - (concat "'" str "'")) + (not (string-match (eval-when-compile + (concat "\\`" erlang-atom-regexp "\\'")) str))) + (progn (if (fboundp 'replace-regexp-in-string) + (setq str (replace-regexp-in-string "'" "\\'" str t t ))) + (concat "'" str "'")) str))) @@ -3797,9 +3797,9 @@ In the future the list may contain more elements." "Return STR without quotes, if present." (let ((md (match-data))) (prog1 - (if (string-match "\\`'\\(.*\\)'\\'" str) - (substring str 1 -1) - str) + (if (string-match "\\`'\\(.*\\)'\\'" str) + (substring str 1 -1) + str) (store-match-data md)))) (defun erlang-match-next-exported-function (max) @@ -3869,30 +3869,30 @@ is prompted. This function is normally placed in the hook `local-write-file-hooks'." (if erlang-check-module-name - (let ((mn (erlang-add-quotes-if-needed - (erlang-get-module))) - (fn (erlang-add-quotes-if-needed - (erlang-get-module-from-file-name (buffer-file-name))))) - (if (and (stringp mn) (stringp fn)) - (or (string-equal mn fn) - (if (or (eq erlang-check-module-name t) - (y-or-n-p - "Module does not match file name. Modify source? ")) - (save-excursion - (save-restriction - (widen) - (goto-char (point-min)) - (if (re-search-forward - (eval-when-compile - (concat "^-module\\s *(\\s *\\(\\(" - erlang-atom-regexp - "\\)?\\)\\s *)\\s *\\.")) - (point-max) t) - (progn - (goto-char (match-beginning 1)) - (delete-region (match-beginning 1) - (match-end 1)) - (insert fn)))))))))) + (let ((mn (erlang-add-quotes-if-needed + (erlang-get-module))) + (fn (erlang-add-quotes-if-needed + (erlang-get-module-from-file-name (buffer-file-name))))) + (if (and (stringp mn) (stringp fn)) + (or (string-equal mn fn) + (if (or (eq erlang-check-module-name t) + (y-or-n-p + "Module does not match file name. Modify source? ")) + (save-excursion + (save-restriction + (widen) + (goto-char (point-min)) + (if (re-search-forward + (eval-when-compile + (concat "^-module\\s *(\\s *\\(\\(" + erlang-atom-regexp + "\\)?\\)\\s *)\\s *\\.")) + (point-max) t) + (progn + (goto-char (match-beginning 1)) + (delete-region (match-beginning 1) + (match-end 1)) + (insert fn)))))))))) ;; Must return nil since it is added to `local-write-file-hook'. nil) @@ -3918,13 +3918,13 @@ non-whitespace characters following the point on the current line." (interactive "P") (self-insert-command (prefix-numeric-value arg)) (if (or arg - (and (listp erlang-electric-commands) - (not (memq 'erlang-electric-semicolon - erlang-electric-commands))) - (erlang-in-literal) - (not (looking-at "\\s *\\(%.*\\)?$")) - (null (erlang-test-criteria-list - erlang-electric-semicolon-criteria))) + (and (listp erlang-electric-commands) + (not (memq 'erlang-electric-semicolon + erlang-electric-commands))) + (erlang-in-literal) + (not (looking-at "\\s *\\(%.*\\)?$")) + (null (erlang-test-criteria-list + erlang-electric-semicolon-criteria))) (setq erlang-electric-newline-inhibit nil) (setq erlang-electric-newline-inhibit t) (undo-boundary) @@ -3932,20 +3932,20 @@ non-whitespace characters following the point on the current line." (end-of-line) (newline) (if (condition-case nil - (progn (erlang-indent-line) t) - (error (if (bolp) (delete-char -1)))) - (if (not (bolp)) - (save-excursion - (insert " ->")) - (condition-case nil - (progn - (erlang-generate-new-clause) - (if erlang-electric-semicolon-insert-blank-lines - (save-excursion - (beginning-of-line) - (newline - erlang-electric-semicolon-insert-blank-lines)))) - (error (if (bolp) (delete-char -1)))))))) + (progn (erlang-indent-line) t) + (error (if (bolp) (delete-char -1)))) + (if (not (bolp)) + (save-excursion + (insert " ->")) + (condition-case nil + (progn + (erlang-generate-new-clause) + (if erlang-electric-semicolon-insert-blank-lines + (save-excursion + (beginning-of-line) + (newline + erlang-electric-semicolon-insert-blank-lines)))) + (error (if (bolp) (delete-char -1)))))))) (defun erlang-electric-comma (&optional arg) @@ -3961,12 +3961,12 @@ non-whitespace characters following the point on the current line." (self-insert-command (prefix-numeric-value arg)) (if (or arg - (and (listp erlang-electric-commands) - (not (memq 'erlang-electric-comma erlang-electric-commands))) - (erlang-in-literal) - (not (looking-at "\\s *\\(%.*\\)?$")) - (null (erlang-test-criteria-list - erlang-electric-comma-criteria))) + (and (listp erlang-electric-commands) + (not (memq 'erlang-electric-comma erlang-electric-commands))) + (erlang-in-literal) + (not (looking-at "\\s *\\(%.*\\)?$")) + (null (erlang-test-criteria-list + erlang-electric-comma-criteria))) (setq erlang-electric-newline-inhibit nil) (setq erlang-electric-newline-inhibit t) (undo-boundary) @@ -3974,12 +3974,12 @@ non-whitespace characters following the point on the current line." (end-of-line) (newline) (condition-case nil - (erlang-indent-line) + (erlang-indent-line) (error (if (bolp) (delete-char -1)))))) (defun erlang-electric-lt (&optional arg) "Insert a less-than sign, and optionally mark it as an open paren." - + (interactive "p") (self-insert-command arg) @@ -3989,48 +3989,48 @@ non-whitespace characters following the point on the current line." (save-excursion (backward-char 2) (when (and (eq (char-after (point)) ?<) - (not (eq (get-text-property (point) 'category) - 'bitsyntax-open-inner))) - ;; Then mark the two chars... - (put-text-property (point) (1+ (point)) - 'category 'bitsyntax-open-outer) - (forward-char 1) - (put-text-property (point) (1+ (point)) - 'category 'bitsyntax-open-inner) - ;;...and unmark any subsequent less-than chars. - (forward-char 1) - (while (eq (char-after (point)) ?<) - (remove-text-properties (point) (1+ (point)) - '(category nil)) - (forward-char 1)))))) + (not (eq (get-text-property (point) 'category) + 'bitsyntax-open-inner))) + ;; Then mark the two chars... + (put-text-property (point) (1+ (point)) + 'category 'bitsyntax-open-outer) + (forward-char 1) + (put-text-property (point) (1+ (point)) + 'category 'bitsyntax-open-inner) + ;;...and unmark any subsequent less-than chars. + (forward-char 1) + (while (eq (char-after (point)) ?<) + (remove-text-properties (point) (1+ (point)) + '(category nil)) + (forward-char 1)))))) (defun erlang-after-bitsyntax-close () "Return t if point is immediately after a bit-syntax close parenthesis (`>>')." (and (>= (point) 3) (save-excursion - (backward-char 2) - (and (eq (char-after (point)) ?>) - (not (eq (get-text-property (point) 'category) - 'bitsyntax-close-outer)))))) - + (backward-char 2) + (and (eq (char-after (point)) ?>) + (not (eq (get-text-property (point) 'category) + 'bitsyntax-close-outer)))))) + (defun erlang-after-arrow () "Return true if point is immediately after a function arrow (`->')." (and (>= (point) 2) - (and - (save-excursion - (backward-char) - (eq (char-before (point)) ?-)) - (or (not (listp erlang-electric-commands)) - (memq 'erlang-electric-gt - erlang-electric-commands)) - (not (erlang-in-literal)) - (looking-at "\\s *\\(%.*\\)?$") - (erlang-test-criteria-list erlang-electric-arrow-criteria)))) + (and + (save-excursion + (backward-char) + (eq (char-before (point)) ?-)) + (or (not (listp erlang-electric-commands)) + (memq 'erlang-electric-gt + erlang-electric-commands)) + (not (erlang-in-literal)) + (looking-at "\\s *\\(%.*\\)?$") + (erlang-test-criteria-list erlang-electric-arrow-criteria)))) (defun erlang-electric-gt (&optional arg) "Insert a greater-than sign, and optionally mark it as a close paren." - + (interactive "p") (self-insert-command arg) @@ -4041,17 +4041,17 @@ non-whitespace characters following the point on the current line." (save-excursion ;; Then mark the two chars... (backward-char 2) - (put-text-property (point) (1+ (point)) - 'category 'bitsyntax-close-inner) + (put-text-property (point) (1+ (point)) + 'category 'bitsyntax-close-inner) (forward-char) (put-text-property (point) (1+ (point)) - 'category 'bitsyntax-close-outer) + 'category 'bitsyntax-close-outer) ;;...and unmark any subsequent greater-than chars. (forward-char) (while (eq (char-after (point)) ?>) - (remove-text-properties (point) (1+ (point)) - '(category nil)) - (forward-char)))) + (remove-text-properties (point) (1+ (point)) + '(category nil)) + (forward-char)))) ;; Did we just write a function arrow (`->')? ((erlang-after-arrow) @@ -4060,13 +4060,13 @@ non-whitespace characters following the point on the current line." (end-of-line) (newline) (condition-case nil - (erlang-indent-line) - (error (if (bolp) (delete-char -1)))))) + (erlang-indent-line) + (error (if (bolp) (delete-char -1)))))) ;; Then it's just a plain greater-than. (t nil))) - + (defun erlang-electric-arrow\ off (&optional arg) "Insert a '>'-sign and possibly a new indented line. @@ -4086,22 +4086,22 @@ After being split/merged into `erlang-after-arrow' and (let ((prec (preceding-char))) (self-insert-command (prefix-numeric-value arg)) (if (or arg - (and (listp erlang-electric-commands) - (not (memq 'erlang-electric-arrow - erlang-electric-commands))) - (not (eq prec ?-)) - (erlang-in-literal) - (not (looking-at "\\s *\\(%.*\\)?$")) - (null (erlang-test-criteria-list - erlang-electric-arrow-criteria))) - (setq erlang-electric-newline-inhibit nil) + (and (listp erlang-electric-commands) + (not (memq 'erlang-electric-arrow + erlang-electric-commands))) + (not (eq prec ?-)) + (erlang-in-literal) + (not (looking-at "\\s *\\(%.*\\)?$")) + (null (erlang-test-criteria-list + erlang-electric-arrow-criteria))) + (setq erlang-electric-newline-inhibit nil) (setq erlang-electric-newline-inhibit t) (undo-boundary) (end-of-line) (newline) (condition-case nil - (erlang-indent-line) - (error (if (bolp) (delete-char -1))))))) + (erlang-indent-line) + (error (if (bolp) (delete-char -1))))))) (defun erlang-electric-newline (&optional arg) @@ -4116,30 +4116,30 @@ Should the previous command be another electric command we assume that the user pressed newline out of old habit, hence we will do nothing." (interactive "P") (cond ((and (not arg) - erlang-electric-newline-inhibit - (memq last-command erlang-electric-newline-inhibit-list)) - ()) ; Do nothing! - ((or arg - (and (listp erlang-electric-commands) - (not (memq 'erlang-electric-newline - erlang-electric-commands))) - (null (erlang-test-criteria-list - erlang-electric-newline-criteria))) - (newline (prefix-numeric-value arg))) - (t - (if (and comment-multi-line - (save-excursion - (beginning-of-line) - (looking-at (concat "\\s *" comment-start-skip)))) - (let ((str (buffer-substring - (or (match-end 1) (match-beginning 0)) - (min (match-end 0) (point))))) - (newline) - (undo-boundary) - (insert str)) - (newline) - (undo-boundary) - (indent-according-to-mode))))) + erlang-electric-newline-inhibit + (memq last-command erlang-electric-newline-inhibit-list)) + ()) ; Do nothing! + ((or arg + (and (listp erlang-electric-commands) + (not (memq 'erlang-electric-newline + erlang-electric-commands))) + (null (erlang-test-criteria-list + erlang-electric-newline-criteria))) + (newline (prefix-numeric-value arg))) + (t + (if (and comment-multi-line + (save-excursion + (beginning-of-line) + (looking-at (concat "\\s *" comment-start-skip)))) + (let ((str (buffer-substring + (or (match-end 1) (match-beginning 0)) + (min (match-end 0) (point))))) + (newline) + (undo-boundary) + (insert str)) + (newline) + (undo-boundary) + (indent-according-to-mode))))) (defun erlang-test-criteria-list (criteria) @@ -4164,14 +4164,14 @@ Return t if criteria fulfilled, nil otherwise." t (save-excursion (let ((answer nil)) - (while (and criteria (null answer)) - (if (eq (car criteria) t) - (setq answer t) - (setq answer (funcall (car criteria)))) - (setq criteria (cdr criteria))) - (if (and answer (not (eq answer 'stop))) - t - nil))))) + (while (and criteria (null answer)) + (if (eq (car criteria) t) + (setq answer t) + (setq answer (funcall (car criteria)))) + (setq criteria (cdr criteria))) + (if (and answer (not (eq answer 'stop))) + t + nil))))) (defun erlang-in-literal (&optional lim) @@ -4182,11 +4182,11 @@ Should the point be inside none of the above mentioned types of context, nil is returned." (save-excursion (let* ((lim (or lim (save-excursion - (erlang-beginning-of-clause) - (point)))) - (state (if (fboundp 'syntax-ppss) ; post Emacs 21.3 - (funcall (symbol-function 'syntax-ppss)) - (parse-partial-sexp lim (point))))) + (erlang-beginning-of-clause) + (point)))) + (state (if (fboundp 'syntax-ppss) ; post Emacs 21.3 + (funcall (symbol-function 'syntax-ppss)) + (parse-partial-sexp lim (point))))) (cond ((eq (nth 3 state) ?') 'atom) ((nth 3 state) 'string) @@ -4200,7 +4200,7 @@ context, nil is returned." This function is designed to be a member of a criteria list." (eq (save-excursion (erlang-skip-blank) (point)) (save-excursion - (erlang-beginning-of-function -1) (point)))) + (erlang-beginning-of-function -1) (point)))) (defun erlang-at-end-of-clause-p () @@ -4209,7 +4209,7 @@ This function is designed to be a member of a criteria list." This function is designed to be a member of a criteria list." (eq (save-excursion (erlang-skip-blank) (point)) (save-excursion - (erlang-beginning-of-clause -1) (point)))) + (erlang-beginning-of-clause -1) (point)))) (defun erlang-stop-when-inside-argument-list () @@ -4221,22 +4221,22 @@ after `||', `stop' is not returned. This function is designed to be a member of a criteria list." (save-excursion (condition-case nil - (let ((orig-point (point)) - (state nil)) - (up-list -1) - (if (not (eq (following-char) ?\[)) - 'stop - ;; Do not return `stop' when inside a list comprehension - ;; construction. (The point must be after `||'). - (while (< (point) orig-point) + (let ((orig-point (point)) + (state nil)) + (up-list -1) + (if (not (eq (following-char) ?\[)) + 'stop + ;; Do not return `stop' when inside a list comprehension + ;; construction. (The point must be after `||'). + (while (< (point) orig-point) (let ((pt (point))) (setq state (erlang-partial-parse pt orig-point state)) (if (= pt (point)) (error "Illegal syntax")))) - (if (and (car state) (eq (car (car (car state))) '||)) - nil - 'stop))) - (error + (if (and (car state) (eq (car (car (car state))) '||)) + nil + 'stop))) + (error nil)))) @@ -4247,11 +4247,11 @@ This function is designed to be a member of a criteria list." (save-excursion (beginning-of-line) (if (and (looking-at (eval-when-compile - (concat "^" erlang-atom-regexp "\\s *("))) - (not (looking-at - (eval-when-compile - (concat "^" erlang-atom-regexp ".*->"))))) - 'stop + (concat "^" erlang-atom-regexp "\\s *("))) + (not (looking-at + (eval-when-compile + (concat "^" erlang-atom-regexp ".*->"))))) + 'stop nil))) @@ -4276,13 +4276,13 @@ A line containing only spaces and tabs is considered empty. This function is designed to be a member of a criteria list." (and erlang-next-lines-empty-threshold (save-excursion - (let ((left erlang-next-lines-empty-threshold) - (cont t)) - (while (and cont (> left 0)) - (forward-line 1) - (setq cont (looking-at "\\s *$")) - (setq left (- left 1))) - cont)))) + (let ((left erlang-next-lines-empty-threshold) + (cont t)) + (while (and cont (> left 0)) + (forward-line 1) + (setq cont (looking-at "\\s *$")) + (setq left (- left 1))) + cont)))) (defun erlang-at-keyword-end-p () @@ -4301,9 +4301,9 @@ This function is designed to be a member of a criteria list." (eval-when-compile (if (or (featurep 'bytecomp) - (featurep 'byte-compile)) + (featurep 'byte-compile)) (progn - (require 'etags)))) + (require 'etags)))) ;; Variables: @@ -4354,11 +4354,11 @@ is not implemented under XEmacs. (Hint: The Emacs 19 etags module works under XEmacs.)" (interactive) (cond ((= erlang-emacs-major-version 18) - (require 'tags) - (erlang-tags-define-keys (current-local-map)) - (setq erlang-tags-installed t)) - (t - (require 'etags) + (require 'tags) + (erlang-tags-define-keys (current-local-map)) + (setq erlang-tags-installed t)) + (t + (require 'etags) (set (make-local-variable 'find-tag-default-function) 'erlang-find-tag-for-completion) (if (>= emacs-major-version 25) @@ -4383,11 +4383,11 @@ works under XEmacs.)" (let ((alist erlang-tags-function-alist)) (while alist (let* ((old (car (car alist))) - (new (cdr (car alist))) - (keys (append (where-is-internal old global-map)))) - (while keys - (define-key map (car keys) new) - (setq keys (cdr keys)))) + (new (cdr (car alist))) + (keys (append (where-is-internal old global-map)))) + (while keys + (define-key map (car keys) new) + (setq keys (cdr keys)))) (setq alist (cdr alist)))) ;; Update the menu. (erlang-menu-substitute erlang-menu-base-items erlang-tags-function-alist) @@ -4400,11 +4400,11 @@ Search `-import' list of imported functions. Single quotes are been stripped away." (let ((mod-func (erlang-get-function-under-point))) (cond ((null mod-func) - nil) - ((null (car mod-func)) - (nth 1 mod-func)) - (t - (concat (car mod-func) ":" (nth 1 mod-func)))))) + nil) + ((null (car mod-func)) + (nth 1 mod-func)) + (t + (concat (car mod-func) ":" (nth 1 mod-func)))))) ;; Return `t' since it is used inside `tags-loop-form'. @@ -4423,31 +4423,31 @@ Tags can be given on the forms `tag', `module:', `module:tag'." (defun erlang-find-tag-other-window (tagname &optional next-p regexp-p) "Like `find-tag-other-window' but aware of Erlang modules." (interactive (erlang-tag-interactive - "Find `module:tag' or `tag' other window: ")) + "Find `module:tag' or `tag' other window: ")) ;; This is to deal with the case where the tag is found in the ;; selected window's buffer; without this, point is moved in both ;; windows. To prevent this, we save the selected window's point ;; before doing find-tag-noselect, and restore it afterwards. (let* ((window-point (window-point (selected-window))) - (tagbuf (erlang-find-tag-noselect tagname next-p regexp-p)) - (tagpoint (progn (set-buffer tagbuf) (point)))) + (tagbuf (erlang-find-tag-noselect tagname next-p regexp-p)) + (tagpoint (progn (set-buffer tagbuf) (point)))) (set-window-point (prog1 - (selected-window) - (switch-to-buffer-other-window tagbuf) - ;; We have to set this new window's point; it - ;; might already have been displaying a - ;; different portion of tagbuf, in which case - ;; switch-to-buffer-other-window doesn't set - ;; the window's point from the buffer. - (set-window-point (selected-window) tagpoint)) - window-point))) + (selected-window) + (switch-to-buffer-other-window tagbuf) + ;; We have to set this new window's point; it + ;; might already have been displaying a + ;; different portion of tagbuf, in which case + ;; switch-to-buffer-other-window doesn't set + ;; the window's point from the buffer. + (set-window-point (selected-window) tagpoint)) + window-point))) (defun erlang-find-tag-other-frame (tagname &optional next-p) "Like `find-tag-other-frame' but aware of Erlang modules." (interactive (erlang-tag-interactive - "Find `module:tag' or `tag' other frame: ")) + "Find `module:tag' or `tag' other frame: ")) (let ((pop-up-frames t)) (erlang-find-tag-other-window tagname next-p))) @@ -4455,13 +4455,13 @@ Tags can be given on the forms `tag', `module:', `module:tag'." (defun erlang-find-tag-regexp (regexp &optional next-p other-window) "Like `find-tag-regexp' but aware of Erlang modules." (interactive (if (fboundp 'find-tag-regexp) - (erlang-tag-interactive - "Find `module:regexp' or `regexp': ") - (error "This version of Emacs can't find tags by regexps"))) + (erlang-tag-interactive + "Find `module:regexp' or `regexp': ") + (error "This version of Emacs can't find tags by regexps"))) (funcall (if other-window - 'erlang-find-tag-other-window - 'erlang-find-tag) - regexp next-p t)) + 'erlang-find-tag-other-window + 'erlang-find-tag) + regexp next-p t)) ;; Just like C-u M-. This could be added to the menu. @@ -4470,7 +4470,7 @@ Tags can be given on the forms `tag', `module:', `module:tag'." (interactive) (let ((current-prefix-arg '(4))) (if erlang-tags-installed - (call-interactively 'erlang-find-tag) + (call-interactively 'erlang-find-tag) (call-interactively 'find-tag)))) @@ -4482,9 +4482,9 @@ Tags can be given on the forms `tag', `module:', `module:tag'." ;; without extension and directory matches the module. ;; ;; * `module:tag' -;; Emacs 19: Replace test functions with functions aware of -;; Erlang modules. Tricky because the etags system wasn't -;; built for these kind of operations... +;; Emacs 19: Replace test functions with functions aware of +;; Erlang modules. Tricky because the etags system wasn't +;; built for these kind of operations... ;; ;; Emacs 18: We loop over `find-tag' until we find a file ;; whose module matches the requested module. The @@ -4503,78 +4503,78 @@ Tags can be given on the forms `tag', `module:', `module:tag'." ;; know where to restart a tags command. (if (boundp 'tags-loop-form) (funcall (symbol-function 'set) - 'tags-loop-form '(erlang-find-tag nil t))) + 'tags-loop-form '(erlang-find-tag nil t))) (save-window-excursion (cond ((string-match ":$" modtagname) ;; Only the module name was given. Read all files whose file name ;; match. (let ((modname (substring modtagname 0 (match-beginning 0))) - (file nil)) - (if (not next-p) - (save-excursion - (visit-tags-table-buffer) - (setq erlang-tags-file-list - (funcall (symbol-function 'tags-table-files))))) - (while (null file) - (or erlang-tags-file-list - (save-excursion - (if (and (featurep 'etags) - (funcall - (symbol-function 'visit-tags-table-buffer) 'same) - (funcall - (symbol-function 'visit-tags-table-buffer) t)) - (setq erlang-tags-file-list - (funcall (symbol-function 'tags-table-files))) - (error "No %stags containing %s" (if next-p "more " "") - modtagname)))) - (if erlang-tags-file-list - (let ((this-module (erlang-get-module-from-file-name - (car erlang-tags-file-list)))) - (if (and (stringp this-module) - (string= modname this-module)) - (setq file (car erlang-tags-file-list))) - (setq erlang-tags-file-list (cdr erlang-tags-file-list))))) - (set-buffer (or (get-file-buffer file) - (find-file-noselect file))))) + (file nil)) + (if (not next-p) + (save-excursion + (visit-tags-table-buffer) + (setq erlang-tags-file-list + (funcall (symbol-function 'tags-table-files))))) + (while (null file) + (or erlang-tags-file-list + (save-excursion + (if (and (featurep 'etags) + (funcall + (symbol-function 'visit-tags-table-buffer) 'same) + (funcall + (symbol-function 'visit-tags-table-buffer) t)) + (setq erlang-tags-file-list + (funcall (symbol-function 'tags-table-files))) + (error "No %stags containing %s" (if next-p "more " "") + modtagname)))) + (if erlang-tags-file-list + (let ((this-module (erlang-get-module-from-file-name + (car erlang-tags-file-list)))) + (if (and (stringp this-module) + (string= modname this-module)) + (setq file (car erlang-tags-file-list))) + (setq erlang-tags-file-list (cdr erlang-tags-file-list))))) + (set-buffer (or (get-file-buffer file) + (find-file-noselect file))))) ((string-match ":" modtagname) (if (boundp 'find-tag-tag-order) - ;; Method one: Add module-recognising functions to the - ;; list of order functions. However, the tags system - ;; from Emacs 18, and derives thereof (read: XEmacs) - ;; hasn't got this feature. - (progn - (erlang-tags-install-module-check) - (unwind-protect - (funcall (symbol-function 'find-tag) - modtagname next-p regexp-p) - (erlang-tags-remove-module-check))) - ;; Method two: Call the tags system until a file matching - ;; the module is found. This could result in that many - ;; files are read. (e.g. The tag "foo:file" will take a - ;; while to process.) - (let* ((modname (substring modtagname 0 (match-beginning 0))) - (tagname (substring modtagname (match-end 0) nil)) - (last-tag tagname) - file) - (while - (progn - (funcall (symbol-function 'find-tag) tagname next-p regexp-p) - (setq next-p t) - ;; Determine the module form the file name. (The - ;; alternative, to check `-module', would make this - ;; code useless for non-Erlang programs.) - (setq file (erlang-get-module-from-file-name buffer-file-name)) - (not (and (stringp file) - (string= modname file)))))))) + ;; Method one: Add module-recognising functions to the + ;; list of order functions. However, the tags system + ;; from Emacs 18, and derives thereof (read: XEmacs) + ;; hasn't got this feature. + (progn + (erlang-tags-install-module-check) + (unwind-protect + (funcall (symbol-function 'find-tag) + modtagname next-p regexp-p) + (erlang-tags-remove-module-check))) + ;; Method two: Call the tags system until a file matching + ;; the module is found. This could result in that many + ;; files are read. (e.g. The tag "foo:file" will take a + ;; while to process.) + (let* ((modname (substring modtagname 0 (match-beginning 0))) + (tagname (substring modtagname (match-end 0) nil)) + (last-tag tagname) + file) + (while + (progn + (funcall (symbol-function 'find-tag) tagname next-p regexp-p) + (setq next-p t) + ;; Determine the module form the file name. (The + ;; alternative, to check `-module', would make this + ;; code useless for non-Erlang programs.) + (setq file (erlang-get-module-from-file-name buffer-file-name)) + (not (and (stringp file) + (string= modname file)))))))) (t (funcall (symbol-function 'find-tag) modtagname next-p regexp-p))) - (current-buffer))) ; Return the new buffer. + (current-buffer))) ; Return the new buffer. + - @@ -4591,18 +4591,18 @@ Tags can be given on the forms `tag', `module:', `module:tag'." (require 'tags))) (if current-prefix-arg (list nil (if (< (prefix-numeric-value current-prefix-arg) 0) - '- - t)) + '- + t)) (let* ((default (erlang-find-tag-default)) - (prompt (if default - (format "%s(default %s) " prompt default) - prompt)) - (spec (if (featurep 'etags) - (completing-read prompt 'erlang-tags-complete-tag) - (read-string prompt)))) + (prompt (if default + (format "%s(default %s) " prompt default) + prompt)) + (spec (if (featurep 'etags) + (completing-read prompt 'erlang-tags-complete-tag) + (read-string prompt)))) (list (if (equal spec "") - (or default (error "There is no default tag")) - spec))))) + (or default (error "There is no default tag")) + spec))))) ;; Search tag functions which are aware of Erlang modules. The tactic @@ -4629,21 +4629,21 @@ Tags can be given on the forms `tag', `module:', `module:tag'." (setq erlang-tags-orig-format-hooks (symbol-value 'tags-table-format-hooks)) (funcall (symbol-function 'set) 'tags-table-format-hooks - (cons 'erlang-tags-recognize-tags-table - erlang-tags-orig-format-hooks)) + (cons 'erlang-tags-recognize-tags-table + erlang-tags-orig-format-hooks)) (setq erlang-tags-buffer-list '()) - )) - + )) + ;; Install our functions in the TAGS files already resident. (save-excursion (let ((files (symbol-value 'tags-table-computed-list))) (while files - (if (stringp (car files)) - (if (get-file-buffer (car files)) - (progn - (set-buffer (get-file-buffer (car files))) - (erlang-tags-install-local)))) - (setq files (cdr files)))))) + (if (stringp (car files)) + (if (get-file-buffer (car files)) + (progn + (set-buffer (get-file-buffer (car files))) + (erlang-tags-install-local)))) + (setq files (cdr files)))))) (defun erlang-tags-install-local () @@ -4653,23 +4653,23 @@ Tags can be given on the forms `tag', `module:', `module:tag'." ;; Mark this buffer as "installed" and record. (set (make-local-variable 'erlang-tags-buffer-installed-p) t) (setq erlang-tags-buffer-list - (cons (current-buffer) erlang-tags-buffer-list)) + (cons (current-buffer) erlang-tags-buffer-list)) ;; Save the original values. (set (make-local-variable 'erlang-tags-orig-tag-order) - (symbol-value 'find-tag-tag-order)) + (symbol-value 'find-tag-tag-order)) (set (make-local-variable 'erlang-tags-orig-regexp-tag-order) - (symbol-value 'find-tag-regexp-tag-order)) + (symbol-value 'find-tag-regexp-tag-order)) (set (make-local-variable 'erlang-tags-orig-search-function) - (symbol-value 'find-tag-search-function)) + (symbol-value 'find-tag-search-function)) (set (make-local-variable 'erlang-tags-orig-regexp-search-function) - (symbol-value 'find-tag-regexp-search-function)) + (symbol-value 'find-tag-regexp-search-function)) ;; Install our own functions. (set (make-local-variable 'find-tag-search-function) - 'erlang-tags-search-forward) + 'erlang-tags-search-forward) (set (make-local-variable 'find-tag-regexp-search-function) - 'erlang-tags-regexp-search-forward) + 'erlang-tags-regexp-search-forward) (set (make-local-variable 'find-tag-tag-order) (mapcar #'erlang-make-order-function-aware-of-modules erlang-tags-orig-tag-order)) @@ -4697,13 +4697,13 @@ Tags can be given on the forms `tag', `module:', `module:tag'." (cond ((>= erlang-emacs-major-version 20) (funcall (symbol-function 'set) - 'tags-table-format-functions - erlang-tags-orig-format-functions) + 'tags-table-format-functions + erlang-tags-orig-format-functions) ) - (t + (t (funcall (symbol-function 'set) - 'tags-table-format-hooks - erlang-tags-orig-format-hooks) + 'tags-table-format-hooks + erlang-tags-orig-format-hooks) )) ;; Remove our functions from the TAGS files. (Note that @@ -4712,11 +4712,11 @@ Tags can be given on the forms `tag', `module:', `module:tag'." (save-excursion (let ((buffers erlang-tags-buffer-list)) (while buffers - (if (buffer-name (car buffers)) - (progn - (set-buffer (car buffers)) - (erlang-tags-remove-local))) - (setq buffers (cdr buffers)))))) + (if (buffer-name (car buffers)) + (progn + (set-buffer (car buffers)) + (erlang-tags-remove-local))) + (setq buffers (cdr buffers)))))) (defun erlang-tags-remove-local () @@ -4725,14 +4725,14 @@ Tags can be given on the forms `tag', `module:', `module:tag'." () (funcall (symbol-function 'set) 'erlang-tags-buffer-installed-p nil) (funcall (symbol-function 'set) - 'find-tag-tag-order erlang-tags-orig-tag-order) + 'find-tag-tag-order erlang-tags-orig-tag-order) (funcall (symbol-function 'set) - 'find-tag-regexp-tag-order erlang-tags-orig-regexp-tag-order) + 'find-tag-regexp-tag-order erlang-tags-orig-regexp-tag-order) (funcall (symbol-function 'set) - 'find-tag-search-function erlang-tags-orig-search-function) + 'find-tag-search-function erlang-tags-orig-search-function) (funcall (symbol-function 'set) - 'find-tag-regexp-search-function - erlang-tags-orig-regexp-search-function))) + 'find-tag-regexp-search-function + erlang-tags-orig-regexp-search-function))) (defun erlang-tags-recognize-tags-table () @@ -4761,10 +4761,10 @@ for a tag on the form `module:tag'." (if (string-match ":" tag) (setq tag (substring tag (match-end 0) nil))) (if (eq erlang-tags-orig-regexp-search-function - 'erlang-tags-regexp-search-forward) + 'erlang-tags-regexp-search-forward) (re-search-forward tag bound noerror count) (funcall erlang-tags-orig-regexp-search-function - tag bound noerror count))) + tag bound noerror count))) ;;; Tags completion, Emacs 19 `etags' specific. ;;; @@ -4810,18 +4810,18 @@ about Erlang modules." ((and erlang-tags-installed (fboundp 'complete-tag) (fboundp 'tags-complete-tag)) ; Emacs 19-22 - (let ((orig-tags-complete-tag (symbol-function 'tags-complete-tag))) - (fset 'tags-complete-tag - (symbol-function 'erlang-tags-complete-tag)) - (unwind-protect + (let ((orig-tags-complete-tag (symbol-function 'tags-complete-tag))) + (fset 'tags-complete-tag + (symbol-function 'erlang-tags-complete-tag)) + (unwind-protect (complete-tag) - (fset 'tags-complete-tag orig-tags-complete-tag)))) - ((fboundp 'complete-tag) ; Emacs 19 + (fset 'tags-complete-tag orig-tags-complete-tag)))) + ((fboundp 'complete-tag) ; Emacs 19 (complete-tag)) - ((fboundp 'tag-complete-symbol) ; XEmacs - (funcall (symbol-function 'tag-complete-symbol))) - (t - (error "This version of Emacs can't complete tags")))) + ((fboundp 'tag-complete-symbol) ; XEmacs + (funcall (symbol-function 'tag-complete-symbol))) + (t + (error "This version of Emacs can't complete tags")))) (defun erlang-find-tag-for-completion () @@ -4845,9 +4845,9 @@ about Erlang modules." ;; If we need to ask for the tag table, allow that. (let ((enable-recursive-minibuffers t)) (visit-tags-table-buffer)) - (if (eq what t) - (all-completions string (erlang-tags-completion-table) predicate) - (try-completion string (erlang-tags-completion-table) predicate))))) + (if (eq what t) + (all-completions string (erlang-tags-completion-table) predicate) + (try-completion string (erlang-tags-completion-table) predicate))))) ;; `tags-completion-table' calls itself recursively, make it @@ -4857,22 +4857,22 @@ about Erlang modules." (defun erlang-tags-completion-table () "Build completion table. Tags on the form `tag' or `module:tag'." (setq erlang-tags-orig-completion-table - (symbol-function 'tags-completion-table)) + (symbol-function 'tags-completion-table)) (fset 'tags-completion-table - (symbol-function 'erlang-tags-completion-table-1)) + (symbol-function 'erlang-tags-completion-table-1)) (unwind-protect (erlang-tags-completion-table-1) (fset 'tags-completion-table - erlang-tags-orig-completion-table))) + erlang-tags-orig-completion-table))) (defun erlang-tags-completion-table-1 () (make-local-variable 'erlang-tags-completion-table) (or erlang-tags-completion-table (let ((tags-completion-table nil) - (tags-completion-table-function - 'erlang-etags-tags-completion-table)) - (funcall erlang-tags-orig-completion-table) - (setq erlang-tags-completion-table tags-completion-table)))) + (tags-completion-table-function + 'erlang-etags-tags-completion-table)) + (funcall erlang-tags-orig-completion-table) + (setq erlang-tags-completion-table tags-completion-table)))) @@ -4973,7 +4973,7 @@ about Erlang modules." (cl-defmethod xref-backend-identifier-completion-table ((_backend (eql erlang-etags))) (let ((erlang-replace-etags-tags-completion-table t)) - (tags-completion-table)))))) + (tags-completion-table)))))) @@ -5215,28 +5215,28 @@ The following special commands are available: ;; Some older versions of comint don't have an input ring. (if (fboundp 'comint-read-input-ring) (progn - (setq comint-input-ring-file-name erlang-input-ring-file-name) - (comint-read-input-ring t) - (make-local-variable 'kill-buffer-hook) - (add-hook 'kill-buffer-hook 'comint-write-input-ring))) + (setq comint-input-ring-file-name erlang-input-ring-file-name) + (comint-read-input-ring t) + (make-local-variable 'kill-buffer-hook) + (add-hook 'kill-buffer-hook 'comint-write-input-ring))) ;; At least in Emacs 21, we need to be in `compilation-minor-mode' ;; for `next-error' to work. We can avoid it clobbering the shell ;; keys thus. (when inferior-erlang-use-cmm (compilation-minor-mode 1) (set (make-local-variable 'minor-mode-overriding-map-alist) - `((compilation-minor-mode - . ,(let ((map (make-sparse-keymap))) - ;; It would be useful to put keymap properties on the - ;; error lines so that we could use RET and mouse-2 - ;; on them directly. - (when (boundp 'compilation-skip-threshold) ; new compile.el - (define-key map [mouse-2] #'erlang-mouse-2-command) - (define-key map "\C-m" #'erlang-RET-command)) - (if (boundp 'compilation-menu-map) - (define-key map [menu-bar compilation] - (cons "Errors" compilation-menu-map))) - map))))) + `((compilation-minor-mode + . ,(let ((map (make-sparse-keymap))) + ;; It would be useful to put keymap properties on the + ;; error lines so that we could use RET and mouse-2 + ;; on them directly. + (when (boundp 'compilation-skip-threshold) ; new compile.el + (define-key map [mouse-2] #'erlang-mouse-2-command) + (define-key map "\C-m" #'erlang-RET-command)) + (if (boundp 'compilation-menu-map) + (define-key map [menu-bar compilation] + (cons "Errors" compilation-menu-map))) + map))))) (erlang-tags-init) (run-hooks 'erlang-shell-mode-hook)) @@ -5246,9 +5246,9 @@ The following special commands are available: Selects Comint or Compilation mode command as appropriate." (interactive "e") (if (save-window-excursion - (save-excursion - (mouse-set-point event) - (consp (get-text-property (line-beginning-position) 'message)))) + (save-excursion + (mouse-set-point event) + (consp (get-text-property (line-beginning-position) 'message)))) (call-interactively (lookup-key compilation-mode-map [mouse-2])) (call-interactively (lookup-key comint-mode-map [mouse-2])))) @@ -5264,7 +5264,7 @@ Selects Comint or Compilation mode command as appropriate." (define-key map "\M-\t" 'erlang-complete-tag) (define-key map "\C-a" 'comint-bol) ; Normally the other way around. (define-key map "\C-c\C-a" 'beginning-of-line) - (define-key map "\C-d" nil) ; Was `comint-delchar-or-maybe-eof' + (define-key map "\C-d" nil) ; Was `comint-delchar-or-maybe-eof' (define-key map "\M-\C-m" 'compile-goto-error) (unless inferior-erlang-use-cmm (define-key map "\C-x`" 'erlang-next-error))) @@ -5338,8 +5338,8 @@ editing control characters: (when current-prefix-arg (list (if (fboundp 'read-shell-command) ;; `read-shell-command' is a new function in Emacs 23. - (read-shell-command "Erlang command: ") - (read-string "Erlang command: "))))) + (read-shell-command "Erlang command: ") + (read-string "Erlang command: "))))) (require 'comint) (let (cmd opts) (if command @@ -5366,16 +5366,16 @@ editing control characters: (setq list-buffers-directory fake-file-name)))) (setq inferior-erlang-process - (get-buffer-process inferior-erlang-buffer)) - (if (> 21 erlang-emacs-major-version) ; funcalls to avoid compiler warnings - (funcall (symbol-function 'set-process-query-on-exit-flag) - inferior-erlang-process nil) + (get-buffer-process inferior-erlang-buffer)) + (if (> 21 erlang-emacs-major-version) ; funcalls to avoid compiler warnings + (funcall (symbol-function 'set-process-query-on-exit-flag) + inferior-erlang-process nil) (funcall (symbol-function 'process-kill-without-query) inferior-erlang-process)) (if erlang-inferior-shell-split-window (switch-to-buffer-other-window inferior-erlang-buffer) - (switch-to-buffer inferior-erlang-buffer)) + (switch-to-buffer inferior-erlang-buffer)) (if (and (not (eq system-type 'windows-nt)) - (eq inferior-erlang-shell-type 'newshell)) + (eq inferior-erlang-shell-type 'newshell)) (setq comint-process-echoes t)) (erlang-shell-mode)) @@ -5407,22 +5407,22 @@ frame will become deselected before the next command." (or (inferior-erlang-running-p) (error "No inferior Erlang process is running")) (let ((win (inferior-erlang-window - inferior-erlang-display-buffer-any-frame)) - (frames-p (fboundp 'selected-frame))) + inferior-erlang-display-buffer-any-frame)) + (frames-p (fboundp 'selected-frame))) (if (null win) - (let ((old-win (selected-window))) - (save-excursion - (switch-to-buffer-other-window inferior-erlang-buffer) - (setq win (selected-window))) - (select-window old-win)) + (let ((old-win (selected-window))) + (save-excursion + (switch-to-buffer-other-window inferior-erlang-buffer) + (setq win (selected-window))) + (select-window old-win)) (if (and window-system - frames-p - (or select - (eq inferior-erlang-display-buffer-any-frame 'raise)) - (not (eq (selected-frame) (window-frame win)))) - (raise-frame (window-frame win)))) + frames-p + (or select + (eq inferior-erlang-display-buffer-any-frame 'raise)) + (not (eq (selected-frame) (window-frame win)))) + (raise-frame (window-frame win)))) (if select - (select-window win)) + (select-window win)) (sit-for 0) win)) @@ -5439,8 +5439,8 @@ frame will become deselected before the next command." "Return the window containing the inferior Erlang, or nil." (and (inferior-erlang-running-p) (if (and all-frames (>= erlang-emacs-major-version 19)) - (get-buffer-window inferior-erlang-buffer t) - (get-buffer-window inferior-erlang-buffer)))) + (get-buffer-window inferior-erlang-buffer t) + (get-buffer-window inferior-erlang-buffer)))) (defun inferior-erlang-wait-prompt () @@ -5448,21 +5448,21 @@ frame will become deselected before the next command." (if (eq inferior-erlang-prompt-timeout t) () (or (inferior-erlang-running-p) - (error "No inferior Erlang shell is running")) + (error "No inferior Erlang shell is running")) (with-current-buffer inferior-erlang-buffer (let ((msg nil)) - (while (save-excursion - (goto-char (process-mark inferior-erlang-process)) - (forward-line 0) - (not (looking-at comint-prompt-regexp))) - (if msg - () - (setq msg t) - (message "Waiting for Erlang shell prompt (press C-g to abort).")) - (or (accept-process-output inferior-erlang-process - inferior-erlang-prompt-timeout) - (error "No Erlang shell prompt before timeout"))) - (if msg (message "")))))) + (while (save-excursion + (goto-char (process-mark inferior-erlang-process)) + (forward-line 0) + (not (looking-at comint-prompt-regexp))) + (if msg + () + (setq msg t) + (message "Waiting for Erlang shell prompt (press C-g to abort).")) + (or (accept-process-output inferior-erlang-process + inferior-erlang-prompt-timeout) + (error "No Erlang shell prompt before timeout"))) + (if msg (message "")))))) (defun inferior-erlang-send-empty-cmd-unless-already-at-prompt () "If not already at a prompt, try to send an empty cmd to get a prompt. @@ -5471,12 +5471,12 @@ situations, for instance if a crash or error report from sasl has been printed after the last prompt." (with-current-buffer inferior-erlang-buffer (if (> (point-max) 1) - ;; make sure we get a prompt if buffer contains data - (if (save-excursion - (goto-char (process-mark inferior-erlang-process)) - (forward-line 0) - (not (looking-at comint-prompt-regexp))) - (inferior-erlang-send-command ""))))) + ;; make sure we get a prompt if buffer contains data + (if (save-excursion + (goto-char (process-mark inferior-erlang-process)) + (forward-line 0) + (not (looking-at comint-prompt-regexp))) + (inferior-erlang-send-command ""))))) (autoload 'comint-send-input "comint") @@ -5493,10 +5493,10 @@ Return the position after the newly inserted command." (or (inferior-erlang-running-p) (error "No inferior Erlang process is running")) (let ((old-buffer (current-buffer)) - (insert-point (marker-position (process-mark inferior-erlang-process))) - (insert-length (if comint-process-echoes - 0 - (1+ (length cmd))))) + (insert-point (marker-position (process-mark inferior-erlang-process))) + (insert-length (if comint-process-echoes + 0 + (1+ (length cmd))))) (set-buffer inferior-erlang-buffer) (goto-char insert-point) (insert cmd) @@ -5509,21 +5509,21 @@ Return the position after the newly inserted command." ;; This was previously cautioned against in the Lisp manual. It ;; has been sorted out in Emacs 21. -- fx (let ((comint-eol-on-send nil) - (comint-input-filter (if hist comint-input-filter 'ignore))) + (comint-input-filter (if hist comint-input-filter 'ignore))) (if (and (not erlang-xemacs-p) - (>= emacs-major-version 22)) - (comint-send-input nil t) - (comint-send-input))) + (>= emacs-major-version 22)) + (comint-send-input nil t) + (comint-send-input))) ;; Adjust all windows whose points are incorrect. (if (null comint-process-echoes) - (walk-windows - (function - (lambda (window) - (if (and (eq (window-buffer window) inferior-erlang-buffer) - (= (window-point window) insert-point)) - (set-window-point window - (+ insert-point insert-length))))) - nil t)) + (walk-windows + (function + (lambda (window) + (if (and (eq (window-buffer window) inferior-erlang-buffer) + (= (window-point window) insert-point)) + (set-window-point window + (+ insert-point insert-length))))) + nil t)) (set-buffer old-buffer) (+ insert-point insert-length))) @@ -5532,17 +5532,17 @@ Return the position after the newly inserted command." "Remove `^H' (delete) and the characters it was supposed to remove." (interactive) (if (and (boundp 'comint-last-input-end) - (boundp 'comint-last-output-start)) + (boundp 'comint-last-output-start)) (save-excursion - (goto-char - (if (erlang-interactive-p) - (symbol-value 'comint-last-input-end) - (symbol-value 'comint-last-output-start))) - (while (progn (skip-chars-forward "^\C-h") - (not (eq (point) (point-max)))) - (delete-char 1) - (or (bolp) - (backward-delete-char 1)))))) + (goto-char + (if (erlang-interactive-p) + (symbol-value 'comint-last-input-end) + (symbol-value 'comint-last-output-start))) + (while (progn (skip-chars-forward "^\C-h") + (not (eq (point) (point-max)))) + (delete-char 1) + (or (bolp) + (backward-delete-char 1)))))) ;; Basically `comint-strip-ctrl-m', with a few extra checks. @@ -5550,15 +5550,15 @@ Return the position after the newly inserted command." "Strip trailing `^M' characters from the current output group." (interactive) (if (and (boundp 'comint-last-input-end) - (boundp 'comint-last-output-start)) + (boundp 'comint-last-output-start)) (let ((pmark (process-mark (get-buffer-process (current-buffer))))) - (save-excursion - (goto-char - (if (erlang-interactive-p) - (symbol-value 'comint-last-input-end) - (symbol-value 'comint-last-output-start))) - (while (re-search-forward "\r+$" pmark t) - (replace-match "" t t)))))) + (save-excursion + (goto-char + (if (erlang-interactive-p) + (symbol-value 'comint-last-input-end) + (symbol-value 'comint-last-output-start))) + (while (re-search-forward "\r+$" pmark t) + (replace-match "" t t)))))) (defun inferior-erlang-compile (arg) @@ -5581,18 +5581,18 @@ There exists two workarounds for this bug: (save-some-buffers) (inferior-erlang-prepare-for-input) (let* ((dir (inferior-erlang-compile-outdir)) - (noext (substring (erlang-local-buffer-file-name) 0 -4)) - (opts (append (list (cons 'outdir dir)) - (if current-prefix-arg - (list 'debug_info 'export_all)) - erlang-compile-extra-opts)) - end) + (noext (substring (erlang-local-buffer-file-name) 0 -4)) + (opts (append (list (cons 'outdir dir)) + (if current-prefix-arg + (list 'debug_info 'export_all)) + erlang-compile-extra-opts)) + end) (with-current-buffer inferior-erlang-buffer (when (fboundp 'compilation-forget-errors) (compilation-forget-errors))) (setq end (inferior-erlang-send-command - (inferior-erlang-compute-compile-command noext opts) - nil)) + (inferior-erlang-compute-compile-command noext opts) + nil)) (sit-for 0) (inferior-erlang-wait-prompt) (with-current-buffer inferior-erlang-buffer @@ -5606,7 +5606,7 @@ The buffer is displayed, according to `inferior-erlang-display-buffer' unless the optional NO-DISPLAY is non-nil." (or (inferior-erlang-running-p) (save-excursion - (inferior-erlang))) + (inferior-erlang))) (or (inferior-erlang-running-p) (error "Error starting inferior Erlang shell")) (if (not no-display) @@ -5618,96 +5618,96 @@ unless the optional NO-DISPLAY is non-nil." (defun inferior-erlang-compile-outdir () "Return the directory to compile the current buffer into." (let* ((buffer-dir (directory-file-name - (file-name-directory (erlang-local-buffer-file-name)))) - (parent-dir (directory-file-name - (file-name-directory buffer-dir))) + (file-name-directory (erlang-local-buffer-file-name)))) + (parent-dir (directory-file-name + (file-name-directory buffer-dir))) (ebin-dir (concat (file-name-as-directory parent-dir) "ebin")) - (buffer-dir-base-name (file-name-nondirectory - (expand-file-name - (concat (file-name-as-directory buffer-dir) - "."))))) + (buffer-dir-base-name (file-name-nondirectory + (expand-file-name + (concat (file-name-as-directory buffer-dir) + "."))))) (if (and (string= buffer-dir-base-name "src") - (file-directory-p ebin-dir)) - (file-name-as-directory ebin-dir) + (file-directory-p ebin-dir)) + (file-name-as-directory ebin-dir) (file-name-as-directory buffer-dir)))) (defun inferior-erlang-compute-compile-command (module-name opts) (let ((ccfn erlang-compile-command-function-alist) - (res (inferior-erlang-compute-erl-compile-command module-name opts)) - ccfn-entry - done + (res (inferior-erlang-compute-erl-compile-command module-name opts)) + ccfn-entry + done result) (if (not (null (erlang-local-buffer-file-name))) - (while (and (not done) (not (null ccfn))) - (setq ccfn-entry (car ccfn)) - (setq ccfn (cdr ccfn)) - (if (string-match (car ccfn-entry) (erlang-local-buffer-file-name)) - (let ((c-fn (cdr ccfn-entry))) - (setq done t) - (if (not (null c-fn)) - (setq result (funcall c-fn module-name opts))))))) + (while (and (not done) (not (null ccfn))) + (setq ccfn-entry (car ccfn)) + (setq ccfn (cdr ccfn)) + (if (string-match (car ccfn-entry) (erlang-local-buffer-file-name)) + (let ((c-fn (cdr ccfn-entry))) + (setq done t) + (if (not (null c-fn)) + (setq result (funcall c-fn module-name opts))))))) result)) (defun inferior-erlang-compute-erl-compile-command (module-name opts) (let* ((out-dir-opt (assoc 'outdir opts)) - (out-dir (cdr out-dir-opt))) + (out-dir (cdr out-dir-opt))) (if erlang-compile-use-outdir - (format "%s(\"%s\"%s)." - erlang-compile-erlang-function - module-name - (inferior-erlang-format-comma-opts opts)) + (format "%s(\"%s\"%s)." + erlang-compile-erlang-function + module-name + (inferior-erlang-format-comma-opts opts)) (let (;; Hopefully, noone else will ever use these... - (tmpvar "Tmp7236") - (tmpvar2 "Tmp8742")) - (format - (concat - "f(%s), {ok, %s} = file:get_cwd(), " - "file:set_cwd(\"%s\"), " - "%s = %s(\"%s\"%s), file:set_cwd(%s), f(%s), %s.") - tmpvar2 tmpvar - out-dir - tmpvar2 - erlang-compile-erlang-function - module-name (inferior-erlang-format-comma-opts - (remq out-dir-opt opts)) - tmpvar tmpvar tmpvar2))))) + (tmpvar "Tmp7236") + (tmpvar2 "Tmp8742")) + (format + (concat + "f(%s), {ok, %s} = file:get_cwd(), " + "file:set_cwd(\"%s\"), " + "%s = %s(\"%s\"%s), file:set_cwd(%s), f(%s), %s.") + tmpvar2 tmpvar + out-dir + tmpvar2 + erlang-compile-erlang-function + module-name (inferior-erlang-format-comma-opts + (remq out-dir-opt opts)) + tmpvar tmpvar tmpvar2))))) (defun inferior-erlang-compute-leex-compile-command (module-name opts) (let ((file-name (erlang-local-buffer-file-name)) - (erl-compile-expr (inferior-erlang-remove-any-trailing-dot - (inferior-erlang-compute-erl-compile-command - module-name opts)))) + (erl-compile-expr (inferior-erlang-remove-any-trailing-dot + (inferior-erlang-compute-erl-compile-command + module-name opts)))) (format (concat "f(LErr1__), f(LErr2__), " - "case case leex:file(\"%s\", [%s]) of" - " ok -> ok;" - " {ok,_} -> ok;" - " {ok,_,_} -> ok;" - " LErr1__ -> LErr1__ " - "end of" - " ok -> %s;" - " LErr2__ -> LErr2__ " - "end.") - file-name - (inferior-erlang-format-comma-opts erlang-leex-compile-opts) - erl-compile-expr))) + "case case leex:file(\"%s\", [%s]) of" + " ok -> ok;" + " {ok,_} -> ok;" + " {ok,_,_} -> ok;" + " LErr1__ -> LErr1__ " + "end of" + " ok -> %s;" + " LErr2__ -> LErr2__ " + "end.") + file-name + (inferior-erlang-format-comma-opts erlang-leex-compile-opts) + erl-compile-expr))) (defun inferior-erlang-compute-yecc-compile-command (module-name opts) (let ((file-name (erlang-local-buffer-file-name)) - (erl-compile-expr (inferior-erlang-remove-any-trailing-dot - (inferior-erlang-compute-erl-compile-command - module-name opts)))) + (erl-compile-expr (inferior-erlang-remove-any-trailing-dot + (inferior-erlang-compute-erl-compile-command + module-name opts)))) (format (concat "f(YErr1__), f(YErr2__), " - "case case yecc:file(\"%s\", [%s]) of" - " {ok,_} -> ok;" - " {ok,_,_} -> ok;" - " YErr1__ -> YErr1__ " - "end of" - " ok -> %s;" - " YErr2__ -> YErr2__ " - "end.") - file-name - (inferior-erlang-format-comma-opts erlang-yecc-compile-opts) - erl-compile-expr))) + "case case yecc:file(\"%s\", [%s]) of" + " {ok,_} -> ok;" + " {ok,_,_} -> ok;" + " YErr1__ -> YErr1__ " + "end of" + " ok -> %s;" + " YErr2__ -> YErr2__ " + "end.") + file-name + (inferior-erlang-format-comma-opts erlang-yecc-compile-opts) + erl-compile-expr))) (defun inferior-erlang-remove-any-trailing-dot (str) (if (string= (substring str -1) ".") @@ -5753,11 +5753,11 @@ unless the optional NO-DISPLAY is non-nil." ;; the file name "/some/path/x.erl" without the ;; tramp-prefix "/ssh:host.example.com:". (cond ((null (buffer-file-name)) - nil) - ((erlang-tramp-remote-file-p) - (erlang-tramp-get-localname)) - (t - (buffer-file-name)))) + nil) + ((erlang-tramp-remote-file-p) + (erlang-tramp-get-localname)) + (t + (buffer-file-name)))) (defun erlang-tramp-remote-file-p () (and (fboundp 'tramp-tramp-file-p) @@ -5783,22 +5783,22 @@ unless the optional NO-DISPLAY is non-nil." Capable of finding error messages in an inferior Erlang buffer." (interactive "P") (let ((done nil) - (buf (or (and (boundp 'next-error-last-buffer) - next-error-last-buffer) - (and (boundp 'compilation-last-buffer) - compilation-last-buffer)))) + (buf (or (and (boundp 'next-error-last-buffer) + next-error-last-buffer) + (and (boundp 'compilation-last-buffer) + compilation-last-buffer)))) (if (and (bufferp buf) - (with-current-buffer buf - (and (eq major-mode 'erlang-shell-mode) - (setq major-mode 'compilation-mode)))) - (unwind-protect - (progn - (setq done t) - (next-error argp)) - (with-current-buffer buf - (setq major-mode 'erlang-shell-mode)))) + (with-current-buffer buf + (and (eq major-mode 'erlang-shell-mode) + (setq major-mode 'compilation-mode)))) + (unwind-protect + (progn + (setq done t) + (next-error argp)) + (with-current-buffer buf + (setq major-mode 'erlang-shell-mode)))) (or done - (next-error argp)))) + (next-error argp)))) (defun inferior-erlang-change-directory (&optional dir) @@ -5835,44 +5835,44 @@ sum([], Sum) -> Sum." (interactive "r") (save-excursion (let (;; regexp for matching arrows. without a prefix argument, - ;; the regexp matches function heads. With a prefix, it - ;; matches any arrow. - (re (if current-prefix-arg - "^.*\\(\\)->" - (eval-when-compile - (concat "^" erlang-atom-regexp ".*\\(\\)->")))) - ;; part of regexp matching directly before the arrow - (arrow-match-pos (if current-prefix-arg - 1 - (1+ erlang-atom-regexp-matches))) - ;; accumulator for positions where arrows are found, ordered - ;; by buffer position (from greatest to smallest) - (arrow-positions '()) - ;; accumulator for longest distance from start of line to arrow - (most-indent 0) - ;; marker to track the end of the region we're aligning - (end-marker (progn (goto-char end) - (point-marker)))) + ;; the regexp matches function heads. With a prefix, it + ;; matches any arrow. + (re (if current-prefix-arg + "^.*\\(\\)->" + (eval-when-compile + (concat "^" erlang-atom-regexp ".*\\(\\)->")))) + ;; part of regexp matching directly before the arrow + (arrow-match-pos (if current-prefix-arg + 1 + (1+ erlang-atom-regexp-matches))) + ;; accumulator for positions where arrows are found, ordered + ;; by buffer position (from greatest to smallest) + (arrow-positions '()) + ;; accumulator for longest distance from start of line to arrow + (most-indent 0) + ;; marker to track the end of the region we're aligning + (end-marker (progn (goto-char end) + (point-marker)))) ;; Pass 1: Find the arrow positions, adjust the whitespace ;; before each arrow to one space, and find the greatest ;; indentation level. (goto-char start) (while (re-search-forward re end-marker t) - (goto-char (match-beginning arrow-match-pos)) - (just-one-space) ; adjust whitespace - (setq arrow-positions (cons (point) arrow-positions)) - (setq most-indent (max most-indent (erlang-column-number)))) - (set-marker end-marker nil) ; free the marker + (goto-char (match-beginning arrow-match-pos)) + (just-one-space) ; adjust whitespace + (setq arrow-positions (cons (point) arrow-positions)) + (setq most-indent (max most-indent (erlang-column-number)))) + (set-marker end-marker nil) ; free the marker ;; Pass 2: Insert extra padding so that all arrow indentation is ;; equal. This is done last-to-first by buffer position, so that ;; inserting spaces before one arrow doesn't change the ;; positions of the next ones. (mapc (lambda (arrow-pos) - (goto-char arrow-pos) - (let* ((pad (- most-indent (erlang-column-number)))) - (when (> pad 0) - (insert-char ?\ pad)))) - arrow-positions)))) + (goto-char arrow-pos) + (let* ((pad (- most-indent (erlang-column-number)))) + (when (> pad 0) + (insert-char ?\ pad)))) + arrow-positions)))) (defun erlang-column-number () "Return the column number of the current position in the buffer. @@ -5884,7 +5884,7 @@ Tab characters are counted by their visual width." (save-excursion (erlang-beginning-of-function) (if (looking-at "[a-z0-9_]+") - (match-string 0)))) + (match-string 0)))) ;; Aliases for backward compatibility with older versions of Erlang Mode. ;; @@ -5903,7 +5903,7 @@ it assumes that NEWDEF is loaded." (erlang-obsolete 'calculate-erlang-indent 'erlang-calculate-indent) (erlang-obsolete 'calculate-erlang-stack-indent - 'erlang-calculate-stack-indent) + 'erlang-calculate-stack-indent) (erlang-obsolete 'at-erlang-keyword 'erlang-at-keyword) (erlang-obsolete 'at-erlang-operator 'erlang-at-operator) (erlang-obsolete 'beginning-of-erlang-clause 'erlang-beginning-of-clause) @@ -5918,12 +5918,12 @@ it assumes that NEWDEF is loaded." (defconst erlang-unload-hook (list (lambda () - (when (featurep 'advice) - (ad-unadvise 'Man-notify-when-ready) - (ad-unadvise 'set-visited-file-name))))) + (when (featurep 'advice) + (ad-unadvise 'Man-notify-when-ready) + (ad-unadvise 'set-visited-file-name))))) -(defun erlang-string-to-int (string) +(defun erlang-string-to-int (string) (if (fboundp 'string-to-number) (string-to-number string) (funcall (symbol-function 'string-to-int) string))) @@ -5936,6 +5936,7 @@ it assumes that NEWDEF is loaded." ;; Local variables: ;; coding: iso-8859-1 +;; indent-tabs-mode: nil ;; End: ;;; erlang.el ends here diff --git a/lib/tools/emacs/test.erl.indented b/lib/tools/emacs/test.erl.indented index 7a1ff6a954..14a4eca7c3 100644 --- a/lib/tools/emacs/test.erl.indented +++ b/lib/tools/emacs/test.erl.indented @@ -1,4 +1,4 @@ -%% -*- erlang -*- +%% -*- Mode: erlang; indent-tabs-mode: nil -*- %% %% %CopyrightBegin% %% @@ -27,7 +27,7 @@ %%% Created : 6 Oct 2009 by Dan Gudmundsson <[email protected]> %%%------------------------------------------------------------------- -%% Start off with syntax highlighting you have to verify this by looking here +%% Start off with syntax highlighting you have to verify this by looking here %% and see that the code looks alright -module(test). @@ -44,175 +44,175 @@ foo() -> %% Module attributes should be highlighted -export([t/1]). --record(record1, {a, - b, - c - }). +-record(record1, {a, + b, + c + }). -record(record2, { - a, - b - }). + a, + b + }). -record(record3, {a = 8#42423 bor - 8#4234, - b = 8#5432 - bor 2#1010101 - c = 123 + - 234, + 8#4234, + b = 8#5432 + bor 2#1010101 + c = 123 + + 234, d}). -record(record4, { - a = 8#42423 bor - 8#4234, - b = 8#5432 - bor 2#1010101 - c = 123 + - 234, - d}). + a = 8#42423 bor + 8#4234, + b = 8#5432 + bor 2#1010101 + c = 123 + + 234, + d}). -record(record5, { a = 1 :: integer() - , b = foobar :: atom() - }). + , b = foobar :: atom() + }). -define(MACRO_1, macro). -define(MACRO_2(_), macro). -spec t(integer()) -> any(). --type ann() :: Var :: integer(). --type ann2() :: Var :: - 'return' - | 'return_white_spaces' - | 'return_comments' - | 'text' | ann(). --type paren() :: - (ann2()). --type t1() :: atom(). --type t2() :: [t1()]. --type t3(Atom) :: integer(Atom). --type t4() :: t3(foobar). --type t5() :: {t1(), t3(foo)}. --type t6() :: 1 | 2 | 3 | - 'foo' | 'bar'. --type t7() :: []. --type t71() :: [_]. +-type ann() :: Var :: integer(). +-type ann2() :: Var :: + 'return' + | 'return_white_spaces' + | 'return_comments' + | 'text' | ann(). +-type paren() :: + (ann2()). +-type t1() :: atom(). +-type t2() :: [t1()]. +-type t3(Atom) :: integer(Atom). +-type t4() :: t3(foobar). +-type t5() :: {t1(), t3(foo)}. +-type t6() :: 1 | 2 | 3 | + 'foo' | 'bar'. +-type t7() :: []. +-type t71() :: [_]. -type t8() :: {any(),none(),pid(),port(), - reference(),float()}. --type t9() :: [1|2|3|foo|bar] | - list(a | b | c) | t71(). --type t10() :: {1|2|3|foo|t9()} | {}. --type t11() :: 1..2. --type t13() :: maybe_improper_list(integer(), t11()). --type t14() :: [erl_scan:foo() | - %% Should be highlighted - term() | - bool() | - byte() | - char() | - non_neg_integer() | nonempty_list() | - pos_integer() | - neg_integer() | - number() | - list() | - nonempty_improper_list() | nonempty_maybe_improper_list() | - maybe_improper_list() | string() | iolist() | byte() | - module() | - mfa() | - node() | - timeout() | - no_return() | - %% Should not be highlighted - nonempty_() | nonlist() | - erl_scan:bar(34, 92) | t13() | m:f(integer() | <<_:_*16>>)]. + reference(),float()}. +-type t9() :: [1|2|3|foo|bar] | + list(a | b | c) | t71(). +-type t10() :: {1|2|3|foo|t9()} | {}. +-type t11() :: 1..2. +-type t13() :: maybe_improper_list(integer(), t11()). +-type t14() :: [erl_scan:foo() | + %% Should be highlighted + term() | + bool() | + byte() | + char() | + non_neg_integer() | nonempty_list() | + pos_integer() | + neg_integer() | + number() | + list() | + nonempty_improper_list() | nonempty_maybe_improper_list() | + maybe_improper_list() | string() | iolist() | byte() | + module() | + mfa() | + node() | + timeout() | + no_return() | + %% Should not be highlighted + nonempty_() | nonlist() | + erl_scan:bar(34, 92) | t13() | m:f(integer() | <<_:_*16>>)]. -type t15() :: {binary(),<<>>,<<_:34>>,<<_:_*42>>, <<_:3,_:_*14>>,<<>>} | [<<>>|<<_:34>>|<<_:16>>| - <<_:3,_:_*1472>>|<<_:19,_:_*14>>| <<_:34>>| - <<_:34>>|<<_:34>>|<<_:34>>]. --type t16() :: fun(). --type t17() :: fun((...) -> paren()). --type t18() :: fun(() -> t17() | t16()). + <<_:3,_:_*1472>>|<<_:19,_:_*14>>| <<_:34>>| + <<_:34>>|<<_:34>>|<<_:34>>]. +-type t16() :: fun(). +-type t17() :: fun((...) -> paren()). +-type t18() :: fun(() -> t17() | t16()). -type t19() :: fun((t18()) -> t16()) | - fun((nonempty_maybe_improper_list('integer', any())| - 1|2|3|a|b|<<_:3,_:_*14>>|integer()) -> - nonempty_maybe_improper_list('integer', any())| - 1|2|3|a|b|<<_:3,_:_*14>>|integer()). --type t20() :: [t19(), ...]. --type t21() :: tuple(). --type t21(A) :: A. --type t22() :: t21(integer()). --type t23() :: #rec1{}. --type t24() :: #rec2{a :: t23(), b :: [atom()]}. --type t25() :: #rec3{f123 :: [t24() | - 1|2|3|4|a|b|c|d| - nonempty_maybe_improper_list(integer, any())]}. + fun((nonempty_maybe_improper_list('integer', any())| + 1|2|3|a|b|<<_:3,_:_*14>>|integer()) -> + nonempty_maybe_improper_list('integer', any())| + 1|2|3|a|b|<<_:3,_:_*14>>|integer()). +-type t20() :: [t19(), ...]. +-type t21() :: tuple(). +-type t21(A) :: A. +-type t22() :: t21(integer()). +-type t23() :: #rec1{}. +-type t24() :: #rec2{a :: t23(), b :: [atom()]}. +-type t25() :: #rec3{f123 :: [t24() | + 1|2|3|4|a|b|c|d| + nonempty_maybe_improper_list(integer, any())]}. -type t26() :: #rec4{ a :: integer() - , b :: any() - }. + , b :: any() + }. -type t27() :: { integer() - , atom() - }. + , atom() + }. -type t99() :: - {t2(),t4(),t5(),t6(),t7(),t8(),t10(),t14(), - t15(),t20(),t21(), t22(),t25()}. + {t2(),t4(),t5(),t6(),t7(),t8(),t10(),t14(), + t15(),t20(),t21(), t22(),t25()}. -spec t1(FooBar :: t99()) -> t99(); - (t2()) -> t2(); + (t2()) -> t2(); (t4()) -> t4() when is_subtype(t4(), t24); - (t23()) -> t23() when is_subtype(t23(), atom()), - is_subtype(t23(), t14()); - (t24()) -> t24() when is_subtype(t24(), atom()), - is_subtype(t24(), t14()), - is_subtype(t24(), t4()). + (t23()) -> t23() when is_subtype(t23(), atom()), + is_subtype(t23(), t14()); + (t24()) -> t24() when is_subtype(t24(), atom()), + is_subtype(t24(), t14()), + is_subtype(t24(), t4()). -spec over(I :: integer()) -> R1 :: foo:typen(); - (A :: atom()) -> R2 :: foo:atomen(); - (T :: tuple()) -> R3 :: bar:typen(). + (A :: atom()) -> R2 :: foo:atomen(); + (T :: tuple()) -> R3 :: bar:typen(). --spec mod:t2() -> any(). +-spec mod:t2() -> any(). --spec handle_cast(Cast :: {'exchange', node(), [[name(),...]]} - | {'del_member', name(), pid()}, - #state{}) -> {'noreply', #state{}}. +-spec handle_cast(Cast :: {'exchange', node(), [[name(),...]]} + | {'del_member', name(), pid()}, + #state{}) -> {'noreply', #state{}}. --spec handle_cast(Cast :: - {'exchange', node(), [[name(),...]]} - | {'del_member', name(), pid()}, - #state{}) -> {'noreply', #state{}}. +-spec handle_cast(Cast :: + {'exchange', node(), [[name(),...]]} + | {'del_member', name(), pid()}, + #state{}) -> {'noreply', #state{}}. -spec all(fun((T) -> boolean()), List :: [T]) -> - boolean() when is_subtype(T, term()). % (*) + boolean() when is_subtype(T, term()). % (*) --spec get_closest_pid(term()) -> - Return :: pid() - | {'error', {'no_process', term()} - | {'no_such_group', term()}}. +-spec get_closest_pid(term()) -> + Return :: pid() + | {'error', {'no_process', term()} + | {'no_such_group', term()}}. -spec add( X :: integer() - , Y :: integer() - ) -> integer(). + , Y :: integer() + ) -> integer(). --opaque attributes_data() :: - [{'column', column()} | {'line', info_line()} | - {'text', string()}] | {line(),column()}. +-opaque attributes_data() :: + [{'column', column()} | {'line', info_line()} | + {'text', string()}] | {line(),column()}. -record(r,{ f1 :: attributes_data(), - f222 = foo:bar(34, #rec3{}, 234234234423, - aassdsfsdfsdf, 2234242323) :: - [t24() | 1|2|3|4|a|b|c|d| - nonempty_maybe_improper_list(integer, any())], - f333 :: [t24() | 1|2|3|4|a|b|c|d| - nonempty_maybe_improper_list(integer, any())], - f3 = x:y(), - f4 = x:z() :: t99(), - f17 :: 'undefined', - f18 :: 1 | 2 | 'undefined', - f19 = 3 :: integer()|undefined, - f5 = 3 :: undefined|integer()}). + f222 = foo:bar(34, #rec3{}, 234234234423, + aassdsfsdfsdf, 2234242323) :: + [t24() | 1|2|3|4|a|b|c|d| + nonempty_maybe_improper_list(integer, any())], + f333 :: [t24() | 1|2|3|4|a|b|c|d| + nonempty_maybe_improper_list(integer, any())], + f3 = x:y(), + f4 = x:z() :: t99(), + f17 :: 'undefined', + f18 :: 1 | 2 | 'undefined', + f19 = 3 :: integer()|undefined, + f5 = 3 :: undefined|integer()}). -record(state, { - sequence_number = 1 :: integer() - }). + sequence_number = 1 :: integer() + }). highlighting(X) % Function definitions should be highlighted @@ -230,12 +230,12 @@ highlighting(X) % Function definitions should be highlighted '#1',atom, $", atom, % atom should be ok - $', atom, + $', atom, "string$", atom, "string$", atom, % currently buggy I know... "string\$", atom, % workaround for bug above - "char $in string", atom, + "char $in string", atom, 'atom$', atom, 'atom$', atom, 'atom\$', atom, @@ -270,15 +270,15 @@ highlighting(X) % Function definitions should be highlighted erlang:anything(lists), %% Guards is_atom(foo), is_float(2.3), is_integer(32), is_number(4323.3), - is_function(Fun), is_pid(self()), + is_function(Fun), is_pid(self()), not_a_guard:is_list([]), %% Other Types atom, % not (currently) hightlighted - 234234, + 234234, 234.43, - [list, are, not, higlighted], + [list, are, not, higlighted], {nor, is, tuple}, ok. @@ -290,35 +290,35 @@ highlighting(X) % Function definitions should be highlighted %% Indented - % Right + % Right -indent_basics(X, Y, Z) +indent_basics(X, Y, Z) when X > 42, Z < 13; Y =:= 4711 -> %% comments - % right comments - case lists:filter(fun(_, AlongName, - B, - C) -> - true - end, - [a,v,b]) + % right comments + case lists:filter(fun(_, AlongName, + B, + C) -> + true + end, + [a,v,b]) of - [] -> - Y = 5 * 43, - ok; - [_|_] -> - Y = 5 * 43, - ok + [] -> + Y = 5 * 43, + ok; + [_|_] -> + Y = 5 * 43, + ok end, Y, %% List, tuples and binaries - [a, + [a, b, c ], - [ a, + [ a, b, c ], @@ -326,10 +326,10 @@ indent_basics(X, Y, Z) a, b ], - {a, + {a, b,c }, - { a, + { a, b,c }, @@ -366,16 +366,16 @@ indent_basics(X, Y, Z) c ), - call(2#42423 bor - #4234, - 2#5432, - other_arg), + call(2#42423 bor + #4234, + 2#5432, + other_arg), ok; -indent_basics(Xlongname, - #struct{a=Foo, - b=Bar}, - [X| - Y]) -> +indent_basics(Xlongname, + #struct{a=Foo, + b=Bar}, + [X| + Y]) -> testing_next_clause, ok; indent_basics( % AD added clause @@ -408,295 +408,295 @@ indent_nested() -> indent_icr(Z) -> % icr = if case receive %% If if Z >= 0 -> - X = 43 div 4, - foo(X); + X = 43 div 4, + foo(X); Z =< 10 -> - X = 43 div 4, - foo(X); + X = 43 div 4, + foo(X); Z == 5 orelse Z == 7 -> - X = 43 div 4, - foo(X); + X = 43 div 4, + foo(X); true -> - if_works + if_works end, %% Case case {Z, foo, bar} of - {Z,_,_} -> - X = 43 div 4, - foo(X); - {Z,_,_} when - Z =:= 42 -> % AD line should be indented as a when - X = 43 div 4, - foo(X); - {Z,_,_} - when Z < 10 -> % AD when should be indented - X = 43 div 4, - foo(X); - {Z,_,_} - when % AD when should be indented - Z < 10 % and the guards should follow when - andalso % unsure about how though - true -> - X = 43 div 4, - foo(X) + {Z,_,_} -> + X = 43 div 4, + foo(X); + {Z,_,_} when + Z =:= 42 -> % AD line should be indented as a when + X = 43 div 4, + foo(X); + {Z,_,_} + when Z < 10 -> % AD when should be indented + X = 43 div 4, + foo(X); + {Z,_,_} + when % AD when should be indented + Z < 10 % and the guards should follow when + andalso % unsure about how though + true -> + X = 43 div 4, + foo(X) end, %% begin begin - sune, - X = 74234 + foo(8456) + - 345 div 43, - ok + sune, + X = 74234 + foo(8456) + + 345 div 43, + ok end, %% receive - receive - {Z,_,_} -> - X = 43 div 4, - foo(X); - Z -> - X = 43 div 4, - foo(X) + receive + {Z,_,_} -> + X = 43 div 4, + foo(X); + Z -> + X = 43 div 4, + foo(X) end, receive - {Z,_,_} -> - X = 43 div 4, - foo(X); - Z % AD added clause - when Z =:= 1 -> % This line should be indented by 2 - X = 43 div 4, - foo(X); - Z when % AD added clause - Z =:= 2 -> % This line should be indented by 2 - X = 43 div 4, - foo(X); - Z -> - X = 43 div 4, - foo(X) + {Z,_,_} -> + X = 43 div 4, + foo(X); + Z % AD added clause + when Z =:= 1 -> % This line should be indented by 2 + X = 43 div 4, + foo(X); + Z when % AD added clause + Z =:= 2 -> % This line should be indented by 2 + X = 43 div 4, + foo(X); + Z -> + X = 43 div 4, + foo(X) after infinity -> - foo(X), - asd(X), - 5*43 + foo(X), + asd(X), + 5*43 end, receive - after 10 -> - foo(X), - asd(X), - 5*43 + after 10 -> + foo(X), + asd(X), + 5*43 end, ok. indent_fun() -> %% Changed fun to one indention level - Var = spawn(fun(X) - when X == 2; - X > 10 -> - hello, - case Hello() of - true when is_atom(X) -> - foo; - false -> - bar - end; - (Foo) when is_atom(Foo), - is_integer(X) -> - X = 6* 45, - Y = true andalso - kalle - end), + Var = spawn(fun(X) + when X == 2; + X > 10 -> + hello, + case Hello() of + true when is_atom(X) -> + foo; + false -> + bar + end; + (Foo) when is_atom(Foo), + is_integer(X) -> + X = 6* 45, + Y = true andalso + kalle + end), %% check EEP37 named funs Fn1 = fun Fact(N) when N > 0 -> - F = Fact(N-1), - N * F; - Fact(0) -> - 1 - end, + F = Fact(N-1), + N * F; + Fact(0) -> + 1 + end, %% check anonymous funs too Fn2 = fun(0) -> - 1; - (N) -> - N - end, + 1; + (N) -> + N + end, ok. indent_try_catch() -> try - io:format(stdout, "Parsing file ~s, ", - [St0#leex.xfile]), - {ok,Line3,REAs,Actions,St3} = - parse_rules(Xfile, Line2, Macs, St2) + io:format(stdout, "Parsing file ~s, ", + [St0#leex.xfile]), + {ok,Line3,REAs,Actions,St3} = + parse_rules(Xfile, Line2, Macs, St2) catch - exit:{badarg,R} -> - foo(R), - io:format(stdout, - "ERROR reason ~p~n", - R); - error:R % AD added clause - when R =:= 42 -> % when should be indented - foo(R); - error:R % AD added clause - when % when should be indented - R =:= 42 -> % but unsure about this (maybe 2 more) - foo(R); - error:R when % AD added clause - R =:= foo -> % line should be 2 indented (works) - foo(R); - error:R -> - foo(R), - io:format(stdout, - "ERROR reason ~p~n", - R) + exit:{badarg,R} -> + foo(R), + io:format(stdout, + "ERROR reason ~p~n", + R); + error:R % AD added clause + when R =:= 42 -> % when should be indented + foo(R); + error:R % AD added clause + when % when should be indented + R =:= 42 -> % but unsure about this (maybe 2 more) + foo(R); + error:R when % AD added clause + R =:= foo -> % line should be 2 indented (works) + foo(R); + error:R -> + foo(R), + io:format(stdout, + "ERROR reason ~p~n", + R) after - foo('after'), - file:close(Xfile) + foo('after'), + file:close(Xfile) end; indent_try_catch() -> try - foo(bar) + foo(bar) of - X when true andalso - kalle -> - io:format(stdout, "Parsing file ~s, ", - [St0#leex.xfile]), - {ok,Line3,REAs,Actions,St3} = - parse_rules(Xfile, Line2, Macs, St2); - X % AD added clause - when false andalso % when should be 2 indented - bengt -> - gurka(); - X when % AD added clause - false andalso % line should be 2 indented - not bengt -> - gurka(); - X -> - io:format(stdout, "Parsing file ~s, ", - [St0#leex.xfile]), - {ok,Line3,REAs,Actions,St3} = - parse_rules(Xfile, Line2, Macs, St2) + X when true andalso + kalle -> + io:format(stdout, "Parsing file ~s, ", + [St0#leex.xfile]), + {ok,Line3,REAs,Actions,St3} = + parse_rules(Xfile, Line2, Macs, St2); + X % AD added clause + when false andalso % when should be 2 indented + bengt -> + gurka(); + X when % AD added clause + false andalso % line should be 2 indented + not bengt -> + gurka(); + X -> + io:format(stdout, "Parsing file ~s, ", + [St0#leex.xfile]), + {ok,Line3,REAs,Actions,St3} = + parse_rules(Xfile, Line2, Macs, St2) catch - exit:{badarg,R} -> - foo(R), - io:format(stdout, - "ERROR reason ~p~n", - R); - error:R -> - foo(R), - io:format(stdout, - "ERROR reason ~p~n", - R) + exit:{badarg,R} -> + foo(R), + io:format(stdout, + "ERROR reason ~p~n", + R); + error:R -> + foo(R), + io:format(stdout, + "ERROR reason ~p~n", + R) after - foo('after'), - file:close(Xfile), - bar(with_long_arg, - with_second_arg) + foo('after'), + file:close(Xfile), + bar(with_long_arg, + with_second_arg) end; indent_try_catch() -> try foo() - after - foo(), - bar(with_long_arg, - with_second_arg) + after + foo(), + bar(with_long_arg, + with_second_arg) end. indent_catch() -> D = B + - float(43.1), + float(43.1), B = catch oskar(X), - A = catch (baz + - bax), + A = catch (baz + + bax), catch foo(), - C = catch B + - float(43.1), + C = catch B + + float(43.1), case catch foo(X) of - A -> - B + A -> + B end, case - catch foo(X) + catch foo(X) of - A -> - B + A -> + B end, case - foo(X) + foo(X) of - A -> - catch B, - X + A -> + catch B, + X end, try sune of - _ -> foo + _ -> foo catch _:_ -> baf end, try - sune + sune of - _ -> - X = 5, - (catch foo(X)), - X + 10 + _ -> + X = 5, + (catch foo(X)), + X + 10 catch _:_ -> baf end, try - (catch sune) + (catch sune) of - _ -> - catch foo() %% BUGBUG can't handle catch inside try without parentheses + _ -> + catch foo() %% BUGBUG can't handle catch inside try without parentheses catch _:_ -> - baf + baf end, try - (catch exit()) + (catch exit()) catch - _ -> - catch baf() + _ -> + catch baf() end, ok. indent_binary() -> X = lists:foldr(fun(M) -> - <<Ma/binary, " ">> - end, [], A), + <<Ma/binary, " ">> + end, [], A), A = <<X/binary, 0:8>>, B. indent_comprehensions() -> - %% I don't have a good idea how we want to handle this + %% I don't have a good idea how we want to handle this %% but they are here to show how they are indented today. - Result1 = [X || - #record{a=X} <- lists:seq(1, 10), - true = (X rem 2) - ], + Result1 = [X || + #record{a=X} <- lists:seq(1, 10), + true = (X rem 2) + ], Result2 = [X || <<X:32,_:32>> <= <<0:512>>, - true = (X rem 2) - ], + true = (X rem 2) + ], - Binary1 = << <<X:8>> || - #record{a=X} <- lists:seq(1, 10), - true = (X rem 2) - >>, + Binary1 = << <<X:8>> || + #record{a=X} <- lists:seq(1, 10), + true = (X rem 2) + >>, Binary2 = << <<X:8>> || <<X:32,_:32>> <= <<0:512>>, - true = (X rem 2) - >>, + true = (X rem 2) + >>, ok. %% This causes an error in earlier erlang-mode versions. foo() -> [#foo{ - foo = foo}]. + foo = foo}]. %% Record indentation some_function_with_a_very_long_name() -> @@ -704,20 +704,20 @@ some_function_with_a_very_long_name() -> field1=a, field2=b}, case dummy_function_with_a_very_very_long_name(x) of - #'a-long-record-name-like-it-sometimes-is-with-asn.1-records'{ - field1=a, - field2=b} -> - ok; - Var = #'a-long-record-name-like-it-sometimes-is-with-asn.1-records'{ - field1=a, - field2=b} -> - Var#'a-long-record-name-like-it-sometimes-is-with-asn.1-records'{ - field1=a, - field2=b}; - #xyz{ - a=1, - b=2} -> - ok + #'a-long-record-name-like-it-sometimes-is-with-asn.1-records'{ + field1=a, + field2=b} -> + ok; + Var = #'a-long-record-name-like-it-sometimes-is-with-asn.1-records'{ + field1=a, + field2=b} -> + Var#'a-long-record-name-like-it-sometimes-is-with-asn.1-records'{ + field1=a, + field2=b}; + #xyz{ + a=1, + b=2} -> + ok end. another_function_with_a_very_very_long_name() -> @@ -726,45 +726,45 @@ another_function_with_a_very_very_long_name() -> field2=1}. some_function_name_xyz(xyzzy, #some_record{ - field1=Field1, - field2=Field2}) -> + field1=Field1, + field2=Field2}) -> SomeVariable = f(#'Some-long-record-name'{ - field_a = 1, - 'inter-xyz-parameters' = - #'Some-other-very-long-record-name'{ - field2 = Field1, - field2 = Field2}}), + field_a = 1, + 'inter-xyz-parameters' = + #'Some-other-very-long-record-name'{ + field2 = Field1, + field2 = Field2}}), {ok, SomeVariable}. commas_first() -> {abc, [ {some_var, 1} - , {some_other_var, 2} - , {erlang_ftw, 9} - , {erlang_cookie, 'cookie'} - , {cmds, - [ {one, "sudo ls"} - , {one, "sudo ls"} - , {two, "sudo ls"} - , {three, "sudo ls"} - , {four, "sudo ls"} - , {three, "sudo ls"} - ] } - , {ssh_username, "yow"} - , {cluster, - [ {aaaa, [ {"10.198.55.12" , "" } - , {"10.198.55.13" , "" } - ] } - , {bbbb, [ {"10.198.55.151", "" } - , {"10.198.55.123", "" } - , {"10.198.55.34" , "" } - , {"10.198.55.85" , "" } - , {"10.198.55.67" , "" } - ] } - , {cccc, [ {"10.198.55.68" , "" } - , {"10.198.55.69" , "" } - ] } - ] } - ] + , {some_other_var, 2} + , {erlang_ftw, 9} + , {erlang_cookie, 'cookie'} + , {cmds, + [ {one, "sudo ls"} + , {one, "sudo ls"} + , {two, "sudo ls"} + , {three, "sudo ls"} + , {four, "sudo ls"} + , {three, "sudo ls"} + ] } + , {ssh_username, "yow"} + , {cluster, + [ {aaaa, [ {"10.198.55.12" , "" } + , {"10.198.55.13" , "" } + ] } + , {bbbb, [ {"10.198.55.151", "" } + , {"10.198.55.123", "" } + , {"10.198.55.34" , "" } + , {"10.198.55.85" , "" } + , {"10.198.55.67" , "" } + ] } + , {cccc, [ {"10.198.55.68" , "" } + , {"10.198.55.69" , "" } + ] } + ] } + ] }. @@ -776,9 +776,9 @@ commas_first() -> %% body, due to the function name being mistaken for a keyword catcher(N) -> try generate_exception(N) of - Val -> {N, normal, Val} + Val -> {N, normal, Val} catch - throw:X -> {N, caught, thrown, X}; - exit:X -> {N, caught, exited, X}; - error:X -> {N, caught, error, X} + throw:X -> {N, caught, thrown, X}; + exit:X -> {N, caught, exited, X}; + error:X -> {N, caught, error, X} end. diff --git a/lib/tools/emacs/test.erl.orig b/lib/tools/emacs/test.erl.orig index 2552c71baf..c0cf1749b6 100644 --- a/lib/tools/emacs/test.erl.orig +++ b/lib/tools/emacs/test.erl.orig @@ -1,4 +1,4 @@ -%% -*- erlang -*- +%% -*- Mode: erlang; indent-tabs-mode: nil -*- %% %% %CopyrightBegin% %% @@ -27,7 +27,7 @@ %%% Created : 6 Oct 2009 by Dan Gudmundsson <[email protected]> %%%------------------------------------------------------------------- -%% Start off with syntax highlighting you have to verify this by looking here +%% Start off with syntax highlighting you have to verify this by looking here %% and see that the code looks alright -module(test). @@ -44,18 +44,18 @@ foo() -> %% Module attributes should be highlighted -export([t/1]). --record(record1, {a, - b, +-record(record1, {a, + b, c }). -record(record2, { a, b }). - + -record(record3, {a = 8#42423 bor 8#4234, - b = 8#5432 + b = 8#5432 bor 2#1010101 c = 123 + 234, @@ -64,7 +64,7 @@ foo() -> -record(record4, { a = 8#42423 bor 8#4234, - b = 8#5432 + b = 8#5432 bor 2#1010101 c = 123 + 234, @@ -79,31 +79,31 @@ foo() -> -spec t(integer()) -> any(). --type ann() :: Var :: integer(). --type ann2() :: Var :: - 'return' - | 'return_white_spaces' +-type ann() :: Var :: integer(). +-type ann2() :: Var :: + 'return' + | 'return_white_spaces' | 'return_comments' - | 'text' | ann(). --type paren() :: - (ann2()). --type t1() :: atom(). --type t2() :: [t1()]. --type t3(Atom) :: integer(Atom). --type t4() :: t3(foobar). --type t5() :: {t1(), t3(foo)}. --type t6() :: 1 | 2 | 3 | - 'foo' | 'bar'. --type t7() :: []. --type t71() :: [_]. + | 'text' | ann(). +-type paren() :: + (ann2()). +-type t1() :: atom(). +-type t2() :: [t1()]. +-type t3(Atom) :: integer(Atom). +-type t4() :: t3(foobar). +-type t5() :: {t1(), t3(foo)}. +-type t6() :: 1 | 2 | 3 | + 'foo' | 'bar'. +-type t7() :: []. +-type t71() :: [_]. -type t8() :: {any(),none(),pid(),port(), - reference(),float()}. --type t9() :: [1|2|3|foo|bar] | - list(a | b | c) | t71(). --type t10() :: {1|2|3|foo|t9()} | {}. --type t11() :: 1..2. --type t13() :: maybe_improper_list(integer(), t11()). --type t14() :: [erl_scan:foo() | + reference(),float()}. +-type t9() :: [1|2|3|foo|bar] | + list(a | b | c) | t71(). +-type t10() :: {1|2|3|foo|t9()} | {}. +-type t11() :: 1..2. +-type t13() :: maybe_improper_list(integer(), t11()). +-type t14() :: [erl_scan:foo() | %% Should be highlighted term() | bool() | @@ -122,31 +122,31 @@ foo() -> timeout() | no_return() | %% Should not be highlighted - nonempty_() | nonlist() | + nonempty_() | nonlist() | erl_scan:bar(34, 92) | t13() | m:f(integer() | <<_:_*16>>)]. -type t15() :: {binary(),<<>>,<<_:34>>,<<_:_*42>>, <<_:3,_:_*14>>,<<>>} | [<<>>|<<_:34>>|<<_:16>>| <<_:3,_:_*1472>>|<<_:19,_:_*14>>| <<_:34>>| -<<_:34>>|<<_:34>>|<<_:34>>]. --type t16() :: fun(). --type t17() :: fun((...) -> paren()). --type t18() :: fun(() -> t17() | t16()). +<<_:34>>|<<_:34>>|<<_:34>>]. +-type t16() :: fun(). +-type t17() :: fun((...) -> paren()). +-type t18() :: fun(() -> t17() | t16()). -type t19() :: fun((t18()) -> t16()) | fun((nonempty_maybe_improper_list('integer', any())| 1|2|3|a|b|<<_:3,_:_*14>>|integer()) -> nonempty_maybe_improper_list('integer', any())| -1|2|3|a|b|<<_:3,_:_*14>>|integer()). --type t20() :: [t19(), ...]. --type t21() :: tuple(). --type t21(A) :: A. --type t22() :: t21(integer()). --type t23() :: #rec1{}. --type t24() :: #rec2{a :: t23(), b :: [atom()]}. --type t25() :: #rec3{f123 :: [t24() | -1|2|3|4|a|b|c|d| -nonempty_maybe_improper_list(integer, any())]}. +1|2|3|a|b|<<_:3,_:_*14>>|integer()). +-type t20() :: [t19(), ...]. +-type t21() :: tuple(). +-type t21(A) :: A. +-type t22() :: t21(integer()). +-type t23() :: #rec1{}. +-type t24() :: #rec2{a :: t23(), b :: [atom()]}. +-type t25() :: #rec3{f123 :: [t24() | +1|2|3|4|a|b|c|d| +nonempty_maybe_improper_list(integer, any())]}. -type t26() :: #rec4{ a :: integer() , b :: any() }. @@ -155,7 +155,7 @@ nonempty_maybe_improper_list(integer, any())]}. }. -type t99() :: {t2(),t4(),t5(),t6(),t7(),t8(),t10(),t14(), -t15(),t20(),t21(), t22(),t25()}. +t15(),t20(),t21(), t22(),t25()}. -spec t1(FooBar :: t99()) -> t99(); (t2()) -> t2(); (t4()) -> t4() when is_subtype(t4(), t24); @@ -169,21 +169,21 @@ t15(),t20(),t21(), t22(),t25()}. (A :: atom()) -> R2 :: foo:atomen(); (T :: tuple()) -> R3 :: bar:typen(). --spec mod:t2() -> any(). +-spec mod:t2() -> any(). --spec handle_cast(Cast :: {'exchange', node(), [[name(),...]]} +-spec handle_cast(Cast :: {'exchange', node(), [[name(),...]]} | {'del_member', name(), pid()}, #state{}) -> {'noreply', #state{}}. --spec handle_cast(Cast :: - {'exchange', node(), [[name(),...]]} +-spec handle_cast(Cast :: + {'exchange', node(), [[name(),...]]} | {'del_member', name(), pid()}, #state{}) -> {'noreply', #state{}}. -spec all(fun((T) -> boolean()), List :: [T]) -> boolean() when is_subtype(T, term()). % (*) --spec get_closest_pid(term()) -> +-spec get_closest_pid(term()) -> Return :: pid() | {'error', {'no_process', term()} | {'no_such_group', term()}}. @@ -192,23 +192,23 @@ t15(),t20(),t21(), t22(),t25()}. , Y :: integer() ) -> integer(). --opaque attributes_data() :: +-opaque attributes_data() :: [{'column', column()} | {'line', info_line()} | - {'text', string()}] | {line(),column()}. + {'text', string()}] | {line(),column()}. -record(r,{ f1 :: attributes_data(), -f222 = foo:bar(34, #rec3{}, 234234234423, - aassdsfsdfsdf, 2234242323) :: -[t24() | 1|2|3|4|a|b|c|d| +f222 = foo:bar(34, #rec3{}, 234234234423, + aassdsfsdfsdf, 2234242323) :: +[t24() | 1|2|3|4|a|b|c|d| nonempty_maybe_improper_list(integer, any())], -f333 :: [t24() | 1|2|3|4|a|b|c|d| +f333 :: [t24() | 1|2|3|4|a|b|c|d| nonempty_maybe_improper_list(integer, any())], f3 = x:y(), f4 = x:z() :: t99(), f17 :: 'undefined', f18 :: 1 | 2 | 'undefined', f19 = 3 :: integer()|undefined, -f5 = 3 :: undefined|integer()}). +f5 = 3 :: undefined|integer()}). -record(state, { sequence_number = 1 :: integer() @@ -230,12 +230,12 @@ highlighting(X) % Function definitions should be highlighted '#1',atom, $", atom, % atom should be ok - $', atom, - + $', atom, + "string$", atom, "string$", atom, % currently buggy I know... "string\$", atom, % workaround for bug above - - "char $in string", atom, + + "char $in string", atom, 'atom$', atom, 'atom$', atom, 'atom\$', atom, @@ -270,18 +270,18 @@ highlighting(X) % Function definitions should be highlighted erlang:anything(lists), %% Guards is_atom(foo), is_float(2.3), is_integer(32), is_number(4323.3), - is_function(Fun), is_pid(self()), + is_function(Fun), is_pid(self()), not_a_guard:is_list([]), %% Other Types atom, % not (currently) hightlighted - 234234, + 234234, 234.43, - [list, are, not, higlighted], + [list, are, not, higlighted], {nor, is, tuple}, ok. - + %%% %%% Indentation %%% @@ -293,32 +293,32 @@ highlighting(X) % Function definitions should be highlighted % Right -indent_basics(X, Y, Z) +indent_basics(X, Y, Z) when X > 42, Z < 13; Y =:= 4711 -> %% comments % right comments - case lists:filter(fun(_, AlongName, - B, + case lists:filter(fun(_, AlongName, + B, C) -> true - end, + end, [a,v,b]) of [] -> Y = 5 * 43, ok; - [_|_] -> + [_|_] -> Y = 5 * 43, ok end, Y, %% List, tuples and binaries - [a, + [a, b, c ], - [ a, + [ a, b, c ], @@ -326,10 +326,10 @@ Y =:= 4711 -> a, b ], - {a, + {a, b,c }, - { a, + { a, b,c }, @@ -337,7 +337,7 @@ Y =:= 4711 -> a, b }, - + <<1:8, 2:8 >>, @@ -359,21 +359,21 @@ Y =:= 4711 -> c ), - + ( a, b, c ), - call(2#42423 bor + call(2#42423 bor #4234, 2#5432, other_arg), ok; -indent_basics(Xlongname, +indent_basics(Xlongname, #struct{a=Foo, - b=Bar}, + b=Bar}, [X| Y]) -> testing_next_clause, @@ -451,13 +451,13 @@ indent_icr(Z) -> % icr = if case receive %% receive - receive + receive {Z,_,_} -> X = 43 div 4, foo(X); Z -> X = 43 div 4, - foo(X) + foo(X) end, receive {Z,_,_} -> @@ -473,33 +473,33 @@ indent_icr(Z) -> % icr = if case receive foo(X); Z -> X = 43 div 4, - foo(X) + foo(X) after infinity -> foo(X), asd(X), 5*43 end, receive - after 10 -> + after 10 -> foo(X), asd(X), 5*43 end, ok. - + indent_fun() -> %% Changed fun to one indention level -Var = spawn(fun(X) +Var = spawn(fun(X) when X == 2; - X > 10 -> + X > 10 -> hello, - case Hello() of - true when is_atom(X) -> + case Hello() of + true when is_atom(X) -> foo; false -> bar end; - (Foo) when is_atom(Foo), + (Foo) when is_atom(Foo), is_integer(X) -> X = 6* 45, Y = true andalso @@ -522,14 +522,14 @@ Fact(0) -> indent_try_catch() -> try - io:format(stdout, "Parsing file ~s, ", + io:format(stdout, "Parsing file ~s, ", [St0#leex.xfile]), - {ok,Line3,REAs,Actions,St3} = + {ok,Line3,REAs,Actions,St3} = parse_rules(Xfile, Line2, Macs, St2) catch exit:{badarg,R} -> foo(R), - io:format(stdout, + io:format(stdout, "ERROR reason ~p~n", R); error:R % AD added clause @@ -544,7 +544,7 @@ indent_try_catch() -> foo(R); error:R -> foo(R), - io:format(stdout, + io:format(stdout, "ERROR reason ~p~n", R) after @@ -577,12 +577,12 @@ indent_try_catch() -> catch exit:{badarg,R} -> foo(R), - io:format(stdout, + io:format(stdout, "ERROR reason ~p~n", R); error:R -> foo(R), - io:format(stdout, + io:format(stdout, "ERROR reason ~p~n", R) after @@ -593,7 +593,7 @@ indent_try_catch() -> end; indent_try_catch() -> try foo() - after + after foo(), bar(with_long_arg, with_second_arg) @@ -602,16 +602,16 @@ indent_try_catch() -> indent_catch() -> D = B + float(43.1), - + B = catch oskar(X), - - A = catch (baz + + + A = catch (baz + bax), catch foo(), - C = catch B + + C = catch B + float(43.1), - + case catch foo(X) of A -> B @@ -673,9 +673,9 @@ indent_binary() -> indent_comprehensions() -> -%% I don't have a good idea how we want to handle this +%% I don't have a good idea how we want to handle this %% but they are here to show how they are indented today. -Result1 = [X || +Result1 = [X || #record{a=X} <- lists:seq(1, 10), true = (X rem 2) ], @@ -683,7 +683,7 @@ Result2 = [X || <<X:32,_:32>> <= <<0:512>>, true = (X rem 2) ], -Binary1 = << <<X:8>> || +Binary1 = << <<X:8>> || #record{a=X} <- lists:seq(1, 10), true = (X rem 2) >>, diff --git a/otp_versions.table b/otp_versions.table index 2832b6fe21..1378f6afea 100644 --- a/otp_versions.table +++ b/otp_versions.table @@ -1,3 +1,6 @@ +OTP-19.1.5 : ssh-4.3.6 # asn1-4.0.4 common_test-1.12.3 compiler-7.0.2 cosEvent-2.2.1 cosEventDomain-1.2.1 cosFileTransfer-1.2.1 cosNotification-1.2.2 cosProperty-1.2.1 cosTime-1.2.2 cosTransactions-1.3.2 crypto-3.7.1 debugger-4.2.1 dialyzer-3.0.2 diameter-1.12.1 edoc-0.8 eldap-1.2.2 erl_docgen-0.6 erl_interface-3.9.1 erts-8.1 et-1.6 eunit-2.3.1 gs-1.6.2 hipe-3.15.2 ic-4.4.2 inets-6.3.3 jinterface-1.7.1 kernel-5.1 megaco-3.18.1 mnesia-4.14.1 observer-2.2.2 odbc-2.11.3 orber-3.8.2 os_mon-2.4.1 otp_mibs-1.1.1 parsetools-2.1.3 percept-0.9 public_key-1.2 reltool-0.7.2 runtime_tools-1.10.1 sasl-3.0.1 snmp-5.2.4 ssl-8.0.3 stdlib-3.1 syntax_tools-2.1 tools-2.8.6 typer-0.9.11 wx-1.7.1 xmerl-1.3.12 : +OTP-19.1.4 : ssh-4.3.5 # asn1-4.0.4 common_test-1.12.3 compiler-7.0.2 cosEvent-2.2.1 cosEventDomain-1.2.1 cosFileTransfer-1.2.1 cosNotification-1.2.2 cosProperty-1.2.1 cosTime-1.2.2 cosTransactions-1.3.2 crypto-3.7.1 debugger-4.2.1 dialyzer-3.0.2 diameter-1.12.1 edoc-0.8 eldap-1.2.2 erl_docgen-0.6 erl_interface-3.9.1 erts-8.1 et-1.6 eunit-2.3.1 gs-1.6.2 hipe-3.15.2 ic-4.4.2 inets-6.3.3 jinterface-1.7.1 kernel-5.1 megaco-3.18.1 mnesia-4.14.1 observer-2.2.2 odbc-2.11.3 orber-3.8.2 os_mon-2.4.1 otp_mibs-1.1.1 parsetools-2.1.3 percept-0.9 public_key-1.2 reltool-0.7.2 runtime_tools-1.10.1 sasl-3.0.1 snmp-5.2.4 ssl-8.0.3 stdlib-3.1 syntax_tools-2.1 tools-2.8.6 typer-0.9.11 wx-1.7.1 xmerl-1.3.12 : +OTP-19.1.3 : ssh-4.3.4 # asn1-4.0.4 common_test-1.12.3 compiler-7.0.2 cosEvent-2.2.1 cosEventDomain-1.2.1 cosFileTransfer-1.2.1 cosNotification-1.2.2 cosProperty-1.2.1 cosTime-1.2.2 cosTransactions-1.3.2 crypto-3.7.1 debugger-4.2.1 dialyzer-3.0.2 diameter-1.12.1 edoc-0.8 eldap-1.2.2 erl_docgen-0.6 erl_interface-3.9.1 erts-8.1 et-1.6 eunit-2.3.1 gs-1.6.2 hipe-3.15.2 ic-4.4.2 inets-6.3.3 jinterface-1.7.1 kernel-5.1 megaco-3.18.1 mnesia-4.14.1 observer-2.2.2 odbc-2.11.3 orber-3.8.2 os_mon-2.4.1 otp_mibs-1.1.1 parsetools-2.1.3 percept-0.9 public_key-1.2 reltool-0.7.2 runtime_tools-1.10.1 sasl-3.0.1 snmp-5.2.4 ssl-8.0.3 stdlib-3.1 syntax_tools-2.1 tools-2.8.6 typer-0.9.11 wx-1.7.1 xmerl-1.3.12 : OTP-19.1.2 : ssh-4.3.3 # asn1-4.0.4 common_test-1.12.3 compiler-7.0.2 cosEvent-2.2.1 cosEventDomain-1.2.1 cosFileTransfer-1.2.1 cosNotification-1.2.2 cosProperty-1.2.1 cosTime-1.2.2 cosTransactions-1.3.2 crypto-3.7.1 debugger-4.2.1 dialyzer-3.0.2 diameter-1.12.1 edoc-0.8 eldap-1.2.2 erl_docgen-0.6 erl_interface-3.9.1 erts-8.1 et-1.6 eunit-2.3.1 gs-1.6.2 hipe-3.15.2 ic-4.4.2 inets-6.3.3 jinterface-1.7.1 kernel-5.1 megaco-3.18.1 mnesia-4.14.1 observer-2.2.2 odbc-2.11.3 orber-3.8.2 os_mon-2.4.1 otp_mibs-1.1.1 parsetools-2.1.3 percept-0.9 public_key-1.2 reltool-0.7.2 runtime_tools-1.10.1 sasl-3.0.1 snmp-5.2.4 ssl-8.0.3 stdlib-3.1 syntax_tools-2.1 tools-2.8.6 typer-0.9.11 wx-1.7.1 xmerl-1.3.12 : OTP-19.1.1 : ssl-8.0.3 # asn1-4.0.4 common_test-1.12.3 compiler-7.0.2 cosEvent-2.2.1 cosEventDomain-1.2.1 cosFileTransfer-1.2.1 cosNotification-1.2.2 cosProperty-1.2.1 cosTime-1.2.2 cosTransactions-1.3.2 crypto-3.7.1 debugger-4.2.1 dialyzer-3.0.2 diameter-1.12.1 edoc-0.8 eldap-1.2.2 erl_docgen-0.6 erl_interface-3.9.1 erts-8.1 et-1.6 eunit-2.3.1 gs-1.6.2 hipe-3.15.2 ic-4.4.2 inets-6.3.3 jinterface-1.7.1 kernel-5.1 megaco-3.18.1 mnesia-4.14.1 observer-2.2.2 odbc-2.11.3 orber-3.8.2 os_mon-2.4.1 otp_mibs-1.1.1 parsetools-2.1.3 percept-0.9 public_key-1.2 reltool-0.7.2 runtime_tools-1.10.1 sasl-3.0.1 snmp-5.2.4 ssh-4.3.2 stdlib-3.1 syntax_tools-2.1 tools-2.8.6 typer-0.9.11 wx-1.7.1 xmerl-1.3.12 : OTP-19.1 : asn1-4.0.4 common_test-1.12.3 compiler-7.0.2 crypto-3.7.1 debugger-4.2.1 dialyzer-3.0.2 diameter-1.12.1 edoc-0.8 erl_docgen-0.6 erl_interface-3.9.1 erts-8.1 eunit-2.3.1 gs-1.6.2 hipe-3.15.2 ic-4.4.2 inets-6.3.3 jinterface-1.7.1 kernel-5.1 mnesia-4.14.1 observer-2.2.2 odbc-2.11.3 parsetools-2.1.3 reltool-0.7.2 runtime_tools-1.10.1 sasl-3.0.1 snmp-5.2.4 ssh-4.3.2 ssl-8.0.2 stdlib-3.1 syntax_tools-2.1 tools-2.8.6 wx-1.7.1 xmerl-1.3.12 # cosEvent-2.2.1 cosEventDomain-1.2.1 cosFileTransfer-1.2.1 cosNotification-1.2.2 cosProperty-1.2.1 cosTime-1.2.2 cosTransactions-1.3.2 eldap-1.2.2 et-1.6 megaco-3.18.1 orber-3.8.2 os_mon-2.4.1 otp_mibs-1.1.1 percept-0.9 public_key-1.2 typer-0.9.11 : diff --git a/system/doc/design_principles/code_lock.dia b/system/doc/design_principles/code_lock.dia Binary files differindex 8e6ff8a898..eaa2aca5b0 100644 --- a/system/doc/design_principles/code_lock.dia +++ b/system/doc/design_principles/code_lock.dia diff --git a/system/doc/design_principles/code_lock.png b/system/doc/design_principles/code_lock.png Binary files differindex 745fd91920..40bd35fc74 100644 --- a/system/doc/design_principles/code_lock.png +++ b/system/doc/design_principles/code_lock.png diff --git a/system/doc/design_principles/code_lock_2.dia b/system/doc/design_principles/code_lock_2.dia Binary files differindex 142909a2f5..3b9ba554d8 100644 --- a/system/doc/design_principles/code_lock_2.dia +++ b/system/doc/design_principles/code_lock_2.dia diff --git a/system/doc/design_principles/code_lock_2.png b/system/doc/design_principles/code_lock_2.png Binary files differindex ecf7b0d799..3aca9dd5aa 100644 --- a/system/doc/design_principles/code_lock_2.png +++ b/system/doc/design_principles/code_lock_2.png diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml index 57e47431b8..bece95e6b8 100644 --- a/system/doc/design_principles/statem.xml +++ b/system/doc/design_principles/statem.xml @@ -29,7 +29,7 @@ <rev></rev> <file>statem.xml</file> </header> - <marker id="gen_statem behaviour"></marker> + <marker id="gen_statem Behaviour" /> <p> This section is to be read with the <seealso marker="stdlib:gen_statem"><c>gen_statem(3)</c></seealso> @@ -50,6 +50,7 @@ <!-- =================================================================== --> <section> + <marker id="Event-Driven State Machines" /> <title>Event-Driven State Machines</title> <p> Established Automata Theory does not deal much with @@ -94,7 +95,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <!-- =================================================================== --> <section> - <marker id="callback_modes" /> + <marker id="Callback Modes" /> <title>Callback Modes</title> <p> The <c>gen_statem</c> behavior supports two callback modes: @@ -109,8 +110,13 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </p> <pre> StateName(EventType, EventContent, Data) -> - .. code for actions here ... - {next_state, NewStateName, NewData}.</pre> + ... code for actions here ... + {next_state, NewStateName, NewData}. + </pre> + <p> + This form is used in most examples here for example in section + <seealso marker="#Example">Example</seealso>. + </p> </item> <item> <p> @@ -120,8 +126,14 @@ StateName(EventType, EventContent, Data) -> </p> <pre> handle_event(EventType, EventContent, State, Data) -> - .. code for actions here ... - {next_state, NewState, NewData}</pre> + ... code for actions here ... + {next_state, NewState, NewData} + </pre> + <p> + Se section + <seealso marker="#One Event Handler">One Event Handler</seealso> + for an example. + </p> </item> </list> <p> @@ -134,10 +146,11 @@ handle_event(EventType, EventContent, State, Data) -> </p> <section> + <marker id="Choosing the Callback Mode" /> <title>Choosing the Callback Mode</title> <p> The two - <seealso marker="#callback_modes">callback modes</seealso> + <seealso marker="#Callback Modes">callback modes</seealso> give different possibilities and restrictions, but one goal remains: you want to handle all possible combinations of @@ -195,10 +208,195 @@ handle_event(EventType, EventContent, State, Data) -> <!-- =================================================================== --> <section> + <marker id="State Enter Calls" /> + <title>State Enter Calls</title> + <p> + The <c>gen_statem</c> behavior can regardless of callback mode + automatically + <seealso marker="stdlib:gen_statem#type-state_enter"> + call the state callback + </seealso> + with special arguments whenever the state changes + so you can write state entry actions + near the rest of the state transition rules. + It typically looks like this: + </p> + <pre> +StateName(enter, _OldState, Data) -> + ... code for state entry actions here ... + {keep_state, NewData}; +StateName(EventType, EventContent, Data) -> + ... code for actions here ... + {next_state, NewStateName, NewData}.</pre> + <p> + Depending on how your state machine is specified, + this can be a very useful feature, + but it forces you to handle the state enter calls in all states. + See also the + <seealso marker="#State Entry Actions"> + State Entry Actions + </seealso> + chapter. + </p> + </section> + +<!-- =================================================================== --> + + <section> + <marker id="Actions" /> + <title>Actions</title> + <p> + In the first section + <seealso marker="#Event-Driven State Machines"> + Event-Driven State Machines + </seealso> + actions were mentioned as a part of + the general state machine model. These general actions + are implemented with the code that callback module + <c>gen_statem</c> executes in an event-handling + callback function before returning + to the <c>gen_statem</c> engine. + </p> + <p> + There are more specific state-transition actions + that a callback function can order the <c>gen_statem</c> + engine to do after the callback function return. + These are ordered by returning a list of + <seealso marker="stdlib:gen_statem#type-action">actions</seealso> + in the + <seealso marker="stdlib:gen_statem#type-state_callback_result">return tuple</seealso> + from the + <seealso marker="stdlib:gen_statem#Module:StateName/3">callback function</seealso>. + These state transition actions affect the <c>gen_statem</c> + engine itself and can do the following: + </p> + <list type="bulleted"> + <item> + <seealso marker="stdlib:gen_statem#type-postpone"> + Postpone + </seealso> + the current event, see section + <seealso marker="#Postponing Events">Postponing Events</seealso> + </item> + <item> + <seealso marker="stdlib:gen_statem#type-hibernate"> + Hibernate + </seealso> + the <c>gen_statem</c>, treated in + <seealso marker="#Hibernation">Hibernation</seealso> + </item> + <item> + Start a + <seealso marker="stdlib:gen_statem#type-state_timeout"> + state time-out</seealso>, + read more in section + <seealso marker="#State Time-Outs">State Time-Outs</seealso> + </item> + <item> + Start an + <seealso marker="stdlib:gen_statem#type-event_timeout">event time-out</seealso>, + see more in section + <seealso marker="#Event Time-Outs">Event Time-Outs</seealso> + </item> + <item> + <seealso marker="stdlib:gen_statem#type-reply_action"> + Reply + </seealso> + to a caller, mentioned at the end of section + <seealso marker="#All State Events">All State Events</seealso> + </item> + <item> + Generate the + <seealso marker="stdlib:gen_statem#type-action"> + next event + </seealso> + to handle, see section + <seealso marker="#Self-Generated Events">Self-Generated Events</seealso> + </item> + </list> + <p> + For details, see the + <seealso marker="stdlib:gen_statem#type-action"> + <c>gen_statem(3)</c> + </seealso> + manual page. + You can, for example, reply to many callers + and generate multiple next events to handle. + </p> + </section> + +<!-- =================================================================== --> + + <section> + <marker id="Event Types" /> + <title>Event Types</title> + <p> + Events are categorized in different + <seealso marker="stdlib:gen_statem#type-event_type">event types</seealso>. + Events of all types are handled in the same callback function, + for a given state, and the function gets + <c>EventType</c> and <c>EventContent</c> as arguments. + </p> + <p> + The following is a complete list of event types and where + they come from: + </p> + <taglist> + <tag><c>cast</c></tag> + <item> + Generated by + <seealso marker="stdlib:gen_statem#cast/2"><c>gen_statem:cast</c></seealso>. + </item> + <tag><c>{call,From}</c></tag> + <item> + Generated by + <seealso marker="stdlib:gen_statem#call/2"><c>gen_statem:call</c></seealso>, + where <c>From</c> is the reply address to use + when replying either through the state transition action + <c>{reply,From,Msg}</c> or by calling + <seealso marker="stdlib:gen_statem#reply/1"><c>gen_statem:reply</c></seealso>. + </item> + <tag><c>info</c></tag> + <item> + Generated by any regular process message sent to + the <c>gen_statem</c> process. + </item> + <tag><c>state_timeout</c></tag> + <item> + Generated by state transition action + <seealso marker="stdlib:gen_statem#type-state_timeout"> + <c>{state_timeout,Time,EventContent}</c> + </seealso> + state timer timing out. + </item> + <tag><c>timeout</c></tag> + <item> + Generated by state transition action + <seealso marker="stdlib:gen_statem#type-event_timeout"> + <c>{timeout,Time,EventContent}</c> + </seealso> + (or its short form <c>Time</c>) + event timer timing out. + </item> + <tag><c>internal</c></tag> + <item> + Generated by state transition + <seealso marker="stdlib:gen_statem#type-action">action</seealso> + <c>{next_event,internal,EventContent}</c>. + All event types above can also be generated using + <c>{next_event,EventType,EventContent}</c>. + </item> + </taglist> + </section> + +<!-- =================================================================== --> + + <section> + <marker id="Example" /> <title>Example</title> <p> This example starts off as equivalent to the example in section - <seealso marker="fsm"><c>gen_fsm</c> Behavior</seealso>. + <seealso marker="fsm"><c>gen_fsm</c> Behavior</seealso>. In later sections, additions and tweaks are made using features in <c>gen_statem</c> that <c>gen_fsm</c> does not have. The end of this chapter provides the example again @@ -221,7 +419,6 @@ handle_event(EventType, EventContent, State, Data) -> This code lock state machine can be implemented using <c>gen_statem</c> with the following callback module: </p> - <marker id="ex"></marker> <code type="erl"><![CDATA[ -module(code_lock). -behaviour(gen_statem). @@ -241,7 +438,7 @@ button(Digit) -> init(Code) -> do_lock(), Data = #{code => Code, remaining => Code}, - {ok,locked,Data}. + {ok, locked, Data}. callback_mode() -> state_functions. @@ -252,19 +449,19 @@ locked( case Remaining of [Digit] -> do_unlock(), - {next_state,open,Data#{remaining := Code},10000}; + {next_state, open, Data#{remaining := Code}, + [{state_timeout,10000,lock}]; [Digit|Rest] -> % Incomplete - {next_state,locked,Data#{remaining := Rest}}; + {next_state, locked, Data#{remaining := Rest}}; _Wrong -> - {next_state,locked,Data#{remaining := Code}} + {next_state, locked, Data#{remaining := Code}} end. -open(timeout, _, Data) -> +open(state_timeout, lock, Data) -> do_lock(), - {next_state,locked,Data}; + {next_state, locked, Data}; open(cast, {button,_}, Data) -> - do_lock(), - {next_state,locked,Data}. + {next_state, open, Data}. do_lock() -> io:format("Lock~n", []). @@ -275,7 +472,7 @@ terminate(_Reason, State, _Data) -> State =/= locked andalso do_lock(), ok. code_change(_Vsn, State, Data, _Extra) -> - {ok,State,Data}. + {ok, State, Data}. ]]></code> <p>The code is explained in the next sections.</p> </section> @@ -283,6 +480,7 @@ code_change(_Vsn, State, Data, _Extra) -> <!-- =================================================================== --> <section> + <marker id="Starting gen_statem" /> <title>Starting gen_statem</title> <p> In the example in the previous section, <c>gen_statem</c> is @@ -345,7 +543,7 @@ start_link(Code) -> <p> If name registration succeeds, the new <c>gen_statem</c> process calls callback function <c>code_lock:init(Code)</c>. - This function is expected to return <c>{ok,State,Data}</c>, + This function is expected to return <c>{ok, State, Data}</c>, where <c>State</c> is the initial state of the <c>gen_statem</c>, in this case <c>locked</c>; assuming that the door is locked to begin with. <c>Data</c> is the internal server data of the <c>gen_statem</c>. @@ -386,7 +584,7 @@ callback_mode() -> Function <seealso marker="stdlib:gen_statem#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> selects the - <seealso marker="#callback_modes"><c>CallbackMode</c></seealso> + <seealso marker="#Callback Modes"><c>CallbackMode</c></seealso> for the callback module, in this case <seealso marker="stdlib:gen_statem#type-callback_mode"><c>state_functions</c></seealso>. That is, each state has got its own handler function. @@ -397,6 +595,7 @@ callback_mode() -> <!-- =================================================================== --> <section> + <marker id="Handling Events" /> <title>Handling Events</title> <p>The function notifying the code lock about a button event is implemented using @@ -416,11 +615,13 @@ button(Digit) -> The event is made into a message and sent to the <c>gen_statem</c>. When the event is received, the <c>gen_statem</c> calls <c>StateName(cast, Event, Data)</c>, which is expected to - return a tuple <c>{next_state,NewStateName,NewData}</c>. + return a tuple <c>{next_state, NewStateName, NewData}</c>, + or <c>{next_state, NewStateName, NewData, Actions}</c>. <c>StateName</c> is the name of the current state and <c>NewStateName</c> is the name of the next state to go to. <c>NewData</c> is a new value for the server data of - the <c>gen_statem</c>. + the <c>gen_statem</c>, and <c>Actions</c> is a list of + actions on the <c>gen_statem</c> engine. </p> <code type="erl"><![CDATA[ locked( @@ -429,19 +630,19 @@ locked( case Remaining of [Digit] -> % Complete do_unlock(), - {next_state,open,Data#{remaining := Code},10000}; + {next_state, open, Data#{remaining := Code}, + [{state_timeout,10000,lock}]}; [Digit|Rest] -> % Incomplete - {next_state,locked,Data#{remaining := Rest}}; + {next_state, locked, Data#{remaining := Rest}}; [_|_] -> % Wrong - {next_state,locked,Data#{remaining := Code}} + {next_state, locked, Data#{remaining := Code}} end. -open(timeout, _, Data) -> +open(state_timeout, lock, Data) -> do_lock(), - {next_state,locked,Data}; + {next_state, locked, Data}; open(cast, {button,_}, Data) -> - do_lock(), - {next_state,locked,Data}. + {next_state, open, Data}. ]]></code> <p> If the door is locked and a button is pressed, the pressed @@ -455,38 +656,55 @@ open(cast, {button,_}, Data) -> restarts from the start of the code sequence. </p> <p> - In state <c>open</c>, any button locks the door, as - any event cancels the event timer, so no - time-out event occurs after a button event. + If the whole code is correct, the server changes states + to <c>open</c>. + </p> + <p> + In state <c>open</c>, a button event is ignored + by staying in the same state. This can also be done + by returning <c>{keep_state, Data}</c> or in this case + since <c>Data</c> unchanged even by returning + <c>keep_state_and_data</c>. </p> </section> <section> - <title>Event Time-Outs</title> + <marker id="State Time-Outs" /> + <title>State Time-Outs</title> <p> When a correct code has been given, the door is unlocked and the following tuple is returned from <c>locked/2</c>: </p> <code type="erl"><![CDATA[ -{next_state,open,Data#{remaining := Code},10000}; +{next_state, open, Data#{remaining := Code}, + [{state_timeout,10000,lock}]}; ]]></code> <p> 10,000 is a time-out value in milliseconds. After this time (10 seconds), a time-out occurs. - Then, <c>StateName(timeout, 10000, Data)</c> is called. + Then, <c>StateName(state_timeout, lock, Data)</c> is called. The time-out occurs when the door has been in state <c>open</c> for 10 seconds. After that the door is locked again: </p> <code type="erl"><![CDATA[ -open(timeout, _, Data) -> +open(state_timeout, lock, Data) -> do_lock(), - {next_state,locked,Data}; + {next_state, locked, Data}; ]]></code> + <p> + The timer for a state time-out is automatically cancelled + when the state machine changes states. You can restart + a state time-out by setting it to a new time, which cancels + the running timer and starts a new. This implies that + you can cancel a state time-out by restarting it with + time <c>infinity</c>. + </p> </section> <!-- =================================================================== --> <section> + <marker id="All State Events" /> <title>All State Events</title> <p> Sometimes events can arrive in any state of the <c>gen_statem</c>. @@ -519,21 +737,24 @@ open(EventType, EventContent, Data) -> handle_event(EventType, EventContent, Data). handle_event({call,From}, code_length, #{code := Code} = Data) -> - {keep_state,Data,[{reply,From,length(Code)}]}. + {keep_state, Data, [{reply,From,length(Code)}]}. ]]></code> <p> This example uses <seealso marker="stdlib:gen_statem#call/2"><c>gen_statem:call/2</c></seealso>, which waits for a reply from the server. The reply is sent with a <c>{reply,From,Reply}</c> tuple - in an action list in the <c>{keep_state,...}</c> tuple - that retains the current state. + in an action list in the <c>{keep_state, ...}</c> tuple + that retains the current state. This return form is convenient + when you want to stay in the current state but do not know or + care about what it is. </p> </section> <!-- =================================================================== --> <section> + <marker id="One Event Handler" /> <title>One Event Handler</title> <p> If mode <c>handle_event_function</c> is used, @@ -557,19 +778,19 @@ handle_event(cast, {button,Digit}, State, #{code := Code} = Data) -> case maps:get(remaining, Data) of [Digit] -> % Complete do_unlock(), - {next_state,open,Data#{remaining := Code},10000}; + {next_state, open, Data#{remaining := Code}, + [{state_timeout,10000,lock}}; [Digit|Rest] -> % Incomplete - {keep_state,Data#{remaining := Rest}}; + {keep_state, Data#{remaining := Rest}}; [_|_] -> % Wrong - {keep_state,Data#{remaining := Code}} + {keep_state, Data#{remaining := Code}} end; open -> - do_lock(), - {next_state,locked,Data} + keep_state_and_data end; -handle_event(timeout, _, open, Data) -> +handle_event(state_timeout, lock, open, Data) -> do_lock(), - {next_state,locked,Data}. + {next_state, locked, Data}. ... ]]></code> @@ -578,9 +799,11 @@ handle_event(timeout, _, open, Data) -> <!-- =================================================================== --> <section> + <marker id="Stopping" /> <title>Stopping</title> <section> + <marker id="In a Supervision Tree" /> <title>In a Supervision Tree</title> <p> If the <c>gen_statem</c> is part of a supervision tree, @@ -620,6 +843,7 @@ terminate(_Reason, State, _Data) -> </section> <section> + <marker id="Standalone gen_statem" /> <title>Standalone gen_statem</title> <p> If the <c>gen_statem</c> is not part of a supervision tree, @@ -646,127 +870,77 @@ stop() -> <!-- =================================================================== --> <section> - <title>Actions</title> + <marker id="Event Time-Outs" /> + <title>Event Time-Outs</title> <p> - In the first sections actions were mentioned as a part of - the general state machine model. These general actions - are implemented with the code that callback module - <c>gen_statem</c> executes in an event-handling - callback function before returning - to the <c>gen_statem</c> engine. + A timeout feature inherited from <c>gen_statem</c>'s predecessor + <seealso marker="stdlib:gen_fsm"><c>gen_fsm</c></seealso>, + is an event time-out, that is, + if an event arrives the timer is cancelled. + You get either an event or a time-out, but not both. </p> <p> - There are more specific state-transition actions - that a callback function can order the <c>gen_statem</c> - engine to do after the callback function return. - These are ordered by returning a list of - <seealso marker="stdlib:gen_statem#type-action">actions</seealso> - in the - <seealso marker="stdlib:gen_statem#type-state_function_result">return tuple</seealso> - from the - <seealso marker="stdlib:gen_statem#Module:StateName/3">callback function</seealso>. - These state transition actions affect the <c>gen_statem</c> - engine itself and can do the following: + It is ordered by the state transition action + <c>{timeout,Time,EventContent}</c>, or just <c>Time</c>, + or even just <c>Time</c> instead of an action list + (the latter is a form inherited from <c>gen_fsm</c>. </p> - <list type="bulleted"> - <item>Postpone the current event</item> - <item>Hibernate the <c>gen_statem</c></item> - <item>Start an event time-out</item> - <item>Reply to a caller</item> - <item>Generate the next event to handle</item> - </list> <p> - In the example earlier was mentioned the event time-out - and replying to a caller. - An example of event postponing is included later in this chapter. - For details, see the - <seealso marker="stdlib:gen_statem#type-action"><c>gen_statem(3)</c></seealso> - manual page. - You can, for example, reply to many callers - and generate multiple next events to handle. + This type of time-out is useful to for example act on inactivity. + Let us start restart the code sequence + if no button is pressed for say 30 seconds: </p> - </section> - -<!-- =================================================================== --> + <code type="erl"><![CDATA[ +... - <section> - <title>Event Types</title> +locked( + timeout, _, + #{code := Code, remaining := Remaining} = Data) -> + {next_state, locked, Data#{remaining := Code}}; +locked( + cast, {button,Digit}, + #{code := Code, remaining := Remaining} = Data) -> +... + [Digit|Rest] -> % Incomplete + {next_state, locked, Data#{remaining := Rest}, 30000}; +... + ]]></code> <p> - The previous sections mentioned a few - <seealso marker="stdlib:gen_statem#type-event_type">event types</seealso>. - Events of all types are handled in the same callback function, - for a given state, and the function gets - <c>EventType</c> and <c>EventContent</c> as arguments. + Whenever we receive a button event we start an event timeout + of 30 seconds, and if we get an event type <c>timeout</c> + we reset the remaining code sequence. </p> <p> - The following is a complete list of event types and where - they come from: + An event timeout is cancelled by any other event so you either + get some other event or the timeout event. It is therefore + not possible nor needed to cancel or restart an event timeout. + Whatever event you act on has already cancelled + the event timeout... </p> - <taglist> - <tag><c>cast</c></tag> - <item> - Generated by - <seealso marker="stdlib:gen_statem#cast/2"><c>gen_statem:cast</c></seealso>. - </item> - <tag><c>{call,From}</c></tag> - <item> - Generated by - <seealso marker="stdlib:gen_statem#call/2"><c>gen_statem:call</c></seealso>, - where <c>From</c> is the reply address to use - when replying either through the state transition action - <c>{reply,From,Msg}</c> or by calling - <seealso marker="stdlib:gen_statem#reply/1"><c>gen_statem:reply</c></seealso>. - </item> - <tag><c>info</c></tag> - <item> - Generated by any regular process message sent to - the <c>gen_statem</c> process. - </item> - <tag><c>timeout</c></tag> - <item> - Generated by state transition action - <c>{timeout,Time,EventContent}</c> (or its short form <c>Time</c>) - timer timing out. - </item> - <tag><c>internal</c></tag> - <item> - Generated by state transition action - <c>{next_event,internal,EventContent}</c>. - All event types above can also be generated using - <c>{next_event,EventType,EventContent}</c>. - </item> - </taglist> </section> <!-- =================================================================== --> <section> - <title>State Time-Outs</title> + <marker id="Erlang Timers" /> + <title>Erlang Timers</title> <p> - The time-out event generated by state transition action - <c>{timeout,Time,EventContent}</c> is an event time-out, - that is, if an event arrives the timer is cancelled. - You get either an event or a time-out, but not both. + The previous example of state time-outs only work if + the state machine stays in the same state during the + time-out time. And event time-outs only work if no + disturbing unrelated events occur. </p> <p> - Often you want a timer not to be cancelled by any event - or you want to start a timer in one state and respond - to the time-out in another. This can be accomplished - with a regular Erlang timer: - <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer</c></seealso>. + You may want to start a timer in one state and respond + to the time-out in another, maybe cancel the time-out + without changing states, or perhaps run multiple + time-outs in parallel. All this can be accomplished + with Erlang Timers: + <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer3,4</c></seealso>. </p> <p> - For the example so far in this chapter: using the - <c>gen_statem</c> event timer has the consequence that - if a button event is generated while in the <c>open</c> state, - the time-out is cancelled and the button event is delivered. - So, we choose to lock the door if this occurred. - </p> - <p> - Suppose that we do not want a button to lock the door, - instead we want to ignore button events in the <c>open</c> state. - Then we start a timer when entering the <c>open</c> state - and wait for it to expire while ignoring button events: + Here is how to accomplish the state time-out + in the previous example by insted using an Erlang Timer: </p> <code type="erl"><![CDATA[ ... @@ -777,25 +951,37 @@ locked( [Digit] -> do_unlock(), Tref = erlang:start_timer(10000, self(), lock), - {next_state,open,Data#{remaining := Code, timer := Tref}}; + {next_state, open, Data#{remaining := Code, timer => Tref}}; ... open(info, {timeout,Tref,lock}, #{timer := Tref} = Data) -> do_lock(), - {next_state,locked,Data}; + {next_state,locked,maps:remove(timer, Data)}; open(cast, {button,_}, Data) -> {keep_state,Data}; ... ]]></code> <p> + Removing the <c>timer</c> key from the map when we + change to state <c>locked</c> is not strictly + necessary since we can only get into state <c>open</c> + with an updated <c>timer</c> map value. But it can be nice + to not have outdated values in the state <c>Data</c>! + </p> + <p> If you need to cancel a timer because of some other event, you can use <seealso marker="erts:erlang#cancel_timer/2"><c>erlang:cancel_timer(Tref)</c></seealso>. - Notice that a time-out message cannot arrive after this, - unless you have postponed it (see the next section) before, + Note that a time-out message cannot arrive after this, + unless you have postponed it before (see the next section), so ensure that you do not accidentally postpone such messages. + Also note that a time-out message may have arrived + just before you cancelling it, so you may have to read out + such a message from the process mailbox depending on + the return value from + <seealso marker="erts:erlang#cancel_timer/2"><c>erlang:cancel_timer(Tref)</c></seealso>. </p> <p> - Another way to cancel a timer is not to cancel it, + Another way to handle a late time-out can be to not cancel it, but to ignore it if it arrives in a state where it is known to be late. </p> @@ -804,6 +990,7 @@ open(cast, {button,_}, Data) -> <!-- =================================================================== --> <section> + <marker id="Postponing Events" /> <title>Postponing Events</title> <p> If you want to ignore a particular event in the current state @@ -842,6 +1029,7 @@ open(cast, {button,_}, Data) -> </p> <section> + <marker id="Fuzzy State Diagrams" /> <title>Fuzzy State Diagrams</title> <p> It is not uncommon that a state diagram does not specify @@ -858,6 +1046,7 @@ open(cast, {button,_}, Data) -> </section> <section> + <marker id="Selective Receive" /> <title>Selective Receive</title> <p> Erlang's selective receive statement is often used to @@ -937,6 +1126,59 @@ do_unlock() -> <!-- =================================================================== --> <section> + <marker id="State Entry Actions" /> + <title>State Entry Actions</title> + <p> + Say you have a state machine specification + that uses state entry actions. + Allthough you can code this using self-generated events + (described in the next section), especially if just + one or a few states has got state entry actions, + this is a perfect use case for the built in + <seealso marker="#State Enter Calls">state enter calls</seealso>. + </p> + <p> + You return a list containing <c>state_enter</c> from your + <seealso marker="stdlib:gen_statem#Module:callback_mode/0"><c>callback_mode/0</c></seealso> + function and the <c>gen_statem</c> engine will call your + state callback once with the arguments + <c>(enter, OldState, ...)</c> whenever the state changes. + Then you just need to handle these event-like calls in all states. + </p> + <code type="erl"><![CDATA[ +... +init(Code) -> + process_flag(trap_exit, true), + Data = #{code => Code}, + {ok, locked, Data}. + +callback_mode() -> + [state_functions,state_enter]. + +locked(enter, _OldState, Data) -> + do_lock(), + {keep_state,Data#{remaining => Code}}; +locked( + cast, {button,Digit}, + #{code := Code, remaining := Remaining} = Data) -> + case Remaining of + [Digit] -> + {next_state, open, Data}; +... + +open(enter, _OldState, _Data) -> + do_unlock(), + {keep_state_and_data, [{state_timeout,10000,lock}]}; +open(state_timeout, lock, Data) -> + {next_state, locked, Data}; +... + ]]></code> + </section> + +<!-- =================================================================== --> + + <section> + <marker id="Self-Generated Events" /> <title>Self-Generated Events</title> <p> It can sometimes be beneficial to be able to generate events @@ -954,64 +1196,71 @@ do_unlock() -> from your state machine to itself. </p> <p> - One example of using self-generated events can be when you have - a state machine specification that uses state entry actions. - You can code that using a dedicated function - to do the state transition. But if you want that code to be - visible besides the other state logic, you can insert - an <c>internal</c> event that does the entry actions. - This has the same unfortunate consequence as using - state transition functions: everywhere you go to - the state, you must explicitly - insert the <c>internal</c> event - or use a state transition function. + One example for this is to pre-process incoming data, for example + decrypting chunks or collecting characters up to a line break. + Purists may argue that this should be modelled with a separate + state machine that sends pre-processed events + to the main state machine. + But to decrease overhead the small pre-processing state machine + can be implemented in the common state event handling + of the main state machine using a few state data variables + that then sends the pre-processed events as internal events + to the main state machine. </p> <p> - The following is an implementation of entry actions - using <c>internal</c> events with content <c>enter</c> - using a helper function <c>enter/3</c> for state entry: + The following example uses an input model where you give the lock + characters with <c>put_chars(Chars)</c> and then call + <c>enter()</c> to finish the input. </p> <code type="erl"><![CDATA[ ... -init(Code) -> - process_flag(trap_exit, true), - Data = #{code => Code}, - enter(ok, locked, Data). +-export(put_chars/1, enter/0). +... +put_chars(Chars) when is_binary(Chars) -> + gen_statem:call(?NAME, {chars,Chars}). -callback_mode() -> - state_functions. +enter() -> + gen_statem:call(?NAME, enter). -locked(internal, enter, _Data) -> - do_lock(), - {keep_state,Data#{remaining => Code}}; -locked( - cast, {button,Digit}, - #{code := Code, remaining := Remaining} = Data) -> - case Remaining of - [Digit] -> - enter(next_state, open, Data); ... -open(internal, enter, _Data) -> - Tref = erlang:start_timer(10000, self(), lock), - do_unlock(), - {keep_state,Data#{timer => Tref}}; -open(info, {timeout,Tref,lock}, #{timer := Tref} = Data) -> - enter(next_state, locked, Data); +locked(enter, _OldState, Data) -> + do_lock(), + {keep_state,Data#{remaining => Code, buf => []}}; ... -enter(Tag, State, Data) -> - {Tag,State,Data,[{next_event,internal,enter}]}. +handle_event({call,From}, {chars,Chars}, #{buf := Buf} = Data) -> + {keep_state, Data#{buf := [Chars|Buf], + [{reply,From,ok}]}; +handle_event({call,From}, enter, #{buf := Buf} = Data) -> + Chars = unicode:characters_to_binary(lists:reverse(Buf)), + try binary_to_integer(Chars) of + Digit -> + {keep_state, Data#{buf := []}, + [{reply,From,ok}, + {next_event,internal,{button,Chars}}]} + catch + error:badarg -> + {keep_state, Data#{buf := []}, + [{reply,From,{error,not_an_integer}}]} + end; +... ]]></code> + <p> + If you start this program with <c>code_lock:start([17])</c> + you can unlock with <c>code_lock:put_chars(<<"001">>), + code_lock:put_chars(<<"7">>), code_lock:enter()</c>. + </p> </section> <!-- =================================================================== --> <section> + <marker id="Example Revisited" /> <title>Example Revisited</title> <p> - This section includes the example after all mentioned modifications - and some more using the entry actions, + This section includes the example after most of the mentioned + modifications and some more using state enter calls, which deserves a new state diagram: </p> <image file="../design_principles/code_lock_2.png"> @@ -1027,6 +1276,7 @@ enter(Tag, State, Data) -> </p> <section> + <marker id="Callback Mode: state_functions" /> <title>Callback Mode: state_functions</title> <p> Using state functions: @@ -1054,43 +1304,44 @@ code_length() -> init(Code) -> process_flag(trap_exit, true), Data = #{code => Code}, - enter(ok, locked, Data). + {ok, locked, Data}. callback_mode() -> - state_functions. + [state_functions,state_enter]. -locked(internal, enter, #{code := Code} = Data) -> +locked(enter, _OldState, #{code := Code} = Data) -> do_lock(), - {keep_state,Data#{remaining => Code}}; + {keep_state, Data#{remaining => Code}}; +locked( + timeout, _, + #{code := Code, remaining := Remaining} = Data) -> + {keep_state, Data#{remaining := Code}}; locked( cast, {button,Digit}, #{code := Code, remaining := Remaining} = Data) -> case Remaining of [Digit] -> % Complete - enter(next_state, open, Data); + {next_state, open, Data}; [Digit|Rest] -> % Incomplete - {keep_state,Data#{remaining := Rest}}; + {keep_state, Data#{remaining := Rest}, 30000}; [_|_] -> % Wrong - {keep_state,Data#{remaining := Code}} + {keep_state, Data#{remaining := Code}} end; locked(EventType, EventContent, Data) -> handle_event(EventType, EventContent, Data). -open(internal, enter, Data) -> - Tref = erlang:start_timer(10000, self(), lock), +open(enter, _OldState, _Data) -> do_unlock(), - {keep_state,Data#{timer => Tref}}; -open(info, {timeout,Tref,lock}, #{timer := Tref} = Data) -> - enter(next_state, locked, Data); + {keep_state_and_data, [{state_timeout,10000,lock}]}; +open(state_timeout, lock, Data) -> + {next_state, locked, Data}; open(cast, {button,_}, _) -> - {keep_state_and_data,[postpone]}; + {keep_state_and_data, [postpone]}; open(EventType, EventContent, Data) -> handle_event(EventType, EventContent, Data). handle_event({call,From}, code_length, #{code := Code}) -> - {keep_state_and_data,[{reply,From,length(Code)}]}. -enter(Tag, State, Data) -> - {Tag,State,Data,[{next_event,internal,enter}]}. + {keep_state_and_data, [{reply,From,length(Code)}]}. do_lock() -> io:format("Locked~n", []). @@ -1106,13 +1357,14 @@ code_change(_Vsn, State, Data, _Extra) -> </section> <section> + <marker id="Callback Mode: handle_event_function" /> <title>Callback Mode: handle_event_function</title> <p> This section describes what to change in the example to use one <c>handle_event/4</c> function. The previously used approach to first branch depending on event - does not work that well here because of the generated - entry actions, so this example first branches depending on state: + does not work that well here because of the state enter calls, + so this example first branches depending on state: </p> <code type="erl"><![CDATA[ ... @@ -1120,44 +1372,49 @@ code_change(_Vsn, State, Data, _Extra) -> ... callback_mode() -> - handle_event_function. + [handle_event_function,state_enter]. %% State: locked -handle_event(internal, enter, locked, #{code := Code} = Data) -> +handle_event( + enter, _OldState, locked, + #{code := Code} = Data) -> do_lock(), - {keep_state,Data#{remaining => Code}}; + {keep_state, Data#{remaining => Code}}; +handle_event( + timeout, _, locked, + #{code := Code, remaining := Remaining} = Data) -> + {keep_state, Data#{remaining := Code}}; handle_event( cast, {button,Digit}, locked, #{code := Code, remaining := Remaining} = Data) -> case Remaining of [Digit] -> % Complete - enter(next_state, open, Data); + {next_state, open, Data}; [Digit|Rest] -> % Incomplete - {keep_state,Data#{remaining := Rest}}; + {keep_state, Data#{remaining := Rest}, 30000}; [_|_] -> % Wrong - {keep_state,Data#{remaining := Code}} + {keep_state, Data#{remaining := Code}} end; %% %% State: open -handle_event(internal, enter, open, Data) -> - Tref = erlang:start_timer(10000, self(), lock), +handle_event(enter, _OldState, open, _Data) -> do_unlock(), - {keep_state,Data#{timer => Tref}}; -handle_event(info, {timeout,Tref,lock}, open, #{timer := Tref} = Data) -> - enter(next_state, locked, Data); + {keep_state_and_data, [{state_timeout,10000,lock}]}; +handle_event(state_timeout, lock, open, Data) -> + {next_state, locked, Data}; handle_event(cast, {button,_}, open, _) -> {keep_state_and_data,[postpone]}; %% %% Any state handle_event({call,From}, code_length, _State, #{code := Code}) -> - {keep_state_and_data,[{reply,From,length(Code)}]}. + {keep_state_and_data, [{reply,From,length(Code)}]}. ... ]]></code> </section> <p> Notice that postponing buttons from the <c>locked</c> state - to the <c>open</c> state feels like the wrong thing to do + to the <c>open</c> state feels like a strange thing to do for a code lock, but it at least illustrates event postponing. </p> </section> @@ -1165,6 +1422,7 @@ handle_event({call,From}, code_length, _State, #{code := Code}) -> <!-- =================================================================== --> <section> + <marker id="Filter the State" /> <title>Filter the State</title> <p> The example servers so far in this chapter @@ -1225,12 +1483,13 @@ format_status(Opt, [_PDict,State,Data]) -> <!-- =================================================================== --> <section> + <marker id="Complex State" /> <title>Complex State</title> <p> The callback mode <seealso marker="stdlib:gen_statem#type-callback_mode"><c>handle_event_function</c></seealso> enables using a non-atom state as described in section - <seealso marker="#callback_modes">Callback Modes</seealso>, + <seealso marker="#Callback Modes">Callback Modes</seealso>, for example, a complex state term like a tuple. </p> <p> @@ -1304,71 +1563,68 @@ set_lock_button(LockButton) -> init({Code,LockButton}) -> process_flag(trap_exit, true), - Data = #{code => Code, remaining => undefined, timer => undefined}, - enter(ok, {locked,LockButton}, Data, []). + Data = #{code => Code, remaining => undefined}, + {ok, {locked,LockButton}, Data}. callback_mode() -> - handle_event_function. + [handle_event_function,state_enter]. handle_event( {call,From}, {set_lock_button,NewLockButton}, {StateName,OldLockButton}, Data) -> - {next_state,{StateName,NewLockButton},Data, + {next_state, {StateName,NewLockButton}, Data, [{reply,From,OldLockButton}]}; handle_event( {call,From}, code_length, {_StateName,_LockButton}, #{code := Code}) -> {keep_state_and_data, - [{reply,From,length(Code)}]}; + [{reply,From,length(Code)}]}; +%% +%% State: locked handle_event( EventType, EventContent, {locked,LockButton}, #{code := Code, remaining := Remaining} = Data) -> - case {EventType,EventContent} of - {internal,enter} -> + case {EventType, EventContent} of + {enter, _OldState} -> do_lock(), - {keep_state,Data#{remaining := Code}}; - {{call,From},{button,Digit}} -> + {keep_state, Data#{remaining := Code}}; + {timeout, _} -> + {keep_state, Data#{remaining := Code}}; + {{call,From}, {button,Digit}} -> case Remaining of [Digit] -> % Complete - next_state( - {open,LockButton}, Data, - [{reply,From,ok}]); + {next_state, {open,LockButton}, Data, + [{reply,From,ok}]}; [Digit|Rest] -> % Incomplete - {keep_state,Data#{remaining := Rest}, + {keep_state, Data#{remaining := Rest, 30000}, [{reply,From,ok}]}; [_|_] -> % Wrong - {keep_state,Data#{remaining := Code}, + {keep_state, Data#{remaining := Code}, [{reply,From,ok}]} end end; +%% +%% State: open handle_event( EventType, EventContent, - {open,LockButton}, #{timer := Timer} = Data) -> - case {EventType,EventContent} of - {internal,enter} -> - Tref = erlang:start_timer(10000, self(), lock), + {open,LockButton}, Data) -> + case {EventType, EventContent} of + {enter, _OldState} -> do_unlock(), - {keep_state,Data#{timer := Tref}}; - {info,{timeout,Timer,lock}} -> - next_state({locked,LockButton}, Data, []); - {{call,From},{button,Digit}} -> + {keep_state_and_data, [{state_timeout,10000,lock}]}; + {state_timeout, lock} -> + {next_state, {locked,LockButton}, Data}; + {{call,From}, {button,Digit}} -> if Digit =:= LockButton -> - erlang:cancel_timer(Timer), - next_state( - {locked,LockButton}, Data, - [{reply,From,locked}]); + {next_state, {locked,LockButton}, Data, + [{reply,From,locked}]); true -> {keep_state_and_data, [postpone]} end end. -next_state(State, Data, Actions) -> - enter(next_state, State, Data, Actions). -enter(Tag, State, Data, Actions) -> - {Tag,State,Data,[{next_event,internal,enter}|Actions]}. - do_lock() -> io:format("Locked~n", []). do_unlock() -> @@ -1405,6 +1661,7 @@ format_status(Opt, [_PDict,State,Data]) -> <!-- =================================================================== --> <section> + <marker id="Hibernation" /> <title>Hibernation</title> <p> If you have many servers in one node @@ -1430,20 +1687,21 @@ format_status(Opt, [_PDict,State,Data]) -> </p> <code type="erl"><![CDATA[ ... +%% State: open handle_event( EventType, EventContent, - {open,LockButton}, #{timer := Timer} = Data) -> - case {EventType,EventContent} of - {internal,enter} -> - Tref = erlang:start_timer(10000, self(), lock), + {open,LockButton}, Data) -> + case {EventType, EventContent} of + {enter, _OldState} -> do_unlock(), - {keep_state,Data#{timer := Tref},[hibernate]}; + {keep_state_and_data, + [{state_timeout,10000,lock},hibernate]}; ... ]]></code> <p> - The - <seealso marker="stdlib:gen_statem#type-hibernate"><c>[hibernate]</c></seealso> - action list on the last line + The atom + <seealso marker="stdlib:gen_statem#type-hibernate"><c>hibernate</c></seealso> + in the action list on the last line when entering the <c>{open,_}</c> state is the only change. If any event arrives in the <c>{open,_},</c> state, we do not bother to rehibernate, so the server stays @@ -1458,6 +1716,10 @@ handle_event( <c>{open,_}</c> state, which would clutter the code. </p> <p> + Another not uncommon scenario is to use the event time-out + to triger hibernation after a certain time of inactivity. + </p> + <p> This server probably does not use heap memory worth hibernating for. To gain anything from hibernation, your server would |
