reorganize module

_archive/rhai_engine/rhaibook/engine/debugging/break-points.md

@@ -0,0 +1,54 @@
+Break-Points
+============
+
+{{#include ../../links.md}}
+
+A _break-point_ **always** stops the current evaluation and calls the [debugging][debugger]
+callback.
+
+A break-point is represented by the `debugger::BreakPoint` type, which is an `enum` with
+the following variants.
+
+| `BreakPoint` variant                     | Not available under | Description                                                                                                                                 |
+| ---------------------------------------- | :-----------------: | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AtPosition { source, pos, enabled }`    |   [`no_position`]   | breaks at the specified position in the specified source (empty if none);<br/>if `pos` is at beginning of line, breaks anywhere on the line |
+| `AtFunctionName { name, enabled }`       |                     | breaks when a function matching the specified name is called (can be [operator])                                                            |
+| `AtFunctionCall { name, args, enabled }` |                     | breaks when a function matching the specified name (can be [operator]) and the specified number of arguments is called                      |
+| `AtProperty { name, enabled }`           |    [`no_object`]    | breaks at the specified property access                                                                                                     |
+
+
+Access Break-Points
+-------------------
+
+The following [`debugger::Debugger`] methods allow access to break-points for manipulation.
+
+| Method             |      Return type       | Description                                       |
+| ------------------ | :--------------------: | ------------------------------------------------- |
+| `break_points`     |    `&[BreakPoint]`     | returns a slice of all `BreakPoint`'s             |
+| `break_points_mut` | `&mut Vec<BreakPoint>` | returns a mutable reference to all `BreakPoint`'s |
+
+
+Example
+-------
+
+```rust
+use rhai::debugger::*;
+
+let debugger = &mut context.global_runtime_state_mut().debugger_mut();
+
+// Get number of break-points.
+let num_break_points = debugger.break_points().len();
+
+// Add a new break-point on calls to 'foo(_, _, _)'
+debugger.break_points_mut().push(
+    BreakPoint::AtFunctionCall { name: "foo".into(), args: 3 }
+);
+
+// Display all break-points
+for bp in debugger.break_points().iter() {
+    println!("{bp}");
+}
+
+// Clear all break-points
+debugger.break_points_mut().clear();
+```