README.md in ruby_jard-0.2.2 vs README.md in ruby_jard-0.2.3

- old
+ new

@@ -1,8 +1,8 @@ ![Ruby Jard](./docs/logo.jpg) -Jard stands for Just Another Ruby Debugger, aims to provide a better experience while debugging Ruby. Ruby Jard provides modular visual interfaces to show relevant information about your debugging program. Those interfaces are optimized for usability, and highly friendly to developers, especially new comers. They help you reduce the commands you need to type, the mental efforts wasted trying to navigate and grab the information you need. As a result, you can now focus more on the debug flow. +Jard stands for Just Another Ruby Debugger, aims to provide a better experience while debugging Ruby. Ruby Jard provides modular visual interfaces to show relevant information about your debugging program. Those interfaces are optimized for usability, and highly friendly to developers, especially new comers. They help you reduce the commands you need to type, the mental efforts wasted trying to navigate and grab the information you need. As a result, you can now focus more on the debug flow. [![Ruby Jard Demo](./docs/demo.png)](https://asciinema.org/a/350233) *[(Click for demo video)](https://asciinema.org/a/350233)* @@ -92,11 +92,11 @@ <img src="./docs/screen-repl.png" alt="Screen repl" /> An interactive Repl for you to interact with your program, inspect values, update values, or control the debug flow as you want. The heart of Jard's repl is [Pry](https://github.com/pry/pry), a masterpiece gem. When you type a command, Jard parses, and does corresponding actions if what you type matches supported command. Otherwise, they are evaluated as Ruby code. -## Commands +## Flow Commands ### List **Repl command**: `list` @@ -112,32 +112,53 @@ **Key binding**: F7 **Alias**: `s` +**Examples:** + +``` +step # Step once +step 3 # Step 3 times +``` + Detect and step into a method call or block in the current line. If there isn't anything to step in, the program continues to next line. In case there are multiple methods on the same line, Jard hornors Ruby's execution order. ### Step out **Repl command**: `step-out` **Key binding**: Shift + F7 **Alias**: `so` -The opposite of step out. This command is used to finish the execution of current frame, and jump to the next line of upper frame. In other words, this command is equivalent to the sequence `up` and `next`. If the neighbor frame already finishes, it continues with even higher frame. +**Examples:** +``` +step-out # Step out once +step-out 3 # Step out 3 times +``` + +The opposite of step. This command is used to finish the execution of current frame, and jump to the next line of upper frame. In other words, this command is equivalent to the sequence `up` and `next`. If the neighbor frame already finishes, it continues with even higher frame. + This command is useful when you loose your interest in frame, and want to quickly go up again. One example is that you accidentally step into a longgggg loop with nothing useful. Another example is that you step into the library source code and don't really care what it does underlying. ### Next **Repl command**: `next` **Key binding**: F8 **Alias**: `n` +**Examples:** + +``` +next # Next instruction +next 3 # Next 3 next instructions +``` + Continue to the next line in the current frame, by pass any steppable method call or blocks in the mid way unless they contains dynamic breakpoint or any `jard` attachment command. If the current frame already reaches the end, it continues to the next line of upper frame and so on. ### Continue **Repl command**: `continue` @@ -152,10 +173,17 @@ **Repl command**: `up` **Key binding**: F6 +**Examples:** + +``` +up # Move to upper frame +up 3 # Move to upper 3 frames +``` + Explore the upper frame. When you use this command, all associated displaying screens will be updated accordingly, but your program current position is still at the latest frame. This command is mostly used to explore, and view the trace, input parameters, or how your program stops at the current position. When use this command, you should have a glance at Variable panel, and Source panel to see the variables at destination frame. You can combine with `next` or `step` to perform powerful execution redirection at the destination frame. Let's look at an example. You are debugging a chain of 10 rack middlewares, you go deep into the #9 middleware, found something, then want to go back to #5 middleware. It's pretty boring and frustrated to just use `next` or `step-out` and hope it eventually goes back. Now use `up` for some times (or `frame`, described below) to go to your desired frame, and use `next` there. Tada, it's magical, just like teleport. One note is that you cannot explore a frame in c. @@ -164,28 +192,112 @@ **Repl command**: `down` **Key binding**: Shift+F6 +**Examples:** + +``` +down # Move to lower frame +down 3 # Move to lower 3 frames +``` + Explore the lower frame. See `up` command for more information. ### Frame -**Repl command**: `frame <frame_id>` +**Repl command**: `frame [-h] [frame_id]` **Key binding:** None -**Examples**:`frame 10` +**Examples:** +``` +frame 0 # Jump to frame 0 +frame 7 # Jump to frame 7 +``` + Explore a particular frame with id `<frame_id>`. It's faster than `up` and `down`. See `up` command for more information. +## Control commands + +All control commands start with`jard` namespaces. This class of commands are used to control the visual interfaces, configuration, or specific operations provided by Jard. + +### Color scheme + +**Repl command**: `jard color-scheme [-l|-h] [frame_id]` + +**Key binding:** None + +**Examples:** + +``` +jard color-scheme -l # List all available color schemes +# Output: +# jard >> +# 256 +# deep-space +# gruvbox +jard color-scheme deep-space # Switch to color scheme deep-space +``` + +List all available color schemes, or switch to a particular color scheme at runtime. + +### Show + +**Repl command**: `jard show [screen]` + +**Key binding:** None + +**Examples:** + +``` +jard show variables +jard show threads +``` + +Show a particular screen on the current interface. + +### Hide + +**Repl command**: `jard hide [screen]` + +**Key binding:** None + +**Examples:** + +``` +jard hide variables +jard hide threads +``` + +Hide a particular screen from the current interface. + +### Output + +**Repl command**: `jard output` + +**Key binding:** None + +**Examples:** + +``` +jard output +``` + +Show all the program output in a pager, allowing navigation, searching (powered by GNU Less). Note that the output are only captured only after Jard already started. All the previous output could not be captured. + ## Color schemes | Name | Screenshots | | ------------------------------------------------------------ | ------------------------------------------------------------ | | `256` <br />Default theme, 256 basic colors, supported by all terminals | <img src="./docs/color_schemes/256.png" style="max-width: 400px;" /> | +| `256-light` | <img src="./docs/color_schemes/256-light.png" style="max-width: 400px;" /> | | `deep-space` | <img src="./docs/color_schemes/deep-space.png" style="max-width: 400px;" /> | +| `gruvbox` | <img src="./docs/color_schemes/gruvbox.png" style="max-width: 400px;" /> | +| `one-half-dark` | <img src="./docs/color_schemes/one-half-dark.png" style="max-width: 400px;" /> | +| `one-half-light` | <img src="./docs/color_schemes/one-half-light.png" style="max-width: 400px;" /> | ## Configuration @@ -194,17 +306,19 @@ - The global configuration file is located at `~/.jardrc`. - The project configuration file is located at `.jardrc` in working directory when you start Ruby Jard. Per-project ones will override, and merge with global ones. There are some supported configurations: -| Name | Description | Default | -| -------------- | ------------------------------------------------------------ | ------- | -| `color_scheme` | Choose your favorite color scheme. The list of color schemes can be looke up in [Color schemes session](#color-schemes), or from `color-scheme -l` command in REPL. | `256` | +| Name | Description | Default | +| ------------------- | ------------------------------------------------------------ | ------- | +| `color_scheme` | Choose your favorite color scheme. The list of color schemes can be looke up in [Color schemes session](#color-schemes), or from `jard color-scheme -l` command in REPL. | `256` | +| `alias_to_debugger` | Use `debugger` instead of `jard` when debugging. | `false` | This is a complete example of a configuration file: ```ruby config.color_scheme = "deep-space" +config.alias_to_debugger = true ``` ## Roadmap ### [Done] Version 0.1.0: Proof of concept