Release Notes for EPIC5-2.1.2 (Released: 2020-05-11)

*** News 05/11/2020 -- EPIC5-2.1.2 released here (Lugubrious) (Commit id: 1908)

*** News 05/09/2020 -- New built in function $execctl()
        You can now program the /EXEC command with this low level function

        --- warning ---
        Many of the things you can set here are not sanity checked.
        If you feed it garbage in, you will get garbage out.
        If you need safety rails, use the /EXEC command.
        --- warning ---

        Usage:
        ------
        $execctl(REFNUMS)
                Get all refnums in the entire system (as integers)
        $execctl(REFNUM <description>)
                Convert a description (like %3 or %myproc) into a refnum integer

        $execctl(NEW <commands>)
                Create a new /exec process (does not run it!)
        $execctl(LAUNCH <refnum>)
                Run an /exec process that hasn't been started yet
        $execctl(CLOSEIN <refnum>)
                Close the STDIN to the process (this means you can't send any
                more data to the program.  This is useful for programs
                that wait until they've got an EOF from stdin to do their
                thing)
        $execctl(CLOSEOUT <refnum>)
                Close the STDOUT and STDERR from the process (this means
                we won't receive any more output from the program.  This is
                useful if we don't want any more output from the program.
                Many programs will die from SIGPIPE if stdout is closed)
        $execctl(SIGNAL <signal> <refnum>)
                KILL (send a signal) to a process.  The <signal> may either
                be an integer (like $execctl(SIGNAL 9 3) or it may
                be a short name (like $execctlSIGNAL HUP 3) to kill
                process 3.

        $execctl(GET <refnum> [FIELD])
        $execctl(SET <refnum> [FIELD] [VALUE])
                You can GET all the fields of the object, and SET some of them.
                Some fields cannot be changed after the process is launched.

        Field           Set?    Notes
        -------------   ------  -----------------------------------
        REFNUM          No      The integer refnum - never repeated.
        REFNUM_DESC     No      The "target" version (ie, %3)
        LOGICAL         Yes     The user-supplied name - must be unique
        LOGICAL_DESC    No      The "target" version (ie, %myproc)
                                -- This will change if you SET LOGICAL
        COMMANDS        Yes     The commands to run (**)
        DIRECT          Yes     Whether to use a shell (**)
        REDIRECT        Yes     Either PRIVMSG or NOTICE
        WHO             Yes     The target to send output to
                                -- Output from the process is redirected verbatim
        WINDOW_REFNUM   Yes     The window this exec runs in context of
                                -- Undefined behavior if window does not exist
        SERVER_REFNUM   Yes     The server this exec runs in context of
                                -- This is for redirects and code callbacks
        LINES_LIMIT     Yes     How many lines to receive before CLOSEOUT
                                -- 0 means "no limit"
        STDOUTC         Yes     ircII code for every complete line of stdout
        STDOUTPC        Yes     ircII code for every partial line of stdout
        STDERRC         Yes     ircII code for every complete line of stderr
        STDERRPC        Yes     ircII code for every partial line of stderr

        PID             No      The process id of the process (after launch)
                                -- This is -1 before launch
        STARTED_AT      No      When the process was created or launched
                                -- It is first set when creation happens
                                -- It is last set when launched
        P_STDIN         No      File descriptor to talk to process's STDIN
        P_STDOUT        No      File descriptor to read from process's STDOUT
        P_STDERR        No      File descriptor to read form process's STDERR
                                -- There is nothing you can do with these.
                                -- Don't try.
        LINES_RECVD     No      How many lines of output the process has sent
        LINES_SENT      No      How many lines we sent to the process
        EXITED          No      0 if process has exited yet -- 1 if it has
        TERMSIG         No      The signal that killed the process
                                -- It is -1 if the process has not died
                                -- It is -1 if the process exited normally
        RETCODE         No      The exit code of the process
                                -- It is -1 if the process has not died
                                -- It is -1 if the process was killed
        DUMB            No      Reserved for future/internal use
        DISOWNED        No      Reserved for future/internal use
        (Note: ** - Cannot be SET after launch)

*** News 05/08/2020 -- New flag to /EXEC, /EXEC -NOLAUNCH
        The /EXEC -NOLAUNCH flag directs the /EXEC command not to launch
        a process that has not already launched.  You can launch it later
        merely by referencing it with its name or refnum.

                /EXEC -nolaunch -name myproc ls -l
                /EXEC -nolaunch -limit 5 %myproc
                /EXEC %myproc

        Many /EXEC operations do not work on an unlaunched process.

*** News 05/07/2020 -- New function, $uuid4()
        This function returns a random UUID4 string.  If you know what that is,
        you might know why it's handy to be able to have one.

        ALL ARGUMENTS TO THIS FUNCTION ARE RESERVED FOR FUTURE EXPANSION.
        To get the default behavior, pass no arguments to this function.
        Forwards compatability is not guaranteed if you pass undefined args

*** News 05/07/2020 -- New /ON, /ON SEND_EXEC
        Whenever text is being sent to an /EXEC process, either through /EXEC -IN
        or /MSG %proc or a /QUERY or whatever, it is displayed to your screen.
        The /ON SEND_EXEC process will let you adorn how this text is displayed,
        instead of it just being displayed blankly as it has always done.

*** News 05/07/2020 -- The /EXEC command
        The /EXEC command has always been part of ircII, but it hasn't
        changed much during EPIC's lifetime.  There were some rough edges
        related to querying exec'd processes, things not always going
        to the windows people expected, some flags not being able to be
        used with other flags, etc.

        So the /EXEC command has been substantially revamped, with an intention
        of everything being "do what i expect".  If you find things that are
        weirdly behaving, please let me know!

        Instead of describing the changes, let's just level-set the behavior:

        Every /EXEC command can create or modify one process

        [The most general explanation of the syntax]
        Modify an existing running exec:
                /EXEC [options] %refnum [extra arguments]
                /EXEC [options] %logical-name [extra arguments]

        Create a new exec:
                /EXEC [options] commands to run
                /EXEC [options] (commands to run) [extra-arguments]

        OPTIONS to /EXEC

           [ Options related to sending data to/from the process ]
                -CLOSE
                        Close the process's STDIN, STDOUT, and STDERR
                -CLOSEIN
                        Close the process's STDIN
                -CLOSEOUT
                        Close the process's STDOUT and STDERR
                -IN [extra arguments]
                        Send data to a process
           [ Options related to how the process integrates with ircII ]
                -NAME
                        Change the logical name of a process
                -OUT
                        Send all output from the process to the now-current
                        channel in the now-current window.
                -WINDOW
                        Display all output from or related to the process to the
                        now-current window.
                -WINTARGET <windesc>
                        Display all output from or related to the process to the
                        specified window
                -MSG [target]
                        Send all output from the process to the target.
                        The target can be an irc, dcc chat, or other exec,
                        or anything you can send a message to.
                        Messages sent over IRC are sent as PRIVMSGs
                -NOTICE
                        Send all output from the process to the target.
                        Messages sent over IRC are sent as NOTICEs.

            [ Options related to scripting with processes ]
                -LINE {code}
                        Run {code} for each full line of output from stdout of the process.
                        $* will be the line of output
                -LINEPART {code}
                        Run {code} for each incomplete line of output from stdout of the process.
                        $* will be the incomplete line of output
                -ERROR {code}
                        Run {code} for each full line of output from stderr of the process.
                        $* will be the incomplete line of output
                -ERRORPART {code}
                        Run {code} for each incomplete line of output from stderr of the process.
                        $* will be the incomplete line of output
                -END {code}
                        Run {code} when the process has completed.  This means when the process
                        has exited and all of its output has been processed.  (Sometimes this
                        lags the actual exit)
                                $0 is the logical process name or its refnum
                                $1 is the signal that killed it (if it was killed)
                                $2 is the exit code (if it exited)

            [ Options that don't fit in the other categories ]
                -DIRECT
                        Run the program directly -- do not use a shell.
                        Advantages:  The command you give is literally executed
                        Disadvantages: If you depend on filename globbing or aliases, well, tough
                -LIMIT <number>
                        Read <number> lines from the process and then -CLOSE it.

            [ Options related to sending a signal to the process ]
                -<signal_number>
                        Send the signal to the process, similar to kill -<signal_number> <pid>
                -<signal_name>
                        Send the signal to the process, similar to kill -<signal_name> <pid>

        Additionally, %<procref> or %<procname> are full blown message targets that you can
        /msg or /query or whatever you want, just like all other targets.

        [Examples of how this works]

*** News 04/26/2020 -- New python script, 'shortener'
        You can load this script with
                pyload shortener
        This script provides an in-client URL shortening service.
        Whenever someone provides a URL in a message, the service
        will create a short URL that will be served by an http
        redirection server that runs in client

        Example:
        --------
        <nick> hey, please visit www.frobnitz.com/really-long-and-wraps
        +onto-the-next-line-so-you-can-tpaste-it
        *** http://127.0.0.1:8080/1

        Then you can visit http://127.0.0.1:8080/1 and it will
        redirect you to the original url.

*** News 02/24/2019 -- EPIC5-2.1.1 (Abulia) was released here
        Even though not everything is done, I think I've probably
        dragged my feet long enough

*** News 11/28/2018 -- /EXEC -WINTARGET outsputs to a window by name (caf)
        The normal behavior of /EXEC is to send the output of a command
        to the current window (or is it the OTHER window?  I forget)
        Before this, you couldn't ordinarily send it to just any old
        random window you wanted.

        You can use /EXEC -WINTARGET to send it to any window you want:
        Example:
                /exec -wintarget msgwin ls