Repository files navigation

bashup.events is an event listener/callback API for creating extensible bash programs. It's small (<2.2k), fast (~10k events/second), and highly portable (no bash4-isms or external programs used). Events can be one-time or repeated, listeners can be added or removed, and any string can be an event name. (You can even have "promises", of a sort!) Callbacks can be any command or function plus any number of arguments, and can even opt to receiveadditional arguments supplied by the event.

Other features include:

• Running a callback each time something happens (event on,event emit)
• Running a callback thenext time something happens, but not after that (event once)
• Alerting subscribers of an event once, making them re-subscribe for future occurrences (event fire )
• Alerting subscribers of a one-time only event or calculation... not just current subscribers, butfuture ones as well (event resolve)
• Allowing subscribed callbacks to veto a process (e.g. validation rules), usingevent all
• Searching for the first callback that can successfully handle something, usingevent any

• Installation, Requirements And Use
• Basic Operations
  • event on
  • event emit
  • event off
  • event has
  • event fire
• Passing Arguments To Callbacks
• Promise-Like Events
  • event resolve
  • event resolved
• Conditional Operations
  • event all
  • event any
• Other Operations
  • event once
  • event encode
  • event decode
  • event get
  • event list
  • event quote
  • event error
• Event Handlers and Subshells
• License

Copy and paste thecode into your script, or place it onPATH andsource bashup.events. (If you havebasher, you canbasher install bashup/events to get it installed on yourPATH.) The code is licensedCC0, so you are not required to add any attribution or copyright notices to your project.

    $source bashup.events

This version of bashup.events works with bash 3.2+. If you don't need to support older bash versions, you can use thebash44 branch, which is significantly faster (~23k emits/second). Besides the supported bash version, the differences between the two versions are:

• The 3.2+ version is a bit larger and a lot slower: only around 10K emits/second, even when run with a newer bash.
• The 3.2+ version ofevent list returns sorted keys; the 4.4 version does not give a guaranteed order
• The 4.4+ version uses associative arrays; the 3.2+ version emulates them using individual variables with urlencoded names. Among other things, this means that the 3.2+ version can mask specific events withlocal, but the 4.4 version cannot.
• Other performance characteristics vary, as they use differentevent encode implementations with different performance characteristics. (4.4's is tuned for reasonable performance regardless of character set, while 3.2's is tuned for speed at all costs with a small character set.)

Sourcingbashup.events exposes one public function,event, that provides a variety of subcommands. All of the primary subcommands take an event name as their first argument.

Event names can be any string, but performance is best if you limit them to pure ASCII alphanumeric or_ characters, as all other characters have to be encoded at the start of each event command. (And the larger the character set used, the slower the encoding process becomes.)

event onevent cmd [args...] subscribescmd args... as a callback toevent, if it's not already added:

    $ event on"event1"echo"got event1"    $ event on"event1"echo"is this cool or what?"

event emitevent data... invokes all the callbacks forevent, passingdata... as additional arguments to any callbacks thatregistered to receive them. Callbacks added to the event while theemit is occurring willnot be invoked until a subsequent occurrence of the event, and the already-added callbacks will remain subscribed (unless they unsubscribe themselves, or were registered withevent once).

    $ event emit"event1"    got event1    is this cool or what?

event offevent [cmd [args...]] unsubscribes thecmd args... callback fromevent. If no callback is given,all callbacks are removed.

    $ event off"event1"echo"got event1"    $ event emit"event1"    is this cool or what?    $ event on"event2"echo foo    $ event off"event2"    $ event emit"event2"

• event hasevent returns truth ifevent has any registered callbacks.
• event hasevent cmd [args...] returns truth ifcmd args... has been registered as a callback forevent.

# `event has` with no callback tests for any callbacks at all    $ event has"event1"&&echo"yes, there are some callbacks"    yes, there are some callbacks    $ event has"something_else"||echo"but not for this other event"    but notfor this other event# Test for specific callback susbscription:    $ event has"event1"echo"is this cool or what?"&&echo"cool!"    cool!    $ event has"event1"echo"got event1"||echo"nope!"    nope!

event fireevent data... fires a "one shot" event, by invoking all the callbacks forevent, passingdata... as additional arguments to any callbacks thatregistered to receive them. All callbacks are removed from the event, and any new callbacks added during the firing will be invoked as soon as all the previously-added callbacks have been invoked (and then are also removed from the event).

The overall idea is somewhat similar to the Javascript "promise" resolution algorithm, except that you canfire an event more than once, and there is no "memory" of the arguments. (Seeevent resolve if you want something closer to a JS Promise.)

# `event fire` removes callbacks and handles nesting:    $mycallback() { event on event1echo"nested!"; }    $ event on"event1" mycallback    $ event fire"event1"    is this cool or what?    nested!    $ event emit"event1"# all callbacks gone now

When invoking an event, you can pass additional arguments that will be added to the end of the arguments supplied to the given callbacks. The callbacks, however, will only receive these arguments if they were registered to do so, by adding an extra argument after the event name: an@ followed by the maximum number of arguments the callback is prepared to receive:

# Callbacks can receive extra arguments sent by emit/fire/resolve/all/any:    $ event on"event2" @2echo"Args:"# accept up to 2 arguments    $ event fire"event2" foo bar baz    Args: foo bar

The reason an argument count is required, is because one purpose of an event system is to beextensible. If an event adds new arguments over time, old callbacks may break if they weren't written in such a way as to ignore the new arguments. Requiring an explicit request for arguments avoids this problem.

If the nature of the event is that it emits avariable number of arguments, however, you can register your callback with@_, which means "receiveall the arguments, no matter how many". You should only use it in places where you can definitely handle any number of arguments, or else you may run into unexpected behavior.

# Why variable arguments lists aren't the default:    $ event on"cleanup" @_echo"rm -rf"    $ event emit"cleanup" foo    rm -rf foo    $ event emit"cleanup" foo /# New release...  "cleanup" event added a new argument!    rm -rf foo /

event on,event once,event off, andevent has all accept argument count specifiers when adding, removing, or checking for callbacks. Callbacks with different argument counts are considered to bedifferent callbacks:

# Only one argument:    $ event on"myevent" @1echo    $ event emit"myevent" foo bar baz    foo# Different count = different callbacks:    $ event has"myevent" @1echo&&echo got it    got it    $ event has"myevent" @2echo||echo nope    nope# Add 2 argument version (numeric value is what's used):    $ event on"myevent" @02echo    $ event emit"myevent" foo bar baz    foo    foo bar# Remove the 2-arg version, add unlimited version:    $ event off"myevent" @2echo    $ event on"myevent" @_echo    $ event emit"myevent" foo bar baz    foo    foo bar baz# Unlimited version is distinct, too:    $ event has"myevent" @_echo&&echo got it    got it    $ event has"myevent" @2echo||echo nope    nope# As is the zero-arg version:    $ event has"myevent"echo||echo nope    nope# But the zero-arg version can be implicit or explicit, w/or without leading zeros:    $ event on"myevent"echo    $ event has"myevent"echo&&echo got it    got it    $ event has"myevent" @0echo&&echo got it    got it    $ event off"myevent" @00echo    $ event has"myevent"echo||echo nope    nope

If you have a truly one-time event, but subscribers could "miss it" by subscribing too late, you can useevent resolve to "permanentlyfire" an event with a specific set of arguments. Once this is done, all futureevent on calls for that event will invoke the callbackimmediately with the previously-given arguments.

There is no way to "unresolve" a resolved event within the current shell. Trying toresolve,emit,fire,any orall an already-resolved event will result in an error message and a failure return of 70 (EX_SOFTWARE).

# Subscribers before the resolve will be fired upon resolve:    $ event on"promised" event on"promised" @1echo"Nested:"    $ event on"promised" @1echo"Plain:"    $ event resolve"promised" value    Plain: value    Nested: value# Subscribers after the resolve are fired immediately:    $ event on"promised" event on"promised" @1echo"Nested:"    Nested: value    $ event on"promised" @1echo"Plain:"    Plain: value# And a resolved event never "has" any subscribers:    $ event has"promised"||echo nope    nope

event resolvedevent returns truth ifevent resolveevent has been called.

    $ event resolved"promised"&&echo"yep"    yep    $ event resolved"another_promise"||echo"not yet"    not yet

event allevent data... works likeevent emit, except that execution stops after the first callback that returns false (i.e., a non-zero exit code), and that exit code is returned. Truth is returned if all events return truth.

# Use an event to validate a password    $validate() {echo"validating:$1"; [[$3=~$2 ]]; }    $ event on"password_check" @1 validate"has a number"'[0-9]+'    $ event on"password_check" @1 validate"is 8+ chars" ........    $ event on"password_check" @1 validate"has uppercase"'[A-Z]'    $ event on"password_check" @1 validate"has lowercase"'[a-z]'    $ event all"password_check"'foo27'||echo"fail!"    validating: has a number    validating: is 8+ chars    fail!    $ event all"password_check"'Blue42Schmoo'&&echo"pass!"    validating: has a number    validating: is 8+ chars    validating: has uppercase    validating: has lowercase    pass!

event anyevent data... also works likeevent emit, except that execution stops on the first callback to return truth (i.e. a zero exit code). An exit code of 1 is returned if all events return non-zero exit codes.

    $match() {echo"checking for$1"; REPLY=$2; [[$1==$3 ]]; }    $ event on"lookup" @1 match a"got one!"    $ event on"lookup" @1 match b"number two"    $ event on"lookup" @1 match c"third time's the charm"    $ event any"lookup" b&&echo"match:$REPLY"    checkingfor a    checkingfor b    match: number two    $ event any"lookup" q||echo"fail!"    checkingfor a    checkingfor b    checkingfor c    fail!

event onceevent cmd [args...] is likeevent on, except that the callback is unsubscribed before it's invoked, ensuring it will be called at most once, even ifevent is emitted multiple times in a row:

    $ event once"something" @_echo    $ event emit"something" this that    this that    $ event emit"something" more stuff

(Note: a callback added byevent once cannot be removed byevent off; if you need to be able to remove such a callback you should useevent on instead and make the callback remove itself withevent off.)

event encodestring sets$REPLY to an encoded version ofstring that is safe to use as part of a bash variable name (i.e. ascii alphanumerics and_). Underscores and all other non-alphanumerics are encoded as an underscore and two hex digits.

    $ event encode"foo"&&echo$REPLY    foo    $ event encode"foo.bar"&&echo$REPLY    foo_2ebar    $ event encode"foo_bar"&&echo$REPLY    foo_5fbar    $ event encode' !"#$%'\''()*+,-./:;<=>?@[\]^_`'&&echo"$REPLY"    _20_21_22_23_24_25_27_28_29_2a_2b_2c_2d_2e_2f_3a_3b_3c_3d_3e_3f_40_5b_5c_5d_5e_5f_60    $ event encode$'\x01\x02\x03\x04\x05\x06\x07\b\t\n\x0b\f\r\x0e\x0f\x10'&&>echo"$REPLY"    _01_02_03_04_05_06_07_08_09_0a_0b_0c_0d_0e_0f_10    $ event encode$'{|}~\x7f'&&echo"$REPLY"    _7b_7c_7d_7e_7f

For performance reasons, the function that handles event encoding is JITted. Every time new non-ASCII or non-alphanumeric characters are seen, the function is rewritten to efficiently handle encoding them. This makes encoding extremely fast when a program only ever uses a handful of punctuation characters in event names or strings passed toevent encode. Encoding arbitrary strings (or using them as event names) is not recommended, however, since this will "train" the encoder to run more slowly forallevent operations from then on.

event decodestring sets$REPLY to the original event name forstring, turning the encoded characters back to their original values. If multiple arguments are given,REPLY is an array of results.

    $ event decode"foo_2ebar_2dbaz"&&echo$REPLY    foo.bar-baz    $ event decode"_2fspim""_2bspam"&&printf'%s\n'"${REPLY[@]}"    /spim    +spam

event getevent sets$REPLY to a string that can beeval'd to do the equivalent ofevent emit "event" "${@:2}". This can be used for debugging, or to allow callbacks likelocal to be run in a specific calling context. An error 70 is returned ifevent is resolved.

    $ event get lookup&&echo"$REPLY"    match a got\one\!"${@:2:1}"    match b number\two"${@:2:1}"    match c third\time\'s\the\charm"${@:2:1}"        $ event get"promised"&&echo"$REPLY"    event"promised" already resolved    [70]

(Notice that the encoded commands in$REPLY reference parameters beginning with"$2", which means that if you want to eval them with"$@" you'll need to unshift a dummy argument.)

event listprefix setsREPLY to an array of currently-defined event names beginning withprefix. events that currently have listeners are returned, as are resolved events.

# event1 and event2 no longer have subscribers:    $ event list"event"&&echo"${#REPLY[@]}"    0# But there are some events starting with "p"    $ event list"p"&&printf'%s\n'"${REPLY[@]}"    password_check    promised    $ event list"lookup"&&printf'%s\n'"${REPLY[@]}"    lookup

event quoteargs sets$REPLY to a space-separated list of the given arguments in shell-quoted form (usingprintf %q). The resulting string is safe toeval, in the sense that the arguments are guaranteed to expand to the same values (and number of values) as were originally given.

    $ event quote a b c&&echo"$REPLY"    a b c    $ event quote"a b c"&&echo"$REPLY"    a\b\c    $ event quote x"" y&&echo"$REPLY"    x'' y    $ event quote&&echo"'$REPLY'"''

event errormessage [exitlevel] printsmessage to stderr and returnsexitlevel, or 64 (EX_USAGE) if noexitlevel is given. (You will still need toreturn orexit for this to have any further effect, unlessset -e is in effect.)

    $ event error"This is an error" 127>/dev/null    This is an error    [127]

Just as with bash variables and functions, the current event handlers and the state of promises are inherited by subshells (e.g. in command substitutions), but changes made by a subshell do not affect the state of the calling shell. (As should be expected given that subshells are forked processes without shared memory or other interprocess communication by default.)

Note that this means adding or removing handlers in a subshell (evenimplicitly, viafire,resolve,once, etc.) hasno effect on the calling shell. As is normally the case for subshells, you’ll need to read their output and act on it, if you need to apply side-effects in the calling process.

To the extent possible under law,PJ Eby has waived all copyright and related or neighboring rights tobashup/events.This work is published from:United States.