ruby_jard 0.2.3 → 0.3.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (91) hide show
  1. checksums.yaml +4 -4
  2. data/.github/FUNDING.yml +3 -0
  3. data/.github/workflows/documentation.yml +65 -0
  4. data/.github/workflows/{ruby.yml → rspec.yml} +22 -11
  5. data/.rubocop.yml +6 -0
  6. data/CHANGELOG.md +15 -3
  7. data/Gemfile +9 -2
  8. data/README.md +52 -332
  9. data/benchmark/path_filter_bench.rb +58 -0
  10. data/lib/ruby_jard.rb +15 -5
  11. data/lib/ruby_jard/color_schemes.rb +9 -1
  12. data/lib/ruby_jard/color_schemes/256_color_scheme.rb +21 -35
  13. data/lib/ruby_jard/color_schemes/256_light_color_scheme.rb +23 -35
  14. data/lib/ruby_jard/color_schemes/deep_space_color_scheme.rb +20 -34
  15. data/lib/ruby_jard/color_schemes/gruvbox_color_scheme.rb +20 -34
  16. data/lib/ruby_jard/color_schemes/one_half_dark_color_scheme.rb +20 -34
  17. data/lib/ruby_jard/color_schemes/one_half_light_color_scheme.rb +21 -34
  18. data/lib/ruby_jard/commands/color_helpers.rb +32 -0
  19. data/lib/ruby_jard/commands/frame_command.rb +2 -2
  20. data/lib/ruby_jard/commands/jard/color_scheme_command.rb +25 -3
  21. data/lib/ruby_jard/commands/jard/filter_command.rb +136 -0
  22. data/lib/ruby_jard/commands/jard/output_command.rb +13 -5
  23. data/lib/ruby_jard/commands/jard_command.rb +3 -1
  24. data/lib/ruby_jard/config.rb +9 -2
  25. data/lib/ruby_jard/decorators/array_decorator.rb +79 -0
  26. data/lib/ruby_jard/decorators/attributes_decorator.rb +172 -0
  27. data/lib/ruby_jard/decorators/color_decorator.rb +12 -5
  28. data/lib/ruby_jard/decorators/hash_decorator.rb +74 -0
  29. data/lib/ruby_jard/decorators/inspection_decorator.rb +91 -58
  30. data/lib/ruby_jard/decorators/object_decorator.rb +122 -0
  31. data/lib/ruby_jard/decorators/path_decorator.rb +55 -72
  32. data/lib/ruby_jard/decorators/rails_decorator.rb +194 -0
  33. data/lib/ruby_jard/decorators/string_decorator.rb +41 -0
  34. data/lib/ruby_jard/decorators/struct_decorator.rb +79 -0
  35. data/lib/ruby_jard/frame.rb +23 -10
  36. data/lib/ruby_jard/keys.rb +1 -0
  37. data/lib/ruby_jard/layouts/narrow_horizontal_layout.rb +4 -0
  38. data/lib/ruby_jard/layouts/tiny_layout.rb +4 -0
  39. data/lib/ruby_jard/pager.rb +21 -5
  40. data/lib/ruby_jard/path_classifier.rb +133 -0
  41. data/lib/ruby_jard/path_filter.rb +125 -0
  42. data/lib/ruby_jard/reflection.rb +97 -0
  43. data/lib/ruby_jard/repl_processor.rb +71 -38
  44. data/lib/ruby_jard/row_renderer.rb +5 -3
  45. data/lib/ruby_jard/screen.rb +2 -2
  46. data/lib/ruby_jard/screen_manager.rb +13 -36
  47. data/lib/ruby_jard/screen_renderer.rb +1 -1
  48. data/lib/ruby_jard/screens/backtrace_screen.rb +55 -39
  49. data/lib/ruby_jard/screens/menu_screen.rb +30 -30
  50. data/lib/ruby_jard/screens/source_screen.rb +46 -62
  51. data/lib/ruby_jard/screens/threads_screen.rb +59 -72
  52. data/lib/ruby_jard/screens/variables_screen.rb +168 -124
  53. data/lib/ruby_jard/session.rb +120 -16
  54. data/lib/ruby_jard/thread_info.rb +69 -0
  55. data/lib/ruby_jard/version.rb +1 -1
  56. data/ruby_jard.gemspec +3 -1
  57. metadata +20 -39
  58. data/.travis.yml +0 -6
  59. data/CNAME +0 -1
  60. data/_config.yml +0 -1
  61. data/docs/_config.yml +0 -8
  62. data/docs/color_schemes/256-light.png +0 -0
  63. data/docs/color_schemes/256.png +0 -0
  64. data/docs/color_schemes/deep-space.png +0 -0
  65. data/docs/color_schemes/gruvbox.png +0 -0
  66. data/docs/color_schemes/one-half-dark.png +0 -0
  67. data/docs/color_schemes/one-half-light.png +0 -0
  68. data/docs/demo.png +0 -0
  69. data/docs/guide-ui.png +0 -0
  70. data/docs/index.md +0 -238
  71. data/docs/logo.jpg +0 -0
  72. data/docs/screen-backtrace.png +0 -0
  73. data/docs/screen-repl.png +0 -0
  74. data/docs/screen-source.png +0 -0
  75. data/docs/screen-threads.png +0 -0
  76. data/docs/screen-variables.png +0 -0
  77. data/images/bg_hr.png +0 -0
  78. data/images/blacktocat.png +0 -0
  79. data/images/body-bg.jpg +0 -0
  80. data/images/download-button.png +0 -0
  81. data/images/github-button.png +0 -0
  82. data/images/header-bg.jpg +0 -0
  83. data/images/highlight-bg.jpg +0 -0
  84. data/images/icon_download.png +0 -0
  85. data/images/sidebar-bg.jpg +0 -0
  86. data/images/sprite_download.png +0 -0
  87. data/javascripts/main.js +0 -1
  88. data/stylesheets/github-light.css +0 -130
  89. data/stylesheets/normalize.css +0 -424
  90. data/stylesheets/print.css +0 -228
  91. data/stylesheets/stylesheet.css +0 -245
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 61f5671a65db3b0ee5292d98b0310ca43668a52582bc88db04a377d26715bfff
4
- data.tar.gz: 60c444c9870f556569077b9022e145602c693178f1b0c1ec02a6783a75a99796
3
+ metadata.gz: e5a458f6dbabbed48b8cb322d6ac9a3c52e664309b1a1bfde1e90f91921092b6
4
+ data.tar.gz: e54b2ddcebc06c72fd78b4cc34dc99aba60eb1ba7d20d6815e0c4d88c39d2076
5
5
  SHA512:
6
- metadata.gz: c149e4a6482b4792279a956a2f51287c6af95361213b13a63d69101925f71bf7719b04bae4a9ee9cb4526ab1a86bba9c546a290241acd1d9baee0fe2a218108e
7
- data.tar.gz: 4825219c8b45ba878d31fe2159e45d0e89a73ae44d2f3acabee15e58b16901bb37adf14aeb6d833d2dafab9b8cbf3a7115ad334d07c22f0ebd8586644bd5f5f1
6
+ metadata.gz: '079110d831bc4729fe3c5ac9a33726d396cd4df50b889890f5b7e602d7e8d6717cf6e48b6038c4e653e2de2ae2ae4d44da6a0790d6f63be67e573475d59a0980'
7
+ data.tar.gz: fe4711967e8d0f3a81962038b1d7d40b319934f323ed6d942bde0f918125971e76bc49a73c603347c4e6be07618bf3950236ef0e868b07c587a2d1583cf7cbe6
@@ -0,0 +1,3 @@
1
+ # These are supported funding model platforms
2
+
3
+ ko_fi: nguyenquangminh0711
@@ -0,0 +1,65 @@
1
+ name: documentation
2
+
3
+ on:
4
+ pull_request:
5
+ branches: [master]
6
+ push:
7
+ branches: [master]
8
+
9
+ jobs:
10
+ checks:
11
+ if: github.event_name != 'push'
12
+ runs-on: ubuntu-latest
13
+ steps:
14
+ - uses: actions/checkout@v1
15
+ - uses: actions/setup-node@v1
16
+ with:
17
+ node-version: '12.x'
18
+ - name: Test Build
19
+ run: |
20
+ cd website
21
+ if [ -e yarn.lock ]; then
22
+ yarn install --frozen-lockfile
23
+ elif [ -e package-lock.json ]; then
24
+ npm ci
25
+ else
26
+ npm i
27
+ fi
28
+ npm run build
29
+ gh-release:
30
+ if: github.event_name != 'pull_request'
31
+ runs-on: ubuntu-latest
32
+ steps:
33
+ - uses: actions/checkout@v1
34
+ - uses: actions/setup-node@v1
35
+ with:
36
+ node-version: '12.x'
37
+ - name: Add key to allow access to repository
38
+ env:
39
+ SSH_AUTH_SOCK: /tmp/ssh_agent.sock
40
+ run: |
41
+ mkdir -p ~/.ssh
42
+ ssh-keyscan github.com >> ~/.ssh/known_hosts
43
+ echo "${{ secrets.GH_PAGES_DEPLOY }}" > ~/.ssh/id_rsa
44
+ chmod 600 ~/.ssh/id_rsa
45
+ cat <<EOT >> ~/.ssh/config
46
+ Host github.com
47
+ HostName github.com
48
+ IdentityFile ~/.ssh/id_rsa
49
+ EOT
50
+ - name: Release to GitHub Pages
51
+ env:
52
+ USE_SSH: true
53
+ GIT_USER: git
54
+ run: |
55
+ git config --global user.email "actions@gihub.com"
56
+ git config --global user.name "gh-actions"
57
+ cd website
58
+ if [ -e yarn.lock ]; then
59
+ yarn install --frozen-lockfile
60
+ elif [ -e package-lock.json ]; then
61
+ npm ci
62
+ else
63
+ npm i
64
+ fi
65
+ npx docusaurus deploy
@@ -1,4 +1,4 @@
1
- name: Ruby
1
+ name: Rspec
2
2
 
3
3
  on:
4
4
  push:
@@ -16,18 +16,15 @@ jobs:
16
16
  uses: ruby/setup-ruby@v1
17
17
  with:
18
18
  ruby-version: 2.5
19
- - name: Install tmux
20
- run: sudo apt install -y tmux
21
- - name: Start tmux
22
- run: tmux start-server
23
19
  - name: Install dependencies
24
20
  run: bundle install
25
21
  - name: Checking offenses
26
22
  run: bundle exec rubocop
27
23
  test-ubuntu:
28
24
  strategy:
25
+ fail-fast: false
29
26
  matrix:
30
- ruby: [2.5, 2.6, 2.7.1]
27
+ ruby: [2.5, 2.6, 2.7.1, head]
31
28
  runs-on: ubuntu-latest
32
29
  steps:
33
30
  - uses: actions/checkout@v2
@@ -39,14 +36,19 @@ jobs:
39
36
  run: sudo apt install -y tmux
40
37
  - name: Start tmux
41
38
  run: tmux start-server
39
+ - name: Start dummy tmux session
40
+ run: tmux new-session -t dummy -d
41
+ - name: Wait for tmux
42
+ run: ruby spec/wait_for_tmux.rb
42
43
  - name: Install dependencies
43
44
  run: bundle install
44
45
  - name: Run tests
45
- run: bundle exec rspec
46
+ run: bundle exec parallel_rspec spec/
46
47
  test-macos:
47
48
  strategy:
49
+ fail-fast: false
48
50
  matrix:
49
- ruby: [2.5, 2.6, 2.7.1]
51
+ ruby: [2.5, 2.6, 2.7.1, head]
50
52
  runs-on: macos-latest
51
53
  steps:
52
54
  - uses: actions/checkout@v2
@@ -58,13 +60,18 @@ jobs:
58
60
  run: brew install tmux
59
61
  - name: Start tmux
60
62
  run: tmux start-server
63
+ - name: start dummy tmux session
64
+ run: tmux new-session -t dummy -d
65
+ - name: Wait for tmux
66
+ run: ruby spec/wait_for_tmux.rb
61
67
  - name: Install dependencies
62
68
  run: bundle install
63
69
  - name: Run tests
64
- run: bundle exec rspec
65
- test-previous-byebug:
70
+ run: bundle exec parallel_rspec -n 2 spec/
71
+ test-byebug:
66
72
  runs-on: ubuntu-latest
67
73
  strategy:
74
+ fail-fast: false
68
75
  matrix:
69
76
  byebug: [9.1.0, 10.0.2]
70
77
  env:
@@ -79,7 +86,11 @@ jobs:
79
86
  run: sudo apt install -y tmux
80
87
  - name: Start tmux
81
88
  run: tmux start-server
89
+ - name: start dummy tmux session
90
+ run: tmux new-session -t dummy -d
91
+ - name: Wait for tmux
92
+ run: ruby spec/wait_for_tmux.rb
82
93
  - name: Install dependencies
83
94
  run: bundle install
84
95
  - name: Run tests
85
- run: bundle exec rspec
96
+ run: bundle exec parallel_rspec spec/
@@ -79,6 +79,10 @@ Style/Alias:
79
79
  EnforcedStyle: prefer_alias_method
80
80
  Style/EvalWithLocation:
81
81
  Enabled: false
82
+ Style/NilComparison:
83
+ Enabled: false
84
+ Style/NonNilCheck:
85
+ Enabled: false
82
86
 
83
87
  RSpec/MultipleExpectations:
84
88
  Enabled: false
@@ -88,6 +92,8 @@ RSpec/DescribeClass:
88
92
  Enabled: false
89
93
  RSpec/NestedGroups:
90
94
  Max: 4
95
+ RSpec/MultipleMemoizedHelpers:
96
+ Enabled: false
91
97
 
92
98
  AllCops:
93
99
  TargetRubyVersion: 2.5
@@ -1,6 +1,18 @@
1
1
  # Changelog
2
2
 
3
- ## [0.2.3 - Alpha 4]
3
+ ## [0.3.0 - Beta 1]
4
+ - Filter feature
5
+ - New variable screen look and feel
6
+ - Improve website and documentation page.
7
+ - Improve color-scheme command
8
+ - Use Thread sequential label instead of Thread's object id
9
+ - Complete testing infrastructure.
10
+ - Fix multiple performance issues.
11
+
12
+ ### Bug fixes
13
+ - Solve program output performance degrade ([#21](https://github.com/nguyenquangminh0711/ruby_jard/pull/21))
14
+
15
+ ## [0.2.3 - Final Alpha]
4
16
 
5
17
  ### UX/UI
6
18
  - Add `gruvbox`, `256-light`, `one-half-dark`, and `one-half-light` color scheme
@@ -31,7 +43,7 @@
31
43
  - Lazily load screen data
32
44
  - Support byebug >= 9.1.0
33
45
 
34
- ## [0.2.2 - Alpha 3]
46
+ ## [0.2.2 - Alpha 4]
35
47
 
36
48
  ### UX/UI
37
49
  - Add `wehereami` as an alias for `list` command
@@ -90,7 +102,7 @@
90
102
  - Implement ReplProxy to wrap around Pry instance.
91
103
  - Utility to debug and benchmark.
92
104
 
93
- ## [0.1.0 - Alpha] - Alpha initial version
105
+ ## [0.1.0 - Alpha 1] - Alpha initial version
94
106
  **Release date**: July 1st 2020
95
107
 
96
108
  - Default Terminal UI, in which the layout and display are responsive to support different screen size.
data/Gemfile CHANGED
@@ -4,12 +4,19 @@ source 'http://rubygems.org'
4
4
 
5
5
  gemspec
6
6
 
7
+ if Gem.path.all? { |path| Dir[File.join(path, 'gems/jard_merge_sort*')].empty? }
8
+ puts '[HACK] Install jard_merge_sort'
9
+ puts `gem install ./spec/examples/jard_merge_sort/jard_merge_sort-0.1.0.gem`
10
+ end
11
+
7
12
  gem 'byebug', '~> 11.1.0'
13
+ gem 'jard_merge_sort', require: false
8
14
  gem 'rake', '~> 12.0'
9
15
  gem 'rspec', '~> 3.0'
10
- gem 'rubocop', '~> 0.88'
11
- gem 'rubocop-rspec', require: false
16
+ gem 'rubocop', '~> 0.89.1'
17
+ gem 'rubocop-rspec', '~> 1.43.1', require: false
12
18
 
13
19
  group :test do
20
+ gem 'parallel_tests'
14
21
  gem 'rspec-retry'
15
22
  end
data/README.md CHANGED
@@ -1,378 +1,98 @@
1
- ![Ruby Jard](./docs/logo.jpg)
1
+ [<img src="./website/static/img/logo/logo-full.png" width="400" />](https://rubyjard.org/)
2
2
 
3
- 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.
3
+ ![Gem](https://img.shields.io/gem/v/ruby_jard?label=Latest%20version&style=for-the-badge) ![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/nguyenquangminh0711/ruby_jard/Rspec/master?label=Build&style=for-the-badge) ![GitHub stars](https://img.shields.io/github/stars/nguyenquangminh0711/ruby_jard?style=for-the-badge) [![From Vietnam with <3](https://raw.githubusercontent.com/webuild-community/badge/master/svg/love-modern.svg)](https://webuild.community)
4
4
 
5
- [![Ruby Jard Demo](./docs/demo.png)](https://asciinema.org/a/350233)
5
+ Ruby Jard provides a rich Terminal UI that visualizes everything your need, navigates your program with pleasure, stops at matter places only, reduces manual and mental efforts. You can now focus on real debugging.
6
6
 
7
- *[(Click for demo video)](https://asciinema.org/a/350233)*
7
+ Please visit [https://rubyjard.org/](https://rubyjard.org/) for more information.
8
8
 
9
- Ruby Jard's core is [Byebug](https://github.com/deivid-rodriguez/byebug), an awesome de factor debugger for Ruby. Therefore, Ruby Jard supports most of Byebug's functionalities.
9
+ [![RubyJard Demo](https://asciinema.org/a/358874.svg)](https://asciinema.org/a/358874)
10
10
 
11
- ## Getting Started
11
+ *[(Click for demo video)](https://asciinema.org/a/358874)*
12
12
 
13
- **Warning**: Ruby Jard is still under heavy development. Bugs and weird behaviors are expected. If you see one, please don't hesitate to open an issue. I'll try my best to fix.
13
+ **Note**: Ruby Jard is still under heavy development. Bugs and weird behaviors are expected. If you see one, please don't hesitate to [open an issue](https://github.com/nguyenquangminh0711/ruby_jard/issues). I'll try my best to fix.
14
14
 
15
- Add `ruby_jard` to your Gemfile, recommend to put it in test or development environment.
15
+ ## Install Ruby Jard
16
16
 
17
- ``` ruby
18
- gem 'ruby_jard'
19
- ```
17
+ ### Bundler
20
18
 
21
- Add magic method `jard` before the line you want to debug, just like `byebug`
19
+ Add one of those lines into your Gemfile. **Note**: Ruby Jard is discouraged to use on production environment.
22
20
 
23
21
  ```ruby
24
- def test_method
25
- a = 1
26
- b = 2
27
- jard # Debugger will stop here
28
- c = a + b
29
- end
30
- ```
31
-
32
- ## Screens
33
-
34
- When Jard attaches at any line of code, the main tile-style UI shows up. By default, there are 5 areas on the UI that you'll be interested.
35
-
36
- ### Source panel
37
-
38
- <img src="./docs/screen-source.png" alt="Source screen" />
39
-
40
- This panel shows the current line of code that your program is stopping, and surrounding related lines. The number of lines shown in this panel depends on your current terminal height, but never less than 5.
41
-
42
- Ruby Jard supports any file extensions that your program runs into, especially `.rb`, `.erb`, `.haml` files. Other file types may encounter minor syntax highlighting issues.
43
-
44
- Ruby Jard also supports inspecting gems and libraries, if you are interested.
45
-
46
- ### Backtrace panel
47
-
48
- <img src="./docs/screen-backtrace.png" alt="Screen backtrace"/>
49
-
50
- This panel describes the current backtrace of the current thread your program is stopping. Each line of this panel describes the current Frame. What is frame and backtrace by the way? Let's step back a little bit at how Ruby executes your code. Internally, Ruby uses an interpreter to read and execute your code, line by line (technically, YARD instructions, but let's go with a simple version). When it meets a chunk of code that needs to open a new scope, like method calls or inline-block call, the interpreter creates a new structure to store the current context so that it can link to the next scope and go back later. This data structure is call Frame. The interpreter pushes frame into a stack, called backtrace (or stack trace, or call stack, whatever), and continues to execute your code. Each thread has a separate backtrace. To understand deeply, you may be interested in this wonderful slide: [Grow and Shrink - Dynamically Extending the Ruby VM Stack](https://www.slideshare.net/KeitaSugiyama1/grow-and-shrink-dynamically-extending-the-ruby-vm-stack).
51
-
52
- Overall, the whole backtrace panel lets you know where you are stopping at, the trace of how your program is running. When combining with other tools and other panels, you will be surprised by how much information the bugger can help you when you encounter your bugs.
53
-
54
- Each frame includes the following information:
55
-
56
- - Frame ID: incremental, can be used to jump to an arbitrary frame with frame command.
57
- - Current location label: a class name and method name of the method covers its frame. If there is a `[c]` prefix in front of a class name, it means that the method is provided by Ruby, implemented in C, and impossible to peek.
58
- - Current physical location: exact file name and line number. If a frame is allocated in a gem, the physical location shows a gem name and version only. For example: `RSpec::Core::Hooks::HookCollections in run in rspec-core (3.9.2)`.
59
-
60
- ### Variable panel
61
-
62
- <img src="./docs/screen-variables.png" alt="Variables screen"/>
63
-
64
- The variable panel lets you explore all the local variables, instance variables, and constants in the current display context. Each variable is described by:
65
-
66
- - Inline indicator: the beginning dot (`•`) implies a variable that appears in the current line.
67
- - Variable type: allow you to know the type of a variable at a single glance. Only built-in types, such as `int`, `flt`, `hash`, `bool`, `rng`, are supported. Instances of any classes will be noted as `var`.
68
- - Size of variable: the size of collection-like variables. Current Jard version supports 3 types:
69
- - Hash: this field shows the number of keys
70
- - Array: this field shows the number of items
71
- - String: this field shows the number of character (fetched from`String#size` method)
72
- - Variable inspection: the content of the variable. The current Jard version generates this field by calling `#inspect`. **Known issue**: this accidentally triggers materializing method of objects, such as `ActiveRecord::Relation`. Future Jard version gonna fix this by a new safe generator.
73
-
74
- This panel interacts well with backtrace panel and backtrace-exploring commands such as (`up`, `down`, `frame`, etc.) to inspect relative variables at each frame layer in the program. A common use case is to recall the parameter values you forgot when digging too deep into a method call.
75
-
76
- By default, the variables are sorted by the following criteria:
77
-
78
- - Pinned variables (coming soon)
79
- - Current context (self)
80
- - Local variables
81
- - Instance variables
82
- - Constants
83
- - Global variables (coming soon)
84
-
85
- ### Thread panel
86
-
87
- <img src="./docs/screen-threads.png" alt="Screen threads" />
88
-
89
- Show all the threads running at the moment. This panel is useful when you are working with a complicated multi-threaded environment like web server, or background jobs.
90
-
91
- ### Repl panel
92
-
93
- <img src="./docs/screen-repl.png" alt="Screen repl" />
94
-
95
- 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.
96
-
97
- ## Flow Commands
98
-
99
- ### List
100
-
101
- **Repl command**: `list`
102
-
103
- **Key binding:** F5
104
-
105
- **Alias**: `l`, `whereami`
106
-
107
- Refresh the whole terminal UI. This command doesn't move you to other steps, nor change any data in your session. It is useful (or the only way) to get back the beautiful UI if you type too much in the REPL console.
108
-
109
- ### Step
110
-
111
- **Repl command**: `step`
112
-
113
- **Key binding**: F7
114
-
115
- **Alias**: `s`
116
-
117
- **Examples:**
118
-
119
- ```
120
- step # Step once
121
- step 3 # Step 3 times
122
- ```
123
-
124
- 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.
125
-
126
- ### Step out
127
-
128
- **Repl command**: `step-out`
129
-
130
- **Key binding**: Shift + F7
131
-
132
- **Alias**: `so`
133
-
134
- **Examples:**
135
-
136
- ```
137
- step-out # Step out once
138
- step-out 3 # Step out 3 times
22
+ gem 'ruby_jard', group: :development
139
23
  ```
140
24
 
141
- 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.
142
-
143
- 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.
144
-
145
- ### Next
146
-
147
- **Repl command**: `next`
148
-
149
- **Key binding**: F8
150
-
151
- **Alias**: `n`
152
-
153
- **Examples:**
154
-
155
- ```
156
- next # Next instruction
157
- next 3 # Next 3 next instructions
158
- ```
159
-
160
- 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.
161
-
162
- ### Continue
163
-
164
- **Repl command**: `continue`
165
-
166
- **Key binding**: F9
167
-
168
- **Alias**: `c`
169
-
170
- Continue the execution of your program to the end, or stop at the first dynamic break point or `jard` attachment command. One common confusion is that long-running ruby processes, such as web server or background jobs, won't stop, and may be used to debug the next request without restarting. If you want to end everything and just exit the process, let's use `exit`.
171
-
172
- ### Up
173
-
174
- **Repl command**: `up`
175
-
176
- **Key binding**: F6
177
-
178
- **Examples:**
179
-
180
- ```
181
- up # Move to upper frame
182
- up 3 # Move to upper 3 frames
25
+ ```bash
26
+ ❯ bundle install
183
27
  ```
184
28
 
185
- 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.
186
-
187
- 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.
188
-
189
- One note is that you cannot explore a frame in c.
29
+ If you would like to use Ruby Jard to debug a test, you can add to group test too.
190
30
 
191
- ### Down
192
31
 
193
- **Repl command**: `down`
194
-
195
- **Key binding**: Shift+F6
196
-
197
- **Examples:**
198
-
199
- ```
200
- down # Move to lower frame
201
- down 3 # Move to lower 3 frames
32
+ ```ruby
33
+ gem 'ruby_jard', group: [:development, :test]
202
34
  ```
203
35
 
204
- Explore the lower frame. See `up` command for more information.
205
-
206
- ### Frame
207
-
208
- **Repl command**: `frame [-h] [frame_id]`
209
-
210
- **Key binding:** None
36
+ If you would like to use edged developing version of Ruby Jard:
211
37
 
212
- **Examples:**
213
-
214
- ```
215
- frame 0 # Jump to frame 0
216
- frame 7 # Jump to frame 7
38
+ ```ruby
39
+ gem 'ruby_jard', group: :development, git: 'https://github.com/nguyenquangminh0711/ruby_jard'
217
40
  ```
218
41
 
219
- Explore a particular frame with id `<frame_id>`. It's faster than `up` and `down`. See `up` command for more information.
220
-
221
- ## Control commands
222
-
223
- 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.
42
+ ### Ruby Gem
224
43
 
225
- ### Color scheme
44
+ If you want to install Ruby Jard independently from bundler:
226
45
 
227
- **Repl command**: `jard color-scheme [-l|-h] [frame_id]`
228
-
229
- **Key binding:** None
230
-
231
- **Examples:**
232
-
233
- ```
234
- jard color-scheme -l # List all available color schemes
235
- # Output:
236
- # jard >>
237
- # 256
238
- # deep-space
239
- # gruvbox
240
- jard color-scheme deep-space # Switch to color scheme deep-space
46
+ ```bash
47
+ gem install ruby_jard
241
48
  ```
242
49
 
243
- List all available color schemes, or switch to a particular color scheme at runtime.
244
-
245
- ### Show
246
-
247
- **Repl command**: `jard show [screen]`
248
-
249
- **Key binding:** None
250
-
251
- **Examples:**
50
+ If you want to install a specific version published on [Ruby gems](https://rubygems.org/gems/ruby_jard):
252
51
 
52
+ ```bash
53
+ gem install ruby_jard@0.2.3
253
54
  ```
254
- jard show variables
255
- jard show threads
256
- ```
257
-
258
- Show a particular screen on the current interface.
259
-
260
- ### Hide
261
-
262
- **Repl command**: `jard hide [screen]`
263
55
 
264
- **Key binding:** None
56
+ ## Run your program with Ruby Jard
265
57
 
266
- **Examples:**
58
+ ![How to run your program with Ruby Jard](./website/static/img/getting_started/how-to-use.gif)
267
59
 
268
- ```
269
- jard hide variables
270
- jard hide threads
271
- ```
272
-
273
- Hide a particular screen from the current interface.
60
+ To use Ruby Jard, you just need to put `jard` magic method **before** any places you want to stop. Jard supports stopping at anywhere, including top level binding, instance methods, class methods, string evaluation, or even inside a class declaration.
274
61
 
275
- ### Output
62
+ ```ruby
63
+ def test_method(input)
64
+ a = 1
65
+ b = 2
66
+ jard # Debugger will stop here
67
+ c = a + b + input
68
+ end
276
69
 
277
- **Repl command**: `jard output`
70
+ class TestClass
71
+ jard # Yes, it can stop here too
72
+ @dirty_class_method = 1 + 1
278
73
 
279
- **Key binding:** None
74
+ def test_method
75
+ jard
76
+ end
280
77
 
281
- **Examples:**
78
+ def self.test_class_method
79
+ jard
80
+ end
81
+ end
282
82
 
83
+ jard
84
+ test_method(5)
283
85
  ```
284
- jard output
285
- ```
286
-
287
- 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.
288
-
289
- ## Color schemes
290
-
291
- | Name | Screenshots |
292
- | ------------------------------------------------------------ | ------------------------------------------------------------ |
293
- | `256` <br />Default theme, 256 basic colors, supported by all terminals | <img src="./docs/color_schemes/256.png" style="max-width: 400px;" /> |
294
- | `256-light` | <img src="./docs/color_schemes/256-light.png" style="max-width: 400px;" /> |
295
- | `deep-space` | <img src="./docs/color_schemes/deep-space.png" style="max-width: 400px;" /> |
296
- | `gruvbox` | <img src="./docs/color_schemes/gruvbox.png" style="max-width: 400px;" /> |
297
- | `one-half-dark` | <img src="./docs/color_schemes/one-half-dark.png" style="max-width: 400px;" /> |
298
- | `one-half-light` | <img src="./docs/color_schemes/one-half-light.png" style="max-width: 400px;" /> |
299
-
300
-
301
-
302
- ## Configuration
303
-
304
- Ruby Jard supports customization via pre-loaded configuration files. You can configure Jard both globally, and per-project.
305
86
 
306
- - The global configuration file is located at `~/.jardrc`.
307
- - 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.
87
+ Afterward, run your program, just like normally. If your program meets `jard` execution break point, it gonna stop, show the UI, and let you debug.
308
88
 
309
- There are some supported configurations:
310
-
311
- | Name | Description | Default |
312
- | ------------------- | ------------------------------------------------------------ | ------- |
313
- | `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` |
314
- | `alias_to_debugger` | Use `debugger` instead of `jard` when debugging. | `false` |
315
-
316
- This is a complete example of a configuration file:
89
+ In case you meet error `undefined local variable or method jard`, please require ruby_jard manually at initializing scripts. If you use Ruby Jard with famous frameworks, ruby_jard will be loaded by default
317
90
 
318
91
  ```ruby
319
- config.color_scheme = "deep-space"
320
- config.alias_to_debugger = true
92
+ require 'ruby_jard'
321
93
  ```
322
94
 
323
- ## Roadmap
324
-
325
- ### [Done] Version 0.1.0: Proof of concept
326
-
327
- This version is a bootstrap to see whether my idea works or not, in term of technical possibility and user usability. Luckily, everything works now, and I receive possible feedback from friends and peers.
328
-
329
- ### [Done] Version 0.2.0: UI completeness
330
-
331
- The bootstrap version is just a series of ugly prints on stdout. It's frustrated as many things can be broken, wrong drawing, text overlapping, etc. This version is to fix those issues, and provide a foundation for more complicated drawing.
332
-
333
- ### Version 0.3.0: Complete the workflow
334
-
335
- This version focuses on making Jard usable for daily activities of any developer. In other words, this version is to become a complete replacement for Byebug (sorry :pray:).
336
-
337
- - Dynamic breakpoints.
338
- - Watch expressions.
339
- - Pin variables.
340
- - Program's STDOUT panel.
341
- - Post moterm.
342
- - Trace variable changes.
343
- - Multi-threaded debugging.
344
- - Fulfill options for existing commands.
345
- - Add more commands to control workflow.
346
- - etc.
347
-
348
- ### Version 0.4.0: User satisfaction
349
-
350
- Ruby Jard now serves well for all debugging use case. But it becomes floated, hard to use, and maybe just not "click" for the user. This version focuses on improve userability, stability, bugs, tweak small details. So that, after this version, Ruby Jard is just pleasant to use.
351
-
352
- - Support different screen sizes.
353
- - Minimal layout configuration.
354
- - Allow customizations (keyboard shortcut for example).
355
- - Rebuild variable inspection to optimize for each data type, especially nested complicated structure.
356
- - Collapsible and expandale variable inspection.
357
- - Windows, viewport, scrolling, etc.
358
- - Navigate between panels.
359
- - Build a buffer system to reduce interaction with STDOUT, and eventually improve drawing latency.
360
-
361
- ### Version 0.5.0: Integration
362
-
363
- Accept or not, not everyone uses vim, or even terminal. Even in the terminal, I just want to provide minimal layout customizations, as I don't want to rebuild Tmux. Therefore, integration with other powerful systems to extend use cases, adapt different work flow and preferences is the focus on this version. I'm not sure about the ultimate solution, but at my limited knowledge now, [Debugger Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) looks promising.
364
-
365
- - Prepare the infrastructure for DAP protocol.
366
- - Separate and split the panels into possible isolated processes, connect them together with DAP.
367
- - Fully layout configurations and integrate with Tmux.
368
- - Integrate with Vim 8+/Neovim via Terminal mode.
369
- - Integrate with Visual Studio Code via DAP.
370
- - Integrate with Emacs via dap mode.
371
- - Encrypted remote debugging.
372
-
373
- ### Further future
374
-
375
- I won't stop until 0.5.0 version, even Jard doesn't have any users. However, as soon as it reaches 0.5.0, and serves my interest well, I don't have much things in mind now. The future is uncertain. Dreaming is good. Making dreams come true is hard, and time-consuming. Hope I can reach that future.
95
+ Please visit [https://rubyjard.org/](https://rubyjard.org/) for more information.
376
96
 
377
97
  ## Contributing
378
98