Rewrite Tools for gen_statem M:callback_mode/0

2 files changed, 131 insertions, 23 deletions

diff --git a/lib/tools/doc/src/erlang_mode.xml b/lib/tools/doc/src/erlang_mode.xml
index 00cf5196b4..7fef74813b 100644
--- a/lib/tools/doc/src/erlang_mode.xml
+++ b/lib/tools/doc/src/erlang_mode.xml
@@ -252,7 +252,14 @@
        behavior</item>
       <item>gen_event - skeleton for the OTP gen_event behavior</item>
       <item>gen_fsm - skeleton for the OTP gen_fsm behavior</item>
-      <item>gen_statem - skeleton for the OTP gen_statem behavior</item>
+      <item>
+	gen_statem (StateName/3) - skeleton for the OTP gen_statem behavior
+	using state name functions
+      </item>
+      <item>
+	gen_statem (handle_event/4) - skeleton for the OTP gen_statem behavior
+	using one state function
+      </item>
       <item>Library module - skeleton for a module that does not
        implement a process.</item>
       <item>Corba callback - skeleton for a Corba callback module.</item>
diff --git a/lib/tools/emacs/erlang-skels.el b/lib/tools/emacs/erlang-skels.el
index c1152f31a4..43763d2c8a 100644
--- a/lib/tools/emacs/erlang-skels.el
+++ b/lib/tools/emacs/erlang-skels.el
@@ -56,8 +56,10 @@
      erlang-skel-gen-event erlang-skel-header)
     ("gen_fsm" "gen-fsm"
      erlang-skel-gen-fsm erlang-skel-header)
-    ("gen_statem" "gen-statem"
-     erlang-skel-gen-statem erlang-skel-header)
+    ("gen_statem (StateName/3)" "gen-statem-StateName"
+     erlang-skel-gen-statem-StateName erlang-skel-header)
+    ("gen_statem (handle_event/4)" "gen-statem-handle-event"
+     erlang-skel-gen-statem-handle-event erlang-skel-header)
     ("wx_object" "wx-object"
      erlang-skel-wx-object erlang-skel-header)
     ("Library module" "gen-lib"
@@ -860,7 +862,7 @@ Please see the function `tempo-define-template'.")
   "*The template of a gen_fsm.
 Please see the function `tempo-define-template'.")
 
-(defvar erlang-skel-gen-statem
+(defvar erlang-skel-gen-statem-StateName
   '((erlang-skel-include erlang-skel-large-header)
     "-behaviour(gen_statem)." n n
 
@@ -868,9 +870,8 @@ Please see the function `tempo-define-template'.")
     "-export([start_link/0])." n
     n
     "%% gen_statem callbacks" n
-    "-export([init/1, terminate/3, code_change/4])." n
+    "-export([callback_mode/0, init/1, terminate/3, code_change/4])." n
     "-export([state_name/3])." n
-    "-export([handle_event/4])." n
     n
     "-define(SERVER, ?MODULE)." n
     n
@@ -899,30 +900,37 @@ Please see the function `tempo-define-template'.")
     (erlang-skel-separator-start 2)
     "%% @private" n
     "%% @doc" n
+    "%% Define the callback_mode() for this callback module." n
+    (erlang-skel-separator-end 2)
+    "-spec callback_mode() -> gen_statem:callback_mode()." n
+    "callback_mode() -> state_functions." n
+    n
+    (erlang-skel-separator-start 2)
+    "%% @private" n
+    "%% @doc" n
     "%% Whenever a gen_statem is started using gen_statem:start/[3,4] or" n
     "%% gen_statem:start_link/[3,4], this function is called by the new" n
     "%% process to initialize." n
     (erlang-skel-separator-end 2)
     "-spec init(Args :: term()) ->" n>
-    "{gen_statem:callback_mode()," n>
-    "State :: term(), Data :: term()} |" n>
-    "{gen_statem:callback_mode()," n>
-    "State :: term(), Data :: term()," n>
+    "{ok, State :: term(), Data :: term()} |" n>
+    "{ok, State :: term(), Data :: term()," n>
     "[gen_statem:action()] | gen_statem:action()} |" n>
     "ignore |" n>
     "{stop, Reason :: term()}." n
     "init([]) ->" n>
-    "{state_functions, state_name, #data{}}." n
+    "{ok, state_name, #data{}}." n
     n
     (erlang-skel-separator-start 2)
     "%% @private" n
     "%% @doc" n
-    "%% If the gen_statem runs with CallbackMode =:= state_functions" n
-    "%% there should be one instance of this function for each possible" n
-    "%% state name. Whenever a gen_statem receives an event," n
-    "%% the instance of this function with the same name" n
-    "%% as the current state name StateName is called to" n
-    "%% handle the event." n
+    "%% There should be one function like this for each state name." n
+    "%% 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>
@@ -934,8 +942,102 @@ Please see the function `tempo-define-template'.")
     (erlang-skel-separator-start 2)
     "%% @private" n
     "%% @doc" n
-    "%% If the gen_statem runs with CallbackMode =:= handle_event_function" n
-    "%% this function is called for every event a gen_statem receives." n
+    "%% This function is called by a gen_statem when it is about to" n
+    "%% terminate. It should be the opposite of Module:init/1 and do any" n
+    "%% necessary cleaning up. When it returns, the gen_statem terminates with" n
+    "%% Reason. The return value is ignored." n
+    (erlang-skel-separator-end 2)
+    "-spec terminate(Reason :: term(), State :: term(), Data :: term()) ->" n>
+    "any()." n
+    "terminate(_Reason, _State, _Data) ->" n>
+    "void." n
+    n
+    (erlang-skel-separator-start 2)
+    "%% @private" n
+    "%% @doc" n
+    "%% Convert process state when code is changed" n
+    (erlang-skel-separator-end 2)
+    "-spec code_change(" n>
+    "OldVsn :: term() | {down,term()}," n>
+    "State :: term(), Data :: term(), Extra :: term()) ->" n>
+    "{ok, NewState :: term(), NewData :: term()} |" n>
+    "(Reason :: term())." n
+    "code_change(_OldVsn, State, Data, _Extra) ->" n>
+    "{ok, State, Data}." n
+    n
+    (erlang-skel-double-separator-start 3)
+    "%%% Internal functions" n
+    (erlang-skel-double-separator-end 3)
+    )
+  "*The template of a gen_statem (StateName/3).
+Please see the function `tempo-define-template'.")
+
+(defvar erlang-skel-gen-statem-handle-event
+  '((erlang-skel-include erlang-skel-large-header)
+    "-behaviour(gen_statem)." n n
+
+    "%% API" n
+    "-export([start_link/0])." n
+    n
+    "%% gen_statem callbacks" n
+    "-export([callback_mode/0, init/1, terminate/3, code_change/4])." n
+    "-export([handle_event/4])." n
+    n
+    "-define(SERVER, ?MODULE)." n
+    n
+    "-record(data, {})." n
+    n
+    (erlang-skel-double-separator-start 3)
+    "%%% API" n
+    (erlang-skel-double-separator-end 3) n
+    (erlang-skel-separator-start 2)
+    "%% @doc" n
+    "%% Creates a gen_statem process which calls Module:init/1 to" n
+    "%% initialize. To ensure a synchronized start-up procedure, this" n
+    "%% function does not return until Module:init/1 has returned." n
+    "%%" n
+    (erlang-skel-separator-end 2)
+    "-spec start_link() ->" n>
+    "{ok, Pid :: pid()} |" n>
+    "ignore |" n>
+    "{error, Error :: term()}." n
+    "start_link() ->" n>
+    "gen_statem:start_link({local, ?SERVER}, ?MODULE, [], [])." n
+    n
+    (erlang-skel-double-separator-start 3)
+    "%%% gen_statem callbacks" n
+    (erlang-skel-double-separator-end 3) n
+    (erlang-skel-separator-start 2)
+    "%% @private" n
+    "%% @doc" n
+    "%% Define the callback_mode() for this callback module." n
+    (erlang-skel-separator-end 2)
+    "-spec callback_mode() -> gen_statem:callback_mode()." n
+    "callback_mode() -> handle_event_function." n
+    n
+    (erlang-skel-separator-start 2)
+    "%% @private" n
+    "%% @doc" n
+    "%% Whenever a gen_statem is started using gen_statem:start/[3,4] or" n
+    "%% gen_statem:start_link/[3,4], this function is called by the new" n
+    "%% process to initialize." n
+    (erlang-skel-separator-end 2)
+    "-spec init(Args :: term()) ->" n>
+    "{ok, State :: term(), Data :: term()} |" n>
+    "{ok, State :: term(), Data :: term()," n>
+    "[gen_statem:action()] | gen_statem:action()} |" n>
+    "ignore |" n>
+    "{stop, Reason :: term()}." n
+    "init([]) ->" n>
+    "{ok, state_name, #data{}}." n
+    n
+    (erlang-skel-separator-start 2)
+    "%% @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>
@@ -965,17 +1067,16 @@ Please see the function `tempo-define-template'.")
     "-spec code_change(" n>
     "OldVsn :: term() | {down,term()}," n>
     "State :: term(), Data :: term(), Extra :: term()) ->" n>
-    "{gen_statem:callback_mode()," n>
-    "NewState :: term(), NewData :: term()} |" n>
+    "{ok, NewState :: term(), NewData :: term()} |" n>
     "(Reason :: term())." n
     "code_change(_OldVsn, State, Data, _Extra) ->" n>
-    "{state_functions, State, Data}." n
+    "{ok, State, Data}." n
     n
     (erlang-skel-double-separator-start 3)
     "%%% Internal functions" n
     (erlang-skel-double-separator-end 3)
     )
-  "*The template of a gen_statem.
+  "*The template of a gen_statem (handle_event/4).
 Please see the function `tempo-define-template'.")
 
 (defvar erlang-skel-wx-object