Update rzshell.md (#2150)
This commit is contained in:
Riccardo Schirone
GitHub
parent
86a7439519
commit
ae081043d9
1 changed files with 17 additions and 17 deletions
|
|
@ -37,15 +37,15 @@ overall CLI experience more consistent and reliable.
|
|||
Rizin uses a parser generated with
|
||||
[tree-sitter](https://tree-sitter.github.io/tree-sitter/), which allows you to
|
||||
write grammars in JavaScript. You can see our grammar
|
||||
[here](https://github.com/rizinorg/rizin/blob/dev/shlr/rizin-shell-parser/grammar.js).
|
||||
[here](https://github.com/rizinorg/rizin/blob/dev/subprojects/rizin-shell-parser/grammar.js).
|
||||
The parser recognizes the entire syntax of the rizin/radare2 shell language,
|
||||
like:
|
||||
|
||||
- [basic statements](https://github.com/rizinorg/rizin/blob/cde558e6e5788d0a6d544ab975b144ed59190676/shlr/rizin-shell-parser/grammar.js#L330): `<command-name> <arg1> <arg2> ... <argN>`
|
||||
- [temporary modifier statements](https://github.com/rizinorg/rizin/blob/cde558e6e5788d0a6d544ab975b144ed59190676/shlr/rizin-shell-parser/grammar.js#L124): `<statement> @ <address`, `<statement> @a:x86:32`, etc.
|
||||
- [iterator statements](https://github.com/rizinorg/rizin/blob/cde558e6e5788d0a6d544ab975b144ed59190676/shlr/rizin-shell-parser/grammar.js#L142): `<statement> @@ sym.*`, `<statement> @@=<addr1> <addr2> ... <addrN>`, etc.
|
||||
- [redirection and pipe statements](https://github.com/rizinorg/rizin/blob/cde558e6e5788d0a6d544ab975b144ed59190676/shlr/rizin-shell-parser/grammar.js#L177): `<statement> [fd|type]> <file>`, `<statement> | <program>`, etc.
|
||||
- [grep statements](https://github.com/rizinorg/rizin/blob/cde558e6e5788d0a6d544ab975b144ed59190676/shlr/rizin-shell-parser/grammar.js#L184): `<statement>~<grep-pattern>`
|
||||
- [basic statements](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/subprojects/rizin-shell-parser/grammar.js#L238): `<command-name> <arg1> <arg2> ... <argN>`
|
||||
- [temporary modifier statements](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/subprojects/rizin-shell-parser/grammar.js#L98): `<statement> @ <address`, `<statement> @a:x86:32`, etc.
|
||||
- [iterator statements](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/subprojects/rizin-shell-parser/grammar.js#L118): `<statement> @@ sym.*`, `<statement> @@=<addr1> <addr2> ... <addrN>`, etc.
|
||||
- [redirection and pipe statements](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/subprojects/rizin-shell-parser/grammar.js#L146): `<statement> [fd|type]> <file>`, `<statement> | <program>`, etc.
|
||||
- [grep statements](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/subprojects/rizin-shell-parser/grammar.js#L148): `<statement>~<grep-pattern>`
|
||||
- and many others
|
||||
|
||||
These patterns deal with the structure of the rizin/radare2 shell language, but
|
||||
|
|
@ -62,10 +62,10 @@ where a command could be registered together with all the information associated
|
|||
with it, like help messages, description, etc..
|
||||
|
||||
The module
|
||||
[`RzCmd`](https://github.com/rizinorg/rizin/blob/cde558e6e5788d0a6d544ab975b144ed59190676/librz/include/rz_cmd.h)
|
||||
[`RzCmd`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/include/rz_cmd.h)
|
||||
is the one in charge of dealing with commands. It provides API to register a new
|
||||
"command descriptor" (called
|
||||
[`RzCmdDesc`](https://github.com/rizinorg/rizin/blob/cde558e6e5788d0a6d544ab975b144ed59190676/librz/include/rz_cmd.h#L153)),
|
||||
[`RzCmdDesc`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/include/rz_cmd.h#L388)),
|
||||
deregister it, call the right command descriptor handler based on a list of
|
||||
command name + arguments, get the help of a command and potentially do many
|
||||
other things.
|
||||
|
|
@ -82,10 +82,10 @@ hashtable, using their names as keys.
|
|||
Let's make an example and suppose we want to add the `sky` command, which
|
||||
would find all occurrences of the word "sky" in a binary. The first thing to
|
||||
do is to see where `sky` command could be added by reading
|
||||
[`librz/core/cmd_descs/cmd_descs.yaml`](https://github.com/rizinorg/rizin/blob/6d901ca8a2ba674e268957fa8c24b3484bfc3626/librz/core/cmd_descs/cmd_descs.yaml).
|
||||
[`librz/core/cmd_descs/cmd_descs.yaml`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/core/cmd_descs/cmd_descs.yaml).
|
||||
`sky` is `s` command's subcommand and they are splitted and placed inside the .YAML
|
||||
file specified by the descriptor `subcommands` of the respective command. Since `sky`
|
||||
starts with an `s`, its subcommands would be in [`librz/core/cmd_descs/cmd_seek.yaml`](https://github.com/rizinorg/rizin/blob/6d901ca8a2ba674e268957fa8c24b3484bfc3626/librz/core/cmd_descs/cmd_seek.yaml).
|
||||
starts with an `s`, its subcommands would be in [`librz/core/cmd_descs/cmd_seek.yaml`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/core/cmd_descs/cmd_seek.yaml).
|
||||
That file respects the same tree structure used when executing rizin and seeing its help,
|
||||
so it should be simple to see where to place it. If we want to place it under the
|
||||
`s` sub-tree, we just need to define the descriptors for the command with at least
|
||||
|
|
@ -93,7 +93,7 @@ so it should be simple to see where to place it. If we want to place it under th
|
|||
|
||||
Now we need to choose what kind of command (`type` field in YAML) we want to
|
||||
have. We can see the various types in the
|
||||
[`RzCmdDescType`](https://github.com/rizinorg/rizin/blob/cde558e6e5788d0a6d544ab975b144ed59190676/librz/include/rz_cmd.h#L135-L151)
|
||||
[`RzCmdDescType`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/include/rz_cmd.h#L326-L380)
|
||||
enum, however let's assume we want a regular command, which is the default
|
||||
one, so no action is required in this regard.
|
||||
|
||||
|
|
@ -122,7 +122,7 @@ Below you can see how the code for adding the `sky` command would look like:
|
|||
```
|
||||
```C
|
||||
// cmd_seek.c (example, real place depends on the parent command)
|
||||
static RzCmdStatus sky_handler(RzCore *core, int argc, const char **argv) {
|
||||
RZ_IPI RzCmdStatus rz_sky_handler(RzCore *core, int argc, const char **argv) {
|
||||
// argc/argv is like in main(), i.e. argv[0] always contains the command name
|
||||
int limit = -1;
|
||||
if (argc > 1) {
|
||||
|
|
@ -143,7 +143,7 @@ handling the specified command.
|
|||
|
||||
If that doesn't work, please report the problem to us! However, you can still
|
||||
find the handler yourself by looking at the file
|
||||
[`librz/core/cmd_descs.yaml`](https://github.com/rizinorg/rizin/blob/9ce5003ca647cdfc181ac3c0f6206762ebb9e3e9/librz/core/cmd_descs.yaml).
|
||||
[`librz/core/cmd_descs/cmd_descs.yaml`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/core/cmd_descs/cmd_descs.yaml).
|
||||
By looking at the `cname` field of the command descriptor, you can see what is
|
||||
the name of the handler of the `x` command. If the `cname` is `hex` and the type
|
||||
is `RZ_CMD_DESC_TYPE_OLDINPUT`, then the handler will be named `rz_hex`. In all
|
||||
|
|
@ -157,8 +157,8 @@ Some examples:
|
|||
## How to improve the help messages of a command
|
||||
|
||||
Find the command in
|
||||
[`librz/core/cmd_descs.yaml`](https://github.com/rizinorg/rizin/blob/9ce5003ca647cdfc181ac3c0f6206762ebb9e3e9/librz/core/cmd_descs.yaml),
|
||||
then fix/improve the `summary` and/or `description` fields.
|
||||
[`librz/core/cmd_descs/cmd_descs.yaml`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/core/cmd_descs/cmd_descs.yaml),
|
||||
then fix/improve the `summary` and/or `description` fields. If the command cannot be directly found in `cmd_descs.yaml`, look for the other files in `librz/core/cmd_descs`.
|
||||
|
||||
## How to show examples of a command or additional details
|
||||
|
||||
|
|
@ -166,10 +166,10 @@ You may notice some commands like `env`, `%`, `*` and others have additional
|
|||
sections when you show the extensive help with e.g. `env??` (or `%??`, etc.).
|
||||
Those additional secions are called `details` and they can be specified,
|
||||
again, in the file
|
||||
[`librz/core/cmd_descs.yaml`](https://github.com/rizinorg/rizin/blob/9ce5003ca647cdfc181ac3c0f6206762ebb9e3e9/librz/core/cmd_descs.yaml).
|
||||
[`librz/core/cmd_descs/cmd_descs.yaml`](https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/core/cmd_descs/cmd_descs.yaml).
|
||||
The structure is explained at the beginning of the file and it can be seen in
|
||||
existing commands (e.g.
|
||||
https://github.com/rizinorg/rizin/blob/9ce5003ca647cdfc181ac3c0f6206762ebb9e3e9/librz/core/cmd_descs.yaml#L325
|
||||
https://github.com/rizinorg/rizin/blob/6f40dfe493f0caf9e0541e1ee83e3d8012b5750f/librz/core/cmd_descs/cmd_shell.yaml#L18
|
||||
). The result, looks something like:
|
||||
```
|
||||
[0x00000000]> %??
|
||||
|
|
|
|||
Loading…
Reference in a new issue