dr-scripts
dr-scripts copied to clipboard
rpherbig
[IDEA] - Call a script with some built-in argument that outputs a bit of information about the script, the available arguments, and the yaml settings used
Today in Discord I was explaining to a fairly new user how to open up a script and take a look at the allowable required or optional arguments that the script can be called with: https://discord.com/channels/745675889622384681/745678330933805157/947946336324558899
Before writing out that explanation, I was inclined to say: "Oh, just call the script with no arguments and you'll get an output of the available args and what they do." But it occurred to me that, if all the script args are optional, rather than outputting the available args, it will instead run the script.
So I started thinking. What if we had something built-in that would spit out a brief description of the script as well as the available arguments? And perhaps even the yaml settings used within the script?
The case in question was about the ;athletics script. All the arguments in this script are optional. Instead of writing a long description in Discord about how to open the script and search for the args section, what if we made it a standard thing to be able to call any script with an "info" argument and it would then spit out a summary of the script and the available args (with the latter nothing different than you'd get now if you called a script without required args or with the wrong format for optional args).
Example:
>;athletics help
Summary: The athletics script is a comprehensive script to help you train the athletics skill. It works in various areas and
tries to train athletics at the closest known athletics training spot.
Script call and available arguments (note that arguments in brackets are optional):
;athletics [wyvern] [undergondola] [xalas] [stationary] [cliffs] [max]
wyvern Climb both undergondola and wyvern cliffs
undergondola Climb branch etc undergondola
xalas Climb xalas in zoluren in instead of undergondola
stationary Stand still and use a climbing rope
cliffs Climb undergondola without attempting branch
max Keep training until 32/34+
Yaml settings used in this script:
have_climbing_rope: Set this to true to use a magic climbing rope for training. This currently requires zills.
held_athletics_items: A list of 1-2 items held while doing athletics to increase the difficulty. Each item adds difficulty. Uses get/stow, and the items don't need to be weapons.
I know that Elanthipedia is typically the place that this kind of information goes, but I find updating Elanthipedia to be excruciating and it's also a manual process which lends it toward getting stale.
My idea above is to make this an automated process. The structure is already there for dumping help information for script arguments, and we'd have to think something up for doing something similar for yaml settings. I don't entirely know what that looks like at the moment but I've always liked the idea of something like Python's docstrings. If you enforce the code commenting convention then you can dump the help information automatically.
What do ya'll think?
I know that Elanthipedia is typically the place that this kind of information goes, but I find updating Elanthipedia to be excruciating and it's also a manual process which lends it toward getting stale.
The idea behind keeping the documentation on Elanthipedia was so that people could update/improve it without having to go through the hassle of submitting PRs. If that isn't happening, I'm open to moving it back to the repo. The centralization appeals to me.
I know that Elanthipedia is typically the place that this kind of information goes, but I find updating Elanthipedia to be excruciating and it's also a manual process which lends it toward getting stale.
The idea behind keeping the documentation on Elanthipedia was so that people could update/improve it without having to go through the hassle of submitting PRs. If that isn't happening, I'm open to moving it back to the repo. The centralization appeals to me.
@KatoakDR also had an idea to move the documentation to the GitHub wiki, which is much more friendly to edit.
Primarily I'm thinking about it like this: each script may have a set of arguments it can accept, and a set of yaml settings it uses. If we could structure the scripts to output this helpful information, it is always accurate, never stale, and easy to call in-game via something like ;buff help.
Full documentation, examples, etc., I agree are better in a wiki format. And calling a script with the help arg could also spit out that link. Then a script user could get some basic help output and a link to more robust documentation without ever having to open the script file itself.
And here I am not realizing that whoever wrote the ArgParser already did this for outputting arg information via a help argument that's built in to the parser and displays the arguments.
Still unsure the right approach to do something programmatically like that for yaml settings used in a script. Sure would be a neat tool. Just today in Discord we were trying to remember the yaml setting to stamp your work in a crafting script.
Just a thought - I imagine it would be pretty easy for the args parser (i.e. not each individual script) to treat "help" or "?" as a special arg which is always valid and outputs the arg help then exits. We'd want to make sure we don't already use that reserved arg in a script, of course.
Just a thought - I imagine it would be pretty easy for the args parser (i.e. not each individual script) to treat "help" or "?" as a special arg which is always valid and outputs the arg help then exits. We'd want to make sure we don't already use that reserved arg in a script, of course.
Thanks, Robert. Really enjoy your input. I'm a little embarrassed to say that, until I bothered to look through the ArgParser method in dependency today, I did not realize that it already has a provision to call a script with a help argument and recognize that call and then do a simple output of the arguments.
class ArgParser
def parse_args(data, flex_args = false)
raw_args = variable.first
baselist = variable.drop(1).dup
unless baselist.size == 1 && baselist.grep(/^help$|^\?$|^h$/).any?
result = data.map { |definition| check_match(definition, baselist.dup, flex_args) }.compact
return result.first if result.length == 1
if result.empty?
echo "***INVALID ARGUMENTS DON'T MATCH ANY PATTERN***"
respond "Provided Arguments: '#{raw_args}'"
elsif result.length > 1
echo '***INVALID ARGUMENTS MATCH MULTIPLE PATTERNS***'
respond "Provided Arguments: '#{raw_args}'"
end
end
display_args(data)
exit
end
So, some of that work is done to give help output for script args. Now, it won't output anything if a script doesn't accept args and doesn't use the ArgParser. And it doesn't output a summary of the script.
The cool thing about the ArgParser is that, by definition, the specifying of the script arguments and the structure to have an description of each argument and be able to output some helpful information is all integral to the coding. So there is no second website to update and get stale. If you add an argument in an update to the script, that addition is automatically handled by the parser and the helpful output is automatically updated.
I think it would be really cool, and arguably more beneficial, to have the same process work for any yaml setting a script utilizes. I wrote a long explanation today to a new user in Discord about the Lich project. Long story short, I told that person one of the beautiful things about the Lich project is that we have this ready-made set of more than 200 scripts that work for all characters, guilds, and circles. And the reason this works is the two-pronged approach to it: a script written in Ruby that a user doesn't ever have to care about, and doesn't have to edit. All they need to do is have their human-readable yaml settings file set up, and the rest is taken care of for them.
So naturally, the next question is: "Oh, cool. Ok, I don't know ruby and couldn't even begin to understand how to edit the ;buff script. But, I can wrap my head around building a yaml file. So, what yaml settings do I need to set to get ;buff to work?"
How cool would it be to say: "Oh, just call ;buff help in game. It'll show you what arguments you can call the script with, and also give you a list of the yaml settings it uses.".
Anyway, that's my thought.
An example of why having a help output that shows the yaml settings used in a script would be friendly: https://discord.com/channels/745675889622384681/745678330933805157/950163353500782632
After conversation with @rcuhljr @rpherbig @MahtraDR , I've got a general framework for doing this via a yaml-of-yamls file, and will endeavor to work on it. It's quite a bit of work, so I can't promise a timeframe, but I do think it would make a meaningful difference helping folks new to Lich, or even those current users who just would like to know what settings are utilized by a script so they can clean up their yaml.
Further, if we want this function not to get stale, we'll need to enforce via code review a fairly simple updating of the information when a script is created to use yaml settings, or new yaml settings are created to be used in existing scripts.
This approach, rather than restructuring things to enforce via code a new paradigm, means if I die next week, the whole thing can just be forgotten and the help readout turned off if desired.
Sample settings output via ;clean-leather help:
outfitting_belt: List of items that are stored on your outfitting belt - Will attempt to retrieve/store scraper from belt
crafting_container: Noun for base container for storing crafting related items - Scraper, preservatives and cleaned hides go here.
bankbot_enabled: The name of your bankbot if you use one - Coin withdrawal
crafting_items_in_container: List of items that are stored in your crafting bag - Will attempt to retrieve/store scraper from bag
hometown: Town you wish to live and work in - Used to look up Stock vendor to buy from and banking settings
outfitting_room: Room to perform outfitting training tasks in - Hide preserving done here.
engineering_room: Room to perform engineering training tasks in - Bone preserving done here.
