Command parsing
Command parsing
(apply-cmd cmd-fn cli raw-args)
(apply-cmd can-exec? cmd-fn cli raw-args)
Execute the provided cmd-fn, parsing its arguments as appropriate
with any annotated argtypes. See (defargtype). The optional first
arg can-exec?
is a (fn [cli cmd]) which will be called with the
cmd-fn if all the args were successfully parsed to make sure it can
be executed. can-exec?
is responsible for informing cli
why it
can't execute a command. If not provided, all commands can always
be executed.
Returns true
if we found a matching function arity, else nil
if
we did nothing
Execute the provided cmd-fn, parsing its arguments as appropriate with any annotated argtypes. See (defargtype). The optional first arg `can-exec?` is a (fn [cli cmd]) which will be called with the cmd-fn if all the args were successfully parsed to make sure it can be executed. `can-exec?` is responsible for informing `cli` why it can't execute a command. If not provided, all commands can always be executed. Returns `true` if we found a matching function arity, else `nil` if we did nothing
(defargtype arg-type doc argv & fn-body)
Declare an argument type. When an argument to a command is annotated with an arg type, the declared argtype handler will be called with the client who's calling, and the input string starting from with the argument.
The handler MUST return a tuple, where the first value is passed
to the command as the argument, and the second is the remaining,
unparsed input string (or nil if there's nothing else).
If the provided input cannot be successfully parsed, you may return
nil to indicate that the doc
text should be shown. If it was
successfully parsed but the input was invalid, a Throwable should
be returned as the first item in the tuple; the message will be
sent to the client.
Argtypes can be used for implementing common functionality; eg: ^:item could locate an item object at the right place and pass that as the arg (instead of just a string). If the item couldn't be located (or didn't exist), that's when a Throwable should be returned.
Such functionality will probably be left to client code (or plugin libraries), but there's lots of potential here. Note that we need the full input string, as we can't assume a single word will apply to a single arg. To continue with ^:item, for example, we might want to support "sword from/in chest" or "shoe on ground"-type phrases. We might also want something like :^rest to keep all the "rest" of the input as a string in a single argument.
You may also accept a parameter to the argtype, for further specification per-cmd. For example, if you want an item but only if it's on the ground you might annotate the cmd arg with ^{:item :on-ground}. The 'value' of the argtype annotation will be passed to your argtype as the third parameter (since it is less common, and you may wish to make it optional).
Most argtypes expect some input, but it is possible to create
argtypes that do not---for example, if you have a command to
'target' a creature, for example, you might want to inject that
target to commands implicitly, and handle the lack of a target
in the argtype. In this case, you should annotate the input
parameter as ^:nilable. Such 'pass-through' argtypes should typically
be after explicit argtypes in your command declarations.
Declare an argument type. When an argument to a command is annotated with an arg type, the declared argtype handler will be called with the client who's calling, and the input string starting from with the argument. The handler MUST return a tuple, where the first value is passed to the command as the argument, and the second is the remaining, unparsed input string (or nil if there's nothing else). If the provided input cannot be successfully parsed, you may return nil to indicate that the `doc` text should be shown. If it was successfully parsed but the input was invalid, a Throwable should be returned as the first item in the tuple; the message will be sent to the client. Argtypes can be used for implementing common functionality; eg: ^:item could locate an item object at the right place and pass that as the arg (instead of just a string). If the item couldn't be located (or didn't exist), that's when a Throwable should be returned. Such functionality will probably be left to client code (or plugin libraries), but there's lots of potential here. Note that we need the full input string, as we can't assume a single word will apply to a single arg. To continue with ^:item, for example, we might want to support "sword from/in chest" or "shoe on ground"-type phrases. We might also want something like :^rest to keep all the "rest" of the input as a string in a single argument. You may also accept a parameter to the argtype, for further specification per-cmd. For example, if you want an item but only if it's on the ground you might annotate the cmd arg with ^{:item :on-ground}. The 'value' of the argtype annotation will be passed to your argtype as the third parameter (since it is less common, and you may wish to make it optional). Most argtypes expect *some* input, but it is possible to create argtypes that do not---for example, if you have a command to 'target' a creature, for example, you might want to inject that target to commands implicitly, and handle the lack of a target in the argtype. In this case, you should annotate the `input` parameter as ^:nilable. Such 'pass-through' argtypes should typically be *after* explicit argtypes in your command declarations.
(extract-command raw-cmd)
Splits input into [cmd, REST], where cmd
is the text command
input, and REST is the rest of the arguments passed, if any
Splits input into [cmd, REST], where `cmd` is the text command input, and REST is the rest of the arguments passed, if any
(extract-word s)
ASSUMES the input is trim'd. Extract the first 'word', returning a sequence of the full match of that 'word' plus any whitespace after it, and the actual intended input. For quoted input, this means the first item will include the quotes and any trailing whitespace, and the second item will not
ASSUMES the input is trim'd. Extract the first 'word', returning a sequence of the full match of that 'word' plus any whitespace after it, and the actual intended input. For quoted input, this means the first item will include the quotes and any trailing whitespace, and the second item will not
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close