advanced ii: using user arguments

utilising user input
the more you use autoresponders, the more complicated your ideas will get. by using the user's arguments, you'll be able to allow users to provide context.
follow up to learning match modes from advanced i, if your match mode is not exact, (i.e. it is startswith, endswith, or includes), you will be able to use your arguments as a part of your response via the [$N] variable. 
this allows you to create commands where there are "user target" or for mimu to respond with the user's input.
the $ sign has nothing to do with money or currency. it is simply the symbol developers decided to use for reference of arguments!

the N letter refers to any number. you do not literally put [$N] in your response, you should put [$1], [$2], [$3]...
i'm still confused on why i would need this
let's take a simple !kiss command. you've changed it so the match mode is startswith so that mimu responds, like below:
.ar + !kiss | awwh, how cute, you kissed them!
.ar editmatchmode !kiss | startswith
without arguments
the "startswith" matchmode also responds with text after the trigger
as you can see, regardless of what the text / user input is after the trigger, the response is always static.
now, the problem is, wouldn't it be cool if it responded with "awwh, how cute, @iara#0001 kissed @pillow#6454!" instead?
this is why you might want to use user arguments, to obtain this result:
using user arguments as a part of your response
how do i use user arguments?
in order to refer to the extra words before or after the autoresponder trigger (depending on the type of matchmode you have), you have to replace N with the number of the word you'd like to use as a placeholder in the response.
for instance, [$1] would be the first word, [$2] would be the second word, [$3] would be the third word, and so on, so forth.
you can also chain multiple words together using the + sign.
for example, [$1+] would be the placeholder to show the first word and everything afterwards; and [$2+]would be the placeholder to show the second word and everything afterwards.
you can also do a range of arguments, for example, [$3-5] would be equivalent to [$3] [$4] [$5] , which returns the 3rd, 4th and 5th words.
a more visual example of what args are
exercise questions
let's do a quick exercise! you can jump to the exercise answers when you're done.
1.what's [$1] in the following ar?
creating the ar: .ar + welcome | let's welcome [$1]!
editing matchmode: .ar emm welcome | startswith
trigger: welcome iara to the server!
2.what's [$2+] in the following ar?
creating the ar: .ar + .bonk | you bonked [$1] with [$2+]!
editing matchmode: .ar emm .bonk | startswith
trigger: .bonk iara a fish i found from the sea
3.what's mimu's response to the following ar?
creating the ar: .ar + are cool | i see that you find [$1+] cool.
editing matchmode: .ar emm are cool | endswith
trigger: hoodies without the hood are cool
4.let's try something more abstract. what's mimu response to the following ar?
creating the ar: .ar + .guess | [$1] [$3-$5]
editing the matchmode: .ar emm .guess | startswith
trigger: .guess abc def ghi jkl mno pqr
some practical examples
below we've given you some simple yet easy to understand examples for you to start with.
commands
example input + output
.ar + .cuddle | you cuddled [$1+]
.ar emm .cuddle | startswith
input: .cuddle iara
response: you cuddled iara
.ar + are cute | i see, you find [$1+] cute!
.ar emm are cute | endswith
input: japanese things are cute
output: i see, you find japanese things cute!
.ar + .sleep | you made [$1] sleep by [$2+]
.ar editmatchmode .sleep | startswith
input: .sleep iara throwing pillows
output: you made iara sleep by throwing pillows
.ar + iara | {sendto:#logs} hey @iara#0001, {user_tag} mentioned your name in {channel}!
.ar editmatchmode iara | includes
input: 
lol iara is stupid >->
output (in #logs):
hey @iara#0001, user#tag mentioned your name in #channel!
if you use includes with the [$N] placeholder for arguments, all arguments will be chained together. for example, if your trigger is uwu and you type a b c uwu d e, then [$1] = a, [$2] = b, [$3] = c, [$4] = d, [$5] = e, and [$1+] = a b c d e.
using user arguments in user placeholders
in order to convert user placeholders to a "targeted" user (a user outside of that invoked), you can convert user placeholders found in the variable list to a function.
here's a quick example:
typically, {user_createdate} returns the user's invoked create date.
however, if you did {user_createdate:[$1]} , it returns the first argument user's create date.
this allows you to create information commands of other users. let's view a quick example here:
.ar + .membinfo | {requirearg:1|user} showing information of {user_tag:[$1]} . . . 
loading . . . !
> - server nick : {user_nick:[$1]}
> - joined serv : {user_joindate:[$1]}
> - joined disc : {user_createdate:[$1]}
> - server bal  : {user_balance:[$1]}
this is fantastic because this allows you to create commands and gain more information on other users other than the user invoked.
using user arguments in functions
as you may expect, you can also utilise these user argument placeholders in your functions, too!
some functions allow you to take the action on another specified user via an optional argument.
let's view a quick example of a command that allows you to manually verify people to enter your server:
.ar + .verify | {requirerole: Mods} {addrole: @verified | [$1+]} {user} has verified [$1+] !
.ar emm .verify | startswith
in this example, we're using the {addrole:} function. as seen in the documentation of the variable list, this accepts an optional "user" input after the pipe |, i.e. {addrole:[role]|<user>}.
hence, if someone with the role "Mods" runs .verify @user, [$1+] would be defined as the @user which would be filled in the function as {addrole:@verified | @user}.
note that [$1+] allows verification of users with spaces in their username, not verification of multiple users at once, as it accepts user#tag inputs too.
there are several functions that accept an optional "user" input! check out the function list for more information.
requiring specific arguments to be specific type of input
as you get more complex with using arguments, you may want the user to input specific types of data.
by using the {requirearg:} function, you can make mimu tell the user they might have done something wrong if they provide invalid arguments.
when will i need to use this?
let's go back to the kiss command we made earlier, but now we'll quickly add user inputs in, so we have this:
.ar editreply !kiss | awwh, how cute! {user} kissed [$1] !
however, users who didn't write this autoresponder might not know that they have to @mention the user they want to kiss (and hence they might just type !kiss  without other arguments.
this means arguments will be missing as [$1] isn't defined by the user input. 
by requiring arguments, you will prevent the user from sending incorrect data.
how do i use this?
the {requirearg:} variable accepts a number, with an optional type after the pipe | symbol.
ex. you want to make the user define [$1] (i.e. the first argument), then you can put {requirearg:1} in your autoresponder response area.
ex 2. if you'd like to make the user define [$1] (i.e. the first argument) but it has to be a user, then you can put {requirearg:1|user} in your autoresponder response area.
this also extends for other types. the current supported types are user, channel, color, role and number.
let's view an example.
.ar + !cuddle | {requirearg:1|user} {user} cuddled [$1] c:
.ar emm !cuddle | startswith
output when the user doesn't put in the right arguments!
when the user puts in the right arguments
this allows you to create even more complex commands that modify other people's balances, for example; or create commands where you can specify colors for the embed, or otherwise. check out the steal command example and embedsay command example.
exercise answers
1.iara
2.fish i found from the sea
3.i see you find hoodies without the hood cool.
4.abc ghi jkl mno
​
​⚠️ important reminder - READ!
it is advised that if you're going to use arguments, you should try to require argument types as much as possible, as mentioned in the require specific arguments to be a specific type of input section. 
this has better error messaging, which in turns allows the user to figure out what they did wrong.
it's always better to tell the user what they did wrong.
it's also strongly advised to embed your responses if you do not specify a specific type of input. i.e. {requirearg:1} only, or no {requirearg:} function variable anywhere.
this is because if a user inputs a role mention as their arguments, mimu will respond with such arguments in the response which may cause unwarranted role mentions if you have given mimu the permission to ping any role regardless of the mention toggle or the ADMINISTRATOR permission, like this:
if you've decided to give Mimu this permission.
OR this permission.
this prevents bad users in your server from cold-mentioning roles through these custom autoresponders and hence safeguards your server !
if the user decides to put roles in arguments, but you don't have any filtering
since embeds have role mentions suppressed, this will prevent people from using your AR in a malicious way.
use embeds to avoid people abusing your AR.
​
​