akfavatar-term(3)                                            akfavatar-term(3)



NNAAMMEE
       akfavatar-term  -  module  to execute terminal based programs inside of
       AKFAvatar

SSYYNNOOPPSSIISS
       term = require "akfavatar-term"

       NNoottee: You have to use a global variable if you  want  to  use  the  APC
       interface.

DDEESSCCRRIIPPTTIIOONN
       This  module  can  be  used  to  execute common terminal based programs
       inside of AKFAvatar.  The terminal emulation emulates a Linux  textcon‐
       sole (not only on Linux based systems).

       It  can also be used to write specific programs for AKFAvatar in other‐
       wise unsupported languages.  There are some facilities with  which  the
       hosting script and the guest program can communicate with each other.

       AATTTTEENNTTIIOONN:  This module is not available for all platforms!  Especially
       not for Windows.

       tteerrmm..ssttaarrttddiirr((_[_d_i_r_e_c_t_o_r_y_]))
              Sets the start directory for the  next  tteerrmm..eexxeeccuuttee(())  command.
              If no directory is given, it clears the previous setting.

              NNoottee:  The  working  directory of the host and the guest program
              are independent!

       tteerrmm..hhoommeeddiirr(())
              Set the start directory for the next tteerrmm..eexxeeccuuttee(())  command  to
              the users home directory.

              NNoottee:  The  working  directory of the host and the guest program
              are independent!

       tteerrmm..ccoolloorr((_t_r_u_e_|_f_a_l_s_e))
              Switches the color support on or off.
              The terminal type with color is "linux",  without  color  it  is
              "linux-m".

       tteerrmm..sseetteennvv((_v_a_r_i_a_b_l_e_, _v_a_l_u_e))
              Sets the given environment _v_a_r_i_a_b_l_e to the given _v_a_l_u_e.
              This   also   affects  programs  started  with  ooss..eexxeeccuuttee(())  or
              iioo..ppooppeenn(()).

       tteerrmm..uunnsseetteennvv((_v_a_r_i_a_b_l_e))
              Unsets (clears) the given environment _v_a_r_i_a_b_l_e.
              This  also  affects  programs  started  with   ooss..eexxeeccuuttee(())   or
              iioo..ppooppeenn(()).

       tteerrmm..eexxeeccuuttee((_[_p_r_o_g_r_a_m _[_,_a_r_g_u_m_e_n_t_s_]_]))
              Executes  the given _p_r_o_g_r_a_m with the given _a_r_g_u_m_e_n_t_s in the ter‐
              minal emulation.  If no _p_r_o_g_r_a_m is given it starts  the  default
              shell.

   AAPPCC iinntteerrffaaccee
       The  "Application  Program  Command"  (APC)  interface is a method with
       which the guest program can communicate with the Lua interpreter of the
       host program.  To use this, the guest program sends Escape sequences to
       the standard output, like follows: ESC + "_", followed by the  command,
       closed  with  ESC + "\" to end the sequence.  The output has eventually
       to be flushed to get an immediate effect.

       For example in C:

       static void
       APC (const char *s)
       {
         fprintf (stdout, "\033_%s\033\\", s);
         fflush (stdout);
       }

       The commands can be Lua function calls, especially the "avt."  commands
       defined by "lua-akfavatar" (see the "lua-akfavatar-ref").
       Up to 1024 characters can be sent.  So it is not suited to send compli‐
       cated code from the guest program.  However the hosting script, that is
       the  Lua script that calls the guest program, can define its own global
       functions, which are then also accessible with the APC interface.

       As a convention the host script should define an  environment  variable
       named _"_A_P_C_", which decribes the accessible commands.

       For example:

         term.setenv("APC", _VERSION .. ", lua-akfavatar")

       tteerrmm..sseenndd((_s_t_r_i_n_g))
              Send  a  string to the guest program, as if it is typed from the
              keyboard.  This can only be used from  the  APC  interface  (see
              above).
              If  the  guest  program  is  line-oriented, the string should be
              closed with a "\r" (for return).

       tteerrmm..ddeecciiddee((_s_t_r_i_n_g_1 _[_,_s_t_r_i_n_g_2_]))
              Present plus/minus buttons and depending on  that  choice  sends
              _s_t_r_i_n_g_1  or _s_t_r_i_n_g_2 to the guest program, as if it is typed from
              the keyboard.  This can only be used from the APC interface (see
              above).   If  the  guest  program is line-oriented, both strings
              should be given  and  they  should  be  closed  with  "\r"  (for
              return).

SSEEEE AALLSSOO
       lluuaa--aakkffaavvaattaarr(1) lluuaa(1) lluuaa--aakkffaavvaattaarr--rreeff(3) aakkffaavvaattaarr--ggrraapphhiicc(3) aakkffaa‐‐
       vvaattaarr..uuttff88(3)



AKFAvatar                         2012-07-21                 akfavatar-term(3)
