From ed417318f9fd56915d63bf37363c7e0178c3e536 Mon Sep 17 00:00:00 2001
From: Becojo <Becojo@users.noreply.github.com>
Date: Sat, 16 Nov 2024 10:43:06 -0500
Subject: [PATCH] docs: add examples

---
 README.md        | 70 +++++++++++++++++++++++++++++++++++++++++-------
 cmd/semsearch.go | 20 +++++++-------
 2 files changed, 70 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 1246229..4611bfb 100644
--- a/README.md
+++ b/README.md
@@ -7,14 +7,14 @@ CLI interface to create and run Semgrep rules that are more complex that what th
 Usage: semsearch [options]
 
 Pattern options:
-  -l,   --language <language>              Add a language to the rule
-  -p,   --pattern <pattern>                Pattern to search for
-  -pi,  --pattern-inside <pattern>         Pattern to search for inside the matched pattern
-  -pni, --pattern-not-inside <pattern>     Pattern to search for not inside the matched pattern
-  -pr,  --pattern-regex <pattern>          Pattern to search for using a regex
-  -pnr, --pattern-not-regex <pattern>      Pattern to search for not using a regex
-  -mr,  --metavariable-regex <name=regex>  Metavariable to search for using a regex
-  -fm,  --focus-metavariable <name>        Metavariable to focus on
+  -l,   --language <language>               Add a language to the rule
+  -p,   --pattern <pattern>                 Pattern to search for
+  -pi,  --pattern-inside <pattern>          Pattern to search for inside the matched pattern
+  -pni, --pattern-not-inside <pattern>      Pattern to search for not inside the matched pattern
+  -pr,  --pattern-regex <pattern>           Pattern to search for using a regex
+  -pnr, --pattern-not-regex <pattern>       Pattern to search for not using a regex
+  -mr,  --metavariable-regex <name=regex>   Metavariable to search for using a regex
+  -fm,  --focus-metavariable <name>         Metavariable to focus on
 
 Pattern group options:
   -ps,  --patterns                          Start a pattern group where all patterns must match
@@ -35,6 +35,56 @@ Rule options:
 
 
 Other options:
-  --debug                                  Debug mode
-  --export                                 Output the rule instead of running Semgrep
+  --debug                                   Debug mode
+  --export                                  Output the rule instead of running Semgrep
 ```
+
+## Examples
+
+
+### Search functions related to `*State`
+``` sh
+semsearch -l go -fm F -pe -p 'func ($S *State) $F(...) {...}'  -p 'func $F(...) *State {...}'
+```
+
+``` sh
+    cmd/semsearch.go
+    ❯❱ id
+          123┆ func NewState() *State {
+             ┆----------------------------------------
+          135┆ func (s *State) Args() []string {
+             ┆----------------------------------------
+          161┆ func (s *State) AddCondition(cond Condition) {
+             ┆----------------------------------------
+          166┆ func (s *State) Build(args []string) {
+             ┆----------------------------------------
+          276┆ func (s *State) Tempfile(name string) (*os.File, error) {
+             ┆----------------------------------------
+          285┆ func (s *State) Cleanup() {
+             ┆----------------------------------------
+          291┆ func (s *State) Prepare() {
+             ┆----------------------------------------
+          308┆ func (s *State) Exec() {
+```
+
+
+### Output the Semgrep rule instead of running it
+
+``` sh
+semsearch -l go -fm F -pe -p 'func ($S *State) $F(...) {...}'  -p 'func $F(...) *State {...}' --export
+```
+
+``` yaml
+rules:
+- id: id
+  patterns:
+  - focus-metavariable: $F
+  - pattern-either:
+    - pattern: func ($S *State) $F(...) {...}
+    - pattern: func $F(...) *State {...}
+  severity: WARNING
+  message: ""
+  languages:
+  - go
+```
+
diff --git a/cmd/semsearch.go b/cmd/semsearch.go
index ca5325c..214c7c2 100644
--- a/cmd/semsearch.go
+++ b/cmd/semsearch.go
@@ -12,14 +12,14 @@ import (
 var help string = `Usage: semsearch [options]
 
 Pattern options:
-  -l,   --language <language>              Add a language to the rule
-  -p,   --pattern <pattern>                Pattern to search for
-  -pi,  --pattern-inside <pattern>         Pattern to search for inside the matched pattern
-  -pni, --pattern-not-inside <pattern>     Pattern to search for not inside the matched pattern
-  -pr,  --pattern-regex <pattern>          Pattern to search for using a regex
-  -pnr, --pattern-not-regex <pattern>      Pattern to search for not using a regex
-  -mr,  --metavariable-regex <name=regex>  Metavariable to search for using a regex
-  -fm,  --focus-metavariable <name>        Metavariable to focus on
+  -l,   --language <language>               Add a language to the rule
+  -p,   --pattern <pattern>                 Pattern to search for
+  -pi,  --pattern-inside <pattern>          Pattern to search for inside the matched pattern
+  -pni, --pattern-not-inside <pattern>      Pattern to search for not inside the matched pattern
+  -pr,  --pattern-regex <pattern>           Pattern to search for using a regex
+  -pnr, --pattern-not-regex <pattern>       Pattern to search for not using a regex
+  -mr,  --metavariable-regex <name=regex>   Metavariable to search for using a regex
+  -fm,  --focus-metavariable <name>         Metavariable to focus on
 
 Pattern group options:
   -ps,  --patterns                          Start a pattern group where all patterns must match
@@ -40,8 +40,8 @@ Rule options:
 
 
 Other options:
-  --debug                                  Debug mode
-  --export                                 Output the rule instead of running Semgrep
+  --debug                                   Debug mode
+  --export                                  Output the rule instead of running Semgrep
 `
 
 var shortcuts = map[string]string{