diff --git a/pr-450/404.html b/pr-450/404.html deleted file mode 100644 index be3dbe1ad..000000000 --- a/pr-450/404.html +++ /dev/null @@ -1,2175 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- -

404 - Not found

- -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/about_us/index.html b/pr-450/about_us/index.html deleted file mode 100644 index a40fabf5c..000000000 --- a/pr-450/about_us/index.html +++ /dev/null @@ -1,2294 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - About Us - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - Skip to content - - -
-
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - - - - - - - - - - - - - -
-
- - - - - - - - - - - - - - - - - - - - -

About Us

-

UBC Sailbot is an engineering design team at The University of British Columbia -that designs, constructs, and tests autonomous sailboats. We have 3 technical sub-teams: Mechanical, Electrical, and Software.

-

This repository, sailbot_workspace, contains all the -code, infrastructure, and documentation for the project we are currently working on, Polaris.

-

To learn more about what the UBC Sailbot Software Team does, read our Team Posting. -If you are a UBC student interested in joining, you can apply here.

- - - - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/assets/images/favicon.png b/pr-450/assets/images/favicon.png deleted file mode 100644 index b695121e0..000000000 Binary files a/pr-450/assets/images/favicon.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/branch_comparison.png b/pr-450/assets/images/github/workflow/branch_comparison.png deleted file mode 100644 index 195b1af37..000000000 Binary files a/pr-450/assets/images/github/workflow/branch_comparison.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/create_pr.png b/pr-450/assets/images/github/workflow/create_pr.png deleted file mode 100644 index 1008ab276..000000000 Binary files a/pr-450/assets/images/github/workflow/create_pr.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/gh_assignee.png b/pr-450/assets/images/github/workflow/gh_assignee.png deleted file mode 100644 index bfdd58ba1..000000000 Binary files a/pr-450/assets/images/github/workflow/gh_assignee.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/gh_labels.png b/pr-450/assets/images/github/workflow/gh_labels.png deleted file mode 100644 index f5c11ca40..000000000 Binary files a/pr-450/assets/images/github/workflow/gh_labels.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/gh_milestone.png b/pr-450/assets/images/github/workflow/gh_milestone.png deleted file mode 100644 index 839c39ba0..000000000 Binary files a/pr-450/assets/images/github/workflow/gh_milestone.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/gh_project.png b/pr-450/assets/images/github/workflow/gh_project.png deleted file mode 100644 index 9697b2a0b..000000000 Binary files a/pr-450/assets/images/github/workflow/gh_project.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/issue_list.png b/pr-450/assets/images/github/workflow/issue_list.png deleted file mode 100644 index ec20ee5af..000000000 Binary files a/pr-450/assets/images/github/workflow/issue_list.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/issue_tab.png b/pr-450/assets/images/github/workflow/issue_tab.png deleted file mode 100644 index 5ccf9bf7d..000000000 Binary files a/pr-450/assets/images/github/workflow/issue_tab.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/issue_template_list.png b/pr-450/assets/images/github/workflow/issue_template_list.png deleted file mode 100644 index bf490d9f6..000000000 Binary files a/pr-450/assets/images/github/workflow/issue_template_list.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/merge_conflict.png b/pr-450/assets/images/github/workflow/merge_conflict.png deleted file mode 100644 index b86119352..000000000 Binary files a/pr-450/assets/images/github/workflow/merge_conflict.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/merge_conflict_file.png b/pr-450/assets/images/github/workflow/merge_conflict_file.png deleted file mode 100644 index f1d5bcffc..000000000 Binary files a/pr-450/assets/images/github/workflow/merge_conflict_file.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/new_feature_template.png b/pr-450/assets/images/github/workflow/new_feature_template.png deleted file mode 100644 index 6592fea02..000000000 Binary files a/pr-450/assets/images/github/workflow/new_feature_template.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/pr_comment_snippet.png b/pr-450/assets/images/github/workflow/pr_comment_snippet.png deleted file mode 100644 index 2570dc990..000000000 Binary files a/pr-450/assets/images/github/workflow/pr_comment_snippet.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/pr_example.png b/pr-450/assets/images/github/workflow/pr_example.png deleted file mode 100644 index 54c2de973..000000000 Binary files a/pr-450/assets/images/github/workflow/pr_example.png and /dev/null differ diff --git a/pr-450/assets/images/github/workflow/pr_merge.png b/pr-450/assets/images/github/workflow/pr_merge.png deleted file mode 100644 index 8bf4047bb..000000000 Binary files a/pr-450/assets/images/github/workflow/pr_merge.png and /dev/null differ diff --git a/pr-450/assets/images/markdown/issue_md_rendered.png b/pr-450/assets/images/markdown/issue_md_rendered.png deleted file mode 100644 index bf7b4ec92..000000000 Binary files a/pr-450/assets/images/markdown/issue_md_rendered.png and /dev/null differ diff --git a/pr-450/assets/images/markdown/issue_md_text.png b/pr-450/assets/images/markdown/issue_md_text.png deleted file mode 100644 index 34f2a2228..000000000 Binary files a/pr-450/assets/images/markdown/issue_md_text.png and /dev/null differ diff --git a/pr-450/assets/images/sailbot_workspace/workflow/sailbot_bug.png b/pr-450/assets/images/sailbot_workspace/workflow/sailbot_bug.png deleted file mode 100644 index a84a83a03..000000000 Binary files a/pr-450/assets/images/sailbot_workspace/workflow/sailbot_bug.png and /dev/null differ diff --git a/pr-450/assets/images/sailbot_workspace/workflow/vscode_testing_tab.png b/pr-450/assets/images/sailbot_workspace/workflow/vscode_testing_tab.png deleted file mode 100644 index e5add7d90..000000000 Binary files a/pr-450/assets/images/sailbot_workspace/workflow/vscode_testing_tab.png and /dev/null differ diff --git a/pr-450/assets/images/sailing/bear_off.jpg b/pr-450/assets/images/sailing/bear_off.jpg deleted file mode 100644 index 7d89c8d08..000000000 Binary files a/pr-450/assets/images/sailing/bear_off.jpg and /dev/null differ diff --git a/pr-450/assets/images/sailing/bear_off_then_gybe.jpg b/pr-450/assets/images/sailing/bear_off_then_gybe.jpg deleted file mode 100644 index 1e06084fb..000000000 Binary files a/pr-450/assets/images/sailing/bear_off_then_gybe.jpg and /dev/null differ diff --git a/pr-450/assets/images/sailing/bearing_vs_heading.jpg b/pr-450/assets/images/sailing/bearing_vs_heading.jpg deleted file mode 100644 index 9c1274f3a..000000000 Binary files a/pr-450/assets/images/sailing/bearing_vs_heading.jpg and /dev/null differ diff --git a/pr-450/assets/images/sailing/gybe.jpg b/pr-450/assets/images/sailing/gybe.jpg deleted file mode 100644 index a672586a8..000000000 Binary files a/pr-450/assets/images/sailing/gybe.jpg and /dev/null differ diff --git a/pr-450/assets/images/sailing/head_up.jpg b/pr-450/assets/images/sailing/head_up.jpg deleted file mode 100644 index 2d7a9abac..000000000 Binary files a/pr-450/assets/images/sailing/head_up.jpg and /dev/null differ diff --git a/pr-450/assets/images/sailing/parts_of_boat.jpg b/pr-450/assets/images/sailing/parts_of_boat.jpg deleted file mode 100644 index 0341922de..000000000 Binary files a/pr-450/assets/images/sailing/parts_of_boat.jpg and /dev/null differ diff --git a/pr-450/assets/images/sailing/points_of_sail.jpg b/pr-450/assets/images/sailing/points_of_sail.jpg deleted file mode 100644 index 5277bdafc..000000000 Binary files a/pr-450/assets/images/sailing/points_of_sail.jpg and /dev/null differ diff --git a/pr-450/assets/images/sailing/regions_of_hull.jpg b/pr-450/assets/images/sailing/regions_of_hull.jpg deleted file mode 100644 index 0bc7f48c9..000000000 Binary files a/pr-450/assets/images/sailing/regions_of_hull.jpg and /dev/null differ diff --git a/pr-450/assets/images/sailing/tack.jpg b/pr-450/assets/images/sailing/tack.jpg deleted file mode 100644 index aa43aa5ac..000000000 Binary files a/pr-450/assets/images/sailing/tack.jpg and /dev/null differ diff --git a/pr-450/assets/images/sailing/tack_other_meaning.jpg b/pr-450/assets/images/sailing/tack_other_meaning.jpg deleted file mode 100644 index f484c73af..000000000 Binary files a/pr-450/assets/images/sailing/tack_other_meaning.jpg and /dev/null differ diff --git a/pr-450/assets/images/sailing/track_made_good.jpg b/pr-450/assets/images/sailing/track_made_good.jpg deleted file mode 100644 index eb91a9bed..000000000 Binary files a/pr-450/assets/images/sailing/track_made_good.jpg and /dev/null differ diff --git a/pr-450/assets/images/sailing/types_of_turn.jpg b/pr-450/assets/images/sailing/types_of_turn.jpg deleted file mode 100644 index 38be9dda1..000000000 Binary files a/pr-450/assets/images/sailing/types_of_turn.jpg and /dev/null differ diff --git a/pr-450/assets/images/sailing/upwind_downwind_sailing.jpg b/pr-450/assets/images/sailing/upwind_downwind_sailing.jpg deleted file mode 100644 index 1e2e045be..000000000 Binary files a/pr-450/assets/images/sailing/upwind_downwind_sailing.jpg and /dev/null differ diff --git a/pr-450/assets/images/sailing/wind_types.jpg b/pr-450/assets/images/sailing/wind_types.jpg deleted file mode 100644 index 8c7c23d4b..000000000 Binary files a/pr-450/assets/images/sailing/wind_types.jpg and /dev/null differ diff --git a/pr-450/assets/images/social/about_us.png b/pr-450/assets/images/social/about_us.png deleted file mode 100644 index 7824b7257..000000000 Binary files a/pr-450/assets/images/social/about_us.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/boat_simulator/overview.png b/pr-450/assets/images/social/current/boat_simulator/overview.png deleted file mode 100644 index a8d7c3cf0..000000000 Binary files a/pr-450/assets/images/social/current/boat_simulator/overview.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/controller/overview.png b/pr-450/assets/images/social/current/controller/overview.png deleted file mode 100644 index a8d7c3cf0..000000000 Binary files a/pr-450/assets/images/social/current/controller/overview.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/custom_interfaces/overview.png b/pr-450/assets/images/social/current/custom_interfaces/overview.png deleted file mode 100644 index a8d7c3cf0..000000000 Binary files a/pr-450/assets/images/social/current/custom_interfaces/overview.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/local_pathfinding/overview.png b/pr-450/assets/images/social/current/local_pathfinding/overview.png deleted file mode 100644 index a8d7c3cf0..000000000 Binary files a/pr-450/assets/images/social/current/local_pathfinding/overview.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/network_systems/overview.png b/pr-450/assets/images/social/current/network_systems/overview.png deleted file mode 100644 index a8d7c3cf0..000000000 Binary files a/pr-450/assets/images/social/current/network_systems/overview.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/overview.png b/pr-450/assets/images/social/current/overview.png deleted file mode 100644 index a8d7c3cf0..000000000 Binary files a/pr-450/assets/images/social/current/overview.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/sailbot_workspace/overview.png b/pr-450/assets/images/social/current/sailbot_workspace/overview.png deleted file mode 100644 index a8d7c3cf0..000000000 Binary files a/pr-450/assets/images/social/current/sailbot_workspace/overview.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/sailbot_workspace/reference/deployment.png b/pr-450/assets/images/social/current/sailbot_workspace/reference/deployment.png deleted file mode 100644 index 5f3536914..000000000 Binary files a/pr-450/assets/images/social/current/sailbot_workspace/reference/deployment.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/sailbot_workspace/reference/docker_images.png b/pr-450/assets/images/social/current/sailbot_workspace/reference/docker_images.png deleted file mode 100644 index a5f059997..000000000 Binary files a/pr-450/assets/images/social/current/sailbot_workspace/reference/docker_images.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/sailbot_workspace/reference/docs_site.png b/pr-450/assets/images/social/current/sailbot_workspace/reference/docs_site.png deleted file mode 100644 index 625011637..000000000 Binary files a/pr-450/assets/images/social/current/sailbot_workspace/reference/docs_site.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/sailbot_workspace/reference/launch_files.png b/pr-450/assets/images/social/current/sailbot_workspace/reference/launch_files.png deleted file mode 100644 index 6a9ab396a..000000000 Binary files a/pr-450/assets/images/social/current/sailbot_workspace/reference/launch_files.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/sailbot_workspace/reference/notebooks.png b/pr-450/assets/images/social/current/sailbot_workspace/reference/notebooks.png deleted file mode 100644 index 228d1ee0a..000000000 Binary files a/pr-450/assets/images/social/current/sailbot_workspace/reference/notebooks.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/sailbot_workspace/reference/parameters.png b/pr-450/assets/images/social/current/sailbot_workspace/reference/parameters.png deleted file mode 100644 index 46725f3da..000000000 Binary files a/pr-450/assets/images/social/current/sailbot_workspace/reference/parameters.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/sailbot_workspace/scripts.png b/pr-450/assets/images/social/current/sailbot_workspace/scripts.png deleted file mode 100644 index 399f6ff88..000000000 Binary files a/pr-450/assets/images/social/current/sailbot_workspace/scripts.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/sailbot_workspace/usage/help.png b/pr-450/assets/images/social/current/sailbot_workspace/usage/help.png deleted file mode 100644 index 5022af51e..000000000 Binary files a/pr-450/assets/images/social/current/sailbot_workspace/usage/help.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/sailbot_workspace/usage/how_to.png b/pr-450/assets/images/social/current/sailbot_workspace/usage/how_to.png deleted file mode 100644 index 56f907413..000000000 Binary files a/pr-450/assets/images/social/current/sailbot_workspace/usage/how_to.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/sailbot_workspace/usage/setup.png b/pr-450/assets/images/social/current/sailbot_workspace/usage/setup.png deleted file mode 100644 index 439413669..000000000 Binary files a/pr-450/assets/images/social/current/sailbot_workspace/usage/setup.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/sailbot_workspace/usage/workflow.png b/pr-450/assets/images/social/current/sailbot_workspace/usage/workflow.png deleted file mode 100644 index cc47722d1..000000000 Binary files a/pr-450/assets/images/social/current/sailbot_workspace/usage/workflow.png and /dev/null differ diff --git a/pr-450/assets/images/social/current/website/overview.png b/pr-450/assets/images/social/current/website/overview.png deleted file mode 100644 index a8d7c3cf0..000000000 Binary files a/pr-450/assets/images/social/current/website/overview.png and /dev/null differ diff --git a/pr-450/assets/images/social/index.png b/pr-450/assets/images/social/index.png deleted file mode 100644 index c2d95da18..000000000 Binary files a/pr-450/assets/images/social/index.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/cpp/differences.png b/pr-450/assets/images/social/reference/cpp/differences.png deleted file mode 100644 index 6c79b7a69..000000000 Binary files a/pr-450/assets/images/social/reference/cpp/differences.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/cpp/start.png b/pr-450/assets/images/social/reference/cpp/start.png deleted file mode 100644 index 43152572d..000000000 Binary files a/pr-450/assets/images/social/reference/cpp/start.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/cpp/tools.png b/pr-450/assets/images/social/reference/cpp/tools.png deleted file mode 100644 index 7654e7419..000000000 Binary files a/pr-450/assets/images/social/reference/cpp/tools.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/docker.png b/pr-450/assets/images/social/reference/docker.png deleted file mode 100644 index e316addff..000000000 Binary files a/pr-450/assets/images/social/reference/docker.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/github/advanced_git.png b/pr-450/assets/images/social/reference/github/advanced_git.png deleted file mode 100644 index b0e3bdb62..000000000 Binary files a/pr-450/assets/images/social/reference/github/advanced_git.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/github/github_actions.png b/pr-450/assets/images/social/reference/github/github_actions.png deleted file mode 100644 index dcda369f6..000000000 Binary files a/pr-450/assets/images/social/reference/github/github_actions.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/github/workflow/branches.png b/pr-450/assets/images/social/reference/github/workflow/branches.png deleted file mode 100644 index 3574a683f..000000000 Binary files a/pr-450/assets/images/social/reference/github/workflow/branches.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/github/workflow/issues.png b/pr-450/assets/images/social/reference/github/workflow/issues.png deleted file mode 100644 index 925257349..000000000 Binary files a/pr-450/assets/images/social/reference/github/workflow/issues.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/github/workflow/overview.png b/pr-450/assets/images/social/reference/github/workflow/overview.png deleted file mode 100644 index a8d7c3cf0..000000000 Binary files a/pr-450/assets/images/social/reference/github/workflow/overview.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/github/workflow/pr.png b/pr-450/assets/images/social/reference/github/workflow/pr.png deleted file mode 100644 index 586330e68..000000000 Binary files a/pr-450/assets/images/social/reference/github/workflow/pr.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/linux_commands.png b/pr-450/assets/images/social/reference/linux_commands.png deleted file mode 100644 index 531d19e40..000000000 Binary files a/pr-450/assets/images/social/reference/linux_commands.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/markdown.png b/pr-450/assets/images/social/reference/markdown.png deleted file mode 100644 index ee0c0ac68..000000000 Binary files a/pr-450/assets/images/social/reference/markdown.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/python/conventions.png b/pr-450/assets/images/social/reference/python/conventions.png deleted file mode 100644 index 9280696c9..000000000 Binary files a/pr-450/assets/images/social/reference/python/conventions.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/python/start.png b/pr-450/assets/images/social/reference/python/start.png deleted file mode 100644 index 43152572d..000000000 Binary files a/pr-450/assets/images/social/reference/python/start.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/python/virtual-environments.png b/pr-450/assets/images/social/reference/python/virtual-environments.png deleted file mode 100644 index 6931bae1e..000000000 Binary files a/pr-450/assets/images/social/reference/python/virtual-environments.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/ros.png b/pr-450/assets/images/social/reference/ros.png deleted file mode 100644 index b8b9c4fe8..000000000 Binary files a/pr-450/assets/images/social/reference/ros.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/sailing/ais_terms.png b/pr-450/assets/images/social/reference/sailing/ais_terms.png deleted file mode 100644 index adef98d64..000000000 Binary files a/pr-450/assets/images/social/reference/sailing/ais_terms.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/sailing/boat_parts.png b/pr-450/assets/images/social/reference/sailing/boat_parts.png deleted file mode 100644 index 32fbb1a1b..000000000 Binary files a/pr-450/assets/images/social/reference/sailing/boat_parts.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/sailing/miscellaneous.png b/pr-450/assets/images/social/reference/sailing/miscellaneous.png deleted file mode 100644 index 6d7ac1db6..000000000 Binary files a/pr-450/assets/images/social/reference/sailing/miscellaneous.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/sailing/overview.png b/pr-450/assets/images/social/reference/sailing/overview.png deleted file mode 100644 index a8d7c3cf0..000000000 Binary files a/pr-450/assets/images/social/reference/sailing/overview.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/sailing/points_of_sail.png b/pr-450/assets/images/social/reference/sailing/points_of_sail.png deleted file mode 100644 index 1ae600160..000000000 Binary files a/pr-450/assets/images/social/reference/sailing/points_of_sail.png and /dev/null differ diff --git a/pr-450/assets/images/social/reference/sailing/turning.png b/pr-450/assets/images/social/reference/sailing/turning.png deleted file mode 100644 index f99fe705e..000000000 Binary files a/pr-450/assets/images/social/reference/sailing/turning.png and /dev/null differ diff --git a/pr-450/assets/javascripts/bundle.83f73b43.min.js b/pr-450/assets/javascripts/bundle.83f73b43.min.js deleted file mode 100644 index 43d8b70f6..000000000 --- a/pr-450/assets/javascripts/bundle.83f73b43.min.js +++ /dev/null @@ -1,16 +0,0 @@ -"use strict";(()=>{var Wi=Object.create;var gr=Object.defineProperty;var Di=Object.getOwnPropertyDescriptor;var Vi=Object.getOwnPropertyNames,Vt=Object.getOwnPropertySymbols,Ni=Object.getPrototypeOf,yr=Object.prototype.hasOwnProperty,ao=Object.prototype.propertyIsEnumerable;var io=(e,t,r)=>t in e?gr(e,t,{enumerable:!0,configurable:!0,writable:!0,value:r}):e[t]=r,$=(e,t)=>{for(var r in t||(t={}))yr.call(t,r)&&io(e,r,t[r]);if(Vt)for(var r of Vt(t))ao.call(t,r)&&io(e,r,t[r]);return e};var so=(e,t)=>{var r={};for(var o in e)yr.call(e,o)&&t.indexOf(o)<0&&(r[o]=e[o]);if(e!=null&&Vt)for(var o of Vt(e))t.indexOf(o)<0&&ao.call(e,o)&&(r[o]=e[o]);return r};var xr=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var zi=(e,t,r,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of Vi(t))!yr.call(e,n)&&n!==r&&gr(e,n,{get:()=>t[n],enumerable:!(o=Di(t,n))||o.enumerable});return e};var Mt=(e,t,r)=>(r=e!=null?Wi(Ni(e)):{},zi(t||!e||!e.__esModule?gr(r,"default",{value:e,enumerable:!0}):r,e));var co=(e,t,r)=>new Promise((o,n)=>{var i=p=>{try{s(r.next(p))}catch(c){n(c)}},a=p=>{try{s(r.throw(p))}catch(c){n(c)}},s=p=>p.done?o(p.value):Promise.resolve(p.value).then(i,a);s((r=r.apply(e,t)).next())});var lo=xr((Er,po)=>{(function(e,t){typeof Er=="object"&&typeof po!="undefined"?t():typeof define=="function"&&define.amd?define(t):t()})(Er,function(){"use strict";function e(r){var o=!0,n=!1,i=null,a={text:!0,search:!0,url:!0,tel:!0,email:!0,password:!0,number:!0,date:!0,month:!0,week:!0,time:!0,datetime:!0,"datetime-local":!0};function s(k){return!!(k&&k!==document&&k.nodeName!=="HTML"&&k.nodeName!=="BODY"&&"classList"in k&&"contains"in k.classList)}function p(k){var ft=k.type,qe=k.tagName;return!!(qe==="INPUT"&&a[ft]&&!k.readOnly||qe==="TEXTAREA"&&!k.readOnly||k.isContentEditable)}function c(k){k.classList.contains("focus-visible")||(k.classList.add("focus-visible"),k.setAttribute("data-focus-visible-added",""))}function l(k){k.hasAttribute("data-focus-visible-added")&&(k.classList.remove("focus-visible"),k.removeAttribute("data-focus-visible-added"))}function f(k){k.metaKey||k.altKey||k.ctrlKey||(s(r.activeElement)&&c(r.activeElement),o=!0)}function u(k){o=!1}function d(k){s(k.target)&&(o||p(k.target))&&c(k.target)}function y(k){s(k.target)&&(k.target.classList.contains("focus-visible")||k.target.hasAttribute("data-focus-visible-added"))&&(n=!0,window.clearTimeout(i),i=window.setTimeout(function(){n=!1},100),l(k.target))}function L(k){document.visibilityState==="hidden"&&(n&&(o=!0),X())}function X(){document.addEventListener("mousemove",J),document.addEventListener("mousedown",J),document.addEventListener("mouseup",J),document.addEventListener("pointermove",J),document.addEventListener("pointerdown",J),document.addEventListener("pointerup",J),document.addEventListener("touchmove",J),document.addEventListener("touchstart",J),document.addEventListener("touchend",J)}function te(){document.removeEventListener("mousemove",J),document.removeEventListener("mousedown",J),document.removeEventListener("mouseup",J),document.removeEventListener("pointermove",J),document.removeEventListener("pointerdown",J),document.removeEventListener("pointerup",J),document.removeEventListener("touchmove",J),document.removeEventListener("touchstart",J),document.removeEventListener("touchend",J)}function J(k){k.target.nodeName&&k.target.nodeName.toLowerCase()==="html"||(o=!1,te())}document.addEventListener("keydown",f,!0),document.addEventListener("mousedown",u,!0),document.addEventListener("pointerdown",u,!0),document.addEventListener("touchstart",u,!0),document.addEventListener("visibilitychange",L,!0),X(),r.addEventListener("focus",d,!0),r.addEventListener("blur",y,!0),r.nodeType===Node.DOCUMENT_FRAGMENT_NODE&&r.host?r.host.setAttribute("data-js-focus-visible",""):r.nodeType===Node.DOCUMENT_NODE&&(document.documentElement.classList.add("js-focus-visible"),document.documentElement.setAttribute("data-js-focus-visible",""))}if(typeof window!="undefined"&&typeof document!="undefined"){window.applyFocusVisiblePolyfill=e;var t;try{t=new CustomEvent("focus-visible-polyfill-ready")}catch(r){t=document.createEvent("CustomEvent"),t.initCustomEvent("focus-visible-polyfill-ready",!1,!1,{})}window.dispatchEvent(t)}typeof document!="undefined"&&e(document)})});var qr=xr((hy,On)=>{"use strict";/*! - * escape-html - * Copyright(c) 2012-2013 TJ Holowaychuk - * Copyright(c) 2015 Andreas Lubbe - * Copyright(c) 2015 Tiancheng "Timothy" Gu - * MIT Licensed - */var $a=/["'&<>]/;On.exports=Pa;function Pa(e){var t=""+e,r=$a.exec(t);if(!r)return t;var o,n="",i=0,a=0;for(i=r.index;i{/*! - * clipboard.js v2.0.11 - * https://clipboardjs.com/ - * - * Licensed MIT © Zeno Rocha - */(function(t,r){typeof It=="object"&&typeof Yr=="object"?Yr.exports=r():typeof define=="function"&&define.amd?define([],r):typeof It=="object"?It.ClipboardJS=r():t.ClipboardJS=r()})(It,function(){return function(){var e={686:function(o,n,i){"use strict";i.d(n,{default:function(){return Ui}});var a=i(279),s=i.n(a),p=i(370),c=i.n(p),l=i(817),f=i.n(l);function u(V){try{return document.execCommand(V)}catch(A){return!1}}var d=function(A){var M=f()(A);return u("cut"),M},y=d;function L(V){var A=document.documentElement.getAttribute("dir")==="rtl",M=document.createElement("textarea");M.style.fontSize="12pt",M.style.border="0",M.style.padding="0",M.style.margin="0",M.style.position="absolute",M.style[A?"right":"left"]="-9999px";var F=window.pageYOffset||document.documentElement.scrollTop;return M.style.top="".concat(F,"px"),M.setAttribute("readonly",""),M.value=V,M}var X=function(A,M){var F=L(A);M.container.appendChild(F);var D=f()(F);return u("copy"),F.remove(),D},te=function(A){var M=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body},F="";return typeof A=="string"?F=X(A,M):A instanceof HTMLInputElement&&!["text","search","url","tel","password"].includes(A==null?void 0:A.type)?F=X(A.value,M):(F=f()(A),u("copy")),F},J=te;function k(V){"@babel/helpers - typeof";return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?k=function(M){return typeof M}:k=function(M){return M&&typeof Symbol=="function"&&M.constructor===Symbol&&M!==Symbol.prototype?"symbol":typeof M},k(V)}var ft=function(){var A=arguments.length>0&&arguments[0]!==void 0?arguments[0]:{},M=A.action,F=M===void 0?"copy":M,D=A.container,Y=A.target,$e=A.text;if(F!=="copy"&&F!=="cut")throw new Error('Invalid "action" value, use either "copy" or "cut"');if(Y!==void 0)if(Y&&k(Y)==="object"&&Y.nodeType===1){if(F==="copy"&&Y.hasAttribute("disabled"))throw new Error('Invalid "target" attribute. Please use "readonly" instead of "disabled" attribute');if(F==="cut"&&(Y.hasAttribute("readonly")||Y.hasAttribute("disabled")))throw new Error(`Invalid "target" attribute. You can't cut text from elements with "readonly" or "disabled" attributes`)}else throw new Error('Invalid "target" value, use a valid Element');if($e)return J($e,{container:D});if(Y)return F==="cut"?y(Y):J(Y,{container:D})},qe=ft;function Fe(V){"@babel/helpers - typeof";return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?Fe=function(M){return typeof M}:Fe=function(M){return M&&typeof Symbol=="function"&&M.constructor===Symbol&&M!==Symbol.prototype?"symbol":typeof M},Fe(V)}function ki(V,A){if(!(V instanceof A))throw new TypeError("Cannot call a class as a function")}function no(V,A){for(var M=0;M0&&arguments[0]!==void 0?arguments[0]:{};this.action=typeof D.action=="function"?D.action:this.defaultAction,this.target=typeof D.target=="function"?D.target:this.defaultTarget,this.text=typeof D.text=="function"?D.text:this.defaultText,this.container=Fe(D.container)==="object"?D.container:document.body}},{key:"listenClick",value:function(D){var Y=this;this.listener=c()(D,"click",function($e){return Y.onClick($e)})}},{key:"onClick",value:function(D){var Y=D.delegateTarget||D.currentTarget,$e=this.action(Y)||"copy",Dt=qe({action:$e,container:this.container,target:this.target(Y),text:this.text(Y)});this.emit(Dt?"success":"error",{action:$e,text:Dt,trigger:Y,clearSelection:function(){Y&&Y.focus(),window.getSelection().removeAllRanges()}})}},{key:"defaultAction",value:function(D){return vr("action",D)}},{key:"defaultTarget",value:function(D){var Y=vr("target",D);if(Y)return document.querySelector(Y)}},{key:"defaultText",value:function(D){return vr("text",D)}},{key:"destroy",value:function(){this.listener.destroy()}}],[{key:"copy",value:function(D){var Y=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body};return J(D,Y)}},{key:"cut",value:function(D){return y(D)}},{key:"isSupported",value:function(){var D=arguments.length>0&&arguments[0]!==void 0?arguments[0]:["copy","cut"],Y=typeof D=="string"?[D]:D,$e=!!document.queryCommandSupported;return Y.forEach(function(Dt){$e=$e&&!!document.queryCommandSupported(Dt)}),$e}}]),M}(s()),Ui=Fi},828:function(o){var n=9;if(typeof Element!="undefined"&&!Element.prototype.matches){var i=Element.prototype;i.matches=i.matchesSelector||i.mozMatchesSelector||i.msMatchesSelector||i.oMatchesSelector||i.webkitMatchesSelector}function a(s,p){for(;s&&s.nodeType!==n;){if(typeof s.matches=="function"&&s.matches(p))return s;s=s.parentNode}}o.exports=a},438:function(o,n,i){var a=i(828);function s(l,f,u,d,y){var L=c.apply(this,arguments);return l.addEventListener(u,L,y),{destroy:function(){l.removeEventListener(u,L,y)}}}function p(l,f,u,d,y){return typeof l.addEventListener=="function"?s.apply(null,arguments):typeof u=="function"?s.bind(null,document).apply(null,arguments):(typeof l=="string"&&(l=document.querySelectorAll(l)),Array.prototype.map.call(l,function(L){return s(L,f,u,d,y)}))}function c(l,f,u,d){return function(y){y.delegateTarget=a(y.target,f),y.delegateTarget&&d.call(l,y)}}o.exports=p},879:function(o,n){n.node=function(i){return i!==void 0&&i instanceof HTMLElement&&i.nodeType===1},n.nodeList=function(i){var a=Object.prototype.toString.call(i);return i!==void 0&&(a==="[object NodeList]"||a==="[object HTMLCollection]")&&"length"in i&&(i.length===0||n.node(i[0]))},n.string=function(i){return typeof i=="string"||i instanceof String},n.fn=function(i){var a=Object.prototype.toString.call(i);return a==="[object Function]"}},370:function(o,n,i){var a=i(879),s=i(438);function p(u,d,y){if(!u&&!d&&!y)throw new Error("Missing required arguments");if(!a.string(d))throw new TypeError("Second argument must be a String");if(!a.fn(y))throw new TypeError("Third argument must be a Function");if(a.node(u))return c(u,d,y);if(a.nodeList(u))return l(u,d,y);if(a.string(u))return f(u,d,y);throw new TypeError("First argument must be a String, HTMLElement, HTMLCollection, or NodeList")}function c(u,d,y){return u.addEventListener(d,y),{destroy:function(){u.removeEventListener(d,y)}}}function l(u,d,y){return Array.prototype.forEach.call(u,function(L){L.addEventListener(d,y)}),{destroy:function(){Array.prototype.forEach.call(u,function(L){L.removeEventListener(d,y)})}}}function f(u,d,y){return s(document.body,u,d,y)}o.exports=p},817:function(o){function n(i){var a;if(i.nodeName==="SELECT")i.focus(),a=i.value;else if(i.nodeName==="INPUT"||i.nodeName==="TEXTAREA"){var s=i.hasAttribute("readonly");s||i.setAttribute("readonly",""),i.select(),i.setSelectionRange(0,i.value.length),s||i.removeAttribute("readonly"),a=i.value}else{i.hasAttribute("contenteditable")&&i.focus();var p=window.getSelection(),c=document.createRange();c.selectNodeContents(i),p.removeAllRanges(),p.addRange(c),a=p.toString()}return a}o.exports=n},279:function(o){function n(){}n.prototype={on:function(i,a,s){var p=this.e||(this.e={});return(p[i]||(p[i]=[])).push({fn:a,ctx:s}),this},once:function(i,a,s){var p=this;function c(){p.off(i,c),a.apply(s,arguments)}return c._=a,this.on(i,c,s)},emit:function(i){var a=[].slice.call(arguments,1),s=((this.e||(this.e={}))[i]||[]).slice(),p=0,c=s.length;for(p;p0&&i[i.length-1])&&(c[0]===6||c[0]===2)){r=0;continue}if(c[0]===3&&(!i||c[1]>i[0]&&c[1]=e.length&&(e=void 0),{value:e&&e[o++],done:!e}}};throw new TypeError(t?"Object is not iterable.":"Symbol.iterator is not defined.")}function N(e,t){var r=typeof Symbol=="function"&&e[Symbol.iterator];if(!r)return e;var o=r.call(e),n,i=[],a;try{for(;(t===void 0||t-- >0)&&!(n=o.next()).done;)i.push(n.value)}catch(s){a={error:s}}finally{try{n&&!n.done&&(r=o.return)&&r.call(o)}finally{if(a)throw a.error}}return i}function q(e,t,r){if(r||arguments.length===2)for(var o=0,n=t.length,i;o1||p(d,L)})},y&&(n[d]=y(n[d])))}function p(d,y){try{c(o[d](y))}catch(L){u(i[0][3],L)}}function c(d){d.value instanceof nt?Promise.resolve(d.value.v).then(l,f):u(i[0][2],d)}function l(d){p("next",d)}function f(d){p("throw",d)}function u(d,y){d(y),i.shift(),i.length&&p(i[0][0],i[0][1])}}function uo(e){if(!Symbol.asyncIterator)throw new TypeError("Symbol.asyncIterator is not defined.");var t=e[Symbol.asyncIterator],r;return t?t.call(e):(e=typeof he=="function"?he(e):e[Symbol.iterator](),r={},o("next"),o("throw"),o("return"),r[Symbol.asyncIterator]=function(){return this},r);function o(i){r[i]=e[i]&&function(a){return new Promise(function(s,p){a=e[i](a),n(s,p,a.done,a.value)})}}function n(i,a,s,p){Promise.resolve(p).then(function(c){i({value:c,done:s})},a)}}function H(e){return typeof e=="function"}function ut(e){var t=function(o){Error.call(o),o.stack=new Error().stack},r=e(t);return r.prototype=Object.create(Error.prototype),r.prototype.constructor=r,r}var zt=ut(function(e){return function(r){e(this),this.message=r?r.length+` errors occurred during unsubscription: -`+r.map(function(o,n){return n+1+") "+o.toString()}).join(` - `):"",this.name="UnsubscriptionError",this.errors=r}});function Qe(e,t){if(e){var r=e.indexOf(t);0<=r&&e.splice(r,1)}}var Ue=function(){function e(t){this.initialTeardown=t,this.closed=!1,this._parentage=null,this._finalizers=null}return e.prototype.unsubscribe=function(){var t,r,o,n,i;if(!this.closed){this.closed=!0;var a=this._parentage;if(a)if(this._parentage=null,Array.isArray(a))try{for(var s=he(a),p=s.next();!p.done;p=s.next()){var c=p.value;c.remove(this)}}catch(L){t={error:L}}finally{try{p&&!p.done&&(r=s.return)&&r.call(s)}finally{if(t)throw t.error}}else a.remove(this);var l=this.initialTeardown;if(H(l))try{l()}catch(L){i=L instanceof zt?L.errors:[L]}var f=this._finalizers;if(f){this._finalizers=null;try{for(var u=he(f),d=u.next();!d.done;d=u.next()){var y=d.value;try{ho(y)}catch(L){i=i!=null?i:[],L instanceof zt?i=q(q([],N(i)),N(L.errors)):i.push(L)}}}catch(L){o={error:L}}finally{try{d&&!d.done&&(n=u.return)&&n.call(u)}finally{if(o)throw o.error}}}if(i)throw new zt(i)}},e.prototype.add=function(t){var r;if(t&&t!==this)if(this.closed)ho(t);else{if(t instanceof e){if(t.closed||t._hasParent(this))return;t._addParent(this)}(this._finalizers=(r=this._finalizers)!==null&&r!==void 0?r:[]).push(t)}},e.prototype._hasParent=function(t){var r=this._parentage;return r===t||Array.isArray(r)&&r.includes(t)},e.prototype._addParent=function(t){var r=this._parentage;this._parentage=Array.isArray(r)?(r.push(t),r):r?[r,t]:t},e.prototype._removeParent=function(t){var r=this._parentage;r===t?this._parentage=null:Array.isArray(r)&&Qe(r,t)},e.prototype.remove=function(t){var r=this._finalizers;r&&Qe(r,t),t instanceof e&&t._removeParent(this)},e.EMPTY=function(){var t=new e;return t.closed=!0,t}(),e}();var Tr=Ue.EMPTY;function qt(e){return e instanceof Ue||e&&"closed"in e&&H(e.remove)&&H(e.add)&&H(e.unsubscribe)}function ho(e){H(e)?e():e.unsubscribe()}var Pe={onUnhandledError:null,onStoppedNotification:null,Promise:void 0,useDeprecatedSynchronousErrorHandling:!1,useDeprecatedNextContext:!1};var dt={setTimeout:function(e,t){for(var r=[],o=2;o0},enumerable:!1,configurable:!0}),t.prototype._trySubscribe=function(r){return this._throwIfClosed(),e.prototype._trySubscribe.call(this,r)},t.prototype._subscribe=function(r){return this._throwIfClosed(),this._checkFinalizedStatuses(r),this._innerSubscribe(r)},t.prototype._innerSubscribe=function(r){var o=this,n=this,i=n.hasError,a=n.isStopped,s=n.observers;return i||a?Tr:(this.currentObservers=null,s.push(r),new Ue(function(){o.currentObservers=null,Qe(s,r)}))},t.prototype._checkFinalizedStatuses=function(r){var o=this,n=o.hasError,i=o.thrownError,a=o.isStopped;n?r.error(i):a&&r.complete()},t.prototype.asObservable=function(){var r=new j;return r.source=this,r},t.create=function(r,o){return new To(r,o)},t}(j);var To=function(e){oe(t,e);function t(r,o){var n=e.call(this)||this;return n.destination=r,n.source=o,n}return t.prototype.next=function(r){var o,n;(n=(o=this.destination)===null||o===void 0?void 0:o.next)===null||n===void 0||n.call(o,r)},t.prototype.error=function(r){var o,n;(n=(o=this.destination)===null||o===void 0?void 0:o.error)===null||n===void 0||n.call(o,r)},t.prototype.complete=function(){var r,o;(o=(r=this.destination)===null||r===void 0?void 0:r.complete)===null||o===void 0||o.call(r)},t.prototype._subscribe=function(r){var o,n;return(n=(o=this.source)===null||o===void 0?void 0:o.subscribe(r))!==null&&n!==void 0?n:Tr},t}(g);var _r=function(e){oe(t,e);function t(r){var o=e.call(this)||this;return o._value=r,o}return Object.defineProperty(t.prototype,"value",{get:function(){return this.getValue()},enumerable:!1,configurable:!0}),t.prototype._subscribe=function(r){var o=e.prototype._subscribe.call(this,r);return!o.closed&&r.next(this._value),o},t.prototype.getValue=function(){var r=this,o=r.hasError,n=r.thrownError,i=r._value;if(o)throw n;return this._throwIfClosed(),i},t.prototype.next=function(r){e.prototype.next.call(this,this._value=r)},t}(g);var At={now:function(){return(At.delegate||Date).now()},delegate:void 0};var Ct=function(e){oe(t,e);function t(r,o,n){r===void 0&&(r=1/0),o===void 0&&(o=1/0),n===void 0&&(n=At);var i=e.call(this)||this;return i._bufferSize=r,i._windowTime=o,i._timestampProvider=n,i._buffer=[],i._infiniteTimeWindow=!0,i._infiniteTimeWindow=o===1/0,i._bufferSize=Math.max(1,r),i._windowTime=Math.max(1,o),i}return t.prototype.next=function(r){var o=this,n=o.isStopped,i=o._buffer,a=o._infiniteTimeWindow,s=o._timestampProvider,p=o._windowTime;n||(i.push(r),!a&&i.push(s.now()+p)),this._trimBuffer(),e.prototype.next.call(this,r)},t.prototype._subscribe=function(r){this._throwIfClosed(),this._trimBuffer();for(var o=this._innerSubscribe(r),n=this,i=n._infiniteTimeWindow,a=n._buffer,s=a.slice(),p=0;p0?e.prototype.schedule.call(this,r,o):(this.delay=o,this.state=r,this.scheduler.flush(this),this)},t.prototype.execute=function(r,o){return o>0||this.closed?e.prototype.execute.call(this,r,o):this._execute(r,o)},t.prototype.requestAsyncId=function(r,o,n){return n===void 0&&(n=0),n!=null&&n>0||n==null&&this.delay>0?e.prototype.requestAsyncId.call(this,r,o,n):(r.flush(this),0)},t}(gt);var Lo=function(e){oe(t,e);function t(){return e!==null&&e.apply(this,arguments)||this}return t}(yt);var kr=new Lo(Oo);var Mo=function(e){oe(t,e);function t(r,o){var n=e.call(this,r,o)||this;return n.scheduler=r,n.work=o,n}return t.prototype.requestAsyncId=function(r,o,n){return n===void 0&&(n=0),n!==null&&n>0?e.prototype.requestAsyncId.call(this,r,o,n):(r.actions.push(this),r._scheduled||(r._scheduled=vt.requestAnimationFrame(function(){return r.flush(void 0)})))},t.prototype.recycleAsyncId=function(r,o,n){var i;if(n===void 0&&(n=0),n!=null?n>0:this.delay>0)return e.prototype.recycleAsyncId.call(this,r,o,n);var a=r.actions;o!=null&&((i=a[a.length-1])===null||i===void 0?void 0:i.id)!==o&&(vt.cancelAnimationFrame(o),r._scheduled=void 0)},t}(gt);var _o=function(e){oe(t,e);function t(){return e!==null&&e.apply(this,arguments)||this}return t.prototype.flush=function(r){this._active=!0;var o=this._scheduled;this._scheduled=void 0;var n=this.actions,i;r=r||n.shift();do if(i=r.execute(r.state,r.delay))break;while((r=n[0])&&r.id===o&&n.shift());if(this._active=!1,i){for(;(r=n[0])&&r.id===o&&n.shift();)r.unsubscribe();throw i}},t}(yt);var me=new _o(Mo);var S=new j(function(e){return e.complete()});function Yt(e){return e&&H(e.schedule)}function Hr(e){return e[e.length-1]}function Xe(e){return H(Hr(e))?e.pop():void 0}function ke(e){return Yt(Hr(e))?e.pop():void 0}function Bt(e,t){return typeof Hr(e)=="number"?e.pop():t}var xt=function(e){return e&&typeof e.length=="number"&&typeof e!="function"};function Gt(e){return H(e==null?void 0:e.then)}function Jt(e){return H(e[bt])}function Xt(e){return Symbol.asyncIterator&&H(e==null?void 0:e[Symbol.asyncIterator])}function Zt(e){return new TypeError("You provided "+(e!==null&&typeof e=="object"?"an invalid object":"'"+e+"'")+" where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.")}function Zi(){return typeof Symbol!="function"||!Symbol.iterator?"@@iterator":Symbol.iterator}var er=Zi();function tr(e){return H(e==null?void 0:e[er])}function rr(e){return fo(this,arguments,function(){var r,o,n,i;return Nt(this,function(a){switch(a.label){case 0:r=e.getReader(),a.label=1;case 1:a.trys.push([1,,9,10]),a.label=2;case 2:return[4,nt(r.read())];case 3:return o=a.sent(),n=o.value,i=o.done,i?[4,nt(void 0)]:[3,5];case 4:return[2,a.sent()];case 5:return[4,nt(n)];case 6:return[4,a.sent()];case 7:return a.sent(),[3,2];case 8:return[3,10];case 9:return r.releaseLock(),[7];case 10:return[2]}})})}function or(e){return H(e==null?void 0:e.getReader)}function U(e){if(e instanceof j)return e;if(e!=null){if(Jt(e))return ea(e);if(xt(e))return ta(e);if(Gt(e))return ra(e);if(Xt(e))return Ao(e);if(tr(e))return oa(e);if(or(e))return na(e)}throw Zt(e)}function ea(e){return new j(function(t){var r=e[bt]();if(H(r.subscribe))return r.subscribe(t);throw new TypeError("Provided object does not correctly implement Symbol.observable")})}function ta(e){return new j(function(t){for(var r=0;r=2;return function(o){return o.pipe(e?b(function(n,i){return e(n,i,o)}):le,Te(1),r?De(t):Qo(function(){return new ir}))}}function jr(e){return e<=0?function(){return S}:E(function(t,r){var o=[];t.subscribe(T(r,function(n){o.push(n),e=2,!0))}function pe(e){e===void 0&&(e={});var t=e.connector,r=t===void 0?function(){return new g}:t,o=e.resetOnError,n=o===void 0?!0:o,i=e.resetOnComplete,a=i===void 0?!0:i,s=e.resetOnRefCountZero,p=s===void 0?!0:s;return function(c){var l,f,u,d=0,y=!1,L=!1,X=function(){f==null||f.unsubscribe(),f=void 0},te=function(){X(),l=u=void 0,y=L=!1},J=function(){var k=l;te(),k==null||k.unsubscribe()};return E(function(k,ft){d++,!L&&!y&&X();var qe=u=u!=null?u:r();ft.add(function(){d--,d===0&&!L&&!y&&(f=Ur(J,p))}),qe.subscribe(ft),!l&&d>0&&(l=new at({next:function(Fe){return qe.next(Fe)},error:function(Fe){L=!0,X(),f=Ur(te,n,Fe),qe.error(Fe)},complete:function(){y=!0,X(),f=Ur(te,a),qe.complete()}}),U(k).subscribe(l))})(c)}}function Ur(e,t){for(var r=[],o=2;oe.next(document)),e}function P(e,t=document){return Array.from(t.querySelectorAll(e))}function R(e,t=document){let r=fe(e,t);if(typeof r=="undefined")throw new ReferenceError(`Missing element: expected "${e}" to be present`);return r}function fe(e,t=document){return t.querySelector(e)||void 0}function Ie(){var e,t,r,o;return(o=(r=(t=(e=document.activeElement)==null?void 0:e.shadowRoot)==null?void 0:t.activeElement)!=null?r:document.activeElement)!=null?o:void 0}var wa=O(h(document.body,"focusin"),h(document.body,"focusout")).pipe(_e(1),Q(void 0),m(()=>Ie()||document.body),G(1));function et(e){return wa.pipe(m(t=>e.contains(t)),K())}function $t(e,t){return C(()=>O(h(e,"mouseenter").pipe(m(()=>!0)),h(e,"mouseleave").pipe(m(()=>!1))).pipe(t?Ht(r=>Le(+!r*t)):le,Q(e.matches(":hover"))))}function Jo(e,t){if(typeof t=="string"||typeof t=="number")e.innerHTML+=t.toString();else if(t instanceof Node)e.appendChild(t);else if(Array.isArray(t))for(let r of t)Jo(e,r)}function x(e,t,...r){let o=document.createElement(e);if(t)for(let n of Object.keys(t))typeof t[n]!="undefined"&&(typeof t[n]!="boolean"?o.setAttribute(n,t[n]):o.setAttribute(n,""));for(let n of r)Jo(o,n);return o}function sr(e){if(e>999){let t=+((e-950)%1e3>99);return`${((e+1e-6)/1e3).toFixed(t)}k`}else return e.toString()}function Tt(e){let t=x("script",{src:e});return C(()=>(document.head.appendChild(t),O(h(t,"load"),h(t,"error").pipe(v(()=>$r(()=>new ReferenceError(`Invalid script: ${e}`))))).pipe(m(()=>{}),_(()=>document.head.removeChild(t)),Te(1))))}var Xo=new g,Ta=C(()=>typeof ResizeObserver=="undefined"?Tt("https://unpkg.com/resize-observer-polyfill"):I(void 0)).pipe(m(()=>new ResizeObserver(e=>e.forEach(t=>Xo.next(t)))),v(e=>O(Ye,I(e)).pipe(_(()=>e.disconnect()))),G(1));function ce(e){return{width:e.offsetWidth,height:e.offsetHeight}}function ge(e){let t=e;for(;t.clientWidth===0&&t.parentElement;)t=t.parentElement;return Ta.pipe(w(r=>r.observe(t)),v(r=>Xo.pipe(b(o=>o.target===t),_(()=>r.unobserve(t)))),m(()=>ce(e)),Q(ce(e)))}function St(e){return{width:e.scrollWidth,height:e.scrollHeight}}function cr(e){let t=e.parentElement;for(;t&&(e.scrollWidth<=t.scrollWidth&&e.scrollHeight<=t.scrollHeight);)t=(e=t).parentElement;return t?e:void 0}function Zo(e){let t=[],r=e.parentElement;for(;r;)(e.clientWidth>r.clientWidth||e.clientHeight>r.clientHeight)&&t.push(r),r=(e=r).parentElement;return t.length===0&&t.push(document.documentElement),t}function Ve(e){return{x:e.offsetLeft,y:e.offsetTop}}function en(e){let t=e.getBoundingClientRect();return{x:t.x+window.scrollX,y:t.y+window.scrollY}}function tn(e){return O(h(window,"load"),h(window,"resize")).pipe(Me(0,me),m(()=>Ve(e)),Q(Ve(e)))}function pr(e){return{x:e.scrollLeft,y:e.scrollTop}}function Ne(e){return O(h(e,"scroll"),h(window,"scroll"),h(window,"resize")).pipe(Me(0,me),m(()=>pr(e)),Q(pr(e)))}var rn=new g,Sa=C(()=>I(new IntersectionObserver(e=>{for(let t of e)rn.next(t)},{threshold:0}))).pipe(v(e=>O(Ye,I(e)).pipe(_(()=>e.disconnect()))),G(1));function tt(e){return Sa.pipe(w(t=>t.observe(e)),v(t=>rn.pipe(b(({target:r})=>r===e),_(()=>t.unobserve(e)),m(({isIntersecting:r})=>r))))}function on(e,t=16){return Ne(e).pipe(m(({y:r})=>{let o=ce(e),n=St(e);return r>=n.height-o.height-t}),K())}var lr={drawer:R("[data-md-toggle=drawer]"),search:R("[data-md-toggle=search]")};function nn(e){return lr[e].checked}function Je(e,t){lr[e].checked!==t&&lr[e].click()}function ze(e){let t=lr[e];return h(t,"change").pipe(m(()=>t.checked),Q(t.checked))}function Oa(e,t){switch(e.constructor){case HTMLInputElement:return e.type==="radio"?/^Arrow/.test(t):!0;case HTMLSelectElement:case HTMLTextAreaElement:return!0;default:return e.isContentEditable}}function La(){return O(h(window,"compositionstart").pipe(m(()=>!0)),h(window,"compositionend").pipe(m(()=>!1))).pipe(Q(!1))}function an(){let e=h(window,"keydown").pipe(b(t=>!(t.metaKey||t.ctrlKey)),m(t=>({mode:nn("search")?"search":"global",type:t.key,claim(){t.preventDefault(),t.stopPropagation()}})),b(({mode:t,type:r})=>{if(t==="global"){let o=Ie();if(typeof o!="undefined")return!Oa(o,r)}return!0}),pe());return La().pipe(v(t=>t?S:e))}function ye(){return new URL(location.href)}function lt(e,t=!1){if(B("navigation.instant")&&!t){let r=x("a",{href:e.href});document.body.appendChild(r),r.click(),r.remove()}else location.href=e.href}function sn(){return new g}function cn(){return location.hash.slice(1)}function pn(e){let t=x("a",{href:e});t.addEventListener("click",r=>r.stopPropagation()),t.click()}function Ma(e){return O(h(window,"hashchange"),e).pipe(m(cn),Q(cn()),b(t=>t.length>0),G(1))}function ln(e){return Ma(e).pipe(m(t=>fe(`[id="${t}"]`)),b(t=>typeof t!="undefined"))}function Pt(e){let t=matchMedia(e);return ar(r=>t.addListener(()=>r(t.matches))).pipe(Q(t.matches))}function mn(){let e=matchMedia("print");return O(h(window,"beforeprint").pipe(m(()=>!0)),h(window,"afterprint").pipe(m(()=>!1))).pipe(Q(e.matches))}function Nr(e,t){return e.pipe(v(r=>r?t():S))}function zr(e,t){return new j(r=>{let o=new XMLHttpRequest;return o.open("GET",`${e}`),o.responseType="blob",o.addEventListener("load",()=>{o.status>=200&&o.status<300?(r.next(o.response),r.complete()):r.error(new Error(o.statusText))}),o.addEventListener("error",()=>{r.error(new Error("Network error"))}),o.addEventListener("abort",()=>{r.complete()}),typeof(t==null?void 0:t.progress$)!="undefined"&&(o.addEventListener("progress",n=>{var i;if(n.lengthComputable)t.progress$.next(n.loaded/n.total*100);else{let a=(i=o.getResponseHeader("Content-Length"))!=null?i:0;t.progress$.next(n.loaded/+a*100)}}),t.progress$.next(5)),o.send(),()=>o.abort()})}function je(e,t){return zr(e,t).pipe(v(r=>r.text()),m(r=>JSON.parse(r)),G(1))}function fn(e,t){let r=new DOMParser;return zr(e,t).pipe(v(o=>o.text()),m(o=>r.parseFromString(o,"text/html")),G(1))}function un(e,t){let r=new DOMParser;return zr(e,t).pipe(v(o=>o.text()),m(o=>r.parseFromString(o,"text/xml")),G(1))}function dn(){return{x:Math.max(0,scrollX),y:Math.max(0,scrollY)}}function hn(){return O(h(window,"scroll",{passive:!0}),h(window,"resize",{passive:!0})).pipe(m(dn),Q(dn()))}function bn(){return{width:innerWidth,height:innerHeight}}function vn(){return h(window,"resize",{passive:!0}).pipe(m(bn),Q(bn()))}function gn(){return z([hn(),vn()]).pipe(m(([e,t])=>({offset:e,size:t})),G(1))}function mr(e,{viewport$:t,header$:r}){let o=t.pipe(ee("size")),n=z([o,r]).pipe(m(()=>Ve(e)));return z([r,t,n]).pipe(m(([{height:i},{offset:a,size:s},{x:p,y:c}])=>({offset:{x:a.x-p,y:a.y-c+i},size:s})))}function _a(e){return h(e,"message",t=>t.data)}function Aa(e){let t=new g;return t.subscribe(r=>e.postMessage(r)),t}function yn(e,t=new Worker(e)){let r=_a(t),o=Aa(t),n=new g;n.subscribe(o);let i=o.pipe(Z(),ie(!0));return n.pipe(Z(),Re(r.pipe(W(i))),pe())}var Ca=R("#__config"),Ot=JSON.parse(Ca.textContent);Ot.base=`${new URL(Ot.base,ye())}`;function xe(){return Ot}function B(e){return Ot.features.includes(e)}function Ee(e,t){return typeof t!="undefined"?Ot.translations[e].replace("#",t.toString()):Ot.translations[e]}function Se(e,t=document){return R(`[data-md-component=${e}]`,t)}function ae(e,t=document){return P(`[data-md-component=${e}]`,t)}function ka(e){let t=R(".md-typeset > :first-child",e);return h(t,"click",{once:!0}).pipe(m(()=>R(".md-typeset",e)),m(r=>({hash:__md_hash(r.innerHTML)})))}function xn(e){if(!B("announce.dismiss")||!e.childElementCount)return S;if(!e.hidden){let t=R(".md-typeset",e);__md_hash(t.innerHTML)===__md_get("__announce")&&(e.hidden=!0)}return C(()=>{let t=new g;return t.subscribe(({hash:r})=>{e.hidden=!0,__md_set("__announce",r)}),ka(e).pipe(w(r=>t.next(r)),_(()=>t.complete()),m(r=>$({ref:e},r)))})}function Ha(e,{target$:t}){return t.pipe(m(r=>({hidden:r!==e})))}function En(e,t){let r=new g;return r.subscribe(({hidden:o})=>{e.hidden=o}),Ha(e,t).pipe(w(o=>r.next(o)),_(()=>r.complete()),m(o=>$({ref:e},o)))}function Rt(e,t){return t==="inline"?x("div",{class:"md-tooltip md-tooltip--inline",id:e,role:"tooltip"},x("div",{class:"md-tooltip__inner md-typeset"})):x("div",{class:"md-tooltip",id:e,role:"tooltip"},x("div",{class:"md-tooltip__inner md-typeset"}))}function wn(...e){return x("div",{class:"md-tooltip2",role:"tooltip"},x("div",{class:"md-tooltip2__inner md-typeset"},e))}function Tn(e,t){if(t=t?`${t}_annotation_${e}`:void 0,t){let r=t?`#${t}`:void 0;return x("aside",{class:"md-annotation",tabIndex:0},Rt(t),x("a",{href:r,class:"md-annotation__index",tabIndex:-1},x("span",{"data-md-annotation-id":e})))}else return x("aside",{class:"md-annotation",tabIndex:0},Rt(t),x("span",{class:"md-annotation__index",tabIndex:-1},x("span",{"data-md-annotation-id":e})))}function Sn(e){return x("button",{class:"md-clipboard md-icon",title:Ee("clipboard.copy"),"data-clipboard-target":`#${e} > code`})}var Ln=Mt(qr());function Qr(e,t){let r=t&2,o=t&1,n=Object.keys(e.terms).filter(p=>!e.terms[p]).reduce((p,c)=>[...p,x("del",null,(0,Ln.default)(c))," "],[]).slice(0,-1),i=xe(),a=new URL(e.location,i.base);B("search.highlight")&&a.searchParams.set("h",Object.entries(e.terms).filter(([,p])=>p).reduce((p,[c])=>`${p} ${c}`.trim(),""));let{tags:s}=xe();return x("a",{href:`${a}`,class:"md-search-result__link",tabIndex:-1},x("article",{class:"md-search-result__article md-typeset","data-md-score":e.score.toFixed(2)},r>0&&x("div",{class:"md-search-result__icon md-icon"}),r>0&&x("h1",null,e.title),r<=0&&x("h2",null,e.title),o>0&&e.text.length>0&&e.text,e.tags&&x("nav",{class:"md-tags"},e.tags.map(p=>{let c=s?p in s?`md-tag-icon md-tag--${s[p]}`:"md-tag-icon":"";return x("span",{class:`md-tag ${c}`},p)})),o>0&&n.length>0&&x("p",{class:"md-search-result__terms"},Ee("search.result.term.missing"),": ",...n)))}function Mn(e){let t=e[0].score,r=[...e],o=xe(),n=r.findIndex(l=>!`${new URL(l.location,o.base)}`.includes("#")),[i]=r.splice(n,1),a=r.findIndex(l=>l.scoreQr(l,1)),...p.length?[x("details",{class:"md-search-result__more"},x("summary",{tabIndex:-1},x("div",null,p.length>0&&p.length===1?Ee("search.result.more.one"):Ee("search.result.more.other",p.length))),...p.map(l=>Qr(l,1)))]:[]];return x("li",{class:"md-search-result__item"},c)}function _n(e){return x("ul",{class:"md-source__facts"},Object.entries(e).map(([t,r])=>x("li",{class:`md-source__fact md-source__fact--${t}`},typeof r=="number"?sr(r):r)))}function Kr(e){let t=`tabbed-control tabbed-control--${e}`;return x("div",{class:t,hidden:!0},x("button",{class:"tabbed-button",tabIndex:-1,"aria-hidden":"true"}))}function An(e){return x("div",{class:"md-typeset__scrollwrap"},x("div",{class:"md-typeset__table"},e))}function Ra(e){var o;let t=xe(),r=new URL(`../${e.version}/`,t.base);return x("li",{class:"md-version__item"},x("a",{href:`${r}`,class:"md-version__link"},e.title,((o=t.version)==null?void 0:o.alias)&&e.aliases.length>0&&x("span",{class:"md-version__alias"},e.aliases[0])))}function Cn(e,t){var o;let r=xe();return e=e.filter(n=>{var i;return!((i=n.properties)!=null&&i.hidden)}),x("div",{class:"md-version"},x("button",{class:"md-version__current","aria-label":Ee("select.version")},t.title,((o=r.version)==null?void 0:o.alias)&&t.aliases.length>0&&x("span",{class:"md-version__alias"},t.aliases[0])),x("ul",{class:"md-version__list"},e.map(Ra)))}var Ia=0;function ja(e){let t=z([et(e),$t(e)]).pipe(m(([o,n])=>o||n),K()),r=C(()=>Zo(e)).pipe(ne(Ne),pt(1),He(t),m(()=>en(e)));return t.pipe(Ae(o=>o),v(()=>z([t,r])),m(([o,n])=>({active:o,offset:n})),pe())}function Fa(e,t){let{content$:r,viewport$:o}=t,n=`__tooltip2_${Ia++}`;return C(()=>{let i=new g,a=new _r(!1);i.pipe(Z(),ie(!1)).subscribe(a);let s=a.pipe(Ht(c=>Le(+!c*250,kr)),K(),v(c=>c?r:S),w(c=>c.id=n),pe());z([i.pipe(m(({active:c})=>c)),s.pipe(v(c=>$t(c,250)),Q(!1))]).pipe(m(c=>c.some(l=>l))).subscribe(a);let p=a.pipe(b(c=>c),re(s,o),m(([c,l,{size:f}])=>{let u=e.getBoundingClientRect(),d=u.width/2;if(l.role==="tooltip")return{x:d,y:8+u.height};if(u.y>=f.height/2){let{height:y}=ce(l);return{x:d,y:-16-y}}else return{x:d,y:16+u.height}}));return z([s,i,p]).subscribe(([c,{offset:l},f])=>{c.style.setProperty("--md-tooltip-host-x",`${l.x}px`),c.style.setProperty("--md-tooltip-host-y",`${l.y}px`),c.style.setProperty("--md-tooltip-x",`${f.x}px`),c.style.setProperty("--md-tooltip-y",`${f.y}px`),c.classList.toggle("md-tooltip2--top",f.y<0),c.classList.toggle("md-tooltip2--bottom",f.y>=0)}),a.pipe(b(c=>c),re(s,(c,l)=>l),b(c=>c.role==="tooltip")).subscribe(c=>{let l=ce(R(":scope > *",c));c.style.setProperty("--md-tooltip-width",`${l.width}px`),c.style.setProperty("--md-tooltip-tail","0px")}),a.pipe(K(),ve(me),re(s)).subscribe(([c,l])=>{l.classList.toggle("md-tooltip2--active",c)}),z([a.pipe(b(c=>c)),s]).subscribe(([c,l])=>{l.role==="dialog"?(e.setAttribute("aria-controls",n),e.setAttribute("aria-haspopup","dialog")):e.setAttribute("aria-describedby",n)}),a.pipe(b(c=>!c)).subscribe(()=>{e.removeAttribute("aria-controls"),e.removeAttribute("aria-describedby"),e.removeAttribute("aria-haspopup")}),ja(e).pipe(w(c=>i.next(c)),_(()=>i.complete()),m(c=>$({ref:e},c)))})}function mt(e,{viewport$:t},r=document.body){return Fa(e,{content$:new j(o=>{let n=e.title,i=wn(n);return o.next(i),e.removeAttribute("title"),r.append(i),()=>{i.remove(),e.setAttribute("title",n)}}),viewport$:t})}function Ua(e,t){let r=C(()=>z([tn(e),Ne(t)])).pipe(m(([{x:o,y:n},i])=>{let{width:a,height:s}=ce(e);return{x:o-i.x+a/2,y:n-i.y+s/2}}));return et(e).pipe(v(o=>r.pipe(m(n=>({active:o,offset:n})),Te(+!o||1/0))))}function kn(e,t,{target$:r}){let[o,n]=Array.from(e.children);return C(()=>{let i=new g,a=i.pipe(Z(),ie(!0));return i.subscribe({next({offset:s}){e.style.setProperty("--md-tooltip-x",`${s.x}px`),e.style.setProperty("--md-tooltip-y",`${s.y}px`)},complete(){e.style.removeProperty("--md-tooltip-x"),e.style.removeProperty("--md-tooltip-y")}}),tt(e).pipe(W(a)).subscribe(s=>{e.toggleAttribute("data-md-visible",s)}),O(i.pipe(b(({active:s})=>s)),i.pipe(_e(250),b(({active:s})=>!s))).subscribe({next({active:s}){s?e.prepend(o):o.remove()},complete(){e.prepend(o)}}),i.pipe(Me(16,me)).subscribe(({active:s})=>{o.classList.toggle("md-tooltip--active",s)}),i.pipe(pt(125,me),b(()=>!!e.offsetParent),m(()=>e.offsetParent.getBoundingClientRect()),m(({x:s})=>s)).subscribe({next(s){s?e.style.setProperty("--md-tooltip-0",`${-s}px`):e.style.removeProperty("--md-tooltip-0")},complete(){e.style.removeProperty("--md-tooltip-0")}}),h(n,"click").pipe(W(a),b(s=>!(s.metaKey||s.ctrlKey))).subscribe(s=>{s.stopPropagation(),s.preventDefault()}),h(n,"mousedown").pipe(W(a),re(i)).subscribe(([s,{active:p}])=>{var c;if(s.button!==0||s.metaKey||s.ctrlKey)s.preventDefault();else if(p){s.preventDefault();let l=e.parentElement.closest(".md-annotation");l instanceof HTMLElement?l.focus():(c=Ie())==null||c.blur()}}),r.pipe(W(a),b(s=>s===o),Ge(125)).subscribe(()=>e.focus()),Ua(e,t).pipe(w(s=>i.next(s)),_(()=>i.complete()),m(s=>$({ref:e},s)))})}function Wa(e){return e.tagName==="CODE"?P(".c, .c1, .cm",e):[e]}function Da(e){let t=[];for(let r of Wa(e)){let o=[],n=document.createNodeIterator(r,NodeFilter.SHOW_TEXT);for(let i=n.nextNode();i;i=n.nextNode())o.push(i);for(let i of o){let a;for(;a=/(\(\d+\))(!)?/.exec(i.textContent);){let[,s,p]=a;if(typeof p=="undefined"){let c=i.splitText(a.index);i=c.splitText(s.length),t.push(c)}else{i.textContent=s,t.push(i);break}}}}return t}function Hn(e,t){t.append(...Array.from(e.childNodes))}function fr(e,t,{target$:r,print$:o}){let n=t.closest("[id]"),i=n==null?void 0:n.id,a=new Map;for(let s of Da(t)){let[,p]=s.textContent.match(/\((\d+)\)/);fe(`:scope > li:nth-child(${p})`,e)&&(a.set(p,Tn(p,i)),s.replaceWith(a.get(p)))}return a.size===0?S:C(()=>{let s=new g,p=s.pipe(Z(),ie(!0)),c=[];for(let[l,f]of a)c.push([R(".md-typeset",f),R(`:scope > li:nth-child(${l})`,e)]);return o.pipe(W(p)).subscribe(l=>{e.hidden=!l,e.classList.toggle("md-annotation-list",l);for(let[f,u]of c)l?Hn(f,u):Hn(u,f)}),O(...[...a].map(([,l])=>kn(l,t,{target$:r}))).pipe(_(()=>s.complete()),pe())})}function $n(e){if(e.nextElementSibling){let t=e.nextElementSibling;if(t.tagName==="OL")return t;if(t.tagName==="P"&&!t.children.length)return $n(t)}}function Pn(e,t){return C(()=>{let r=$n(e);return typeof r!="undefined"?fr(r,e,t):S})}var Rn=Mt(Br());var Va=0;function In(e){if(e.nextElementSibling){let t=e.nextElementSibling;if(t.tagName==="OL")return t;if(t.tagName==="P"&&!t.children.length)return In(t)}}function Na(e){return ge(e).pipe(m(({width:t})=>({scrollable:St(e).width>t})),ee("scrollable"))}function jn(e,t){let{matches:r}=matchMedia("(hover)"),o=C(()=>{let n=new g,i=n.pipe(jr(1));n.subscribe(({scrollable:c})=>{c&&r?e.setAttribute("tabindex","0"):e.removeAttribute("tabindex")});let a=[];if(Rn.default.isSupported()&&(e.closest(".copy")||B("content.code.copy")&&!e.closest(".no-copy"))){let c=e.closest("pre");c.id=`__code_${Va++}`;let l=Sn(c.id);c.insertBefore(l,e),B("content.tooltips")&&a.push(mt(l,{viewport$}))}let s=e.closest(".highlight");if(s instanceof HTMLElement){let c=In(s);if(typeof c!="undefined"&&(s.classList.contains("annotate")||B("content.code.annotate"))){let l=fr(c,e,t);a.push(ge(s).pipe(W(i),m(({width:f,height:u})=>f&&u),K(),v(f=>f?l:S)))}}return P(":scope > span[id]",e).length&&e.classList.add("md-code__content"),Na(e).pipe(w(c=>n.next(c)),_(()=>n.complete()),m(c=>$({ref:e},c)),Re(...a))});return B("content.lazy")?tt(e).pipe(b(n=>n),Te(1),v(()=>o)):o}function za(e,{target$:t,print$:r}){let o=!0;return O(t.pipe(m(n=>n.closest("details:not([open])")),b(n=>e===n),m(()=>({action:"open",reveal:!0}))),r.pipe(b(n=>n||!o),w(()=>o=e.open),m(n=>({action:n?"open":"close"}))))}function Fn(e,t){return C(()=>{let r=new g;return r.subscribe(({action:o,reveal:n})=>{e.toggleAttribute("open",o==="open"),n&&e.scrollIntoView()}),za(e,t).pipe(w(o=>r.next(o)),_(()=>r.complete()),m(o=>$({ref:e},o)))})}var Un=".node circle,.node ellipse,.node path,.node polygon,.node rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}marker{fill:var(--md-mermaid-edge-color)!important}.edgeLabel .label rect{fill:#0000}.label{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.label foreignObject{line-height:normal;overflow:visible}.label div .edgeLabel{color:var(--md-mermaid-label-fg-color)}.edgeLabel,.edgeLabel p,.label div .edgeLabel{background-color:var(--md-mermaid-label-bg-color)}.edgeLabel,.edgeLabel p{fill:var(--md-mermaid-label-bg-color);color:var(--md-mermaid-edge-color)}.edgePath .path,.flowchart-link{stroke:var(--md-mermaid-edge-color);stroke-width:.05rem}.edgePath .arrowheadPath{fill:var(--md-mermaid-edge-color);stroke:none}.cluster rect{fill:var(--md-default-fg-color--lightest);stroke:var(--md-default-fg-color--lighter)}.cluster span{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}g #flowchart-circleEnd,g #flowchart-circleStart,g #flowchart-crossEnd,g #flowchart-crossStart,g #flowchart-pointEnd,g #flowchart-pointStart{stroke:none}g.classGroup line,g.classGroup rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}g.classGroup text{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.classLabel .box{fill:var(--md-mermaid-label-bg-color);background-color:var(--md-mermaid-label-bg-color);opacity:1}.classLabel .label{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.node .divider{stroke:var(--md-mermaid-node-fg-color)}.relation{stroke:var(--md-mermaid-edge-color)}.cardinality{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.cardinality text{fill:inherit!important}defs #classDiagram-compositionEnd,defs #classDiagram-compositionStart,defs #classDiagram-dependencyEnd,defs #classDiagram-dependencyStart,defs #classDiagram-extensionEnd,defs #classDiagram-extensionStart{fill:var(--md-mermaid-edge-color)!important;stroke:var(--md-mermaid-edge-color)!important}defs #classDiagram-aggregationEnd,defs #classDiagram-aggregationStart{fill:var(--md-mermaid-label-bg-color)!important;stroke:var(--md-mermaid-edge-color)!important}g.stateGroup rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}g.stateGroup .state-title{fill:var(--md-mermaid-label-fg-color)!important;font-family:var(--md-mermaid-font-family)}g.stateGroup .composit{fill:var(--md-mermaid-label-bg-color)}.nodeLabel,.nodeLabel p{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}a .nodeLabel{text-decoration:underline}.node circle.state-end,.node circle.state-start,.start-state{fill:var(--md-mermaid-edge-color);stroke:none}.end-state-inner,.end-state-outer{fill:var(--md-mermaid-edge-color)}.end-state-inner,.node circle.state-end{stroke:var(--md-mermaid-label-bg-color)}.transition{stroke:var(--md-mermaid-edge-color)}[id^=state-fork] rect,[id^=state-join] rect{fill:var(--md-mermaid-edge-color)!important;stroke:none!important}.statediagram-cluster.statediagram-cluster .inner{fill:var(--md-default-bg-color)}.statediagram-cluster rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}.statediagram-state rect.divider{fill:var(--md-default-fg-color--lightest);stroke:var(--md-default-fg-color--lighter)}defs #statediagram-barbEnd{stroke:var(--md-mermaid-edge-color)}.attributeBoxEven,.attributeBoxOdd{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}.entityBox{fill:var(--md-mermaid-label-bg-color);stroke:var(--md-mermaid-node-fg-color)}.entityLabel{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.relationshipLabelBox{fill:var(--md-mermaid-label-bg-color);fill-opacity:1;background-color:var(--md-mermaid-label-bg-color);opacity:1}.relationshipLabel{fill:var(--md-mermaid-label-fg-color)}.relationshipLine{stroke:var(--md-mermaid-edge-color)}defs #ONE_OR_MORE_END *,defs #ONE_OR_MORE_START *,defs #ONLY_ONE_END *,defs #ONLY_ONE_START *,defs #ZERO_OR_MORE_END *,defs #ZERO_OR_MORE_START *,defs #ZERO_OR_ONE_END *,defs #ZERO_OR_ONE_START *{stroke:var(--md-mermaid-edge-color)!important}defs #ZERO_OR_MORE_END circle,defs #ZERO_OR_MORE_START circle{fill:var(--md-mermaid-label-bg-color)}.actor{fill:var(--md-mermaid-sequence-actor-bg-color);stroke:var(--md-mermaid-sequence-actor-border-color)}text.actor>tspan{fill:var(--md-mermaid-sequence-actor-fg-color);font-family:var(--md-mermaid-font-family)}line{stroke:var(--md-mermaid-sequence-actor-line-color)}.actor-man circle,.actor-man line{fill:var(--md-mermaid-sequence-actorman-bg-color);stroke:var(--md-mermaid-sequence-actorman-line-color)}.messageLine0,.messageLine1{stroke:var(--md-mermaid-sequence-message-line-color)}.note{fill:var(--md-mermaid-sequence-note-bg-color);stroke:var(--md-mermaid-sequence-note-border-color)}.loopText,.loopText>tspan,.messageText,.noteText>tspan{stroke:none;font-family:var(--md-mermaid-font-family)!important}.messageText{fill:var(--md-mermaid-sequence-message-fg-color)}.loopText,.loopText>tspan{fill:var(--md-mermaid-sequence-loop-fg-color)}.noteText>tspan{fill:var(--md-mermaid-sequence-note-fg-color)}#arrowhead path{fill:var(--md-mermaid-sequence-message-line-color);stroke:none}.loopLine{fill:var(--md-mermaid-sequence-loop-bg-color);stroke:var(--md-mermaid-sequence-loop-border-color)}.labelBox{fill:var(--md-mermaid-sequence-label-bg-color);stroke:none}.labelText,.labelText>span{fill:var(--md-mermaid-sequence-label-fg-color);font-family:var(--md-mermaid-font-family)}.sequenceNumber{fill:var(--md-mermaid-sequence-number-fg-color)}rect.rect{fill:var(--md-mermaid-sequence-box-bg-color);stroke:none}rect.rect+text.text{fill:var(--md-mermaid-sequence-box-fg-color)}defs #sequencenumber{fill:var(--md-mermaid-sequence-number-bg-color)!important}";var Gr,Qa=0;function Ka(){return typeof mermaid=="undefined"||mermaid instanceof Element?Tt("https://unpkg.com/mermaid@11/dist/mermaid.min.js"):I(void 0)}function Wn(e){return e.classList.remove("mermaid"),Gr||(Gr=Ka().pipe(w(()=>mermaid.initialize({startOnLoad:!1,themeCSS:Un,sequence:{actorFontSize:"16px",messageFontSize:"16px",noteFontSize:"16px"}})),m(()=>{}),G(1))),Gr.subscribe(()=>co(this,null,function*(){e.classList.add("mermaid");let t=`__mermaid_${Qa++}`,r=x("div",{class:"mermaid"}),o=e.textContent,{svg:n,fn:i}=yield mermaid.render(t,o),a=r.attachShadow({mode:"closed"});a.innerHTML=n,e.replaceWith(r),i==null||i(a)})),Gr.pipe(m(()=>({ref:e})))}var Dn=x("table");function Vn(e){return e.replaceWith(Dn),Dn.replaceWith(An(e)),I({ref:e})}function Ya(e){let t=e.find(r=>r.checked)||e[0];return O(...e.map(r=>h(r,"change").pipe(m(()=>R(`label[for="${r.id}"]`))))).pipe(Q(R(`label[for="${t.id}"]`)),m(r=>({active:r})))}function Nn(e,{viewport$:t,target$:r}){let o=R(".tabbed-labels",e),n=P(":scope > input",e),i=Kr("prev");e.append(i);let a=Kr("next");return e.append(a),C(()=>{let s=new g,p=s.pipe(Z(),ie(!0));z([s,ge(e),tt(e)]).pipe(W(p),Me(1,me)).subscribe({next([{active:c},l]){let f=Ve(c),{width:u}=ce(c);e.style.setProperty("--md-indicator-x",`${f.x}px`),e.style.setProperty("--md-indicator-width",`${u}px`);let d=pr(o);(f.xd.x+l.width)&&o.scrollTo({left:Math.max(0,f.x-16),behavior:"smooth"})},complete(){e.style.removeProperty("--md-indicator-x"),e.style.removeProperty("--md-indicator-width")}}),z([Ne(o),ge(o)]).pipe(W(p)).subscribe(([c,l])=>{let f=St(o);i.hidden=c.x<16,a.hidden=c.x>f.width-l.width-16}),O(h(i,"click").pipe(m(()=>-1)),h(a,"click").pipe(m(()=>1))).pipe(W(p)).subscribe(c=>{let{width:l}=ce(o);o.scrollBy({left:l*c,behavior:"smooth"})}),r.pipe(W(p),b(c=>n.includes(c))).subscribe(c=>c.click()),o.classList.add("tabbed-labels--linked");for(let c of n){let l=R(`label[for="${c.id}"]`);l.replaceChildren(x("a",{href:`#${l.htmlFor}`,tabIndex:-1},...Array.from(l.childNodes))),h(l.firstElementChild,"click").pipe(W(p),b(f=>!(f.metaKey||f.ctrlKey)),w(f=>{f.preventDefault(),f.stopPropagation()})).subscribe(()=>{history.replaceState({},"",`#${l.htmlFor}`),l.click()})}return B("content.tabs.link")&&s.pipe(Ce(1),re(t)).subscribe(([{active:c},{offset:l}])=>{let f=c.innerText.trim();if(c.hasAttribute("data-md-switching"))c.removeAttribute("data-md-switching");else{let u=e.offsetTop-l.y;for(let y of P("[data-tabs]"))for(let L of P(":scope > input",y)){let X=R(`label[for="${L.id}"]`);if(X!==c&&X.innerText.trim()===f){X.setAttribute("data-md-switching",""),L.click();break}}window.scrollTo({top:e.offsetTop-u});let d=__md_get("__tabs")||[];__md_set("__tabs",[...new Set([f,...d])])}}),s.pipe(W(p)).subscribe(()=>{for(let c of P("audio, video",e))c.pause()}),Ya(n).pipe(w(c=>s.next(c)),_(()=>s.complete()),m(c=>$({ref:e},c)))}).pipe(Ke(se))}function zn(e,{viewport$:t,target$:r,print$:o}){return O(...P(".annotate:not(.highlight)",e).map(n=>Pn(n,{target$:r,print$:o})),...P("pre:not(.mermaid) > code",e).map(n=>jn(n,{target$:r,print$:o})),...P("pre.mermaid",e).map(n=>Wn(n)),...P("table:not([class])",e).map(n=>Vn(n)),...P("details",e).map(n=>Fn(n,{target$:r,print$:o})),...P("[data-tabs]",e).map(n=>Nn(n,{viewport$:t,target$:r})),...P("[title]",e).filter(()=>B("content.tooltips")).map(n=>mt(n,{viewport$:t})))}function Ba(e,{alert$:t}){return t.pipe(v(r=>O(I(!0),I(!1).pipe(Ge(2e3))).pipe(m(o=>({message:r,active:o})))))}function qn(e,t){let r=R(".md-typeset",e);return C(()=>{let o=new g;return o.subscribe(({message:n,active:i})=>{e.classList.toggle("md-dialog--active",i),r.textContent=n}),Ba(e,t).pipe(w(n=>o.next(n)),_(()=>o.complete()),m(n=>$({ref:e},n)))})}var Ga=0;function Ja(e,t){document.body.append(e);let{width:r}=ce(e);e.style.setProperty("--md-tooltip-width",`${r}px`),e.remove();let o=cr(t),n=typeof o!="undefined"?Ne(o):I({x:0,y:0}),i=O(et(t),$t(t)).pipe(K());return z([i,n]).pipe(m(([a,s])=>{let{x:p,y:c}=Ve(t),l=ce(t),f=t.closest("table");return f&&t.parentElement&&(p+=f.offsetLeft+t.parentElement.offsetLeft,c+=f.offsetTop+t.parentElement.offsetTop),{active:a,offset:{x:p-s.x+l.width/2-r/2,y:c-s.y+l.height+8}}}))}function Qn(e){let t=e.title;if(!t.length)return S;let r=`__tooltip_${Ga++}`,o=Rt(r,"inline"),n=R(".md-typeset",o);return n.innerHTML=t,C(()=>{let i=new g;return i.subscribe({next({offset:a}){o.style.setProperty("--md-tooltip-x",`${a.x}px`),o.style.setProperty("--md-tooltip-y",`${a.y}px`)},complete(){o.style.removeProperty("--md-tooltip-x"),o.style.removeProperty("--md-tooltip-y")}}),O(i.pipe(b(({active:a})=>a)),i.pipe(_e(250),b(({active:a})=>!a))).subscribe({next({active:a}){a?(e.insertAdjacentElement("afterend",o),e.setAttribute("aria-describedby",r),e.removeAttribute("title")):(o.remove(),e.removeAttribute("aria-describedby"),e.setAttribute("title",t))},complete(){o.remove(),e.removeAttribute("aria-describedby"),e.setAttribute("title",t)}}),i.pipe(Me(16,me)).subscribe(({active:a})=>{o.classList.toggle("md-tooltip--active",a)}),i.pipe(pt(125,me),b(()=>!!e.offsetParent),m(()=>e.offsetParent.getBoundingClientRect()),m(({x:a})=>a)).subscribe({next(a){a?o.style.setProperty("--md-tooltip-0",`${-a}px`):o.style.removeProperty("--md-tooltip-0")},complete(){o.style.removeProperty("--md-tooltip-0")}}),Ja(o,e).pipe(w(a=>i.next(a)),_(()=>i.complete()),m(a=>$({ref:e},a)))}).pipe(Ke(se))}function Xa({viewport$:e}){if(!B("header.autohide"))return I(!1);let t=e.pipe(m(({offset:{y:n}})=>n),Be(2,1),m(([n,i])=>[nMath.abs(i-n.y)>100),m(([,[n]])=>n),K()),o=ze("search");return z([e,o]).pipe(m(([{offset:n},i])=>n.y>400&&!i),K(),v(n=>n?r:I(!1)),Q(!1))}function Kn(e,t){return C(()=>z([ge(e),Xa(t)])).pipe(m(([{height:r},o])=>({height:r,hidden:o})),K((r,o)=>r.height===o.height&&r.hidden===o.hidden),G(1))}function Yn(e,{header$:t,main$:r}){return C(()=>{let o=new g,n=o.pipe(Z(),ie(!0));o.pipe(ee("active"),He(t)).subscribe(([{active:a},{hidden:s}])=>{e.classList.toggle("md-header--shadow",a&&!s),e.hidden=s});let i=ue(P("[title]",e)).pipe(b(()=>B("content.tooltips")),ne(a=>Qn(a)));return r.subscribe(o),t.pipe(W(n),m(a=>$({ref:e},a)),Re(i.pipe(W(n))))})}function Za(e,{viewport$:t,header$:r}){return mr(e,{viewport$:t,header$:r}).pipe(m(({offset:{y:o}})=>{let{height:n}=ce(e);return{active:o>=n}}),ee("active"))}function Bn(e,t){return C(()=>{let r=new g;r.subscribe({next({active:n}){e.classList.toggle("md-header__title--active",n)},complete(){e.classList.remove("md-header__title--active")}});let o=fe(".md-content h1");return typeof o=="undefined"?S:Za(o,t).pipe(w(n=>r.next(n)),_(()=>r.complete()),m(n=>$({ref:e},n)))})}function Gn(e,{viewport$:t,header$:r}){let o=r.pipe(m(({height:i})=>i),K()),n=o.pipe(v(()=>ge(e).pipe(m(({height:i})=>({top:e.offsetTop,bottom:e.offsetTop+i})),ee("bottom"))));return z([o,n,t]).pipe(m(([i,{top:a,bottom:s},{offset:{y:p},size:{height:c}}])=>(c=Math.max(0,c-Math.max(0,a-p,i)-Math.max(0,c+p-s)),{offset:a-i,height:c,active:a-i<=p})),K((i,a)=>i.offset===a.offset&&i.height===a.height&&i.active===a.active))}function es(e){let t=__md_get("__palette")||{index:e.findIndex(o=>matchMedia(o.getAttribute("data-md-color-media")).matches)},r=Math.max(0,Math.min(t.index,e.length-1));return I(...e).pipe(ne(o=>h(o,"change").pipe(m(()=>o))),Q(e[r]),m(o=>({index:e.indexOf(o),color:{media:o.getAttribute("data-md-color-media"),scheme:o.getAttribute("data-md-color-scheme"),primary:o.getAttribute("data-md-color-primary"),accent:o.getAttribute("data-md-color-accent")}})),G(1))}function Jn(e){let t=P("input",e),r=x("meta",{name:"theme-color"});document.head.appendChild(r);let o=x("meta",{name:"color-scheme"});document.head.appendChild(o);let n=Pt("(prefers-color-scheme: light)");return C(()=>{let i=new g;return i.subscribe(a=>{if(document.body.setAttribute("data-md-color-switching",""),a.color.media==="(prefers-color-scheme)"){let s=matchMedia("(prefers-color-scheme: light)"),p=document.querySelector(s.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");a.color.scheme=p.getAttribute("data-md-color-scheme"),a.color.primary=p.getAttribute("data-md-color-primary"),a.color.accent=p.getAttribute("data-md-color-accent")}for(let[s,p]of Object.entries(a.color))document.body.setAttribute(`data-md-color-${s}`,p);for(let s=0;sa.key==="Enter"),re(i,(a,s)=>s)).subscribe(({index:a})=>{a=(a+1)%t.length,t[a].click(),t[a].focus()}),i.pipe(m(()=>{let a=Se("header"),s=window.getComputedStyle(a);return o.content=s.colorScheme,s.backgroundColor.match(/\d+/g).map(p=>(+p).toString(16).padStart(2,"0")).join("")})).subscribe(a=>r.content=`#${a}`),i.pipe(ve(se)).subscribe(()=>{document.body.removeAttribute("data-md-color-switching")}),es(t).pipe(W(n.pipe(Ce(1))),ct(),w(a=>i.next(a)),_(()=>i.complete()),m(a=>$({ref:e},a)))})}function Xn(e,{progress$:t}){return C(()=>{let r=new g;return r.subscribe(({value:o})=>{e.style.setProperty("--md-progress-value",`${o}`)}),t.pipe(w(o=>r.next({value:o})),_(()=>r.complete()),m(o=>({ref:e,value:o})))})}var Jr=Mt(Br());function ts(e){e.setAttribute("data-md-copying","");let t=e.closest("[data-copy]"),r=t?t.getAttribute("data-copy"):e.innerText;return e.removeAttribute("data-md-copying"),r.trimEnd()}function Zn({alert$:e}){Jr.default.isSupported()&&new j(t=>{new Jr.default("[data-clipboard-target], [data-clipboard-text]",{text:r=>r.getAttribute("data-clipboard-text")||ts(R(r.getAttribute("data-clipboard-target")))}).on("success",r=>t.next(r))}).pipe(w(t=>{t.trigger.focus()}),m(()=>Ee("clipboard.copied"))).subscribe(e)}function ei(e,t){return e.protocol=t.protocol,e.hostname=t.hostname,e}function rs(e,t){let r=new Map;for(let o of P("url",e)){let n=R("loc",o),i=[ei(new URL(n.textContent),t)];r.set(`${i[0]}`,i);for(let a of P("[rel=alternate]",o)){let s=a.getAttribute("href");s!=null&&i.push(ei(new URL(s),t))}}return r}function ur(e){return un(new URL("sitemap.xml",e)).pipe(m(t=>rs(t,new URL(e))),de(()=>I(new Map)))}function os(e,t){if(!(e.target instanceof Element))return S;let r=e.target.closest("a");if(r===null)return S;if(r.target||e.metaKey||e.ctrlKey)return S;let o=new URL(r.href);return o.search=o.hash="",t.has(`${o}`)?(e.preventDefault(),I(new URL(r.href))):S}function ti(e){let t=new Map;for(let r of P(":scope > *",e.head))t.set(r.outerHTML,r);return t}function ri(e){for(let t of P("[href], [src]",e))for(let r of["href","src"]){let o=t.getAttribute(r);if(o&&!/^(?:[a-z]+:)?\/\//i.test(o)){t[r]=t[r];break}}return I(e)}function ns(e){for(let o of["[data-md-component=announce]","[data-md-component=container]","[data-md-component=header-topic]","[data-md-component=outdated]","[data-md-component=logo]","[data-md-component=skip]",...B("navigation.tabs.sticky")?["[data-md-component=tabs]"]:[]]){let n=fe(o),i=fe(o,e);typeof n!="undefined"&&typeof i!="undefined"&&n.replaceWith(i)}let t=ti(document);for(let[o,n]of ti(e))t.has(o)?t.delete(o):document.head.appendChild(n);for(let o of t.values()){let n=o.getAttribute("name");n!=="theme-color"&&n!=="color-scheme"&&o.remove()}let r=Se("container");return We(P("script",r)).pipe(v(o=>{let n=e.createElement("script");if(o.src){for(let i of o.getAttributeNames())n.setAttribute(i,o.getAttribute(i));return o.replaceWith(n),new j(i=>{n.onload=()=>i.complete()})}else return n.textContent=o.textContent,o.replaceWith(n),S}),Z(),ie(document))}function oi({location$:e,viewport$:t,progress$:r}){let o=xe();if(location.protocol==="file:")return S;let n=ur(o.base);I(document).subscribe(ri);let i=h(document.body,"click").pipe(He(n),v(([p,c])=>os(p,c)),pe()),a=h(window,"popstate").pipe(m(ye),pe());i.pipe(re(t)).subscribe(([p,{offset:c}])=>{history.replaceState(c,""),history.pushState(null,"",p)}),O(i,a).subscribe(e);let s=e.pipe(ee("pathname"),v(p=>fn(p,{progress$:r}).pipe(de(()=>(lt(p,!0),S)))),v(ri),v(ns),pe());return O(s.pipe(re(e,(p,c)=>c)),s.pipe(v(()=>e),ee("pathname"),v(()=>e),ee("hash")),e.pipe(K((p,c)=>p.pathname===c.pathname&&p.hash===c.hash),v(()=>i),w(()=>history.back()))).subscribe(p=>{var c,l;history.state!==null||!p.hash?window.scrollTo(0,(l=(c=history.state)==null?void 0:c.y)!=null?l:0):(history.scrollRestoration="auto",pn(p.hash),history.scrollRestoration="manual")}),e.subscribe(()=>{history.scrollRestoration="manual"}),h(window,"beforeunload").subscribe(()=>{history.scrollRestoration="auto"}),t.pipe(ee("offset"),_e(100)).subscribe(({offset:p})=>{history.replaceState(p,"")}),s}var ni=Mt(qr());function ii(e){let t=e.separator.split("|").map(n=>n.replace(/(\(\?[!=<][^)]+\))/g,"").length===0?"\uFFFD":n).join("|"),r=new RegExp(t,"img"),o=(n,i,a)=>`${i}${a}`;return n=>{n=n.replace(/[\s*+\-:~^]+/g," ").trim();let i=new RegExp(`(^|${e.separator}|)(${n.replace(/[|\\{}()[\]^$+*?.-]/g,"\\$&").replace(r,"|")})`,"img");return a=>(0,ni.default)(a).replace(i,o).replace(/<\/mark>(\s+)]*>/img,"$1")}}function jt(e){return e.type===1}function dr(e){return e.type===3}function ai(e,t){let r=yn(e);return O(I(location.protocol!=="file:"),ze("search")).pipe(Ae(o=>o),v(()=>t)).subscribe(({config:o,docs:n})=>r.next({type:0,data:{config:o,docs:n,options:{suggest:B("search.suggest")}}})),r}function si(e){var l;let{selectedVersionSitemap:t,selectedVersionBaseURL:r,currentLocation:o,currentBaseURL:n}=e,i=(l=Xr(n))==null?void 0:l.pathname;if(i===void 0)return;let a=ss(o.pathname,i);if(a===void 0)return;let s=ps(t.keys());if(!t.has(s))return;let p=Xr(a,s);if(!p||!t.has(p.href))return;let c=Xr(a,r);if(c)return c.hash=o.hash,c.search=o.search,c}function Xr(e,t){try{return new URL(e,t)}catch(r){return}}function ss(e,t){if(e.startsWith(t))return e.slice(t.length)}function cs(e,t){let r=Math.min(e.length,t.length),o;for(o=0;oS)),o=r.pipe(m(n=>{let[,i]=t.base.match(/([^/]+)\/?$/);return n.find(({version:a,aliases:s})=>a===i||s.includes(i))||n[0]}));r.pipe(m(n=>new Map(n.map(i=>[`${new URL(`../${i.version}/`,t.base)}`,i]))),v(n=>h(document.body,"click").pipe(b(i=>!i.metaKey&&!i.ctrlKey),re(o),v(([i,a])=>{if(i.target instanceof Element){let s=i.target.closest("a");if(s&&!s.target&&n.has(s.href)){let p=s.href;return!i.target.closest(".md-version")&&n.get(p)===a?S:(i.preventDefault(),I(new URL(p)))}}return S}),v(i=>ur(i).pipe(m(a=>{var s;return(s=si({selectedVersionSitemap:a,selectedVersionBaseURL:i,currentLocation:ye(),currentBaseURL:t.base}))!=null?s:i})))))).subscribe(n=>lt(n,!0)),z([r,o]).subscribe(([n,i])=>{R(".md-header__topic").appendChild(Cn(n,i))}),e.pipe(v(()=>o)).subscribe(n=>{var a;let i=__md_get("__outdated",sessionStorage);if(i===null){i=!0;let s=((a=t.version)==null?void 0:a.default)||"latest";Array.isArray(s)||(s=[s]);e:for(let p of s)for(let c of n.aliases.concat(n.version))if(new RegExp(p,"i").test(c)){i=!1;break e}__md_set("__outdated",i,sessionStorage)}if(i)for(let s of ae("outdated"))s.hidden=!1})}function ls(e,{worker$:t}){let{searchParams:r}=ye();r.has("q")&&(Je("search",!0),e.value=r.get("q"),e.focus(),ze("search").pipe(Ae(i=>!i)).subscribe(()=>{let i=ye();i.searchParams.delete("q"),history.replaceState({},"",`${i}`)}));let o=et(e),n=O(t.pipe(Ae(jt)),h(e,"keyup"),o).pipe(m(()=>e.value),K());return z([n,o]).pipe(m(([i,a])=>({value:i,focus:a})),G(1))}function pi(e,{worker$:t}){let r=new g,o=r.pipe(Z(),ie(!0));z([t.pipe(Ae(jt)),r],(i,a)=>a).pipe(ee("value")).subscribe(({value:i})=>t.next({type:2,data:i})),r.pipe(ee("focus")).subscribe(({focus:i})=>{i&&Je("search",i)}),h(e.form,"reset").pipe(W(o)).subscribe(()=>e.focus());let n=R("header [for=__search]");return h(n,"click").subscribe(()=>e.focus()),ls(e,{worker$:t}).pipe(w(i=>r.next(i)),_(()=>r.complete()),m(i=>$({ref:e},i)),G(1))}function li(e,{worker$:t,query$:r}){let o=new g,n=on(e.parentElement).pipe(b(Boolean)),i=e.parentElement,a=R(":scope > :first-child",e),s=R(":scope > :last-child",e);ze("search").subscribe(l=>s.setAttribute("role",l?"list":"presentation")),o.pipe(re(r),Wr(t.pipe(Ae(jt)))).subscribe(([{items:l},{value:f}])=>{switch(l.length){case 0:a.textContent=f.length?Ee("search.result.none"):Ee("search.result.placeholder");break;case 1:a.textContent=Ee("search.result.one");break;default:let u=sr(l.length);a.textContent=Ee("search.result.other",u)}});let p=o.pipe(w(()=>s.innerHTML=""),v(({items:l})=>O(I(...l.slice(0,10)),I(...l.slice(10)).pipe(Be(4),Vr(n),v(([f])=>f)))),m(Mn),pe());return p.subscribe(l=>s.appendChild(l)),p.pipe(ne(l=>{let f=fe("details",l);return typeof f=="undefined"?S:h(f,"toggle").pipe(W(o),m(()=>f))})).subscribe(l=>{l.open===!1&&l.offsetTop<=i.scrollTop&&i.scrollTo({top:l.offsetTop})}),t.pipe(b(dr),m(({data:l})=>l)).pipe(w(l=>o.next(l)),_(()=>o.complete()),m(l=>$({ref:e},l)))}function ms(e,{query$:t}){return t.pipe(m(({value:r})=>{let o=ye();return o.hash="",r=r.replace(/\s+/g,"+").replace(/&/g,"%26").replace(/=/g,"%3D"),o.search=`q=${r}`,{url:o}}))}function mi(e,t){let r=new g,o=r.pipe(Z(),ie(!0));return r.subscribe(({url:n})=>{e.setAttribute("data-clipboard-text",e.href),e.href=`${n}`}),h(e,"click").pipe(W(o)).subscribe(n=>n.preventDefault()),ms(e,t).pipe(w(n=>r.next(n)),_(()=>r.complete()),m(n=>$({ref:e},n)))}function fi(e,{worker$:t,keyboard$:r}){let o=new g,n=Se("search-query"),i=O(h(n,"keydown"),h(n,"focus")).pipe(ve(se),m(()=>n.value),K());return o.pipe(He(i),m(([{suggest:s},p])=>{let c=p.split(/([\s-]+)/);if(s!=null&&s.length&&c[c.length-1]){let l=s[s.length-1];l.startsWith(c[c.length-1])&&(c[c.length-1]=l)}else c.length=0;return c})).subscribe(s=>e.innerHTML=s.join("").replace(/\s/g," ")),r.pipe(b(({mode:s})=>s==="search")).subscribe(s=>{switch(s.type){case"ArrowRight":e.innerText.length&&n.selectionStart===n.value.length&&(n.value=e.innerText);break}}),t.pipe(b(dr),m(({data:s})=>s)).pipe(w(s=>o.next(s)),_(()=>o.complete()),m(()=>({ref:e})))}function ui(e,{index$:t,keyboard$:r}){let o=xe();try{let n=ai(o.search,t),i=Se("search-query",e),a=Se("search-result",e);h(e,"click").pipe(b(({target:p})=>p instanceof Element&&!!p.closest("a"))).subscribe(()=>Je("search",!1)),r.pipe(b(({mode:p})=>p==="search")).subscribe(p=>{let c=Ie();switch(p.type){case"Enter":if(c===i){let l=new Map;for(let f of P(":first-child [href]",a)){let u=f.firstElementChild;l.set(f,parseFloat(u.getAttribute("data-md-score")))}if(l.size){let[[f]]=[...l].sort(([,u],[,d])=>d-u);f.click()}p.claim()}break;case"Escape":case"Tab":Je("search",!1),i.blur();break;case"ArrowUp":case"ArrowDown":if(typeof c=="undefined")i.focus();else{let l=[i,...P(":not(details) > [href], summary, details[open] [href]",a)],f=Math.max(0,(Math.max(0,l.indexOf(c))+l.length+(p.type==="ArrowUp"?-1:1))%l.length);l[f].focus()}p.claim();break;default:i!==Ie()&&i.focus()}}),r.pipe(b(({mode:p})=>p==="global")).subscribe(p=>{switch(p.type){case"f":case"s":case"/":i.focus(),i.select(),p.claim();break}});let s=pi(i,{worker$:n});return O(s,li(a,{worker$:n,query$:s})).pipe(Re(...ae("search-share",e).map(p=>mi(p,{query$:s})),...ae("search-suggest",e).map(p=>fi(p,{worker$:n,keyboard$:r}))))}catch(n){return e.hidden=!0,Ye}}function di(e,{index$:t,location$:r}){return z([t,r.pipe(Q(ye()),b(o=>!!o.searchParams.get("h")))]).pipe(m(([o,n])=>ii(o.config)(n.searchParams.get("h"))),m(o=>{var a;let n=new Map,i=document.createNodeIterator(e,NodeFilter.SHOW_TEXT);for(let s=i.nextNode();s;s=i.nextNode())if((a=s.parentElement)!=null&&a.offsetHeight){let p=s.textContent,c=o(p);c.length>p.length&&n.set(s,c)}for(let[s,p]of n){let{childNodes:c}=x("span",null,p);s.replaceWith(...Array.from(c))}return{ref:e,nodes:n}}))}function fs(e,{viewport$:t,main$:r}){let o=e.closest(".md-grid"),n=o.offsetTop-o.parentElement.offsetTop;return z([r,t]).pipe(m(([{offset:i,height:a},{offset:{y:s}}])=>(a=a+Math.min(n,Math.max(0,s-i))-n,{height:a,locked:s>=i+n})),K((i,a)=>i.height===a.height&&i.locked===a.locked))}function Zr(e,o){var n=o,{header$:t}=n,r=so(n,["header$"]);let i=R(".md-sidebar__scrollwrap",e),{y:a}=Ve(i);return C(()=>{let s=new g,p=s.pipe(Z(),ie(!0)),c=s.pipe(Me(0,me));return c.pipe(re(t)).subscribe({next([{height:l},{height:f}]){i.style.height=`${l-2*a}px`,e.style.top=`${f}px`},complete(){i.style.height="",e.style.top=""}}),c.pipe(Ae()).subscribe(()=>{for(let l of P(".md-nav__link--active[href]",e)){if(!l.clientHeight)continue;let f=l.closest(".md-sidebar__scrollwrap");if(typeof f!="undefined"){let u=l.offsetTop-f.offsetTop,{height:d}=ce(f);f.scrollTo({top:u-d/2})}}}),ue(P("label[tabindex]",e)).pipe(ne(l=>h(l,"click").pipe(ve(se),m(()=>l),W(p)))).subscribe(l=>{let f=R(`[id="${l.htmlFor}"]`);R(`[aria-labelledby="${l.id}"]`).setAttribute("aria-expanded",`${f.checked}`)}),fs(e,r).pipe(w(l=>s.next(l)),_(()=>s.complete()),m(l=>$({ref:e},l)))})}function hi(e,t){if(typeof t!="undefined"){let r=`https://api.github.com/repos/${e}/${t}`;return st(je(`${r}/releases/latest`).pipe(de(()=>S),m(o=>({version:o.tag_name})),De({})),je(r).pipe(de(()=>S),m(o=>({stars:o.stargazers_count,forks:o.forks_count})),De({}))).pipe(m(([o,n])=>$($({},o),n)))}else{let r=`https://api.github.com/users/${e}`;return je(r).pipe(m(o=>({repositories:o.public_repos})),De({}))}}function bi(e,t){let r=`https://${e}/api/v4/projects/${encodeURIComponent(t)}`;return st(je(`${r}/releases/permalink/latest`).pipe(de(()=>S),m(({tag_name:o})=>({version:o})),De({})),je(r).pipe(de(()=>S),m(({star_count:o,forks_count:n})=>({stars:o,forks:n})),De({}))).pipe(m(([o,n])=>$($({},o),n)))}function vi(e){let t=e.match(/^.+github\.com\/([^/]+)\/?([^/]+)?/i);if(t){let[,r,o]=t;return hi(r,o)}if(t=e.match(/^.+?([^/]*gitlab[^/]+)\/(.+?)\/?$/i),t){let[,r,o]=t;return bi(r,o)}return S}var us;function ds(e){return us||(us=C(()=>{let t=__md_get("__source",sessionStorage);if(t)return I(t);if(ae("consent").length){let o=__md_get("__consent");if(!(o&&o.github))return S}return vi(e.href).pipe(w(o=>__md_set("__source",o,sessionStorage)))}).pipe(de(()=>S),b(t=>Object.keys(t).length>0),m(t=>({facts:t})),G(1)))}function gi(e){let t=R(":scope > :last-child",e);return C(()=>{let r=new g;return r.subscribe(({facts:o})=>{t.appendChild(_n(o)),t.classList.add("md-source__repository--active")}),ds(e).pipe(w(o=>r.next(o)),_(()=>r.complete()),m(o=>$({ref:e},o)))})}function hs(e,{viewport$:t,header$:r}){return ge(document.body).pipe(v(()=>mr(e,{header$:r,viewport$:t})),m(({offset:{y:o}})=>({hidden:o>=10})),ee("hidden"))}function yi(e,t){return C(()=>{let r=new g;return r.subscribe({next({hidden:o}){e.hidden=o},complete(){e.hidden=!1}}),(B("navigation.tabs.sticky")?I({hidden:!1}):hs(e,t)).pipe(w(o=>r.next(o)),_(()=>r.complete()),m(o=>$({ref:e},o)))})}function bs(e,{viewport$:t,header$:r}){let o=new Map,n=P(".md-nav__link",e);for(let s of n){let p=decodeURIComponent(s.hash.substring(1)),c=fe(`[id="${p}"]`);typeof c!="undefined"&&o.set(s,c)}let i=r.pipe(ee("height"),m(({height:s})=>{let p=Se("main"),c=R(":scope > :first-child",p);return s+.8*(c.offsetTop-p.offsetTop)}),pe());return ge(document.body).pipe(ee("height"),v(s=>C(()=>{let p=[];return I([...o].reduce((c,[l,f])=>{for(;p.length&&o.get(p[p.length-1]).tagName>=f.tagName;)p.pop();let u=f.offsetTop;for(;!u&&f.parentElement;)f=f.parentElement,u=f.offsetTop;let d=f.offsetParent;for(;d;d=d.offsetParent)u+=d.offsetTop;return c.set([...p=[...p,l]].reverse(),u)},new Map))}).pipe(m(p=>new Map([...p].sort(([,c],[,l])=>c-l))),He(i),v(([p,c])=>t.pipe(Fr(([l,f],{offset:{y:u},size:d})=>{let y=u+d.height>=Math.floor(s.height);for(;f.length;){let[,L]=f[0];if(L-c=u&&!y)f=[l.pop(),...f];else break}return[l,f]},[[],[...p]]),K((l,f)=>l[0]===f[0]&&l[1]===f[1])))))).pipe(m(([s,p])=>({prev:s.map(([c])=>c),next:p.map(([c])=>c)})),Q({prev:[],next:[]}),Be(2,1),m(([s,p])=>s.prev.length{let i=new g,a=i.pipe(Z(),ie(!0));if(i.subscribe(({prev:s,next:p})=>{for(let[c]of p)c.classList.remove("md-nav__link--passed"),c.classList.remove("md-nav__link--active");for(let[c,[l]]of s.entries())l.classList.add("md-nav__link--passed"),l.classList.toggle("md-nav__link--active",c===s.length-1)}),B("toc.follow")){let s=O(t.pipe(_e(1),m(()=>{})),t.pipe(_e(250),m(()=>"smooth")));i.pipe(b(({prev:p})=>p.length>0),He(o.pipe(ve(se))),re(s)).subscribe(([[{prev:p}],c])=>{let[l]=p[p.length-1];if(l.offsetHeight){let f=cr(l);if(typeof f!="undefined"){let u=l.offsetTop-f.offsetTop,{height:d}=ce(f);f.scrollTo({top:u-d/2,behavior:c})}}})}return B("navigation.tracking")&&t.pipe(W(a),ee("offset"),_e(250),Ce(1),W(n.pipe(Ce(1))),ct({delay:250}),re(i)).subscribe(([,{prev:s}])=>{let p=ye(),c=s[s.length-1];if(c&&c.length){let[l]=c,{hash:f}=new URL(l.href);p.hash!==f&&(p.hash=f,history.replaceState({},"",`${p}`))}else p.hash="",history.replaceState({},"",`${p}`)}),bs(e,{viewport$:t,header$:r}).pipe(w(s=>i.next(s)),_(()=>i.complete()),m(s=>$({ref:e},s)))})}function vs(e,{viewport$:t,main$:r,target$:o}){let n=t.pipe(m(({offset:{y:a}})=>a),Be(2,1),m(([a,s])=>a>s&&s>0),K()),i=r.pipe(m(({active:a})=>a));return z([i,n]).pipe(m(([a,s])=>!(a&&s)),K(),W(o.pipe(Ce(1))),ie(!0),ct({delay:250}),m(a=>({hidden:a})))}function Ei(e,{viewport$:t,header$:r,main$:o,target$:n}){let i=new g,a=i.pipe(Z(),ie(!0));return i.subscribe({next({hidden:s}){e.hidden=s,s?(e.setAttribute("tabindex","-1"),e.blur()):e.removeAttribute("tabindex")},complete(){e.style.top="",e.hidden=!0,e.removeAttribute("tabindex")}}),r.pipe(W(a),ee("height")).subscribe(({height:s})=>{e.style.top=`${s+16}px`}),h(e,"click").subscribe(s=>{s.preventDefault(),window.scrollTo({top:0})}),vs(e,{viewport$:t,main$:o,target$:n}).pipe(w(s=>i.next(s)),_(()=>i.complete()),m(s=>$({ref:e},s)))}function wi({document$:e,viewport$:t}){e.pipe(v(()=>P(".md-ellipsis")),ne(r=>tt(r).pipe(W(e.pipe(Ce(1))),b(o=>o),m(()=>r),Te(1))),b(r=>r.offsetWidth{let o=r.innerText,n=r.closest("a")||r;return n.title=o,B("content.tooltips")?mt(n,{viewport$:t}).pipe(W(e.pipe(Ce(1))),_(()=>n.removeAttribute("title"))):S})).subscribe(),B("content.tooltips")&&e.pipe(v(()=>P(".md-status")),ne(r=>mt(r,{viewport$:t}))).subscribe()}function Ti({document$:e,tablet$:t}){e.pipe(v(()=>P(".md-toggle--indeterminate")),w(r=>{r.indeterminate=!0,r.checked=!1}),ne(r=>h(r,"change").pipe(Dr(()=>r.classList.contains("md-toggle--indeterminate")),m(()=>r))),re(t)).subscribe(([r,o])=>{r.classList.remove("md-toggle--indeterminate"),o&&(r.checked=!1)})}function gs(){return/(iPad|iPhone|iPod)/.test(navigator.userAgent)}function Si({document$:e}){e.pipe(v(()=>P("[data-md-scrollfix]")),w(t=>t.removeAttribute("data-md-scrollfix")),b(gs),ne(t=>h(t,"touchstart").pipe(m(()=>t)))).subscribe(t=>{let r=t.scrollTop;r===0?t.scrollTop=1:r+t.offsetHeight===t.scrollHeight&&(t.scrollTop=r-1)})}function Oi({viewport$:e,tablet$:t}){z([ze("search"),t]).pipe(m(([r,o])=>r&&!o),v(r=>I(r).pipe(Ge(r?400:100))),re(e)).subscribe(([r,{offset:{y:o}}])=>{if(r)document.body.setAttribute("data-md-scrolllock",""),document.body.style.top=`-${o}px`;else{let n=-1*parseInt(document.body.style.top,10);document.body.removeAttribute("data-md-scrolllock"),document.body.style.top="",n&&window.scrollTo(0,n)}})}Object.entries||(Object.entries=function(e){let t=[];for(let r of Object.keys(e))t.push([r,e[r]]);return t});Object.values||(Object.values=function(e){let t=[];for(let r of Object.keys(e))t.push(e[r]);return t});typeof Element!="undefined"&&(Element.prototype.scrollTo||(Element.prototype.scrollTo=function(e,t){typeof e=="object"?(this.scrollLeft=e.left,this.scrollTop=e.top):(this.scrollLeft=e,this.scrollTop=t)}),Element.prototype.replaceWith||(Element.prototype.replaceWith=function(...e){let t=this.parentNode;if(t){e.length===0&&t.removeChild(this);for(let r=e.length-1;r>=0;r--){let o=e[r];typeof o=="string"?o=document.createTextNode(o):o.parentNode&&o.parentNode.removeChild(o),r?t.insertBefore(this.previousSibling,o):t.replaceChild(o,this)}}}));function ys(){return location.protocol==="file:"?Tt(`${new URL("search/search_index.js",eo.base)}`).pipe(m(()=>__index),G(1)):je(new URL("search/search_index.json",eo.base))}document.documentElement.classList.remove("no-js");document.documentElement.classList.add("js");var ot=Go(),Ut=sn(),Lt=ln(Ut),to=an(),Oe=gn(),hr=Pt("(min-width: 960px)"),Mi=Pt("(min-width: 1220px)"),_i=mn(),eo=xe(),Ai=document.forms.namedItem("search")?ys():Ye,ro=new g;Zn({alert$:ro});var oo=new g;B("navigation.instant")&&oi({location$:Ut,viewport$:Oe,progress$:oo}).subscribe(ot);var Li;((Li=eo.version)==null?void 0:Li.provider)==="mike"&&ci({document$:ot});O(Ut,Lt).pipe(Ge(125)).subscribe(()=>{Je("drawer",!1),Je("search",!1)});to.pipe(b(({mode:e})=>e==="global")).subscribe(e=>{switch(e.type){case"p":case",":let t=fe("link[rel=prev]");typeof t!="undefined"&<(t);break;case"n":case".":let r=fe("link[rel=next]");typeof r!="undefined"&<(r);break;case"Enter":let o=Ie();o instanceof HTMLLabelElement&&o.click()}});wi({viewport$:Oe,document$:ot});Ti({document$:ot,tablet$:hr});Si({document$:ot});Oi({viewport$:Oe,tablet$:hr});var rt=Kn(Se("header"),{viewport$:Oe}),Ft=ot.pipe(m(()=>Se("main")),v(e=>Gn(e,{viewport$:Oe,header$:rt})),G(1)),xs=O(...ae("consent").map(e=>En(e,{target$:Lt})),...ae("dialog").map(e=>qn(e,{alert$:ro})),...ae("palette").map(e=>Jn(e)),...ae("progress").map(e=>Xn(e,{progress$:oo})),...ae("search").map(e=>ui(e,{index$:Ai,keyboard$:to})),...ae("source").map(e=>gi(e))),Es=C(()=>O(...ae("announce").map(e=>xn(e)),...ae("content").map(e=>zn(e,{viewport$:Oe,target$:Lt,print$:_i})),...ae("content").map(e=>B("search.highlight")?di(e,{index$:Ai,location$:Ut}):S),...ae("header").map(e=>Yn(e,{viewport$:Oe,header$:rt,main$:Ft})),...ae("header-title").map(e=>Bn(e,{viewport$:Oe,header$:rt})),...ae("sidebar").map(e=>e.getAttribute("data-md-type")==="navigation"?Nr(Mi,()=>Zr(e,{viewport$:Oe,header$:rt,main$:Ft})):Nr(hr,()=>Zr(e,{viewport$:Oe,header$:rt,main$:Ft}))),...ae("tabs").map(e=>yi(e,{viewport$:Oe,header$:rt})),...ae("toc").map(e=>xi(e,{viewport$:Oe,header$:rt,main$:Ft,target$:Lt})),...ae("top").map(e=>Ei(e,{viewport$:Oe,header$:rt,main$:Ft,target$:Lt})))),Ci=ot.pipe(v(()=>Es),Re(xs),G(1));Ci.subscribe();window.document$=ot;window.location$=Ut;window.target$=Lt;window.keyboard$=to;window.viewport$=Oe;window.tablet$=hr;window.screen$=Mi;window.print$=_i;window.alert$=ro;window.progress$=oo;window.component$=Ci;})(); -//# sourceMappingURL=bundle.83f73b43.min.js.map - diff --git a/pr-450/assets/javascripts/bundle.83f73b43.min.js.map b/pr-450/assets/javascripts/bundle.83f73b43.min.js.map deleted file mode 100644 index fe920b7d6..000000000 --- a/pr-450/assets/javascripts/bundle.83f73b43.min.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["node_modules/focus-visible/dist/focus-visible.js", "node_modules/escape-html/index.js", "node_modules/clipboard/dist/clipboard.js", "src/templates/assets/javascripts/bundle.ts", "node_modules/tslib/tslib.es6.mjs", "node_modules/rxjs/src/internal/util/isFunction.ts", "node_modules/rxjs/src/internal/util/createErrorClass.ts", "node_modules/rxjs/src/internal/util/UnsubscriptionError.ts", "node_modules/rxjs/src/internal/util/arrRemove.ts", "node_modules/rxjs/src/internal/Subscription.ts", "node_modules/rxjs/src/internal/config.ts", "node_modules/rxjs/src/internal/scheduler/timeoutProvider.ts", "node_modules/rxjs/src/internal/util/reportUnhandledError.ts", "node_modules/rxjs/src/internal/util/noop.ts", "node_modules/rxjs/src/internal/NotificationFactories.ts", "node_modules/rxjs/src/internal/util/errorContext.ts", "node_modules/rxjs/src/internal/Subscriber.ts", "node_modules/rxjs/src/internal/symbol/observable.ts", "node_modules/rxjs/src/internal/util/identity.ts", "node_modules/rxjs/src/internal/util/pipe.ts", "node_modules/rxjs/src/internal/Observable.ts", "node_modules/rxjs/src/internal/util/lift.ts", "node_modules/rxjs/src/internal/operators/OperatorSubscriber.ts", "node_modules/rxjs/src/internal/scheduler/animationFrameProvider.ts", "node_modules/rxjs/src/internal/util/ObjectUnsubscribedError.ts", "node_modules/rxjs/src/internal/Subject.ts", "node_modules/rxjs/src/internal/BehaviorSubject.ts", "node_modules/rxjs/src/internal/scheduler/dateTimestampProvider.ts", "node_modules/rxjs/src/internal/ReplaySubject.ts", "node_modules/rxjs/src/internal/scheduler/Action.ts", "node_modules/rxjs/src/internal/scheduler/intervalProvider.ts", "node_modules/rxjs/src/internal/scheduler/AsyncAction.ts", "node_modules/rxjs/src/internal/Scheduler.ts", "node_modules/rxjs/src/internal/scheduler/AsyncScheduler.ts", "node_modules/rxjs/src/internal/scheduler/async.ts", "node_modules/rxjs/src/internal/scheduler/QueueAction.ts", "node_modules/rxjs/src/internal/scheduler/QueueScheduler.ts", "node_modules/rxjs/src/internal/scheduler/queue.ts", "node_modules/rxjs/src/internal/scheduler/AnimationFrameAction.ts", "node_modules/rxjs/src/internal/scheduler/AnimationFrameScheduler.ts", "node_modules/rxjs/src/internal/scheduler/animationFrame.ts", "node_modules/rxjs/src/internal/observable/empty.ts", "node_modules/rxjs/src/internal/util/isScheduler.ts", "node_modules/rxjs/src/internal/util/args.ts", "node_modules/rxjs/src/internal/util/isArrayLike.ts", "node_modules/rxjs/src/internal/util/isPromise.ts", "node_modules/rxjs/src/internal/util/isInteropObservable.ts", "node_modules/rxjs/src/internal/util/isAsyncIterable.ts", "node_modules/rxjs/src/internal/util/throwUnobservableError.ts", "node_modules/rxjs/src/internal/symbol/iterator.ts", "node_modules/rxjs/src/internal/util/isIterable.ts", "node_modules/rxjs/src/internal/util/isReadableStreamLike.ts", "node_modules/rxjs/src/internal/observable/innerFrom.ts", "node_modules/rxjs/src/internal/util/executeSchedule.ts", "node_modules/rxjs/src/internal/operators/observeOn.ts", "node_modules/rxjs/src/internal/operators/subscribeOn.ts", "node_modules/rxjs/src/internal/scheduled/scheduleObservable.ts", "node_modules/rxjs/src/internal/scheduled/schedulePromise.ts", "node_modules/rxjs/src/internal/scheduled/scheduleArray.ts", "node_modules/rxjs/src/internal/scheduled/scheduleIterable.ts", "node_modules/rxjs/src/internal/scheduled/scheduleAsyncIterable.ts", "node_modules/rxjs/src/internal/scheduled/scheduleReadableStreamLike.ts", "node_modules/rxjs/src/internal/scheduled/scheduled.ts", "node_modules/rxjs/src/internal/observable/from.ts", "node_modules/rxjs/src/internal/observable/of.ts", "node_modules/rxjs/src/internal/observable/throwError.ts", "node_modules/rxjs/src/internal/util/EmptyError.ts", "node_modules/rxjs/src/internal/util/isDate.ts", "node_modules/rxjs/src/internal/operators/map.ts", "node_modules/rxjs/src/internal/util/mapOneOrManyArgs.ts", "node_modules/rxjs/src/internal/util/argsArgArrayOrObject.ts", "node_modules/rxjs/src/internal/util/createObject.ts", "node_modules/rxjs/src/internal/observable/combineLatest.ts", "node_modules/rxjs/src/internal/operators/mergeInternals.ts", "node_modules/rxjs/src/internal/operators/mergeMap.ts", "node_modules/rxjs/src/internal/operators/mergeAll.ts", "node_modules/rxjs/src/internal/operators/concatAll.ts", "node_modules/rxjs/src/internal/observable/concat.ts", "node_modules/rxjs/src/internal/observable/defer.ts", "node_modules/rxjs/src/internal/observable/fromEvent.ts", "node_modules/rxjs/src/internal/observable/fromEventPattern.ts", "node_modules/rxjs/src/internal/observable/timer.ts", "node_modules/rxjs/src/internal/observable/merge.ts", "node_modules/rxjs/src/internal/observable/never.ts", "node_modules/rxjs/src/internal/util/argsOrArgArray.ts", "node_modules/rxjs/src/internal/operators/filter.ts", "node_modules/rxjs/src/internal/observable/zip.ts", "node_modules/rxjs/src/internal/operators/audit.ts", "node_modules/rxjs/src/internal/operators/auditTime.ts", "node_modules/rxjs/src/internal/operators/bufferCount.ts", "node_modules/rxjs/src/internal/operators/catchError.ts", "node_modules/rxjs/src/internal/operators/scanInternals.ts", "node_modules/rxjs/src/internal/operators/combineLatest.ts", "node_modules/rxjs/src/internal/operators/combineLatestWith.ts", "node_modules/rxjs/src/internal/operators/debounce.ts", "node_modules/rxjs/src/internal/operators/debounceTime.ts", "node_modules/rxjs/src/internal/operators/defaultIfEmpty.ts", "node_modules/rxjs/src/internal/operators/take.ts", "node_modules/rxjs/src/internal/operators/ignoreElements.ts", "node_modules/rxjs/src/internal/operators/mapTo.ts", "node_modules/rxjs/src/internal/operators/delayWhen.ts", "node_modules/rxjs/src/internal/operators/delay.ts", "node_modules/rxjs/src/internal/operators/distinctUntilChanged.ts", "node_modules/rxjs/src/internal/operators/distinctUntilKeyChanged.ts", "node_modules/rxjs/src/internal/operators/throwIfEmpty.ts", "node_modules/rxjs/src/internal/operators/endWith.ts", "node_modules/rxjs/src/internal/operators/finalize.ts", "node_modules/rxjs/src/internal/operators/first.ts", "node_modules/rxjs/src/internal/operators/takeLast.ts", "node_modules/rxjs/src/internal/operators/merge.ts", "node_modules/rxjs/src/internal/operators/mergeWith.ts", "node_modules/rxjs/src/internal/operators/repeat.ts", "node_modules/rxjs/src/internal/operators/scan.ts", "node_modules/rxjs/src/internal/operators/share.ts", "node_modules/rxjs/src/internal/operators/shareReplay.ts", "node_modules/rxjs/src/internal/operators/skip.ts", "node_modules/rxjs/src/internal/operators/skipUntil.ts", "node_modules/rxjs/src/internal/operators/startWith.ts", "node_modules/rxjs/src/internal/operators/switchMap.ts", "node_modules/rxjs/src/internal/operators/takeUntil.ts", "node_modules/rxjs/src/internal/operators/takeWhile.ts", "node_modules/rxjs/src/internal/operators/tap.ts", "node_modules/rxjs/src/internal/operators/throttle.ts", "node_modules/rxjs/src/internal/operators/throttleTime.ts", "node_modules/rxjs/src/internal/operators/withLatestFrom.ts", "node_modules/rxjs/src/internal/operators/zip.ts", "node_modules/rxjs/src/internal/operators/zipWith.ts", "src/templates/assets/javascripts/browser/document/index.ts", "src/templates/assets/javascripts/browser/element/_/index.ts", "src/templates/assets/javascripts/browser/element/focus/index.ts", "src/templates/assets/javascripts/browser/element/hover/index.ts", "src/templates/assets/javascripts/utilities/h/index.ts", "src/templates/assets/javascripts/utilities/round/index.ts", "src/templates/assets/javascripts/browser/script/index.ts", "src/templates/assets/javascripts/browser/element/size/_/index.ts", "src/templates/assets/javascripts/browser/element/size/content/index.ts", "src/templates/assets/javascripts/browser/element/offset/_/index.ts", "src/templates/assets/javascripts/browser/element/offset/content/index.ts", "src/templates/assets/javascripts/browser/element/visibility/index.ts", "src/templates/assets/javascripts/browser/toggle/index.ts", "src/templates/assets/javascripts/browser/keyboard/index.ts", "src/templates/assets/javascripts/browser/location/_/index.ts", "src/templates/assets/javascripts/browser/location/hash/index.ts", "src/templates/assets/javascripts/browser/media/index.ts", "src/templates/assets/javascripts/browser/request/index.ts", "src/templates/assets/javascripts/browser/viewport/offset/index.ts", "src/templates/assets/javascripts/browser/viewport/size/index.ts", "src/templates/assets/javascripts/browser/viewport/_/index.ts", "src/templates/assets/javascripts/browser/viewport/at/index.ts", "src/templates/assets/javascripts/browser/worker/index.ts", "src/templates/assets/javascripts/_/index.ts", "src/templates/assets/javascripts/components/_/index.ts", "src/templates/assets/javascripts/components/announce/index.ts", "src/templates/assets/javascripts/components/consent/index.ts", "src/templates/assets/javascripts/templates/tooltip/index.tsx", "src/templates/assets/javascripts/templates/annotation/index.tsx", "src/templates/assets/javascripts/templates/clipboard/index.tsx", "src/templates/assets/javascripts/templates/search/index.tsx", "src/templates/assets/javascripts/templates/source/index.tsx", "src/templates/assets/javascripts/templates/tabbed/index.tsx", "src/templates/assets/javascripts/templates/table/index.tsx", "src/templates/assets/javascripts/templates/version/index.tsx", "src/templates/assets/javascripts/components/tooltip2/index.ts", "src/templates/assets/javascripts/components/content/annotation/_/index.ts", "src/templates/assets/javascripts/components/content/annotation/list/index.ts", "src/templates/assets/javascripts/components/content/annotation/block/index.ts", "src/templates/assets/javascripts/components/content/code/_/index.ts", "src/templates/assets/javascripts/components/content/details/index.ts", "src/templates/assets/javascripts/components/content/mermaid/index.css", "src/templates/assets/javascripts/components/content/mermaid/index.ts", "src/templates/assets/javascripts/components/content/table/index.ts", "src/templates/assets/javascripts/components/content/tabs/index.ts", "src/templates/assets/javascripts/components/content/_/index.ts", "src/templates/assets/javascripts/components/dialog/index.ts", "src/templates/assets/javascripts/components/tooltip/index.ts", "src/templates/assets/javascripts/components/header/_/index.ts", "src/templates/assets/javascripts/components/header/title/index.ts", "src/templates/assets/javascripts/components/main/index.ts", "src/templates/assets/javascripts/components/palette/index.ts", "src/templates/assets/javascripts/components/progress/index.ts", "src/templates/assets/javascripts/integrations/clipboard/index.ts", "src/templates/assets/javascripts/integrations/sitemap/index.ts", "src/templates/assets/javascripts/integrations/instant/index.ts", "src/templates/assets/javascripts/integrations/search/highlighter/index.ts", "src/templates/assets/javascripts/integrations/search/worker/message/index.ts", "src/templates/assets/javascripts/integrations/search/worker/_/index.ts", "src/templates/assets/javascripts/integrations/version/findurl/index.ts", "src/templates/assets/javascripts/integrations/version/index.ts", "src/templates/assets/javascripts/components/search/query/index.ts", "src/templates/assets/javascripts/components/search/result/index.ts", "src/templates/assets/javascripts/components/search/share/index.ts", "src/templates/assets/javascripts/components/search/suggest/index.ts", "src/templates/assets/javascripts/components/search/_/index.ts", "src/templates/assets/javascripts/components/search/highlight/index.ts", "src/templates/assets/javascripts/components/sidebar/index.ts", "src/templates/assets/javascripts/components/source/facts/github/index.ts", "src/templates/assets/javascripts/components/source/facts/gitlab/index.ts", "src/templates/assets/javascripts/components/source/facts/_/index.ts", "src/templates/assets/javascripts/components/source/_/index.ts", "src/templates/assets/javascripts/components/tabs/index.ts", "src/templates/assets/javascripts/components/toc/index.ts", "src/templates/assets/javascripts/components/top/index.ts", "src/templates/assets/javascripts/patches/ellipsis/index.ts", "src/templates/assets/javascripts/patches/indeterminate/index.ts", "src/templates/assets/javascripts/patches/scrollfix/index.ts", "src/templates/assets/javascripts/patches/scrolllock/index.ts", "src/templates/assets/javascripts/polyfills/index.ts"], - "sourcesContent": ["(function (global, factory) {\n typeof exports === 'object' && typeof module !== 'undefined' ? factory() :\n typeof define === 'function' && define.amd ? define(factory) :\n (factory());\n}(this, (function () { 'use strict';\n\n /**\n * Applies the :focus-visible polyfill at the given scope.\n * A scope in this case is either the top-level Document or a Shadow Root.\n *\n * @param {(Document|ShadowRoot)} scope\n * @see https://github.com/WICG/focus-visible\n */\n function applyFocusVisiblePolyfill(scope) {\n var hadKeyboardEvent = true;\n var hadFocusVisibleRecently = false;\n var hadFocusVisibleRecentlyTimeout = null;\n\n var inputTypesAllowlist = {\n text: true,\n search: true,\n url: true,\n tel: true,\n email: true,\n password: true,\n number: true,\n date: true,\n month: true,\n week: true,\n time: true,\n datetime: true,\n 'datetime-local': true\n };\n\n /**\n * Helper function for legacy browsers and iframes which sometimes focus\n * elements like document, body, and non-interactive SVG.\n * @param {Element} el\n */\n function isValidFocusTarget(el) {\n if (\n el &&\n el !== document &&\n el.nodeName !== 'HTML' &&\n el.nodeName !== 'BODY' &&\n 'classList' in el &&\n 'contains' in el.classList\n ) {\n return true;\n }\n return false;\n }\n\n /**\n * Computes whether the given element should automatically trigger the\n * `focus-visible` class being added, i.e. whether it should always match\n * `:focus-visible` when focused.\n * @param {Element} el\n * @return {boolean}\n */\n function focusTriggersKeyboardModality(el) {\n var type = el.type;\n var tagName = el.tagName;\n\n if (tagName === 'INPUT' && inputTypesAllowlist[type] && !el.readOnly) {\n return true;\n }\n\n if (tagName === 'TEXTAREA' && !el.readOnly) {\n return true;\n }\n\n if (el.isContentEditable) {\n return true;\n }\n\n return false;\n }\n\n /**\n * Add the `focus-visible` class to the given element if it was not added by\n * the author.\n * @param {Element} el\n */\n function addFocusVisibleClass(el) {\n if (el.classList.contains('focus-visible')) {\n return;\n }\n el.classList.add('focus-visible');\n el.setAttribute('data-focus-visible-added', '');\n }\n\n /**\n * Remove the `focus-visible` class from the given element if it was not\n * originally added by the author.\n * @param {Element} el\n */\n function removeFocusVisibleClass(el) {\n if (!el.hasAttribute('data-focus-visible-added')) {\n return;\n }\n el.classList.remove('focus-visible');\n el.removeAttribute('data-focus-visible-added');\n }\n\n /**\n * If the most recent user interaction was via the keyboard;\n * and the key press did not include a meta, alt/option, or control key;\n * then the modality is keyboard. Otherwise, the modality is not keyboard.\n * Apply `focus-visible` to any current active element and keep track\n * of our keyboard modality state with `hadKeyboardEvent`.\n * @param {KeyboardEvent} e\n */\n function onKeyDown(e) {\n if (e.metaKey || e.altKey || e.ctrlKey) {\n return;\n }\n\n if (isValidFocusTarget(scope.activeElement)) {\n addFocusVisibleClass(scope.activeElement);\n }\n\n hadKeyboardEvent = true;\n }\n\n /**\n * If at any point a user clicks with a pointing device, ensure that we change\n * the modality away from keyboard.\n * This avoids the situation where a user presses a key on an already focused\n * element, and then clicks on a different element, focusing it with a\n * pointing device, while we still think we're in keyboard modality.\n * @param {Event} e\n */\n function onPointerDown(e) {\n hadKeyboardEvent = false;\n }\n\n /**\n * On `focus`, add the `focus-visible` class to the target if:\n * - the target received focus as a result of keyboard navigation, or\n * - the event target is an element that will likely require interaction\n * via the keyboard (e.g. a text box)\n * @param {Event} e\n */\n function onFocus(e) {\n // Prevent IE from focusing the document or HTML element.\n if (!isValidFocusTarget(e.target)) {\n return;\n }\n\n if (hadKeyboardEvent || focusTriggersKeyboardModality(e.target)) {\n addFocusVisibleClass(e.target);\n }\n }\n\n /**\n * On `blur`, remove the `focus-visible` class from the target.\n * @param {Event} e\n */\n function onBlur(e) {\n if (!isValidFocusTarget(e.target)) {\n return;\n }\n\n if (\n e.target.classList.contains('focus-visible') ||\n e.target.hasAttribute('data-focus-visible-added')\n ) {\n // To detect a tab/window switch, we look for a blur event followed\n // rapidly by a visibility change.\n // If we don't see a visibility change within 100ms, it's probably a\n // regular focus change.\n hadFocusVisibleRecently = true;\n window.clearTimeout(hadFocusVisibleRecentlyTimeout);\n hadFocusVisibleRecentlyTimeout = window.setTimeout(function() {\n hadFocusVisibleRecently = false;\n }, 100);\n removeFocusVisibleClass(e.target);\n }\n }\n\n /**\n * If the user changes tabs, keep track of whether or not the previously\n * focused element had .focus-visible.\n * @param {Event} e\n */\n function onVisibilityChange(e) {\n if (document.visibilityState === 'hidden') {\n // If the tab becomes active again, the browser will handle calling focus\n // on the element (Safari actually calls it twice).\n // If this tab change caused a blur on an element with focus-visible,\n // re-apply the class when the user switches back to the tab.\n if (hadFocusVisibleRecently) {\n hadKeyboardEvent = true;\n }\n addInitialPointerMoveListeners();\n }\n }\n\n /**\n * Add a group of listeners to detect usage of any pointing devices.\n * These listeners will be added when the polyfill first loads, and anytime\n * the window is blurred, so that they are active when the window regains\n * focus.\n */\n function addInitialPointerMoveListeners() {\n document.addEventListener('mousemove', onInitialPointerMove);\n document.addEventListener('mousedown', onInitialPointerMove);\n document.addEventListener('mouseup', onInitialPointerMove);\n document.addEventListener('pointermove', onInitialPointerMove);\n document.addEventListener('pointerdown', onInitialPointerMove);\n document.addEventListener('pointerup', onInitialPointerMove);\n document.addEventListener('touchmove', onInitialPointerMove);\n document.addEventListener('touchstart', onInitialPointerMove);\n document.addEventListener('touchend', onInitialPointerMove);\n }\n\n function removeInitialPointerMoveListeners() {\n document.removeEventListener('mousemove', onInitialPointerMove);\n document.removeEventListener('mousedown', onInitialPointerMove);\n document.removeEventListener('mouseup', onInitialPointerMove);\n document.removeEventListener('pointermove', onInitialPointerMove);\n document.removeEventListener('pointerdown', onInitialPointerMove);\n document.removeEventListener('pointerup', onInitialPointerMove);\n document.removeEventListener('touchmove', onInitialPointerMove);\n document.removeEventListener('touchstart', onInitialPointerMove);\n document.removeEventListener('touchend', onInitialPointerMove);\n }\n\n /**\n * When the polfyill first loads, assume the user is in keyboard modality.\n * If any event is received from a pointing device (e.g. mouse, pointer,\n * touch), turn off keyboard modality.\n * This accounts for situations where focus enters the page from the URL bar.\n * @param {Event} e\n */\n function onInitialPointerMove(e) {\n // Work around a Safari quirk that fires a mousemove on whenever the\n // window blurs, even if you're tabbing out of the page. \u00AF\\_(\u30C4)_/\u00AF\n if (e.target.nodeName && e.target.nodeName.toLowerCase() === 'html') {\n return;\n }\n\n hadKeyboardEvent = false;\n removeInitialPointerMoveListeners();\n }\n\n // For some kinds of state, we are interested in changes at the global scope\n // only. For example, global pointer input, global key presses and global\n // visibility change should affect the state at every scope:\n document.addEventListener('keydown', onKeyDown, true);\n document.addEventListener('mousedown', onPointerDown, true);\n document.addEventListener('pointerdown', onPointerDown, true);\n document.addEventListener('touchstart', onPointerDown, true);\n document.addEventListener('visibilitychange', onVisibilityChange, true);\n\n addInitialPointerMoveListeners();\n\n // For focus and blur, we specifically care about state changes in the local\n // scope. This is because focus / blur events that originate from within a\n // shadow root are not re-dispatched from the host element if it was already\n // the active element in its own scope:\n scope.addEventListener('focus', onFocus, true);\n scope.addEventListener('blur', onBlur, true);\n\n // We detect that a node is a ShadowRoot by ensuring that it is a\n // DocumentFragment and also has a host property. This check covers native\n // implementation and polyfill implementation transparently. If we only cared\n // about the native implementation, we could just check if the scope was\n // an instance of a ShadowRoot.\n if (scope.nodeType === Node.DOCUMENT_FRAGMENT_NODE && scope.host) {\n // Since a ShadowRoot is a special kind of DocumentFragment, it does not\n // have a root element to add a class to. So, we add this attribute to the\n // host element instead:\n scope.host.setAttribute('data-js-focus-visible', '');\n } else if (scope.nodeType === Node.DOCUMENT_NODE) {\n document.documentElement.classList.add('js-focus-visible');\n document.documentElement.setAttribute('data-js-focus-visible', '');\n }\n }\n\n // It is important to wrap all references to global window and document in\n // these checks to support server-side rendering use cases\n // @see https://github.com/WICG/focus-visible/issues/199\n if (typeof window !== 'undefined' && typeof document !== 'undefined') {\n // Make the polyfill helper globally available. This can be used as a signal\n // to interested libraries that wish to coordinate with the polyfill for e.g.,\n // applying the polyfill to a shadow root:\n window.applyFocusVisiblePolyfill = applyFocusVisiblePolyfill;\n\n // Notify interested libraries of the polyfill's presence, in case the\n // polyfill was loaded lazily:\n var event;\n\n try {\n event = new CustomEvent('focus-visible-polyfill-ready');\n } catch (error) {\n // IE11 does not support using CustomEvent as a constructor directly:\n event = document.createEvent('CustomEvent');\n event.initCustomEvent('focus-visible-polyfill-ready', false, false, {});\n }\n\n window.dispatchEvent(event);\n }\n\n if (typeof document !== 'undefined') {\n // Apply the polyfill to the global document, so that no JavaScript\n // coordination is required to use the polyfill in the top-level document:\n applyFocusVisiblePolyfill(document);\n }\n\n})));\n", "/*!\n * escape-html\n * Copyright(c) 2012-2013 TJ Holowaychuk\n * Copyright(c) 2015 Andreas Lubbe\n * Copyright(c) 2015 Tiancheng \"Timothy\" Gu\n * MIT Licensed\n */\n\n'use strict';\n\n/**\n * Module variables.\n * @private\n */\n\nvar matchHtmlRegExp = /[\"'&<>]/;\n\n/**\n * Module exports.\n * @public\n */\n\nmodule.exports = escapeHtml;\n\n/**\n * Escape special characters in the given string of html.\n *\n * @param {string} string The string to escape for inserting into HTML\n * @return {string}\n * @public\n */\n\nfunction escapeHtml(string) {\n var str = '' + string;\n var match = matchHtmlRegExp.exec(str);\n\n if (!match) {\n return str;\n }\n\n var escape;\n var html = '';\n var index = 0;\n var lastIndex = 0;\n\n for (index = match.index; index < str.length; index++) {\n switch (str.charCodeAt(index)) {\n case 34: // \"\n escape = '"';\n break;\n case 38: // &\n escape = '&';\n break;\n case 39: // '\n escape = ''';\n break;\n case 60: // <\n escape = '<';\n break;\n case 62: // >\n escape = '>';\n break;\n default:\n continue;\n }\n\n if (lastIndex !== index) {\n html += str.substring(lastIndex, index);\n }\n\n lastIndex = index + 1;\n html += escape;\n }\n\n return lastIndex !== index\n ? html + str.substring(lastIndex, index)\n : html;\n}\n", "/*!\n * clipboard.js v2.0.11\n * https://clipboardjs.com/\n *\n * Licensed MIT \u00A9 Zeno Rocha\n */\n(function webpackUniversalModuleDefinition(root, factory) {\n\tif(typeof exports === 'object' && typeof module === 'object')\n\t\tmodule.exports = factory();\n\telse if(typeof define === 'function' && define.amd)\n\t\tdefine([], factory);\n\telse if(typeof exports === 'object')\n\t\texports[\"ClipboardJS\"] = factory();\n\telse\n\t\troot[\"ClipboardJS\"] = factory();\n})(this, function() {\nreturn /******/ (function() { // webpackBootstrap\n/******/ \tvar __webpack_modules__ = ({\n\n/***/ 686:\n/***/ (function(__unused_webpack_module, __webpack_exports__, __webpack_require__) {\n\n\"use strict\";\n\n// EXPORTS\n__webpack_require__.d(__webpack_exports__, {\n \"default\": function() { return /* binding */ clipboard; }\n});\n\n// EXTERNAL MODULE: ./node_modules/tiny-emitter/index.js\nvar tiny_emitter = __webpack_require__(279);\nvar tiny_emitter_default = /*#__PURE__*/__webpack_require__.n(tiny_emitter);\n// EXTERNAL MODULE: ./node_modules/good-listener/src/listen.js\nvar listen = __webpack_require__(370);\nvar listen_default = /*#__PURE__*/__webpack_require__.n(listen);\n// EXTERNAL MODULE: ./node_modules/select/src/select.js\nvar src_select = __webpack_require__(817);\nvar select_default = /*#__PURE__*/__webpack_require__.n(src_select);\n;// CONCATENATED MODULE: ./src/common/command.js\n/**\n * Executes a given operation type.\n * @param {String} type\n * @return {Boolean}\n */\nfunction command(type) {\n try {\n return document.execCommand(type);\n } catch (err) {\n return false;\n }\n}\n;// CONCATENATED MODULE: ./src/actions/cut.js\n\n\n/**\n * Cut action wrapper.\n * @param {String|HTMLElement} target\n * @return {String}\n */\n\nvar ClipboardActionCut = function ClipboardActionCut(target) {\n var selectedText = select_default()(target);\n command('cut');\n return selectedText;\n};\n\n/* harmony default export */ var actions_cut = (ClipboardActionCut);\n;// CONCATENATED MODULE: ./src/common/create-fake-element.js\n/**\n * Creates a fake textarea element with a value.\n * @param {String} value\n * @return {HTMLElement}\n */\nfunction createFakeElement(value) {\n var isRTL = document.documentElement.getAttribute('dir') === 'rtl';\n var fakeElement = document.createElement('textarea'); // Prevent zooming on iOS\n\n fakeElement.style.fontSize = '12pt'; // Reset box model\n\n fakeElement.style.border = '0';\n fakeElement.style.padding = '0';\n fakeElement.style.margin = '0'; // Move element out of screen horizontally\n\n fakeElement.style.position = 'absolute';\n fakeElement.style[isRTL ? 'right' : 'left'] = '-9999px'; // Move element to the same position vertically\n\n var yPosition = window.pageYOffset || document.documentElement.scrollTop;\n fakeElement.style.top = \"\".concat(yPosition, \"px\");\n fakeElement.setAttribute('readonly', '');\n fakeElement.value = value;\n return fakeElement;\n}\n;// CONCATENATED MODULE: ./src/actions/copy.js\n\n\n\n/**\n * Create fake copy action wrapper using a fake element.\n * @param {String} target\n * @param {Object} options\n * @return {String}\n */\n\nvar fakeCopyAction = function fakeCopyAction(value, options) {\n var fakeElement = createFakeElement(value);\n options.container.appendChild(fakeElement);\n var selectedText = select_default()(fakeElement);\n command('copy');\n fakeElement.remove();\n return selectedText;\n};\n/**\n * Copy action wrapper.\n * @param {String|HTMLElement} target\n * @param {Object} options\n * @return {String}\n */\n\n\nvar ClipboardActionCopy = function ClipboardActionCopy(target) {\n var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {\n container: document.body\n };\n var selectedText = '';\n\n if (typeof target === 'string') {\n selectedText = fakeCopyAction(target, options);\n } else if (target instanceof HTMLInputElement && !['text', 'search', 'url', 'tel', 'password'].includes(target === null || target === void 0 ? void 0 : target.type)) {\n // If input type doesn't support `setSelectionRange`. Simulate it. https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange\n selectedText = fakeCopyAction(target.value, options);\n } else {\n selectedText = select_default()(target);\n command('copy');\n }\n\n return selectedText;\n};\n\n/* harmony default export */ var actions_copy = (ClipboardActionCopy);\n;// CONCATENATED MODULE: ./src/actions/default.js\nfunction _typeof(obj) { \"@babel/helpers - typeof\"; if (typeof Symbol === \"function\" && typeof Symbol.iterator === \"symbol\") { _typeof = function _typeof(obj) { return typeof obj; }; } else { _typeof = function _typeof(obj) { return obj && typeof Symbol === \"function\" && obj.constructor === Symbol && obj !== Symbol.prototype ? \"symbol\" : typeof obj; }; } return _typeof(obj); }\n\n\n\n/**\n * Inner function which performs selection from either `text` or `target`\n * properties and then executes copy or cut operations.\n * @param {Object} options\n */\n\nvar ClipboardActionDefault = function ClipboardActionDefault() {\n var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};\n // Defines base properties passed from constructor.\n var _options$action = options.action,\n action = _options$action === void 0 ? 'copy' : _options$action,\n container = options.container,\n target = options.target,\n text = options.text; // Sets the `action` to be performed which can be either 'copy' or 'cut'.\n\n if (action !== 'copy' && action !== 'cut') {\n throw new Error('Invalid \"action\" value, use either \"copy\" or \"cut\"');\n } // Sets the `target` property using an element that will be have its content copied.\n\n\n if (target !== undefined) {\n if (target && _typeof(target) === 'object' && target.nodeType === 1) {\n if (action === 'copy' && target.hasAttribute('disabled')) {\n throw new Error('Invalid \"target\" attribute. Please use \"readonly\" instead of \"disabled\" attribute');\n }\n\n if (action === 'cut' && (target.hasAttribute('readonly') || target.hasAttribute('disabled'))) {\n throw new Error('Invalid \"target\" attribute. You can\\'t cut text from elements with \"readonly\" or \"disabled\" attributes');\n }\n } else {\n throw new Error('Invalid \"target\" value, use a valid Element');\n }\n } // Define selection strategy based on `text` property.\n\n\n if (text) {\n return actions_copy(text, {\n container: container\n });\n } // Defines which selection strategy based on `target` property.\n\n\n if (target) {\n return action === 'cut' ? actions_cut(target) : actions_copy(target, {\n container: container\n });\n }\n};\n\n/* harmony default export */ var actions_default = (ClipboardActionDefault);\n;// CONCATENATED MODULE: ./src/clipboard.js\nfunction clipboard_typeof(obj) { \"@babel/helpers - typeof\"; if (typeof Symbol === \"function\" && typeof Symbol.iterator === \"symbol\") { clipboard_typeof = function _typeof(obj) { return typeof obj; }; } else { clipboard_typeof = function _typeof(obj) { return obj && typeof Symbol === \"function\" && obj.constructor === Symbol && obj !== Symbol.prototype ? \"symbol\" : typeof obj; }; } return clipboard_typeof(obj); }\n\nfunction _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError(\"Cannot call a class as a function\"); } }\n\nfunction _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if (\"value\" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } }\n\nfunction _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); return Constructor; }\n\nfunction _inherits(subClass, superClass) { if (typeof superClass !== \"function\" && superClass !== null) { throw new TypeError(\"Super expression must either be null or a function\"); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, writable: true, configurable: true } }); if (superClass) _setPrototypeOf(subClass, superClass); }\n\nfunction _setPrototypeOf(o, p) { _setPrototypeOf = Object.setPrototypeOf || function _setPrototypeOf(o, p) { o.__proto__ = p; return o; }; return _setPrototypeOf(o, p); }\n\nfunction _createSuper(Derived) { var hasNativeReflectConstruct = _isNativeReflectConstruct(); return function _createSuperInternal() { var Super = _getPrototypeOf(Derived), result; if (hasNativeReflectConstruct) { var NewTarget = _getPrototypeOf(this).constructor; result = Reflect.construct(Super, arguments, NewTarget); } else { result = Super.apply(this, arguments); } return _possibleConstructorReturn(this, result); }; }\n\nfunction _possibleConstructorReturn(self, call) { if (call && (clipboard_typeof(call) === \"object\" || typeof call === \"function\")) { return call; } return _assertThisInitialized(self); }\n\nfunction _assertThisInitialized(self) { if (self === void 0) { throw new ReferenceError(\"this hasn't been initialised - super() hasn't been called\"); } return self; }\n\nfunction _isNativeReflectConstruct() { if (typeof Reflect === \"undefined\" || !Reflect.construct) return false; if (Reflect.construct.sham) return false; if (typeof Proxy === \"function\") return true; try { Date.prototype.toString.call(Reflect.construct(Date, [], function () {})); return true; } catch (e) { return false; } }\n\nfunction _getPrototypeOf(o) { _getPrototypeOf = Object.setPrototypeOf ? Object.getPrototypeOf : function _getPrototypeOf(o) { return o.__proto__ || Object.getPrototypeOf(o); }; return _getPrototypeOf(o); }\n\n\n\n\n\n\n/**\n * Helper function to retrieve attribute value.\n * @param {String} suffix\n * @param {Element} element\n */\n\nfunction getAttributeValue(suffix, element) {\n var attribute = \"data-clipboard-\".concat(suffix);\n\n if (!element.hasAttribute(attribute)) {\n return;\n }\n\n return element.getAttribute(attribute);\n}\n/**\n * Base class which takes one or more elements, adds event listeners to them,\n * and instantiates a new `ClipboardAction` on each click.\n */\n\n\nvar Clipboard = /*#__PURE__*/function (_Emitter) {\n _inherits(Clipboard, _Emitter);\n\n var _super = _createSuper(Clipboard);\n\n /**\n * @param {String|HTMLElement|HTMLCollection|NodeList} trigger\n * @param {Object} options\n */\n function Clipboard(trigger, options) {\n var _this;\n\n _classCallCheck(this, Clipboard);\n\n _this = _super.call(this);\n\n _this.resolveOptions(options);\n\n _this.listenClick(trigger);\n\n return _this;\n }\n /**\n * Defines if attributes would be resolved using internal setter functions\n * or custom functions that were passed in the constructor.\n * @param {Object} options\n */\n\n\n _createClass(Clipboard, [{\n key: \"resolveOptions\",\n value: function resolveOptions() {\n var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};\n this.action = typeof options.action === 'function' ? options.action : this.defaultAction;\n this.target = typeof options.target === 'function' ? options.target : this.defaultTarget;\n this.text = typeof options.text === 'function' ? options.text : this.defaultText;\n this.container = clipboard_typeof(options.container) === 'object' ? options.container : document.body;\n }\n /**\n * Adds a click event listener to the passed trigger.\n * @param {String|HTMLElement|HTMLCollection|NodeList} trigger\n */\n\n }, {\n key: \"listenClick\",\n value: function listenClick(trigger) {\n var _this2 = this;\n\n this.listener = listen_default()(trigger, 'click', function (e) {\n return _this2.onClick(e);\n });\n }\n /**\n * Defines a new `ClipboardAction` on each click event.\n * @param {Event} e\n */\n\n }, {\n key: \"onClick\",\n value: function onClick(e) {\n var trigger = e.delegateTarget || e.currentTarget;\n var action = this.action(trigger) || 'copy';\n var text = actions_default({\n action: action,\n container: this.container,\n target: this.target(trigger),\n text: this.text(trigger)\n }); // Fires an event based on the copy operation result.\n\n this.emit(text ? 'success' : 'error', {\n action: action,\n text: text,\n trigger: trigger,\n clearSelection: function clearSelection() {\n if (trigger) {\n trigger.focus();\n }\n\n window.getSelection().removeAllRanges();\n }\n });\n }\n /**\n * Default `action` lookup function.\n * @param {Element} trigger\n */\n\n }, {\n key: \"defaultAction\",\n value: function defaultAction(trigger) {\n return getAttributeValue('action', trigger);\n }\n /**\n * Default `target` lookup function.\n * @param {Element} trigger\n */\n\n }, {\n key: \"defaultTarget\",\n value: function defaultTarget(trigger) {\n var selector = getAttributeValue('target', trigger);\n\n if (selector) {\n return document.querySelector(selector);\n }\n }\n /**\n * Allow fire programmatically a copy action\n * @param {String|HTMLElement} target\n * @param {Object} options\n * @returns Text copied.\n */\n\n }, {\n key: \"defaultText\",\n\n /**\n * Default `text` lookup function.\n * @param {Element} trigger\n */\n value: function defaultText(trigger) {\n return getAttributeValue('text', trigger);\n }\n /**\n * Destroy lifecycle.\n */\n\n }, {\n key: \"destroy\",\n value: function destroy() {\n this.listener.destroy();\n }\n }], [{\n key: \"copy\",\n value: function copy(target) {\n var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {\n container: document.body\n };\n return actions_copy(target, options);\n }\n /**\n * Allow fire programmatically a cut action\n * @param {String|HTMLElement} target\n * @returns Text cutted.\n */\n\n }, {\n key: \"cut\",\n value: function cut(target) {\n return actions_cut(target);\n }\n /**\n * Returns the support of the given action, or all actions if no action is\n * given.\n * @param {String} [action]\n */\n\n }, {\n key: \"isSupported\",\n value: function isSupported() {\n var action = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : ['copy', 'cut'];\n var actions = typeof action === 'string' ? [action] : action;\n var support = !!document.queryCommandSupported;\n actions.forEach(function (action) {\n support = support && !!document.queryCommandSupported(action);\n });\n return support;\n }\n }]);\n\n return Clipboard;\n}((tiny_emitter_default()));\n\n/* harmony default export */ var clipboard = (Clipboard);\n\n/***/ }),\n\n/***/ 828:\n/***/ (function(module) {\n\nvar DOCUMENT_NODE_TYPE = 9;\n\n/**\n * A polyfill for Element.matches()\n */\nif (typeof Element !== 'undefined' && !Element.prototype.matches) {\n var proto = Element.prototype;\n\n proto.matches = proto.matchesSelector ||\n proto.mozMatchesSelector ||\n proto.msMatchesSelector ||\n proto.oMatchesSelector ||\n proto.webkitMatchesSelector;\n}\n\n/**\n * Finds the closest parent that matches a selector.\n *\n * @param {Element} element\n * @param {String} selector\n * @return {Function}\n */\nfunction closest (element, selector) {\n while (element && element.nodeType !== DOCUMENT_NODE_TYPE) {\n if (typeof element.matches === 'function' &&\n element.matches(selector)) {\n return element;\n }\n element = element.parentNode;\n }\n}\n\nmodule.exports = closest;\n\n\n/***/ }),\n\n/***/ 438:\n/***/ (function(module, __unused_webpack_exports, __webpack_require__) {\n\nvar closest = __webpack_require__(828);\n\n/**\n * Delegates event to a selector.\n *\n * @param {Element} element\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @param {Boolean} useCapture\n * @return {Object}\n */\nfunction _delegate(element, selector, type, callback, useCapture) {\n var listenerFn = listener.apply(this, arguments);\n\n element.addEventListener(type, listenerFn, useCapture);\n\n return {\n destroy: function() {\n element.removeEventListener(type, listenerFn, useCapture);\n }\n }\n}\n\n/**\n * Delegates event to a selector.\n *\n * @param {Element|String|Array} [elements]\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @param {Boolean} useCapture\n * @return {Object}\n */\nfunction delegate(elements, selector, type, callback, useCapture) {\n // Handle the regular Element usage\n if (typeof elements.addEventListener === 'function') {\n return _delegate.apply(null, arguments);\n }\n\n // Handle Element-less usage, it defaults to global delegation\n if (typeof type === 'function') {\n // Use `document` as the first parameter, then apply arguments\n // This is a short way to .unshift `arguments` without running into deoptimizations\n return _delegate.bind(null, document).apply(null, arguments);\n }\n\n // Handle Selector-based usage\n if (typeof elements === 'string') {\n elements = document.querySelectorAll(elements);\n }\n\n // Handle Array-like based usage\n return Array.prototype.map.call(elements, function (element) {\n return _delegate(element, selector, type, callback, useCapture);\n });\n}\n\n/**\n * Finds closest match and invokes callback.\n *\n * @param {Element} element\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @return {Function}\n */\nfunction listener(element, selector, type, callback) {\n return function(e) {\n e.delegateTarget = closest(e.target, selector);\n\n if (e.delegateTarget) {\n callback.call(element, e);\n }\n }\n}\n\nmodule.exports = delegate;\n\n\n/***/ }),\n\n/***/ 879:\n/***/ (function(__unused_webpack_module, exports) {\n\n/**\n * Check if argument is a HTML element.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.node = function(value) {\n return value !== undefined\n && value instanceof HTMLElement\n && value.nodeType === 1;\n};\n\n/**\n * Check if argument is a list of HTML elements.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.nodeList = function(value) {\n var type = Object.prototype.toString.call(value);\n\n return value !== undefined\n && (type === '[object NodeList]' || type === '[object HTMLCollection]')\n && ('length' in value)\n && (value.length === 0 || exports.node(value[0]));\n};\n\n/**\n * Check if argument is a string.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.string = function(value) {\n return typeof value === 'string'\n || value instanceof String;\n};\n\n/**\n * Check if argument is a function.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.fn = function(value) {\n var type = Object.prototype.toString.call(value);\n\n return type === '[object Function]';\n};\n\n\n/***/ }),\n\n/***/ 370:\n/***/ (function(module, __unused_webpack_exports, __webpack_require__) {\n\nvar is = __webpack_require__(879);\nvar delegate = __webpack_require__(438);\n\n/**\n * Validates all params and calls the right\n * listener function based on its target type.\n *\n * @param {String|HTMLElement|HTMLCollection|NodeList} target\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listen(target, type, callback) {\n if (!target && !type && !callback) {\n throw new Error('Missing required arguments');\n }\n\n if (!is.string(type)) {\n throw new TypeError('Second argument must be a String');\n }\n\n if (!is.fn(callback)) {\n throw new TypeError('Third argument must be a Function');\n }\n\n if (is.node(target)) {\n return listenNode(target, type, callback);\n }\n else if (is.nodeList(target)) {\n return listenNodeList(target, type, callback);\n }\n else if (is.string(target)) {\n return listenSelector(target, type, callback);\n }\n else {\n throw new TypeError('First argument must be a String, HTMLElement, HTMLCollection, or NodeList');\n }\n}\n\n/**\n * Adds an event listener to a HTML element\n * and returns a remove listener function.\n *\n * @param {HTMLElement} node\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenNode(node, type, callback) {\n node.addEventListener(type, callback);\n\n return {\n destroy: function() {\n node.removeEventListener(type, callback);\n }\n }\n}\n\n/**\n * Add an event listener to a list of HTML elements\n * and returns a remove listener function.\n *\n * @param {NodeList|HTMLCollection} nodeList\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenNodeList(nodeList, type, callback) {\n Array.prototype.forEach.call(nodeList, function(node) {\n node.addEventListener(type, callback);\n });\n\n return {\n destroy: function() {\n Array.prototype.forEach.call(nodeList, function(node) {\n node.removeEventListener(type, callback);\n });\n }\n }\n}\n\n/**\n * Add an event listener to a selector\n * and returns a remove listener function.\n *\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenSelector(selector, type, callback) {\n return delegate(document.body, selector, type, callback);\n}\n\nmodule.exports = listen;\n\n\n/***/ }),\n\n/***/ 817:\n/***/ (function(module) {\n\nfunction select(element) {\n var selectedText;\n\n if (element.nodeName === 'SELECT') {\n element.focus();\n\n selectedText = element.value;\n }\n else if (element.nodeName === 'INPUT' || element.nodeName === 'TEXTAREA') {\n var isReadOnly = element.hasAttribute('readonly');\n\n if (!isReadOnly) {\n element.setAttribute('readonly', '');\n }\n\n element.select();\n element.setSelectionRange(0, element.value.length);\n\n if (!isReadOnly) {\n element.removeAttribute('readonly');\n }\n\n selectedText = element.value;\n }\n else {\n if (element.hasAttribute('contenteditable')) {\n element.focus();\n }\n\n var selection = window.getSelection();\n var range = document.createRange();\n\n range.selectNodeContents(element);\n selection.removeAllRanges();\n selection.addRange(range);\n\n selectedText = selection.toString();\n }\n\n return selectedText;\n}\n\nmodule.exports = select;\n\n\n/***/ }),\n\n/***/ 279:\n/***/ (function(module) {\n\nfunction E () {\n // Keep this empty so it's easier to inherit from\n // (via https://github.com/lipsmack from https://github.com/scottcorgan/tiny-emitter/issues/3)\n}\n\nE.prototype = {\n on: function (name, callback, ctx) {\n var e = this.e || (this.e = {});\n\n (e[name] || (e[name] = [])).push({\n fn: callback,\n ctx: ctx\n });\n\n return this;\n },\n\n once: function (name, callback, ctx) {\n var self = this;\n function listener () {\n self.off(name, listener);\n callback.apply(ctx, arguments);\n };\n\n listener._ = callback\n return this.on(name, listener, ctx);\n },\n\n emit: function (name) {\n var data = [].slice.call(arguments, 1);\n var evtArr = ((this.e || (this.e = {}))[name] || []).slice();\n var i = 0;\n var len = evtArr.length;\n\n for (i; i < len; i++) {\n evtArr[i].fn.apply(evtArr[i].ctx, data);\n }\n\n return this;\n },\n\n off: function (name, callback) {\n var e = this.e || (this.e = {});\n var evts = e[name];\n var liveEvents = [];\n\n if (evts && callback) {\n for (var i = 0, len = evts.length; i < len; i++) {\n if (evts[i].fn !== callback && evts[i].fn._ !== callback)\n liveEvents.push(evts[i]);\n }\n }\n\n // Remove event from queue to prevent memory leak\n // Suggested by https://github.com/lazd\n // Ref: https://github.com/scottcorgan/tiny-emitter/commit/c6ebfaa9bc973b33d110a84a307742b7cf94c953#commitcomment-5024910\n\n (liveEvents.length)\n ? e[name] = liveEvents\n : delete e[name];\n\n return this;\n }\n};\n\nmodule.exports = E;\nmodule.exports.TinyEmitter = E;\n\n\n/***/ })\n\n/******/ \t});\n/************************************************************************/\n/******/ \t// The module cache\n/******/ \tvar __webpack_module_cache__ = {};\n/******/ \t\n/******/ \t// The require function\n/******/ \tfunction __webpack_require__(moduleId) {\n/******/ \t\t// Check if module is in cache\n/******/ \t\tif(__webpack_module_cache__[moduleId]) {\n/******/ \t\t\treturn __webpack_module_cache__[moduleId].exports;\n/******/ \t\t}\n/******/ \t\t// Create a new module (and put it into the cache)\n/******/ \t\tvar module = __webpack_module_cache__[moduleId] = {\n/******/ \t\t\t// no module.id needed\n/******/ \t\t\t// no module.loaded needed\n/******/ \t\t\texports: {}\n/******/ \t\t};\n/******/ \t\n/******/ \t\t// Execute the module function\n/******/ \t\t__webpack_modules__[moduleId](module, module.exports, __webpack_require__);\n/******/ \t\n/******/ \t\t// Return the exports of the module\n/******/ \t\treturn module.exports;\n/******/ \t}\n/******/ \t\n/************************************************************************/\n/******/ \t/* webpack/runtime/compat get default export */\n/******/ \t!function() {\n/******/ \t\t// getDefaultExport function for compatibility with non-harmony modules\n/******/ \t\t__webpack_require__.n = function(module) {\n/******/ \t\t\tvar getter = module && module.__esModule ?\n/******/ \t\t\t\tfunction() { return module['default']; } :\n/******/ \t\t\t\tfunction() { return module; };\n/******/ \t\t\t__webpack_require__.d(getter, { a: getter });\n/******/ \t\t\treturn getter;\n/******/ \t\t};\n/******/ \t}();\n/******/ \t\n/******/ \t/* webpack/runtime/define property getters */\n/******/ \t!function() {\n/******/ \t\t// define getter functions for harmony exports\n/******/ \t\t__webpack_require__.d = function(exports, definition) {\n/******/ \t\t\tfor(var key in definition) {\n/******/ \t\t\t\tif(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n/******/ \t\t\t\t\tObject.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n/******/ \t\t\t\t}\n/******/ \t\t\t}\n/******/ \t\t};\n/******/ \t}();\n/******/ \t\n/******/ \t/* webpack/runtime/hasOwnProperty shorthand */\n/******/ \t!function() {\n/******/ \t\t__webpack_require__.o = function(obj, prop) { return Object.prototype.hasOwnProperty.call(obj, prop); }\n/******/ \t}();\n/******/ \t\n/************************************************************************/\n/******/ \t// module exports must be returned from runtime so entry inlining is disabled\n/******/ \t// startup\n/******/ \t// Load entry module and return exports\n/******/ \treturn __webpack_require__(686);\n/******/ })()\n.default;\n});", "/*\n * Copyright (c) 2016-2024 Martin Donath \n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to\n * deal in the Software without restriction, including without limitation the\n * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or\n * sell copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in\n * all copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\n * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS\n * IN THE SOFTWARE.\n */\n\nimport \"focus-visible\"\n\nimport {\n EMPTY,\n NEVER,\n Observable,\n Subject,\n defer,\n delay,\n filter,\n map,\n merge,\n mergeWith,\n shareReplay,\n switchMap\n} from \"rxjs\"\n\nimport { configuration, feature } from \"./_\"\nimport {\n at,\n getActiveElement,\n getOptionalElement,\n requestJSON,\n setLocation,\n setToggle,\n watchDocument,\n watchKeyboard,\n watchLocation,\n watchLocationTarget,\n watchMedia,\n watchPrint,\n watchScript,\n watchViewport\n} from \"./browser\"\nimport {\n getComponentElement,\n getComponentElements,\n mountAnnounce,\n mountBackToTop,\n mountConsent,\n mountContent,\n mountDialog,\n mountHeader,\n mountHeaderTitle,\n mountPalette,\n mountProgress,\n mountSearch,\n mountSearchHiglight,\n mountSidebar,\n mountSource,\n mountTableOfContents,\n mountTabs,\n watchHeader,\n watchMain\n} from \"./components\"\nimport {\n SearchIndex,\n setupClipboardJS,\n setupInstantNavigation,\n setupVersionSelector\n} from \"./integrations\"\nimport {\n patchEllipsis,\n patchIndeterminate,\n patchScrollfix,\n patchScrolllock\n} from \"./patches\"\nimport \"./polyfills\"\n\n/* ----------------------------------------------------------------------------\n * Functions - @todo refactor\n * ------------------------------------------------------------------------- */\n\n/**\n * Fetch search index\n *\n * @returns Search index observable\n */\nfunction fetchSearchIndex(): Observable {\n if (location.protocol === \"file:\") {\n return watchScript(\n `${new URL(\"search/search_index.js\", config.base)}`\n )\n .pipe(\n // @ts-ignore - @todo fix typings\n map(() => __index),\n shareReplay(1)\n )\n } else {\n return requestJSON(\n new URL(\"search/search_index.json\", config.base)\n )\n }\n}\n\n/* ----------------------------------------------------------------------------\n * Application\n * ------------------------------------------------------------------------- */\n\n/* Yay, JavaScript is available */\ndocument.documentElement.classList.remove(\"no-js\")\ndocument.documentElement.classList.add(\"js\")\n\n/* Set up navigation observables and subjects */\nconst document$ = watchDocument()\nconst location$ = watchLocation()\nconst target$ = watchLocationTarget(location$)\nconst keyboard$ = watchKeyboard()\n\n/* Set up media observables */\nconst viewport$ = watchViewport()\nconst tablet$ = watchMedia(\"(min-width: 960px)\")\nconst screen$ = watchMedia(\"(min-width: 1220px)\")\nconst print$ = watchPrint()\n\n/* Retrieve search index, if search is enabled */\nconst config = configuration()\nconst index$ = document.forms.namedItem(\"search\")\n ? fetchSearchIndex()\n : NEVER\n\n/* Set up Clipboard.js integration */\nconst alert$ = new Subject()\nsetupClipboardJS({ alert$ })\n\n/* Set up progress indicator */\nconst progress$ = new Subject()\n\n/* Set up instant navigation, if enabled */\nif (feature(\"navigation.instant\"))\n setupInstantNavigation({ location$, viewport$, progress$ })\n .subscribe(document$)\n\n/* Set up version selector */\nif (config.version?.provider === \"mike\")\n setupVersionSelector({ document$ })\n\n/* Always close drawer and search on navigation */\nmerge(location$, target$)\n .pipe(\n delay(125)\n )\n .subscribe(() => {\n setToggle(\"drawer\", false)\n setToggle(\"search\", false)\n })\n\n/* Set up global keyboard handlers */\nkeyboard$\n .pipe(\n filter(({ mode }) => mode === \"global\")\n )\n .subscribe(key => {\n switch (key.type) {\n\n /* Go to previous page */\n case \"p\":\n case \",\":\n const prev = getOptionalElement(\"link[rel=prev]\")\n if (typeof prev !== \"undefined\")\n setLocation(prev)\n break\n\n /* Go to next page */\n case \"n\":\n case \".\":\n const next = getOptionalElement(\"link[rel=next]\")\n if (typeof next !== \"undefined\")\n setLocation(next)\n break\n\n /* Expand navigation, see https://bit.ly/3ZjG5io */\n case \"Enter\":\n const active = getActiveElement()\n if (active instanceof HTMLLabelElement)\n active.click()\n }\n })\n\n/* Set up patches */\npatchEllipsis({ viewport$, document$ })\npatchIndeterminate({ document$, tablet$ })\npatchScrollfix({ document$ })\npatchScrolllock({ viewport$, tablet$ })\n\n/* Set up header and main area observable */\nconst header$ = watchHeader(getComponentElement(\"header\"), { viewport$ })\nconst main$ = document$\n .pipe(\n map(() => getComponentElement(\"main\")),\n switchMap(el => watchMain(el, { viewport$, header$ })),\n shareReplay(1)\n )\n\n/* Set up control component observables */\nconst control$ = merge(\n\n /* Consent */\n ...getComponentElements(\"consent\")\n .map(el => mountConsent(el, { target$ })),\n\n /* Dialog */\n ...getComponentElements(\"dialog\")\n .map(el => mountDialog(el, { alert$ })),\n\n /* Color palette */\n ...getComponentElements(\"palette\")\n .map(el => mountPalette(el)),\n\n /* Progress bar */\n ...getComponentElements(\"progress\")\n .map(el => mountProgress(el, { progress$ })),\n\n /* Search */\n ...getComponentElements(\"search\")\n .map(el => mountSearch(el, { index$, keyboard$ })),\n\n /* Repository information */\n ...getComponentElements(\"source\")\n .map(el => mountSource(el))\n)\n\n/* Set up content component observables */\nconst content$ = defer(() => merge(\n\n /* Announcement bar */\n ...getComponentElements(\"announce\")\n .map(el => mountAnnounce(el)),\n\n /* Content */\n ...getComponentElements(\"content\")\n .map(el => mountContent(el, { viewport$, target$, print$ })),\n\n /* Search highlighting */\n ...getComponentElements(\"content\")\n .map(el => feature(\"search.highlight\")\n ? mountSearchHiglight(el, { index$, location$ })\n : EMPTY\n ),\n\n /* Header */\n ...getComponentElements(\"header\")\n .map(el => mountHeader(el, { viewport$, header$, main$ })),\n\n /* Header title */\n ...getComponentElements(\"header-title\")\n .map(el => mountHeaderTitle(el, { viewport$, header$ })),\n\n /* Sidebar */\n ...getComponentElements(\"sidebar\")\n .map(el => el.getAttribute(\"data-md-type\") === \"navigation\"\n ? at(screen$, () => mountSidebar(el, { viewport$, header$, main$ }))\n : at(tablet$, () => mountSidebar(el, { viewport$, header$, main$ }))\n ),\n\n /* Navigation tabs */\n ...getComponentElements(\"tabs\")\n .map(el => mountTabs(el, { viewport$, header$ })),\n\n /* Table of contents */\n ...getComponentElements(\"toc\")\n .map(el => mountTableOfContents(el, {\n viewport$, header$, main$, target$\n })),\n\n /* Back-to-top button */\n ...getComponentElements(\"top\")\n .map(el => mountBackToTop(el, { viewport$, header$, main$, target$ }))\n))\n\n/* Set up component observables */\nconst component$ = document$\n .pipe(\n switchMap(() => content$),\n mergeWith(control$),\n shareReplay(1)\n )\n\n/* Subscribe to all components */\ncomponent$.subscribe()\n\n/* ----------------------------------------------------------------------------\n * Exports\n * ------------------------------------------------------------------------- */\n\nwindow.document$ = document$ /* Document observable */\nwindow.location$ = location$ /* Location subject */\nwindow.target$ = target$ /* Location target observable */\nwindow.keyboard$ = keyboard$ /* Keyboard observable */\nwindow.viewport$ = viewport$ /* Viewport observable */\nwindow.tablet$ = tablet$ /* Media tablet observable */\nwindow.screen$ = screen$ /* Media screen observable */\nwindow.print$ = print$ /* Media print observable */\nwindow.alert$ = alert$ /* Alert subject */\nwindow.progress$ = progress$ /* Progress indicator subject */\nwindow.component$ = component$ /* Component observable */\n", "/******************************************************************************\nCopyright (c) Microsoft Corporation.\n\nPermission to use, copy, modify, and/or distribute this software for any\npurpose with or without fee is hereby granted.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH\nREGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY\nAND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,\nINDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM\nLOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR\nOTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR\nPERFORMANCE OF THIS SOFTWARE.\n***************************************************************************** */\n/* global Reflect, Promise, SuppressedError, Symbol, Iterator */\n\nvar extendStatics = function(d, b) {\n extendStatics = Object.setPrototypeOf ||\n ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||\n function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };\n return extendStatics(d, b);\n};\n\nexport function __extends(d, b) {\n if (typeof b !== \"function\" && b !== null)\n throw new TypeError(\"Class extends value \" + String(b) + \" is not a constructor or null\");\n extendStatics(d, b);\n function __() { this.constructor = d; }\n d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());\n}\n\nexport var __assign = function() {\n __assign = Object.assign || function __assign(t) {\n for (var s, i = 1, n = arguments.length; i < n; i++) {\n s = arguments[i];\n for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p)) t[p] = s[p];\n }\n return t;\n }\n return __assign.apply(this, arguments);\n}\n\nexport function __rest(s, e) {\n var t = {};\n for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)\n t[p] = s[p];\n if (s != null && typeof Object.getOwnPropertySymbols === \"function\")\n for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {\n if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))\n t[p[i]] = s[p[i]];\n }\n return t;\n}\n\nexport function __decorate(decorators, target, key, desc) {\n var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;\n if (typeof Reflect === \"object\" && typeof Reflect.decorate === \"function\") r = Reflect.decorate(decorators, target, key, desc);\n else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;\n return c > 3 && r && Object.defineProperty(target, key, r), r;\n}\n\nexport function __param(paramIndex, decorator) {\n return function (target, key) { decorator(target, key, paramIndex); }\n}\n\nexport function __esDecorate(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {\n function accept(f) { if (f !== void 0 && typeof f !== \"function\") throw new TypeError(\"Function expected\"); return f; }\n var kind = contextIn.kind, key = kind === \"getter\" ? \"get\" : kind === \"setter\" ? \"set\" : \"value\";\n var target = !descriptorIn && ctor ? contextIn[\"static\"] ? ctor : ctor.prototype : null;\n var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});\n var _, done = false;\n for (var i = decorators.length - 1; i >= 0; i--) {\n var context = {};\n for (var p in contextIn) context[p] = p === \"access\" ? {} : contextIn[p];\n for (var p in contextIn.access) context.access[p] = contextIn.access[p];\n context.addInitializer = function (f) { if (done) throw new TypeError(\"Cannot add initializers after decoration has completed\"); extraInitializers.push(accept(f || null)); };\n var result = (0, decorators[i])(kind === \"accessor\" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);\n if (kind === \"accessor\") {\n if (result === void 0) continue;\n if (result === null || typeof result !== \"object\") throw new TypeError(\"Object expected\");\n if (_ = accept(result.get)) descriptor.get = _;\n if (_ = accept(result.set)) descriptor.set = _;\n if (_ = accept(result.init)) initializers.unshift(_);\n }\n else if (_ = accept(result)) {\n if (kind === \"field\") initializers.unshift(_);\n else descriptor[key] = _;\n }\n }\n if (target) Object.defineProperty(target, contextIn.name, descriptor);\n done = true;\n};\n\nexport function __runInitializers(thisArg, initializers, value) {\n var useValue = arguments.length > 2;\n for (var i = 0; i < initializers.length; i++) {\n value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);\n }\n return useValue ? value : void 0;\n};\n\nexport function __propKey(x) {\n return typeof x === \"symbol\" ? x : \"\".concat(x);\n};\n\nexport function __setFunctionName(f, name, prefix) {\n if (typeof name === \"symbol\") name = name.description ? \"[\".concat(name.description, \"]\") : \"\";\n return Object.defineProperty(f, \"name\", { configurable: true, value: prefix ? \"\".concat(prefix, \" \", name) : name });\n};\n\nexport function __metadata(metadataKey, metadataValue) {\n if (typeof Reflect === \"object\" && typeof Reflect.metadata === \"function\") return Reflect.metadata(metadataKey, metadataValue);\n}\n\nexport function __awaiter(thisArg, _arguments, P, generator) {\n function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }\n return new (P || (P = Promise))(function (resolve, reject) {\n function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }\n function rejected(value) { try { step(generator[\"throw\"](value)); } catch (e) { reject(e); } }\n function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }\n step((generator = generator.apply(thisArg, _arguments || [])).next());\n });\n}\n\nexport function __generator(thisArg, body) {\n var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === \"function\" ? Iterator : Object).prototype);\n return g.next = verb(0), g[\"throw\"] = verb(1), g[\"return\"] = verb(2), typeof Symbol === \"function\" && (g[Symbol.iterator] = function() { return this; }), g;\n function verb(n) { return function (v) { return step([n, v]); }; }\n function step(op) {\n if (f) throw new TypeError(\"Generator is already executing.\");\n while (g && (g = 0, op[0] && (_ = 0)), _) try {\n if (f = 1, y && (t = op[0] & 2 ? y[\"return\"] : op[0] ? y[\"throw\"] || ((t = y[\"return\"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;\n if (y = 0, t) op = [op[0] & 2, t.value];\n switch (op[0]) {\n case 0: case 1: t = op; break;\n case 4: _.label++; return { value: op[1], done: false };\n case 5: _.label++; y = op[1]; op = [0]; continue;\n case 7: op = _.ops.pop(); _.trys.pop(); continue;\n default:\n if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }\n if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }\n if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }\n if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }\n if (t[2]) _.ops.pop();\n _.trys.pop(); continue;\n }\n op = body.call(thisArg, _);\n } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }\n if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };\n }\n}\n\nexport var __createBinding = Object.create ? (function(o, m, k, k2) {\n if (k2 === undefined) k2 = k;\n var desc = Object.getOwnPropertyDescriptor(m, k);\n if (!desc || (\"get\" in desc ? !m.__esModule : desc.writable || desc.configurable)) {\n desc = { enumerable: true, get: function() { return m[k]; } };\n }\n Object.defineProperty(o, k2, desc);\n}) : (function(o, m, k, k2) {\n if (k2 === undefined) k2 = k;\n o[k2] = m[k];\n});\n\nexport function __exportStar(m, o) {\n for (var p in m) if (p !== \"default\" && !Object.prototype.hasOwnProperty.call(o, p)) __createBinding(o, m, p);\n}\n\nexport function __values(o) {\n var s = typeof Symbol === \"function\" && Symbol.iterator, m = s && o[s], i = 0;\n if (m) return m.call(o);\n if (o && typeof o.length === \"number\") return {\n next: function () {\n if (o && i >= o.length) o = void 0;\n return { value: o && o[i++], done: !o };\n }\n };\n throw new TypeError(s ? \"Object is not iterable.\" : \"Symbol.iterator is not defined.\");\n}\n\nexport function __read(o, n) {\n var m = typeof Symbol === \"function\" && o[Symbol.iterator];\n if (!m) return o;\n var i = m.call(o), r, ar = [], e;\n try {\n while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);\n }\n catch (error) { e = { error: error }; }\n finally {\n try {\n if (r && !r.done && (m = i[\"return\"])) m.call(i);\n }\n finally { if (e) throw e.error; }\n }\n return ar;\n}\n\n/** @deprecated */\nexport function __spread() {\n for (var ar = [], i = 0; i < arguments.length; i++)\n ar = ar.concat(__read(arguments[i]));\n return ar;\n}\n\n/** @deprecated */\nexport function __spreadArrays() {\n for (var s = 0, i = 0, il = arguments.length; i < il; i++) s += arguments[i].length;\n for (var r = Array(s), k = 0, i = 0; i < il; i++)\n for (var a = arguments[i], j = 0, jl = a.length; j < jl; j++, k++)\n r[k] = a[j];\n return r;\n}\n\nexport function __spreadArray(to, from, pack) {\n if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {\n if (ar || !(i in from)) {\n if (!ar) ar = Array.prototype.slice.call(from, 0, i);\n ar[i] = from[i];\n }\n }\n return to.concat(ar || Array.prototype.slice.call(from));\n}\n\nexport function __await(v) {\n return this instanceof __await ? (this.v = v, this) : new __await(v);\n}\n\nexport function __asyncGenerator(thisArg, _arguments, generator) {\n if (!Symbol.asyncIterator) throw new TypeError(\"Symbol.asyncIterator is not defined.\");\n var g = generator.apply(thisArg, _arguments || []), i, q = [];\n return i = Object.create((typeof AsyncIterator === \"function\" ? AsyncIterator : Object).prototype), verb(\"next\"), verb(\"throw\"), verb(\"return\", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;\n function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }\n function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }\n function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }\n function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }\n function fulfill(value) { resume(\"next\", value); }\n function reject(value) { resume(\"throw\", value); }\n function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }\n}\n\nexport function __asyncDelegator(o) {\n var i, p;\n return i = {}, verb(\"next\"), verb(\"throw\", function (e) { throw e; }), verb(\"return\"), i[Symbol.iterator] = function () { return this; }, i;\n function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: false } : f ? f(v) : v; } : f; }\n}\n\nexport function __asyncValues(o) {\n if (!Symbol.asyncIterator) throw new TypeError(\"Symbol.asyncIterator is not defined.\");\n var m = o[Symbol.asyncIterator], i;\n return m ? m.call(o) : (o = typeof __values === \"function\" ? __values(o) : o[Symbol.iterator](), i = {}, verb(\"next\"), verb(\"throw\"), verb(\"return\"), i[Symbol.asyncIterator] = function () { return this; }, i);\n function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }\n function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }\n}\n\nexport function __makeTemplateObject(cooked, raw) {\n if (Object.defineProperty) { Object.defineProperty(cooked, \"raw\", { value: raw }); } else { cooked.raw = raw; }\n return cooked;\n};\n\nvar __setModuleDefault = Object.create ? (function(o, v) {\n Object.defineProperty(o, \"default\", { enumerable: true, value: v });\n}) : function(o, v) {\n o[\"default\"] = v;\n};\n\nexport function __importStar(mod) {\n if (mod && mod.__esModule) return mod;\n var result = {};\n if (mod != null) for (var k in mod) if (k !== \"default\" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);\n __setModuleDefault(result, mod);\n return result;\n}\n\nexport function __importDefault(mod) {\n return (mod && mod.__esModule) ? mod : { default: mod };\n}\n\nexport function __classPrivateFieldGet(receiver, state, kind, f) {\n if (kind === \"a\" && !f) throw new TypeError(\"Private accessor was defined without a getter\");\n if (typeof state === \"function\" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError(\"Cannot read private member from an object whose class did not declare it\");\n return kind === \"m\" ? f : kind === \"a\" ? f.call(receiver) : f ? f.value : state.get(receiver);\n}\n\nexport function __classPrivateFieldSet(receiver, state, value, kind, f) {\n if (kind === \"m\") throw new TypeError(\"Private method is not writable\");\n if (kind === \"a\" && !f) throw new TypeError(\"Private accessor was defined without a setter\");\n if (typeof state === \"function\" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError(\"Cannot write private member to an object whose class did not declare it\");\n return (kind === \"a\" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;\n}\n\nexport function __classPrivateFieldIn(state, receiver) {\n if (receiver === null || (typeof receiver !== \"object\" && typeof receiver !== \"function\")) throw new TypeError(\"Cannot use 'in' operator on non-object\");\n return typeof state === \"function\" ? receiver === state : state.has(receiver);\n}\n\nexport function __addDisposableResource(env, value, async) {\n if (value !== null && value !== void 0) {\n if (typeof value !== \"object\" && typeof value !== \"function\") throw new TypeError(\"Object expected.\");\n var dispose, inner;\n if (async) {\n if (!Symbol.asyncDispose) throw new TypeError(\"Symbol.asyncDispose is not defined.\");\n dispose = value[Symbol.asyncDispose];\n }\n if (dispose === void 0) {\n if (!Symbol.dispose) throw new TypeError(\"Symbol.dispose is not defined.\");\n dispose = value[Symbol.dispose];\n if (async) inner = dispose;\n }\n if (typeof dispose !== \"function\") throw new TypeError(\"Object not disposable.\");\n if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };\n env.stack.push({ value: value, dispose: dispose, async: async });\n }\n else if (async) {\n env.stack.push({ async: true });\n }\n return value;\n}\n\nvar _SuppressedError = typeof SuppressedError === \"function\" ? SuppressedError : function (error, suppressed, message) {\n var e = new Error(message);\n return e.name = \"SuppressedError\", e.error = error, e.suppressed = suppressed, e;\n};\n\nexport function __disposeResources(env) {\n function fail(e) {\n env.error = env.hasError ? new _SuppressedError(e, env.error, \"An error was suppressed during disposal.\") : e;\n env.hasError = true;\n }\n var r, s = 0;\n function next() {\n while (r = env.stack.pop()) {\n try {\n if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);\n if (r.dispose) {\n var result = r.dispose.call(r.value);\n if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });\n }\n else s |= 1;\n }\n catch (e) {\n fail(e);\n }\n }\n if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();\n if (env.hasError) throw env.error;\n }\n return next();\n}\n\nexport default {\n __extends,\n __assign,\n __rest,\n __decorate,\n __param,\n __metadata,\n __awaiter,\n __generator,\n __createBinding,\n __exportStar,\n __values,\n __read,\n __spread,\n __spreadArrays,\n __spreadArray,\n __await,\n __asyncGenerator,\n __asyncDelegator,\n __asyncValues,\n __makeTemplateObject,\n __importStar,\n __importDefault,\n __classPrivateFieldGet,\n __classPrivateFieldSet,\n __classPrivateFieldIn,\n __addDisposableResource,\n __disposeResources,\n};\n", "/**\n * Returns true if the object is a function.\n * @param value The value to check\n */\nexport function isFunction(value: any): value is (...args: any[]) => any {\n return typeof value === 'function';\n}\n", "/**\n * Used to create Error subclasses until the community moves away from ES5.\n *\n * This is because compiling from TypeScript down to ES5 has issues with subclassing Errors\n * as well as other built-in types: https://github.com/Microsoft/TypeScript/issues/12123\n *\n * @param createImpl A factory function to create the actual constructor implementation. The returned\n * function should be a named function that calls `_super` internally.\n */\nexport function createErrorClass(createImpl: (_super: any) => any): T {\n const _super = (instance: any) => {\n Error.call(instance);\n instance.stack = new Error().stack;\n };\n\n const ctorFunc = createImpl(_super);\n ctorFunc.prototype = Object.create(Error.prototype);\n ctorFunc.prototype.constructor = ctorFunc;\n return ctorFunc;\n}\n", "import { createErrorClass } from './createErrorClass';\n\nexport interface UnsubscriptionError extends Error {\n readonly errors: any[];\n}\n\nexport interface UnsubscriptionErrorCtor {\n /**\n * @deprecated Internal implementation detail. Do not construct error instances.\n * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269\n */\n new (errors: any[]): UnsubscriptionError;\n}\n\n/**\n * An error thrown when one or more errors have occurred during the\n * `unsubscribe` of a {@link Subscription}.\n */\nexport const UnsubscriptionError: UnsubscriptionErrorCtor = createErrorClass(\n (_super) =>\n function UnsubscriptionErrorImpl(this: any, errors: (Error | string)[]) {\n _super(this);\n this.message = errors\n ? `${errors.length} errors occurred during unsubscription:\n${errors.map((err, i) => `${i + 1}) ${err.toString()}`).join('\\n ')}`\n : '';\n this.name = 'UnsubscriptionError';\n this.errors = errors;\n }\n);\n", "/**\n * Removes an item from an array, mutating it.\n * @param arr The array to remove the item from\n * @param item The item to remove\n */\nexport function arrRemove(arr: T[] | undefined | null, item: T) {\n if (arr) {\n const index = arr.indexOf(item);\n 0 <= index && arr.splice(index, 1);\n }\n}\n", "import { isFunction } from './util/isFunction';\nimport { UnsubscriptionError } from './util/UnsubscriptionError';\nimport { SubscriptionLike, TeardownLogic, Unsubscribable } from './types';\nimport { arrRemove } from './util/arrRemove';\n\n/**\n * Represents a disposable resource, such as the execution of an Observable. A\n * Subscription has one important method, `unsubscribe`, that takes no argument\n * and just disposes the resource held by the subscription.\n *\n * Additionally, subscriptions may be grouped together through the `add()`\n * method, which will attach a child Subscription to the current Subscription.\n * When a Subscription is unsubscribed, all its children (and its grandchildren)\n * will be unsubscribed as well.\n *\n * @class Subscription\n */\nexport class Subscription implements SubscriptionLike {\n /** @nocollapse */\n public static EMPTY = (() => {\n const empty = new Subscription();\n empty.closed = true;\n return empty;\n })();\n\n /**\n * A flag to indicate whether this Subscription has already been unsubscribed.\n */\n public closed = false;\n\n private _parentage: Subscription[] | Subscription | null = null;\n\n /**\n * The list of registered finalizers to execute upon unsubscription. Adding and removing from this\n * list occurs in the {@link #add} and {@link #remove} methods.\n */\n private _finalizers: Exclude[] | null = null;\n\n /**\n * @param initialTeardown A function executed first as part of the finalization\n * process that is kicked off when {@link #unsubscribe} is called.\n */\n constructor(private initialTeardown?: () => void) {}\n\n /**\n * Disposes the resources held by the subscription. May, for instance, cancel\n * an ongoing Observable execution or cancel any other type of work that\n * started when the Subscription was created.\n * @return {void}\n */\n unsubscribe(): void {\n let errors: any[] | undefined;\n\n if (!this.closed) {\n this.closed = true;\n\n // Remove this from it's parents.\n const { _parentage } = this;\n if (_parentage) {\n this._parentage = null;\n if (Array.isArray(_parentage)) {\n for (const parent of _parentage) {\n parent.remove(this);\n }\n } else {\n _parentage.remove(this);\n }\n }\n\n const { initialTeardown: initialFinalizer } = this;\n if (isFunction(initialFinalizer)) {\n try {\n initialFinalizer();\n } catch (e) {\n errors = e instanceof UnsubscriptionError ? e.errors : [e];\n }\n }\n\n const { _finalizers } = this;\n if (_finalizers) {\n this._finalizers = null;\n for (const finalizer of _finalizers) {\n try {\n execFinalizer(finalizer);\n } catch (err) {\n errors = errors ?? [];\n if (err instanceof UnsubscriptionError) {\n errors = [...errors, ...err.errors];\n } else {\n errors.push(err);\n }\n }\n }\n }\n\n if (errors) {\n throw new UnsubscriptionError(errors);\n }\n }\n }\n\n /**\n * Adds a finalizer to this subscription, so that finalization will be unsubscribed/called\n * when this subscription is unsubscribed. If this subscription is already {@link #closed},\n * because it has already been unsubscribed, then whatever finalizer is passed to it\n * will automatically be executed (unless the finalizer itself is also a closed subscription).\n *\n * Closed Subscriptions cannot be added as finalizers to any subscription. Adding a closed\n * subscription to a any subscription will result in no operation. (A noop).\n *\n * Adding a subscription to itself, or adding `null` or `undefined` will not perform any\n * operation at all. (A noop).\n *\n * `Subscription` instances that are added to this instance will automatically remove themselves\n * if they are unsubscribed. Functions and {@link Unsubscribable} objects that you wish to remove\n * will need to be removed manually with {@link #remove}\n *\n * @param teardown The finalization logic to add to this subscription.\n */\n add(teardown: TeardownLogic): void {\n // Only add the finalizer if it's not undefined\n // and don't add a subscription to itself.\n if (teardown && teardown !== this) {\n if (this.closed) {\n // If this subscription is already closed,\n // execute whatever finalizer is handed to it automatically.\n execFinalizer(teardown);\n } else {\n if (teardown instanceof Subscription) {\n // We don't add closed subscriptions, and we don't add the same subscription\n // twice. Subscription unsubscribe is idempotent.\n if (teardown.closed || teardown._hasParent(this)) {\n return;\n }\n teardown._addParent(this);\n }\n (this._finalizers = this._finalizers ?? []).push(teardown);\n }\n }\n }\n\n /**\n * Checks to see if a this subscription already has a particular parent.\n * This will signal that this subscription has already been added to the parent in question.\n * @param parent the parent to check for\n */\n private _hasParent(parent: Subscription) {\n const { _parentage } = this;\n return _parentage === parent || (Array.isArray(_parentage) && _parentage.includes(parent));\n }\n\n /**\n * Adds a parent to this subscription so it can be removed from the parent if it\n * unsubscribes on it's own.\n *\n * NOTE: THIS ASSUMES THAT {@link _hasParent} HAS ALREADY BEEN CHECKED.\n * @param parent The parent subscription to add\n */\n private _addParent(parent: Subscription) {\n const { _parentage } = this;\n this._parentage = Array.isArray(_parentage) ? (_parentage.push(parent), _parentage) : _parentage ? [_parentage, parent] : parent;\n }\n\n /**\n * Called on a child when it is removed via {@link #remove}.\n * @param parent The parent to remove\n */\n private _removeParent(parent: Subscription) {\n const { _parentage } = this;\n if (_parentage === parent) {\n this._parentage = null;\n } else if (Array.isArray(_parentage)) {\n arrRemove(_parentage, parent);\n }\n }\n\n /**\n * Removes a finalizer from this subscription that was previously added with the {@link #add} method.\n *\n * Note that `Subscription` instances, when unsubscribed, will automatically remove themselves\n * from every other `Subscription` they have been added to. This means that using the `remove` method\n * is not a common thing and should be used thoughtfully.\n *\n * If you add the same finalizer instance of a function or an unsubscribable object to a `Subscription` instance\n * more than once, you will need to call `remove` the same number of times to remove all instances.\n *\n * All finalizer instances are removed to free up memory upon unsubscription.\n *\n * @param teardown The finalizer to remove from this subscription\n */\n remove(teardown: Exclude): void {\n const { _finalizers } = this;\n _finalizers && arrRemove(_finalizers, teardown);\n\n if (teardown instanceof Subscription) {\n teardown._removeParent(this);\n }\n }\n}\n\nexport const EMPTY_SUBSCRIPTION = Subscription.EMPTY;\n\nexport function isSubscription(value: any): value is Subscription {\n return (\n value instanceof Subscription ||\n (value && 'closed' in value && isFunction(value.remove) && isFunction(value.add) && isFunction(value.unsubscribe))\n );\n}\n\nfunction execFinalizer(finalizer: Unsubscribable | (() => void)) {\n if (isFunction(finalizer)) {\n finalizer();\n } else {\n finalizer.unsubscribe();\n }\n}\n", "import { Subscriber } from './Subscriber';\nimport { ObservableNotification } from './types';\n\n/**\n * The {@link GlobalConfig} object for RxJS. It is used to configure things\n * like how to react on unhandled errors.\n */\nexport const config: GlobalConfig = {\n onUnhandledError: null,\n onStoppedNotification: null,\n Promise: undefined,\n useDeprecatedSynchronousErrorHandling: false,\n useDeprecatedNextContext: false,\n};\n\n/**\n * The global configuration object for RxJS, used to configure things\n * like how to react on unhandled errors. Accessible via {@link config}\n * object.\n */\nexport interface GlobalConfig {\n /**\n * A registration point for unhandled errors from RxJS. These are errors that\n * cannot were not handled by consuming code in the usual subscription path. For\n * example, if you have this configured, and you subscribe to an observable without\n * providing an error handler, errors from that subscription will end up here. This\n * will _always_ be called asynchronously on another job in the runtime. This is because\n * we do not want errors thrown in this user-configured handler to interfere with the\n * behavior of the library.\n */\n onUnhandledError: ((err: any) => void) | null;\n\n /**\n * A registration point for notifications that cannot be sent to subscribers because they\n * have completed, errored or have been explicitly unsubscribed. By default, next, complete\n * and error notifications sent to stopped subscribers are noops. However, sometimes callers\n * might want a different behavior. For example, with sources that attempt to report errors\n * to stopped subscribers, a caller can configure RxJS to throw an unhandled error instead.\n * This will _always_ be called asynchronously on another job in the runtime. This is because\n * we do not want errors thrown in this user-configured handler to interfere with the\n * behavior of the library.\n */\n onStoppedNotification: ((notification: ObservableNotification, subscriber: Subscriber) => void) | null;\n\n /**\n * The promise constructor used by default for {@link Observable#toPromise toPromise} and {@link Observable#forEach forEach}\n * methods.\n *\n * @deprecated As of version 8, RxJS will no longer support this sort of injection of a\n * Promise constructor. If you need a Promise implementation other than native promises,\n * please polyfill/patch Promise as you see appropriate. Will be removed in v8.\n */\n Promise?: PromiseConstructorLike;\n\n /**\n * If true, turns on synchronous error rethrowing, which is a deprecated behavior\n * in v6 and higher. This behavior enables bad patterns like wrapping a subscribe\n * call in a try/catch block. It also enables producer interference, a nasty bug\n * where a multicast can be broken for all observers by a downstream consumer with\n * an unhandled error. DO NOT USE THIS FLAG UNLESS IT'S NEEDED TO BUY TIME\n * FOR MIGRATION REASONS.\n *\n * @deprecated As of version 8, RxJS will no longer support synchronous throwing\n * of unhandled errors. All errors will be thrown on a separate call stack to prevent bad\n * behaviors described above. Will be removed in v8.\n */\n useDeprecatedSynchronousErrorHandling: boolean;\n\n /**\n * If true, enables an as-of-yet undocumented feature from v5: The ability to access\n * `unsubscribe()` via `this` context in `next` functions created in observers passed\n * to `subscribe`.\n *\n * This is being removed because the performance was severely problematic, and it could also cause\n * issues when types other than POJOs are passed to subscribe as subscribers, as they will likely have\n * their `this` context overwritten.\n *\n * @deprecated As of version 8, RxJS will no longer support altering the\n * context of next functions provided as part of an observer to Subscribe. Instead,\n * you will have access to a subscription or a signal or token that will allow you to do things like\n * unsubscribe and test closed status. Will be removed in v8.\n */\n useDeprecatedNextContext: boolean;\n}\n", "import type { TimerHandle } from './timerHandle';\ntype SetTimeoutFunction = (handler: () => void, timeout?: number, ...args: any[]) => TimerHandle;\ntype ClearTimeoutFunction = (handle: TimerHandle) => void;\n\ninterface TimeoutProvider {\n setTimeout: SetTimeoutFunction;\n clearTimeout: ClearTimeoutFunction;\n delegate:\n | {\n setTimeout: SetTimeoutFunction;\n clearTimeout: ClearTimeoutFunction;\n }\n | undefined;\n}\n\nexport const timeoutProvider: TimeoutProvider = {\n // When accessing the delegate, use the variable rather than `this` so that\n // the functions can be called without being bound to the provider.\n setTimeout(handler: () => void, timeout?: number, ...args) {\n const { delegate } = timeoutProvider;\n if (delegate?.setTimeout) {\n return delegate.setTimeout(handler, timeout, ...args);\n }\n return setTimeout(handler, timeout, ...args);\n },\n clearTimeout(handle) {\n const { delegate } = timeoutProvider;\n return (delegate?.clearTimeout || clearTimeout)(handle as any);\n },\n delegate: undefined,\n};\n", "import { config } from '../config';\nimport { timeoutProvider } from '../scheduler/timeoutProvider';\n\n/**\n * Handles an error on another job either with the user-configured {@link onUnhandledError},\n * or by throwing it on that new job so it can be picked up by `window.onerror`, `process.on('error')`, etc.\n *\n * This should be called whenever there is an error that is out-of-band with the subscription\n * or when an error hits a terminal boundary of the subscription and no error handler was provided.\n *\n * @param err the error to report\n */\nexport function reportUnhandledError(err: any) {\n timeoutProvider.setTimeout(() => {\n const { onUnhandledError } = config;\n if (onUnhandledError) {\n // Execute the user-configured error handler.\n onUnhandledError(err);\n } else {\n // Throw so it is picked up by the runtime's uncaught error mechanism.\n throw err;\n }\n });\n}\n", "/* tslint:disable:no-empty */\nexport function noop() { }\n", "import { CompleteNotification, NextNotification, ErrorNotification } from './types';\n\n/**\n * A completion object optimized for memory use and created to be the\n * same \"shape\" as other notifications in v8.\n * @internal\n */\nexport const COMPLETE_NOTIFICATION = (() => createNotification('C', undefined, undefined) as CompleteNotification)();\n\n/**\n * Internal use only. Creates an optimized error notification that is the same \"shape\"\n * as other notifications.\n * @internal\n */\nexport function errorNotification(error: any): ErrorNotification {\n return createNotification('E', undefined, error) as any;\n}\n\n/**\n * Internal use only. Creates an optimized next notification that is the same \"shape\"\n * as other notifications.\n * @internal\n */\nexport function nextNotification(value: T) {\n return createNotification('N', value, undefined) as NextNotification;\n}\n\n/**\n * Ensures that all notifications created internally have the same \"shape\" in v8.\n *\n * TODO: This is only exported to support a crazy legacy test in `groupBy`.\n * @internal\n */\nexport function createNotification(kind: 'N' | 'E' | 'C', value: any, error: any) {\n return {\n kind,\n value,\n error,\n };\n}\n", "import { config } from '../config';\n\nlet context: { errorThrown: boolean; error: any } | null = null;\n\n/**\n * Handles dealing with errors for super-gross mode. Creates a context, in which\n * any synchronously thrown errors will be passed to {@link captureError}. Which\n * will record the error such that it will be rethrown after the call back is complete.\n * TODO: Remove in v8\n * @param cb An immediately executed function.\n */\nexport function errorContext(cb: () => void) {\n if (config.useDeprecatedSynchronousErrorHandling) {\n const isRoot = !context;\n if (isRoot) {\n context = { errorThrown: false, error: null };\n }\n cb();\n if (isRoot) {\n const { errorThrown, error } = context!;\n context = null;\n if (errorThrown) {\n throw error;\n }\n }\n } else {\n // This is the general non-deprecated path for everyone that\n // isn't crazy enough to use super-gross mode (useDeprecatedSynchronousErrorHandling)\n cb();\n }\n}\n\n/**\n * Captures errors only in super-gross mode.\n * @param err the error to capture\n */\nexport function captureError(err: any) {\n if (config.useDeprecatedSynchronousErrorHandling && context) {\n context.errorThrown = true;\n context.error = err;\n }\n}\n", "import { isFunction } from './util/isFunction';\nimport { Observer, ObservableNotification } from './types';\nimport { isSubscription, Subscription } from './Subscription';\nimport { config } from './config';\nimport { reportUnhandledError } from './util/reportUnhandledError';\nimport { noop } from './util/noop';\nimport { nextNotification, errorNotification, COMPLETE_NOTIFICATION } from './NotificationFactories';\nimport { timeoutProvider } from './scheduler/timeoutProvider';\nimport { captureError } from './util/errorContext';\n\n/**\n * Implements the {@link Observer} interface and extends the\n * {@link Subscription} class. While the {@link Observer} is the public API for\n * consuming the values of an {@link Observable}, all Observers get converted to\n * a Subscriber, in order to provide Subscription-like capabilities such as\n * `unsubscribe`. Subscriber is a common type in RxJS, and crucial for\n * implementing operators, but it is rarely used as a public API.\n *\n * @class Subscriber\n */\nexport class Subscriber extends Subscription implements Observer {\n /**\n * A static factory for a Subscriber, given a (potentially partial) definition\n * of an Observer.\n * @param next The `next` callback of an Observer.\n * @param error The `error` callback of an\n * Observer.\n * @param complete The `complete` callback of an\n * Observer.\n * @return A Subscriber wrapping the (partially defined)\n * Observer represented by the given arguments.\n * @nocollapse\n * @deprecated Do not use. Will be removed in v8. There is no replacement for this\n * method, and there is no reason to be creating instances of `Subscriber` directly.\n * If you have a specific use case, please file an issue.\n */\n static create(next?: (x?: T) => void, error?: (e?: any) => void, complete?: () => void): Subscriber {\n return new SafeSubscriber(next, error, complete);\n }\n\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n protected isStopped: boolean = false;\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n protected destination: Subscriber | Observer; // this `any` is the escape hatch to erase extra type param (e.g. R)\n\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n * There is no reason to directly create an instance of Subscriber. This type is exported for typings reasons.\n */\n constructor(destination?: Subscriber | Observer) {\n super();\n if (destination) {\n this.destination = destination;\n // Automatically chain subscriptions together here.\n // if destination is a Subscription, then it is a Subscriber.\n if (isSubscription(destination)) {\n destination.add(this);\n }\n } else {\n this.destination = EMPTY_OBSERVER;\n }\n }\n\n /**\n * The {@link Observer} callback to receive notifications of type `next` from\n * the Observable, with a value. The Observable may call this method 0 or more\n * times.\n * @param {T} [value] The `next` value.\n * @return {void}\n */\n next(value?: T): void {\n if (this.isStopped) {\n handleStoppedNotification(nextNotification(value), this);\n } else {\n this._next(value!);\n }\n }\n\n /**\n * The {@link Observer} callback to receive notifications of type `error` from\n * the Observable, with an attached `Error`. Notifies the Observer that\n * the Observable has experienced an error condition.\n * @param {any} [err] The `error` exception.\n * @return {void}\n */\n error(err?: any): void {\n if (this.isStopped) {\n handleStoppedNotification(errorNotification(err), this);\n } else {\n this.isStopped = true;\n this._error(err);\n }\n }\n\n /**\n * The {@link Observer} callback to receive a valueless notification of type\n * `complete` from the Observable. Notifies the Observer that the Observable\n * has finished sending push-based notifications.\n * @return {void}\n */\n complete(): void {\n if (this.isStopped) {\n handleStoppedNotification(COMPLETE_NOTIFICATION, this);\n } else {\n this.isStopped = true;\n this._complete();\n }\n }\n\n unsubscribe(): void {\n if (!this.closed) {\n this.isStopped = true;\n super.unsubscribe();\n this.destination = null!;\n }\n }\n\n protected _next(value: T): void {\n this.destination.next(value);\n }\n\n protected _error(err: any): void {\n try {\n this.destination.error(err);\n } finally {\n this.unsubscribe();\n }\n }\n\n protected _complete(): void {\n try {\n this.destination.complete();\n } finally {\n this.unsubscribe();\n }\n }\n}\n\n/**\n * This bind is captured here because we want to be able to have\n * compatibility with monoid libraries that tend to use a method named\n * `bind`. In particular, a library called Monio requires this.\n */\nconst _bind = Function.prototype.bind;\n\nfunction bind any>(fn: Fn, thisArg: any): Fn {\n return _bind.call(fn, thisArg);\n}\n\n/**\n * Internal optimization only, DO NOT EXPOSE.\n * @internal\n */\nclass ConsumerObserver implements Observer {\n constructor(private partialObserver: Partial>) {}\n\n next(value: T): void {\n const { partialObserver } = this;\n if (partialObserver.next) {\n try {\n partialObserver.next(value);\n } catch (error) {\n handleUnhandledError(error);\n }\n }\n }\n\n error(err: any): void {\n const { partialObserver } = this;\n if (partialObserver.error) {\n try {\n partialObserver.error(err);\n } catch (error) {\n handleUnhandledError(error);\n }\n } else {\n handleUnhandledError(err);\n }\n }\n\n complete(): void {\n const { partialObserver } = this;\n if (partialObserver.complete) {\n try {\n partialObserver.complete();\n } catch (error) {\n handleUnhandledError(error);\n }\n }\n }\n}\n\nexport class SafeSubscriber extends Subscriber {\n constructor(\n observerOrNext?: Partial> | ((value: T) => void) | null,\n error?: ((e?: any) => void) | null,\n complete?: (() => void) | null\n ) {\n super();\n\n let partialObserver: Partial>;\n if (isFunction(observerOrNext) || !observerOrNext) {\n // The first argument is a function, not an observer. The next\n // two arguments *could* be observers, or they could be empty.\n partialObserver = {\n next: (observerOrNext ?? undefined) as (((value: T) => void) | undefined),\n error: error ?? undefined,\n complete: complete ?? undefined,\n };\n } else {\n // The first argument is a partial observer.\n let context: any;\n if (this && config.useDeprecatedNextContext) {\n // This is a deprecated path that made `this.unsubscribe()` available in\n // next handler functions passed to subscribe. This only exists behind a flag\n // now, as it is *very* slow.\n context = Object.create(observerOrNext);\n context.unsubscribe = () => this.unsubscribe();\n partialObserver = {\n next: observerOrNext.next && bind(observerOrNext.next, context),\n error: observerOrNext.error && bind(observerOrNext.error, context),\n complete: observerOrNext.complete && bind(observerOrNext.complete, context),\n };\n } else {\n // The \"normal\" path. Just use the partial observer directly.\n partialObserver = observerOrNext;\n }\n }\n\n // Wrap the partial observer to ensure it's a full observer, and\n // make sure proper error handling is accounted for.\n this.destination = new ConsumerObserver(partialObserver);\n }\n}\n\nfunction handleUnhandledError(error: any) {\n if (config.useDeprecatedSynchronousErrorHandling) {\n captureError(error);\n } else {\n // Ideal path, we report this as an unhandled error,\n // which is thrown on a new call stack.\n reportUnhandledError(error);\n }\n}\n\n/**\n * An error handler used when no error handler was supplied\n * to the SafeSubscriber -- meaning no error handler was supplied\n * do the `subscribe` call on our observable.\n * @param err The error to handle\n */\nfunction defaultErrorHandler(err: any) {\n throw err;\n}\n\n/**\n * A handler for notifications that cannot be sent to a stopped subscriber.\n * @param notification The notification being sent\n * @param subscriber The stopped subscriber\n */\nfunction handleStoppedNotification(notification: ObservableNotification, subscriber: Subscriber) {\n const { onStoppedNotification } = config;\n onStoppedNotification && timeoutProvider.setTimeout(() => onStoppedNotification(notification, subscriber));\n}\n\n/**\n * The observer used as a stub for subscriptions where the user did not\n * pass any arguments to `subscribe`. Comes with the default error handling\n * behavior.\n */\nexport const EMPTY_OBSERVER: Readonly> & { closed: true } = {\n closed: true,\n next: noop,\n error: defaultErrorHandler,\n complete: noop,\n};\n", "/**\n * Symbol.observable or a string \"@@observable\". Used for interop\n *\n * @deprecated We will no longer be exporting this symbol in upcoming versions of RxJS.\n * Instead polyfill and use Symbol.observable directly *or* use https://www.npmjs.com/package/symbol-observable\n */\nexport const observable: string | symbol = (() => (typeof Symbol === 'function' && Symbol.observable) || '@@observable')();\n", "/**\n * This function takes one parameter and just returns it. Simply put,\n * this is like `(x: T): T => x`.\n *\n * ## Examples\n *\n * This is useful in some cases when using things like `mergeMap`\n *\n * ```ts\n * import { interval, take, map, range, mergeMap, identity } from 'rxjs';\n *\n * const source$ = interval(1000).pipe(take(5));\n *\n * const result$ = source$.pipe(\n * map(i => range(i)),\n * mergeMap(identity) // same as mergeMap(x => x)\n * );\n *\n * result$.subscribe({\n * next: console.log\n * });\n * ```\n *\n * Or when you want to selectively apply an operator\n *\n * ```ts\n * import { interval, take, identity } from 'rxjs';\n *\n * const shouldLimit = () => Math.random() < 0.5;\n *\n * const source$ = interval(1000);\n *\n * const result$ = source$.pipe(shouldLimit() ? take(5) : identity);\n *\n * result$.subscribe({\n * next: console.log\n * });\n * ```\n *\n * @param x Any value that is returned by this function\n * @returns The value passed as the first parameter to this function\n */\nexport function identity(x: T): T {\n return x;\n}\n", "import { identity } from './identity';\nimport { UnaryFunction } from '../types';\n\nexport function pipe(): typeof identity;\nexport function pipe(fn1: UnaryFunction): UnaryFunction;\nexport function pipe(fn1: UnaryFunction, fn2: UnaryFunction): UnaryFunction;\nexport function pipe(fn1: UnaryFunction, fn2: UnaryFunction, fn3: UnaryFunction): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction,\n fn9: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction,\n fn9: UnaryFunction,\n ...fns: UnaryFunction[]\n): UnaryFunction;\n\n/**\n * pipe() can be called on one or more functions, each of which can take one argument (\"UnaryFunction\")\n * and uses it to return a value.\n * It returns a function that takes one argument, passes it to the first UnaryFunction, and then\n * passes the result to the next one, passes that result to the next one, and so on. \n */\nexport function pipe(...fns: Array>): UnaryFunction {\n return pipeFromArray(fns);\n}\n\n/** @internal */\nexport function pipeFromArray(fns: Array>): UnaryFunction {\n if (fns.length === 0) {\n return identity as UnaryFunction;\n }\n\n if (fns.length === 1) {\n return fns[0];\n }\n\n return function piped(input: T): R {\n return fns.reduce((prev: any, fn: UnaryFunction) => fn(prev), input as any);\n };\n}\n", "import { Operator } from './Operator';\nimport { SafeSubscriber, Subscriber } from './Subscriber';\nimport { isSubscription, Subscription } from './Subscription';\nimport { TeardownLogic, OperatorFunction, Subscribable, Observer } from './types';\nimport { observable as Symbol_observable } from './symbol/observable';\nimport { pipeFromArray } from './util/pipe';\nimport { config } from './config';\nimport { isFunction } from './util/isFunction';\nimport { errorContext } from './util/errorContext';\n\n/**\n * A representation of any set of values over any amount of time. This is the most basic building block\n * of RxJS.\n *\n * @class Observable\n */\nexport class Observable implements Subscribable {\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n */\n source: Observable | undefined;\n\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n */\n operator: Operator | undefined;\n\n /**\n * @constructor\n * @param {Function} subscribe the function that is called when the Observable is\n * initially subscribed to. This function is given a Subscriber, to which new values\n * can be `next`ed, or an `error` method can be called to raise an error, or\n * `complete` can be called to notify of a successful completion.\n */\n constructor(subscribe?: (this: Observable, subscriber: Subscriber) => TeardownLogic) {\n if (subscribe) {\n this._subscribe = subscribe;\n }\n }\n\n // HACK: Since TypeScript inherits static properties too, we have to\n // fight against TypeScript here so Subject can have a different static create signature\n /**\n * Creates a new Observable by calling the Observable constructor\n * @owner Observable\n * @method create\n * @param {Function} subscribe? the subscriber function to be passed to the Observable constructor\n * @return {Observable} a new observable\n * @nocollapse\n * @deprecated Use `new Observable()` instead. Will be removed in v8.\n */\n static create: (...args: any[]) => any = (subscribe?: (subscriber: Subscriber) => TeardownLogic) => {\n return new Observable(subscribe);\n };\n\n /**\n * Creates a new Observable, with this Observable instance as the source, and the passed\n * operator defined as the new observable's operator.\n * @method lift\n * @param operator the operator defining the operation to take on the observable\n * @return a new observable with the Operator applied\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n * If you have implemented an operator using `lift`, it is recommended that you create an\n * operator by simply returning `new Observable()` directly. See \"Creating new operators from\n * scratch\" section here: https://rxjs.dev/guide/operators\n */\n lift(operator?: Operator): Observable {\n const observable = new Observable();\n observable.source = this;\n observable.operator = operator;\n return observable;\n }\n\n subscribe(observerOrNext?: Partial> | ((value: T) => void)): Subscription;\n /** @deprecated Instead of passing separate callback arguments, use an observer argument. Signatures taking separate callback arguments will be removed in v8. Details: https://rxjs.dev/deprecations/subscribe-arguments */\n subscribe(next?: ((value: T) => void) | null, error?: ((error: any) => void) | null, complete?: (() => void) | null): Subscription;\n /**\n * Invokes an execution of an Observable and registers Observer handlers for notifications it will emit.\n *\n * Use it when you have all these Observables, but still nothing is happening.\n *\n * `subscribe` is not a regular operator, but a method that calls Observable's internal `subscribe` function. It\n * might be for example a function that you passed to Observable's constructor, but most of the time it is\n * a library implementation, which defines what will be emitted by an Observable, and when it be will emitted. This means\n * that calling `subscribe` is actually the moment when Observable starts its work, not when it is created, as it is often\n * the thought.\n *\n * Apart from starting the execution of an Observable, this method allows you to listen for values\n * that an Observable emits, as well as for when it completes or errors. You can achieve this in two\n * of the following ways.\n *\n * The first way is creating an object that implements {@link Observer} interface. It should have methods\n * defined by that interface, but note that it should be just a regular JavaScript object, which you can create\n * yourself in any way you want (ES6 class, classic function constructor, object literal etc.). In particular, do\n * not attempt to use any RxJS implementation details to create Observers - you don't need them. Remember also\n * that your object does not have to implement all methods. If you find yourself creating a method that doesn't\n * do anything, you can simply omit it. Note however, if the `error` method is not provided and an error happens,\n * it will be thrown asynchronously. Errors thrown asynchronously cannot be caught using `try`/`catch`. Instead,\n * use the {@link onUnhandledError} configuration option or use a runtime handler (like `window.onerror` or\n * `process.on('error)`) to be notified of unhandled errors. Because of this, it's recommended that you provide\n * an `error` method to avoid missing thrown errors.\n *\n * The second way is to give up on Observer object altogether and simply provide callback functions in place of its methods.\n * This means you can provide three functions as arguments to `subscribe`, where the first function is equivalent\n * of a `next` method, the second of an `error` method and the third of a `complete` method. Just as in case of an Observer,\n * if you do not need to listen for something, you can omit a function by passing `undefined` or `null`,\n * since `subscribe` recognizes these functions by where they were placed in function call. When it comes\n * to the `error` function, as with an Observer, if not provided, errors emitted by an Observable will be thrown asynchronously.\n *\n * You can, however, subscribe with no parameters at all. This may be the case where you're not interested in terminal events\n * and you also handled emissions internally by using operators (e.g. using `tap`).\n *\n * Whichever style of calling `subscribe` you use, in both cases it returns a Subscription object.\n * This object allows you to call `unsubscribe` on it, which in turn will stop the work that an Observable does and will clean\n * up all resources that an Observable used. Note that cancelling a subscription will not call `complete` callback\n * provided to `subscribe` function, which is reserved for a regular completion signal that comes from an Observable.\n *\n * Remember that callbacks provided to `subscribe` are not guaranteed to be called asynchronously.\n * It is an Observable itself that decides when these functions will be called. For example {@link of}\n * by default emits all its values synchronously. Always check documentation for how given Observable\n * will behave when subscribed and if its default behavior can be modified with a `scheduler`.\n *\n * #### Examples\n *\n * Subscribe with an {@link guide/observer Observer}\n *\n * ```ts\n * import { of } from 'rxjs';\n *\n * const sumObserver = {\n * sum: 0,\n * next(value) {\n * console.log('Adding: ' + value);\n * this.sum = this.sum + value;\n * },\n * error() {\n * // We actually could just remove this method,\n * // since we do not really care about errors right now.\n * },\n * complete() {\n * console.log('Sum equals: ' + this.sum);\n * }\n * };\n *\n * of(1, 2, 3) // Synchronously emits 1, 2, 3 and then completes.\n * .subscribe(sumObserver);\n *\n * // Logs:\n * // 'Adding: 1'\n * // 'Adding: 2'\n * // 'Adding: 3'\n * // 'Sum equals: 6'\n * ```\n *\n * Subscribe with functions ({@link deprecations/subscribe-arguments deprecated})\n *\n * ```ts\n * import { of } from 'rxjs'\n *\n * let sum = 0;\n *\n * of(1, 2, 3).subscribe(\n * value => {\n * console.log('Adding: ' + value);\n * sum = sum + value;\n * },\n * undefined,\n * () => console.log('Sum equals: ' + sum)\n * );\n *\n * // Logs:\n * // 'Adding: 1'\n * // 'Adding: 2'\n * // 'Adding: 3'\n * // 'Sum equals: 6'\n * ```\n *\n * Cancel a subscription\n *\n * ```ts\n * import { interval } from 'rxjs';\n *\n * const subscription = interval(1000).subscribe({\n * next(num) {\n * console.log(num)\n * },\n * complete() {\n * // Will not be called, even when cancelling subscription.\n * console.log('completed!');\n * }\n * });\n *\n * setTimeout(() => {\n * subscription.unsubscribe();\n * console.log('unsubscribed!');\n * }, 2500);\n *\n * // Logs:\n * // 0 after 1s\n * // 1 after 2s\n * // 'unsubscribed!' after 2.5s\n * ```\n *\n * @param {Observer|Function} observerOrNext (optional) Either an observer with methods to be called,\n * or the first of three possible handlers, which is the handler for each value emitted from the subscribed\n * Observable.\n * @param {Function} error (optional) A handler for a terminal event resulting from an error. If no error handler is provided,\n * the error will be thrown asynchronously as unhandled.\n * @param {Function} complete (optional) A handler for a terminal event resulting from successful completion.\n * @return {Subscription} a subscription reference to the registered handlers\n * @method subscribe\n */\n subscribe(\n observerOrNext?: Partial> | ((value: T) => void) | null,\n error?: ((error: any) => void) | null,\n complete?: (() => void) | null\n ): Subscription {\n const subscriber = isSubscriber(observerOrNext) ? observerOrNext : new SafeSubscriber(observerOrNext, error, complete);\n\n errorContext(() => {\n const { operator, source } = this;\n subscriber.add(\n operator\n ? // We're dealing with a subscription in the\n // operator chain to one of our lifted operators.\n operator.call(subscriber, source)\n : source\n ? // If `source` has a value, but `operator` does not, something that\n // had intimate knowledge of our API, like our `Subject`, must have\n // set it. We're going to just call `_subscribe` directly.\n this._subscribe(subscriber)\n : // In all other cases, we're likely wrapping a user-provided initializer\n // function, so we need to catch errors and handle them appropriately.\n this._trySubscribe(subscriber)\n );\n });\n\n return subscriber;\n }\n\n /** @internal */\n protected _trySubscribe(sink: Subscriber): TeardownLogic {\n try {\n return this._subscribe(sink);\n } catch (err) {\n // We don't need to return anything in this case,\n // because it's just going to try to `add()` to a subscription\n // above.\n sink.error(err);\n }\n }\n\n /**\n * Used as a NON-CANCELLABLE means of subscribing to an observable, for use with\n * APIs that expect promises, like `async/await`. You cannot unsubscribe from this.\n *\n * **WARNING**: Only use this with observables you *know* will complete. If the source\n * observable does not complete, you will end up with a promise that is hung up, and\n * potentially all of the state of an async function hanging out in memory. To avoid\n * this situation, look into adding something like {@link timeout}, {@link take},\n * {@link takeWhile}, or {@link takeUntil} amongst others.\n *\n * #### Example\n *\n * ```ts\n * import { interval, take } from 'rxjs';\n *\n * const source$ = interval(1000).pipe(take(4));\n *\n * async function getTotal() {\n * let total = 0;\n *\n * await source$.forEach(value => {\n * total += value;\n * console.log('observable -> ' + value);\n * });\n *\n * return total;\n * }\n *\n * getTotal().then(\n * total => console.log('Total: ' + total)\n * );\n *\n * // Expected:\n * // 'observable -> 0'\n * // 'observable -> 1'\n * // 'observable -> 2'\n * // 'observable -> 3'\n * // 'Total: 6'\n * ```\n *\n * @param next a handler for each value emitted by the observable\n * @return a promise that either resolves on observable completion or\n * rejects with the handled error\n */\n forEach(next: (value: T) => void): Promise;\n\n /**\n * @param next a handler for each value emitted by the observable\n * @param promiseCtor a constructor function used to instantiate the Promise\n * @return a promise that either resolves on observable completion or\n * rejects with the handled error\n * @deprecated Passing a Promise constructor will no longer be available\n * in upcoming versions of RxJS. This is because it adds weight to the library, for very\n * little benefit. If you need this functionality, it is recommended that you either\n * polyfill Promise, or you create an adapter to convert the returned native promise\n * to whatever promise implementation you wanted. Will be removed in v8.\n */\n forEach(next: (value: T) => void, promiseCtor: PromiseConstructorLike): Promise;\n\n forEach(next: (value: T) => void, promiseCtor?: PromiseConstructorLike): Promise {\n promiseCtor = getPromiseCtor(promiseCtor);\n\n return new promiseCtor((resolve, reject) => {\n const subscriber = new SafeSubscriber({\n next: (value) => {\n try {\n next(value);\n } catch (err) {\n reject(err);\n subscriber.unsubscribe();\n }\n },\n error: reject,\n complete: resolve,\n });\n this.subscribe(subscriber);\n }) as Promise;\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): TeardownLogic {\n return this.source?.subscribe(subscriber);\n }\n\n /**\n * An interop point defined by the es7-observable spec https://github.com/zenparsing/es-observable\n * @method Symbol.observable\n * @return {Observable} this instance of the observable\n */\n [Symbol_observable]() {\n return this;\n }\n\n /* tslint:disable:max-line-length */\n pipe(): Observable;\n pipe(op1: OperatorFunction): Observable;\n pipe(op1: OperatorFunction, op2: OperatorFunction): Observable;\n pipe(op1: OperatorFunction, op2: OperatorFunction, op3: OperatorFunction): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction,\n op8: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction,\n op8: OperatorFunction,\n op9: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction,\n op8: OperatorFunction,\n op9: OperatorFunction,\n ...operations: OperatorFunction[]\n ): Observable;\n /* tslint:enable:max-line-length */\n\n /**\n * Used to stitch together functional operators into a chain.\n * @method pipe\n * @return {Observable} the Observable result of all of the operators having\n * been called in the order they were passed in.\n *\n * ## Example\n *\n * ```ts\n * import { interval, filter, map, scan } from 'rxjs';\n *\n * interval(1000)\n * .pipe(\n * filter(x => x % 2 === 0),\n * map(x => x + x),\n * scan((acc, x) => acc + x)\n * )\n * .subscribe(x => console.log(x));\n * ```\n */\n pipe(...operations: OperatorFunction[]): Observable {\n return pipeFromArray(operations)(this);\n }\n\n /* tslint:disable:max-line-length */\n /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */\n toPromise(): Promise;\n /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */\n toPromise(PromiseCtor: typeof Promise): Promise;\n /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */\n toPromise(PromiseCtor: PromiseConstructorLike): Promise;\n /* tslint:enable:max-line-length */\n\n /**\n * Subscribe to this Observable and get a Promise resolving on\n * `complete` with the last emission (if any).\n *\n * **WARNING**: Only use this with observables you *know* will complete. If the source\n * observable does not complete, you will end up with a promise that is hung up, and\n * potentially all of the state of an async function hanging out in memory. To avoid\n * this situation, look into adding something like {@link timeout}, {@link take},\n * {@link takeWhile}, or {@link takeUntil} amongst others.\n *\n * @method toPromise\n * @param [promiseCtor] a constructor function used to instantiate\n * the Promise\n * @return A Promise that resolves with the last value emit, or\n * rejects on an error. If there were no emissions, Promise\n * resolves with undefined.\n * @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise\n */\n toPromise(promiseCtor?: PromiseConstructorLike): Promise {\n promiseCtor = getPromiseCtor(promiseCtor);\n\n return new promiseCtor((resolve, reject) => {\n let value: T | undefined;\n this.subscribe(\n (x: T) => (value = x),\n (err: any) => reject(err),\n () => resolve(value)\n );\n }) as Promise;\n }\n}\n\n/**\n * Decides between a passed promise constructor from consuming code,\n * A default configured promise constructor, and the native promise\n * constructor and returns it. If nothing can be found, it will throw\n * an error.\n * @param promiseCtor The optional promise constructor to passed by consuming code\n */\nfunction getPromiseCtor(promiseCtor: PromiseConstructorLike | undefined) {\n return promiseCtor ?? config.Promise ?? Promise;\n}\n\nfunction isObserver(value: any): value is Observer {\n return value && isFunction(value.next) && isFunction(value.error) && isFunction(value.complete);\n}\n\nfunction isSubscriber(value: any): value is Subscriber {\n return (value && value instanceof Subscriber) || (isObserver(value) && isSubscription(value));\n}\n", "import { Observable } from '../Observable';\nimport { Subscriber } from '../Subscriber';\nimport { OperatorFunction } from '../types';\nimport { isFunction } from './isFunction';\n\n/**\n * Used to determine if an object is an Observable with a lift function.\n */\nexport function hasLift(source: any): source is { lift: InstanceType['lift'] } {\n return isFunction(source?.lift);\n}\n\n/**\n * Creates an `OperatorFunction`. Used to define operators throughout the library in a concise way.\n * @param init The logic to connect the liftedSource to the subscriber at the moment of subscription.\n */\nexport function operate(\n init: (liftedSource: Observable, subscriber: Subscriber) => (() => void) | void\n): OperatorFunction {\n return (source: Observable) => {\n if (hasLift(source)) {\n return source.lift(function (this: Subscriber, liftedSource: Observable) {\n try {\n return init(liftedSource, this);\n } catch (err) {\n this.error(err);\n }\n });\n }\n throw new TypeError('Unable to lift unknown Observable type');\n };\n}\n", "import { Subscriber } from '../Subscriber';\n\n/**\n * Creates an instance of an `OperatorSubscriber`.\n * @param destination The downstream subscriber.\n * @param onNext Handles next values, only called if this subscriber is not stopped or closed. Any\n * error that occurs in this function is caught and sent to the `error` method of this subscriber.\n * @param onError Handles errors from the subscription, any errors that occur in this handler are caught\n * and send to the `destination` error handler.\n * @param onComplete Handles completion notification from the subscription. Any errors that occur in\n * this handler are sent to the `destination` error handler.\n * @param onFinalize Additional teardown logic here. This will only be called on teardown if the\n * subscriber itself is not already closed. This is called after all other teardown logic is executed.\n */\nexport function createOperatorSubscriber(\n destination: Subscriber,\n onNext?: (value: T) => void,\n onComplete?: () => void,\n onError?: (err: any) => void,\n onFinalize?: () => void\n): Subscriber {\n return new OperatorSubscriber(destination, onNext, onComplete, onError, onFinalize);\n}\n\n/**\n * A generic helper for allowing operators to be created with a Subscriber and\n * use closures to capture necessary state from the operator function itself.\n */\nexport class OperatorSubscriber extends Subscriber {\n /**\n * Creates an instance of an `OperatorSubscriber`.\n * @param destination The downstream subscriber.\n * @param onNext Handles next values, only called if this subscriber is not stopped or closed. Any\n * error that occurs in this function is caught and sent to the `error` method of this subscriber.\n * @param onError Handles errors from the subscription, any errors that occur in this handler are caught\n * and send to the `destination` error handler.\n * @param onComplete Handles completion notification from the subscription. Any errors that occur in\n * this handler are sent to the `destination` error handler.\n * @param onFinalize Additional finalization logic here. This will only be called on finalization if the\n * subscriber itself is not already closed. This is called after all other finalization logic is executed.\n * @param shouldUnsubscribe An optional check to see if an unsubscribe call should truly unsubscribe.\n * NOTE: This currently **ONLY** exists to support the strange behavior of {@link groupBy}, where unsubscription\n * to the resulting observable does not actually disconnect from the source if there are active subscriptions\n * to any grouped observable. (DO NOT EXPOSE OR USE EXTERNALLY!!!)\n */\n constructor(\n destination: Subscriber,\n onNext?: (value: T) => void,\n onComplete?: () => void,\n onError?: (err: any) => void,\n private onFinalize?: () => void,\n private shouldUnsubscribe?: () => boolean\n ) {\n // It's important - for performance reasons - that all of this class's\n // members are initialized and that they are always initialized in the same\n // order. This will ensure that all OperatorSubscriber instances have the\n // same hidden class in V8. This, in turn, will help keep the number of\n // hidden classes involved in property accesses within the base class as\n // low as possible. If the number of hidden classes involved exceeds four,\n // the property accesses will become megamorphic and performance penalties\n // will be incurred - i.e. inline caches won't be used.\n //\n // The reasons for ensuring all instances have the same hidden class are\n // further discussed in this blog post from Benedikt Meurer:\n // https://benediktmeurer.de/2018/03/23/impact-of-polymorphism-on-component-based-frameworks-like-react/\n super(destination);\n this._next = onNext\n ? function (this: OperatorSubscriber, value: T) {\n try {\n onNext(value);\n } catch (err) {\n destination.error(err);\n }\n }\n : super._next;\n this._error = onError\n ? function (this: OperatorSubscriber, err: any) {\n try {\n onError(err);\n } catch (err) {\n // Send any errors that occur down stream.\n destination.error(err);\n } finally {\n // Ensure finalization.\n this.unsubscribe();\n }\n }\n : super._error;\n this._complete = onComplete\n ? function (this: OperatorSubscriber) {\n try {\n onComplete();\n } catch (err) {\n // Send any errors that occur down stream.\n destination.error(err);\n } finally {\n // Ensure finalization.\n this.unsubscribe();\n }\n }\n : super._complete;\n }\n\n unsubscribe() {\n if (!this.shouldUnsubscribe || this.shouldUnsubscribe()) {\n const { closed } = this;\n super.unsubscribe();\n // Execute additional teardown if we have any and we didn't already do so.\n !closed && this.onFinalize?.();\n }\n }\n}\n", "import { Subscription } from '../Subscription';\n\ninterface AnimationFrameProvider {\n schedule(callback: FrameRequestCallback): Subscription;\n requestAnimationFrame: typeof requestAnimationFrame;\n cancelAnimationFrame: typeof cancelAnimationFrame;\n delegate:\n | {\n requestAnimationFrame: typeof requestAnimationFrame;\n cancelAnimationFrame: typeof cancelAnimationFrame;\n }\n | undefined;\n}\n\nexport const animationFrameProvider: AnimationFrameProvider = {\n // When accessing the delegate, use the variable rather than `this` so that\n // the functions can be called without being bound to the provider.\n schedule(callback) {\n let request = requestAnimationFrame;\n let cancel: typeof cancelAnimationFrame | undefined = cancelAnimationFrame;\n const { delegate } = animationFrameProvider;\n if (delegate) {\n request = delegate.requestAnimationFrame;\n cancel = delegate.cancelAnimationFrame;\n }\n const handle = request((timestamp) => {\n // Clear the cancel function. The request has been fulfilled, so\n // attempting to cancel the request upon unsubscription would be\n // pointless.\n cancel = undefined;\n callback(timestamp);\n });\n return new Subscription(() => cancel?.(handle));\n },\n requestAnimationFrame(...args) {\n const { delegate } = animationFrameProvider;\n return (delegate?.requestAnimationFrame || requestAnimationFrame)(...args);\n },\n cancelAnimationFrame(...args) {\n const { delegate } = animationFrameProvider;\n return (delegate?.cancelAnimationFrame || cancelAnimationFrame)(...args);\n },\n delegate: undefined,\n};\n", "import { createErrorClass } from './createErrorClass';\n\nexport interface ObjectUnsubscribedError extends Error {}\n\nexport interface ObjectUnsubscribedErrorCtor {\n /**\n * @deprecated Internal implementation detail. Do not construct error instances.\n * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269\n */\n new (): ObjectUnsubscribedError;\n}\n\n/**\n * An error thrown when an action is invalid because the object has been\n * unsubscribed.\n *\n * @see {@link Subject}\n * @see {@link BehaviorSubject}\n *\n * @class ObjectUnsubscribedError\n */\nexport const ObjectUnsubscribedError: ObjectUnsubscribedErrorCtor = createErrorClass(\n (_super) =>\n function ObjectUnsubscribedErrorImpl(this: any) {\n _super(this);\n this.name = 'ObjectUnsubscribedError';\n this.message = 'object unsubscribed';\n }\n);\n", "import { Operator } from './Operator';\nimport { Observable } from './Observable';\nimport { Subscriber } from './Subscriber';\nimport { Subscription, EMPTY_SUBSCRIPTION } from './Subscription';\nimport { Observer, SubscriptionLike, TeardownLogic } from './types';\nimport { ObjectUnsubscribedError } from './util/ObjectUnsubscribedError';\nimport { arrRemove } from './util/arrRemove';\nimport { errorContext } from './util/errorContext';\n\n/**\n * A Subject is a special type of Observable that allows values to be\n * multicasted to many Observers. Subjects are like EventEmitters.\n *\n * Every Subject is an Observable and an Observer. You can subscribe to a\n * Subject, and you can call next to feed values as well as error and complete.\n */\nexport class Subject extends Observable implements SubscriptionLike {\n closed = false;\n\n private currentObservers: Observer[] | null = null;\n\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n observers: Observer[] = [];\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n isStopped = false;\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n hasError = false;\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n thrownError: any = null;\n\n /**\n * Creates a \"subject\" by basically gluing an observer to an observable.\n *\n * @nocollapse\n * @deprecated Recommended you do not use. Will be removed at some point in the future. Plans for replacement still under discussion.\n */\n static create: (...args: any[]) => any = (destination: Observer, source: Observable): AnonymousSubject => {\n return new AnonymousSubject(destination, source);\n };\n\n constructor() {\n // NOTE: This must be here to obscure Observable's constructor.\n super();\n }\n\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n lift(operator: Operator): Observable {\n const subject = new AnonymousSubject(this, this);\n subject.operator = operator as any;\n return subject as any;\n }\n\n /** @internal */\n protected _throwIfClosed() {\n if (this.closed) {\n throw new ObjectUnsubscribedError();\n }\n }\n\n next(value: T) {\n errorContext(() => {\n this._throwIfClosed();\n if (!this.isStopped) {\n if (!this.currentObservers) {\n this.currentObservers = Array.from(this.observers);\n }\n for (const observer of this.currentObservers) {\n observer.next(value);\n }\n }\n });\n }\n\n error(err: any) {\n errorContext(() => {\n this._throwIfClosed();\n if (!this.isStopped) {\n this.hasError = this.isStopped = true;\n this.thrownError = err;\n const { observers } = this;\n while (observers.length) {\n observers.shift()!.error(err);\n }\n }\n });\n }\n\n complete() {\n errorContext(() => {\n this._throwIfClosed();\n if (!this.isStopped) {\n this.isStopped = true;\n const { observers } = this;\n while (observers.length) {\n observers.shift()!.complete();\n }\n }\n });\n }\n\n unsubscribe() {\n this.isStopped = this.closed = true;\n this.observers = this.currentObservers = null!;\n }\n\n get observed() {\n return this.observers?.length > 0;\n }\n\n /** @internal */\n protected _trySubscribe(subscriber: Subscriber): TeardownLogic {\n this._throwIfClosed();\n return super._trySubscribe(subscriber);\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n this._throwIfClosed();\n this._checkFinalizedStatuses(subscriber);\n return this._innerSubscribe(subscriber);\n }\n\n /** @internal */\n protected _innerSubscribe(subscriber: Subscriber) {\n const { hasError, isStopped, observers } = this;\n if (hasError || isStopped) {\n return EMPTY_SUBSCRIPTION;\n }\n this.currentObservers = null;\n observers.push(subscriber);\n return new Subscription(() => {\n this.currentObservers = null;\n arrRemove(observers, subscriber);\n });\n }\n\n /** @internal */\n protected _checkFinalizedStatuses(subscriber: Subscriber) {\n const { hasError, thrownError, isStopped } = this;\n if (hasError) {\n subscriber.error(thrownError);\n } else if (isStopped) {\n subscriber.complete();\n }\n }\n\n /**\n * Creates a new Observable with this Subject as the source. You can do this\n * to create custom Observer-side logic of the Subject and conceal it from\n * code that uses the Observable.\n * @return {Observable} Observable that the Subject casts to\n */\n asObservable(): Observable {\n const observable: any = new Observable();\n observable.source = this;\n return observable;\n }\n}\n\n/**\n * @class AnonymousSubject\n */\nexport class AnonymousSubject extends Subject {\n constructor(\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n public destination?: Observer,\n source?: Observable\n ) {\n super();\n this.source = source;\n }\n\n next(value: T) {\n this.destination?.next?.(value);\n }\n\n error(err: any) {\n this.destination?.error?.(err);\n }\n\n complete() {\n this.destination?.complete?.();\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n return this.source?.subscribe(subscriber) ?? EMPTY_SUBSCRIPTION;\n }\n}\n", "import { Subject } from './Subject';\nimport { Subscriber } from './Subscriber';\nimport { Subscription } from './Subscription';\n\n/**\n * A variant of Subject that requires an initial value and emits its current\n * value whenever it is subscribed to.\n *\n * @class BehaviorSubject\n */\nexport class BehaviorSubject extends Subject {\n constructor(private _value: T) {\n super();\n }\n\n get value(): T {\n return this.getValue();\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n const subscription = super._subscribe(subscriber);\n !subscription.closed && subscriber.next(this._value);\n return subscription;\n }\n\n getValue(): T {\n const { hasError, thrownError, _value } = this;\n if (hasError) {\n throw thrownError;\n }\n this._throwIfClosed();\n return _value;\n }\n\n next(value: T): void {\n super.next((this._value = value));\n }\n}\n", "import { TimestampProvider } from '../types';\n\ninterface DateTimestampProvider extends TimestampProvider {\n delegate: TimestampProvider | undefined;\n}\n\nexport const dateTimestampProvider: DateTimestampProvider = {\n now() {\n // Use the variable rather than `this` so that the function can be called\n // without being bound to the provider.\n return (dateTimestampProvider.delegate || Date).now();\n },\n delegate: undefined,\n};\n", "import { Subject } from './Subject';\nimport { TimestampProvider } from './types';\nimport { Subscriber } from './Subscriber';\nimport { Subscription } from './Subscription';\nimport { dateTimestampProvider } from './scheduler/dateTimestampProvider';\n\n/**\n * A variant of {@link Subject} that \"replays\" old values to new subscribers by emitting them when they first subscribe.\n *\n * `ReplaySubject` has an internal buffer that will store a specified number of values that it has observed. Like `Subject`,\n * `ReplaySubject` \"observes\" values by having them passed to its `next` method. When it observes a value, it will store that\n * value for a time determined by the configuration of the `ReplaySubject`, as passed to its constructor.\n *\n * When a new subscriber subscribes to the `ReplaySubject` instance, it will synchronously emit all values in its buffer in\n * a First-In-First-Out (FIFO) manner. The `ReplaySubject` will also complete, if it has observed completion; and it will\n * error if it has observed an error.\n *\n * There are two main configuration items to be concerned with:\n *\n * 1. `bufferSize` - This will determine how many items are stored in the buffer, defaults to infinite.\n * 2. `windowTime` - The amount of time to hold a value in the buffer before removing it from the buffer.\n *\n * Both configurations may exist simultaneously. So if you would like to buffer a maximum of 3 values, as long as the values\n * are less than 2 seconds old, you could do so with a `new ReplaySubject(3, 2000)`.\n *\n * ### Differences with BehaviorSubject\n *\n * `BehaviorSubject` is similar to `new ReplaySubject(1)`, with a couple of exceptions:\n *\n * 1. `BehaviorSubject` comes \"primed\" with a single value upon construction.\n * 2. `ReplaySubject` will replay values, even after observing an error, where `BehaviorSubject` will not.\n *\n * @see {@link Subject}\n * @see {@link BehaviorSubject}\n * @see {@link shareReplay}\n */\nexport class ReplaySubject extends Subject {\n private _buffer: (T | number)[] = [];\n private _infiniteTimeWindow = true;\n\n /**\n * @param bufferSize The size of the buffer to replay on subscription\n * @param windowTime The amount of time the buffered items will stay buffered\n * @param timestampProvider An object with a `now()` method that provides the current timestamp. This is used to\n * calculate the amount of time something has been buffered.\n */\n constructor(\n private _bufferSize = Infinity,\n private _windowTime = Infinity,\n private _timestampProvider: TimestampProvider = dateTimestampProvider\n ) {\n super();\n this._infiniteTimeWindow = _windowTime === Infinity;\n this._bufferSize = Math.max(1, _bufferSize);\n this._windowTime = Math.max(1, _windowTime);\n }\n\n next(value: T): void {\n const { isStopped, _buffer, _infiniteTimeWindow, _timestampProvider, _windowTime } = this;\n if (!isStopped) {\n _buffer.push(value);\n !_infiniteTimeWindow && _buffer.push(_timestampProvider.now() + _windowTime);\n }\n this._trimBuffer();\n super.next(value);\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n this._throwIfClosed();\n this._trimBuffer();\n\n const subscription = this._innerSubscribe(subscriber);\n\n const { _infiniteTimeWindow, _buffer } = this;\n // We use a copy here, so reentrant code does not mutate our array while we're\n // emitting it to a new subscriber.\n const copy = _buffer.slice();\n for (let i = 0; i < copy.length && !subscriber.closed; i += _infiniteTimeWindow ? 1 : 2) {\n subscriber.next(copy[i] as T);\n }\n\n this._checkFinalizedStatuses(subscriber);\n\n return subscription;\n }\n\n private _trimBuffer() {\n const { _bufferSize, _timestampProvider, _buffer, _infiniteTimeWindow } = this;\n // If we don't have an infinite buffer size, and we're over the length,\n // use splice to truncate the old buffer values off. Note that we have to\n // double the size for instances where we're not using an infinite time window\n // because we're storing the values and the timestamps in the same array.\n const adjustedBufferSize = (_infiniteTimeWindow ? 1 : 2) * _bufferSize;\n _bufferSize < Infinity && adjustedBufferSize < _buffer.length && _buffer.splice(0, _buffer.length - adjustedBufferSize);\n\n // Now, if we're not in an infinite time window, remove all values where the time is\n // older than what is allowed.\n if (!_infiniteTimeWindow) {\n const now = _timestampProvider.now();\n let last = 0;\n // Search the array for the first timestamp that isn't expired and\n // truncate the buffer up to that point.\n for (let i = 1; i < _buffer.length && (_buffer[i] as number) <= now; i += 2) {\n last = i;\n }\n last && _buffer.splice(0, last + 1);\n }\n }\n}\n", "import { Scheduler } from '../Scheduler';\nimport { Subscription } from '../Subscription';\nimport { SchedulerAction } from '../types';\n\n/**\n * A unit of work to be executed in a `scheduler`. An action is typically\n * created from within a {@link SchedulerLike} and an RxJS user does not need to concern\n * themselves about creating and manipulating an Action.\n *\n * ```ts\n * class Action extends Subscription {\n * new (scheduler: Scheduler, work: (state?: T) => void);\n * schedule(state?: T, delay: number = 0): Subscription;\n * }\n * ```\n *\n * @class Action\n */\nexport class Action extends Subscription {\n constructor(scheduler: Scheduler, work: (this: SchedulerAction, state?: T) => void) {\n super();\n }\n /**\n * Schedules this action on its parent {@link SchedulerLike} for execution. May be passed\n * some context object, `state`. May happen at some point in the future,\n * according to the `delay` parameter, if specified.\n * @param {T} [state] Some contextual data that the `work` function uses when\n * called by the Scheduler.\n * @param {number} [delay] Time to wait before executing the work, where the\n * time unit is implicit and defined by the Scheduler.\n * @return {void}\n */\n public schedule(state?: T, delay: number = 0): Subscription {\n return this;\n }\n}\n", "import type { TimerHandle } from './timerHandle';\ntype SetIntervalFunction = (handler: () => void, timeout?: number, ...args: any[]) => TimerHandle;\ntype ClearIntervalFunction = (handle: TimerHandle) => void;\n\ninterface IntervalProvider {\n setInterval: SetIntervalFunction;\n clearInterval: ClearIntervalFunction;\n delegate:\n | {\n setInterval: SetIntervalFunction;\n clearInterval: ClearIntervalFunction;\n }\n | undefined;\n}\n\nexport const intervalProvider: IntervalProvider = {\n // When accessing the delegate, use the variable rather than `this` so that\n // the functions can be called without being bound to the provider.\n setInterval(handler: () => void, timeout?: number, ...args) {\n const { delegate } = intervalProvider;\n if (delegate?.setInterval) {\n return delegate.setInterval(handler, timeout, ...args);\n }\n return setInterval(handler, timeout, ...args);\n },\n clearInterval(handle) {\n const { delegate } = intervalProvider;\n return (delegate?.clearInterval || clearInterval)(handle as any);\n },\n delegate: undefined,\n};\n", "import { Action } from './Action';\nimport { SchedulerAction } from '../types';\nimport { Subscription } from '../Subscription';\nimport { AsyncScheduler } from './AsyncScheduler';\nimport { intervalProvider } from './intervalProvider';\nimport { arrRemove } from '../util/arrRemove';\nimport { TimerHandle } from './timerHandle';\n\nexport class AsyncAction extends Action {\n public id: TimerHandle | undefined;\n public state?: T;\n // @ts-ignore: Property has no initializer and is not definitely assigned\n public delay: number;\n protected pending: boolean = false;\n\n constructor(protected scheduler: AsyncScheduler, protected work: (this: SchedulerAction, state?: T) => void) {\n super(scheduler, work);\n }\n\n public schedule(state?: T, delay: number = 0): Subscription {\n if (this.closed) {\n return this;\n }\n\n // Always replace the current state with the new state.\n this.state = state;\n\n const id = this.id;\n const scheduler = this.scheduler;\n\n //\n // Important implementation note:\n //\n // Actions only execute once by default, unless rescheduled from within the\n // scheduled callback. This allows us to implement single and repeat\n // actions via the same code path, without adding API surface area, as well\n // as mimic traditional recursion but across asynchronous boundaries.\n //\n // However, JS runtimes and timers distinguish between intervals achieved by\n // serial `setTimeout` calls vs. a single `setInterval` call. An interval of\n // serial `setTimeout` calls can be individually delayed, which delays\n // scheduling the next `setTimeout`, and so on. `setInterval` attempts to\n // guarantee the interval callback will be invoked more precisely to the\n // interval period, regardless of load.\n //\n // Therefore, we use `setInterval` to schedule single and repeat actions.\n // If the action reschedules itself with the same delay, the interval is not\n // canceled. If the action doesn't reschedule, or reschedules with a\n // different delay, the interval will be canceled after scheduled callback\n // execution.\n //\n if (id != null) {\n this.id = this.recycleAsyncId(scheduler, id, delay);\n }\n\n // Set the pending flag indicating that this action has been scheduled, or\n // has recursively rescheduled itself.\n this.pending = true;\n\n this.delay = delay;\n // If this action has already an async Id, don't request a new one.\n this.id = this.id ?? this.requestAsyncId(scheduler, this.id, delay);\n\n return this;\n }\n\n protected requestAsyncId(scheduler: AsyncScheduler, _id?: TimerHandle, delay: number = 0): TimerHandle {\n return intervalProvider.setInterval(scheduler.flush.bind(scheduler, this), delay);\n }\n\n protected recycleAsyncId(_scheduler: AsyncScheduler, id?: TimerHandle, delay: number | null = 0): TimerHandle | undefined {\n // If this action is rescheduled with the same delay time, don't clear the interval id.\n if (delay != null && this.delay === delay && this.pending === false) {\n return id;\n }\n // Otherwise, if the action's delay time is different from the current delay,\n // or the action has been rescheduled before it's executed, clear the interval id\n if (id != null) {\n intervalProvider.clearInterval(id);\n }\n\n return undefined;\n }\n\n /**\n * Immediately executes this action and the `work` it contains.\n * @return {any}\n */\n public execute(state: T, delay: number): any {\n if (this.closed) {\n return new Error('executing a cancelled action');\n }\n\n this.pending = false;\n const error = this._execute(state, delay);\n if (error) {\n return error;\n } else if (this.pending === false && this.id != null) {\n // Dequeue if the action didn't reschedule itself. Don't call\n // unsubscribe(), because the action could reschedule later.\n // For example:\n // ```\n // scheduler.schedule(function doWork(counter) {\n // /* ... I'm a busy worker bee ... */\n // var originalAction = this;\n // /* wait 100ms before rescheduling the action */\n // setTimeout(function () {\n // originalAction.schedule(counter + 1);\n // }, 100);\n // }, 1000);\n // ```\n this.id = this.recycleAsyncId(this.scheduler, this.id, null);\n }\n }\n\n protected _execute(state: T, _delay: number): any {\n let errored: boolean = false;\n let errorValue: any;\n try {\n this.work(state);\n } catch (e) {\n errored = true;\n // HACK: Since code elsewhere is relying on the \"truthiness\" of the\n // return here, we can't have it return \"\" or 0 or false.\n // TODO: Clean this up when we refactor schedulers mid-version-8 or so.\n errorValue = e ? e : new Error('Scheduled action threw falsy error');\n }\n if (errored) {\n this.unsubscribe();\n return errorValue;\n }\n }\n\n unsubscribe() {\n if (!this.closed) {\n const { id, scheduler } = this;\n const { actions } = scheduler;\n\n this.work = this.state = this.scheduler = null!;\n this.pending = false;\n\n arrRemove(actions, this);\n if (id != null) {\n this.id = this.recycleAsyncId(scheduler, id, null);\n }\n\n this.delay = null!;\n super.unsubscribe();\n }\n }\n}\n", "import { Action } from './scheduler/Action';\nimport { Subscription } from './Subscription';\nimport { SchedulerLike, SchedulerAction } from './types';\nimport { dateTimestampProvider } from './scheduler/dateTimestampProvider';\n\n/**\n * An execution context and a data structure to order tasks and schedule their\n * execution. Provides a notion of (potentially virtual) time, through the\n * `now()` getter method.\n *\n * Each unit of work in a Scheduler is called an `Action`.\n *\n * ```ts\n * class Scheduler {\n * now(): number;\n * schedule(work, delay?, state?): Subscription;\n * }\n * ```\n *\n * @class Scheduler\n * @deprecated Scheduler is an internal implementation detail of RxJS, and\n * should not be used directly. Rather, create your own class and implement\n * {@link SchedulerLike}. Will be made internal in v8.\n */\nexport class Scheduler implements SchedulerLike {\n public static now: () => number = dateTimestampProvider.now;\n\n constructor(private schedulerActionCtor: typeof Action, now: () => number = Scheduler.now) {\n this.now = now;\n }\n\n /**\n * A getter method that returns a number representing the current time\n * (at the time this function was called) according to the scheduler's own\n * internal clock.\n * @return {number} A number that represents the current time. May or may not\n * have a relation to wall-clock time. May or may not refer to a time unit\n * (e.g. milliseconds).\n */\n public now: () => number;\n\n /**\n * Schedules a function, `work`, for execution. May happen at some point in\n * the future, according to the `delay` parameter, if specified. May be passed\n * some context object, `state`, which will be passed to the `work` function.\n *\n * The given arguments will be processed an stored as an Action object in a\n * queue of actions.\n *\n * @param {function(state: ?T): ?Subscription} work A function representing a\n * task, or some unit of work to be executed by the Scheduler.\n * @param {number} [delay] Time to wait before executing the work, where the\n * time unit is implicit and defined by the Scheduler itself.\n * @param {T} [state] Some contextual data that the `work` function uses when\n * called by the Scheduler.\n * @return {Subscription} A subscription in order to be able to unsubscribe\n * the scheduled work.\n */\n public schedule(work: (this: SchedulerAction, state?: T) => void, delay: number = 0, state?: T): Subscription {\n return new this.schedulerActionCtor(this, work).schedule(state, delay);\n }\n}\n", "import { Scheduler } from '../Scheduler';\nimport { Action } from './Action';\nimport { AsyncAction } from './AsyncAction';\nimport { TimerHandle } from './timerHandle';\n\nexport class AsyncScheduler extends Scheduler {\n public actions: Array> = [];\n /**\n * A flag to indicate whether the Scheduler is currently executing a batch of\n * queued actions.\n * @type {boolean}\n * @internal\n */\n public _active: boolean = false;\n /**\n * An internal ID used to track the latest asynchronous task such as those\n * coming from `setTimeout`, `setInterval`, `requestAnimationFrame`, and\n * others.\n * @type {any}\n * @internal\n */\n public _scheduled: TimerHandle | undefined;\n\n constructor(SchedulerAction: typeof Action, now: () => number = Scheduler.now) {\n super(SchedulerAction, now);\n }\n\n public flush(action: AsyncAction): void {\n const { actions } = this;\n\n if (this._active) {\n actions.push(action);\n return;\n }\n\n let error: any;\n this._active = true;\n\n do {\n if ((error = action.execute(action.state, action.delay))) {\n break;\n }\n } while ((action = actions.shift()!)); // exhaust the scheduler queue\n\n this._active = false;\n\n if (error) {\n while ((action = actions.shift()!)) {\n action.unsubscribe();\n }\n throw error;\n }\n }\n}\n", "import { AsyncAction } from './AsyncAction';\nimport { AsyncScheduler } from './AsyncScheduler';\n\n/**\n *\n * Async Scheduler\n *\n * Schedule task as if you used setTimeout(task, duration)\n *\n * `async` scheduler schedules tasks asynchronously, by putting them on the JavaScript\n * event loop queue. It is best used to delay tasks in time or to schedule tasks repeating\n * in intervals.\n *\n * If you just want to \"defer\" task, that is to perform it right after currently\n * executing synchronous code ends (commonly achieved by `setTimeout(deferredTask, 0)`),\n * better choice will be the {@link asapScheduler} scheduler.\n *\n * ## Examples\n * Use async scheduler to delay task\n * ```ts\n * import { asyncScheduler } from 'rxjs';\n *\n * const task = () => console.log('it works!');\n *\n * asyncScheduler.schedule(task, 2000);\n *\n * // After 2 seconds logs:\n * // \"it works!\"\n * ```\n *\n * Use async scheduler to repeat task in intervals\n * ```ts\n * import { asyncScheduler } from 'rxjs';\n *\n * function task(state) {\n * console.log(state);\n * this.schedule(state + 1, 1000); // `this` references currently executing Action,\n * // which we reschedule with new state and delay\n * }\n *\n * asyncScheduler.schedule(task, 3000, 0);\n *\n * // Logs:\n * // 0 after 3s\n * // 1 after 4s\n * // 2 after 5s\n * // 3 after 6s\n * ```\n */\n\nexport const asyncScheduler = new AsyncScheduler(AsyncAction);\n\n/**\n * @deprecated Renamed to {@link asyncScheduler}. Will be removed in v8.\n */\nexport const async = asyncScheduler;\n", "import { AsyncAction } from './AsyncAction';\nimport { Subscription } from '../Subscription';\nimport { QueueScheduler } from './QueueScheduler';\nimport { SchedulerAction } from '../types';\nimport { TimerHandle } from './timerHandle';\n\nexport class QueueAction extends AsyncAction {\n constructor(protected scheduler: QueueScheduler, protected work: (this: SchedulerAction, state?: T) => void) {\n super(scheduler, work);\n }\n\n public schedule(state?: T, delay: number = 0): Subscription {\n if (delay > 0) {\n return super.schedule(state, delay);\n }\n this.delay = delay;\n this.state = state;\n this.scheduler.flush(this);\n return this;\n }\n\n public execute(state: T, delay: number): any {\n return delay > 0 || this.closed ? super.execute(state, delay) : this._execute(state, delay);\n }\n\n protected requestAsyncId(scheduler: QueueScheduler, id?: TimerHandle, delay: number = 0): TimerHandle {\n // If delay exists and is greater than 0, or if the delay is null (the\n // action wasn't rescheduled) but was originally scheduled as an async\n // action, then recycle as an async action.\n\n if ((delay != null && delay > 0) || (delay == null && this.delay > 0)) {\n return super.requestAsyncId(scheduler, id, delay);\n }\n\n // Otherwise flush the scheduler starting with this action.\n scheduler.flush(this);\n\n // HACK: In the past, this was returning `void`. However, `void` isn't a valid\n // `TimerHandle`, and generally the return value here isn't really used. So the\n // compromise is to return `0` which is both \"falsy\" and a valid `TimerHandle`,\n // as opposed to refactoring every other instanceo of `requestAsyncId`.\n return 0;\n }\n}\n", "import { AsyncScheduler } from './AsyncScheduler';\n\nexport class QueueScheduler extends AsyncScheduler {\n}\n", "import { QueueAction } from './QueueAction';\nimport { QueueScheduler } from './QueueScheduler';\n\n/**\n *\n * Queue Scheduler\n *\n * Put every next task on a queue, instead of executing it immediately\n *\n * `queue` scheduler, when used with delay, behaves the same as {@link asyncScheduler} scheduler.\n *\n * When used without delay, it schedules given task synchronously - executes it right when\n * it is scheduled. However when called recursively, that is when inside the scheduled task,\n * another task is scheduled with queue scheduler, instead of executing immediately as well,\n * that task will be put on a queue and wait for current one to finish.\n *\n * This means that when you execute task with `queue` scheduler, you are sure it will end\n * before any other task scheduled with that scheduler will start.\n *\n * ## Examples\n * Schedule recursively first, then do something\n * ```ts\n * import { queueScheduler } from 'rxjs';\n *\n * queueScheduler.schedule(() => {\n * queueScheduler.schedule(() => console.log('second')); // will not happen now, but will be put on a queue\n *\n * console.log('first');\n * });\n *\n * // Logs:\n * // \"first\"\n * // \"second\"\n * ```\n *\n * Reschedule itself recursively\n * ```ts\n * import { queueScheduler } from 'rxjs';\n *\n * queueScheduler.schedule(function(state) {\n * if (state !== 0) {\n * console.log('before', state);\n * this.schedule(state - 1); // `this` references currently executing Action,\n * // which we reschedule with new state\n * console.log('after', state);\n * }\n * }, 0, 3);\n *\n * // In scheduler that runs recursively, you would expect:\n * // \"before\", 3\n * // \"before\", 2\n * // \"before\", 1\n * // \"after\", 1\n * // \"after\", 2\n * // \"after\", 3\n *\n * // But with queue it logs:\n * // \"before\", 3\n * // \"after\", 3\n * // \"before\", 2\n * // \"after\", 2\n * // \"before\", 1\n * // \"after\", 1\n * ```\n */\n\nexport const queueScheduler = new QueueScheduler(QueueAction);\n\n/**\n * @deprecated Renamed to {@link queueScheduler}. Will be removed in v8.\n */\nexport const queue = queueScheduler;\n", "import { AsyncAction } from './AsyncAction';\nimport { AnimationFrameScheduler } from './AnimationFrameScheduler';\nimport { SchedulerAction } from '../types';\nimport { animationFrameProvider } from './animationFrameProvider';\nimport { TimerHandle } from './timerHandle';\n\nexport class AnimationFrameAction extends AsyncAction {\n constructor(protected scheduler: AnimationFrameScheduler, protected work: (this: SchedulerAction, state?: T) => void) {\n super(scheduler, work);\n }\n\n protected requestAsyncId(scheduler: AnimationFrameScheduler, id?: TimerHandle, delay: number = 0): TimerHandle {\n // If delay is greater than 0, request as an async action.\n if (delay !== null && delay > 0) {\n return super.requestAsyncId(scheduler, id, delay);\n }\n // Push the action to the end of the scheduler queue.\n scheduler.actions.push(this);\n // If an animation frame has already been requested, don't request another\n // one. If an animation frame hasn't been requested yet, request one. Return\n // the current animation frame request id.\n return scheduler._scheduled || (scheduler._scheduled = animationFrameProvider.requestAnimationFrame(() => scheduler.flush(undefined)));\n }\n\n protected recycleAsyncId(scheduler: AnimationFrameScheduler, id?: TimerHandle, delay: number = 0): TimerHandle | undefined {\n // If delay exists and is greater than 0, or if the delay is null (the\n // action wasn't rescheduled) but was originally scheduled as an async\n // action, then recycle as an async action.\n if (delay != null ? delay > 0 : this.delay > 0) {\n return super.recycleAsyncId(scheduler, id, delay);\n }\n // If the scheduler queue has no remaining actions with the same async id,\n // cancel the requested animation frame and set the scheduled flag to\n // undefined so the next AnimationFrameAction will request its own.\n const { actions } = scheduler;\n if (id != null && actions[actions.length - 1]?.id !== id) {\n animationFrameProvider.cancelAnimationFrame(id as number);\n scheduler._scheduled = undefined;\n }\n // Return undefined so the action knows to request a new async id if it's rescheduled.\n return undefined;\n }\n}\n", "import { AsyncAction } from './AsyncAction';\nimport { AsyncScheduler } from './AsyncScheduler';\n\nexport class AnimationFrameScheduler extends AsyncScheduler {\n public flush(action?: AsyncAction): void {\n this._active = true;\n // The async id that effects a call to flush is stored in _scheduled.\n // Before executing an action, it's necessary to check the action's async\n // id to determine whether it's supposed to be executed in the current\n // flush.\n // Previous implementations of this method used a count to determine this,\n // but that was unsound, as actions that are unsubscribed - i.e. cancelled -\n // are removed from the actions array and that can shift actions that are\n // scheduled to be executed in a subsequent flush into positions at which\n // they are executed within the current flush.\n const flushId = this._scheduled;\n this._scheduled = undefined;\n\n const { actions } = this;\n let error: any;\n action = action || actions.shift()!;\n\n do {\n if ((error = action.execute(action.state, action.delay))) {\n break;\n }\n } while ((action = actions[0]) && action.id === flushId && actions.shift());\n\n this._active = false;\n\n if (error) {\n while ((action = actions[0]) && action.id === flushId && actions.shift()) {\n action.unsubscribe();\n }\n throw error;\n }\n }\n}\n", "import { AnimationFrameAction } from './AnimationFrameAction';\nimport { AnimationFrameScheduler } from './AnimationFrameScheduler';\n\n/**\n *\n * Animation Frame Scheduler\n *\n * Perform task when `window.requestAnimationFrame` would fire\n *\n * When `animationFrame` scheduler is used with delay, it will fall back to {@link asyncScheduler} scheduler\n * behaviour.\n *\n * Without delay, `animationFrame` scheduler can be used to create smooth browser animations.\n * It makes sure scheduled task will happen just before next browser content repaint,\n * thus performing animations as efficiently as possible.\n *\n * ## Example\n * Schedule div height animation\n * ```ts\n * // html:
\n * import { animationFrameScheduler } from 'rxjs';\n *\n * const div = document.querySelector('div');\n *\n * animationFrameScheduler.schedule(function(height) {\n * div.style.height = height + \"px\";\n *\n * this.schedule(height + 1); // `this` references currently executing Action,\n * // which we reschedule with new state\n * }, 0, 0);\n *\n * // You will see a div element growing in height\n * ```\n */\n\nexport const animationFrameScheduler = new AnimationFrameScheduler(AnimationFrameAction);\n\n/**\n * @deprecated Renamed to {@link animationFrameScheduler}. Will be removed in v8.\n */\nexport const animationFrame = animationFrameScheduler;\n", "import { Observable } from '../Observable';\nimport { SchedulerLike } from '../types';\n\n/**\n * A simple Observable that emits no items to the Observer and immediately\n * emits a complete notification.\n *\n * Just emits 'complete', and nothing else.\n *\n * ![](empty.png)\n *\n * A simple Observable that only emits the complete notification. It can be used\n * for composing with other Observables, such as in a {@link mergeMap}.\n *\n * ## Examples\n *\n * Log complete notification\n *\n * ```ts\n * import { EMPTY } from 'rxjs';\n *\n * EMPTY.subscribe({\n * next: () => console.log('Next'),\n * complete: () => console.log('Complete!')\n * });\n *\n * // Outputs\n * // Complete!\n * ```\n *\n * Emit the number 7, then complete\n *\n * ```ts\n * import { EMPTY, startWith } from 'rxjs';\n *\n * const result = EMPTY.pipe(startWith(7));\n * result.subscribe(x => console.log(x));\n *\n * // Outputs\n * // 7\n * ```\n *\n * Map and flatten only odd numbers to the sequence `'a'`, `'b'`, `'c'`\n *\n * ```ts\n * import { interval, mergeMap, of, EMPTY } from 'rxjs';\n *\n * const interval$ = interval(1000);\n * const result = interval$.pipe(\n * mergeMap(x => x % 2 === 1 ? of('a', 'b', 'c') : EMPTY),\n * );\n * result.subscribe(x => console.log(x));\n *\n * // Results in the following to the console:\n * // x is equal to the count on the interval, e.g. (0, 1, 2, 3, ...)\n * // x will occur every 1000ms\n * // if x % 2 is equal to 1, print a, b, c (each on its own)\n * // if x % 2 is not equal to 1, nothing will be output\n * ```\n *\n * @see {@link Observable}\n * @see {@link NEVER}\n * @see {@link of}\n * @see {@link throwError}\n */\nexport const EMPTY = new Observable((subscriber) => subscriber.complete());\n\n/**\n * @param scheduler A {@link SchedulerLike} to use for scheduling\n * the emission of the complete notification.\n * @deprecated Replaced with the {@link EMPTY} constant or {@link scheduled} (e.g. `scheduled([], scheduler)`). Will be removed in v8.\n */\nexport function empty(scheduler?: SchedulerLike) {\n return scheduler ? emptyScheduled(scheduler) : EMPTY;\n}\n\nfunction emptyScheduled(scheduler: SchedulerLike) {\n return new Observable((subscriber) => scheduler.schedule(() => subscriber.complete()));\n}\n", "import { SchedulerLike } from '../types';\nimport { isFunction } from './isFunction';\n\nexport function isScheduler(value: any): value is SchedulerLike {\n return value && isFunction(value.schedule);\n}\n", "import { SchedulerLike } from '../types';\nimport { isFunction } from './isFunction';\nimport { isScheduler } from './isScheduler';\n\nfunction last(arr: T[]): T | undefined {\n return arr[arr.length - 1];\n}\n\nexport function popResultSelector(args: any[]): ((...args: unknown[]) => unknown) | undefined {\n return isFunction(last(args)) ? args.pop() : undefined;\n}\n\nexport function popScheduler(args: any[]): SchedulerLike | undefined {\n return isScheduler(last(args)) ? args.pop() : undefined;\n}\n\nexport function popNumber(args: any[], defaultValue: number): number {\n return typeof last(args) === 'number' ? args.pop()! : defaultValue;\n}\n", "export const isArrayLike = ((x: any): x is ArrayLike => x && typeof x.length === 'number' && typeof x !== 'function');", "import { isFunction } from \"./isFunction\";\n\n/**\n * Tests to see if the object is \"thennable\".\n * @param value the object to test\n */\nexport function isPromise(value: any): value is PromiseLike {\n return isFunction(value?.then);\n}\n", "import { InteropObservable } from '../types';\nimport { observable as Symbol_observable } from '../symbol/observable';\nimport { isFunction } from './isFunction';\n\n/** Identifies an input as being Observable (but not necessary an Rx Observable) */\nexport function isInteropObservable(input: any): input is InteropObservable {\n return isFunction(input[Symbol_observable]);\n}\n", "import { isFunction } from './isFunction';\n\nexport function isAsyncIterable(obj: any): obj is AsyncIterable {\n return Symbol.asyncIterator && isFunction(obj?.[Symbol.asyncIterator]);\n}\n", "/**\n * Creates the TypeError to throw if an invalid object is passed to `from` or `scheduled`.\n * @param input The object that was passed.\n */\nexport function createInvalidObservableTypeError(input: any) {\n // TODO: We should create error codes that can be looked up, so this can be less verbose.\n return new TypeError(\n `You provided ${\n input !== null && typeof input === 'object' ? 'an invalid object' : `'${input}'`\n } where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.`\n );\n}\n", "export function getSymbolIterator(): symbol {\n if (typeof Symbol !== 'function' || !Symbol.iterator) {\n return '@@iterator' as any;\n }\n\n return Symbol.iterator;\n}\n\nexport const iterator = getSymbolIterator();\n", "import { iterator as Symbol_iterator } from '../symbol/iterator';\nimport { isFunction } from './isFunction';\n\n/** Identifies an input as being an Iterable */\nexport function isIterable(input: any): input is Iterable {\n return isFunction(input?.[Symbol_iterator]);\n}\n", "import { ReadableStreamLike } from '../types';\nimport { isFunction } from './isFunction';\n\nexport async function* readableStreamLikeToAsyncGenerator(readableStream: ReadableStreamLike): AsyncGenerator {\n const reader = readableStream.getReader();\n try {\n while (true) {\n const { value, done } = await reader.read();\n if (done) {\n return;\n }\n yield value!;\n }\n } finally {\n reader.releaseLock();\n }\n}\n\nexport function isReadableStreamLike(obj: any): obj is ReadableStreamLike {\n // We don't want to use instanceof checks because they would return\n // false for instances from another Realm, like an - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/current/sailbot_workspace/overview/index.html b/pr-450/current/sailbot_workspace/overview/index.html deleted file mode 100644 index c668c1a65..000000000 --- a/pr-450/current/sailbot_workspace/overview/index.html +++ /dev/null @@ -1,2623 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Overview - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -
-

Source code

-

The Sailbot Workspace README has been copied below.

-
-

Sailbot Workspace

-

Tests -Docs Site -Build Images

-

This repository will get you set up to develop UBCSailbot's software on VS Code. It is based on athackst's -vscode_ros2_workspace.

-

Features

-

An overview of Sailbot Workspace's features can be found below. -See our docs site -for how to use these features.

-

Style

-

C++ and Python linters and formatters are integrated into Sailbot Workspace:

-
    -
  • ament_flake8
    • -
  • ament_lint_cmake
    • -
  • ament_xmllint
    • -
  • black
    • -
  • clang-tidy
    • -
  • isort
    • -
-

The ament linters are configured to be consistent with the -ROS style guide.

-

Dev Container

-

Dev Containers enable us to use a -Docker container as a fully-featured development environment -containing all our configuration and dependencies. -Our Dev Container configuration can be found in .devcontainer/.

-

Multi-Root Workspace

-

Workspaces are VS Code instances that contain one or more folders. -Our workspace configuration file can be found at -sailbot.code-workspace.

-

Our software spans many repositories: software team repositories. -Multi-root workspaces -make it easy to work with multiple repositories at the same time. -Our roots are defined in the folders section of our workspace file.

-

Debugging

-

Launch configurations -have been created to debug our software. They are defined in the launch section of -our workspace file.

-

Tasks

-

Tasks provide an alternative to memorizing the multitude of -CLI commands we use to setup, build, lint, test, and run our software. They are defined in tasks section of -our workspace file.

-

Continuous Integration

-

Actions -were used to build our Docker containers -and lint and test our code the same way it is done locally in Sailbot Workspace on GitHub. -We use a reusable workflow -to create a single source of truth for our tests across all our repositories. -Our CI can be found in .github/workflows/.

-

Customization

-

This repository supports user-specific configuration files. To set this up, see -How to use your dotfiles.

-

Run Raye's Software

-

Raye was our previous project. -Her software can be run in the raye branch -following the instructions in How to run Raye's software. -The initial differences between the main and raye branches are summarized in -this PR.

-

Documentation

-

Further documentation, including setup and run instructions, can be found on our Docs website.

-

Tutorial

-
-

Disclaimer

-

This tutorial was done a while ago, so some parts may no longer be relevant. For the most up to date information, consult the docs pages and the software leads.

-
- -
- -
- - - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/current/sailbot_workspace/reference/deployment/index.html b/pr-450/current/sailbot_workspace/reference/deployment/index.html deleted file mode 100644 index be47862db..000000000 --- a/pr-450/current/sailbot_workspace/reference/deployment/index.html +++ /dev/null @@ -1,2430 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Deployment - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -
-

Source code

-

The source code for deployment can be found in scripts/deployment. -Its README has been copied below.

-
-

Deployment

-

Deploying our software to our autonomous sailboat's main computer.

-

Scripts

-

setup_boot.sh

-

Configures programs and scripts that need to run when the main computer boots. Only needs to be run once unless the -script is updated. Does not need to be rerun if any scripts or programs it targets are updated, with the exception of -renaming or moving the file.

-

Usage:

-
    -
  • Must be run as root: sudo ./setup_boot.sh
    • -
-

start_containers.sh

-

Runs our Docker Compose files. You may have to install commands like wget. -Would recommend running this script in its own clone of sailbot_workspace (not the one you open in VS Code).

-

Usage:

-
    -
  • Runs the global launch file by default: ./start_containers.sh
    • -
  • Add the --website argument to additionally run the website container
    • -
  • Add the --interactive argument to manually run commands in the sailbot workspace container
    • -
  • Add the --help argument to see all available arguments
    • -
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/current/sailbot_workspace/reference/docker_images/index.html b/pr-450/current/sailbot_workspace/reference/docker_images/index.html deleted file mode 100644 index 94c1f6740..000000000 --- a/pr-450/current/sailbot_workspace/reference/docker_images/index.html +++ /dev/null @@ -1,2368 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Images - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Docker Images

-

A table detailing the Docker images used to create the Dev Container can be found below. -Click on an image to learn more about its features and how to update it.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ImageParent ImageSource CodeWhy it is RebuiltWhere it is Built
pre-baseUbuntu 22.04base-dev.DockerfileTo install ROS or OMPLPersonal computer
basepre-basebase-dev.DockerfileTo install core dependenciesWorkflow dispatch
local-basebasebase-dev.DockerfileTo install core dev dependenciesWorkflow dispatch
devlocal-basebase-dev.DockerfileTo install dev dependenciesWorkflow dispatch
Dev ContainerdevDockerfileTo configure the Dev ContainerVS Code
docsmkdocs-materialdocs.DockerfileTo install and run docs siteVS Code (optional)
websitejavascript-nodewebsite.DockerfileTo install and run websiteVS Code (optional)
- - - - - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/current/sailbot_workspace/reference/docs_site/index.html b/pr-450/current/sailbot_workspace/reference/docs_site/index.html deleted file mode 100644 index 41ceac767..000000000 --- a/pr-450/current/sailbot_workspace/reference/docs_site/index.html +++ /dev/null @@ -1,2663 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Docs Site - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Docs Site

-

UBCSailbot software team's documentation site. It is meant to be developed in Sailbot Workspace -in conjunction with our other software, but doesn't have to be. There are instructions for both cases below.

-

Setup

-

Setup in Sailbot Workspace

-
    -
  1. Uncomment docs/docker-compose.docs.yml in .devcontainer/devcontainer.json
    2. -
  2. Uncomment 8000:8000 in .devcontainer/docker-compose.yml
    3. -
  3. Rebuild the Dev Container
    4. -
-

Refer to How to work with containerized applications -for more details.

-

Setup Standalone

-
    -
  1. -

    Manually install social plugin OS dependencies

    -
    2. -
  2. -

    Install Python dependencies

    -

    pip install --upgrade pip - pip install -Ur docs/requirements.txt

    - -
    3. -
-

Run

-

Run in Sailbot Workspace

-

After setup, the Docs site should be running on port 8000.

-

Refer to How to work with containerized applications -for more details.

-

Run Standalone

-
mkdocs serve
-
-

Update Dependencies

-

This site is built using the latest versions of dependencies in docs/requirements.txt -at the time of the most recent commit to the main branch. -To see exactly how the site will look when deployed, ensure your local dependencies are up to date.

-

Update Dependencies in Sailbot Workspace

-

Rebuild the Dev Container.

-

Update Dependencies By Itself

-
pip install -Ur docs/requirements.txt
-
-

Maintain

-

Contribute to This Site

-

Read our Markdown Reference Page for the syntax supported by this site.

-

Delete Docs Versions

-

A version of the docs site is created when a PR is open, and is deleted when it is merged or closed. -However, the CI that does this is very finicky, so if 2 PR's are trying to update the site at the exact same time -one might fail.

-

This is especially annoying if this happens to be one that deletes a version, because this means that -there is a version still open for a merged/closed PR. To manually clean up these PR's, run the following commands in -the docs container (in Docker Desktop, the exec tab):

-
git config user.name <your github username>
-git config user.email <your github email>
-mike delete --push pr-<number>
-
-

If you get an error that your local copy of the gh-pages branch has diverged from the remote, you can delete it -with git branch -D gh-pages and rerun the mike delete command above.

-

It will probably ask you to login to GitHub: enter your username then a GitHub access token -with write permission.

- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/current/sailbot_workspace/reference/launch_files/index.html b/pr-450/current/sailbot_workspace/reference/launch_files/index.html deleted file mode 100644 index 0c9e4d6d2..000000000 --- a/pr-450/current/sailbot_workspace/reference/launch_files/index.html +++ /dev/null @@ -1,2703 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Launch Files - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

ROS Launch Files in Sailbot Workspace

-

ROS 2 Launch files allow us to programatically start up and configure multiple ROS nodes.1 -Within Sailbot Workspace, ROS launch files are used to start up our ROS packages with ease. -Additionally, we take advantage of the hierarchical properties of launch files by defining a global -entry point that invokes the launch files of all ROS packages in the system.

-

Tutorial

- -
- -
- - -

Launch File Architecture

-

There are two launch processes that we utilize: namely the Package Launch Process and the Global launch process.

-

The Package Launch Process

- - - - -

The package launch process is intended to start up a specific ROS package by directly using the package launch file. -The process is as follows:

-
    -
  1. The package launch file is invoked with the user passing arguments via the CLI and specifying a configuration file.
    2. -
  2. Global argument declarations and environment variables are loaded into the launch process.
    3. -
  3. Local arguments, specific to the package, are declared.
    4. -
  4. Both global and local arguments are parsed based on the argument declarations and are set for use upon start up.
    5. -
  5. The ROS nodes belonging to the package begin execution, utilizing the ROS parameters from the configuration file.
    6. -
-
-When launching individual packages, be aware of dependencies between ROS packages -

Some packages rely on the data produced by other packages in the system. This may cause only -partial functionality of the ROS node(s) that are running inside the launched package. Therefore, -it may be necessary to launch multiple packages manually to get the desired functionality.

-
-

The Global Launch Process

- - - - -

The global launch process is intended to start up the entire system (both the development and production environments). -This process invokes the package launch files for each ROS package used in the system through a global launch file. -The process is as follows:

-
    -
  1. The global launch file is invoked with the user passing arguments via the CLI and specifying a configuration file.
    2. -
  2. Environment variables common to all ROS packages are declared. In addition, the global arguments common across -all ROS packages are declared.
    3. -
  3. For each package launch file:
      -
    • The CLI arguments, global argument declarations, and environment variables are passed into the package launch - file.
      • -
    • Local arguments, specific to the package, are declared. Both the global and local arguments are parsed based on the - argument declarations and are set for use upon start up.
      • -
    • The ROS nodes belonging to the package begin execution, utilizing the ROS parameters from the configuration file.
      • -
    -
    4. -
-

Invoking Launch Files

-
-Stopping the execution of a launch file -

Entering Ctrl+C in the terminal where the launch file was invoked will stop all associated -ROS packages from running.

-
-

Use Cmd+C for Mac OS

-
-
-

Package Launch

-

At the bare minimum, the following packages need to be built with the Build or Build All VS Code task before launching:

-
    -
  • custom_interfaces
    • -
  • The package you want to launch
    • -
-

Packages only need to be rebuilt either when the workspace is first set up, or if any changes are made to the ROS -package. Once built, the package launch file can be invoked either in the CLI or using a VS Code command:

-
-
-
-

Either the package and launch file name, or the path to the launch file can be used:

-
    -
  • Method 1: ros2 launch <package> <launch file>. This method can only be used when a launch file - is part of a built ROS package.
    • -
  • Method 2: ros2 launch <path to launch file>. This method can be used regardless if a launch file - is in a ROS package or not.
    • -
-
-

Launch via CLI Examples

-

Let's launch local pathfinding using both CLI methods:

-

Method 1 -

ros2 launch local_pathfinding main_launch.py
-

-

Method 2 -

ros2 launch $ROS_WORKSPACE/src/local_pathfinding/launch/main_launch.py
-

-
-
-
-

Run the following VS Code command from the Run and Debug tab: ROS: Launch (workspace)

-

There will be a prompt to select which launch file to run. Select the desired launch file.

-
-
-
-

Global Launch

-

Before running the system, be sure to run the Build All VS Code task to build all ROS packages. If the ROS launch -debug configuration is being used, then this step is not necessary as the Build All task is ran automatically before -launch.

-
-
-
-

Run the entire system with the following CLI command:

-
ros2 launch $ROS_WORKSPACE/src/global_launch/main_launch.py
-
-
-
-

Run the following VS Code command from the Run and Debug tab: ROS: Launch (workspace)

-

There will be a prompt to select which launch file to run. Select the desired launch file.

-
-
-
-

Remember to that you need to potentially reload the window if the nodes are not being detected -by VS Code. This usually happens when somebody build for the first time. Also, note that the global -launch file is not part of a ROS package, so the path to the global launch file always -must be provided. This is not always the case when a launch file is contained within a ROS package.

-

Using CLI Arguments

-

Invoking the launch files as is will provide the system with the default CLI arguments. As an example, -the following command will launch local pathfinding while setting the log level to "debug":

-
ros2 launch local_pathfinding main_launch.py log_level:=debug
-
-

It can also be ran with the VS Code command named ROS: Launch.

-

Passing arguments takes the form of <arg name>:=<arg value>. To list the arguments that a launch file takes, -simply add the -s flag at the end of the launch command.

-
-Example using the -s flag in a launch command -

Let's add the -s flag after the global launch command to see the list of arguments:

-
ros2 launch $ROS_WORKSPACE/src/global_launch/main_launch.py -s
-
-

The following output is observed in the terminal (as of September 2023):

-
Arguments (pass arguments as '<name>:=<value>'):
-
-'config':
-    Path to ROS parameter config file. Controls ROS parameters passed into ROS nodes
-    (default: '/workspaces/sailbot_workspace/src/global_launch/config/globals.yaml')
-
-'log_level':
-    Logging severity level. A logger will only process log messages with severity levels at or higher than the
-    specified severity. Valid choices are: ['debug', 'info', 'warn', 'error', 'fatal']
-    (default: 'info')
-
-'mode':
-    System mode. Decides whether the system is ran with development or production interfaces. Valid choices are:
-    ['production', 'development']
-    (default: 'development')
-
-
-
-Example using multiple CLI arguments -
ros2 launch local_pathfinding main_launch.py log_level:=debug mode:=production
-
-
-
-Example passing local launch arguments to the global launch file -

As long as an argument is valid inside one of the package launch files, it may be passed to the global launch -file without generating any errors. This is valid even though the argument doesn't show up in the argument list for -the global launch file. For example, the following will run:

-
ros2 launch $ROS_WORKSPACE/src/global_launch/main_launch.py enable_sim_multithreading:=true
-
-

Compare the argument list between the global launch file and the package launch file for the boat_simulator -package. It will be observed that the argument enable_sim_multithreading shows up in the boat_simulator -package argument list, but not for the global launch file.

-
-

ROS Parameter Config File

-

All launch files in Sailbot Workspace accept a configuration file, which controls the ROS parameters that the ROS nodes -in the system have access to. This makes our system highly configurable and customizable during development and testing. -See more about ROS parameters.

-
-
-
    -
  1. -

    ROS Launch File Documentation ↩

    -
    2. -
-
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/current/sailbot_workspace/reference/notebooks/index.html b/pr-450/current/sailbot_workspace/reference/notebooks/index.html deleted file mode 100644 index 10739e062..000000000 --- a/pr-450/current/sailbot_workspace/reference/notebooks/index.html +++ /dev/null @@ -1,2370 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Notebooks - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -
-

Source code

-

The source code for Notebooks can be found in notebooks. -Its README has been copied below.

-
-

Notebooks

-

UBC Sailbot's Jupyter notebooks for researching and exporing implementations.

-

Standards

-
    -
  1. In addition to the dependencies installed in Sailbot Workspace, -notebooks may have additional dependencies that are installed in the first code block
    2. -
  2. Implementations in notebooks should be complete: do not import functions from other UBC Sailbot repositories
    3. -
  3. Notebooks should be organized into directories named like the UBC Sailbot repositories they correspond to
    4. -
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/current/sailbot_workspace/reference/parameters/index.html b/pr-450/current/sailbot_workspace/reference/parameters/index.html deleted file mode 100644 index 76be8ba67..000000000 --- a/pr-450/current/sailbot_workspace/reference/parameters/index.html +++ /dev/null @@ -1,2872 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Parameters - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -
-

Source code

-

Our ROS parameters can be found in src/global_launch/config. -Its README has been copied below.

-
-

Sailbot ROS Parameter Configuration

-

The description of each parameter contained in globals.yaml are described in this README. Descriptions of parameters -for each node are included. These parameters can be changed dynamically as well via the command line interface. To -learn more, see the ROS 2 documentation on ROS 2 Parameters.

-

Each parameter is specified in the following format:

-
    -
  • Description: The description of the parameter.
    • -
  • Datatype: The datatype. If it happens to be an array, the datatype of the elements should be specified and the length -of the array.
    • -
  • Range/Acceptable Values: Ranges of integers and floating point values are specified with interval notation. -Namely, [] denotes inclusive boundaries, while () denotes non-inclusive boundaries. For strings, the acceptable -values are listed.
    • -
-

Additional information may be included when necessary.

-
-

[!IMPORTANT] -This document should be updated when any changes occur to the ROS parameters specified in globals.yaml.

-
-

Global Parameters

-

ROS parameters common across all ROS nodes in the network.

-

pub_period_sec

-
    -
  • Description: The period at which the publishers publish.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

Local Pathfinding Parameters

-

ROS parameters specific to the nodes in the local_pathfinding package.

-

mgp_main

-

global_path_filepath

-
    -
  • Description: The absolute filepath to a global path csv file.
    • -
  • Datatype: string
    • -
  • Acceptable Values: Any valid filepath to a properly formatted csv file.
    • -
-

interval_spacing

-
    -
  • Description: The upper bound on spacing between each point in the global path in km.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

write

-
    -
  • Description: Whether or not to write a generated global path to a new csv file.
    • -
  • Datatype: boolean
    • -
  • Acceptable Values: true, false
    • -
-

gps_threshold

-
    -
  • Description: A new path will be generated if the GPS position changed by more thangps_threshold*interval_spacing.
    • -
  • Datatype: double
    • -
  • Acceptable Values: (1.0, MAX_DOUBLE)
    • -
-

force

-
    -
  • Description: Force the mock global path callback to update the global path when set to true.
    • -
  • Datatype: boolean
    • -
  • Acceptable Values: true, false
    • -
- -

path_planner

-
    -
  • Description: The path planner to use. Planners are from OMPL Library.
    • -
  • Datatype: string
    • -
  • Acceptable Values: "bitstar", "bfmtstar", "fmtstar", "informedrrtstar", "lazylbtrrt", "lazyprmstar", - "lbtrrt", "prmstar", "rrtconnect", "rrtsharp", "rrtstar", "rrtxstatic", "sorrtstar"
    • -
-

Controller Parameters

-

ROS parameters specific to the nodes in the Controller.

-

wingsail_ctrl_node

-

reynolds_number

-
    -
  • Description: The Reynolds number of the wind.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

angle_of_attack

-
    -
  • Description: The angle of attack of the sail.
    • -
  • Datatype: double
    • -
  • Range: (-180.0, 180.0]
    • -
-

Boat Simulator Parameters

-

ROS parameters specific to the nodes in the boat simulator.

-

low_level_control_node

-

info_log_throttle_period_sec

-
    -
  • Description: Limits the info logs to avoid overwhelming the terminal.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

logging_throttle_period_sec

-
    -
  • Description: Controls the message logging throttle period.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

qos_depth

-
    -
  • Description: The maximum number of subscription messages to queue for further processing.
    • -
  • Datatype: int
    • -
  • Range: [1, MAX_INT)
    • -
-

rudder.actuation_execution_period_sec

-
    -
  • Description: The period at which the main loop in the rudder action server executes in seconds.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

rudder.disable_actuation

-
    -
  • Description: Controls whether or not rudder actuation is disabled. If true, the rudder angle is fixed to some value. -Otherwise, the PID mechanism is used to control the rudder angle.
    • -
  • Datatype: boolean
    • -
  • Acceptable Values: true, false
    • -
-

rudder.fixed_angle_deg

-
    -
  • Description: The angle to fix the rudder in degrees. Only used if rudder.disable_actuation is true.
    • -
  • Datatype: double
    • -
  • Range: [-45.0, 45.0]
    • -
-

rudder.pid.buffer_size

-
    -
  • Description: The buffer size of PID that stores previously computed errors over time.
    • -
  • Datatype: int
    • -
  • Range: [1, MAX_INT)
    • -
-

rudder.pid.kd

-
    -
  • Description: The PID Derivative constant for the rudder. Only used if rudder.disable_actuation is false.
    • -
  • Datatype: double
    • -
  • Range: [0.0, MAX_DOUBLE)
    • -
-

rudder.pid.ki

-
    -
  • Description: The PID Integral constant for the rudder. Only used if rudder.disable_actuation is false.
    • -
  • Datatype: double
    • -
  • Range: [0.0, MAX_DOUBLE)
    • -
-

rudder.pid.kp

-
    -
  • Description: The PID Proportionality constant for the rudder. Only used if rudder.disable_actuation is false.
    • -
  • Datatype: double
    • -
  • Range: [0.0, MAX_DOUBLE)
    • -
-

wingsail.actuation_execution_period_sec

-
    -
  • Description: The period at which the main loop in the sail action server executes in seconds.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

wingsail.actuation_speed_deg_per_sec

-
    -
  • Description: The speed at which the wingsail trim tab actuates in degrees per second.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

wingsail.disable_actuation

-
    -
  • Description: Controls whether or not wingsail trim tab actuation is disabled. If true, the trim tab is fixed to some -value. Otherwise, the trim tab angle is determined by the wingsail controller.
    • -
  • Datatype: boolean
    • -
  • Acceptable Values: true, false
    • -
-

wingsail.fixed_angle_degree

-
    -
  • Description: Fixed the wingsail trim tab to some angle in degrees. Only used if wingsail.disable_actuation is true.
    • -
  • Datatype: double
    • -
  • Range: [-180.0, 180.0)
    • -
-

physics_engine_node

-

action_send_goal_timeout_sec

-
    -
  • Description: How long the action clients wait for the action server to respond to a request before timing out in seconds.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

info_log_throttle_period_sec

-
    -
  • Description: Limits the info logs to avoid overwhelming the terminal.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

logging_throttle_period_sec

-
    -
  • Description: Controls the message logging throttle period.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

qos_depth

-
    -
  • Description: The maximum number of subscription messages to queue for further processing.
    • -
  • Datatype: int
    • -
  • Range: [1, MAX_INT)
    • -
-

rudder.actuation_request_period_sec

-
    -
  • Description: How often the rudder action client requests a rudder actuation in seconds.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

wingsail.actuation_request_period_sec

-
    -
  • Description: How often the sail action server requests a wingsail actuation.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

wind_sensor.constant_params.value

-
    -
  • Description: Specifies the constant vector returned by the constant generator that represents the wind velocity in kmph. -Namely, the same value is fixed in the wind sensors. The value is an array containing the x and y components of the -velocity. Only used if wind_sensor.generator_type is constant.
    • -
  • Datatype: double array, length 2
    • -
  • Range: (MIN_DOUBLE, MAX_DOUBLE)
    • -
-

wind_sensor.gaussian_params.corr_xy

-
    -
  • Description: The correlation coefficient between x and y components of the wind velocity. Only used if -wind_sensor.generator_type is gaussian.
    • -
  • Datatype: double
    • -
  • Range: [-1.0, 1.0]
    • -
-

wind_sensor.gaussian_params.mean

-
    -
  • Description: The mean wind velocity parameter in kmph for the gaussian generator. The mean is an array containing -the x and y components of the velocity. Only used if wind_sensor.generator_type is gaussian.
    • -
  • Datatype: double array, length 2
    • -
  • Range: (MIN_DOUBLE, MAX_DOUBLE)
    • -
-

wind_sensor.gaussian_params.std_dev

-
    -
  • Description: The standard deviation parameters in kmph for the gaussian generator. There are two standard deviations -specified within an array: one for the x component, and one for the y component. Only used if -wind_sensor.generator_type is gaussian.
    • -
  • Datatype: double array, length 2
    • -
  • Range: (0.0, MAX_DOUBLE)
      -
    • If a standard deviation of zero is desired, then consider using the constant generator instead.
      • -
    -
    • -
-

wind_sensor.generator_type

-
    -
  • Description: Determines the type of random number generator that will be used to generate wind sensor data.
    • -
  • Datatype: string
    • -
  • Acceptable Values: gaussian, constant
    • -
-

wind_generation.mvgaussian_params.mean

-
    -
  • Description: The mean value for the wind generated, expressed in kilometers per hour (km/h), for the multivariate -Gaussian generator.
    • -
  • Datatype: double array, length 3
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

wind_generation.mvgaussian_params.cov

-
    -
  • Description: The covariance matrix for the generated wind, represented as a string formatted as a 2D double array, -since ROS parameters do not support native 2D array types.
    • -
  • Datatype: string
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

current_generation.mvgaussian_params.mean

-
    -
  • Description: The mean value for the current generated, expressed in kilometers per hour (km/h), for the multivariate -Gaussian generator.
    • -
  • Datatype: double array, length 3
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

current_generation.mvgaussian_params.cov

-
    -
  • Description: The covariance matrix for the generated current, represented as a string formatted as a 2D double -array, since ROS parameters do not support native 2D array types.
    • -
  • Datatype: string
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
-

data_collection_node

-

file_name

-
    -
  • Description: The name of the file in which the data is saved, excluding the file extension.
    • -
  • Datatype: string
    • -
  • Acceptable Values: Any valid file name.
    • -
-

qos_depth

-
    -
  • Description: The maximum number of subscription messages to queue for further processing.
    • -
  • Datatype: int
    • -
  • Range: [1, MAX_INT)
    • -
-

topics

-
    -
  • Description: Specifies the topics to subscribe to. It should adhere to the format ['topic_name_1', 'topic_type_1', ...].
    • -
  • Datatype: string array with an even length
    • -
  • Acceptable Values: Each pair within the array must consist of a valid topic name as the first string and the -corresponding correct type as the second string.
    • -
-

bag

-
    -
  • Description: Determines whether to save recorded data as a ROS bag.
    • -
  • Datatype: boolean
    • -
  • Acceptable Values: true, false
    • -
-

json

-
    -
  • Description: Determines whether to save recorded data as a JSON file.
    • -
  • Datatype: boolean
    • -
  • Acceptable Values: true, false
    • -
-

write_period_sec

-
    -
  • Description: The interval (in seconds) for writing queued data to the JSON file.
    • -
  • Datatype: double
    • -
  • Range: (0.0, MAX_DOUBLE)
    • -
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/current/sailbot_workspace/scripts/index.html b/pr-450/current/sailbot_workspace/scripts/index.html deleted file mode 100644 index 44672b2de..000000000 --- a/pr-450/current/sailbot_workspace/scripts/index.html +++ /dev/null @@ -1,2559 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Scripts - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -
-

Source code

-

Our scripts can be found in scripts. -Its README has been copied below.

-
-

Scripts

-

how to run

-

All scripts in this directory should be able to be run with ./path/to/script (excluding arguments). -For this to work, the script will need to have a shebang and be executable. -For more details, see this tutorial.

-

ament-lint.sh

-

Script to lint source code in all ROS packages.

-

build.sh

-

Script to build all ROS packages in the Sailbot Workspace.

-

clang-tidy.sh

-

Script to run Clang-Tidy using ament_clang_tidy.py.

-

run_virtual_iridium.sh

-
./run_virtual_iridium.sh <(optional) webhook server url> <(optional) virtual iridium http server port>
-
-

Creates a pair of socat sockets $LOCAL_TRANSCEIVER_TEST_PORT and $VIRTUAL_IRIDIUM_PORT and binds the latter to a -virtual iridium server running on localhost:8080, which substitutes the Rockblock HTTP server used in deployment. -Allows testing of satellite code without needing physical hardware.

-

Optional argument - webhook server url:

-
    -
  • Specify where the URL where the Remote Transceiver or whatever other HTTP server is running.
    • -
  • Default is http://127.0.0.1:8081, which assumes fully local testing.
    • -
-

Optional argument - virtual iridium server port

-
    -
  • Specify which localhost port the virtual iridium runs on.
    • -
  • Default is 8080.
    • -
-

$LOCAL_TRANSCEIVER_TEST_PORT acts as the serial port for AT commands. For example, to test via CLI:

-
    -
  1. ./run_virtual_iridium.sh
    2. -
  2. To monitor just the $LOCAL_TRANSCEIVER_TEST_PORT without extra debug messages, in a new terminal run - cat $LOCAL_TRANSCEIVER_TEST_PORT. What you see output from this command will be what the Local Transceiver reads - and sends.
    3. -
  3. To issue CLI commands, open a new terminal and run stty 19200 < $LOCAL_TRANSCEIVER_TEST_PORT to set the baud rate.
    4. -
  4. printf "at+sbdix\r" > $LOCAL_TRANSCEIVER_TEST_PORT. This command queries the (currently empty) mailbox.
    5. -
  5. curl -X POST -F "test=1234" http://localhost:8080 (this is garbage data - it doesn't mean - anything). You should see the original terminal print that it received a POST request.
    6. -
  6. printf "at+sbdix\r" > $LOCAL_TRANSCEIVER_TEST_PORT to view the mailbox again. It will now indicate that it has the - data.
    7. -
-

Other relevant commands include (but are not limited to):

-
    -
  • at+sbdwb=<msg_length>\r: Setup the port to receive binary data of length msg_length on next input.
    • -
  • at+sbdrb\r: Read binary content in the mailbox.
    • -
  • at+sbdd2\r: Clear all buffers.
    • -
-

run-tests.sh

-

Script to setup, build, and test all ROS packages.

-

run_software.sh

-

Script to setup, build, and run all ROS packages.

-

setup.sh

-

Script to handle ROS setup.

-

test.sh

-

Script to run tests in all ROS packages.

- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/current/sailbot_workspace/usage/help/index.html b/pr-450/current/sailbot_workspace/usage/help/index.html deleted file mode 100644 index b37efe4f8..000000000 --- a/pr-450/current/sailbot_workspace/usage/help/index.html +++ /dev/null @@ -1,2555 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Help - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Help

-

Performance Issues

-

If you are not satisfied with the performance of Sailbot Workspace, here are some things you can try:

-
    -
  • Free up memory: close programs that you aren't using
    • -
  • Free up disk space: permanently delete large programs and files that you don't need anymore
    • -
  • Run Sailbot Workspace in a GitHub Codespace
      -
    • In a codespace with 8GB of RAM, building all packages from scratch with the -q argument takes about a minute. -If your computer takes longer than, or you want to free up memory and disk space, you can -setup Sailbot Workspace in a GitHub Codespace
      • -
    -
    • -
  • If you are running Sailbot Workspace on Windows, dual boot Ubuntu and run Sailbot Workspace there
      -
    • Sailbot Workspace performs worse on Windows than bare metal Linux because it uses Docker, which is not natively supported.
      • -
    • Here is a guide to dual boot the operating systems we recommend: How to Dual Boot Ubuntu 22.04 LTS and Windows 11
        -
      • We recommend allocating at least 50 GB to Ubuntu to leave some wiggle room for Docker
        • -
      • The process is similar for other Ubuntu and Windows versions, - but feel free to search for a guide specific to the combination you want to dual boot
        • -
      • Since Sailbot Workspace uses Docker, it should be able to run on any Linux distribution, not just Ubuntu. - However, we may not be able to provide support if you encounter any difficulties with this
        • -
      -
      • -
    -
    • -
-

Troubleshooting

-

If you are having some trouble running our software, here are some things you can try:

-

Sailbot Workspace Troubleshooting

-
    -
  • Update Sailbot Workspace
    • -
  • Run the setup task to update package dependencies
    • -
  • Build from scratch
      -
    1. Run the clean task to delete C++ generated files
      2. -
    2. Run the purge task to delete ROS generated files
      3. -
    3. Run the Build All task to rebuild
      4. -
    -
    • -
-

VS Code Troubleshooting

-
    -
  • Rebuild the Dev Container: run the Dev Containers: Rebuild Container VS Code command
    • -
  • Reload VS Code: run the Developer: Reload Window VS Code command
    • -
  • Identify broken extension: run the Help: Start Extension Bisect VS Code command -
    • -
-

System Troubleshooting

-
    -
  • Restart WSL: close Sailbot Workspace and Docker Desktop then run wsl --shutdown in PowerShell
    • -
  • Restart computer
    • -
-

Docker Troubleshooting

-
    -
  • -

    Delete Docker files

    -
    -Running Docker CLI commands on Windows -

    On Windows, Docker CLI commands should be run in the Ubuntu terminal while Docker Desktop is running.

    -
    -
      -
    • Run docker system prune to remove all unused containers, networks, and dangling and unreferenced images
        -
      • Add --all to additionally remove unused images (don't have a container associated with them)
        • -
      • Add --volumes to additionally remove volumes (makes Bash history and ROS logs persist across containers)
        • -
      -
      • -
    • Run docker rmi -f $(docker images -aq) to remove all images
      • -
    • Install a previous version of Docker Desktop
      • -
    -
    • -
-

Shrink WSL Distributions' Size

-

After using Docker and Ubuntu for a while, you may notice that the vdisks are very large. As of May 2024, -they are located at C:\Users\<user>\AppData\Local\Docker\wsl\data\ext4.vhdx and C:\Users\<user>\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx, -respectively.

-

The problem is that these vdisks can automatically grow but not shrink, so if you download -large files (like Docker images) and delete them once they're not needed the space is not freed. -You can shrink vdisk using these commands.

- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/current/sailbot_workspace/usage/how_to/index.html b/pr-450/current/sailbot_workspace/usage/how_to/index.html deleted file mode 100644 index 510cb3ec6..000000000 --- a/pr-450/current/sailbot_workspace/usage/how_to/index.html +++ /dev/null @@ -1,3011 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - How-To's - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

How-To's

-

Run VS Code commands, tasks, and launch configurations

-
-

MacOS keyboard shortcuts

-

For keyboard shortcuts on MacOS, substitute Ctrl with Cmd.

-
-

VS Code commands can be run in the Command Palette. -Open the Command Palette from the View menu or with Ctrl+Shift+P.

-

Tasks can be run using the Tasks: Run Task VS Code command. Build tasks can be run with Ctrl+Shift+B.

-

Launch configurations can be run from the Run and Debug view.

-

You can also run VS Code commands, tasks, launch configurations, and much more by typing their prefixes -into an empty Command Palette. Open an empty Command Palette with Ctrl+P or by clicking the box in the center -of the title bar. See the list below for some prefixes and their functions. -For prefixes that are words, you will have to append a space to them to bring up their functions.

-
    -
  • Nothing: files
    • -
  • >: VS Code commands
    • -
  • task: tasks
    • -
  • debug: launch configurations
    • -
  • ?: list all prefixes and their functions
    • -
-

Work with containerized applications

-

We have containerized the following applications for a variety of reasons:

- -

Running containerized applications

-

In the first section of dockerComposeFile of .devcontainer/devcontainer.json, there is a list of files: -each file contains the configuration for one or more applications.

-

The ones that are commented out are not run. To run them:

-
    -
  1. Uncomment the Docker Compose file(s) that the application(s) you desire to run are defined in
      -
    • Programs that are defined in the uncommented Docker Compose files will be started and stopped with Sailbot Workspace
      • -
    -
    2. -
  2. Uncomment the port mapping(s) of the application(s) you want to run in .devcontainer/docker-compose.yml
      -
    • Uncommented port mappings exposed ports to the host operating system; - e.g., so that web applications can be opened in your browser
      • -
    -
    3. -
  3. Run the Dev Containers: Rebuild Container VS Code command to restart Sailbot Workspace
    4. -
-

To stop running them:

-
    -
  1. Comment out the corresponding Docker Compose file in .devcontainer/devcontainer.json and port mapping in .devcontainer/docker-compose.yml
    2. -
  2. Stop the application's container: see Managing containerized applications
    3. -
-

Viewing MongoDB data

-

Connect the MongoDB VS Code extension to the running database: -Create a Connection for Deployment

-
    -
  • Use the default methods: "Paste Connection String" and "Open from Overview Page"
    • -
  • Our database's connection string is mongodb://localhost:27017
    • -
  • See the MongoDB VS Code extension docs for how - to use it to navigate or explore the database
    • -
-

Opening Docs or Website

-

Docs runs on port 8000 and Website 3005. You can see them in your browser at localhost:<port>. To open them using VS Code:

-
    -
  1. Run the Ports: Focus on Ports View VS Code command
    2. -
  2. Open the site by hovering over its local address and clicking either "Open in Browser" or "Preview in Editor"
      -
    • The local address of Docs is the line with a port of 8000
      • -
    • The local address of Website is the line with a port of 3005
      • -
    -
    3. -
-
-

Turn off auto saving

-

Changes made to their files are loaded when they are saved, so if Auto Save is on, turn it off -so that the Docs/Website servers aren't continuously reloading. Auto Save is on by default in GitHub Codespaces

-
-

Managing containerized applications

-

Each application runs in a Docker container. Containers can be managed using Docker Desktop or CLI commands:

-
    -
  • -

    View Sailbot Workspace containers

    -
    -
    -
    -
      -
    1. Select "Containers" in the top right
      2. -
    2. Expand "sailbot_workspace_devcontainer"
        -
      • The "Status" column shows whether a container is running or not
        • -
      -
      3. -
    -
    -
    -
    docker ps -a
-
    -
      -
    • Sailbot Workspace containers should be named something like sailbot_workspace_devcontainer-<application>-<number>
      • -
    • The STATUS column shows whether a container is running or not
      • -
    -
    -
    -
    -
    • -
  • -

    View a container's logs, the output of the container (including errors that caused it to stop)

    -
    -
    -
    -
      -
    1. Click on a container
      2. -
    2. Navigate to the "Logs" view if not already on it
      3. -
    -
    -
    -
    docker logs <container>
-
    -
    -
    -
    -
    • -
  • -

    Start a container that is not running

    -
    -
    -
    -
      -
    1. Click start
      2. -
    -
    -
    -
    docker start <container>
-
    -
    -
    -
    -
    • -
  • -

    Stop a container that is running

    -
    -
    -
    -
      -
    1. Click stop
      2. -
    -
    -
    -
    docker stop <container>
-
    -
    -
    -
    -
    • -
-

Manage software packages

-
-

Why can't I just install the dependencies myself in the command line interface with pip or apt?

-

Although this will temporarily work, installing apt and/or Python dependencies directly in sailbot workspace using -the commandline interface will not persist between container instances. The dependencies will need to be manually -installed every single time you create a new instance of sailbot workspace, which is not feasible when we start to -use many dependencies at once.

-

Of course, one could also install dependencies inside the sailbot workspace Docker images to allow such dependencies -to persist across container instances. However, putting dependencies inside package.xml distinguishes between -what dependencies are needed for ROS packages and what dependencies are needed for infrastructure purposes.

-
-

Add apt or python dependencies to ROS packages

-

If running your ROS packages requires external dependencies from an apt repository or python package, one of the following -tags should be added to the package.xml file in the root directory of the ROS package:

-
<depend>ROSDEP_KEY</depend>
-<build_depend>ROSDEP_KEY</build_depend>
-<build_export_depend>ROSDEP_KEY</build_export_depend>
-<exec_depend>ROSDEP_KEY</exec_depend>
-<test_depend>ROSDEP_KEY</test_depend>
-
-
    -
  • -

    Learn what each tag is used for here.

    -
    • -
  • -

    Replace ROSDEP_KEY with the rosdep key for the dependency, which can be found online.

    -
      -
    • Use the key associated with ubuntu since sailbot workspace uses Ubuntu, or debian which Ubuntu is based on
      • -
    • Do not include the square brackets in package.xml
      • -
    -
    -
    -
    -
      -
    • Rosdep keys for apt repositories can be found here
      • -
    -
    -
    -
      -
    • Rosdep keys for python packages can be found here
      • -
    • Since we use Python 3, look for the packages that start with python3- (python- is usually for Python 2)
      • -
    -
    -
    -
    -
    • -
  • -

    If there isn't rosdep key for the dependency, you can add your own to custom-rosdep.yaml - in the root directory of the ROS package

    -
    • -
-

After completing these steps, run the setup task and the -desired dependencies should be installed. ROS uses a dependency management utility, rosdep, to handle the installation -of dependencies. In addition to runtime dependencies, rosdep also handles dependencies for build time, dependencies for -testing, sharing dependencies between ROS packages, and more. -See the ROS documentation on rosdep -to learn more.

-

Add dependencies to a Docker image

-

There are a couple cases where you would want to add dependencies to a Docker image instead of ROS package:

-
    -
  1. The dependency is not used to build/run/test a ROS package
    2. -
  2. There is no apt or pip package for your dependency so you have to build from source
    3. -
-

To verify your changes, you can add them to .devcontainer/Dockerfile then -run the Dev Containers: Rebuild Container VS Code command. Once verified, migrate the changes to one of the upstream -images: base, local-base, dev, or pre-base.

-

Enable GitHub Copilot in Sailbot Workspace

-

GitHub Copilot is an AI paired programming tool that can help you accelerate your development by providing suggestions -for whole lines or entire functions inside your editor.1 To enable GitHub Copilot:

-
    -
  1. -

    Apply to GitHub Global Campus as a student -to use GitHub Copilot and get other student benefits for free. It may take a few days for your student status to be -verified. In the meantime, you can still continue with the next steps. However, you will need to use the GitHub Copilot -free trial until your account is verified.

    -
    2. -
  2. -

    Sign up for GitHub Copilot for your personal account. -If it offers a free trial, then take it. You should see a page telling you that you can use GitHub Copilot for free -(if you have a verified student account).

    -
    3. -
  3. -

    Uncomment the github.copilot extension in .devcontainer/devcontainer.json and run the - Dev Containers: Rebuild Container VS Code command

    -
    4. -
  4. -

    Sign into your GitHub account in VS Code. The GitHub Copilot extension should automatically prompt you to sign into -your account if you are not already.

    -
    -VS Code is not prompting me to sign into my account -

    You may already be signed in into your GitHub account. You can check by clicking on the -Accounts icon in the bottom-left corner in VS Code and verify that you see your GitHub account.

    -

    If you do not see your account, you can get the sign in prompt by trying:

    -
      -
    • Reloading the VS Code window: Ctrl+Shift+P and select Developer: Reload Window
      • -
    • Rebuilding the devcontainer: Ctrl+Shift+P and select Dev Containers: Rebuild Container
      • -
    • If using a Mac, use Cmd instead of Ctrl
      • -
    -
    -
    5. -
  5. -

    If all the previous steps were done correctly, you should see the GitHub Copilot icon in -the bottom-right corner of VS Code without any error messages. For more information on how to use Copilot and a tutorial, -refer to:

    - -
    6. -
-

Use your dotfiles

-

Dotfiles are configuration files for various programs.2

-
-More about dotfiles -
    -
  • They are called dotfiles because their filenames start with a dot (.)
    • -
  • On Linux and MacOS, files and directories that begin with a dot are hidden by default
    • -
  • To list dotfiles using the ls command, specify the -a argument: ls -a
    • -
-
-

Dotfiles that are commonly modified include:

-
    -
  • Bash: ~/.bashrc
    • -
  • Git: ~/.gitconfig
    • -
  • Vim: ~/.vimrc
    • -
-

To use your dotfiles:

-
    -
  1. Ensure that the base, local-base, or dev image - installs the programs that the dotfiles correspond to
    2. -
  2. -

    Copy the dotfiles to the .devcontainer/config/ directory. - If a dotfile is located in a child directory, you will have to created it. - For example, if a dotfile's path is ~/.config/ex_dotfile, you will need to copy it to .devcontainer/config/.config/ex_dotfile

    -
    -

    Special cases

    -
      -
    • ~/.gitconfig: there is no need copy your Git dotfile, as Dev Containers do this automatically
      • -
    • ~/.bashrc: don't copy your Bash dotfile, as it would override the one created in the dev image. -Instead, add your bash configuration .aliases.bash or .functions.bash in the config directory, as these are sourced -by the created Bash dotfile.
      • -
    -
    -
    3. -
  3. -

    Run the Dev Containers: Rebuild Container VS Code command

    -
    4. -
-

Run Raye's software

-

Raye was our previous project. Her software can be run in the raye branch:

-
    -
  1. Switch to the raye branch: git switch raye
    2. -
  2. Rebuild the Dev Container: run the Dev Containers: Rebuild Container VS Code command
    3. -
  3. If you want to run Raye's local pathfinding visualizer, - complete step 2 of the setup instructions
    4. -
-
-

raye branch disclaimers

-
    -
  1. Since raye (and Raye's codebase in general) is not in active development, it may not be 100% functional - or contain all the features in main
    2. -
  2. raye is more memory intensive than main because the parent image of its Dev Container is much larger; - this may lead to worse performance
    3. -
-
-

Build Raye's ROS packages

-

To build Raye's ROS packages, run the following commands:

-
roscd
-catkin_make
-
-

Run packages from different workspaces

-

The raye branch has two ROS workspaces: one for Raye and one for the new project. -To run ROS packages, you will have to source the overlay of the workspace that it is in:

-
-
-
-
srcnew
-
-
-
-
srcraye
-
-
-
-
-

Then you can run launch files or package-specific executables in that workspace with:

-
-
-
-

ros2 launch ... or ros2 run ..., respectively.

-
-
-

roslaunch ... or rosrun ..., respectively.

-
-
-
-

Raye's known issues

-
-

Run commands for Raye packages are very slow

-

On non-Ubuntu-based Linux operating systems, Run commands for Raye packages may take a long time to start-up. -This is because the system has trouble resolving the local hostname.

-

To resolve this bug, run the commands below in the Dev Container:

-
echo 'export ROS_HOSTNAME=localhost' >> ~/.bashrc
-echo 'export ROS_MASTER_URI=http://localhost:11311' >> ~/.bashrc
-
-
-
-
-
    -
  1. -

    GitHub Copilot Quickstart Guide ↩

    -
    2. -
  2. -

    Dotfiles – What is a Dotfile and How to Create it in Mac and Linux ↩

    -
    3. -
-
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/current/sailbot_workspace/usage/setup/index.html b/pr-450/current/sailbot_workspace/usage/setup/index.html deleted file mode 100644 index 9c54bc7b1..000000000 --- a/pr-450/current/sailbot_workspace/usage/setup/index.html +++ /dev/null @@ -1,2943 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Setup - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Setup Instructions

-

Sailbot Workspace can be run on Windows, Linux, or macOS, but is the easiest to set up and performs the best on -Ubuntu and its derivatives. -The workspace may not perform well on Windows computers with 8GB of memory or less; -in this case, please check out our recommendations in the Performance Issues -section.

-

1. Setup prerequisites

-

Docker

-

Docker is a platform that uses OS-level virtualization1 to develop, ship, and -run applications.2 We use it to separate our applications from our infrastructure2 so that we can update and -version control our infrastructure for every use case (software members, CI, deployment) in one place: this repository.

-

Docker Engine is a software used to run Docker. -However, it can only be installed on Linux. -Docker Desktop is a software used to run Docker in a VM,3 -allowing it to be installed on Windows and macOS in addition to Linux.

-
-
-
-
    -
  1. -

    Set up prerequisites, WSL and Ubuntu:

    -
      -
    1. -

      In PowerShell, run wsl --install Ubuntu, then exit, wsl --update, and wsl --set-default Ubuntu

      -
      -Ubuntu is already installed? -

      If Ubuntu is already installed, check that it is the right WSL version:

      -
        -
      1. Check the WSL versions of Linux distributions with wsl -l -v
        2. -
      2. If Ubuntu's VERSION is 1, upgrade it to WSL 2 with wsl --set-version Ubuntu 2
        3. -
      -
      -
      2. -
    2. -

      Open the Ubuntu app to set up or verify its configuration:

      -
        -
      1. If you are opening Ubuntu for the first time, a setup process will run; -follow the prompts to finish setting it up
        2. -
      2. -

        Run whoami to verify that it returns your Ubuntu username

        -
        -whoami returns root -

        If whoami returns root:

        -
          -
        1. Create a non-root user with sudo privileges
          2. -
        2. Change the default Ubuntu user to this newly-created user: run ubuntu config --default-user <username> -in PowerShell, replacing <username> with the name of the newly-created user
          3. -
        3. Run whoami after closing and reopening Ubuntu, verifying that it returns your Ubuntu username
          4. -
        -
        -
        3. -
      -
      3. -
    -
    2. -
  2. -

    Install Docker Desktop -with the WSL 2 backend

    -
    -Docker Desktop - Unexpected WSL Error -

    image

    -

    If the above error shows when trying to start Docker Desktop on your laptop:

    -
      -
    1. For windows users navigate to C:\Users\user_name and delete the .Docker folder
      2. -
    2. Restart Docker Desktop
      3. -
    -
    -
    -Docker Desktop can't start up and WSL hangs when restarting -

    If Ubuntu can't start up and WSL hangs when restarting:

    -
      -
    1. Open command prompt as administrator and run the command netsh winsock reset
      2. -
    2. Uninstall and reinstall Docker Desktop
      3. -
    3. Restart your computer
      4. -
    -

    More potential solutions can be found here: -Link

    -
    -
    3. -
-
-
-

Install Docker Desktop for your computer's CPU.

-
-
-
    -
  1. Install Docker Engine
      -
    • As of February 2023, Sailbot Workspace (more specifically its use of VS Code Dev Containers) isn't compatible - with Docker Desktop for Linux; if you have Docker Desktop installed, uninstall it and install Docker Engine instead.
      • -
    -
    2. -
  2. Manage Docker as a non-root user
    3. -
  3. Configure Docker to start on boot
    4. -
-
-
-
-

VS Code

-

Visual Studio Code is a powerful and customizable code editor for -Windows, Linux, and macOS. We strongly recommend that you use this editor to develop our software so that you can -use all the features of Sailbot Workspace.

-
    -
  1. Install VS Code
    2. -
  2. Install the Remote Development Extension Pack
    3. -
-

Git

-

Git is a free and open source distributed version control system designed to handle everything from -small to very large projects with speed and efficiency.4

-
    -
  1. Check if Git is installed with git --version (on Windows, run command in PowerShell) -
    2. -
  2. Configure your name and email: Git config file setup - (on Windows, run commands in Ubuntu)
    3. -
  3. -

    Login to GitHub

    -
    -
    -
    -
      -
    1. -

      Run the git config command for your Git version in Git Credential Manager setup (run command in Ubuntu)

      -
      -

      Which Git to check

      -

      Git is installed seperately in Windows and Ubuntu, so they could be at different versions. -We want to check the version of Git on Windows, not Ubuntu: -run git --version in PowerShell and not Ubuntu. -However, the git config command itself is run in Ubuntu.

      -
      -
      2. -
    -
    -
    -
      -
    1. Install the GitHub CLI: Installation
      2. -
    2. Run gh auth login and select the first option for all choices
      3. -
    -
    -
    -
    -
    4. -
  4. -

    Verify that you have successfully logged in to GitHub by cloning a private GitHub repository (run command in Ubuntu)

    -
      -
    1. If you are a part of the UBCSailbot Software GitHub team, - you shouldn't see any errors running git clone https://github.com/UBCSailbot/raye-ais.git
      2. -
    2. You can delete this repository with rm -rf raye-ais
      3. -
    -
    5. -
-

2. Setup X11 forwarding

-

X11 forwarding is a mechanism that enables Sailbot Workspace to run GUI applications.

-
-

You can skip this step since we currently aren't running any GUI applications

-
-
-Setup instructions for X11 forwarding -
    -
  1. Ensure that the versions of VS Code and its Dev Containers extension support X11 forwarding:
      -
    1. VS Code version >= 1.75
      2. -
    2. Dev Containers version >= 0.275.1
      3. -
    -
    2. -
  2. -

    Verify that echo $DISPLAY returns something like :0

    -
    -echo $DISPLAY doesn't return anything -

    If echo $DISPLAY doesn't return anything, set it to :0 on shell initialization:

    -
      -
    1. Find out what shell you are using with echo $SHELL
        -
      1. Most Linux distributions use Bash by default, whose rc file path is ~/.bashrc
        2. -
      2. macOS uses Zsh by default, whose rc file path is: ~/.zshrc
        3. -
      -
      2. -
    2. Run echo 'export DISPLAY=:0' >> <rc file path>, replacing <rc file path> -with the path to your shell's rc file
      3. -
    3. Run echo $DISPLAY after closing and reopening your terminal, verifying it returns something like :0
      4. -
    -
    -
    3. -
  3. -

    Install a X11 server

    -
    -
    -
    -

    WSL includes a X11 server.

    -
    -
    -
      -
    1. Set up XQuartz following this guide
      2. -
    2. Copy the default xinitrc to your home directory: cp /opt/X11/etc/X11/xinit/xinitrc ~/.xinitrc
      3. -
    3. Add xhost +localhost to ~/.xinitrc after its first line
      4. -
    -
    -
    -
    -
    -
    -

    As of February 2023, almost all Linux distributions include a X11 server, Xorg. -This may change in the future as Wayland matures.

    -
    -
    -
      -
    1. Install xhost: sudo pacman -S xorg-xhost
      2. -
    2. Copy the default xinitrc to your home directory: cp /etc/X11/xinit/xinitrc ~/.xinitrc
      3. -
    3. Add xhost +local:docker to ~/.xinitrc after its first line
      4. -
    -
    -
    -
    -
    -
    -
    -
    4. -
  4. -

    Verify that X11 forwarding works:

    -
      -
    1. -

      Install x11-apps

      -
      -
      -
      -

      In Ubuntu, sudo apt install x11-apps.

      -
      -
      -

      XQuartz includes x11-apps. Ensure that XQuartz is running.

      -
      -
      -

      Install x11-apps using your desired package manager.

      -
      -
      -
      -
      2. -
    2. -

      Verify that running xcalc opens a calculator and that you can use it

      -
      3. -
    -
    5. -
-
-

3. Clone Sailbot Workspace

-
-

Where to clone on Windows

-

Run the command below in the Ubuntu app to clone it in the Ubuntu file system, otherwise sailbot workspace will not work. -Windows has a native file system as well as file systems for each WSL distribution.

-
-
git clone https://github.com/UBCSailbot/sailbot_workspace.git
-
-

4. Open Sailbot Workspace in VS Code

-
    -
  1. -

    Install code command in PATH

    -
    -
    -
    -

    The code command is installed by default.

    -
    -
    -

    See launching from the command line.

    -
    -
    -

    The code command is installed by default.

    -
    -
    -
    -
    2. -
  2. -

    Open the sailbot_workspace/ directory in VS Code: run code <relative path to sailbot workspace>

    -
      -
    • For example, if you just cloned the repository, the command would be code sailbot_workspace
      • -
    -
    3. -
-

5. Open the workspace file

-

Click the popup to Open Workspace. If there isn't a popup:

-
    -
  1. Open the file sailbot.code-workspace in VS Code
    2. -
  2. Click Open Workspace
    3. -
-

6. Open Sailbot Workspace in a Dev Container

-
    -
  1. Ensure that Docker is running
    2. -
  2. Click the popup to Reopen in Container. If there isn't a popup, - run the Dev Containers: Reopen in Container VS Code command
    3. -
-

7. Run the Build All task

-
-

Wait before running

-

Ensure that the postCreateCommand from devcontainer.json has completed before running this task.

-
-

The Build All task builds all the ROS packages.

-

8. Reload the VS Code terminals and window

-

Delete all open terminals and run the Developer: Reload Window VS Code command -to detect the files that were generated from building.

-

9. Start the system

-

Run the entire system to verify everything is working using the following command in the VS Code terminal:

-
ros2 launch $ROS_WORKSPACE/src/global_launch/main_launch.py
-
-

Use Ctrl+C in the terminal to stop the system.

-

Setup Sailbot Workspace in a GitHub Codespace

-

A codespace is a development environment that's hosted in the cloud.5 -Since Sailbot Workspace is resource intensive, it has high hardware requirements and power consumption, -which aren't ideal for development on laptops. GitHub Codespaces provide a seamless experience to work on repositories -off-device, especially if they specify a Dev Container like Sailbot Workspace. Codespaces can run in VS Code -or even in a browser for times when you aren't on your programming computer.

-
    -
  1. Create a GitHub Codespace following the steps in the relevant GitHub Docs page: -create a codespace for a repository. -A couple things to note: -
    2. -
  2. Follow the local setup instructions starting from 5. Open the workspace file
    3. -
-

Once you have a codespace set up:

-
    -
  • Open it by following the steps in the relevant GitHub Docs page: -reopening a codespace
    • -
  • Close it by running the Codespaces: Stop Current Codespace VS Code command
    • -
-
-

Known limitations of running Sailbot Workspace in a GitHub Codespace

-
    -
  • Does not support X11 forwarding to run GUI applications
    • -
  • High-spec machines not available: as of March 2023, the highest-spec machine that is publically available - has a 4-core CPU and 8GB of RAM
    • -
-
-
-
-
    -
  1. -

    Wikipedia Docker page ↩

    -
    2. -
  2. -

    Get Docker ↩↩

    -
    3. -
  3. -

    What is the difference between Docker Desktop for Linux and Docker Engine ↩

    -
    4. -
  4. -

    Git SCM ↩

    -
    5. -
  5. -

    GitHub Codespaces overview ↩

    -
    6. -
-
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/current/sailbot_workspace/usage/workflow/index.html b/pr-450/current/sailbot_workspace/usage/workflow/index.html deleted file mode 100644 index 2add228fe..000000000 --- a/pr-450/current/sailbot_workspace/usage/workflow/index.html +++ /dev/null @@ -1,2690 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Workflow - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Development Workflow

-

1. Open Sailbot Workspace

-

Once you have set up Sailbot Workspace, you can open it by opening a new VS Code window and selecting:

-
File > Open Recent > /workspaces/sailbot_workspace/.devcontainer/config/sailbot_workspace (Workspace) [Dev Container: Sailbot Workspace]
-
-
-Another way to open Sailbot Workspace on Windows -
    -
  1. Pin VS Code to the taskbar
    2. -
  2. Right-click VS Code in the taskbar and pin sailbot_workspace (Workspace) [Dev Container]
    3. -
-

Then you can open Sailbot Workspace by selecting it from the "Pinned" section of the VS Code taskbar icon's -right-click menu.

-
-

2. Update Sailbot Workspace

-

Sailbot Workspace is still in active development, check out its recent releases -and commit history. -If there are new features or bug fixes that you want to try, you will need to update your local version of Sailbot Workspace:

-
    -
  1. -

    Switch Sailbot Workspace to the main branch if you aren't in it already

    -
    -If you running Git commands in the CLI, make sure that you are in the correct repository -

    Sailbot Workspace contains other repositories in the src/ directory, so if you are in one of its subdirectories -you may be in the wrong repository.

    -

    To check which repository you are in, run git remote -v; if its output contains sailbot_workspace, -you are good to go. -If not, you can navigate the root directory of the Sailbot Workspace repository with cd $ROS_WORKSPACE, -or open a new terminal in its root directory with Ctrl+Shift+` then Enter.

    -
    -
      -
    • If you are unable to switch branches because you have uncommitted changes, stash them
      • -
    -
    2. -
  2. -

    Pull the latest changes

    -
      -
    • If you stashed your uncommitted changes, pop them
      • -
    -
    3. -
  3. -

    If prompted, rebuild the Dev Container

    -
    -When does the Dev Container need to be rebuilt? -

    To apply the modifications to its configuration files in .devcontainer/ that occurred since it was last built.

    -

    VS Code will prompt you to rebuild when devcontainer.json, Dockerfile, or docker-compose*.yml. -These file may be modified if you:

    -
      -
    • Pull the lastest changes of a branch
      • -
    • Switch branches
      • -
    • Update a file in .devcontainer/ yourself
      • -
    -

    However, there may be changes to the Dev Container that VS Code can't detect. -To rebuild it yourself, run the Dev Containers: Rebuild Container VS Code command.

    -
    -
    4. -
  4. -

    If you want to run our docs or website, see How to work with containerized applications

    -
    5. -
-

3. Make your changes

-

We make changes to our software following our GitHub development workflow. -Of particular relevance is the Developing on Branches page.

-
-

Git interfaces

-

One way to interface with Git is through CLI commands. However, you may find it faster to use -VS Code's interface, -especially when working with multiple repositories.

-
-

Things to note when making changes:

-
    -
  • When C++ or Python files are saved, you may notice that some lines change. We use formatters to help fix lint errors; - not all lint errors can be fixed by formatters, so you may have to resolve some manually
    • -
  • When changing a package's source files, you likely should update its test files accordingly
    • -
-

4. Build your changes

-

In general, changes need to be built before they can be run. You can skip this step if you only modified Python source -or test files (in python_package/python_package/ or python_package/test, respectively), or are running a launch type -launch configuration.

-
    -
  1. Depending on which packages you modified, run the Build All or Build Package task
      -
    1. Unless you want to run clang-tidy, use the -q build argument (default) for quicker build times
      2. -
    -
    2. -
-

5. Verify your changes

-
-Running GUI applications on macOS -

If you want to run GUI applications on macOS, ensure that XQuartz is running.

-
-

Lint and Test

-

Run lint and test tasks to make sure you changes will pass our CI:

-
    -
  • ament lint
    • -
  • For C++ packages, clang-tidy
    • -
  • test
    • -
-

In addition to VS Code tasks, the Testing tab on the VS Code primary sidebar -contains individual tests. One can run specific unit tests by clicking the Run Test -icon beside the test name.

-

VS Code Test Tab

-

Run a Package

-

To verify that your changes do what you expect, you may want to run the package you modified. The run commands for each -package should be documented in their READMEs, but in general they can be run using a CLI or VS Code command:

-
-
-
-
    -
  • Launch files:
      -
    • ros2 launch <package> <launch file>
      • -
    • ros2 launch <path to launch file>
      • -
    -
    • -
  • Nodes:
      -
    • ros2 run <package> <executable>
      • -
    -
    • -
-
-CLI features -

There are many commands that can be autocompleted in the terminal. -Take advantage of this so that you run commands faster and memorize less syntax. -If there is only one possibility, pressing tab once will complete it. -If there is more than one possibility, pressing tab again will list them out.

-

Some tab completion use cases:

-
    -
  • -

    View available commands: lists all ros2 commands

    -
    $ ros2 <tab><tab>
-action                          extension_points                multicast                       security
-bag                             extensions                      node                            service
-...
-
    -
    • -
  • -

    Complete commands: runs ros2 launch local_pathfinding main_launch.py

    -
    $ ros2<tab>la<tab>loc<tab>m<tab>
-
    -
    • -
  • -

    Navigate to directories: runs cd .devcontainer/config from the root directory of Sailbot Workspace

    -
    $ cd .d<tab>c<tab>
-
    -
    • -
-

Furthermore, navigate past commands with Up and Down and search through them with Ctrl+R.

-
-
-
-
    -
  • Launch files: ROS: Run a ROS launch file (roslaunch)
    • -
  • Nodes: ROS: Run a ROS executable (rosrun)
    • -
-
-
-
-

For more information on launch file use in our system, see this page.

-

Run the System

-

To verify that you didn't break anything, you may want to run the entire system. See -Invoking Launch Files for more information -on running the system.

-

Debugging

-

Debug your changes if they aren't behaving how you expect by setting breakpoints and running one of our launch -configurations in the Run and Debug tab on the VS Code primary sidebar. The launch configuration types are:

-
    -
  • Launch: runs the desired launch file or executable
      -
    • For launch files, ROS: Launch
      • -
    • For C++ executables, C++ (GDB): Launch
      • -
    -
    • -
  • Attach: attaches to a running executable
      -
    • ROS: Attach
      • -
    -
    • -
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/current/website/overview/index.html b/pr-450/current/website/overview/index.html deleted file mode 100644 index 673b7947d..000000000 --- a/pr-450/current/website/overview/index.html +++ /dev/null @@ -1,2525 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Overview - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -
-

Source code

-

The source code for Website can be found in src/website. -Its README has been copied below.

-
-

Website

-

In the website development timeline, we are currently evaluating the folllowing software stack: -Next.js website (this repository), Typescript, -React + Redux, and the MongoDB database. -The easiest way to evaluate these potential solutions for our purposes is in sailbot_workspace.

-

Database

-

MongoDB is a general purpose, document-based, distributed database built for modern application -developers and for the cloud era. If you want to learn more about MongoDB, visit their docs site: MongoDB Documentation.

-

Setup

-

Environment variables

-

We have two separate configurations: one for development .env.development, -the other for production .env.production. The values may vary, but the environment variables are the same. See below:

-
    -
  • MONGODB_URI: Your MongoDB connection string. Use mongodb://localhost:27017/<DB_NAME> to establish a connection - with the local database.
    • -
  • NEXT_PUBLIC_SERVER_HOST: The host URL of the website.
    • -
  • NEXT_PUBLIC_SERVER_PORT: The port number of the website.
    • -
  • NEXT_PUBLIC_POLLING_TIME_MS: The time interval for polling the database in milliseconds.
    • -
-

Package installation

-

The following command installs all required dependencies listed in the package.json file:

-
npm install
-
-

Once the installation is complete, you should see a node_modules directory in the project's root. -This directory contains all installed packages.

-

When installing a new package to the website, please follow the steps below:

-
    -
  1. -

    Access the terminal of the website container on Docker.

    -
    2. -
  2. -

    Run the command npm install <package-name>. - Replace <package-name> with the actual name of the package you want to add.

    -
    3. -
  3. -

    Should you encounter errors related to resolving peer dependencies, please re-run the command with - the header --legacy-peer-deps. Do not to use --force unless you're well aware of the potential consequences.

    -
    4. -
  4. -

    Review the package.json file to ensure the new package and its version have been added to the dependencies section.

    -
    5. -
  5. Confirm that package-lock.json has also been updated. - This file holds specific version information to ensure consistent installations across different environments.
    6. -
  6. Once the installation process is finished, please make sure to commit the files package.json and package-lock.json. - These files are essential for version controlling the dependencies that have been added.
    7. -
-

Run

-

Using Sailbot Workspace, -the website should be up and running on http://localhost:3005.

-

Otherwise, you execute the following commands to run it in development mode:

-
npm run dev
-
-

Linters

-

Before merging in new changes to the repository, please execute the following commands in order:

-
npm run format
-
-

This command runs Prettier to automatically format the code according to -the rules defined in the configuration file .prettierrc.

-
npm run lint
-
-

This command runs ESLint to analyze the code for potential errors -and enforce coding style based on the rules defined in the configuration file .eslintrc.

- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/index.html b/pr-450/index.html deleted file mode 100644 index 12845a405..000000000 --- a/pr-450/index.html +++ /dev/null @@ -1,2398 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - - - - - - - - - - - - - -
-
- - - - - - - - - - - - - - - - - - - - -

UBCSailbot Software Team Docs

-

Welcome to the UBC Sailbot software team docs 👋

-

Looking to get started with running the Sailbot codebase? Start by setting up the Sailbot Workspace:

-

Getting Started

-

What information is on this website?

-

Information on our current project is contained on this website. In particular, information on each of our major software -projects are provided in detail.

-

Current Project Overview

-

References to the software tools that we use are also provided on this website. This includes basic information on these -tools, how we use these tools on UBC Sailbot, and external links to helpful references and tutorials.

-

Software Team References

-

Who is this website for?

-

The docs site is primarily for the members on the UBC Sailbot software team. However, curious members of the public and/or -those who are interested in contributing to our open source software would also benefit from this site.

-

Prospective Members

-

Are you a member of the UBC community? Are you interested in what we do at UBC Sailbot? We are always looking for motivated -students to help us tackle the challenge of autonomous sailing. Learn more below!

-

Software Team Posting

-

Apply to join UBC Sailbot

- - - - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/javascripts/mathjax.js b/pr-450/javascripts/mathjax.js deleted file mode 100644 index 080801efb..000000000 --- a/pr-450/javascripts/mathjax.js +++ /dev/null @@ -1,16 +0,0 @@ -window.MathJax = { - tex: { - inlineMath: [["\\(", "\\)"]], - displayMath: [["\\[", "\\]"]], - processEscapes: true, - processEnvironments: true - }, - options: { - ignoreHtmlClass: ".*|", - processHtmlClass: "arithmatex" - } -}; - -document$.subscribe(() => { - MathJax.typesetPromise() -}) diff --git a/pr-450/javascripts/table_of_contents_themes.js b/pr-450/javascripts/table_of_contents_themes.js deleted file mode 100644 index 037d8ba45..000000000 --- a/pr-450/javascripts/table_of_contents_themes.js +++ /dev/null @@ -1,55 +0,0 @@ -const LIGHT_MODE = 0; -const DARK_MODE = 1; -const LIGHT_MODE_TABLE_OF_CONTENTS_LINK_COLOR = "#000000"; // Black -const DARK_MODE_TABLE_OF_CONTENTS_LINK_COLOR = "#ffffff"; // White -const SAILBOT_BLUE = "#2f97ec"; - -// Sets the theme given a mode -function set_table_of_content_link_color(mode) { - let linkColor = ""; - switch (mode) { - case LIGHT_MODE: - linkColor = LIGHT_MODE_TABLE_OF_CONTENTS_LINK_COLOR; - break; - case DARK_MODE: - linkColor = DARK_MODE_TABLE_OF_CONTENTS_LINK_COLOR; - break; - default: - console.log("Error determining website theme. Defaulting table of content link color to sailbot blue."); - linkColor = SAILBOT_BLUE; - break; - } - document.documentElement.style.setProperty("--md-table-of-contents-link-color", linkColor); -} - -// Returns the new theme index given the current theme -function toggle_table_of_contents_link_color(current_mode) { - switch (current_mode) { - case LIGHT_MODE: - return DARK_MODE; - case DARK_MODE: - return LIGHT_MODE; - default: - return -1; - } -} - -// An enslosure that keeps track of the mode and toggles the theme accordingly -const theme_enclosure = function(initial_mode) { - let current_mode = initial_mode; - return { - setLinkColor: () => {set_table_of_content_link_color(current_mode);}, - toggleLinkColor: () => {current_mode = toggle_table_of_contents_link_color(current_mode); set_table_of_content_link_color(current_mode);} - }; -}; - -// Set the theme upon the window loading -var initial_mode = __md_get("__palette").index; -table_of_contents_theme = theme_enclosure(initial_mode); -table_of_contents_theme.setLinkColor(); - -// Set the theme when the light/dark mode button is clicked -const buttons = document.querySelectorAll("form.md-header__option > label.md-header__button"); -buttons.forEach((button) => { - button.addEventListener('click', table_of_contents_theme.toggleLinkColor); -}); diff --git a/pr-450/overrides/main.html b/pr-450/overrides/main.html deleted file mode 100644 index c3eaa1a76..000000000 --- a/pr-450/overrides/main.html +++ /dev/null @@ -1,8 +0,0 @@ -{% extends "base.html" %} - -{% block outdated %} - You're not viewing the version in the main branch. - - Click here to go to main. - -{% endblock %} diff --git a/pr-450/reference/cpp/differences/index.html b/pr-450/reference/cpp/differences/index.html deleted file mode 100644 index c7ad1e3a5..000000000 --- a/pr-450/reference/cpp/differences/index.html +++ /dev/null @@ -1,2703 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Differences - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Differences Between C and C++

-

For most use cases, you can think of C++ as a superset of C. While this is not technically true, more often than not -you are able to write standard C code for a C++ program without issues. However, doing so ignores a lot of the benefits -and reasons to use C++.

-

Classes and Structs

-

In C structs can only contain member variables, but in C++ structs are basically classes but with a default member -visibility of public instead of private.

-
-Example -

The following code blocks are equivalent.

-
struct foo {
-private:
-    int x;
-    void helper(void);
-public:
-    foo(int y);
-}
-
-
class foo {
-private:
-    int x;
-    void helper(void);
-public:
-    foo(int y);
-}
-
-
-

Namespaces

-

One problem that is prevalent in C concerns the scoping of names. For example, let there be two files A.h and B.h -and a program ighxy.c, and let them both contain a float x and int bar(void).

-

Our program cannot compile because the linker cannot distinguish which bar() function we want to use! One way to fix -this in a C program would be to rename them a_bar() and b_bar(). Although this fix seems trivial for this example, -applying it to a file that has potentially 100 functions can be a lot more difficult, especially if two files just -happen to share the same prefix for their functions!

-

C++ introduces namespaces to tackle this problem. With namespaces, we can deal with naming conflicts much more easily. -Though be aware that namespaces are not necessary everywhere. See the following code snippet to see how they work.

-
-Example -
-
-
-
A.h
float x;
-int bar(void);
-
-
B.h
float x;
-int bar(void);
-
-
ighxy.c
#include "A.h"
-#include "B.h"
-
-int main(void) {
-    int a = bar();
-    ...
-}
-/* Error, does not compile*/
-
-
-
-
A.h
namespace a {
-float x;
-int bar(void);
-}
-
-
B.h
namespace b {
-float x;
-int bar(void);
-}
-
-
ighxy.cpp
#include "A.h"
-#include "B.h"
-
-int main(void) {
-    int a = a::bar();
-    int b = b::bar();
-    float xa = a::x;
-    float xb = b::x;
-    /* No problem! */
-    ...
-}
-
-
-
-
-
-
-Warning -

You may come across something like:

-
example.cpp
using namespace std;
-namespace io = std::filesystem;
-
-int main(int argc, char* argv[]) {
-    bool isDirectory = io::is_directory(argv[1]);  // Equivalent to std::filesystem::is_directory(argv[1])
-    cout << isDirectory << endl;
-    return 0;
-}
-
-

There are two things going on here.

-

First, using namespace std makes all functions and types defined within the standard namespace and included via -#include directives visible to example.cpp. If you are familiar with Python, the Python equivalent of this would -be import std as *. However, it is considered bad practice to do this as it eliminates the point of using -namespaces.

-
-
-
-
    class string {
-        // Insert implementation here
-    }
-
-    int main(void) {
-        string ourString = "Our own string implementation";
-        std::string stdString = "Standard Library string implementation";
-        ...
-    }
-
-
-
-
    using namespace std;
-
-    // ERROR - multiple definitions of type string
-    class string {
-
-    }
-
-

The compiler cannot infer which implementation we want.

-
-
-
-

Secondly, namespace io = std::filesystem is basically an alias for the std::filesystem namespace. This practice -is acceptable for long namespace identifiers, but be careful as it can still run into namespace conflicts if your -alias is the same as another namespace or alias.

-
-

Constant Expressions

-

In C, if we want to declare a constant or a function/expression that we want to be evaluated at compile time, we need -to use #define statements. One of the problems with #define statements is that they perform a simple copy paste -wherever they're used. For example:

-
-
-
-
#define PI 3.14F
-#define AREA_OF_CIRCLE(radius) ((PI) * (radius) * (radius))
-
-int main(void) {
-    float area = AREA_OF_CIRCLE(2.5F);
-    ...
-}
-
-
-
-
int main(void) {
-    float area = ((3.14F) * (2.5F) * (2.5F));
-    ...
-}
-
-
-
-
-
-

Note

-

AREA_OF_CIRCLE is a macro with arguments. If you are confused by it, this resource -has a detailed explanation on how they work.

-
-

Because of this copy-pasting, you need to be very careful with syntax, sometimes necessitating an ugly -do {} while(0) wrapper. -Moreover, symbols declared with #define are always globally visible, ignoring namespaces!

-

In C++, the use of constant expressions are preferred.

-
constexpr float pi = 3.14F;
-constexpr float area_of_circle(float radius) {
-    return pi * radius * radius;
-}
-
-

Constant expressions do not get copy pasted, and are instead placed in program memory just like a normal variable -or function. They also respect namespaces and function scopes, meaning the following code compiles.

-
Constant Expression Scoping
void foo(void) {
-    constexpr float rand = 123.456;
-    ...
-}
-
-void bar (void) {
-    constexpr float rand = 789.123;
-    ...
-}
-
-

Lambdas

-

Lambdas are primarily useful when you need to register a callback function one time and don't feel it's necessary to -write out a full function. They are in no way required though, so do not worry about learning them. However, it's -necessary to know that they exist such that you don't get confused when reading code. For more information, go here -for Microsoft's explanation.

-

Misc

-

Arrays

-

Using the C++ implementation of arrays -is preferred over C arrays. It is simply easier and safer to work with than a standard C array without any performance -costs.

-
-Example -

Passing an array to a function an iterating over it

-
-
-
-

#include "stdio.h"
-
-void print_contents(int *arr, int size) {
-    for (int i = 0; i < size; i++) {
-        printf("%d\n", *arr);
-    }
-}
-
-int main(void) {
-    int arr[5] = {0, 1, 2, 3, 4};
-    foo(arr, 5);
-    return 0;
-}
-
-We can't even guarantee that the integer pointer arr is an array!

-
-
-

C++ 20 makes passing arrays around a lot simpler. Do not worry about understanding the code shown below. It uses -some fairly advanced concepts and exists to illustrate how different such a simple operation can be.

-
#include <iostream>
-#include <array>
-#include <span>
-
-void print_contents(std::span<int> container) {
-    for (const auto &e : container) {
-        std::cout << e << std::endl;
-    }
-}
-
-int main(void) {
-    std::array<int, 5> arr = {0, 1, 2, 3, 4};
-    foo(arr);
-    return 0;
-}
-
-

The advantages of the C++ version are:

-
    -
  • Size is implicitly part of the object
    • -
  • We guarantee that foo takes a container, but it does not care if it's an array or, say, a vector, which is - preferable in this scenario where we simply iterate through the container's existing elements
    • -
-
-
-
-
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/cpp/start/index.html b/pr-450/reference/cpp/start/index.html deleted file mode 100644 index 2c88dab90..000000000 --- a/pr-450/reference/cpp/start/index.html +++ /dev/null @@ -1,2402 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Getting Started - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Getting Started

-

UBC Sailbot's Network Systems team uses C++ for its software. If you know already know C, then you already know the -bare minimum to write C++. This is a good starting point, but the additional features C++ provides allow for safer -programming practices.

-

For C/C++ Beginners

-

If you just need to know how C++ is different from C, then see the Differences Between C and C++. -You should also look at it if you go through and finish this section.

-

If you are new to C and C++, then this the best place to start. The tutorials provided in this section will help you -learn the fundamentals of the language. Do not feel pressured to do all the tutorials! Just get comfortable with the -syntax and the mechanisms of the language.

-
-

Note

-

The hardest part about this will likely be pointers and dynamic memory, so pay close attention to tutorials -concerning them! Additionally, dynamic memory requires the usage of pointers, but pointers do not require dynamic -memory!

-
-
-

Tip

-

Dynamic memory is much more prone to error than statically allocated memory, so try to use static allocation -whenever possible

-
- - - - - - - - - - - - - - - - - - - - - -
ResourceDescription
w3schools TutorialA structured tutorial that goes through basic concepts in C++. It's good to do up to the section on Classes.
YouTube TutorialIf you prefer video tutorial, then this is a comprehensive 4 hour video covering similar concepts to the one above. It is 4 hours long though.
Dynamic Memory OverviewA page going over how dynamic memory works in C++.
-

Feel free to add other resources other than the ones listed above if you find any that you like!

- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/cpp/tools/index.html b/pr-450/reference/cpp/tools/index.html deleted file mode 100644 index b8d2b809f..000000000 --- a/pr-450/reference/cpp/tools/index.html +++ /dev/null @@ -1,2619 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Tools - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Tools

-

A lot goes into making a well structured C++ project, much more than any one team should have to do.

-

CMake

-

CMake is a powerfull build automation tool that makes compiling code for large projects with a lot of interoperating -files a lot easier. Steps 1-3 of the official tutorial -are great for understanding the basics.

-

GDB

-

The GNU Project Debugger is the most commonly debugger for the C -language family. -VSCode also has a degree of integration with GDB that allows an easy to use GUI. This GDB cheat sheet -has all the GDB comands you will need to know. Be aware the VSCode has GUI buttons for some of these commands that are -easier to use.

- - -

GoogleTest

-

GoogleTest is the C++ unit testing framework we will be using. -The GoogleTest Primer is a good place to start.

-
-Example -
-
-
-
cached_fib.h
#include <vector>
-class CachedFib {
-public:
-    void CachedFib(int n);
-    int  getFib(int n);
-private:
-    std::vector<int> cache;
-}
-
-
cached_fib.cpp
#include <iostream>
-#include <vector>
-#include "cached_fib.h"
-
-void CachedFib::CachedFib(int n) {
-    cache.push_back(0);
-    cache.push_back(1);
-    for (int i = 2; i < n; i++) {
-        cache.push_back(cache[i - 1] + cache[i - 2]);
-    }
-}
-
-int CachedFib::getFib(int n) {
-    if (cache.size() < n) {
-        for (int i = cache.size(); i < n; i++) {
-            cache.push_back(cache[i-1] + cache[i-2]);
-        }
-    }
-    std::cout << cache[n - 1] << std::endl;
-}
-
-
-
-
test_cached_fib.cpp
#include "cached_fib.h"
-#include "gtest/gtest.h"
-
-CachedFib::testFib;
-
-class TestFib : public ::testing::Test {
-protected:
-    void Setup override {
-        // Every time a test is started, testFib is reinitialized with a constructor parameter of 5
-        testFib = CachedFib(5);
-    }
-}
-
-TEST_F(TestFib, TestBasic) {
-    ASSERT_EQ(getFib(5), 3) << "5th fibonacci number must be 3!";
-}
-
-// more tests
-
-
-
-
-
- - -

Google Protocol Buffer

-

Google Protocol Buffer (Protobuf) is a portable data serialization -method. We use it over other methods like JSON and XML because it produces smaller binaries, an important consideration -when sending data across an ocean. Unfortunately, there does not seem to be a easy to follow tutorial for using them, -but here are the C++ basics. The page -is quite dense and can be hard to follow, so do not worry if you do not understand it.

-

Clang

-

In its most basic form, Clang is a compiler for the C language family. -Clang has multiple -benefits like easier portability compared to, for example, GCC. Clang is actually "half" the compiler, the other half -being LLVM. Without going into unnecessary detail, Clang compiles C++ code to a generic language before LLVM compiles -it to machine specific language.

-

Clangd

-

Clangd is the Clang language server. It provides a much more powerful -intellisense than the default one used in VSCode's C/C++ extension.

-

Clang-Tidy

-

Clang-Tidy is a linting tool, who's main purpose is to catch potential -programming errors caused by bad programming style/practices using just static analysis.

-

Clang Format

-

An autoformatting tool that makes enforcing style guidelines much easier. When se tup, it corrects formatting as soon -as you hit save.

-

llvm-cov

-

We will use llvm-cov to evaluate our test coverage. -When used with -genhtml, we can generate HTML reports that that -show our line, function, and branch coverage line-by-line.

- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/docker/index.html b/pr-450/reference/docker/index.html deleted file mode 100644 index abb255383..000000000 --- a/pr-450/reference/docker/index.html +++ /dev/null @@ -1,2379 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Docker - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
- -
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/github/advanced_git/index.html b/pr-450/reference/github/advanced_git/index.html deleted file mode 100644 index eac99e5a1..000000000 --- a/pr-450/reference/github/advanced_git/index.html +++ /dev/null @@ -1,2365 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Advanced Git - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Advanced Git

-

Tutorial

- -
- -
- - - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/github/github_actions/index.html b/pr-450/reference/github/github_actions/index.html deleted file mode 100644 index 72bcdcf78..000000000 --- a/pr-450/reference/github/github_actions/index.html +++ /dev/null @@ -1,2365 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - GitHub Actions - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

GitHub Actions

-

Tutorial

- -
- -
- - - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/github/workflow/branches/index.html b/pr-450/reference/github/workflow/branches/index.html deleted file mode 100644 index 069b412b7..000000000 --- a/pr-450/reference/github/workflow/branches/index.html +++ /dev/null @@ -1,2529 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Developing on Branches - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Developing on Branches

-

We use branching to work on issues without modifying the main line. This ensures that the main line only -contains functional code and handles merge conflicts that arise -when multiple people are developing at the same time. For a quick rundown on branching in git, -consult the official git documentation.

-

Creating a branch

-

When starting a new issue, you will want to create a new branch for it:

-
-

Caution

-

When creating branches locally, it uses your local copy to create the new branch. Remember to do a git pull -if you intend on using the latest changes from the remote branch you are creating from.

-
-
Creating a new branch from main
# Switch to main
-git switch main
-
-# Update your local copy
-git pull
-
-# Clone a new branch from main
-git switch -c <branch_name>
-
-

IMPORTANT: When creating a new branch for an issue, you must create the branch from main.

-

Branch naming convention

-

When working on a new issue, you will want to create a branch to work on it. We have the following branch -naming convention:

-
<github_username>/<issue_number>-<issue_description>
-
-
-

Example

-

If Jill (GitHub Username: jill99) is going to take on an issue titled "Fix bug on pathfinding software" -and the issue number is 39, then the branch named can be named something like user/jill99/39-fix-pathfinding-bug.

-
-

If the branch that you are creating is not tied to an issue, then you do not need to put an issue number. -A descriptive title will suffice.

-

Tracking and committing changes

-

All files where new changes have been made must first be "staged" in order to make commits:

-
git add <FILES>
-
-

Files that are staged will be part of your next commit. Once you are confident in your changes and you are ready -to finalize them, then you should commit your changes:

-
git commit -m "<commit_message>"
-
-

Be sure to add a commit message that is descriptive of the changes that you made. It is encouraged that you make commits -often so you can keep track of your changes more easily and avoid overwhelmingly large commits when you look back on your -version history.

-

When you are ready to move your local changes to a remote branch, you want to push to the correct branch -and potentially set the upstream if it does not yet exist:

-
git push -u origin <current_branch_name>
-
-

Merging branches

-

There may be times where you want to merge two branches together, whether you diverged on some ideas and finally -want to synthesize them, or you just want to update your issue's branch with the main branch. In any case, merging -branches will be inevitable as part of the development process, so it is essential to understand how to merge branches.

-
-
-
-
# Checkout to destination branch
-git checkout <dest_branch>
-
-# Merge with local copy of other branch
-git merge <other_branch>
-
-
-
-
# Checkout to destination branch
-git checkout <dest_branch>
-
-# Fetch from remote
-git fetch
-
-# Merge remote copy of other branch
-git merge origin/<other_branch>
-
-
-
-
-
-

Info

-

Merging a remote branch into its local counterpart using the method above is essentially -the same operation as git pull.

-
-

Once the merge operation is complete, your destination branch should have updates both from itself and the other -branch that you merge. If you do a git log, you will also see a new commit that indicates that the merge happened.

-

Resolving merge conflicts

-

Merging two branches is not always easy since the commit history for both branches could look quite different, and -therefore conflicting changes can easily be made. If you run into a scenario like this, you may get something like this:

-

image

-

Upon inspecting bar.txt, we see the following:

-

image

-

Resolving merge conflicts is not always a trivial task, but there are many ways to resolve them which include:

- -
-

Tip

-

If you cannot resolve a merge conflict on your own, reach out to your lead for help!

-
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/github/workflow/issues/index.html b/pr-450/reference/github/workflow/issues/index.html deleted file mode 100644 index 47e80b116..000000000 --- a/pr-450/reference/github/workflow/issues/index.html +++ /dev/null @@ -1,2522 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Creating Issues - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Creating Issues

-

GitHub issues lets us plan and track our work on GitHub.

-

Getting started with issue templates

-

An issue is associated with a specific repository. To open the issues page for a given repository, click on -the issues tab in the repository navigation bar.

-

image

-

You will see a list of current issues (if any) for the repository. To create a new issue, click on the -New issue button in the upper right corner.

-

image

-

When creating a new issue, you will see a few issue templates. Since issues can be created for a variety of reasons, -issues may therefore be structured differently and contain different kinds of information. Issue templates were -introduced to give us a quick and structured way to writing issues.

-

image

-
-

Note

-

GitHub issues are written using GitHub-flavoured markdown. To add a little spice to your issues, refer -to the official GitHub documentation -for some quick tips and tricks on how to write awesome markdown!

-
-

Click on the Get started button to open the issue template. For this example, let's go with the New Feature -issue template. Upon opening the issue template, you should see a page like the one below:

-

image

-

At this point, you should give a succinct title and describe the issue in the textbox. You will also see some templated -sections to fill out. Try to give only the necessary details to make a clear and concise issue. If you are unsure on how -to construct your issue, take a look at current or past issues and ask the software leads for further guidance if necessary.

-

Finally, feel free to make suggestions -on new templates or changing current templates!

-
-

Tip

-

We understand that some issues may need extra sections to describe the issue further, or some of -the templated sections might not be relevant at all! Add or remove sections as necessary to get your -point across. The goal of the issue templates is to provide guidance, not police your documentation -methodologies!

-
-

Adding issues to a project

-

We use projects to plan and track the status of our issues and pull requests. -To add an issue to an existing project, click on the gear icon in the Projects section and add it to your desired -project. You will almost always want to add your issue to the Software organization project.

-

image

-

To verify that your issue has been added to your desired project, go to the UBC Sailbot organization, go -to the Projects tab on the organization banner, and select the project that it is added to. When added -to a project, it should show up under the General tab (depending on the project, this might not always -be the case).

-

Adding issues to a milestone

-

We use milestones to track progress on groups of issues or pull requests that we want to complete by a certain date. -Since our projects span over many years, it is important to work incrementally with small, -yet achievable goals. If your issue should belong to a milestone, simply add it to a milestone by clicking -on the gear icon in the Milestone section and add it to your desired milestone.

-

image

-
-

Note

-

Unlike projects, milestones are strictly associated with a repository.

-
-

Labelling issues

-

GitHub allows us to label our issues so that we can categorize them. It helps us identify at first glance what -kind of a problem that an issue aims to solve and which issues are more important. To add a label to your issue, -click on the gear icon in the Labels section and add your desired label(s).

-

image

-

The issue templates will already have labels assigned to them, but you should add or remove labels as you see fit -to make them as relevant as possible.

-
-

Note

-

Each repository might have different labels available, so be sure to check out all of the labels -at least once in the repository that you are working in. Feel free to suggest additional labels -as well!

-
-

Adding assignees

-

Every issue should be assigned to at least one person to work on it. If you are not sure who should be assigned -the issue initially, then don't worry about it for now since you can assign someone to the issue later on. To -assign someone an issue, click on the gear icon in the Assignees section and add the desired people.

-

image

-

Submit the issue

-

Once you are finished writing your issue, click on the Submit new issue button. You should now see your issue -in the issues list and in the UBC Sailbot software project.

- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/github/workflow/overview/index.html b/pr-450/reference/github/workflow/overview/index.html deleted file mode 100644 index 8e8d11ea9..000000000 --- a/pr-450/reference/github/workflow/overview/index.html +++ /dev/null @@ -1,2453 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Overview - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Development Workflow Overview

-
graph LR
-    B[Problem Conception] --> C{Small Fix?};
-    C --> |Yes| E[Development];
-    C --> |No| D[Issue Creation];
-    D --> E;
-    E --> F[Pull Request];
-    F --> G{Approved?};
-    G --> |No| E;
-    G --> |Yes| H[Merge PR into Main];
-

A good development workflow is essential to maintain a robust codebase and stay organized. The above -diagram is a high level overview of how our development process works, and parts of this process -are explained in subsequent sections.

-

Tutorial

- -
- -
- - -

Version control: Git

-

We use git to help us keep track of the version history of our codebase. Git is a free and open source -distributed version control system, and it is commonly used by many developers to keep track of changes -to their code over time. As a member of the software team on UBC Sailbot, it is absolutely necessary that -you know git. If you are unfamiliar with git, here are a few resources to help you get started:

- - - - - - - - - - - - - - - - - - - - - -
ResourceDescription
Beginners TutorialA 30 minute video on git for beginners. Good if you want to learn git quickly and nail all the fundamentals.
Pro Git bookA textbook on using git. Good if you are a completionist and want to deep dive into how git works (and if you have some time on your hands).
Common Git CommandsA condensed summary of some common git commands. Good to refer to once you are familiar with the fundamentals of git.
-

Remote server: GitHub

-

We use GitHub as our remote server where we store our codebase. In addition to using it for storage, we also -leverage many of GitHub's features to make for a smoother development process. Some examples of features -that we use are:

- - - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/github/workflow/pr/index.html b/pr-450/reference/github/workflow/pr/index.html deleted file mode 100644 index ea286a519..000000000 --- a/pr-450/reference/github/workflow/pr/index.html +++ /dev/null @@ -1,2484 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Pull Requests - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Pull Requests

-

Pull requests are used to verify code functionality and quality of a development branch before merging into the main branch, -accomplished through CI and code reviews.

-
-

Note

-

Pull requests are much like issues where we can do many of the same things. This goes for creating -comments in markdown, assigning reviewers, adding labels, adding projects, or adding milestones. -Sometimes we skip writing an issue when the change is relatively small.

-
-

Creating a pull request

-

To create a pull request in a repository, to go the Pull requests tab and then click New pull request:

-

image

-

On the next screen, you need to select the base branch that you are merging into, and the branch that you -are comparing. For the most part, the base branch will be the main branch, and the branch that you are comparing -will be the issue branch.

-

image

-

Once you have decided on your base and compare branches, click on Create pull request. You should see -the page below (looking in the dropdown menu, you can open the pull request as a draft to avoid notifying -reviewers until you are ready):

-

image

-

Notice how this is remarkably similar to the page of an issue. To link a pull request to an issue, simply add -<KEYWORD> #<ISSUE NUMBER> to the initial comment in the pull request. A list of valid keywords can be found -here.

-
-

Example

-

"This issue resolves #49. Please review my pull request!"

-
-

Observe that the right-hand side banner contains the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
ReviewersAssign reviewers to review your pull request. Always try to assign at least one reviewer.
AssigneesAssign the people who worked on the issue.
LabelsAssign labels to categorize pull requests.
ProjectsAssign a pull request to a project.
MilestoneAssign a pull request to a milestone.
-
-

Attention

-

If you linked the pull request to an issue, you should not add the pull request to a project or a milestone to -avoid duplicate cards.

-
-

Merging into main

-

Once the pull request and code reviews are complete, it is time to merge the changes in the pull request into the main -branch! However, this can only be done when the following conditions are met:

-
    -
  1. All CI checks pass (look for a green checkmark beside your latest commit on GitHub).
    2. -
  2. All reviewers have reviewed the PR and approved the PR.
    3. -
  3. There are no unresolved comments and suggestions from the reviewers.
    4. -
  4. There are no merge conflicts with the main branch.
    5. -
-

If all of these conditions are met, confirm that the merge is good to go by clicking Squash and merge:

-

image

-

Reviewing a pull request

-

A common activity that you will participate in is reviewing pull requests to give your feedback on other's code. -You will be notified when you have been requested to review a pull request and should promptly review it as -soon as time permits.

-

image

-

In particular, you will most likely be doing the following in a pull request:

-
    -
  • Asking Questions: Clarify your understanding about something that you are not sure about.
    • -
  • Providing Suggestions: Give some ideas about how to improve the current implementation and provide feedback to -your peers. This is a good opportunity to share your knowledge with others.
    • -
  • Verify Implementations: Identify potential bugs in the implementation and raise your concerns with the person -who developed the solution. This will reduce the likelihood of bugs and significantly bring down the number of issues -in the future.
    • -
  • Documentation: Record why certain changes were made, especially if this diverges from the proposed solution -in the linked issue (if any).
    • -
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/linux_commands/index.html b/pr-450/reference/linux_commands/index.html deleted file mode 100644 index dda1ed513..000000000 --- a/pr-450/reference/linux_commands/index.html +++ /dev/null @@ -1,2365 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Linux Commands - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Linux Commands

-

Tutorial

- -
- -
- - - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/markdown/index.html b/pr-450/reference/markdown/index.html deleted file mode 100644 index a8ea1bb19..000000000 --- a/pr-450/reference/markdown/index.html +++ /dev/null @@ -1,2578 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Markdown - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Markdown

-

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents.1 -You can do anything with Markdown, from creating websites to PDF documents, all in a clean format that is easy to -learn. Many of your favorite services use Markdown, so it would -be useful to pick it up to write technical documentation.

-

Markdown is not standardized across services. Many services that support Markdown have their -own "flavour" of Markdown. Be sure to know the Markdown features of the service -you are using so that your Markdown renders properly.

-

Getting Started

-

We recommend markdownguide.org to be your first point of reference if\ -you are learning Markdown for the first time. It covers topics like what Markdown is, its syntax, advanced tips, and the -different services that support Markdown. Flavours of Markdown specific to a service build on top of these basics.

-

Sailbot and Markdown

-

We write Markdown for GitHub and Material for MkDocs. The following sections -detail how Markdown is used in these services.

-

GitHub

-

We use Markdown in GitHub for technical documentation and collaboration. This includes:

-
    -
  • README.md files
    • -
  • Issues
    • -
  • Pull Requests
    • -
-

Almost all places where text is written in GitHub support Markdown. GitHub also allows you to preview -your Markdown before you submit any comments.

-
-
-
-

image

-
-
-

image

-
-
-
-

The image above shows an example of a "write" and a "preview" tab for writing a comment on an issue. It might look -different depending on where you are writing, but there usually exists a preview option!

-
-

GitHub-Flavoured Markdown

-

GitHub uses its own "flavour" of Markdown. Certain features, like using HTML, are excluded for security reasons. -Visit the official GitHub Markdown guide -for more information on the available features.

-
-

Material for MkDocs

-

We use Markdown in Material for MkDocs to create this website! Since it is written in Markdown, no frontend -experience is required to contribute to our docs.

-

Material for MkDocs supports powerful features purpose-built to take technical documentation to the next level. -Feel free to browse this site to see how we use these features, exploring their syntax in the -source code. -Since GitHub renders Markdown files automatically you will need to click the "Raw" button to view their contents.

-
-

Material-Flavoured Markdown

-

Material for MkDocs' flavour of Markdown extends upon vanilla Markdown, adding features such as admonitions -(like this note) and content tabs. Refer to the -official Material for MkDocs reference page -for more information on the available features.

-
-

Rendering Markdown

-

You have a few choices to render Markdown on your computer. -Be advised that if you are using an extended version of Markdown, you will -need to consult the documentation from the service provider to render their flavour of Markdown properly. The following -resources are good for rendering Markdown:

-
-
-
- -
-
-
    -
  • Markdown Preview GitHub Styling: -VS Code extension that renders GitHub-flavoured markdown.
    • -
  • Create a draft issue on GitHub and preview the markdown to see how it renders.
    • -
-
-
- -
-
-
-

Other resources exist to render Markdown like browser extensions that render Markdown as HTML and GitHub repositories -that contain source code to render your Markdown. Feel free -to browse around for the solution that suits your needs.

-

Linting

-

We lint our Markdown files to reduce errors and increase readability. In particular, we use two tools:

-
    -
  1. -

    markdownlint is -used to enforce a style guide. Its configuration file for this repository is .markdownlint.json. -If you use VS Code, there is a markdownlint extension.

    -
    2. -
  2. -

    markdown-link-check is -used to check for broken links. Its configuration file for this repository is .markdown-link-check.json.

    -
    3. -
-
-
-
    -
  1. -

    https://www.markdownguide.org/getting-started/ ↩

    -
    2. -
-
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/python/conventions/index.html b/pr-450/reference/python/conventions/index.html deleted file mode 100644 index 735f8b754..000000000 --- a/pr-450/reference/python/conventions/index.html +++ /dev/null @@ -1,2709 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Conventions - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Conventions

-

At UBC Sailbot, we follow standards in how we code to maintain a clean and comprehensible codebase. -This page addresses what conventions we use specifically when programming in Python and the tools to help us maintain -these conventions.

-

Style guide

-

Linting

-

To ensure that the codebase stays clean, we use flake8, which is a -tool for style guide enforcement mostly based off pep8. To automate -most of this process, we use autopep8, which is a tool that resolves -most style issues. However, there will be some issues that must be resolved by you!

-

Refer to this guide on how to write readable code in python with the -pep8 style guide.

-
-

Note

-

Our CI automatically checks that your code follows the pep8 standard. If it does not, your pull requests will -be blocked from being merged until those issues are resolved!

-
-

Type hinting

-

Even though Python is a dynamically typed language, newer versions support type hinting. Type hinting catches -errors, documents code, improves IDEs and linters, and helps build and maintain a clean software architecture.1 -Expanding on how it catches errors, a static type checker such as mypy -can be used.

-

There is some syntax to get familiar in order to use type checking. We recommend the following resources:

- -

Below are a few examples of using type hinting:

-
-Return the sum of a sequence -
from typing import Sequence, Union
-
-
-Number = Union[int, float]
-
-
-def sumseq(seq : Sequence[Number]) -> Number:
-    return sum(seq)
-
-
-
-Function with optional parameters and default values -
from typing import Optional
-
-
-def printArgs(a : str, b : str="World", c : Optional[str]=None) -> None:
-    print(f"Value of a: {a}")
-    print(f"Value of b: {b}")
-    if c is not None:
-        print(f"Value of c: {c}")
-
-
-
-Function with custom class -
class MyClass:
-    def __init__(self) -> None:
-        pass
-
-
-def foo(a : MyClass) -> None:
-    print(a)
-
-
-
-Forward referencing a class -
-
-
-
from __future__ import annotations
-
-
-def foo(a : MyClass) -> None:
-    print(a)
-
-
-class MyClass:
-    def __init__(self) -> None:
-        pass
-
-
-
-
def foo(a : 'MyClass') -> None:
-    print(a)
-
-
-class MyClass:
-    def __init__(self) -> None:
-        pass
-
-
-
-
-
-
-Function that never returns -
from typing import NoReturn
-
-
-def bar() -> NoReturn:
-    while True:
-        print("Hello World!")
-
-
-

Documentation

-

Code is written once and read a thousand times, so it is important to provide good documentation for current -and future members of the software team. The major things that we document in our code are:

-
    -
  1. Classes and Objects:
      -
    • What does it represent? What is it used for?
      • -
    • What are its member variables? What are they used for?
      • -
    -
    2. -
  2. Functions:
      -
    • What are the inputs and outputs?
      • -
    • What is the overall behavior and purpose of the function?
      • -
    -
    3. -
  3. Code:
      -
    • Is a line of code obscure and/or not clear? Add an inline comment to clear things up.
      • -
    • Break down a large process.
      • -
    -
    4. -
-

Ideally, the third point should be avoided as much as possible since we would want our code to be -self explanatory. It should be done only when absolutely necessary.

-

Generating docstrings

-

We use a vscode extension called autoDocstring -which autogenerates docstrings that we use to document our code. To install this extension, go to the Extensions tab in -vscode and search autoDocstring in the marketplace.

-

To generate docstrings, type """ at the beginning of the function that you want to document and the template -will be generated for you! If you use type hinting, this extention will autofill some of the -documentation for you!

-
-

Note

-

The autoDocstring extension only works for functions. It does not work for classes and objects, so documenting these -will have to be done manually. Be sure to follow the same format used by functions.

-
-

Example on documentation

-

It's hard to imagine what good documentation looks like. We provide a few examples below of documenting code using the -autoDocstring extension. The extension uses Google style docstrings -by default.

-
-Documentation example on a function -
from typing import List
-def inner_product(v1 : List[float], v2 : List[float]) -> float:
-    """
-    Computes the inner product between two 1D real vectors. Input vectors should have the
-    same dimensions.
-
-    Args:
-        v1 (List[float]): The first vector of real numbers.
-        v2 (List[float]): The second vector of real numbers.
-
-    Returns:
-        float : The inner product between v1 and v2
-    """
-    assert (len(v1) == len(v2)), "Input lists must have same length"
-
-    # Iterate through elementwise pairs
-    summation = 0
-    for e1, e2 in zip(v1, v2):
-        summation += (e1 * e2)
-    return float(summation)
-
-
-
-Documentation example with a stack -
from typing import Any
-class Stack:
-
-    """
-    This class represents a stack, which is an abstract data type that serves as a collection of
-    elements. The stack is a LIFO datastructure defined by two main operations: Push and Pop.
-
-    Attributes:
-        __stack (List[Any]): A list containing the elements on the stack.
-    """
-
-    def __init__(self):
-        """
-        Initializes the Stack object.
-        """
-        self.__stack = []
-
-    def push(self, element : Any) -> Any:
-        """
-        Pushes an element to the top of the stack.
-
-        Args:
-            element (Any): The element to be pushed on to the stack.
-        """
-        self.__stack.append(element)
-
-    def pop(self) -> Any:
-        """
-        Removes the element at the top of the stack and returns it. If the stack is empty,
-        then None is returned.
-
-        Returns:
-            Any, NoneType: The element at the top of the stack.
-        """
-        if self.is_empty():
-            return None
-        else:
-            return self.__stack.pop()
-
-    def is_empty(self) -> bool:
-        """
-        Determines whether the stack is empty or not.
-
-        Returns:
-            bool: Returns True if the stack is empty, and False otherwise.
-        """
-        empty = (len(self.__stack) == 0)
-        return empty
-
-    def __len__(self) -> int:
-        """
-        Gets the number of elements on the stack.
-
-        Returns:
-            int: The number of elements on the stack.
-        """
-        length = len(self.__stack)
-        return length
-
-
-

For more examples, see Example Google Style Python Docstrings.

-
-
-
    -
  1. -

    https://realpython.com/lessons/pros-and-cons-type-hints/ ↩

    -
    2. -
-
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/python/start/index.html b/pr-450/reference/python/start/index.html deleted file mode 100644 index 74591724d..000000000 --- a/pr-450/reference/python/start/index.html +++ /dev/null @@ -1,2397 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Getting Started - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Getting Started

-

We use Python 3 to write the majority of our software at UBC Sailbot. Pathfinding and Controls mainly use Python 3, -so it is critical that you are familiar with the language if you are on one of these sub-teams.

-

Python tutorials

-

We understand that not everyone who joins Sailbot has Python in their toolkit, nor do we expect it either! Whether you -are learning Python for the first time or you just want to brush up, we have provided some resources below. You may not -learn absolutely everything from the resources below, but it is a good starting point. You will mostly learn through doing, -as you would with most technical skills!

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ResourceDescription
The Python TutorialThe official python tutorial. Good if you have some time on your hands and you are a completionist. Sections 1 - 5 and 9 are the most relevant.
w3schools TutorialGood if you want a more brief introduction to Python. It breaks down a lot of concepts into sections. Everything up to Python Classes/Objects is relevant.
YouTube TutorialIf you like video tutorials, then we recommend this tutorial. This video is about 5 hours long, but it pretty much covers everything that you'll need to know for Python and there are some hands on projects.
Shorter YouTube TutorialA shorter alternative YouTube tutorial condensed into 1 hour. It covers less material but still covers many of the essentials.
CodingBat PracticeGood resource to put your Python skills to practice on some simple coding problems. Note that this resource does not teach you python.
-

Feel free to add other resources other than the ones listed above if you find any that you like!

- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/python/virtual-environments/index.html b/pr-450/reference/python/virtual-environments/index.html deleted file mode 100644 index 750ad8fd3..000000000 --- a/pr-450/reference/python/virtual-environments/index.html +++ /dev/null @@ -1,2804 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Virtual Environments - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Virtual Environments

-

The Python virtual environment is a tool for dependency management and project isolation. They solve many -common issues, including:

-
    -
  • -

    Dependency Resolution: A project might want a package with version A while another project might want -a package with version B. With a virtual environment, you can separate which packages that you want to use -for a given project.

    -
    • -
  • -

    Project Isolation: The environment for your project is self-contained and reproducible by capturing all -dependencies in a configuration file.

    -
    • -
  • -

    Housekeeping: Virtual environments allow you to keep your global workspace tidy.

    -
    • -
-

There are two main methods of creating virtual environments: virtualenv -and Anaconda. Each have their own benefits and drawbacks. Here are some differences -between the two:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
VirtualenvAnaconda
Environment files are local.Environment files are available globally.
Must activate environment by giving the path.Can activate the environment without knowing the path, but only the name.
Can only use pip to install packages.Can either use pip or built-in conda package manager.
Installation is very simple.Installation takes more effort.
Can only install python packages.In addition to packages, you can download many data science tools.
-

We recommend virtualenv over Anaconda because of its simplicity. However, feel free to appeal to your preferences.

-

Installation

-
-
-
-

If you already have python and the pip package manager installed, just execute the following:

-
Using pip to install virtualenv
pip install virtualenv
-
-
-
-

Go to the official Anaconda website and follow the installation -instructions for your operating system.

-
-
-
-

Using virtual environments

-

The name of a virtual environment is configurable. For the purposes of this site, we will use env as the environment -name unless specified otherwise.

-

Creating a virtual environment

-
-
-
-

Since virtualenv creates the environment directory in a specific location, make sure that you -are in the located in the project that you want to work on.

-
Create virtual environment with virtualenv
# Go to desired location
-cd <PATH TO DIRECTORY>
-
-# Create the environment with the name env
-python3 -m venv env
-
-

Verify that your environment is created by examining your current directory and look for the directory -that matches the name of your virtual environment.

-
-
-

Since the environment will be available globally, there is no need to go to a specific location to create -it.

-
Create virtual environment with Anaconda
# Create environment with name env and python version
-conda env create -n env python=<PYTHON VERSION NUM>
-
-

If you don't specify a python version, the default is the version you used when you downloaded and installed Anaconda. -Verify that your environment is created by executing conda env list.

-
-
-
-

Activating the virtual environment

-

To use the virtual environment, you must activate it.

-
-
-
-
-
-
-
Activation for Windows
env\Scripts\activate
-
-
-
-
Activation for macOS
source env/bin/activate
-
-
-
-
Activation for Linux
source env/bin/activate
-
-
-
-
-
-
-
Activation for Anaconda
conda activate env
-
-
-
-
-

After activating your virtual environment, you might see (env) on your terminal before or after -your current line. Now you are in your virtual environment!

-

Installing dependencies

-

Any dependencies that you install while your virtual environment is activated are only available in your virtual -environment. If you deactivate your environment and try to use those dependencies, you will find that you will get -errors because they will not be found unless you install those dependencies in the other environment!

-
-
-
-

Use the pip package manager to install python dependencies. Before installing any Python dependencies, it is good -practice to upgrade pip:

-
Upgrade pip
pip install --upgrade pip
-
-

Now, install any Python dependencies pip:

-
Install dependency with pip
pip install <PACKAGE>
-
-
-
-
-
-
-

Use the pip package manager to install python dependencies.

-
Install dependency with pip
# Install pip using conda
-conda install pip
-
-# Install python packages using pip
-pip install <PACKAGE>
-
-
-
-

Use the built-in conda package manager to install python dependencies.

-
Install dependency with conda
conda install -c <CHANNEL> <PACKAGE>
-
-

Sometimes, installing a package like this simply won't work because you are not installing -from the correct channel. -You usually will have to google the command to use in order to install your package correctly because -it usually comes from a specific channel that you don't know about. Some common channels to try are:

-
    -
  • conda-forge
    • -
  • anaconda
    • -
  • bioconda
    • -
  • r
    • -
-
-
-
-
-
-
-

Deactivating the virtual environment

-

When you are finished using your virtual environment, you will need to deactivate it.

-
-
-
-
Deactivate virtualenv environment
deactivate
-
-
-
-
Deactivate anaconda environment
conda deactivate
-
-
-
-
-

Reproducing your virtual environment

-

When you want to share your code with others, it is important for others to be able to reproduce the environment -that you worked in. We discuss two topics in this section: exporting your environment and reproducing the environment.

-

Exporting your virtual environment

-

In order to reproduce your virtual environment, you need to export some information about your environment. -Be sure to follow the instructions below while your environment is activated.

-
-
-
-

You will create a requirements.txt file, which essentially lists all of your python dependencies in one -file:

-
Creating requirements file
pip freeze > requirements.txt
-
-

The pip freeze command prints all of your pip dependencies, and > requirements.txt redirects the output -to a text file.

-
-
-

Anaconda uses configuration files to recreate an environment.

-
-
-
-

Execute the following command to create a file called environment.yml:

-
Create config file
conda env export > environment.yml
-
-

Then, open the environment.yml file and delete the line with prefix:.

-
-
-

Execute the following command to create a file called environment.yml:

-
Create config file
conda env export | grep -v "^prefix: " > environment.yml
-
-
-
-

Execute the following command to create a file called environment.yml:

-
Create config file
conda env export | grep -v "^prefix: " > environment.yml
-
-
-
-
-
-
-
-

Reproducing the environment

-

You can reproduce your virtual environment when given the information about it. The steps above tell you how -to extract the information, and now we will use that information to recreate the virtual environment. -Remember to deactivate the current environment before making a new environment.

-
-
-
-

We use the requirements.txt file that we generated earlier to recreate the environment.

-
Recreate virtualenv environment
# Create the new environment
-python -m venv <NEW ENV NAME>
-
-# Activate the environment
-source <NEW ENV NAME>/bin/activate
-
-# Install dependencies
-pip install -r <PATH TO requirements.txt file>
-
-
-
-

We use the environment.yml file that we generated earlier to recreate the environment.

-
Recreate the conda environment
# Create the new environment with the dependencies
-conda env create -f <PATH TO environment.yml> -n <ENV NAME>
-
-
-
-
-

Official references

-

In this section, we summarized what virtual environments are, why they are used, and how to use them. We did not -cover all of the functions of virtual environments, but feel free to consult the official references to learn -about virtual environments more in depth.

- - - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/ros/index.html b/pr-450/reference/ros/index.html deleted file mode 100644 index d7cdc1c14..000000000 --- a/pr-450/reference/ros/index.html +++ /dev/null @@ -1,2564 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Robot Operating System - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Robot Operating System

-

Robot Operating System (ROS) is a set of software libraries and tools for building robot applications.1 -It provides functionality for hardware abstraction, device drivers, communication between processes over -multiple machines, tools for testing and visualization, and much more.2

-

We use ROS because it is open-source, language-agnostic, and built with cross-collaboration in mind. -It enables our sub-teams to work independently on well-defined components of our software system -without having to worry about the hardware it runs on or the implementation of other components.

-

The official ROS 2 documentation contains everything you need -to get started using ROS. From it we have hand-picked the resources that are most relevant to our current and expected -future usage of ROS assuming that you use our preconfigured workspace. -To run our software on your device without our workspace, you would have to install ROS -and the dependencies that are in our Docker images -yourself.

-

Tutorial

- -
- -
- - -

Workspace Configuration

-

To get our workspace configuration running on your computer:

-
    -
  1. Set it up by following the setup instructions
    2. -
  2. Uncomment the ROS 2 tutorials section in .devcontainer/Dockerfile, - then run the "Dev Containers: Rebuild Container" VS Code command, to install the tutorials' dependencies
    3. -
  3. Clone the repositories used in the tutuorials: ros_tutorials - (humble branch), py_pubsub_ex, and cpp_pubsub_ex, - then run the setup VS Code task to install their dependencies
    4. -
-

Our workspace configuration contains easier methods of accomplishing some of the tutorial steps, or eliminates the need -for them altogether.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Tutorial stepSailbot Workspace configuration
Install a packageAll packages used in the tutorials are already installed (step 2 above)
Clone a sample repo (ros_tutorials)ros_tutorials is already cloned (step 3 above)
Resolve dependenciesRun the "install dependencies" VS Code task
Build the workspaceRun the "Build" VS Code task, AKA Ctrl+Shift+B
Source the overlayRun the srcnew terminal command
Create a package with a nodeRun the "new ament_(python|cmake) package with a node" VS Code task
-

Tutorials

-

We encourage all software members to work through the ROS tutorials -that are listed below in order. For tutorials that have both C++ and Python versions, -NET members should do the C++ version while CTRL and PATH members should do the Python version.

-
    -
  • Beginner: CLI tools
      -
    • Introducing turtlesim and rqt
      • -
    • Understanding nodes
      • -
    • Understanding topics
      • -
    • Understanding services
      • -
    • Understanding parameters
      • -
    • Understanding actions
      • -
    • Using rqt_console to view logs
      • -
    • Recording and playing back data
      • -
    -
    • -
  • Beginner: Client libraries
      -
    • Creating a workspace
      • -
    • Creating a package
      • -
    • Writing a simple publisher and subscriber (C++ or Python)
      • -
    • Writing a simple service and client (C++ or Python)
      • -
    • Using parameters in a class (C++ or Python)
      • -
    • Using ros2doctor to identify issues
      • -
    -
    • -
  • Intermediate
      -
    • Launch
      • -
    • Testing
      • -
    -
    • -
  • Demos
      -
    • Logging
      • -
    -
    • -
-

Concepts

-

We encourage all software members to read the following documentation on key ROS concepts:

-
    -
  • About logging and logger configuration
    • -
  • About ROS 2 interfaces
    • -
  • About parameters in ROS 2
    • -
-

ROS 1 Bridge

-

There are two major versions of ROS, aptly named ROS 1 and ROS 2. Our previous project, Raye, -uses ROS 1 because it was the only version available during her design process. Our new project will -use ROS 2, a complete re-design of the framework that tackles the shortcomings of ROS 1 to bring it up -to industry needs and standards.3 If you are curious about the changes made in ROS 2 compared to 1, -this article is a worthwhile read.

-

ROS 2 includes the ROS 1 Bridge, a collection of packages that can be installed alongside ROS 1 to help migrate code -from ROS 1 to ROS 2. As we will be reusing parts of Raye's codebase, it is essential to know how to use these packages. -Until we are completely done with Raye, our preconfigured workspace will have ROS 1, ROS 1 Bridge, and ROS 2 installed.

-

We encourage all software members work through the ROS 1 Bridge README. -For PATH members, the Migrating launch files from ROS 1 to ROS 2 page -will be a helpful reference when we do so.

-
-
-
    -
  1. -

    https://docs.ros.org/en/humble/index.html ↩

    -
    2. -
  2. -

    https://www.toptal.com/robotics/introduction-to-robot-operating-system ↩

    -
    3. -
  3. -

    https://ubuntu.com/robotics/what-is-ros ↩

    -
    4. -
-
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/sailing/ais_terms/index.html b/pr-450/reference/sailing/ais_terms/index.html deleted file mode 100644 index 4e7dcfe7a..000000000 --- a/pr-450/reference/sailing/ais_terms/index.html +++ /dev/null @@ -1,2441 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - AIS Terms - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

AIS Terms

-

This section explains the most unfamiliar fields that we receive from the AIS.

-

MMSI a.k.a ID

-

A 9-digit, unique identification number for the ship.

-

COG: Course over Ground

-

The direction the boat is travelling, relative to the sea floor. This is the direction of the rate of change -of the Track Made Good.

-

This is measured with the navigational angle convention, where 0° is towards the North, and angles increase in the -clockwise direction. If we make the slight simplification of neglecting the effect of the wind, then

-
    -
  • If the boatspeed is positive and there is no current, the boat's Course over Ground will be the same as the Heading.
    • -
  • If the boatspeed is zero and there is positive current, the boat's Course over Ground will be the same direction as the -current is flowing.
    • -
-

SOG: Speed over Ground

-

The speed the boat is travelling at, relative to the sea floor. This is the magnitude of the rate of change -of the Track Made Good.

-

\(\begin{align*} -\text{SoG} &= \left|\frac{d}{dt} \overrightarrow{(\text{Track Made Good})} \right|\\ -\end{align*}\)

-

If we make the slight simplification of neglecting the effect of the wind, then

-
    -
  • If the boatspeed is positive and there is no current, the boat's Speed over Ground will be the same as the speed of water -hitting your hand, if you were sitting on the boat and put your hand in the water.
    • -
  • If the boatspeed is zero and there is positive current, the boat's Speed over Ground will be the same speed as the -current.
    • -
-

RoT: Rate of Turn

-

The angular velocity of the boat (how fast it's turning), measured in degrees per minute.

- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/sailing/boat_parts/index.html b/pr-450/reference/sailing/boat_parts/index.html deleted file mode 100644 index 0bca304aa..000000000 --- a/pr-450/reference/sailing/boat_parts/index.html +++ /dev/null @@ -1,2538 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Parts of a Sailboat - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Parts of a Sailboat

-

This page names some important parts of a sailboat, and explains what the part is for. -Read the descriptions of the parts below, and refer to the image to see where the part fits in.

-

image

-

Hull

-

The Hull is the "boat" part of the boat, which displaces water to create buoyancy. The following parts of the boat -are attached to the hull:

-
    -
  • Keel: The keel has a large mass on the end, which keeps the sailboat upright. The fin-like shape of the -keel provides lateral resistance to prevent the boat from slipping sideways through the water.
    • -
  • Rudder: Raye has two rudders for redundancy. The rudders can angle side to side to steer the boat. -To steer the boat effectively, the rudders need enough water flowing over them to create a pressure difference when they -angle sideways. Controls sends commands to the rudder to steer the boat.
    • -
-

It is also helpful to know the names of the following "regions" of the hull:

-
    -
  • Bow: The front of the boat.
    • -
  • Stern: The back of the boat.
      -
    • Aft means "backwards towards the stern".
      • -
    -
    • -
  • Starboard: The side of the boat which is on the right, for someone standing on the boat facing the bow.
    • -
  • Port: The side of the boat which is on the left, for someone standing on the boat facing the bow.
      -
    • To remember which is which between starboard and port, remember that "port" and "left" both have 4 letters.
      • -
    -
    • -
-

The image below shows a birds-eye view of the outline of a hull of a sailboat, -where the "regions" of the hull are labeled.

-

image

-

Jib

-

The Jib is the sail located near the bow, and is the smaller of the two sails.

-
    -
  • Jib Sheet: In general, sheets are ropes that pull a sail in to the boat, and the jib sheet does this for the jib. -On Raye, the jib sheet connects to the back bottom corner of the jib, through a pulley near the bottom of the mast to -the Jib Winch. Most sailboats have two jib sheets, one on either side, but Raye is designed differently for autonomy.
    • -
  • The Jib Winch is a motor-driven device that tightens or pulls in the jib by pulling on the jib sheet. -Controls sends commands to the winches.
    • -
  • The jib halyard: In general, a halyard is a rope that pulls a sail up. The jib halyard pulls up the jib. -It connects to the top of the jib, runs through a pulley near the top of the mast, and is tied off -near the bottom of the mast.
    • -
-

Mast

-

The Mast is the long vertical pole which connects to hull. It holds up the sails and some instruments.

-

The following instruments are at the top of the mast:

-
    -
  • One of the 3 Wind Sensors. The top of the mast is a good location to measure undisturbed wind. -Pathfinding and Controls both use data from the wind sensors.
    • -
  • The AIS antenna. AIS ("Autonomous Identification System") is a system by which ships -communicate their location, speed, and other information to surrounding ships via radio signals. -Pathfinding uses AIS data to avoid other ships.
    • -
-

The mast is held upright by three lines:

-
    -
  • The forestay connects the mast from the top of the jib to the bow, and runs parallel to the front edge of the jib.
    • -
  • The two shrouds connect the mast from the top of the jib to the outside edges of the hull slightly aft of the mast. -There is one shroud on the startboard side and one on the port side.
    • -
-

Main Sail

-

The Main Sail is the larger of the two sails, and is located aft of the mast. -Most of the boat's propulsion comes from the main sail.

-
    -
  • The Boom is the horizontal pole that holds the bottom corner of the main sail out from the mast.
    • -
  • Main Sheet is the rope that pulls the main sail in towards the center of the boat. It connects from the back end of -the boom, through a pulley on the stern, to the Main Winch.
    • -
  • The Main Winch is a motor-driven device that pulls in the main sail by pulling on the main sheet. -Controls sends commands to the main winch.
    • -
  • The main halyard is the line used to hoist the main sail.
    • -
-

Conclusion

-

Hopefully this section helped you gain familiarity with some common sailing terms. -It likely feels like this section contains a lot of new information. It's unrealistic to remember it all perfectly, -but make an effort to remember the terms which are Bolded and Italicized.

-

Keywords on this Page

-
    -
  • Hull
    • -
  • Keel
    • -
  • Rudder
    • -
  • Bow
    • -
  • Stern
    • -
  • Starboard
    • -
  • Port
    • -
  • Jib
    • -
  • Jib winch
    • -
  • Mast
    • -
  • Wind Sensor
    • -
  • AIS Antenna
    • -
  • Main Sail
    • -
  • Main Winch
    • -
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/sailing/miscellaneous/index.html b/pr-450/reference/sailing/miscellaneous/index.html deleted file mode 100644 index cebd80365..000000000 --- a/pr-450/reference/sailing/miscellaneous/index.html +++ /dev/null @@ -1,2620 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Miscellaneous - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Miscellaneous Sailing Knowledge

-

This section covers some other useful information.

-

Wind Direction Convention

-

Generally speaking, there are two ways to use an angle to describe the wind direction.

-
    -
  1. The angle tells you which way the wind is blowing towards. For example, 0° means the wind is blowing from North -to South.
    2. -
  2. The angle tells you which way the wind is coming from. For example, 0° means the wind is blowing from South to North.
    3. -
-

In sailing, we normally talk about "where the wind is coming from". Somehow this ends up being more intuitive when -talking about maneuvers or sail angle adjustments.

-

However, when describing the wind as a vector, it can make more sense for the vector to represent the actual -speed and direction the air is flowing. Make sure to document which convention you are using in your work when -its applicable, and don't be afraid to ask someone to clarify which convention they are using in their work.

- -

Heading

-

In navigation generally (outside of Sailbot), the Heading is the direction the bow of the boat is pointing -towards. Headings are typically (but not always at Sailbot) measured relative to true North in the clockwise direction.

-

Bearing

-

A Bearing is used to describe one point in relation to another: the Bearing of point "A" from point "B" -is the direction you would would look towards if you wanted to see point "A" while standing at point "B". A Range -is the distance between points "A" and "B", so that a Bearing and Range together can locate point "A" relative to point -"B" in polar co-ordinates. There are two main ways of measuring bearings:

-
    -
  • A True Bearing is a bearing where the angle convention is as follows: 0° is towards the North, -angles increase in the clockwise direction, and angles are typically bounded within [0°, 360°)]
    • -
  • A Relative Bearing is a bearing where the angle convention is as follows: 0° is straight forwards relative to the -boat, and angle measurements increase in the clockwise direction. Angles may be bounded in [-180°, 180°) or [0°, 360°)
    • -
-

In the example below, the boat "B" has a Heading (H) of 30°. The True Bearing (\(B_t\)) of the Lighthouse "A" -from the boat is 90°. The Relative Bearing (\(B_r\)) of the lighthouse from the boat is 60°.

-

image

-

Track Made Good

-

Boats do not necessarily travel in the same direction as their Heading, due to the effects of ocean current and -wind. The path the boat has traveled relative to the sea floor is called the Track Made Good. This is the -same as if you measured motion compared to land or with a GPS.

-

image

-

Heading and Bearing in Raye Project

-

In Sailbot's Raye project, Heading and Bearing are used to refer to different conventions for describing -which way the boat is pointing. -The following 3 pieces of information are needed to unambiguously define an angle measuring convention:

-
    -
  • What does 0° mean? If 0° is North, is it towards the North or away from the North?
    • -
  • Do the angle measurements increase in the clockwise or counter-clockwise direction?
    • -
  • What range should the angles be bounded to? This part is often unimportant if the angles are only used in -trigonometry functions.
    • -
-

Some common examples of angle measuring conventions which we use are:

-
    -
  • 0° means towards the East, angles increase in the counter-clockwise direction, and angles are bounded in -[-180°, 180°). This is effectively the main angle convention used in most math courses.
    • -
  • 0° means towards the North, angles increase in the clockwise direction, and angles are bounded in [0°, 360°). This -angle convention is more commonly used by navigators.
    • -
-

The specific angle conventions which we call Heading and Bearing can be ambiguous, and may be subject to change, -so they are deliberately omitted here. Refer to the applicable source code to determine what the angle conventions are.

-

True, Apparent, and Boat Wind

-
    -
  • True Wind is the wind vector (speed and direction) which you would measure while standing on land (or motionless at -sea with unchanging GPS co-ordinates). In sailbot code, this may be referred to as Global Wind. When people -refer to "the wind", they normally mean True Wind.
    • -
  • Boat Wind is the wind vector which you would measure while standing on a moving boat when the True Wind speed is 0. -This means that boat wind always blows straight onto the bow of the boat, and the magnitude of the boat wind is equal to -the speed of the boat.
    • -
  • Apparent Wind is the vector sum of the True Wind and the Boat Wind. This is the wind that you would measure while -standing on a moving boat more generally, even if there is non-zero wind. The apparent wind is also what our wind -sensors measure, and what our sails feel. In Sailbot code, Apparent Wind may be referred to as Measured Wind.
    • -
-

In the example below, suppose the wind is blowing from the North at 4 m/s, and suppose the boat is moving towards -the East at 3 m/s.

-
    -
  • The True Wind everywhere is blowing at 4 m/s from the North
    • -
  • The Boat Wind onboard the boat is blowing from the East at 3 m/s
    • -
  • The Apparent Wind onboard the boat is has a magnitude of \(\sqrt{3^2 + 4^2} = 5 \text{ m/s}\), -and is coming from a true bearing of \(\arctan{(\frac{3}{4})} = 36.9°\).
    • -
-

image

-

Tack

-

In the Types of Turn -page, we discussed how a Tack is a type of turn. Weirdly, the word "tack" actually has two -more distinct meanings in sailing. The word "Tack" can refer to:

-
    -
  • the type of turn, as covered before.
    • -
  • Starboard Tack vs Port Tack: The tack is basically the side of the boat which is further upwind. More thoroughly, -the tack is the opposite side to the sail. This means that boats change tack when the sail switches sides.
      -
    • In the diagram below, -the 3 boats on the left of the diagram are on Starboard Tack, and the 3 boats on the right side are on Port Tack.
      • -
    • The tack of a boat in Irons is undefined.
      • -
    • The boat in the diagram on a run is on Port Tack. If the boat continued straight but the sail switched sides into -the position shown by the dashed line, the boat would be on Starboard Tack.
      • -
    -
    • -
-

image

-
    -
  • Finally, the Tack can refer to particular region of the main sail. This is not important for software members.
    • -
-

Keywords on this Page

-
    -
  • Heading
    • -
  • Bearing
    • -
  • Track Made Good
    • -
  • Global Wind (aka True Wind)
    • -
  • Measured Wind (aka Apparent Wind)
    • -
  • Tack
    • -
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/sailing/overview/index.html b/pr-450/reference/sailing/overview/index.html deleted file mode 100644 index 945526b0e..000000000 --- a/pr-450/reference/sailing/overview/index.html +++ /dev/null @@ -1,2372 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Overview - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Sailing Knowledge Section Overview

-

In order to make high-quality contributions to Sailbot's Software teams, it is extremely helpful to have some -understanding of sailing. This section introduces important parts of a sailboat, explains the 4 types of turns, -discusses upwind and downwind sailing, and covers some other helpful knowledge.

-

In this section, terms which are Bolded and Italicized are the most important terms to know. -These terms are listed at the bottom of each page. -Terms that are only Italicized are other helpful sailing terms. -Words that are bolded are meant to be emphasized, but are not necessarily considered important vocabulary.

-

Tutorial

- -
- -
- - - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/sailing/points_of_sail/index.html b/pr-450/reference/sailing/points_of_sail/index.html deleted file mode 100644 index 38f5b54f5..000000000 --- a/pr-450/reference/sailing/points_of_sail/index.html +++ /dev/null @@ -1,2448 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Points of Sail - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Points of Sail

-

In sailing, we sometimes talk about different angles that we can sail on with respect to the wind. -Ranges of angles which are close together have special names. These ranges are called points of sail. -The discussion below coveres the most important points of sail for software members to understand.

-

Notice how for higher points of sail (points of sail closer to straight into the wind), the sail is pulled tightly -in to the boat. If the boat is on a lower point of sail, the sails should be let further out of the boat. For any -point of sail, there is an optimum angle that the sail should be adjusted to. If the sails are adjusted too far in -or too far out, the boat will not go as fast as it could if the sails were adjusted correctly.

-

image

-

Irons

-

The range of angles where the boat is roughly pointing straight into the wind are called Irons, or the -No-Go Zone. -If the boat is pointing in these directions, the sails will be flapping regardless of how the sheets are adjusted. -When the sails are flapping, they are not catching the wind in a way that can propell the boat forwards. -When the boat looses propulsion, water stops flowing over the rudder, and the boat loses steering. -This is why we want our sailbots to avoid being stuck in irons.

-

Upwind Sailing

-

If we want to sail to a destination that is not on too high or low of an angle upwind or downwind from our starting -position, we can just point our boat in that direction, adjust our sails, and go there.

-

However, sometimes we want to sail to a destination that is straight upwind of our starting position. -To get there, we will need to do upwind sailing. -Since we can't point our boat directly into the wind, we need to sail on an angle on the edge of irons. -We will need to tack back and forth every now and then if we want to go directly upwind. -The point of sail on the edge of Irons is called Close Hauled.

-

Downwind Sailing

-

Raye also avoids sailing straight downwind. This means that to reach a goal downwind of the starting position, -we need to gybe back and forth in a zig-zag pattern. The point of sail straight -downwind is called a run, and the next point of sail higher than a run is called a broad reach.

-

image

-

Keywords on this Page

-
    -
  • Irons (aka No-Go Zone)
    • -
  • Upwind Sailing
    • -
  • Close Hauled
    • -
  • Downwind Sailing
    • -
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/reference/sailing/turning/index.html b/pr-450/reference/sailing/turning/index.html deleted file mode 100644 index b01dfea97..000000000 --- a/pr-450/reference/sailing/turning/index.html +++ /dev/null @@ -1,2550 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - Types of Turns - UBCSailbot Software Team Docs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
- - - - - - - - -
- - - - - - - -
- -
- - - - -
-
- - - -
-
-
- - - - - - - -
-
-
- - - -
-
-
- - - -
-
-
- - - -
-
- - - - - - - - - - - - - - - - - - - - -

Types of Turns

-

In sailing, there are 4 distinct types of turns. Read the descriptions below, and observe how they fit into the diagrams.

-

Note that any of these types of turn can be done in either the clockwise or counter-clockwise directions.

-

Classifying Types Of Turns Summary

-

The following flowchart summarizes how to distinguish between different types of turns. Note:

-
    -
  • to point higher means to steer your boat to point in a direction closer to straight into the wind
    • -
  • to point lower means to steer your boat to point in a direction closer towards to straight downwind
    • -
-
graph LR
-    B[Classify a Turn] --> C{Does the sail change<br/>sides during the turn?};
-    C --> |Yes| E{Which end of<br/>the boat is upwind<br/>during the turn?};
-    C --> |No| D{Does the<br/>boat point higher<br/>or lower at the end<br/>of the turn?};
-    D --> |Higher| F[Heading Up];
-    D --> |Lower| G[Bearing Off];
-    E --> |Bow| H[Tack];
-    E --> |Stern| I[Gybe];
-

The diagrams in this section show outlines of the hull of a boat and its main sail going through turns. -As is common in these types of diagrams, assume that the wind is blowing down from the top of the screen unless -there is an arrow that indicates otherwise.

-

image

-

Heading Up

-

When the boat makes any turn as follows, it is called Heading Up:

-
    -
  • At the end of the turn, the boat is pointing higher.
    • -
  • Throughout the turn, the sails stay on the same side of the boat. In other words, the sails do not cross between -the starboard and port sides.
    • -
-

Unlike some of the other turns listed here, heading up can be a large turn or a small course adjustment of just a few -degrees.

-

The image below shows a boat heading up. Notice how the sail stays on the starboard side of the boat.

-

image

-

Bearing Off

-

When the boat makes any turn as follows, it is called Bearing Off:

-
    -
  • At the end of the turn, the boat is pointing lower.
    • -
  • Throughout the turn, the sails stays on the same side of the boat (port or starboard).
    • -
-

Like heading up, bearing off can be a small course adjustment.

-

image

-

Tacking

-

When the boat makes any turn as follows, it is called a Tack or Tacking:

-
    -
  • The sails change sides.
    • -
  • Through the turn, the wind hits the bow of the boat before the stern. You can also say that the bow is upwind or -windward of the stern.
    • -
-

Notice how at some point throughout this turn, the boat will be pointing straight into the wind. -While the boat points nearly straight into the wind, the sails don't generate any forward propulsion. -This means that a tack must be a large (at least ~90°) turn all at once, so that the boat's momentum carries it through -the range of angles where it does not get propulsion.

-

image

-

Gybing

-

When the boat makes any turn as follows, it is called a Gybe or Gybing.

-
    -
  • The sails change sides.
    • -
  • Through the turn, the wind hits the stern of the boat before the bow. You can also say that the bow of the boat is -downwind or leeward of the stern.
    • -
-

When sailing on most angles relative to the wind, the sail is always blown to the downwind side of the boat. -However, sailing nearly straight downwind, both sides of the boat are equally "downwind" relative to eachother. -This means that the sail can be on either side of the boat.

-

The sail propells the boat throughout a gybe, so it is possible to conduct the turn more gradually than a tack. -However, because the sail can be on either side, the sails can switch sides in an uncontrolled way as the boat moves in -the waves. For this reason, Raye avoids sailing on angles close to straight downwind, and gybes by doing a quick ~60° -turn.

-

Note that "gybe" is the spelling used in Canadian and British english, whereas in American english it is spelled "Jibe"

-

image

-

Combinations of Turns

-

Of course, it is possible to do two or more of these types of turns in one continuous motion. -What two types of turns does the boat do in the image below?

-

image

-

Answer: In the turn shown by the first arrow, the sail stays on the port side of the boat while it steers to point further -downwind. This means that the first part of the maneuver is bearing off. In the next part of the maneuver, the sail -changes sides and the stern of the boat is upwind of the bow. This part of the maneuver is a gybe.

-

Keywords on this Page

-
    -
  • Higher (in relation to pointing)
    • -
  • Lower (in relation to pointing)
    • -
  • Heading Up
    • -
  • Bearing Off
    • -
  • Tack
    • -
  • Gybe (aka Jibe)
    • -
- - - - - - - - - - - - - - - - -
-
- - - - - -
- - - -
- - - -
-
-
-
- - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/pr-450/requirements.txt b/pr-450/requirements.txt deleted file mode 100644 index 1b84d29e6..000000000 --- a/pr-450/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -mike==2.* diff --git a/pr-450/search/search_index.json b/pr-450/search/search_index.json deleted file mode 100644 index 9c5f62563..000000000 --- a/pr-450/search/search_index.json +++ /dev/null @@ -1 +0,0 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-,:!=\\[\\]()\"/]+|(?!\\b)(?=[A-Z][a-z])|\\.(?!\\d)|&[lg]t;","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"UBCSailbot Software Team Docs","text":"

Welcome to the UBC Sailbot software team docs

Looking to get started with running the Sailbot codebase? Start by setting up the Sailbot Workspace:

Getting Started

"},{"location":"#what-information-is-on-this-website","title":"What information is on this website?","text":"

Information on our current project is contained on this website. In particular, information on each of our major software projects are provided in detail.

Current Project Overview

References to the software tools that we use are also provided on this website. This includes basic information on these tools, how we use these tools on UBC Sailbot, and external links to helpful references and tutorials.

Software Team References

"},{"location":"#who-is-this-website-for","title":"Who is this website for?","text":"

The docs site is primarily for the members on the UBC Sailbot software team. However, curious members of the public and/or those who are interested in contributing to our open source software would also benefit from this site.

"},{"location":"#prospective-members","title":"Prospective Members","text":"

Are you a member of the UBC community? Are you interested in what we do at UBC Sailbot? We are always looking for motivated students to help us tackle the challenge of autonomous sailing. Learn more below!

Software Team Posting

Apply to join UBC Sailbot

"},{"location":"about_us/","title":"About Us","text":"

UBC Sailbot is an engineering design team at The University of British Columbia that designs, constructs, and tests autonomous sailboats. We have 3 technical sub-teams: Mechanical, Electrical, and Software.

This repository, sailbot_workspace, contains all the code, infrastructure, and documentation for the project we are currently working on, Polaris.

To learn more about what the UBC Sailbot Software Team does, read our Team Posting. If you are a UBC student interested in joining, you can apply here.

"},{"location":"current/overview/","title":"Current Project Overview","text":"

Our current project, Polaris, is an autonomous research vessel capable of collecting oceanic and atmospheric data. With our expertise in autonomous sailing, the goal is to monitor the health of our oceans while collaborating with stakeholders and researchers involved in climate science and oceanography.

The software team is responsible for designing, implementing, and testing the software system of our autonomous sailboats. We work on both low-level and high-level integration, from interfacing with sensors to planning sea routes with pathfinding algorithms.

"},{"location":"current/overview/#dataflow","title":"Dataflow","text":"

The software architecture for our next autonomous sailboat is split across two computers: the on board computer on board and the remote server off board. The following paragraphs will follow the flow of data between the software components (bolded) on each computer.

On the remote server, global pathfinding uses the A* pathfinding algorithm to create a sailing path, a list of global waypoints from the current position to destination. Global sailing paths are sent via the Remote Transceiver to the Local Transceiver on the on board computer.

On the on board computer, the CAN Transceiver receives GPS and wind data from their respective sensors. This raw data is filtered before being used in the other software components. Local Pathfinding uses GPS and wind data, as well as the global path and AIS data from the AIS Receiver, to create a local path, a list of local waypoints from the current position to the next global waypoint. The Controller uses wind data and the relative bearing to the local path to adjust the rudder and sails accordingly. The state of the boat and research data we collect is sent via the Local Transceiver to the Remote Transceiver on the remote server.

Back on the remote server, the Website presents the boat state and research data for monitoring and analysis purposes. The Remote Transceiver additionally includes manual overrides such as resetting the boat state and modifying the global path.

As for the communication mediums, the computers communicate via satellite, and components on the on board computer communicate through the Robot Operating System framework, or ROS for short.

For software development purposes, all software components will be able to run and communicate with each other locally. To accomplish this, we will:

  1. Create a development environment that has all software component dependencies: Sailbot Workspace.
  2. Develop accurate simulations of the environment and hardware: Simulator, Mock AIS, Mock Global Pathfinding.
  3. Add configuration options to select between real and simulated hardware as well as running remote server components remotely or locally.
"},{"location":"current/overview/#diagrams","title":"Diagrams","text":"

In these diagrams, the bubbles represent components of our software system, and the direction of arrows connecting the bubbles represent the flow of data between them. The color of the bubbles denote the sub-team leading their development:

  • Purple: Controls
  • Green: Network Systems
  • Blue: Pathfinding
  • Red: Website
  • White: Not a part of the Software Team's codebase

Components that are used in both the production and development environments are darker, while ones that are only used in one are lighter.

Interacting with the diagram

  • To switch between the production and development environment diagrams, hover over the image to make the toolbar visible and navigate with the arrows on the left side
"},{"location":"current/boat_simulator/overview/","title":"Overview","text":"

Source code

The source code for Boat Simulator can be found in src/boat_simulator. Its README has been copied below.

"},{"location":"current/boat_simulator/overview/#ubc-sailbot-boat-simulator","title":"UBC Sailbot Boat Simulator","text":"

UBC Sailbot's boat simulator for the new project. This repository contains a ROS package boat_simulator. This README contains only setup and run instructions. Further information on the boat simulator can be found on the software team's docs website.

"},{"location":"current/boat_simulator/overview/#setup","title":"Setup","text":"

The boat simulator is meant to be ran inside the Sailbot Workspace development environment. Follow the setup instructions for the Sailbot Workspace here to get started and build all the necessary ROS packages.

"},{"location":"current/boat_simulator/overview/#run","title":"Run","text":"

The launch/ folder contains a ROS 2 launch file responsible for starting up the boat simulator. To run the boat simulator standalone, execute the launch file after building the boat_simulator package:

ros2 launch boat_simulator main_launch.py [OPTIONS]...\n

To see a list of options for simulator configuration, add the -s flag at the end of the above command.

"},{"location":"current/boat_simulator/overview/#test","title":"Test","text":"

Run the test task in the Sailbot Workspace. See here on how to run vscode tasks.

"},{"location":"current/controller/overview/","title":"Overview","text":"

Source code

The source code for Controller can be found in src/controller. Its README has been copied below.

"},{"location":"current/controller/overview/#controller","title":"Controller","text":"

UBC Sailbot's controller for the new project. This repository contains a ROS package controller. This README contains only setup and run instructions. Further information on the controller can be found on the software team's docs website.

"},{"location":"current/controller/overview/#setup","title":"Setup","text":"

The controller is meant to be ran inside the Sailbot Workspace development environment. Follow the setup instructions for the Sailbot Workspace here to get started and build all the necessary ROS packages.

"},{"location":"current/controller/overview/#run","title":"Run","text":"

The launch/ folder contains a ROS 2 launch file responsible for starting up the controller. To run the controller standalone, execute the launch file after building the controller package:

ros2 launch controller main_launch.py [OPTIONS]...\n

To see a list of options for configuration, add the -s flag at the end of the above command.

"},{"location":"current/controller/overview/#test","title":"Test","text":"

Run the test task in the Sailbot Workspace. See here on how to run vscode tasks.

"},{"location":"current/custom_interfaces/overview/","title":"Overview","text":"

Source code

The source code for Custom Interfaces can be found in src/custom_interfaces. Its README has been copied below.

"},{"location":"current/custom_interfaces/overview/#custom-interfaces","title":"Custom Interfaces","text":"

UBC Sailbot's custom interfaces ROS package. To add custom_interfaces to another ROS package, follow the instructions here.

The terminology that we use in this document are the following:

  • External Interface: An interface used to communicate data between nodes and ROS packages.
  • Internal Interface: An interface used to standardize conventions across external interfaces. Standards are documented in the .msg or .srv file associated with that interface.
"},{"location":"current/custom_interfaces/overview/#project-wide-interfaces","title":"Project-wide Interfaces","text":"

ROS messages and services used across many ROS packages in the project.

"},{"location":"current/custom_interfaces/overview/#project-wide-external-interfaces","title":"Project-wide External Interfaces","text":""},{"location":"current/custom_interfaces/overview/#project-wide-internal-interfaces","title":"Project-wide Internal Interfaces","text":"Interface Used In HelperAISShip AISShips HelperBattery Batteries HelperDimension HelperAISShip HelperGenericSensor GenericSensors HelperHeading DesiredHeading, GPS, HelperAISShip HelperLatLon GPS, HelperAISShip, Path HelperROT HelperAISShip HelperSpeed GPS, HelperAISShip, WindSensor"},{"location":"current/custom_interfaces/overview/#boat-simulator-interfaces","title":"Boat Simulator Interfaces","text":"

ROS messages and services used in our boat simulator.

"},{"location":"current/custom_interfaces/overview/#boat-simulator-external-interfaces","title":"Boat Simulator External Interfaces","text":"Topic Type Publisher Subscriber(s) mock_kinematics SimWorldState Simulator Physics Engine Simulator Visualizer"},{"location":"current/custom_interfaces/overview/#boat-simulator-actions","title":"Boat Simulator Actions","text":"Action Client Node Server Node SimRudderActuation Simulator Physics Engine Simulator Low Level Controller SimSailTrimTabActuation Simulator Physics Engine Simulator Low Level Controller"},{"location":"current/custom_interfaces/overview/#resources","title":"Resources","text":""},{"location":"current/custom_interfaces/overview/#common-interfaces","title":"Common Interfaces","text":"

The ROS2 common_interfaces repository defines a set of packages which contain common interface files. Since we are using the Humble version of ROS2, see the humble branch. These interfaces can be used in this repository or as a reference for ideas and best practices.

Package Possible Usage diagnostic_msgs Could be used for website sensors geometry_msgs Simulator, Local Pathfinding sensor_msgs Reference for CAN Transceiver std_msgs Reference std_srvs Reference visualization_msgs Reference

For more detail on the usefulness of each package, see this issue comment. If you are interested in creating your own custom message or service, see the ROS Humble documentation.

"},{"location":"current/local_pathfinding/overview/","title":"Overview","text":"

Source code

The source code for Local Pathfinding can be found in src/local_pathfinding. Its README has been copied below.

"},{"location":"current/local_pathfinding/overview/#local-pathfinding","title":"Local Pathfinding","text":"

UBC Sailbot's local pathfinding ROS package

"},{"location":"current/local_pathfinding/overview/#run","title":"Run","text":"

Using main launch file: ros2 launch local_pathfinding main_launch.py

"},{"location":"current/local_pathfinding/overview/#launch-parameters","title":"Launch Parameters","text":"

Launch arguments are added to the run command in the format <name>:=<value>.

name description value log_level Logging level A severity level (case insensitive)"},{"location":"current/local_pathfinding/overview/#server-files","title":"Server Files","text":"

The server files: get_server.py and post_server.py are basic http server files which are used for testing the global_path module's GET and POST methods.

"},{"location":"current/network_systems/overview/","title":"Overview","text":"

Source code

The source code for Network Systems can be found in src/network_systems. Its README has been copied below.

"},{"location":"current/network_systems/overview/#network-systems","title":"Network Systems","text":"

This repository contains the source code for all of UBC Sailbot's Network Systems programs. It is made to work as part of Sailbot Workspace, and is not meant to be built as an independent project.

"},{"location":"current/network_systems/overview/#setup","title":"Setup","text":"

For comprehensive setup instructions, follow our setup guide.

"},{"location":"current/network_systems/overview/#building","title":"Building","text":"

Option A: With sailbot_workspace open, invoke the VSCode build or debug task.

Option B: Run /workspaces/sailbot_workspace/build.sh

"},{"location":"current/network_systems/overview/#running","title":"Running","text":""},{"location":"current/network_systems/overview/#ros-launch","title":"ROS Launch","text":"

Instructions found here.

For example:

ros2 launch network_systems main_launch.py\n

This is the best option if multiple modules need to be run at once. Launch configurations are found under the config folder. These configurations define which modules to enable/disable and what parameters to use.

"},{"location":"current/network_systems/overview/#ros-run","title":"ROS Run","text":"

If you just want to run a single module, then this is a direct and easy way to do it.

For example:

ros2 run network_systems example --ros-args -p enabled:=true\n
"},{"location":"current/network_systems/overview/#binary","title":"Binary","text":"

Not recommended as you cannot pass ROS parameters, so modules may not work by default. Binaries for each module found under projects can be found under /workspaces/sailbot_workspace/build/network_systems/projects/{module_name}/{module_name}.

For example:

/workspaces/sailbot_workspace/build/network_systems/projects/example/example\n
"},{"location":"current/network_systems/overview/#testing","title":"Testing","text":"

Unit tests specific to Network Systems is done using GoogleTest. Unit tests are defined per module. For example, under projects/example/test/.

"},{"location":"current/network_systems/overview/#run-all-tests","title":"Run All Tests","text":"

Option A: With sailbot_workspace open, invoke the VSCode test task.

Option B: Under the sailbot_workspace directory, run /workspaces/sailbot_workspace/scripts/test.sh

Both options will run all of UBC Sailbot's tests, including those from other projects. More often than not, this is unnecessary.

"},{"location":"current/network_systems/overview/#run-and-debug-specific-tests","title":"Run and Debug Specific Tests","text":"

This is the preferred way to run and debug tests. When you open a test source file like the example's, there will be green arrows next to each TEST_F macro. Clicking a double green arrow runs a test suite, while clicking single green arrow runs one unit test. Right clicking either arrow will open a prompt with a debug test option. When running a test via the debug option, we can set breakpoints and step through our code line by line to resolve issues.

This convenient testing frontend is thank's to the TestMate extension.

Warning: Large failing tests can crash VSCode. If this happens, either lower the size of the tests (ex. reduce the number of iterations) or run the test binary directly.

"},{"location":"current/network_systems/overview/#run-test-binaries","title":"Run Test Binaries","text":"

Test binaries for each module found under projects can be found under /workspaces/sailbot_workspace/build/network_systems/projects/{module_name}/test_{module_name}.

For example:

/workspaces/sailbot_workspace/build/network_systems/projects/example/test_example\n
"},{"location":"current/sailbot_workspace/overview/","title":"Overview","text":"

Source code

The Sailbot Workspace README has been copied below.

"},{"location":"current/sailbot_workspace/overview/#sailbot-workspace","title":"Sailbot Workspace","text":"

This repository will get you set up to develop UBCSailbot's software on VS Code. It is based on athackst's vscode_ros2_workspace.

"},{"location":"current/sailbot_workspace/overview/#features","title":"Features","text":"

An overview of Sailbot Workspace's features can be found below. See our docs site for how to use these features.

"},{"location":"current/sailbot_workspace/overview/#style","title":"Style","text":"

C++ and Python linters and formatters are integrated into Sailbot Workspace:

  • ament_flake8
  • ament_lint_cmake
  • ament_xmllint
  • black
  • clang-tidy
  • isort

The ament linters are configured to be consistent with the ROS style guide.

"},{"location":"current/sailbot_workspace/overview/#dev-container","title":"Dev Container","text":"

Dev Containers enable us to use a Docker container as a fully-featured development environment containing all our configuration and dependencies. Our Dev Container configuration can be found in .devcontainer/.

"},{"location":"current/sailbot_workspace/overview/#multi-root-workspace","title":"Multi-Root Workspace","text":"

Workspaces are VS Code instances that contain one or more folders. Our workspace configuration file can be found at sailbot.code-workspace.

Our software spans many repositories: software team repositories. Multi-root workspaces make it easy to work with multiple repositories at the same time. Our roots are defined in the folders section of our workspace file.

"},{"location":"current/sailbot_workspace/overview/#debugging","title":"Debugging","text":"

Launch configurations have been created to debug our software. They are defined in the launch section of our workspace file.

"},{"location":"current/sailbot_workspace/overview/#tasks","title":"Tasks","text":"

Tasks provide an alternative to memorizing the multitude of CLI commands we use to setup, build, lint, test, and run our software. They are defined in tasks section of our workspace file.

"},{"location":"current/sailbot_workspace/overview/#continuous-integration","title":"Continuous Integration","text":"

Actions were used to build our Docker containers and lint and test our code the same way it is done locally in Sailbot Workspace on GitHub. We use a reusable workflow to create a single source of truth for our tests across all our repositories. Our CI can be found in .github/workflows/.

"},{"location":"current/sailbot_workspace/overview/#customization","title":"Customization","text":"

This repository supports user-specific configuration files. To set this up, see How to use your dotfiles.

"},{"location":"current/sailbot_workspace/overview/#run-rayes-software","title":"Run Raye's Software","text":"

Raye was our previous project. Her software can be run in the raye branch following the instructions in How to run Raye's software. The initial differences between the main and raye branches are summarized in this PR.

"},{"location":"current/sailbot_workspace/overview/#documentation","title":"Documentation","text":"

Further documentation, including setup and run instructions, can be found on our Docs website.

"},{"location":"current/sailbot_workspace/overview/#tutorial","title":"Tutorial","text":"

Disclaimer

This tutorial was done a while ago, so some parts may no longer be relevant. For the most up to date information, consult the docs pages and the software leads.

"},{"location":"current/sailbot_workspace/scripts/","title":"Scripts","text":"

Source code

Our scripts can be found in scripts. Its README has been copied below.

"},{"location":"current/sailbot_workspace/scripts/#scripts","title":"Scripts","text":""},{"location":"current/sailbot_workspace/scripts/#how-to-run","title":"how to run","text":"

All scripts in this directory should be able to be run with ./path/to/script (excluding arguments). For this to work, the script will need to have a shebang and be executable. For more details, see this tutorial.

"},{"location":"current/sailbot_workspace/scripts/#ament-lintsh","title":"ament-lint.sh","text":"

Script to lint source code in all ROS packages.

"},{"location":"current/sailbot_workspace/scripts/#buildsh","title":"build.sh","text":"

Script to build all ROS packages in the Sailbot Workspace.

"},{"location":"current/sailbot_workspace/scripts/#clang-tidysh","title":"clang-tidy.sh","text":"

Script to run Clang-Tidy using ament_clang_tidy.py.

"},{"location":"current/sailbot_workspace/scripts/#run_virtual_iridiumsh","title":"run_virtual_iridium.sh","text":"
./run_virtual_iridium.sh <(optional) webhook server url> <(optional) virtual iridium http server port>\n

Creates a pair of socat sockets $LOCAL_TRANSCEIVER_TEST_PORT and $VIRTUAL_IRIDIUM_PORT and binds the latter to a virtual iridium server running on localhost:8080, which substitutes the Rockblock HTTP server used in deployment. Allows testing of satellite code without needing physical hardware.

Optional argument - webhook server url:

  • Specify where the URL where the Remote Transceiver or whatever other HTTP server is running.
  • Default is http://127.0.0.1:8081, which assumes fully local testing.

Optional argument - virtual iridium server port

  • Specify which localhost port the virtual iridium runs on.
  • Default is 8080.

$LOCAL_TRANSCEIVER_TEST_PORT acts as the serial port for AT commands. For example, to test via CLI:

  1. ./run_virtual_iridium.sh
  2. To monitor just the $LOCAL_TRANSCEIVER_TEST_PORT without extra debug messages, in a new terminal run cat $LOCAL_TRANSCEIVER_TEST_PORT. What you see output from this command will be what the Local Transceiver reads and sends.
  3. To issue CLI commands, open a new terminal and run stty 19200 < $LOCAL_TRANSCEIVER_TEST_PORT to set the baud rate.
  4. printf \"at+sbdix\\r\" > $LOCAL_TRANSCEIVER_TEST_PORT. This command queries the (currently empty) mailbox.
  5. curl -X POST -F \"test=1234\" http://localhost:8080 (this is garbage data - it doesn't mean anything). You should see the original terminal print that it received a POST request.
  6. printf \"at+sbdix\\r\" > $LOCAL_TRANSCEIVER_TEST_PORT to view the mailbox again. It will now indicate that it has the data.

Other relevant commands include (but are not limited to):

  • at+sbdwb=<msg_length>\\r: Setup the port to receive binary data of length msg_length on next input.
  • at+sbdrb\\r: Read binary content in the mailbox.
  • at+sbdd2\\r: Clear all buffers.
"},{"location":"current/sailbot_workspace/scripts/#run-testssh","title":"run-tests.sh","text":"

Script to setup, build, and test all ROS packages.

"},{"location":"current/sailbot_workspace/scripts/#run_softwaresh","title":"run_software.sh","text":"

Script to setup, build, and run all ROS packages.

"},{"location":"current/sailbot_workspace/scripts/#setupsh","title":"setup.sh","text":"

Script to handle ROS setup.

"},{"location":"current/sailbot_workspace/scripts/#testsh","title":"test.sh","text":"

Script to run tests in all ROS packages.

"},{"location":"current/sailbot_workspace/reference/deployment/","title":"Deployment","text":"

Source code

The source code for deployment can be found in scripts/deployment. Its README has been copied below.

"},{"location":"current/sailbot_workspace/reference/deployment/#deployment","title":"Deployment","text":"

Deploying our software to our autonomous sailboat's main computer.

"},{"location":"current/sailbot_workspace/reference/deployment/#scripts","title":"Scripts","text":""},{"location":"current/sailbot_workspace/reference/deployment/#setup_bootsh","title":"setup_boot.sh","text":"

Configures programs and scripts that need to run when the main computer boots. Only needs to be run once unless the script is updated. Does not need to be rerun if any scripts or programs it targets are updated, with the exception of renaming or moving the file.

Usage:

  • Must be run as root: sudo ./setup_boot.sh
"},{"location":"current/sailbot_workspace/reference/deployment/#start_containerssh","title":"start_containers.sh","text":"

Runs our Docker Compose files. You may have to install commands like wget. Would recommend running this script in its own clone of sailbot_workspace (not the one you open in VS Code).

Usage:

  • Runs the global launch file by default: ./start_containers.sh
  • Add the --website argument to additionally run the website container
  • Add the --interactive argument to manually run commands in the sailbot workspace container
  • Add the --help argument to see all available arguments
"},{"location":"current/sailbot_workspace/reference/docker_images/","title":"Docker Images","text":"

A table detailing the Docker images used to create the Dev Container can be found below. Click on an image to learn more about its features and how to update it.

Image Parent Image Source Code Why it is Rebuilt Where it is Built pre-base Ubuntu 22.04 base-dev.Dockerfile To install ROS or OMPL Personal computer base pre-base base-dev.Dockerfile To install core dependencies Workflow dispatch local-base base base-dev.Dockerfile To install core dev dependencies Workflow dispatch dev local-base base-dev.Dockerfile To install dev dependencies Workflow dispatch Dev Container dev Dockerfile To configure the Dev Container VS Code docs mkdocs-material docs.Dockerfile To install and run docs site VS Code (optional) website javascript-node website.Dockerfile To install and run website VS Code (optional)"},{"location":"current/sailbot_workspace/reference/docs_site/","title":"Docs Site","text":"

UBCSailbot software team's documentation site. It is meant to be developed in Sailbot Workspace in conjunction with our other software, but doesn't have to be. There are instructions for both cases below.

"},{"location":"current/sailbot_workspace/reference/docs_site/#setup","title":"Setup","text":""},{"location":"current/sailbot_workspace/reference/docs_site/#setup-in-sailbot-workspace","title":"Setup in Sailbot Workspace","text":"
  1. Uncomment docs/docker-compose.docs.yml in .devcontainer/devcontainer.json
  2. Uncomment 8000:8000 in .devcontainer/docker-compose.yml
  3. Rebuild the Dev Container

Refer to How to work with containerized applications for more details.

"},{"location":"current/sailbot_workspace/reference/docs_site/#setup-standalone","title":"Setup Standalone","text":"

  1. Manually install social plugin OS dependencies

  2. Install Python dependencies

    pip install --upgrade pip pip install -Ur docs/requirements.txt

    • Can do this in a Python virtual environment
"},{"location":"current/sailbot_workspace/reference/docs_site/#run","title":"Run","text":""},{"location":"current/sailbot_workspace/reference/docs_site/#run-in-sailbot-workspace","title":"Run in Sailbot Workspace","text":"

After setup, the Docs site should be running on port 8000.

Refer to How to work with containerized applications for more details.

"},{"location":"current/sailbot_workspace/reference/docs_site/#run-standalone","title":"Run Standalone","text":"
mkdocs serve\n
"},{"location":"current/sailbot_workspace/reference/docs_site/#update-dependencies","title":"Update Dependencies","text":"

This site is built using the latest versions of dependencies in docs/requirements.txt at the time of the most recent commit to the main branch. To see exactly how the site will look when deployed, ensure your local dependencies are up to date.

"},{"location":"current/sailbot_workspace/reference/docs_site/#update-dependencies-in-sailbot-workspace","title":"Update Dependencies in Sailbot Workspace","text":"

Rebuild the Dev Container.

"},{"location":"current/sailbot_workspace/reference/docs_site/#update-dependencies-by-itself","title":"Update Dependencies By Itself","text":"
pip install -Ur docs/requirements.txt\n
"},{"location":"current/sailbot_workspace/reference/docs_site/#maintain","title":"Maintain","text":""},{"location":"current/sailbot_workspace/reference/docs_site/#contribute-to-this-site","title":"Contribute to This Site","text":"

Read our Markdown Reference Page for the syntax supported by this site.

"},{"location":"current/sailbot_workspace/reference/docs_site/#delete-docs-versions","title":"Delete Docs Versions","text":"

A version of the docs site is created when a PR is open, and is deleted when it is merged or closed. However, the CI that does this is very finicky, so if 2 PR's are trying to update the site at the exact same time one might fail.

This is especially annoying if this happens to be one that deletes a version, because this means that there is a version still open for a merged/closed PR. To manually clean up these PR's, run the following commands in the docs container (in Docker Desktop, the exec tab):

git config user.name <your github username>\ngit config user.email <your github email>\nmike delete --push pr-<number>\n

If you get an error that your local copy of the gh-pages branch has diverged from the remote, you can delete it with git branch -D gh-pages and rerun the mike delete command above.

It will probably ask you to login to GitHub: enter your username then a GitHub access token with write permission.

"},{"location":"current/sailbot_workspace/reference/launch_files/","title":"ROS Launch Files in Sailbot Workspace","text":"

ROS 2 Launch files allow us to programatically start up and configure multiple ROS nodes.1 Within Sailbot Workspace, ROS launch files are used to start up our ROS packages with ease. Additionally, we take advantage of the hierarchical properties of launch files by defining a global entry point that invokes the launch files of all ROS packages in the system.

"},{"location":"current/sailbot_workspace/reference/launch_files/#tutorial","title":"Tutorial","text":""},{"location":"current/sailbot_workspace/reference/launch_files/#launch-file-architecture","title":"Launch File Architecture","text":"

There are two launch processes that we utilize: namely the Package Launch Process and the Global launch process.

"},{"location":"current/sailbot_workspace/reference/launch_files/#the-package-launch-process","title":"The Package Launch Process","text":"

The package launch process is intended to start up a specific ROS package by directly using the package launch file. The process is as follows:

  1. The package launch file is invoked with the user passing arguments via the CLI and specifying a configuration file.
  2. Global argument declarations and environment variables are loaded into the launch process.
  3. Local arguments, specific to the package, are declared.
  4. Both global and local arguments are parsed based on the argument declarations and are set for use upon start up.
  5. The ROS nodes belonging to the package begin execution, utilizing the ROS parameters from the configuration file.
When launching individual packages, be aware of dependencies between ROS packages

Some packages rely on the data produced by other packages in the system. This may cause only partial functionality of the ROS node(s) that are running inside the launched package. Therefore, it may be necessary to launch multiple packages manually to get the desired functionality.

"},{"location":"current/sailbot_workspace/reference/launch_files/#the-global-launch-process","title":"The Global Launch Process","text":"

The global launch process is intended to start up the entire system (both the development and production environments). This process invokes the package launch files for each ROS package used in the system through a global launch file. The process is as follows:

  1. The global launch file is invoked with the user passing arguments via the CLI and specifying a configuration file.
  2. Environment variables common to all ROS packages are declared. In addition, the global arguments common across all ROS packages are declared.
  3. For each package launch file:
    • The CLI arguments, global argument declarations, and environment variables are passed into the package launch file.
    • Local arguments, specific to the package, are declared. Both the global and local arguments are parsed based on the argument declarations and are set for use upon start up.
    • The ROS nodes belonging to the package begin execution, utilizing the ROS parameters from the configuration file.
"},{"location":"current/sailbot_workspace/reference/launch_files/#invoking-launch-files","title":"Invoking Launch Files","text":"Stopping the execution of a launch file

Entering Ctrl+C in the terminal where the launch file was invoked will stop all associated ROS packages from running.

Use Cmd+C for Mac OS

"},{"location":"current/sailbot_workspace/reference/launch_files/#package-launch","title":"Package Launch","text":"

At the bare minimum, the following packages need to be built with the Build or Build All VS Code task before launching:

  • custom_interfaces
  • The package you want to launch

Packages only need to be rebuilt either when the workspace is first set up, or if any changes are made to the ROS package. Once built, the package launch file can be invoked either in the CLI or using a VS Code command:

CLI VS Code

Either the package and launch file name, or the path to the launch file can be used:

  • Method 1: ros2 launch <package> <launch file>. This method can only be used when a launch file is part of a built ROS package.
  • Method 2: ros2 launch <path to launch file>. This method can be used regardless if a launch file is in a ROS package or not.

Launch via CLI Examples

Let's launch local pathfinding using both CLI methods:

Method 1 

ros2 launch local_pathfinding main_launch.py\n

Method 2 

ros2 launch $ROS_WORKSPACE/src/local_pathfinding/launch/main_launch.py\n

Run the following VS Code command from the Run and Debug tab: ROS: Launch (workspace)

There will be a prompt to select which launch file to run. Select the desired launch file.

"},{"location":"current/sailbot_workspace/reference/launch_files/#global-launch","title":"Global Launch","text":"

Before running the system, be sure to run the Build All VS Code task to build all ROS packages. If the ROS launch debug configuration is being used, then this step is not necessary as the Build All task is ran automatically before launch.

CLI VS Code

Run the entire system with the following CLI command:

ros2 launch $ROS_WORKSPACE/src/global_launch/main_launch.py\n

Run the following VS Code command from the Run and Debug tab: ROS: Launch (workspace)

There will be a prompt to select which launch file to run. Select the desired launch file.

Remember to that you need to potentially reload the window if the nodes are not being detected by VS Code. This usually happens when somebody build for the first time. Also, note that the global launch file is not part of a ROS package, so the path to the global launch file always must be provided. This is not always the case when a launch file is contained within a ROS package.

"},{"location":"current/sailbot_workspace/reference/launch_files/#using-cli-arguments","title":"Using CLI Arguments","text":"

Invoking the launch files as is will provide the system with the default CLI arguments. As an example, the following command will launch local pathfinding while setting the log level to \"debug\":

ros2 launch local_pathfinding main_launch.py log_level:=debug\n

It can also be ran with the VS Code command named ROS: Launch.

Passing arguments takes the form of <arg name>:=<arg value>. To list the arguments that a launch file takes, simply add the -s flag at the end of the launch command.

Example using the -s flag in a launch command

Let's add the -s flag after the global launch command to see the list of arguments:

ros2 launch $ROS_WORKSPACE/src/global_launch/main_launch.py -s\n

The following output is observed in the terminal (as of September 2023):

Arguments (pass arguments as '<name>:=<value>'):\n\n'config':\n    Path to ROS parameter config file. Controls ROS parameters passed into ROS nodes\n    (default: '/workspaces/sailbot_workspace/src/global_launch/config/globals.yaml')\n\n'log_level':\n    Logging severity level. A logger will only process log messages with severity levels at or higher than the\n    specified severity. Valid choices are: ['debug', 'info', 'warn', 'error', 'fatal']\n    (default: 'info')\n\n'mode':\n    System mode. Decides whether the system is ran with development or production interfaces. Valid choices are:\n    ['production', 'development']\n    (default: 'development')\n
Example using multiple CLI arguments 
ros2 launch local_pathfinding main_launch.py log_level:=debug mode:=production\n
Example passing local launch arguments to the global launch file

As long as an argument is valid inside one of the package launch files, it may be passed to the global launch file without generating any errors. This is valid even though the argument doesn't show up in the argument list for the global launch file. For example, the following will run:

ros2 launch $ROS_WORKSPACE/src/global_launch/main_launch.py enable_sim_multithreading:=true\n

Compare the argument list between the global launch file and the package launch file for the boat_simulator package. It will be observed that the argument enable_sim_multithreading shows up in the boat_simulator package argument list, but not for the global launch file.

"},{"location":"current/sailbot_workspace/reference/launch_files/#ros-parameter-config-file","title":"ROS Parameter Config File","text":"

All launch files in Sailbot Workspace accept a configuration file, which controls the ROS parameters that the ROS nodes in the system have access to. This makes our system highly configurable and customizable during development and testing. See more about ROS parameters.

  1. ROS Launch File Documentation \u21a9

"},{"location":"current/sailbot_workspace/reference/notebooks/","title":"Notebooks","text":"

Source code

The source code for Notebooks can be found in notebooks. Its README has been copied below.

"},{"location":"current/sailbot_workspace/reference/notebooks/#notebooks","title":"Notebooks","text":"

UBC Sailbot's Jupyter notebooks for researching and exporing implementations.

"},{"location":"current/sailbot_workspace/reference/notebooks/#standards","title":"Standards","text":"
  1. In addition to the dependencies installed in Sailbot Workspace, notebooks may have additional dependencies that are installed in the first code block
  2. Implementations in notebooks should be complete: do not import functions from other UBC Sailbot repositories
  3. Notebooks should be organized into directories named like the UBC Sailbot repositories they correspond to
"},{"location":"current/sailbot_workspace/reference/parameters/","title":"Parameters","text":"

Source code

Our ROS parameters can be found in src/global_launch/config. Its README has been copied below.

"},{"location":"current/sailbot_workspace/reference/parameters/#sailbot-ros-parameter-configuration","title":"Sailbot ROS Parameter Configuration","text":"

The description of each parameter contained in globals.yaml are described in this README. Descriptions of parameters for each node are included. These parameters can be changed dynamically as well via the command line interface. To learn more, see the ROS 2 documentation on ROS 2 Parameters.

Each parameter is specified in the following format:

  • Description: The description of the parameter.
  • Datatype: The datatype. If it happens to be an array, the datatype of the elements should be specified and the length of the array.
  • Range/Acceptable Values: Ranges of integers and floating point values are specified with interval notation. Namely, [] denotes inclusive boundaries, while () denotes non-inclusive boundaries. For strings, the acceptable values are listed.

Additional information may be included when necessary.

[!IMPORTANT] This document should be updated when any changes occur to the ROS parameters specified in globals.yaml.

"},{"location":"current/sailbot_workspace/reference/parameters/#global-parameters","title":"Global Parameters","text":"

ROS parameters common across all ROS nodes in the network.

pub_period_sec

  • Description: The period at which the publishers publish.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)
"},{"location":"current/sailbot_workspace/reference/parameters/#local-pathfinding-parameters","title":"Local Pathfinding Parameters","text":"

ROS parameters specific to the nodes in the local_pathfinding package.

"},{"location":"current/sailbot_workspace/reference/parameters/#mgp_main","title":"mgp_main","text":"

global_path_filepath

  • Description: The absolute filepath to a global path csv file.
  • Datatype: string
  • Acceptable Values: Any valid filepath to a properly formatted csv file.

interval_spacing

  • Description: The upper bound on spacing between each point in the global path in km.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)

write

  • Description: Whether or not to write a generated global path to a new csv file.
  • Datatype: boolean
  • Acceptable Values: true, false

gps_threshold

  • Description: A new path will be generated if the GPS position changed by more thangps_threshold*interval_spacing.
  • Datatype: double
  • Acceptable Values: (1.0, MAX_DOUBLE)

force

  • Description: Force the mock global path callback to update the global path when set to true.
  • Datatype: boolean
  • Acceptable Values: true, false
"},{"location":"current/sailbot_workspace/reference/parameters/#navigate_main","title":"navigate_main","text":"

path_planner

  • Description: The path planner to use. Planners are from OMPL Library.
  • Datatype: string
  • Acceptable Values: \"bitstar\", \"bfmtstar\", \"fmtstar\", \"informedrrtstar\", \"lazylbtrrt\", \"lazyprmstar\", \"lbtrrt\", \"prmstar\", \"rrtconnect\", \"rrtsharp\", \"rrtstar\", \"rrtxstatic\", \"sorrtstar\"
"},{"location":"current/sailbot_workspace/reference/parameters/#controller-parameters","title":"Controller Parameters","text":"

ROS parameters specific to the nodes in the Controller.

"},{"location":"current/sailbot_workspace/reference/parameters/#wingsail_ctrl_node","title":"wingsail_ctrl_node","text":"

reynolds_number

  • Description: The Reynolds number of the wind.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)

angle_of_attack

  • Description: The angle of attack of the sail.
  • Datatype: double
  • Range: (-180.0, 180.0]
"},{"location":"current/sailbot_workspace/reference/parameters/#boat-simulator-parameters","title":"Boat Simulator Parameters","text":"

ROS parameters specific to the nodes in the boat simulator.

"},{"location":"current/sailbot_workspace/reference/parameters/#low_level_control_node","title":"low_level_control_node","text":"

info_log_throttle_period_sec

  • Description: Limits the info logs to avoid overwhelming the terminal.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)

logging_throttle_period_sec

  • Description: Controls the message logging throttle period.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)

qos_depth

  • Description: The maximum number of subscription messages to queue for further processing.
  • Datatype: int
  • Range: [1, MAX_INT)

rudder.actuation_execution_period_sec

  • Description: The period at which the main loop in the rudder action server executes in seconds.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)

rudder.disable_actuation

  • Description: Controls whether or not rudder actuation is disabled. If true, the rudder angle is fixed to some value. Otherwise, the PID mechanism is used to control the rudder angle.
  • Datatype: boolean
  • Acceptable Values: true, false

rudder.fixed_angle_deg

  • Description: The angle to fix the rudder in degrees. Only used if rudder.disable_actuation is true.
  • Datatype: double
  • Range: [-45.0, 45.0]

rudder.pid.buffer_size

  • Description: The buffer size of PID that stores previously computed errors over time.
  • Datatype: int
  • Range: [1, MAX_INT)

rudder.pid.kd

  • Description: The PID Derivative constant for the rudder. Only used if rudder.disable_actuation is false.
  • Datatype: double
  • Range: [0.0, MAX_DOUBLE)

rudder.pid.ki

  • Description: The PID Integral constant for the rudder. Only used if rudder.disable_actuation is false.
  • Datatype: double
  • Range: [0.0, MAX_DOUBLE)

rudder.pid.kp

  • Description: The PID Proportionality constant for the rudder. Only used if rudder.disable_actuation is false.
  • Datatype: double
  • Range: [0.0, MAX_DOUBLE)

wingsail.actuation_execution_period_sec

  • Description: The period at which the main loop in the sail action server executes in seconds.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)

wingsail.actuation_speed_deg_per_sec

  • Description: The speed at which the wingsail trim tab actuates in degrees per second.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)

wingsail.disable_actuation

  • Description: Controls whether or not wingsail trim tab actuation is disabled. If true, the trim tab is fixed to some value. Otherwise, the trim tab angle is determined by the wingsail controller.
  • Datatype: boolean
  • Acceptable Values: true, false

wingsail.fixed_angle_degree

  • Description: Fixed the wingsail trim tab to some angle in degrees. Only used if wingsail.disable_actuation is true.
  • Datatype: double
  • Range: [-180.0, 180.0)
"},{"location":"current/sailbot_workspace/reference/parameters/#physics_engine_node","title":"physics_engine_node","text":"

action_send_goal_timeout_sec

  • Description: How long the action clients wait for the action server to respond to a request before timing out in seconds.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)

info_log_throttle_period_sec

  • Description: Limits the info logs to avoid overwhelming the terminal.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)

logging_throttle_period_sec

  • Description: Controls the message logging throttle period.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)

qos_depth

  • Description: The maximum number of subscription messages to queue for further processing.
  • Datatype: int
  • Range: [1, MAX_INT)

rudder.actuation_request_period_sec

  • Description: How often the rudder action client requests a rudder actuation in seconds.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)

wingsail.actuation_request_period_sec

  • Description: How often the sail action server requests a wingsail actuation.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)

wind_sensor.constant_params.value

  • Description: Specifies the constant vector returned by the constant generator that represents the wind velocity in kmph. Namely, the same value is fixed in the wind sensors. The value is an array containing the x and y components of the velocity. Only used if wind_sensor.generator_type is constant.
  • Datatype: double array, length 2
  • Range: (MIN_DOUBLE, MAX_DOUBLE)

wind_sensor.gaussian_params.corr_xy

  • Description: The correlation coefficient between x and y components of the wind velocity. Only used if wind_sensor.generator_type is gaussian.
  • Datatype: double
  • Range: [-1.0, 1.0]

wind_sensor.gaussian_params.mean

  • Description: The mean wind velocity parameter in kmph for the gaussian generator. The mean is an array containing the x and y components of the velocity. Only used if wind_sensor.generator_type is gaussian.
  • Datatype: double array, length 2
  • Range: (MIN_DOUBLE, MAX_DOUBLE)

wind_sensor.gaussian_params.std_dev

  • Description: The standard deviation parameters in kmph for the gaussian generator. There are two standard deviations specified within an array: one for the x component, and one for the y component. Only used if wind_sensor.generator_type is gaussian.
  • Datatype: double array, length 2
  • Range: (0.0, MAX_DOUBLE)
    • If a standard deviation of zero is desired, then consider using the constant generator instead.

wind_sensor.generator_type

  • Description: Determines the type of random number generator that will be used to generate wind sensor data.
  • Datatype: string
  • Acceptable Values: gaussian, constant

wind_generation.mvgaussian_params.mean

  • Description: The mean value for the wind generated, expressed in kilometers per hour (km/h), for the multivariate Gaussian generator.
  • Datatype: double array, length 3
  • Range: (0.0, MAX_DOUBLE)

wind_generation.mvgaussian_params.cov

  • Description: The covariance matrix for the generated wind, represented as a string formatted as a 2D double array, since ROS parameters do not support native 2D array types.
  • Datatype: string
  • Range: (0.0, MAX_DOUBLE)

current_generation.mvgaussian_params.mean

  • Description: The mean value for the current generated, expressed in kilometers per hour (km/h), for the multivariate Gaussian generator.
  • Datatype: double array, length 3
  • Range: (0.0, MAX_DOUBLE)

current_generation.mvgaussian_params.cov

  • Description: The covariance matrix for the generated current, represented as a string formatted as a 2D double array, since ROS parameters do not support native 2D array types.
  • Datatype: string
  • Range: (0.0, MAX_DOUBLE)
"},{"location":"current/sailbot_workspace/reference/parameters/#data_collection_node","title":"data_collection_node","text":"

file_name

  • Description: The name of the file in which the data is saved, excluding the file extension.
  • Datatype: string
  • Acceptable Values: Any valid file name.

qos_depth

  • Description: The maximum number of subscription messages to queue for further processing.
  • Datatype: int
  • Range: [1, MAX_INT)

topics

  • Description: Specifies the topics to subscribe to. It should adhere to the format ['topic_name_1', 'topic_type_1', ...].
  • Datatype: string array with an even length
  • Acceptable Values: Each pair within the array must consist of a valid topic name as the first string and the corresponding correct type as the second string.

bag

  • Description: Determines whether to save recorded data as a ROS bag.
  • Datatype: boolean
  • Acceptable Values: true, false

json

  • Description: Determines whether to save recorded data as a JSON file.
  • Datatype: boolean
  • Acceptable Values: true, false

write_period_sec

  • Description: The interval (in seconds) for writing queued data to the JSON file.
  • Datatype: double
  • Range: (0.0, MAX_DOUBLE)
"},{"location":"current/sailbot_workspace/usage/help/","title":"Help","text":""},{"location":"current/sailbot_workspace/usage/help/#performance-issues","title":"Performance Issues","text":"

If you are not satisfied with the performance of Sailbot Workspace, here are some things you can try:

  • Free up memory: close programs that you aren't using
  • Free up disk space: permanently delete large programs and files that you don't need anymore
  • Run Sailbot Workspace in a GitHub Codespace
    • In a codespace with 8GB of RAM, building all packages from scratch with the -q argument takes about a minute. If your computer takes longer than, or you want to free up memory and disk space, you can setup Sailbot Workspace in a GitHub Codespace
  • If you are running Sailbot Workspace on Windows, dual boot Ubuntu and run Sailbot Workspace there
    • Sailbot Workspace performs worse on Windows than bare metal Linux because it uses Docker, which is not natively supported.
    • Here is a guide to dual boot the operating systems we recommend: How to Dual Boot Ubuntu 22.04 LTS and Windows 11
      • We recommend allocating at least 50 GB to Ubuntu to leave some wiggle room for Docker
      • The process is similar for other Ubuntu and Windows versions, but feel free to search for a guide specific to the combination you want to dual boot
      • Since Sailbot Workspace uses Docker, it should be able to run on any Linux distribution, not just Ubuntu. However, we may not be able to provide support if you encounter any difficulties with this
"},{"location":"current/sailbot_workspace/usage/help/#troubleshooting","title":"Troubleshooting","text":"

If you are having some trouble running our software, here are some things you can try:

"},{"location":"current/sailbot_workspace/usage/help/#sailbot-workspace-troubleshooting","title":"Sailbot Workspace Troubleshooting","text":"
  • Update Sailbot Workspace
  • Run the setup task to update package dependencies
  • Build from scratch
    1. Run the clean task to delete C++ generated files
    2. Run the purge task to delete ROS generated files
    3. Run the Build All task to rebuild
"},{"location":"current/sailbot_workspace/usage/help/#vs-code-troubleshooting","title":"VS Code Troubleshooting","text":"
  • Rebuild the Dev Container: run the Dev Containers: Rebuild Container VS Code command
  • Reload VS Code: run the Developer: Reload Window VS Code command
  • Identify broken extension: run the Help: Start Extension Bisect VS Code command
    • Once you have identified a broken extension, you can install a previous version until the issue is fixed in a new release
"},{"location":"current/sailbot_workspace/usage/help/#system-troubleshooting","title":"System Troubleshooting","text":"
  • Restart WSL: close Sailbot Workspace and Docker Desktop then run wsl --shutdown in PowerShell
  • Restart computer
"},{"location":"current/sailbot_workspace/usage/help/#docker-troubleshooting","title":"Docker Troubleshooting","text":"

  • Delete Docker files

    Running Docker CLI commands on Windows

    On Windows, Docker CLI commands should be run in the Ubuntu terminal while Docker Desktop is running.

    • Run docker system prune to remove all unused containers, networks, and dangling and unreferenced images
      • Add --all to additionally remove unused images (don't have a container associated with them)
      • Add --volumes to additionally remove volumes (makes Bash history and ROS logs persist across containers)
    • Run docker rmi -f $(docker images -aq) to remove all images
    • Install a previous version of Docker Desktop
"},{"location":"current/sailbot_workspace/usage/help/#shrink-wsl-distributions-size","title":"Shrink WSL Distributions' Size","text":"

After using Docker and Ubuntu for a while, you may notice that the vdisks are very large. As of May 2024, they are located at C:\\Users\\<user>\\AppData\\Local\\Docker\\wsl\\data\\ext4.vhdx and C:\\Users\\<user>\\AppData\\Local\\Packages\\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\\LocalState\\ext4.vhdx, respectively.

The problem is that these vdisks can automatically grow but not shrink, so if you download large files (like Docker images) and delete them once they're not needed the space is not freed. You can shrink vdisk using these commands.

"},{"location":"current/sailbot_workspace/usage/how_to/","title":"How-To's","text":""},{"location":"current/sailbot_workspace/usage/how_to/#run-vs-code-commands-tasks-and-launch-configurations","title":"Run VS Code commands, tasks, and launch configurations","text":"

MacOS keyboard shortcuts

For keyboard shortcuts on MacOS, substitute Ctrl with Cmd.

VS Code commands can be run in the Command Palette. Open the Command Palette from the View menu or with Ctrl+Shift+P.

Tasks can be run using the Tasks: Run Task VS Code command. Build tasks can be run with Ctrl+Shift+B.

Launch configurations can be run from the Run and Debug view.

You can also run VS Code commands, tasks, launch configurations, and much more by typing their prefixes into an empty Command Palette. Open an empty Command Palette with Ctrl+P or by clicking the box in the center of the title bar. See the list below for some prefixes and their functions. For prefixes that are words, you will have to append a space to them to bring up their functions.

  • Nothing: files
  • >: VS Code commands
  • task: tasks
  • debug: launch configurations
  • ?: list all prefixes and their functions
"},{"location":"current/sailbot_workspace/usage/how_to/#work-with-containerized-applications","title":"Work with containerized applications","text":"

We have containerized the following applications for a variety of reasons:

  • MongoDB database
  • Docs site
  • Website
"},{"location":"current/sailbot_workspace/usage/how_to/#running-containerized-applications","title":"Running containerized applications","text":"

In the first section of dockerComposeFile of .devcontainer/devcontainer.json, there is a list of files: each file contains the configuration for one or more applications.

The ones that are commented out are not run. To run them:

  1. Uncomment the Docker Compose file(s) that the application(s) you desire to run are defined in
    • Programs that are defined in the uncommented Docker Compose files will be started and stopped with Sailbot Workspace
  2. Uncomment the port mapping(s) of the application(s) you want to run in .devcontainer/docker-compose.yml
    • Uncommented port mappings exposed ports to the host operating system; e.g., so that web applications can be opened in your browser
  3. Run the Dev Containers: Rebuild Container VS Code command to restart Sailbot Workspace

To stop running them:

  1. Comment out the corresponding Docker Compose file in .devcontainer/devcontainer.json and port mapping in .devcontainer/docker-compose.yml
  2. Stop the application's container: see Managing containerized applications
"},{"location":"current/sailbot_workspace/usage/how_to/#viewing-mongodb-data","title":"Viewing MongoDB data","text":"

Connect the MongoDB VS Code extension to the running database: Create a Connection for Deployment

  • Use the default methods: \"Paste Connection String\" and \"Open from Overview Page\"
  • Our database's connection string is mongodb://localhost:27017
  • See the MongoDB VS Code extension docs for how to use it to navigate or explore the database
"},{"location":"current/sailbot_workspace/usage/how_to/#opening-docs-or-website","title":"Opening Docs or Website","text":"

Docs runs on port 8000 and Website 3005. You can see them in your browser at localhost:<port>. To open them using VS Code:

  1. Run the Ports: Focus on Ports View VS Code command
  2. Open the site by hovering over its local address and clicking either \"Open in Browser\" or \"Preview in Editor\"
    • The local address of Docs is the line with a port of 8000
    • The local address of Website is the line with a port of 3005

Turn off auto saving

Changes made to their files are loaded when they are saved, so if Auto Save is on, turn it off so that the Docs/Website servers aren't continuously reloading. Auto Save is on by default in GitHub Codespaces

"},{"location":"current/sailbot_workspace/usage/how_to/#managing-containerized-applications","title":"Managing containerized applications","text":"

Each application runs in a Docker container. Containers can be managed using Docker Desktop or CLI commands:

  • View Sailbot Workspace containers

    Docker Desktop CLI Commands
    1. Select \"Containers\" in the top right
    2. Expand \"sailbot_workspace_devcontainer\"
      • The \"Status\" column shows whether a container is running or not
    docker ps -a\n
    • Sailbot Workspace containers should be named something like sailbot_workspace_devcontainer-<application>-<number>
    • The STATUS column shows whether a container is running or not

  • View a container's logs, the output of the container (including errors that caused it to stop)

    Docker Desktop CLI Commands
    1. Click on a container
    2. Navigate to the \"Logs\" view if not already on it
    docker logs <container>\n

  • Start a container that is not running

    Docker Desktop CLI Commands
    1. Click start 
    docker start <container>\n

  • Stop a container that is running

    Docker Desktop CLI Commands
    1. Click stop 
    docker stop <container>\n
"},{"location":"current/sailbot_workspace/usage/how_to/#manage-software-packages","title":"Manage software packages","text":"

Why can't I just install the dependencies myself in the command line interface with pip or apt?

Although this will temporarily work, installing apt and/or Python dependencies directly in sailbot workspace using the commandline interface will not persist between container instances. The dependencies will need to be manually installed every single time you create a new instance of sailbot workspace, which is not feasible when we start to use many dependencies at once.

Of course, one could also install dependencies inside the sailbot workspace Docker images to allow such dependencies to persist across container instances. However, putting dependencies inside package.xml distinguishes between what dependencies are needed for ROS packages and what dependencies are needed for infrastructure purposes.

"},{"location":"current/sailbot_workspace/usage/how_to/#add-apt-or-python-dependencies-to-ros-packages","title":"Add apt or python dependencies to ROS packages","text":"

If running your ROS packages requires external dependencies from an apt repository or python package, one of the following tags should be added to the package.xml file in the root directory of the ROS package:

<depend>ROSDEP_KEY</depend>\n<build_depend>ROSDEP_KEY</build_depend>\n<build_export_depend>ROSDEP_KEY</build_export_depend>\n<exec_depend>ROSDEP_KEY</exec_depend>\n<test_depend>ROSDEP_KEY</test_depend>\n

  • Learn what each tag is used for here.

  • Replace ROSDEP_KEY with the rosdep key for the dependency, which can be found online.

    • Use the key associated with ubuntu since sailbot workspace uses Ubuntu, or debian which Ubuntu is based on
    • Do not include the square brackets in package.xml
    Apt Dependencies Python Dependencies
    • Rosdep keys for apt repositories can be found here
    • Rosdep keys for python packages can be found here
    • Since we use Python 3, look for the packages that start with python3- (python- is usually for Python 2)

  • If there isn't rosdep key for the dependency, you can add your own to custom-rosdep.yaml in the root directory of the ROS package

After completing these steps, run the setup task and the desired dependencies should be installed. ROS uses a dependency management utility, rosdep, to handle the installation of dependencies. In addition to runtime dependencies, rosdep also handles dependencies for build time, dependencies for testing, sharing dependencies between ROS packages, and more. See the ROS documentation on rosdep to learn more.

"},{"location":"current/sailbot_workspace/usage/how_to/#add-dependencies-to-a-docker-image","title":"Add dependencies to a Docker image","text":"

There are a couple cases where you would want to add dependencies to a Docker image instead of ROS package:

  1. The dependency is not used to build/run/test a ROS package
  2. There is no apt or pip package for your dependency so you have to build from source

To verify your changes, you can add them to .devcontainer/Dockerfile then run the Dev Containers: Rebuild Container VS Code command. Once verified, migrate the changes to one of the upstream images: base, local-base, dev, or pre-base.

"},{"location":"current/sailbot_workspace/usage/how_to/#enable-github-copilot-in-sailbot-workspace","title":"Enable GitHub Copilot in Sailbot Workspace","text":"

GitHub Copilot is an AI paired programming tool that can help you accelerate your development by providing suggestions for whole lines or entire functions inside your editor.1 To enable GitHub Copilot:

  1. Apply to GitHub Global Campus as a student to use GitHub Copilot and get other student benefits for free. It may take a few days for your student status to be verified. In the meantime, you can still continue with the next steps. However, you will need to use the GitHub Copilot free trial until your account is verified.

  2. Sign up for GitHub Copilot for your personal account. If it offers a free trial, then take it. You should see a page telling you that you can use GitHub Copilot for free (if you have a verified student account).

  3. Uncomment the github.copilot extension in .devcontainer/devcontainer.json and run the Dev Containers: Rebuild Container VS Code command

  4. Sign into your GitHub account in VS Code. The GitHub Copilot extension should automatically prompt you to sign into your account if you are not already.

    VS Code is not prompting me to sign into my account

    You may already be signed in into your GitHub account. You can check by clicking on the Accounts icon in the bottom-left corner in VS Code and verify that you see your GitHub account.

    If you do not see your account, you can get the sign in prompt by trying:

    • Reloading the VS Code window: Ctrl+Shift+P and select Developer: Reload Window
    • Rebuilding the devcontainer: Ctrl+Shift+P and select Dev Containers: Rebuild Container
    • If using a Mac, use Cmd instead of Ctrl

  5. If all the previous steps were done correctly, you should see the GitHub Copilot icon in the bottom-right corner of VS Code without any error messages. For more information on how to use Copilot and a tutorial, refer to:

    • The GitHub Copilot Getting Started Guide
    • Configuring GitHub Copilot in your Environment
"},{"location":"current/sailbot_workspace/usage/how_to/#use-your-dotfiles","title":"Use your dotfiles","text":"

Dotfiles are configuration files for various programs.2

More about dotfiles
  • They are called dotfiles because their filenames start with a dot (.)
  • On Linux and MacOS, files and directories that begin with a dot are hidden by default
  • To list dotfiles using the ls command, specify the -a argument: ls -a

Dotfiles that are commonly modified include:

  • Bash: ~/.bashrc
  • Git: ~/.gitconfig
  • Vim: ~/.vimrc

To use your dotfiles:

  1. Ensure that the base, local-base, or dev image installs the programs that the dotfiles correspond to

  2. Copy the dotfiles to the .devcontainer/config/ directory. If a dotfile is located in a child directory, you will have to created it. For example, if a dotfile's path is ~/.config/ex_dotfile, you will need to copy it to .devcontainer/config/.config/ex_dotfile

    Special cases

    • ~/.gitconfig: there is no need copy your Git dotfile, as Dev Containers do this automatically
    • ~/.bashrc: don't copy your Bash dotfile, as it would override the one created in the dev image. Instead, add your bash configuration .aliases.bash or .functions.bash in the config directory, as these are sourced by the created Bash dotfile.

  3. Run the Dev Containers: Rebuild Container VS Code command

"},{"location":"current/sailbot_workspace/usage/how_to/#run-rayes-software","title":"Run Raye's software","text":"

Raye was our previous project. Her software can be run in the raye branch:

  1. Switch to the raye branch: git switch raye
  2. Rebuild the Dev Container: run the Dev Containers: Rebuild Container VS Code command
  3. If you want to run Raye's local pathfinding visualizer, complete step 2 of the setup instructions

raye branch disclaimers

  1. Since raye (and Raye's codebase in general) is not in active development, it may not be 100% functional or contain all the features in main
  2. raye is more memory intensive than main because the parent image of its Dev Container is much larger; this may lead to worse performance
"},{"location":"current/sailbot_workspace/usage/how_to/#build-rayes-ros-packages","title":"Build Raye's ROS packages","text":"

To build Raye's ROS packages, run the following commands:

roscd\ncatkin_make\n
"},{"location":"current/sailbot_workspace/usage/how_to/#run-packages-from-different-workspaces","title":"Run packages from different workspaces","text":"

The raye branch has two ROS workspaces: one for Raye and one for the new project. To run ROS packages, you will have to source the overlay of the workspace that it is in:

New ProjectRaye 
srcnew\n
srcraye\n

Then you can run launch files or package-specific executables in that workspace with:

New ProjectRaye

ros2 launch ... or ros2 run ..., respectively.

roslaunch ... or rosrun ..., respectively.

"},{"location":"current/sailbot_workspace/usage/how_to/#rayes-known-issues","title":"Raye's known issues","text":"

Run commands for Raye packages are very slow

On non-Ubuntu-based Linux operating systems, Run commands for Raye packages may take a long time to start-up. This is because the system has trouble resolving the local hostname.

To resolve this bug, run the commands below in the Dev Container:

echo 'export ROS_HOSTNAME=localhost' >> ~/.bashrc\necho 'export ROS_MASTER_URI=http://localhost:11311' >> ~/.bashrc\n

  1. GitHub Copilot Quickstart Guide \u21a9

  2. Dotfiles \u2013 What is a Dotfile and How to Create it in Mac and Linux \u21a9

"},{"location":"current/sailbot_workspace/usage/setup/","title":"Setup Instructions","text":"

Sailbot Workspace can be run on Windows, Linux, or macOS, but is the easiest to set up and performs the best on Ubuntu and its derivatives. The workspace may not perform well on Windows computers with 8GB of memory or less; in this case, please check out our recommendations in the Performance Issues section.

"},{"location":"current/sailbot_workspace/usage/setup/#1-setup-prerequisites","title":"1. Setup prerequisites","text":""},{"location":"current/sailbot_workspace/usage/setup/#docker","title":"Docker","text":"

Docker is a platform that uses OS-level virtualization1 to develop, ship, and run applications.2 We use it to separate our applications from our infrastructure2 so that we can update and version control our infrastructure for every use case (software members, CI, deployment) in one place: this repository.

Docker Engine is a software used to run Docker. However, it can only be installed on Linux. Docker Desktop is a software used to run Docker in a VM,3 allowing it to be installed on Windows and macOS in addition to Linux.

Windows macOS Linux

  1. Set up prerequisites, WSL and Ubuntu:

    1. In PowerShell, run wsl --install Ubuntu, then exit, wsl --update, and wsl --set-default Ubuntu

      Ubuntu is already installed?

      If Ubuntu is already installed, check that it is the right WSL version:

      1. Check the WSL versions of Linux distributions with wsl -l -v
      2. If Ubuntu's VERSION is 1, upgrade it to WSL 2 with wsl --set-version Ubuntu 2

    2. Open the Ubuntu app to set up or verify its configuration:

      1. If you are opening Ubuntu for the first time, a setup process will run; follow the prompts to finish setting it up

      2. Run whoami to verify that it returns your Ubuntu username

        whoami returns root

        If whoami returns root:

        1. Create a non-root user with sudo privileges
        2. Change the default Ubuntu user to this newly-created user: run ubuntu config --default-user <username> in PowerShell, replacing <username> with the name of the newly-created user
        3. Run whoami after closing and reopening Ubuntu, verifying that it returns your Ubuntu username

  2. Install Docker Desktop with the WSL 2 backend

    Docker Desktop - Unexpected WSL Error

    If the above error shows when trying to start Docker Desktop on your laptop:

    1. For windows users navigate to C:\\Users\\user_name and delete the .Docker folder
    2. Restart Docker Desktop
    Docker Desktop can't start up and WSL hangs when restarting

    If Ubuntu can't start up and WSL hangs when restarting:

    1. Open command prompt as administrator and run the command netsh winsock reset
    2. Uninstall and reinstall Docker Desktop
    3. Restart your computer

    More potential solutions can be found here: Link

Install Docker Desktop for your computer's CPU.

  1. Install Docker Engine
    • As of February 2023, Sailbot Workspace (more specifically its use of VS Code Dev Containers) isn't compatible with Docker Desktop for Linux; if you have Docker Desktop installed, uninstall it and install Docker Engine instead.
  2. Manage Docker as a non-root user
  3. Configure Docker to start on boot
"},{"location":"current/sailbot_workspace/usage/setup/#vs-code","title":"VS Code","text":"

Visual Studio Code is a powerful and customizable code editor for Windows, Linux, and macOS. We strongly recommend that you use this editor to develop our software so that you can use all the features of Sailbot Workspace.

  1. Install VS Code
  2. Install the Remote Development Extension Pack
"},{"location":"current/sailbot_workspace/usage/setup/#git","title":"Git","text":"

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.4

  1. Check if Git is installed with git --version (on Windows, run command in PowerShell)
    • If not installed, download and install it from Git Downloads
  2. Configure your name and email: Git config file setup (on Windows, run commands in Ubuntu)

  3. Login to GitHub

    Windows macOS / Linux

    1. Run the git config command for your Git version in Git Credential Manager setup (run command in Ubuntu)

      Which Git to check

      Git is installed seperately in Windows and Ubuntu, so they could be at different versions. We want to check the version of Git on Windows, not Ubuntu: run git --version in PowerShell and not Ubuntu. However, the git config command itself is run in Ubuntu.

    1. Install the GitHub CLI: Installation
    2. Run gh auth login and select the first option for all choices

  4. Verify that you have successfully logged in to GitHub by cloning a private GitHub repository (run command in Ubuntu)

    1. If you are a part of the UBCSailbot Software GitHub team, you shouldn't see any errors running git clone https://github.com/UBCSailbot/raye-ais.git
    2. You can delete this repository with rm -rf raye-ais
"},{"location":"current/sailbot_workspace/usage/setup/#2-setup-x11-forwarding","title":"2. Setup X11 forwarding","text":"

X11 forwarding is a mechanism that enables Sailbot Workspace to run GUI applications.

You can skip this step since we currently aren't running any GUI applications

Setup instructions for X11 forwarding
  1. Ensure that the versions of VS Code and its Dev Containers extension support X11 forwarding:
    1. VS Code version >= 1.75
    2. Dev Containers version >= 0.275.1

  2. Verify that echo $DISPLAY returns something like :0

    echo $DISPLAY doesn't return anything

    If echo $DISPLAY doesn't return anything, set it to :0 on shell initialization:

    1. Find out what shell you are using with echo $SHELL
      1. Most Linux distributions use Bash by default, whose rc file path is ~/.bashrc
      2. macOS uses Zsh by default, whose rc file path is: ~/.zshrc
    2. Run echo 'export DISPLAY=:0' >> <rc file path>, replacing <rc file path> with the path to your shell's rc file
    3. Run echo $DISPLAY after closing and reopening your terminal, verifying it returns something like :0

  3. Install a X11 server

    Windows macOS Linux

    WSL includes a X11 server.

    1. Set up XQuartz following this guide
    2. Copy the default xinitrc to your home directory: cp /opt/X11/etc/X11/xinit/xinitrc ~/.xinitrc
    3. Add xhost +localhost to ~/.xinitrc after its first line
    General Arch Linux

    As of February 2023, almost all Linux distributions include a X11 server, Xorg. This may change in the future as Wayland matures.

    1. Install xhost: sudo pacman -S xorg-xhost
    2. Copy the default xinitrc to your home directory: cp /etc/X11/xinit/xinitrc ~/.xinitrc
    3. Add xhost +local:docker to ~/.xinitrc after its first line

  4. Verify that X11 forwarding works:

    1. Install x11-apps

      Windows macOS Linux

      In Ubuntu, sudo apt install x11-apps.

      XQuartz includes x11-apps. Ensure that XQuartz is running.

      Install x11-apps using your desired package manager.

    2. Verify that running xcalc opens a calculator and that you can use it

"},{"location":"current/sailbot_workspace/usage/setup/#3-clone-sailbot-workspace","title":"3. Clone Sailbot Workspace","text":"

Where to clone on Windows

Run the command below in the Ubuntu app to clone it in the Ubuntu file system, otherwise sailbot workspace will not work. Windows has a native file system as well as file systems for each WSL distribution.

git clone https://github.com/UBCSailbot/sailbot_workspace.git\n
"},{"location":"current/sailbot_workspace/usage/setup/#4-open-sailbot-workspace-in-vs-code","title":"4. Open Sailbot Workspace in VS Code","text":"

  1. Install code command in PATH

    Windows macOS Linux

    The code command is installed by default.

    See launching from the command line.

    The code command is installed by default.

  2. Open the sailbot_workspace/ directory in VS Code: run code <relative path to sailbot workspace>

    • For example, if you just cloned the repository, the command would be code sailbot_workspace
"},{"location":"current/sailbot_workspace/usage/setup/#5-open-the-workspace-file","title":"5. Open the workspace file","text":"

Click the popup to Open Workspace. If there isn't a popup:

  1. Open the file sailbot.code-workspace in VS Code
  2. Click Open Workspace
"},{"location":"current/sailbot_workspace/usage/setup/#6-open-sailbot-workspace-in-a-dev-container","title":"6. Open Sailbot Workspace in a Dev Container","text":"
  1. Ensure that Docker is running
  2. Click the popup to Reopen in Container. If there isn't a popup, run the Dev Containers: Reopen in Container VS Code command
"},{"location":"current/sailbot_workspace/usage/setup/#7-run-the-build-all-task","title":"7. Run the Build All task","text":"

Wait before running

Ensure that the postCreateCommand from devcontainer.json has completed before running this task.

The Build All task builds all the ROS packages.

"},{"location":"current/sailbot_workspace/usage/setup/#8-reload-the-vs-code-terminals-and-window","title":"8. Reload the VS Code terminals and window","text":"

Delete all open terminals and run the Developer: Reload Window VS Code command to detect the files that were generated from building.

"},{"location":"current/sailbot_workspace/usage/setup/#9-start-the-system","title":"9. Start the system","text":"

Run the entire system to verify everything is working using the following command in the VS Code terminal:

ros2 launch $ROS_WORKSPACE/src/global_launch/main_launch.py\n

Use Ctrl+C in the terminal to stop the system.

"},{"location":"current/sailbot_workspace/usage/setup/#setup-sailbot-workspace-in-a-github-codespace","title":"Setup Sailbot Workspace in a GitHub Codespace","text":"

A codespace is a development environment that's hosted in the cloud.5 Since Sailbot Workspace is resource intensive, it has high hardware requirements and power consumption, which aren't ideal for development on laptops. GitHub Codespaces provide a seamless experience to work on repositories off-device, especially if they specify a Dev Container like Sailbot Workspace. Codespaces can run in VS Code or even in a browser for times when you aren't on your programming computer.

  1. Create a GitHub Codespace following the steps in the relevant GitHub Docs page: create a codespace for a repository. A couple things to note:
    • For the best Sailbot Workspace development experience, select the high-spec machine available
    • There are usage limits if you don't want to pay: monthly included storage and core hours for personal accounts
      • Upgrade to a Pro account for increased usage limits (this is free for students): apply to GitHub Global Campus as a student
      • Stop your codespace as soon as you are done using it: stopping a codespace
      • Delete codespaces that you do not plan to use anymore: deleting a codespace
  2. Follow the local setup instructions starting from 5. Open the workspace file

Once you have a codespace set up:

  • Open it by following the steps in the relevant GitHub Docs page: reopening a codespace
  • Close it by running the Codespaces: Stop Current Codespace VS Code command

Known limitations of running Sailbot Workspace in a GitHub Codespace

  • Does not support X11 forwarding to run GUI applications
  • High-spec machines not available: as of March 2023, the highest-spec machine that is publically available has a 4-core CPU and 8GB of RAM

  1. Wikipedia Docker page \u21a9

  2. Get Docker \u21a9\u21a9

  3. What is the difference between Docker Desktop for Linux and Docker Engine \u21a9

  4. Git SCM \u21a9

  5. GitHub Codespaces overview \u21a9

"},{"location":"current/sailbot_workspace/usage/workflow/","title":"Development Workflow","text":""},{"location":"current/sailbot_workspace/usage/workflow/#1-open-sailbot-workspace","title":"1. Open Sailbot Workspace","text":"

Once you have set up Sailbot Workspace, you can open it by opening a new VS Code window and selecting:

File > Open Recent > /workspaces/sailbot_workspace/.devcontainer/config/sailbot_workspace (Workspace) [Dev Container: Sailbot Workspace]\n
Another way to open Sailbot Workspace on Windows
  1. Pin VS Code to the taskbar
  2. Right-click VS Code in the taskbar and pin sailbot_workspace (Workspace) [Dev Container]

Then you can open Sailbot Workspace by selecting it from the \"Pinned\" section of the VS Code taskbar icon's right-click menu.

"},{"location":"current/sailbot_workspace/usage/workflow/#2-update-sailbot-workspace","title":"2. Update Sailbot Workspace","text":"

Sailbot Workspace is still in active development, check out its recent releases and commit history. If there are new features or bug fixes that you want to try, you will need to update your local version of Sailbot Workspace:

  1. Switch Sailbot Workspace to the main branch if you aren't in it already

    If you running Git commands in the CLI, make sure that you are in the correct repository

    Sailbot Workspace contains other repositories in the src/ directory, so if you are in one of its subdirectories you may be in the wrong repository.

    To check which repository you are in, run git remote -v; if its output contains sailbot_workspace, you are good to go. If not, you can navigate the root directory of the Sailbot Workspace repository with cd $ROS_WORKSPACE, or open a new terminal in its root directory with Ctrl+Shift+` then Enter.

    • If you are unable to switch branches because you have uncommitted changes, stash them

  2. Pull the latest changes

    • If you stashed your uncommitted changes, pop them

  3. If prompted, rebuild the Dev Container

    When does the Dev Container need to be rebuilt?

    To apply the modifications to its configuration files in .devcontainer/ that occurred since it was last built.

    VS Code will prompt you to rebuild when devcontainer.json, Dockerfile, or docker-compose*.yml. These file may be modified if you:

    • Pull the lastest changes of a branch
    • Switch branches
    • Update a file in .devcontainer/ yourself

    However, there may be changes to the Dev Container that VS Code can't detect. To rebuild it yourself, run the Dev Containers: Rebuild Container VS Code command.

  4. If you want to run our docs or website, see How to work with containerized applications

"},{"location":"current/sailbot_workspace/usage/workflow/#3-make-your-changes","title":"3. Make your changes","text":"

We make changes to our software following our GitHub development workflow. Of particular relevance is the Developing on Branches page.

Git interfaces

One way to interface with Git is through CLI commands. However, you may find it faster to use VS Code's interface, especially when working with multiple repositories.

Things to note when making changes:

  • When C++ or Python files are saved, you may notice that some lines change. We use formatters to help fix lint errors; not all lint errors can be fixed by formatters, so you may have to resolve some manually
  • When changing a package's source files, you likely should update its test files accordingly
"},{"location":"current/sailbot_workspace/usage/workflow/#4-build-your-changes","title":"4. Build your changes","text":"

In general, changes need to be built before they can be run. You can skip this step if you only modified Python source or test files (in python_package/python_package/ or python_package/test, respectively), or are running a launch type launch configuration.

  1. Depending on which packages you modified, run the Build All or Build Package task
    1. Unless you want to run clang-tidy, use the -q build argument (default) for quicker build times
"},{"location":"current/sailbot_workspace/usage/workflow/#5-verify-your-changes","title":"5. Verify your changes","text":"Running GUI applications on macOS

If you want to run GUI applications on macOS, ensure that XQuartz is running.

"},{"location":"current/sailbot_workspace/usage/workflow/#lint-and-test","title":"Lint and Test","text":"

Run lint and test tasks to make sure you changes will pass our CI:

  • ament lint
  • For C++ packages, clang-tidy
  • test

In addition to VS Code tasks, the Testing tab on the VS Code primary sidebar contains individual tests. One can run specific unit tests by clicking the Run Test icon beside the test name.

"},{"location":"current/sailbot_workspace/usage/workflow/#run-a-package","title":"Run a Package","text":"

To verify that your changes do what you expect, you may want to run the package you modified. The run commands for each package should be documented in their READMEs, but in general they can be run using a CLI or VS Code command:

CLI VS Code
  • Launch files:
    • ros2 launch <package> <launch file>
    • ros2 launch <path to launch file>
  • Nodes:
    • ros2 run <package> <executable>
CLI features

There are many commands that can be autocompleted in the terminal. Take advantage of this so that you run commands faster and memorize less syntax. If there is only one possibility, pressing tab once will complete it. If there is more than one possibility, pressing tab again will list them out.

Some tab completion use cases:

  • View available commands: lists all ros2 commands

    $ ros2 <tab><tab>\naction                          extension_points                multicast                       security\nbag                             extensions                      node                            service\n...\n

  • Complete commands: runs ros2 launch local_pathfinding main_launch.py

    $ ros2<tab>la<tab>loc<tab>m<tab>\n

  • Navigate to directories: runs cd .devcontainer/config from the root directory of Sailbot Workspace

    $ cd .d<tab>c<tab>\n

Furthermore, navigate past commands with Up and Down and search through them with Ctrl+R.

  • Launch files: ROS: Run a ROS launch file (roslaunch)
  • Nodes: ROS: Run a ROS executable (rosrun)

For more information on launch file use in our system, see this page.

"},{"location":"current/sailbot_workspace/usage/workflow/#run-the-system","title":"Run the System","text":"

To verify that you didn't break anything, you may want to run the entire system. See Invoking Launch Files for more information on running the system.

"},{"location":"current/sailbot_workspace/usage/workflow/#debugging","title":"Debugging","text":"

Debug your changes if they aren't behaving how you expect by setting breakpoints and running one of our launch configurations in the Run and Debug tab on the VS Code primary sidebar. The launch configuration types are:

  • Launch: runs the desired launch file or executable
    • For launch files, ROS: Launch
    • For C++ executables, C++ (GDB): Launch
  • Attach: attaches to a running executable
    • ROS: Attach
"},{"location":"current/website/overview/","title":"Overview","text":"

Source code

The source code for Website can be found in src/website. Its README has been copied below.

"},{"location":"current/website/overview/#website","title":"Website","text":"

In the website development timeline, we are currently evaluating the folllowing software stack: Next.js website (this repository), Typescript, React + Redux, and the MongoDB database. The easiest way to evaluate these potential solutions for our purposes is in sailbot_workspace.

"},{"location":"current/website/overview/#database","title":"Database","text":"

MongoDB is a general purpose, document-based, distributed database built for modern application developers and for the cloud era. If you want to learn more about MongoDB, visit their docs site: MongoDB Documentation.

"},{"location":"current/website/overview/#setup","title":"Setup","text":""},{"location":"current/website/overview/#environment-variables","title":"Environment variables","text":"

We have two separate configurations: one for development .env.development, the other for production .env.production. The values may vary, but the environment variables are the same. See below:

  • MONGODB_URI: Your MongoDB connection string. Use mongodb://localhost:27017/<DB_NAME> to establish a connection with the local database.
  • NEXT_PUBLIC_SERVER_HOST: The host URL of the website.
  • NEXT_PUBLIC_SERVER_PORT: The port number of the website.
  • NEXT_PUBLIC_POLLING_TIME_MS: The time interval for polling the database in milliseconds.
"},{"location":"current/website/overview/#package-installation","title":"Package installation","text":"

The following command installs all required dependencies listed in the package.json file:

npm install\n

Once the installation is complete, you should see a node_modules directory in the project's root. This directory contains all installed packages.

When installing a new package to the website, please follow the steps below:

  1. Access the terminal of the website container on Docker.

  2. Run the command npm install <package-name>. Replace <package-name> with the actual name of the package you want to add.

  3. Should you encounter errors related to resolving peer dependencies, please re-run the command with the header --legacy-peer-deps. Do not to use --force unless you're well aware of the potential consequences.

  4. Review the package.json file to ensure the new package and its version have been added to the dependencies section.

  5. Confirm that package-lock.json has also been updated. This file holds specific version information to ensure consistent installations across different environments.
  6. Once the installation process is finished, please make sure to commit the files package.json and package-lock.json. These files are essential for version controlling the dependencies that have been added.
"},{"location":"current/website/overview/#run","title":"Run","text":"

Using Sailbot Workspace, the website should be up and running on http://localhost:3005.

Otherwise, you execute the following commands to run it in development mode:

npm run dev\n
"},{"location":"current/website/overview/#linters","title":"Linters","text":"

Before merging in new changes to the repository, please execute the following commands in order:

npm run format\n

This command runs Prettier to automatically format the code according to the rules defined in the configuration file .prettierrc.

npm run lint\n

This command runs ESLint to analyze the code for potential errors and enforce coding style based on the rules defined in the configuration file .eslintrc.

"},{"location":"reference/docker/","title":"Docker","text":"

Docker is a platform that uses OS-level virtualization1 to develop, ship, and run applications.2

"},{"location":"reference/docker/#tutorial","title":"Tutorial","text":"

  1. Wikipedia Docker page \u21a9

  2. Get Docker \u21a9

"},{"location":"reference/linux_commands/","title":"Linux Commands","text":""},{"location":"reference/linux_commands/#tutorial","title":"Tutorial","text":""},{"location":"reference/markdown/","title":"Markdown","text":"

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents.1 You can do anything with Markdown, from creating websites to PDF documents, all in a clean format that is easy to learn. Many of your favorite services use Markdown, so it would be useful to pick it up to write technical documentation.

Markdown is not standardized across services. Many services that support Markdown have their own \"flavour\" of Markdown. Be sure to know the Markdown features of the service you are using so that your Markdown renders properly.

"},{"location":"reference/markdown/#getting-started","title":"Getting Started","text":"

We recommend markdownguide.org to be your first point of reference if\\ you are learning Markdown for the first time. It covers topics like what Markdown is, its syntax, advanced tips, and the different services that support Markdown. Flavours of Markdown specific to a service build on top of these basics.

"},{"location":"reference/markdown/#sailbot-and-markdown","title":"Sailbot and Markdown","text":"

We write Markdown for GitHub and Material for MkDocs. The following sections detail how Markdown is used in these services.

"},{"location":"reference/markdown/#github","title":"GitHub","text":"

We use Markdown in GitHub for technical documentation and collaboration. This includes:

  • README.md files
  • Issues
  • Pull Requests

Almost all places where text is written in GitHub support Markdown. GitHub also allows you to preview your Markdown before you submit any comments.

Before RenderingAfter Rendering

The image above shows an example of a \"write\" and a \"preview\" tab for writing a comment on an issue. It might look different depending on where you are writing, but there usually exists a preview option!

GitHub-Flavoured Markdown

GitHub uses its own \"flavour\" of Markdown. Certain features, like using HTML, are excluded for security reasons. Visit the official GitHub Markdown guide for more information on the available features.

"},{"location":"reference/markdown/#material-for-mkdocs","title":"Material for MkDocs","text":"

We use Markdown in Material for MkDocs to create this website! Since it is written in Markdown, no frontend experience is required to contribute to our docs.

Material for MkDocs supports powerful features purpose-built to take technical documentation to the next level. Feel free to browse this site to see how we use these features, exploring their syntax in the source code. Since GitHub renders Markdown files automatically you will need to click the \"Raw\" button to view their contents.

Material-Flavoured Markdown

Material for MkDocs' flavour of Markdown extends upon vanilla Markdown, adding features such as admonitions (like this note) and content tabs. Refer to the official Material for MkDocs reference page for more information on the available features.

"},{"location":"reference/markdown/#rendering-markdown","title":"Rendering Markdown","text":"

You have a few choices to render Markdown on your computer. Be advised that if you are using an extended version of Markdown, you will need to consult the documentation from the service provider to render their flavour of Markdown properly. The following resources are good for rendering Markdown:

Vanilla Github Material for MkDocs
  • VS Code: Markdown rendering is supported out of the box.
  • Markdown Live Preview: An online rendering tool.
  • Markdown Preview GitHub Styling: VS Code extension that renders GitHub-flavoured markdown.
  • Create a draft issue on GitHub and preview the markdown to see how it renders.
  • UBC Sailbot Docs: To preview your changes when working on this site, refer to the How to work with containerized applications.
  • Material for MkDocs sites in general: If you ever decide to write your own documentation using Material for MkDocs, refer to the official \"Getting Started\" guide.

Other resources exist to render Markdown like browser extensions that render Markdown as HTML and GitHub repositories that contain source code to render your Markdown. Feel free to browse around for the solution that suits your needs.

"},{"location":"reference/markdown/#linting","title":"Linting","text":"

We lint our Markdown files to reduce errors and increase readability. In particular, we use two tools:

  1. markdownlint is used to enforce a style guide. Its configuration file for this repository is .markdownlint.json. If you use VS Code, there is a markdownlint extension.

  2. markdown-link-check is used to check for broken links. Its configuration file for this repository is .markdown-link-check.json.

  1. https://www.markdownguide.org/getting-started/ \u21a9

"},{"location":"reference/ros/","title":"Robot Operating System","text":"

Robot Operating System (ROS) is a set of software libraries and tools for building robot applications.1 It provides functionality for hardware abstraction, device drivers, communication between processes over multiple machines, tools for testing and visualization, and much more.2

We use ROS because it is open-source, language-agnostic, and built with cross-collaboration in mind. It enables our sub-teams to work independently on well-defined components of our software system without having to worry about the hardware it runs on or the implementation of other components.

The official ROS 2 documentation contains everything you need to get started using ROS. From it we have hand-picked the resources that are most relevant to our current and expected future usage of ROS assuming that you use our preconfigured workspace. To run our software on your device without our workspace, you would have to install ROS and the dependencies that are in our Docker images yourself.

"},{"location":"reference/ros/#tutorial","title":"Tutorial","text":""},{"location":"reference/ros/#workspace-configuration","title":"Workspace Configuration","text":"

To get our workspace configuration running on your computer:

  1. Set it up by following the setup instructions
  2. Uncomment the ROS 2 tutorials section in .devcontainer/Dockerfile, then run the \"Dev Containers: Rebuild Container\" VS Code command, to install the tutorials' dependencies
  3. Clone the repositories used in the tutuorials: ros_tutorials (humble branch), py_pubsub_ex, and cpp_pubsub_ex, then run the setup VS Code task to install their dependencies

Our workspace configuration contains easier methods of accomplishing some of the tutorial steps, or eliminates the need for them altogether.

Tutorial step Sailbot Workspace configuration Install a package All packages used in the tutorials are already installed (step 2 above) Clone a sample repo (ros_tutorials) ros_tutorials is already cloned (step 3 above) Resolve dependencies Run the \"install dependencies\" VS Code task Build the workspace Run the \"Build\" VS Code task, AKA Ctrl+Shift+B Source the overlay Run the srcnew terminal command Create a package with a node Run the \"new ament_(python|cmake) package with a node\" VS Code task"},{"location":"reference/ros/#tutorials","title":"Tutorials","text":"

We encourage all software members to work through the ROS tutorials that are listed below in order. For tutorials that have both C++ and Python versions, NET members should do the C++ version while CTRL and PATH members should do the Python version.

  • Beginner: CLI tools
    • Introducing turtlesim and rqt
    • Understanding nodes
    • Understanding topics
    • Understanding services
    • Understanding parameters
    • Understanding actions
    • Using rqt_console to view logs
    • Recording and playing back data
  • Beginner: Client libraries
    • Creating a workspace
    • Creating a package
    • Writing a simple publisher and subscriber (C++ or Python)
    • Writing a simple service and client (C++ or Python)
    • Using parameters in a class (C++ or Python)
    • Using ros2doctor to identify issues
  • Intermediate
    • Launch
    • Testing
  • Demos
    • Logging
"},{"location":"reference/ros/#concepts","title":"Concepts","text":"

We encourage all software members to read the following documentation on key ROS concepts:

  • About logging and logger configuration
  • About ROS 2 interfaces
  • About parameters in ROS 2
"},{"location":"reference/ros/#ros-1-bridge","title":"ROS 1 Bridge","text":"

There are two major versions of ROS, aptly named ROS 1 and ROS 2. Our previous project, Raye, uses ROS 1 because it was the only version available during her design process. Our new project will use ROS 2, a complete re-design of the framework that tackles the shortcomings of ROS 1 to bring it up to industry needs and standards.3 If you are curious about the changes made in ROS 2 compared to 1, this article is a worthwhile read.

ROS 2 includes the ROS 1 Bridge, a collection of packages that can be installed alongside ROS 1 to help migrate code from ROS 1 to ROS 2. As we will be reusing parts of Raye's codebase, it is essential to know how to use these packages. Until we are completely done with Raye, our preconfigured workspace will have ROS 1, ROS 1 Bridge, and ROS 2 installed.

We encourage all software members work through the ROS 1 Bridge README. For PATH members, the Migrating launch files from ROS 1 to ROS 2 page will be a helpful reference when we do so.

  1. https://docs.ros.org/en/humble/index.html \u21a9

  2. https://www.toptal.com/robotics/introduction-to-robot-operating-system \u21a9

  3. https://ubuntu.com/robotics/what-is-ros \u21a9

"},{"location":"reference/cpp/differences/","title":"Differences Between C and C++","text":"

For most use cases, you can think of C++ as a superset of C. While this is not technically true, more often than not you are able to write standard C code for a C++ program without issues. However, doing so ignores a lot of the benefits and reasons to use C++.

"},{"location":"reference/cpp/differences/#classes-and-structs","title":"Classes and Structs","text":"

In C structs can only contain member variables, but in C++ structs are basically classes but with a default member visibility of public instead of private.

Example

The following code blocks are equivalent.

struct foo {\nprivate:\n    int x;\n    void helper(void);\npublic:\n    foo(int y);\n}\n
class foo {\nprivate:\n    int x;\n    void helper(void);\npublic:\n    foo(int y);\n}\n
"},{"location":"reference/cpp/differences/#namespaces","title":"Namespaces","text":"

One problem that is prevalent in C concerns the scoping of names. For example, let there be two files A.h and B.h and a program ighxy.c, and let them both contain a float x and int bar(void).

Our program cannot compile because the linker cannot distinguish which bar() function we want to use! One way to fix this in a C program would be to rename them a_bar() and b_bar(). Although this fix seems trivial for this example, applying it to a file that has potentially 100 functions can be a lot more difficult, especially if two files just happen to share the same prefix for their functions!

C++ introduces namespaces to tackle this problem. With namespaces, we can deal with naming conflicts much more easily. Though be aware that namespaces are not necessary everywhere. See the following code snippet to see how they work.

Example CC++ A.h
float x;\nint bar(void);\n
B.h
float x;\nint bar(void);\n
ighxy.c
#include \"A.h\"\n#include \"B.h\"\n\nint main(void) {\n    int a = bar();\n    ...\n}\n/* Error, does not compile*/\n
A.h
namespace a {\nfloat x;\nint bar(void);\n}\n
B.h
namespace b {\nfloat x;\nint bar(void);\n}\n
ighxy.cpp
#include \"A.h\"\n#include \"B.h\"\n\nint main(void) {\n    int a = a::bar();\n    int b = b::bar();\n    float xa = a::x;\n    float xb = b::x;\n    /* No problem! */\n    ...\n}\n
Warning

You may come across something like:

example.cpp
using namespace std;\nnamespace io = std::filesystem;\n\nint main(int argc, char* argv[]) {\n    bool isDirectory = io::is_directory(argv[1]);  // Equivalent to std::filesystem::is_directory(argv[1])\n    cout << isDirectory << endl;\n    return 0;\n}\n

There are two things going on here.

First, using namespace std makes all functions and types defined within the standard namespace and included via #include directives visible to example.cpp. If you are familiar with Python, the Python equivalent of this would be import std as *. However, it is considered bad practice to do this as it eliminates the point of using namespaces.

OKNot OK 
    class string {\n        // Insert implementation here\n    }\n\n    int main(void) {\n        string ourString = \"Our own string implementation\";\n        std::string stdString = \"Standard Library string implementation\";\n        ...\n    }\n
    using namespace std;\n\n    // ERROR - multiple definitions of type string\n    class string {\n\n    }\n

The compiler cannot infer which implementation we want.

Secondly, namespace io = std::filesystem is basically an alias for the std::filesystem namespace. This practice is acceptable for long namespace identifiers, but be careful as it can still run into namespace conflicts if your alias is the same as another namespace or alias.

"},{"location":"reference/cpp/differences/#constant-expressions","title":"Constant Expressions","text":"

In C, if we want to declare a constant or a function/expression that we want to be evaluated at compile time, we need to use #define statements. One of the problems with #define statements is that they perform a simple copy paste wherever they're used. For example:

Before PrecompileAfter Precompile 
#define PI 3.14F\n#define AREA_OF_CIRCLE(radius) ((PI) * (radius) * (radius))\n\nint main(void) {\n    float area = AREA_OF_CIRCLE(2.5F);\n    ...\n}\n
int main(void) {\n    float area = ((3.14F) * (2.5F) * (2.5F));\n    ...\n}\n

Note

AREA_OF_CIRCLE is a macro with arguments. If you are confused by it, this resource has a detailed explanation on how they work.

Because of this copy-pasting, you need to be very careful with syntax, sometimes necessitating an ugly do {} while(0) wrapper. Moreover, symbols declared with #define are always globally visible, ignoring namespaces!

In C++, the use of constant expressions are preferred.

constexpr float pi = 3.14F;\nconstexpr float area_of_circle(float radius) {\n    return pi * radius * radius;\n}\n

Constant expressions do not get copy pasted, and are instead placed in program memory just like a normal variable or function. They also respect namespaces and function scopes, meaning the following code compiles.

Constant Expression Scoping
void foo(void) {\n    constexpr float rand = 123.456;\n    ...\n}\n\nvoid bar (void) {\n    constexpr float rand = 789.123;\n    ...\n}\n
"},{"location":"reference/cpp/differences/#lambdas","title":"Lambdas","text":"

Lambdas are primarily useful when you need to register a callback function one time and don't feel it's necessary to write out a full function. They are in no way required though, so do not worry about learning them. However, it's necessary to know that they exist such that you don't get confused when reading code. For more information, go here for Microsoft's explanation.

"},{"location":"reference/cpp/differences/#misc","title":"Misc","text":""},{"location":"reference/cpp/differences/#arrays","title":"Arrays","text":"

Using the C++ implementation of arrays is preferred over C arrays. It is simply easier and safer to work with than a standard C array without any performance costs.

Example

Passing an array to a function an iterating over it

CC++ 

#include \"stdio.h\"\n\nvoid print_contents(int *arr, int size) {\n    for (int i = 0; i < size; i++) {\n        printf(\"%d\\n\", *arr);\n    }\n}\n\nint main(void) {\n    int arr[5] = {0, 1, 2, 3, 4};\n    foo(arr, 5);\n    return 0;\n}\n
We can't even guarantee that the integer pointer arr is an array!

C++ 20 makes passing arrays around a lot simpler. Do not worry about understanding the code shown below. It uses some fairly advanced concepts and exists to illustrate how different such a simple operation can be.

#include <iostream>\n#include <array>\n#include <span>\n\nvoid print_contents(std::span<int> container) {\n    for (const auto &e : container) {\n        std::cout << e << std::endl;\n    }\n}\n\nint main(void) {\n    std::array<int, 5> arr = {0, 1, 2, 3, 4};\n    foo(arr);\n    return 0;\n}\n

The advantages of the C++ version are:

  • Size is implicitly part of the object
  • We guarantee that foo takes a container, but it does not care if it's an array or, say, a vector, which is preferable in this scenario where we simply iterate through the container's existing elements
"},{"location":"reference/cpp/start/","title":"Getting Started","text":"

UBC Sailbot's Network Systems team uses C++ for its software. If you know already know C, then you already know the bare minimum to write C++. This is a good starting point, but the additional features C++ provides allow for safer programming practices.

"},{"location":"reference/cpp/start/#for-cc-beginners","title":"For C/C++ Beginners","text":"

If you just need to know how C++ is different from C, then see the Differences Between C and C++. You should also look at it if you go through and finish this section.

If you are new to C and C++, then this the best place to start. The tutorials provided in this section will help you learn the fundamentals of the language. Do not feel pressured to do all the tutorials! Just get comfortable with the syntax and the mechanisms of the language.

Note

The hardest part about this will likely be pointers and dynamic memory, so pay close attention to tutorials concerning them! Additionally, dynamic memory requires the usage of pointers, but pointers do not require dynamic memory!

Tip

Dynamic memory is much more prone to error than statically allocated memory, so try to use static allocation whenever possible

Resource Description w3schools Tutorial A structured tutorial that goes through basic concepts in C++. It's good to do up to the section on Classes. YouTube Tutorial If you prefer video tutorial, then this is a comprehensive 4 hour video covering similar concepts to the one above. It is 4 hours long though. Dynamic Memory Overview A page going over how dynamic memory works in C++.

Feel free to add other resources other than the ones listed above if you find any that you like!

"},{"location":"reference/cpp/tools/","title":"Tools","text":"

A lot goes into making a well structured C++ project, much more than any one team should have to do.

"},{"location":"reference/cpp/tools/#cmake","title":"CMake","text":"

CMake is a powerfull build automation tool that makes compiling code for large projects with a lot of interoperating files a lot easier. Steps 1-3 of the official tutorial are great for understanding the basics.

"},{"location":"reference/cpp/tools/#gdb","title":"GDB","text":"

The GNU Project Debugger is the most commonly debugger for the C language family. VSCode also has a degree of integration with GDB that allows an easy to use GUI. This GDB cheat sheet has all the GDB comands you will need to know. Be aware the VSCode has GUI buttons for some of these commands that are easier to use.

"},{"location":"reference/cpp/tools/#googletest","title":"GoogleTest","text":"

GoogleTest is the C++ unit testing framework we will be using. The GoogleTest Primer is a good place to start.

Example Cached Fibonacci ProgramTest Cached Fibonacci Program cached_fib.h
#include <vector>\nclass CachedFib {\npublic:\n    void CachedFib(int n);\n    int  getFib(int n);\nprivate:\n    std::vector<int> cache;\n}\n
cached_fib.cpp
#include <iostream>\n#include <vector>\n#include \"cached_fib.h\"\n\nvoid CachedFib::CachedFib(int n) {\n    cache.push_back(0);\n    cache.push_back(1);\n    for (int i = 2; i < n; i++) {\n        cache.push_back(cache[i - 1] + cache[i - 2]);\n    }\n}\n\nint CachedFib::getFib(int n) {\n    if (cache.size() < n) {\n        for (int i = cache.size(); i < n; i++) {\n            cache.push_back(cache[i-1] + cache[i-2]);\n        }\n    }\n    std::cout << cache[n - 1] << std::endl;\n}\n
test_cached_fib.cpp
#include \"cached_fib.h\"\n#include \"gtest/gtest.h\"\n\nCachedFib::testFib;\n\nclass TestFib : public ::testing::Test {\nprotected:\n    void Setup override {\n        // Every time a test is started, testFib is reinitialized with a constructor parameter of 5\n        testFib = CachedFib(5);\n    }\n}\n\nTEST_F(TestFib, TestBasic) {\n    ASSERT_EQ(getFib(5), 3) << \"5th fibonacci number must be 3!\";\n}\n\n// more tests\n
"},{"location":"reference/cpp/tools/#google-protocol-buffer","title":"Google Protocol Buffer","text":"

Google Protocol Buffer (Protobuf) is a portable data serialization method. We use it over other methods like JSON and XML because it produces smaller binaries, an important consideration when sending data across an ocean. Unfortunately, there does not seem to be a easy to follow tutorial for using them, but here are the C++ basics. The page is quite dense and can be hard to follow, so do not worry if you do not understand it.

"},{"location":"reference/cpp/tools/#clang","title":"Clang","text":"

In its most basic form, Clang is a compiler for the C language family. Clang has multiple benefits like easier portability compared to, for example, GCC. Clang is actually \"half\" the compiler, the other half being LLVM. Without going into unnecessary detail, Clang compiles C++ code to a generic language before LLVM compiles it to machine specific language.

"},{"location":"reference/cpp/tools/#clangd","title":"Clangd","text":"

Clangd is the Clang language server. It provides a much more powerful intellisense than the default one used in VSCode's C/C++ extension.

"},{"location":"reference/cpp/tools/#clang-tidy","title":"Clang-Tidy","text":"

Clang-Tidy is a linting tool, who's main purpose is to catch potential programming errors caused by bad programming style/practices using just static analysis.

"},{"location":"reference/cpp/tools/#clang-format","title":"Clang Format","text":"

An autoformatting tool that makes enforcing style guidelines much easier. When se tup, it corrects formatting as soon as you hit save.

"},{"location":"reference/cpp/tools/#llvm-cov","title":"llvm-cov","text":"

We will use llvm-cov to evaluate our test coverage. When used with genhtml, we can generate HTML reports that that show our line, function, and branch coverage line-by-line.

"},{"location":"reference/github/advanced_git/","title":"Advanced Git","text":""},{"location":"reference/github/advanced_git/#tutorial","title":"Tutorial","text":""},{"location":"reference/github/github_actions/","title":"GitHub Actions","text":""},{"location":"reference/github/github_actions/#tutorial","title":"Tutorial","text":""},{"location":"reference/github/workflow/branches/","title":"Developing on Branches","text":"

We use branching to work on issues without modifying the main line. This ensures that the main line only contains functional code and handles merge conflicts that arise when multiple people are developing at the same time. For a quick rundown on branching in git, consult the official git documentation.

"},{"location":"reference/github/workflow/branches/#creating-a-branch","title":"Creating a branch","text":"

When starting a new issue, you will want to create a new branch for it:

Caution

When creating branches locally, it uses your local copy to create the new branch. Remember to do a git pull if you intend on using the latest changes from the remote branch you are creating from.

Creating a new branch from main
# Switch to main\ngit switch main\n\n# Update your local copy\ngit pull\n\n# Clone a new branch from main\ngit switch -c <branch_name>\n

IMPORTANT: When creating a new branch for an issue, you must create the branch from main.

"},{"location":"reference/github/workflow/branches/#branch-naming-convention","title":"Branch naming convention","text":"

When working on a new issue, you will want to create a branch to work on it. We have the following branch naming convention:

<github_username>/<issue_number>-<issue_description>\n

Example

If Jill (GitHub Username: jill99) is going to take on an issue titled \"Fix bug on pathfinding software\" and the issue number is 39, then the branch named can be named something like user/jill99/39-fix-pathfinding-bug.

If the branch that you are creating is not tied to an issue, then you do not need to put an issue number. A descriptive title will suffice.

"},{"location":"reference/github/workflow/branches/#tracking-and-committing-changes","title":"Tracking and committing changes","text":"

All files where new changes have been made must first be \"staged\" in order to make commits:

git add <FILES>\n

Files that are staged will be part of your next commit. Once you are confident in your changes and you are ready to finalize them, then you should commit your changes:

git commit -m \"<commit_message>\"\n

Be sure to add a commit message that is descriptive of the changes that you made. It is encouraged that you make commits often so you can keep track of your changes more easily and avoid overwhelmingly large commits when you look back on your version history.

When you are ready to move your local changes to a remote branch, you want to push to the correct branch and potentially set the upstream if it does not yet exist:

git push -u origin <current_branch_name>\n
"},{"location":"reference/github/workflow/branches/#merging-branches","title":"Merging branches","text":"

There may be times where you want to merge two branches together, whether you diverged on some ideas and finally want to synthesize them, or you just want to update your issue's branch with the main branch. In any case, merging branches will be inevitable as part of the development process, so it is essential to understand how to merge branches.

Merge Local BranchMerge Remote Branch 
# Checkout to destination branch\ngit checkout <dest_branch>\n\n# Merge with local copy of other branch\ngit merge <other_branch>\n
# Checkout to destination branch\ngit checkout <dest_branch>\n\n# Fetch from remote\ngit fetch\n\n# Merge remote copy of other branch\ngit merge origin/<other_branch>\n

Info

Merging a remote branch into its local counterpart using the method above is essentially the same operation as git pull.

Once the merge operation is complete, your destination branch should have updates both from itself and the other branch that you merge. If you do a git log, you will also see a new commit that indicates that the merge happened.

"},{"location":"reference/github/workflow/branches/#resolving-merge-conflicts","title":"Resolving merge conflicts","text":"

Merging two branches is not always easy since the commit history for both branches could look quite different, and therefore conflicting changes can easily be made. If you run into a scenario like this, you may get something like this:

Upon inspecting bar.txt, we see the following:

Resolving merge conflicts is not always a trivial task, but there are many ways to resolve them which include:

  • Resolving on GitHub (recommended)
  • Resolving in Command Line

Tip

If you cannot resolve a merge conflict on your own, reach out to your lead for help!

"},{"location":"reference/github/workflow/issues/","title":"Creating Issues","text":"

GitHub issues lets us plan and track our work on GitHub.

"},{"location":"reference/github/workflow/issues/#getting-started-with-issue-templates","title":"Getting started with issue templates","text":"

An issue is associated with a specific repository. To open the issues page for a given repository, click on the issues tab in the repository navigation bar.

You will see a list of current issues (if any) for the repository. To create a new issue, click on the New issue button in the upper right corner.

When creating a new issue, you will see a few issue templates. Since issues can be created for a variety of reasons, issues may therefore be structured differently and contain different kinds of information. Issue templates were introduced to give us a quick and structured way to writing issues.

Note

GitHub issues are written using GitHub-flavoured markdown. To add a little spice to your issues, refer to the official GitHub documentation for some quick tips and tricks on how to write awesome markdown!

Click on the Get started button to open the issue template. For this example, let's go with the New Feature issue template. Upon opening the issue template, you should see a page like the one below:

At this point, you should give a succinct title and describe the issue in the textbox. You will also see some templated sections to fill out. Try to give only the necessary details to make a clear and concise issue. If you are unsure on how to construct your issue, take a look at current or past issues and ask the software leads for further guidance if necessary.

Finally, feel free to make suggestions on new templates or changing current templates!

Tip

We understand that some issues may need extra sections to describe the issue further, or some of the templated sections might not be relevant at all! Add or remove sections as necessary to get your point across. The goal of the issue templates is to provide guidance, not police your documentation methodologies!

"},{"location":"reference/github/workflow/issues/#adding-issues-to-a-project","title":"Adding issues to a project","text":"

We use projects to plan and track the status of our issues and pull requests. To add an issue to an existing project, click on the gear icon in the Projects section and add it to your desired project. You will almost always want to add your issue to the Software organization project.

To verify that your issue has been added to your desired project, go to the UBC Sailbot organization, go to the Projects tab on the organization banner, and select the project that it is added to. When added to a project, it should show up under the General tab (depending on the project, this might not always be the case).

"},{"location":"reference/github/workflow/issues/#adding-issues-to-a-milestone","title":"Adding issues to a milestone","text":"

We use milestones to track progress on groups of issues or pull requests that we want to complete by a certain date. Since our projects span over many years, it is important to work incrementally with small, yet achievable goals. If your issue should belong to a milestone, simply add it to a milestone by clicking on the gear icon in the Milestone section and add it to your desired milestone.

Note

Unlike projects, milestones are strictly associated with a repository.

"},{"location":"reference/github/workflow/issues/#labelling-issues","title":"Labelling issues","text":"

GitHub allows us to label our issues so that we can categorize them. It helps us identify at first glance what kind of a problem that an issue aims to solve and which issues are more important. To add a label to your issue, click on the gear icon in the Labels section and add your desired label(s).

The issue templates will already have labels assigned to them, but you should add or remove labels as you see fit to make them as relevant as possible.

Note

Each repository might have different labels available, so be sure to check out all of the labels at least once in the repository that you are working in. Feel free to suggest additional labels as well!

"},{"location":"reference/github/workflow/issues/#adding-assignees","title":"Adding assignees","text":"

Every issue should be assigned to at least one person to work on it. If you are not sure who should be assigned the issue initially, then don't worry about it for now since you can assign someone to the issue later on. To assign someone an issue, click on the gear icon in the Assignees section and add the desired people.

"},{"location":"reference/github/workflow/issues/#submit-the-issue","title":"Submit the issue","text":"

Once you are finished writing your issue, click on the Submit new issue button. You should now see your issue in the issues list and in the UBC Sailbot software project.

"},{"location":"reference/github/workflow/overview/","title":"Development Workflow Overview","text":"
graph LR\n    B[Problem Conception] --> C{Small Fix?};\n    C --> |Yes| E[Development];\n    C --> |No| D[Issue Creation];\n    D --> E;\n    E --> F[Pull Request];\n    F --> G{Approved?};\n    G --> |No| E;\n    G --> |Yes| H[Merge PR into Main];

A good development workflow is essential to maintain a robust codebase and stay organized. The above diagram is a high level overview of how our development process works, and parts of this process are explained in subsequent sections.

"},{"location":"reference/github/workflow/overview/#tutorial","title":"Tutorial","text":""},{"location":"reference/github/workflow/overview/#version-control-git","title":"Version control: Git","text":"

We use git to help us keep track of the version history of our codebase. Git is a free and open source distributed version control system, and it is commonly used by many developers to keep track of changes to their code over time. As a member of the software team on UBC Sailbot, it is absolutely necessary that you know git. If you are unfamiliar with git, here are a few resources to help you get started:

Resource Description Beginners Tutorial A 30 minute video on git for beginners. Good if you want to learn git quickly and nail all the fundamentals. Pro Git book A textbook on using git. Good if you are a completionist and want to deep dive into how git works (and if you have some time on your hands). Common Git Commands A condensed summary of some common git commands. Good to refer to once you are familiar with the fundamentals of git."},{"location":"reference/github/workflow/overview/#remote-server-github","title":"Remote server: GitHub","text":"

We use GitHub as our remote server where we store our codebase. In addition to using it for storage, we also leverage many of GitHub's features to make for a smoother development process. Some examples of features that we use are:

  • Issues
  • Projects
  • Milestones
  • GitHub Organizations
  • Repository Permissions and Branch Protection Rules
  • And more!
"},{"location":"reference/github/workflow/pr/","title":"Pull Requests","text":"

Pull requests are used to verify code functionality and quality of a development branch before merging into the main branch, accomplished through CI and code reviews.

Note

Pull requests are much like issues where we can do many of the same things. This goes for creating comments in markdown, assigning reviewers, adding labels, adding projects, or adding milestones. Sometimes we skip writing an issue when the change is relatively small.

"},{"location":"reference/github/workflow/pr/#creating-a-pull-request","title":"Creating a pull request","text":"

To create a pull request in a repository, to go the Pull requests tab and then click New pull request:

On the next screen, you need to select the base branch that you are merging into, and the branch that you are comparing. For the most part, the base branch will be the main branch, and the branch that you are comparing will be the issue branch.

Once you have decided on your base and compare branches, click on Create pull request. You should see the page below (looking in the dropdown menu, you can open the pull request as a draft to avoid notifying reviewers until you are ready):

Notice how this is remarkably similar to the page of an issue. To link a pull request to an issue, simply add <KEYWORD> #<ISSUE NUMBER> to the initial comment in the pull request. A list of valid keywords can be found here.

Example

\"This issue resolves #49. Please review my pull request!\"

Observe that the right-hand side banner contains the following:

Field Description Reviewers Assign reviewers to review your pull request. Always try to assign at least one reviewer. Assignees Assign the people who worked on the issue. Labels Assign labels to categorize pull requests. Projects Assign a pull request to a project. Milestone Assign a pull request to a milestone.

Attention

If you linked the pull request to an issue, you should not add the pull request to a project or a milestone to avoid duplicate cards.

"},{"location":"reference/github/workflow/pr/#merging-into-main","title":"Merging into main","text":"

Once the pull request and code reviews are complete, it is time to merge the changes in the pull request into the main branch! However, this can only be done when the following conditions are met:

  1. All CI checks pass (look for a green checkmark beside your latest commit on GitHub).
  2. All reviewers have reviewed the PR and approved the PR.
  3. There are no unresolved comments and suggestions from the reviewers.
  4. There are no merge conflicts with the main branch.

If all of these conditions are met, confirm that the merge is good to go by clicking Squash and merge:

"},{"location":"reference/github/workflow/pr/#reviewing-a-pull-request","title":"Reviewing a pull request","text":"

A common activity that you will participate in is reviewing pull requests to give your feedback on other's code. You will be notified when you have been requested to review a pull request and should promptly review it as soon as time permits.

In particular, you will most likely be doing the following in a pull request:

  • Asking Questions: Clarify your understanding about something that you are not sure about.
  • Providing Suggestions: Give some ideas about how to improve the current implementation and provide feedback to your peers. This is a good opportunity to share your knowledge with others.
  • Verify Implementations: Identify potential bugs in the implementation and raise your concerns with the person who developed the solution. This will reduce the likelihood of bugs and significantly bring down the number of issues in the future.
  • Documentation: Record why certain changes were made, especially if this diverges from the proposed solution in the linked issue (if any).
"},{"location":"reference/python/conventions/","title":"Conventions","text":"

At UBC Sailbot, we follow standards in how we code to maintain a clean and comprehensible codebase. This page addresses what conventions we use specifically when programming in Python and the tools to help us maintain these conventions.

"},{"location":"reference/python/conventions/#style-guide","title":"Style guide","text":""},{"location":"reference/python/conventions/#linting","title":"Linting","text":"

To ensure that the codebase stays clean, we use flake8, which is a tool for style guide enforcement mostly based off pep8. To automate most of this process, we use autopep8, which is a tool that resolves most style issues. However, there will be some issues that must be resolved by you!

Refer to this guide on how to write readable code in python with the pep8 style guide.

Note

Our CI automatically checks that your code follows the pep8 standard. If it does not, your pull requests will be blocked from being merged until those issues are resolved!

"},{"location":"reference/python/conventions/#type-hinting","title":"Type hinting","text":"

Even though Python is a dynamically typed language, newer versions support type hinting. Type hinting catches errors, documents code, improves IDEs and linters, and helps build and maintain a clean software architecture.1 Expanding on how it catches errors, a static type checker such as mypy can be used.

There is some syntax to get familiar in order to use type checking. We recommend the following resources:

  • mypy Typing Cheatsheet
  • PEP 483: The Theory of Type Hints (A Simplified Guide)
  • PEP 484: Type Hints (Fully Comprehensive Guide)

Below are a few examples of using type hinting:

Return the sum of a sequence 
from typing import Sequence, Union\n\n\nNumber = Union[int, float]\n\n\ndef sumseq(seq : Sequence[Number]) -> Number:\n    return sum(seq)\n
Function with optional parameters and default values 
from typing import Optional\n\n\ndef printArgs(a : str, b : str=\"World\", c : Optional[str]=None) -> None:\n    print(f\"Value of a: {a}\")\n    print(f\"Value of b: {b}\")\n    if c is not None:\n        print(f\"Value of c: {c}\")\n
Function with custom class 
class MyClass:\n    def __init__(self) -> None:\n        pass\n\n\ndef foo(a : MyClass) -> None:\n    print(a)\n
Forward referencing a class With __future__Without __future__ 
from __future__ import annotations\n\n\ndef foo(a : MyClass) -> None:\n    print(a)\n\n\nclass MyClass:\n    def __init__(self) -> None:\n        pass\n
def foo(a : 'MyClass') -> None:\n    print(a)\n\n\nclass MyClass:\n    def __init__(self) -> None:\n        pass\n
Function that never returns 
from typing import NoReturn\n\n\ndef bar() -> NoReturn:\n    while True:\n        print(\"Hello World!\")\n
"},{"location":"reference/python/conventions/#documentation","title":"Documentation","text":"

Code is written once and read a thousand times, so it is important to provide good documentation for current and future members of the software team. The major things that we document in our code are:

  1. Classes and Objects:
    • What does it represent? What is it used for?
    • What are its member variables? What are they used for?
  2. Functions:
    • What are the inputs and outputs?
    • What is the overall behavior and purpose of the function?
  3. Code:
    • Is a line of code obscure and/or not clear? Add an inline comment to clear things up.
    • Break down a large process.

Ideally, the third point should be avoided as much as possible since we would want our code to be self explanatory. It should be done only when absolutely necessary.

"},{"location":"reference/python/conventions/#generating-docstrings","title":"Generating docstrings","text":"

We use a vscode extension called autoDocstring which autogenerates docstrings that we use to document our code. To install this extension, go to the Extensions tab in vscode and search autoDocstring in the marketplace.

To generate docstrings, type \"\"\" at the beginning of the function that you want to document and the template will be generated for you! If you use type hinting, this extention will autofill some of the documentation for you!

Note

The autoDocstring extension only works for functions. It does not work for classes and objects, so documenting these will have to be done manually. Be sure to follow the same format used by functions.

"},{"location":"reference/python/conventions/#example-on-documentation","title":"Example on documentation","text":"

It's hard to imagine what good documentation looks like. We provide a few examples below of documenting code using the autoDocstring extension. The extension uses Google style docstrings by default.

Documentation example on a function 
from typing import List\ndef inner_product(v1 : List[float], v2 : List[float]) -> float:\n    \"\"\"\n    Computes the inner product between two 1D real vectors. Input vectors should have the\n    same dimensions.\n\n    Args:\n        v1 (List[float]): The first vector of real numbers.\n        v2 (List[float]): The second vector of real numbers.\n\n    Returns:\n        float : The inner product between v1 and v2\n    \"\"\"\n    assert (len(v1) == len(v2)), \"Input lists must have same length\"\n\n    # Iterate through elementwise pairs\n    summation = 0\n    for e1, e2 in zip(v1, v2):\n        summation += (e1 * e2)\n    return float(summation)\n
Documentation example with a stack 
from typing import Any\nclass Stack:\n\n    \"\"\"\n    This class represents a stack, which is an abstract data type that serves as a collection of\n    elements. The stack is a LIFO datastructure defined by two main operations: Push and Pop.\n\n    Attributes:\n        __stack (List[Any]): A list containing the elements on the stack.\n    \"\"\"\n\n    def __init__(self):\n        \"\"\"\n        Initializes the Stack object.\n        \"\"\"\n        self.__stack = []\n\n    def push(self, element : Any) -> Any:\n        \"\"\"\n        Pushes an element to the top of the stack.\n\n        Args:\n            element (Any): The element to be pushed on to the stack.\n        \"\"\"\n        self.__stack.append(element)\n\n    def pop(self) -> Any:\n        \"\"\"\n        Removes the element at the top of the stack and returns it. If the stack is empty,\n        then None is returned.\n\n        Returns:\n            Any, NoneType: The element at the top of the stack.\n        \"\"\"\n        if self.is_empty():\n            return None\n        else:\n            return self.__stack.pop()\n\n    def is_empty(self) -> bool:\n        \"\"\"\n        Determines whether the stack is empty or not.\n\n        Returns:\n            bool: Returns True if the stack is empty, and False otherwise.\n        \"\"\"\n        empty = (len(self.__stack) == 0)\n        return empty\n\n    def __len__(self) -> int:\n        \"\"\"\n        Gets the number of elements on the stack.\n\n        Returns:\n            int: The number of elements on the stack.\n        \"\"\"\n        length = len(self.__stack)\n        return length\n

For more examples, see Example Google Style Python Docstrings.

  1. https://realpython.com/lessons/pros-and-cons-type-hints/ \u21a9

"},{"location":"reference/python/start/","title":"Getting Started","text":"

We use Python 3 to write the majority of our software at UBC Sailbot. Pathfinding and Controls mainly use Python 3, so it is critical that you are familiar with the language if you are on one of these sub-teams.

"},{"location":"reference/python/start/#python-tutorials","title":"Python tutorials","text":"

We understand that not everyone who joins Sailbot has Python in their toolkit, nor do we expect it either! Whether you are learning Python for the first time or you just want to brush up, we have provided some resources below. You may not learn absolutely everything from the resources below, but it is a good starting point. You will mostly learn through doing, as you would with most technical skills!

Resource Description The Python Tutorial The official python tutorial. Good if you have some time on your hands and you are a completionist. Sections 1 - 5 and 9 are the most relevant. w3schools Tutorial Good if you want a more brief introduction to Python. It breaks down a lot of concepts into sections. Everything up to Python Classes/Objects is relevant. YouTube Tutorial If you like video tutorials, then we recommend this tutorial. This video is about 5 hours long, but it pretty much covers everything that you'll need to know for Python and there are some hands on projects. Shorter YouTube Tutorial A shorter alternative YouTube tutorial condensed into 1 hour. It covers less material but still covers many of the essentials. CodingBat Practice Good resource to put your Python skills to practice on some simple coding problems. Note that this resource does not teach you python.

Feel free to add other resources other than the ones listed above if you find any that you like!

"},{"location":"reference/python/virtual-environments/","title":"Virtual Environments","text":"

The Python virtual environment is a tool for dependency management and project isolation. They solve many common issues, including:

  • Dependency Resolution: A project might want a package with version A while another project might want a package with version B. With a virtual environment, you can separate which packages that you want to use for a given project.

  • Project Isolation: The environment for your project is self-contained and reproducible by capturing all dependencies in a configuration file.

  • Housekeeping: Virtual environments allow you to keep your global workspace tidy.

There are two main methods of creating virtual environments: virtualenv and Anaconda. Each have their own benefits and drawbacks. Here are some differences between the two:

Virtualenv Anaconda Environment files are local. Environment files are available globally. Must activate environment by giving the path. Can activate the environment without knowing the path, but only the name. Can only use pip to install packages. Can either use pip or built-in conda package manager. Installation is very simple. Installation takes more effort. Can only install python packages. In addition to packages, you can download many data science tools.

We recommend virtualenv over Anaconda because of its simplicity. However, feel free to appeal to your preferences.

"},{"location":"reference/python/virtual-environments/#installation","title":"Installation","text":"Virtualenv Anaconda

If you already have python and the pip package manager installed, just execute the following:

Using pip to install virtualenv
pip install virtualenv\n

Go to the official Anaconda website and follow the installation instructions for your operating system.

"},{"location":"reference/python/virtual-environments/#using-virtual-environments","title":"Using virtual environments","text":"

The name of a virtual environment is configurable. For the purposes of this site, we will use env as the environment name unless specified otherwise.

"},{"location":"reference/python/virtual-environments/#creating-a-virtual-environment","title":"Creating a virtual environment","text":"Virtualenv Anaconda

Since virtualenv creates the environment directory in a specific location, make sure that you are in the located in the project that you want to work on.

Create virtual environment with virtualenv
# Go to desired location\ncd <PATH TO DIRECTORY>\n\n# Create the environment with the name env\npython3 -m venv env\n

Verify that your environment is created by examining your current directory and look for the directory that matches the name of your virtual environment.

Since the environment will be available globally, there is no need to go to a specific location to create it.

Create virtual environment with Anaconda
# Create environment with name env and python version\nconda env create -n env python=<PYTHON VERSION NUM>\n

If you don't specify a python version, the default is the version you used when you downloaded and installed Anaconda. Verify that your environment is created by executing conda env list.

"},{"location":"reference/python/virtual-environments/#activating-the-virtual-environment","title":"Activating the virtual environment","text":"

To use the virtual environment, you must activate it.

Virtualenv Anaconda Windows macOS Linux Activation for Windows
env\\Scripts\\activate\n
Activation for macOS
source env/bin/activate\n
Activation for Linux
source env/bin/activate\n
Activation for Anaconda
conda activate env\n

After activating your virtual environment, you might see (env) on your terminal before or after your current line. Now you are in your virtual environment!

"},{"location":"reference/python/virtual-environments/#installing-dependencies","title":"Installing dependencies","text":"

Any dependencies that you install while your virtual environment is activated are only available in your virtual environment. If you deactivate your environment and try to use those dependencies, you will find that you will get errors because they will not be found unless you install those dependencies in the other environment!

Virtualenv Anaconda

Use the pip package manager to install python dependencies. Before installing any Python dependencies, it is good practice to upgrade pip:

Upgrade pip
pip install --upgrade pip\n

Now, install any Python dependencies pip:

Install dependency with pip
pip install <PACKAGE>\n
Option 1: pipOption 2: conda

Use the pip package manager to install python dependencies.

Install dependency with pip
# Install pip using conda\nconda install pip\n\n# Install python packages using pip\npip install <PACKAGE>\n

Use the built-in conda package manager to install python dependencies.

Install dependency with conda
conda install -c <CHANNEL> <PACKAGE>\n

Sometimes, installing a package like this simply won't work because you are not installing from the correct channel. You usually will have to google the command to use in order to install your package correctly because it usually comes from a specific channel that you don't know about. Some common channels to try are:

  • conda-forge
  • anaconda
  • bioconda
  • r
"},{"location":"reference/python/virtual-environments/#deactivating-the-virtual-environment","title":"Deactivating the virtual environment","text":"

When you are finished using your virtual environment, you will need to deactivate it.

Virtualenv Anaconda Deactivate virtualenv environment
deactivate\n
Deactivate anaconda environment
conda deactivate\n
"},{"location":"reference/python/virtual-environments/#reproducing-your-virtual-environment","title":"Reproducing your virtual environment","text":"

When you want to share your code with others, it is important for others to be able to reproduce the environment that you worked in. We discuss two topics in this section: exporting your environment and reproducing the environment.

"},{"location":"reference/python/virtual-environments/#exporting-your-virtual-environment","title":"Exporting your virtual environment","text":"

In order to reproduce your virtual environment, you need to export some information about your environment. Be sure to follow the instructions below while your environment is activated.

Virtualenv Anaconda

You will create a requirements.txt file, which essentially lists all of your python dependencies in one file:

Creating requirements file
pip freeze > requirements.txt\n

The pip freeze command prints all of your pip dependencies, and > requirements.txt redirects the output to a text file.

Anaconda uses configuration files to recreate an environment.

Windows macOS Linux

Execute the following command to create a file called environment.yml:

Create config file
conda env export > environment.yml\n

Then, open the environment.yml file and delete the line with prefix:.

Execute the following command to create a file called environment.yml:

Create config file
conda env export | grep -v \"^prefix: \" > environment.yml\n

Execute the following command to create a file called environment.yml:

Create config file
conda env export | grep -v \"^prefix: \" > environment.yml\n
"},{"location":"reference/python/virtual-environments/#reproducing-the-environment","title":"Reproducing the environment","text":"

You can reproduce your virtual environment when given the information about it. The steps above tell you how to extract the information, and now we will use that information to recreate the virtual environment. Remember to deactivate the current environment before making a new environment.

Virtualenv Anaconda

We use the requirements.txt file that we generated earlier to recreate the environment.

Recreate virtualenv environment
# Create the new environment\npython -m venv <NEW ENV NAME>\n\n# Activate the environment\nsource <NEW ENV NAME>/bin/activate\n\n# Install dependencies\npip install -r <PATH TO requirements.txt file>\n

We use the environment.yml file that we generated earlier to recreate the environment.

Recreate the conda environment
# Create the new environment with the dependencies\nconda env create -f <PATH TO environment.yml> -n <ENV NAME>\n
"},{"location":"reference/python/virtual-environments/#official-references","title":"Official references","text":"

In this section, we summarized what virtual environments are, why they are used, and how to use them. We did not cover all of the functions of virtual environments, but feel free to consult the official references to learn about virtual environments more in depth.

  • Virtualenv Reference
  • Anaconda Reference
"},{"location":"reference/sailing/ais_terms/","title":"AIS Terms","text":"

This section explains the most unfamiliar fields that we receive from the AIS.

"},{"location":"reference/sailing/ais_terms/#mmsi-aka-id","title":"MMSI a.k.a ID","text":"

A 9-digit, unique identification number for the ship.

"},{"location":"reference/sailing/ais_terms/#cog-course-over-ground","title":"COG: Course over Ground","text":"

The direction the boat is travelling, relative to the sea floor. This is the direction of the rate of change of the Track Made Good.

This is measured with the navigational angle convention, where 0\u00b0 is towards the North, and angles increase in the clockwise direction. If we make the slight simplification of neglecting the effect of the wind, then

  • If the boatspeed is positive and there is no current, the boat's Course over Ground will be the same as the Heading.
  • If the boatspeed is zero and there is positive current, the boat's Course over Ground will be the same direction as the current is flowing.
"},{"location":"reference/sailing/ais_terms/#sog-speed-over-ground","title":"SOG: Speed over Ground","text":"

The speed the boat is travelling at, relative to the sea floor. This is the magnitude of the rate of change of the Track Made Good.

\\(\\begin{align*} \\text{SoG} &= \\left|\\frac{d}{dt} \\overrightarrow{(\\text{Track Made Good})} \\right|\\\\ \\end{align*}\\)

If we make the slight simplification of neglecting the effect of the wind, then

  • If the boatspeed is positive and there is no current, the boat's Speed over Ground will be the same as the speed of water hitting your hand, if you were sitting on the boat and put your hand in the water.
  • If the boatspeed is zero and there is positive current, the boat's Speed over Ground will be the same speed as the current.
"},{"location":"reference/sailing/ais_terms/#rot-rate-of-turn","title":"RoT: Rate of Turn","text":"

The angular velocity of the boat (how fast it's turning), measured in degrees per minute.

"},{"location":"reference/sailing/boat_parts/","title":"Parts of a Sailboat","text":"

This page names some important parts of a sailboat, and explains what the part is for. Read the descriptions of the parts below, and refer to the image to see where the part fits in.

"},{"location":"reference/sailing/boat_parts/#hull","title":"Hull","text":"

The Hull is the \"boat\" part of the boat, which displaces water to create buoyancy. The following parts of the boat are attached to the hull:

  • Keel: The keel has a large mass on the end, which keeps the sailboat upright. The fin-like shape of the keel provides lateral resistance to prevent the boat from slipping sideways through the water.
  • Rudder: Raye has two rudders for redundancy. The rudders can angle side to side to steer the boat. To steer the boat effectively, the rudders need enough water flowing over them to create a pressure difference when they angle sideways. Controls sends commands to the rudder to steer the boat.

It is also helpful to know the names of the following \"regions\" of the hull:

  • Bow: The front of the boat.
  • Stern: The back of the boat.
    • Aft means \"backwards towards the stern\".
  • Starboard: The side of the boat which is on the right, for someone standing on the boat facing the bow.
  • Port: The side of the boat which is on the left, for someone standing on the boat facing the bow.
    • To remember which is which between starboard and port, remember that \"port\" and \"left\" both have 4 letters.

The image below shows a birds-eye view of the outline of a hull of a sailboat, where the \"regions\" of the hull are labeled.

"},{"location":"reference/sailing/boat_parts/#jib","title":"Jib","text":"

The Jib is the sail located near the bow, and is the smaller of the two sails.

  • Jib Sheet: In general, sheets are ropes that pull a sail in to the boat, and the jib sheet does this for the jib. On Raye, the jib sheet connects to the back bottom corner of the jib, through a pulley near the bottom of the mast to the Jib Winch. Most sailboats have two jib sheets, one on either side, but Raye is designed differently for autonomy.
  • The Jib Winch is a motor-driven device that tightens or pulls in the jib by pulling on the jib sheet. Controls sends commands to the winches.
  • The jib halyard: In general, a halyard is a rope that pulls a sail up. The jib halyard pulls up the jib. It connects to the top of the jib, runs through a pulley near the top of the mast, and is tied off near the bottom of the mast.
"},{"location":"reference/sailing/boat_parts/#mast","title":"Mast","text":"

The Mast is the long vertical pole which connects to hull. It holds up the sails and some instruments.

The following instruments are at the top of the mast:

  • One of the 3 Wind Sensors. The top of the mast is a good location to measure undisturbed wind. Pathfinding and Controls both use data from the wind sensors.
  • The AIS antenna. AIS (\"Autonomous Identification System\") is a system by which ships communicate their location, speed, and other information to surrounding ships via radio signals. Pathfinding uses AIS data to avoid other ships.

The mast is held upright by three lines:

  • The forestay connects the mast from the top of the jib to the bow, and runs parallel to the front edge of the jib.
  • The two shrouds connect the mast from the top of the jib to the outside edges of the hull slightly aft of the mast. There is one shroud on the startboard side and one on the port side.
"},{"location":"reference/sailing/boat_parts/#main-sail","title":"Main Sail","text":"

The Main Sail is the larger of the two sails, and is located aft of the mast. Most of the boat's propulsion comes from the main sail.

  • The Boom is the horizontal pole that holds the bottom corner of the main sail out from the mast.
  • Main Sheet is the rope that pulls the main sail in towards the center of the boat. It connects from the back end of the boom, through a pulley on the stern, to the Main Winch.
  • The Main Winch is a motor-driven device that pulls in the main sail by pulling on the main sheet. Controls sends commands to the main winch.
  • The main halyard is the line used to hoist the main sail.
"},{"location":"reference/sailing/boat_parts/#conclusion","title":"Conclusion","text":"

Hopefully this section helped you gain familiarity with some common sailing terms. It likely feels like this section contains a lot of new information. It's unrealistic to remember it all perfectly, but make an effort to remember the terms which are Bolded and Italicized.

"},{"location":"reference/sailing/boat_parts/#keywords-on-this-page","title":"Keywords on this Page","text":"
  • Hull
  • Keel
  • Rudder
  • Bow
  • Stern
  • Starboard
  • Port
  • Jib
  • Jib winch
  • Mast
  • Wind Sensor
  • AIS Antenna
  • Main Sail
  • Main Winch
"},{"location":"reference/sailing/miscellaneous/","title":"Miscellaneous Sailing Knowledge","text":"

This section covers some other useful information.

"},{"location":"reference/sailing/miscellaneous/#wind-direction-convention","title":"Wind Direction Convention","text":"

Generally speaking, there are two ways to use an angle to describe the wind direction.

  1. The angle tells you which way the wind is blowing towards. For example, 0\u00b0 means the wind is blowing from North to South.
  2. The angle tells you which way the wind is coming from. For example, 0\u00b0 means the wind is blowing from South to North.

In sailing, we normally talk about \"where the wind is coming from\". Somehow this ends up being more intuitive when talking about maneuvers or sail angle adjustments.

However, when describing the wind as a vector, it can make more sense for the vector to represent the actual speed and direction the air is flowing. Make sure to document which convention you are using in your work when its applicable, and don't be afraid to ask someone to clarify which convention they are using in their work.

"},{"location":"reference/sailing/miscellaneous/#navigation-terms","title":"Navigation Terms","text":""},{"location":"reference/sailing/miscellaneous/#heading","title":"Heading","text":"

In navigation generally (outside of Sailbot), the Heading is the direction the bow of the boat is pointing towards. Headings are typically (but not always at Sailbot) measured relative to true North in the clockwise direction.

"},{"location":"reference/sailing/miscellaneous/#bearing","title":"Bearing","text":"

A Bearing is used to describe one point in relation to another: the Bearing of point \"A\" from point \"B\" is the direction you would would look towards if you wanted to see point \"A\" while standing at point \"B\". A Range is the distance between points \"A\" and \"B\", so that a Bearing and Range together can locate point \"A\" relative to point \"B\" in polar co-ordinates. There are two main ways of measuring bearings:

  • A True Bearing is a bearing where the angle convention is as follows: 0\u00b0 is towards the North, angles increase in the clockwise direction, and angles are typically bounded within [0\u00b0, 360\u00b0)]
  • A Relative Bearing is a bearing where the angle convention is as follows: 0\u00b0 is straight forwards relative to the boat, and angle measurements increase in the clockwise direction. Angles may be bounded in [-180\u00b0, 180\u00b0) or [0\u00b0, 360\u00b0)

In the example below, the boat \"B\" has a Heading (H) of 30\u00b0. The True Bearing (\\(B_t\\)) of the Lighthouse \"A\" from the boat is 90\u00b0. The Relative Bearing (\\(B_r\\)) of the lighthouse from the boat is 60\u00b0.

"},{"location":"reference/sailing/miscellaneous/#track-made-good","title":"Track Made Good","text":"

Boats do not necessarily travel in the same direction as their Heading, due to the effects of ocean current and wind. The path the boat has traveled relative to the sea floor is called the Track Made Good. This is the same as if you measured motion compared to land or with a GPS.

"},{"location":"reference/sailing/miscellaneous/#heading-and-bearing-in-raye-project","title":"Heading and Bearing in Raye Project","text":"

In Sailbot's Raye project, Heading and Bearing are used to refer to different conventions for describing which way the boat is pointing. The following 3 pieces of information are needed to unambiguously define an angle measuring convention:

  • What does 0\u00b0 mean? If 0\u00b0 is North, is it towards the North or away from the North?
  • Do the angle measurements increase in the clockwise or counter-clockwise direction?
  • What range should the angles be bounded to? This part is often unimportant if the angles are only used in trigonometry functions.

Some common examples of angle measuring conventions which we use are:

  • 0\u00b0 means towards the East, angles increase in the counter-clockwise direction, and angles are bounded in [-180\u00b0, 180\u00b0). This is effectively the main angle convention used in most math courses.
  • 0\u00b0 means towards the North, angles increase in the clockwise direction, and angles are bounded in [0\u00b0, 360\u00b0). This angle convention is more commonly used by navigators.

The specific angle conventions which we call Heading and Bearing can be ambiguous, and may be subject to change, so they are deliberately omitted here. Refer to the applicable source code to determine what the angle conventions are.

"},{"location":"reference/sailing/miscellaneous/#true-apparent-and-boat-wind","title":"True, Apparent, and Boat Wind","text":"
  • True Wind is the wind vector (speed and direction) which you would measure while standing on land (or motionless at sea with unchanging GPS co-ordinates). In sailbot code, this may be referred to as Global Wind. When people refer to \"the wind\", they normally mean True Wind.
  • Boat Wind is the wind vector which you would measure while standing on a moving boat when the True Wind speed is 0. This means that boat wind always blows straight onto the bow of the boat, and the magnitude of the boat wind is equal to the speed of the boat.
  • Apparent Wind is the vector sum of the True Wind and the Boat Wind. This is the wind that you would measure while standing on a moving boat more generally, even if there is non-zero wind. The apparent wind is also what our wind sensors measure, and what our sails feel. In Sailbot code, Apparent Wind may be referred to as Measured Wind.

In the example below, suppose the wind is blowing from the North at 4 m/s, and suppose the boat is moving towards the East at 3 m/s.

  • The True Wind everywhere is blowing at 4 m/s from the North
  • The Boat Wind onboard the boat is blowing from the East at 3 m/s
  • The Apparent Wind onboard the boat is has a magnitude of \\(\\sqrt{3^2 + 4^2} = 5 \\text{ m/s}\\), and is coming from a true bearing of \\(\\arctan{(\\frac{3}{4})} = 36.9\u00b0\\).

"},{"location":"reference/sailing/miscellaneous/#tack","title":"Tack","text":"

In the Types of Turn page, we discussed how a Tack is a type of turn. Weirdly, the word \"tack\" actually has two more distinct meanings in sailing. The word \"Tack\" can refer to:

  • the type of turn, as covered before.
  • Starboard Tack vs Port Tack: The tack is basically the side of the boat which is further upwind. More thoroughly, the tack is the opposite side to the sail. This means that boats change tack when the sail switches sides.
    • In the diagram below, the 3 boats on the left of the diagram are on Starboard Tack, and the 3 boats on the right side are on Port Tack.
    • The tack of a boat in Irons is undefined.
    • The boat in the diagram on a run is on Port Tack. If the boat continued straight but the sail switched sides into the position shown by the dashed line, the boat would be on Starboard Tack.

  • Finally, the Tack can refer to particular region of the main sail. This is not important for software members.
"},{"location":"reference/sailing/miscellaneous/#keywords-on-this-page","title":"Keywords on this Page","text":"
  • Heading
  • Bearing
  • Track Made Good
  • Global Wind (aka True Wind)
  • Measured Wind (aka Apparent Wind)
  • Tack
"},{"location":"reference/sailing/overview/","title":"Sailing Knowledge Section Overview","text":"

In order to make high-quality contributions to Sailbot's Software teams, it is extremely helpful to have some understanding of sailing. This section introduces important parts of a sailboat, explains the 4 types of turns, discusses upwind and downwind sailing, and covers some other helpful knowledge.

In this section, terms which are Bolded and Italicized are the most important terms to know. These terms are listed at the bottom of each page. Terms that are only Italicized are other helpful sailing terms. Words that are bolded are meant to be emphasized, but are not necessarily considered important vocabulary.

"},{"location":"reference/sailing/overview/#tutorial","title":"Tutorial","text":""},{"location":"reference/sailing/points_of_sail/","title":"Points of Sail","text":"

In sailing, we sometimes talk about different angles that we can sail on with respect to the wind. Ranges of angles which are close together have special names. These ranges are called points of sail. The discussion below coveres the most important points of sail for software members to understand.

Notice how for higher points of sail (points of sail closer to straight into the wind), the sail is pulled tightly in to the boat. If the boat is on a lower point of sail, the sails should be let further out of the boat. For any point of sail, there is an optimum angle that the sail should be adjusted to. If the sails are adjusted too far in or too far out, the boat will not go as fast as it could if the sails were adjusted correctly.

"},{"location":"reference/sailing/points_of_sail/#irons","title":"Irons","text":"

The range of angles where the boat is roughly pointing straight into the wind are called Irons, or the No-Go Zone. If the boat is pointing in these directions, the sails will be flapping regardless of how the sheets are adjusted. When the sails are flapping, they are not catching the wind in a way that can propell the boat forwards. When the boat looses propulsion, water stops flowing over the rudder, and the boat loses steering. This is why we want our sailbots to avoid being stuck in irons.

"},{"location":"reference/sailing/points_of_sail/#upwind-sailing","title":"Upwind Sailing","text":"

If we want to sail to a destination that is not on too high or low of an angle upwind or downwind from our starting position, we can just point our boat in that direction, adjust our sails, and go there.

However, sometimes we want to sail to a destination that is straight upwind of our starting position. To get there, we will need to do upwind sailing. Since we can't point our boat directly into the wind, we need to sail on an angle on the edge of irons. We will need to tack back and forth every now and then if we want to go directly upwind. The point of sail on the edge of Irons is called Close Hauled.

"},{"location":"reference/sailing/points_of_sail/#downwind-sailing","title":"Downwind Sailing","text":"

Raye also avoids sailing straight downwind. This means that to reach a goal downwind of the starting position, we need to gybe back and forth in a zig-zag pattern. The point of sail straight downwind is called a run, and the next point of sail higher than a run is called a broad reach.

"},{"location":"reference/sailing/points_of_sail/#keywords-on-this-page","title":"Keywords on this Page","text":"
  • Irons (aka No-Go Zone)
  • Upwind Sailing
  • Close Hauled
  • Downwind Sailing
"},{"location":"reference/sailing/turning/","title":"Types of Turns","text":"

In sailing, there are 4 distinct types of turns. Read the descriptions below, and observe how they fit into the diagrams.

Note that any of these types of turn can be done in either the clockwise or counter-clockwise directions.

"},{"location":"reference/sailing/turning/#classifying-types-of-turns-summary","title":"Classifying Types Of Turns Summary","text":"

The following flowchart summarizes how to distinguish between different types of turns. Note:

  • to point higher means to steer your boat to point in a direction closer to straight into the wind
  • to point lower means to steer your boat to point in a direction closer towards to straight downwind
graph LR\n    B[Classify a Turn] --> C{Does the sail change<br/>sides during the turn?};\n    C --> |Yes| E{Which end of<br/>the boat is upwind<br/>during the turn?};\n    C --> |No| D{Does the<br/>boat point higher<br/>or lower at the end<br/>of the turn?};\n    D --> |Higher| F[Heading Up];\n    D --> |Lower| G[Bearing Off];\n    E --> |Bow| H[Tack];\n    E --> |Stern| I[Gybe];

The diagrams in this section show outlines of the hull of a boat and its main sail going through turns. As is common in these types of diagrams, assume that the wind is blowing down from the top of the screen unless there is an arrow that indicates otherwise.

"},{"location":"reference/sailing/turning/#heading-up","title":"Heading Up","text":"

When the boat makes any turn as follows, it is called Heading Up:

  • At the end of the turn, the boat is pointing higher.
  • Throughout the turn, the sails stay on the same side of the boat. In other words, the sails do not cross between the starboard and port sides.

Unlike some of the other turns listed here, heading up can be a large turn or a small course adjustment of just a few degrees.

The image below shows a boat heading up. Notice how the sail stays on the starboard side of the boat.

"},{"location":"reference/sailing/turning/#bearing-off","title":"Bearing Off","text":"

When the boat makes any turn as follows, it is called Bearing Off:

  • At the end of the turn, the boat is pointing lower.
  • Throughout the turn, the sails stays on the same side of the boat (port or starboard).

Like heading up, bearing off can be a small course adjustment.

"},{"location":"reference/sailing/turning/#tacking","title":"Tacking","text":"

When the boat makes any turn as follows, it is called a Tack or Tacking:

  • The sails change sides.
  • Through the turn, the wind hits the bow of the boat before the stern. You can also say that the bow is upwind or windward of the stern.

Notice how at some point throughout this turn, the boat will be pointing straight into the wind. While the boat points nearly straight into the wind, the sails don't generate any forward propulsion. This means that a tack must be a large (at least ~90\u00b0) turn all at once, so that the boat's momentum carries it through the range of angles where it does not get propulsion.

"},{"location":"reference/sailing/turning/#gybing","title":"Gybing","text":"

When the boat makes any turn as follows, it is called a Gybe or Gybing.

  • The sails change sides.
  • Through the turn, the wind hits the stern of the boat before the bow. You can also say that the bow of the boat is downwind or leeward of the stern.

When sailing on most angles relative to the wind, the sail is always blown to the downwind side of the boat. However, sailing nearly straight downwind, both sides of the boat are equally \"downwind\" relative to eachother. This means that the sail can be on either side of the boat.

The sail propells the boat throughout a gybe, so it is possible to conduct the turn more gradually than a tack. However, because the sail can be on either side, the sails can switch sides in an uncontrolled way as the boat moves in the waves. For this reason, Raye avoids sailing on angles close to straight downwind, and gybes by doing a quick ~60\u00b0 turn.

Note that \"gybe\" is the spelling used in Canadian and British english, whereas in American english it is spelled \"Jibe\"

"},{"location":"reference/sailing/turning/#combinations-of-turns","title":"Combinations of Turns","text":"

Of course, it is possible to do two or more of these types of turns in one continuous motion. What two types of turns does the boat do in the image below?

Answer: In the turn shown by the first arrow, the sail stays on the port side of the boat while it steers to point further downwind. This means that the first part of the maneuver is bearing off. In the next part of the maneuver, the sail changes sides and the stern of the boat is upwind of the bow. This part of the maneuver is a gybe.

"},{"location":"reference/sailing/turning/#keywords-on-this-page","title":"Keywords on this Page","text":"
  • Higher (in relation to pointing)
  • Lower (in relation to pointing)
  • Heading Up
  • Bearing Off
  • Tack
  • Gybe (aka Jibe)
"}]} \ No newline at end of file diff --git a/pr-450/sitemap.xml b/pr-450/sitemap.xml deleted file mode 100644 index cc24e3e04..000000000 --- a/pr-450/sitemap.xml +++ /dev/null @@ -1,175 +0,0 @@ - - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/about_us/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/overview/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/boat_simulator/overview/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/controller/overview/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/custom_interfaces/overview/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/local_pathfinding/overview/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/network_systems/overview/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/sailbot_workspace/overview/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/sailbot_workspace/scripts/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/sailbot_workspace/reference/deployment/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/sailbot_workspace/reference/docker_images/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/sailbot_workspace/reference/docs_site/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/sailbot_workspace/reference/launch_files/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/sailbot_workspace/reference/notebooks/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/sailbot_workspace/reference/parameters/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/sailbot_workspace/usage/help/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/sailbot_workspace/usage/how_to/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/sailbot_workspace/usage/setup/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/sailbot_workspace/usage/workflow/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/current/website/overview/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/docker/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/linux_commands/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/markdown/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/ros/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/cpp/differences/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/cpp/start/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/cpp/tools/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/github/advanced_git/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/github/github_actions/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/github/workflow/branches/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/github/workflow/issues/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/github/workflow/overview/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/github/workflow/pr/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/python/conventions/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/python/start/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/python/virtual-environments/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/sailing/ais_terms/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/sailing/boat_parts/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/sailing/miscellaneous/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/sailing/overview/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/sailing/points_of_sail/ - 2024-10-31 - - - https://UBCSailbot.github.io/sailbot_workspace/pr-450/reference/sailing/turning/ - 2024-10-31 - - \ No newline at end of file diff --git a/pr-450/sitemap.xml.gz b/pr-450/sitemap.xml.gz deleted file mode 100644 index 4dca1a633..000000000 Binary files a/pr-450/sitemap.xml.gz and /dev/null differ diff --git a/pr-450/stylesheets/extra.css b/pr-450/stylesheets/extra.css deleted file mode 100644 index cbf59debf..000000000 --- a/pr-450/stylesheets/extra.css +++ /dev/null @@ -1,45 +0,0 @@ -:root > * { - --md-primary-fg-color: #1665a2; - --md-primary-fg-color--light: #73a3c7; - --md-primary-fg-color--dark: #0d3d61; -} - -[data-md-color-scheme="slate"] { - --md-hue: 200; -} - -/* Styling for left navigation panel*/ -.md-sidebar__inner > .md-nav > .md-nav__list > .md-nav__item > .md-nav__link { color: #2f97ec; } -.md-nav__link:hover { color: #2f97ec; } -.md-nav__link.md-nav__link--active { color: #2f97ec; } - -/* Styling for links embedded in text*/ -.md-content__inner a {color: #2f97ec;} -.md-content__inner a:hover {color: #2f97ec;} -.md-content__inner a:focus {color: #2f97ec;} - -/* Styling for right navigation panel (Table of Contents) controlled by javascripts/table_of_contents_themes.js */ -nav.md-nav.md-nav--secondary > .md-nav__list > .md-nav__item > .md-nav__link {color: var(--md-table-of-contents-link-color);} -nav.md-nav.md-nav--secondary > .md-nav__list > .md-nav__item > .md-nav__link:hover {color: #2f97ec;} -nav.md-nav.md-nav--secondary > .md-nav__list > .md-nav__item > .md-nav__link.md-nav__link--passed.md-nav__link--active {color: #2f97ec;} -.md-nav__link--passed {color: var(--md-table-of-contents-link-color);} -.md-nav__link--passed:hover {color: #2f97ec;} - -/* Styling for embedded videos*/ -.video-wrapper { - position: relative; - display: block; - height: 0; - padding: 0; - overflow: hidden; - padding-bottom: 56.25%; -} -.video-wrapper > iframe { - position: absolute; - top: 0; - bottom: 0; - left: 0; - width: 100%; - height: 100%; - border: 0; -} diff --git a/versions.json b/versions.json index 9a8e20e80..96727934c 100644 --- a/versions.json +++ b/versions.json @@ -1,9 +1,4 @@ [ - { - "version": "pr-450", - "title": "pr-450", - "aliases": [] - }, { "version": "pr-449", "title": "pr-449",