*****************************************************************
***                  Log AkelPad plugin v5.7                  ***
*****************************************************************

2012-2025 Shengalts Aleksander aka Instructor (Shengalts@mail.ru)


*** Description ***

Watch logs or capture application output in real-time.


*** Functions ***

Log::Watch
Watch log.

Log::Output
Capture output.

Log::Settings
Settings dialog.


*** External call Log::Output ***

Call("Log::Output", 1, "PROGRAM", "WORKDIR", "REPATTERN", "RETAGS", INPUTCODEPAGE, OUTPUTCODEPAGE, FLAGS, "ALIAS")
  Parameters:
    1
      Execute application and capture output.
    "PROGRAM"
      File for execution. Can be "", if need to change "REPATTERN" and "RETAGS".
    "WORKDIR"
      Working directory.
    "REPATTERN"
      Regular expression pattern. Applied to each output line to jump to the text from the panel.
    "RETAGS"
      Pattern matches map.
        /FILE=\1         file to jump.
        /GOTOLINE=\2:\3  line and column to jump.
        /GOTOBYTE=\2     byte offset to jump.
        /GOTOCHAR=\2     character offset to jump.
        /FRAME=\1        frame data handle to jump.
    INPUTCODEPAGE
      Codepage of the input text for executed file.
      If -1, codepage will be autodetected.
      If -2 or not specified, codepage from plugin settings will be used.
    OUTPUTCODEPAGE
      Codepage of the output text from executed file.
      If -1, codepage will be autodetected.
      If -2 or not specified, codepage from plugin settings will be used.
    FLAGS (sum of the following):
         1  Don't create output panel.
         2  Hide input line.
         4  Save all documents before execution.
         8  Append text to the end.
        16  No scroll to the end.
        32  Wrap lines.
        64  Create, but don't show output panel. Requires closing through Call("Log::Output", 6).
       128  Close output panel, if application exit code equal to zero.

      4096  Source input - selection or all document if selection is empty.
      8192  Source input - all document.
     16384  Source input - selection.
            By default: source input isn't used.

   1048576  Output target - selection or all document if selection is empty.
   2097152  Output target - current document.
   4194304  Output target - current document selection.
   8388608  Output target - new tab.
            By default: output target - output panel.
    "ALIAS"
      Alias for Coder plugin theme, example: ".html". By default not used.

  Example (output to output panel):
    Call("Log::Output", 1, `tracert akelpad.sourceforge.net`)
  Example (output to selection without output panel):
    Call("Log::Output", 1, `ipconfig`, "", "", "", -1, -1, 1048577)
  Example (batch file execution for compilation):
    Call("Log::Output", 1, `"%d\Build.cmd" /S`, "%d", "^\s*(.*?)[(:](\d+)([,:](\d+))?[):]", "/FILE=\1 /GOTOLINE=\2:\4", -2, -2, 4)

Call("Log::Output", 2, *WINDOW, *DOCK)
  Parameters:
    2
      Get text output window handle. Use with Scripts plugin.
    *WINDOW
      Pointer to a variable, that receives text output window handle.
    *DOCK
      Pointer to a variable, that receives pointer to a DOCK structure.
  Example:
    WScript.Echo(GetOutputWindow());

    function GetOutputWindow()
    {
      var lpWnd;
      var hWnd=0;

      if (lpWnd=AkelPad.MemAlloc(_X64?8:4 /*sizeof(HWND)*/))
      {
        AkelPad.Call("Log::Output", 2, lpWnd);
        hWnd=AkelPad.MemRead(lpWnd, 2 /*DT_QWORD*/);
        AkelPad.MemFree(lpWnd);
      }
      return hWnd;
    }

Call("Log::Output", 3, *EXECSTATE, *PLUGINTHREAD, *PROCESSHANDLE, *PROCESSID, *EXITCODE)
  Parameters:
    3
      Get information about the current executed application. Use with Scripts plugin.
    *EXECSTATE
      Pointer to a variable, that receives execution state. Can be NULL.
      Sum of the following:
        0  Idle state.
        1  Execution command received.
        2  Plugin thread created, from which application will be executed.
        4  Application is executed and working.
    *PLUGINTHREAD
      Pointer to a variable, that receives plugin thread handle from which application was executed. Can be NULL.
    *PROCESSHANDLE
      Pointer to a variable, that receives process handle of the executed application. Can be NULL.
    *PROCESSID
      Pointer to a variable, that receives process id of the executed application. Can be NULL.
    *EXITCODE
      Pointer to a variable, that receives exit code of the executed application. Can be NULL.
  Example:
    WScript.Echo(GetExecState());

    function GetExecState()
    {
      var lpState;
      var nState=0;

      if (lpState=AkelPad.MemAlloc(4 /*sizeof(DWORD)*/))
      {
        AkelPad.Call("Log::Output", 3, lpState);
        nState=AkelPad.MemRead(lpState, 3 /*DT_DWORD*/);
        AkelPad.MemFree(lpState);
      }
      return nState;
    }

Call("Log::Output", 4, "TEXT", TEXTLEN, APPEND, CODEPAGE, "ALIAS")
  Parameters:
    4
      Set/Add text in the output panel. Use with Scripts plugin.
    "TEXT"
      Text for insertion.
    TEXTLEN
      Text length (default is -1). If -1, text string is terminated with NULL symbol.
    APPEND (one of the following):
      0 Replace all text in the output panel.
      1 Add text in the output panel (by default).
      2 Add text in the output panel in new line.
    CODEPAGE
      ANSI text codepage. By default zero - ANSI system codepage is used. Not used if text in Unicode.
    "ALIAS"
      Alias for Coder plugin theme, example: ".html". By default not used.

Call("Log::Output", 5, "TEXT", TEXTLEN, APPEND)
  Same as 4. Left for compatibility.

Call("Log::Output", 6)
  Parameters:
    6
      Close output panel.
  Example (uses functions GetOutputWindow and GetExecState):
    WScript.Echo(GetStdOut("ipconfig"));

    function GetStdOut(pCmd)
    {
      var hWndOutput=GetOutputWindow();
      var pStdOut="";
      var bClose=true;

      AkelPad.Call("Log::Output", 1, pCmd, "", "", "", -1, -1, 64);
      while (GetExecState())
        WScript.Sleep(100);

      if (hWndOutput)
        bClose=false;
      else
        hWndOutput=GetOutputWindow();

      if (hWndOutput)
      {
        AkelPad.SetEditWnd(hWndOutput);
        pStdOut=AkelPad.GetTextRange(0, -1);
        AkelPad.SetEditWnd(0);
        if (bClose) AkelPad.Call("Log::Output", 6);
      }
      return pStdOut;
    }

Call("Log::Output::NextMatch")
  Go to the next match.

Call("Log::Output::PrevMatch")
  Go to the previous match.

Call("Log::Output::RunCmd")
  Execute command.

Call("Log::Output::RunCmdDlg")
  Execute command dialog.


*** External call Log::Settings ***

Call("Log::Settings", 1, PAGE)
  Parameters:
    1
      Open settings dialog at specified page.
    PAGE
      Zero based page index.
