Hi!
Thanks for the great question!
While there are probably lots of ways of doing, there are two well-supported methods. You can either use RV’s commands.commandLineFlag, or external events.
Command Line Flags
The original method of doing this is using command line flags using the -flags argument for RV. The API call commands.commandLineFlag can obtain what flags RV was launched with, and optionally values that were passed.
A popular existing built into RV’s mode manager can be called with -flags ModeManagerVerbose. Within RV’s internal ModeManager, RV uses the commands.commandLineFlag to check if this was set. Because it is, the ModeManager outputs additional debugging information (such as what packages were loaded, from where, and how much time they took to load). The -flags approach is useful if you want an application state to exist, especially on startup. Since the flags are populated early and they are persistent, you can query them early or late in your application life cycle and RV will know what flags you launched with.
The API reference for this command looks like this:
commands.commandLineFlag( string; string flagName, string defaultValue = nil )
The RV command line has an option -flags . Arguments after -flags can have the form foo or foo=bar . commandLineFlag() will find the value of one of these name value pairs. If the argument does not have a value, then true will be returned.
For example:
shell> rv -flags A B=foo
commandLineFlag("A") would return true
commandLineFlag("B") would return foo
Python Function Signature Note
The API is notated in Mu syntax. When converting Mu to Python, the first item in the function signature is the return type. In Python, this would be called with:
import rv
result = rv.commands.commandLineFlag("flagName", 42)
This works well, but it doesn’t have any sense of command-flow with a direct point where anything is executed. That leads us to our other option:
External Events
Since RV 6.2.8, RV supports the ability to trigger the regular event system from the command line. You can use -sendEvent <eventName> <eventContents> to call an event of your choosing in RV. To keep the event types to events intended to come from outside of the app, the event name is prepended with external-.
This allows you to handle command-line arguments similarly to how you would handle your keyboard shortcut. Where you would define something like key-down-alt-j in the event table for your mode, you could define external-my-event with a callback.
For instance, if you run:
rv -sendEvent my-event 1234
An event with the name external-my-eveent with the event.contents() of 1234 will be sent immediately after packages are loaded. The events follow the same event pattern as any other event (i.e. priority based on what modes are loaded and their sort order, and an event will no longer propagate if it isn’t rejected).
This method also works to initiate an event over OSX’s shared application URL handling (so you can send a -sendEvent using an rvlink to a running instance of RV) or cross-application with rvpush.