ltluatex documentation improvement concerning callbacks

Brief outline of the enhancement

It should be noticed in the ltluatex documentation that \IfFileExists also triggers an open_read_file callback which may not seem natural at all. As a side effect, LuaLaTeX \input triggers open_read_file twice whereas LuaTeX \input triggers it only once. It does not make a difference for the reader function but the close function must definitely take this into account, because it is called twice. Next example uses a virtual file named "foo" which contains exactly 3 lines. Before I input "foo" I register the appropriate callbacks and I unregister them in the close function, but only when at least one line of the virtual file has been read. Without this test, that would work perfectly in LuaTeX , but not in LuaLaTeX.

\documentclass{minimal}
\begin{document}
\directlua{
  luatexbase.add_to_callback(
    'find_read_file',
    function(id_number, asked_name)
      print('**** find_read_file', id_number, asked_name)
      return asked_name
    end,
    'DUMMY'
  );
  luatexbase.add_to_callback(
    'open_read_file',
    function (file_name)
      print('**** open_read_file', file_name)
      local i = 0;
      local lines = {'a', 'b', 'c'};
      return {
        reader = function (env)
          i = i+1;
          print('**** read', i, lines[i]);
          env.can_close = true
          return lines[i];
        end,
        close = function (env)
          if env.can_close then
            print('**** close');
            luatexbase.remove_from_callback(
              'find_read_file',
              'DUMMY'
            )
            luatexbase.remove_from_callback(
              'open_read_file',
              'DUMMY'
            )
          end
        end
      }
    end,
    'DUMMY'
  )
}
\input{foo}
\end{document}

And the LuaTeX version

\directlua{
  callback.register(
    'find_read_file',
    function (id_number, asked_name)
      print('**** find_read_file', id_number, asked_name)
      return asked_name
    end
  );
  callback.register(
    'open_read_file',
    function (file_name)
      print('**** open_read_file', file_name)
      local lines = {'a', 'b', 'c'};
      local i = 0;
      return {
        reader = function (this)
          i = i+1;
print('**** reader', i, lines[i]);
          return lines[i];
        end,
        close = function (this)
          print('**** close');
          callback.register('find_read_file', nil)
          callback.register('open_read_file', nil)
        end
      }
    end
  );
}
\input{foo}
\bye

latex3 / latex2e

ltluatex documentation improvement concerning callbacks #812

Brief outline of the enhancement