Automation 4 Progress Reporting and Debugging interface

This document describes the functions used for reporting progress and
outputting debug information during the running of a script.

---

Showing/hiding the progress dialog

This function is used to show or hide the progress dialog.

function aegisub.progress.show(do_show, can_cancel)

@do_show (boolean)
  True if the dialog should be shown, false if it should be hidden.

@can_cancel (boolean)
  Determines whether the Cancel button is shown. If you set this to true,
  you should remember to periodically test whether the script has been
  cancelled.

Returns: nothing.

---

Setting the progress bar position

function aegisub.progress.set(precent)

@percent (number)
  The percentage completed.

Returns: nothing.

---

Showing the current task

Used to set a message describing the current task being done.

function aegisub.progress.task(msg, ...)

@msg (string)
  A format string used for the message.

@...
  Parameters to the format string.

Returns: nothing.

---

Setting the progress dialog title

function aegisub.progress.title(title, ...)

@title (string)
  A format string used for the title.

@...
  Parameters to the format string.

Returns: nothing.

---

Getting the "cancelled" status

Call this function to determine whether the Cancel button in the progress
dialog has been clicked.

function aegisub.progress.is_cancelled()

Returns: Boolean. True is the user has clicked the Cancel button, false if it
  has not been clicked, nil if there is no Cancel button.

---

Outputting text to the debug log

function aegisub.debug.out(level, msg, ...)

@level (number)
  Integer describing the verbosity of this message. Here are some suggested
  values you can use:
    0: Fatal, this is really an error that can't be ignored.
    1: Error, this kind of error can be recovered from, but might result in a
       fatal error later on.
    2: Warning, something might be going wrong.
    3: Hint, something isn't entirely sane, but nothing wrong.
    4: Debug, some additional data only needed for development.
    5: Trace, extremely verbose data showing every tiny step during execution.

@msg (string)
  A format string used for the message.

@...
  Parameters for the format string.

Returns: nothing.

---