[Tutorial] All About CLI Script Parameters and Sending Data to your Scripts

[agentcallooh]

If you've messed with OSBot's CLI, perhaps in creating a bot farm, you've probably messed with the -script CLI argument and using Script.getParameters() in your code. Or maybe you're just looking into automating your OSBot scripts; this guide will show you everything you need to know  

What are Script Parameters?

Parameters are a single String sent to your script via the command line (shell) using the -script CLI argument. It is accessed using Script.getParameters, which may return null if no parameters were provided. You'll need to learn a little bit of String manipulation in Java in order to work with them effectively. Here's some basics to get you started:

// To get multiple delimited parameters, use split:
// (Warning: you cannot use the comma or pipe character!)
String[] params = getParameters().split(";");
// To parse an integer or float from a String, use:
int itemsToUse = Integer.parseInt(params[0]);
float ratio = Float.parseFloat(params[1]);
// Test string equality - use .equals() not ==
if (params[2].equals("foobar")) log("Foobar mode enabled");

Requirements

In order to use -script you must:

• Provide your OSBot forum credentials via -login
• Specify an account to log in with via -bot.
  • If your script logs in manually (i.e. you use -allow norandoms and/or disable the auto login random solver then implement your own login handler like Explv's LoginEvent) then you should provide dummy credentials here eg. -bot LOGIN:PASS:0000

Restrictions

• You cannot use a comma (,) or pipe (|) character within a script name or parameter at all.
  • Doing so may cause various runtime errors like java.lang.NumberFormatException or java.lang.NullPointerException.
• Most shells have a length limit for commands. See the section below.

Escaping Spaces, Double Quotes and Backslashes (with Example)

If you are using either spaces ( ), double quotes (") or backslashes in your script name or parameters, you'll need to escape these, potentially twice: once for OSBot, and once for your shell. I'll give an example below for the a script named My "Test" Script with parameters My "Test" Parameters. The example content will be in blue and inserted content will be green.

1. If your script name contains either spaces ( ), double quotes (") or backslashes (\):
   1. Insert a backslash (\) before all existing double quotes or backslashes.
      My \"Test\" Script
   2. Surround the whole thing with double quotes that are not escaped with a backslash.
      "My \"Test\" Script"
2. Do the process above (1) for your script parameters if they contain spaces, double quotes, backslashes:
   "My \"Test\" Parameters"
3. Combine the script name and parameters with a colon in the middle.
   "My \"Test\" Script":"My \"Test\" Parameters"
   This is the raw string to be passed via the command line. If you are using a shell utility or sub-process library that takes an array/list of CLI args, stop here! Such a utility or library should do the next escaping step for you. If you are writing your own .bat/.sh scripts manually, continue on.
4. Before every double quote (") or backslash (\), insert another backslash.
   \"My \\\"Test\\\" Script\":\"My \\\"Test\\\" Parameters\"
5. Surround the entire thing with double quotes again.
   "\"My \\\"Test\\\" Script\":\"My \\\"Test\\\" Parameters\""

You're done! Yes, it's ugly, but it should work! Put the result directly after -script in your shell and you're good to go. Here's a combined example:

java -jar OSBot.jar -login username:password -bot login:password:bankpin -script "\"My \\\"Test\\\" Script\":\"My \\\"Test\\\" Parameters\""

Once again, this runs a script with the following ScriptManifest name My "Test" Script:

@ScriptManifest(name = "My \"Test\" Script", ...)
public class MyTestScript extends Script {
  // ..
}

Using Files Instead of Script Parameters

Sometimes shells can have surprisingly low limits on command length. If you expect your script input to be long (such as JSON, CSV or XML), you should be loading these from file instead instead of stuffing them in script parameters! These data formats may also contain incompatible characters (comma and pipe). Here's a few short examples to get you started (this isn't a guide on reading text from files in Java...)

String filePath = getDirectoryData() + File.separator + getParameters();
File fp = new File(filePath);
BufferedReader in = new BufferedReader(new FileReader(fp));
String line;
while ((line = in.readLine()) != null) {
	// Process one line of input.
}
in.close();

If you want the entire file contents read into a string, you can use Files.readAllBytes and Paths.get:

String filePath = getDirectoryData() + File.separator + getParameters();
String fileContent = new String(Files.readAllBytes(Paths.get(filePath)));

Finally, using files has an added benefit of being able to provide default input data when script parameters aren't available (ie. the script was run via the Script Selector window):

String filePath = getDirectoryData() + File.separator + (getParameters() != null ? getParameters() : "myDefaultInput.txt"));
// Use the filePath as above

And as usual, catch FileNotFound and other IOExceptions as necessary. Using files is a much better way to load in data than a lengthy script parameter!

Additional Tips

• If you're having trouble escaping things properly, perhaps it's better to question if including the escaped content is even necessary at all. In other words, if it's easier to not name scripts using spaces, quotes or backslashes, then do that instead of escaping. Simplicity is better than being smart.
• For a good user experience, provide sensible defaults if parameters aren't provided. If your script requires input and can't come up with defaults, try using the Java Swing framework to show a UI (see Explv's AIO if you need an example).
• DON'T USE COMMAS (,) OR PIPE CHARACTERS (|) AS DELIMITERS. They aren't allowed and will break OSBot! If you need to delimit a parameter string, try a healthy low-carb alternative of a semicolon.

Edited November 28, 2019 by agentcallooh
Correct getDataDirectory to getDirectoryData

[Naked]

first

[Medusa]

ok

[duinroosjes]

very nice

 

[Vi X]

Good Stuff <.<

[Probability]

Good thorough guide.