Sway Ref: Style guide pattern matching (FuelLabs#4655)

Laskidiii · Jun 16, 2023 · a413feb · a413feb
1 parent e4a5f3d
commit a413feb
Show file tree

Hide file tree

Showing 6 changed files with 120 additions and 46 deletions.
diff --git a/docs/reference/src/code/Forc.lock b/docs/reference/src/code/Forc.lock
@@ -1,27 +1,27 @@
 [[package]]
 name = 'annotation_style'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'annotations'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'arrays'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'assertions'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'asset_operations'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'associated-consts'
@@ -30,30 +30,30 @@ source = 'member'
 [[package]]
 name = 'booleans'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'bytes'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'call'
 source = 'member'
 dependencies = [
     'contract_interface',
-    'std',
+    'std path+from-root-0F28276288D2432C',
 ]
 
 [[package]]
 name = 'call_data'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'comments'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'constants'
@@ -62,184 +62,198 @@ source = 'member'
 [[package]]
 name = 'contract_interface'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'control_flow'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'core'
 source = 'path+from-root-0F28276288D2432C'
 
+[[package]]
+name = 'core'
+source = 'path+from-root-D62A8C57DD8D2801'
+
 [[package]]
 name = 'counter'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'empty_storage_init'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'enum-advanced'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'enum_style'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'enums'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'fizzbuzz'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'functions'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'hashing'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'interface'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'letter_casing'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'logging'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'my_lib'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'my_library'
 source = 'member'
 dependencies = [
     'my_other_library',
-    'std',
+    'std path+from-root-0F28276288D2432C',
 ]
 
 [[package]]
 name = 'my_other_library'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'namespace'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'numerics'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'ownership'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
+
+[[package]]
+name = 'pattern_matching'
+source = 'member'
+dependencies = ['std git+https://github.com/fuellabs/sway?tag=v0.40.1#48104d0bde0d343154a5bc39a310092532883235']
 
 [[package]]
 name = 'reading_writing_to_storage'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'simple_predicate'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'simple_script'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
+
+[[package]]
+name = 'std'
+source = 'git+https://github.com/fuellabs/sway?tag=v0.40.1#48104d0bde0d343154a5bc39a310092532883235'
+dependencies = ['core path+from-root-D62A8C57DD8D2801']
 
 [[package]]
 name = 'std'
 source = 'path+from-root-0F28276288D2432C'
-dependencies = ['core']
+dependencies = ['core path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'storage_init'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'storage_map'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'storage_vec'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'store_get'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'string_issue'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'strings'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'struct_shorthand'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'structs'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'tuples'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'variables'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
 
 [[package]]
 name = 'wallet'
 source = 'member'
 dependencies = [
     'interface',
-    'std',
+    'std path+from-root-0F28276288D2432C',
 ]
 
 [[package]]
 name = 'wallet_example'
 source = 'member'
-dependencies = ['std']
+dependencies = ['std path+from-root-0F28276288D2432C']
diff --git a/docs/reference/src/code/Forc.toml b/docs/reference/src/code/Forc.toml
@@ -27,6 +27,7 @@ members = [
   "language/style-guide/annotation_style",
   "language/style-guide/enum_style",
   "language/style-guide/letter_casing",
+  "language/style-guide/pattern_matching",
   "language/style-guide/struct_shorthand",
   "language/traits/associated-consts",
   "language/variables",

diff --git a/docs/reference/src/code/language/style-guide/pattern_matching/.gitignore b/docs/reference/src/code/language/style-guide/pattern_matching/.gitignore
@@ -0,0 +1,2 @@
+out
+target
diff --git a/docs/reference/src/code/language/style-guide/pattern_matching/Forc.toml b/docs/reference/src/code/language/style-guide/pattern_matching/Forc.toml
@@ -0,0 +1,7 @@
+[project]
+authors = ["Fuel Labs <[email protected]>"]
+entry = "lib.sw"
+license = "Apache-2.0"
+name = "pattern_matching"
+
+[dependencies]
diff --git a/docs/reference/src/code/language/style-guide/pattern_matching/src/lib.sw b/docs/reference/src/code/language/style-guide/pattern_matching/src/lib.sw
@@ -0,0 +1,34 @@
+library;
+
+#[allow(dead_code)]
+enum Shape {
+    Triangle: (),
+    Quadrilateral: (),
+    Pentagon: (),
+    Hexagon: (),
+    Heptagon: (),
+}
+
+#[allow(dead_code)]
+// ANCHOR: style_match_unnamed
+fn unnamed_case(shape: Shape) {
+    let value = match shape {
+        Shape::Triangle => 3,
+        Shape::Quadrilateral => 4,
+        Shape::Pentagon => 5,
+        _ => 0,
+    };
+}
+// ANCHOR_END: style_match_unnamed
+
+#[allow(dead_code)]
+// ANCHOR: style_match_named
+fn named_case(shape: Shape) {
+    let value = match shape {
+        Shape::Triangle => 3,
+        Shape::Quadrilateral => 4,
+        Shape::Pentagon => 5,
+        _invalid_shape => 0,
+    };
+}
+// ANCHOR_END: style_match_named
diff --git a/docs/reference/src/documentation/language/style-guide/pattern-matching.md b/docs/reference/src/documentation/language/style-guide/pattern-matching.md
@@ -1,3 +1,19 @@
 # Pattern Matching
 
-> TODO: throw away variables `_` and catch all case names
+The following examples present pattern matching using the [`match`](../../language/control-flow/match/index.md) keyword for the catch-all case.
+
+## Encouraged
+
+The `_` is used for the catch-all to indicate the important cases have been defined above and the last case is not important enough to warrant a name.
+
+```sway
+{{#include ../../../code/language/style-guide/pattern_matching/src/lib.sw:style_match_unnamed}}
+```
+
+## Alternative
+
+We may apply an appropriate name to provide context to the reader; however, unless it provides additional information the preferred usage is defined in the [`encouraged`](#encouraged) case.
+
+```sway
+{{#include ../../../code/language/style-guide/pattern_matching/src/lib.sw:style_match_named}}
+```