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