Update documentation.

README.md

@@ -1,4 +1,4 @@
-# kata 形 🤺
+# Kata 形 🤺
 [![GoDoc](https://godoc.org/github.com/arvenil/kata?status.svg)](https://pkg.go.dev/github.com/arvenil/kata?tab=doc)
 [![Go Report Card](https://goreportcard.com/badge/github.com/arvenil/kata)](https://goreportcard.com/report/github.com/arvenil/kata)
 [![BuildStatus](https://github.com/arvenil/kata/workflows/go/badge.svg)](https://github.com/arvenil/kata/actions?query=workflow%3Ago)
@@ -9,3 +9,104 @@
 > referring to a detailed choreographed pattern of movements made to be practised alone,
 > and within groups and in unison when training.
 > It is practised in Japanese martial arts as a way to memorize and perfect the movements being executed.
+
+# Install
+
+```bash
+brew tap arvenil/kata
+brew install kata
+```
+
+# Kata02
+
+In computer science, binary algorithms, also known as half-interval algorithms, logarithmic algorithms, or binary chop,
+is a algorithms algorithm that finds the position of a target value within a sorted array.
+Binary algorithms compares the target value to the middle element of the array.
+If they are not equal, the half in which the target cannot lie is eliminated
+and the algorithms continues on the remaining half, again taking the middle element to compare to the target value,
+and repeating this until the target value is found.
+If the algorithms ends with the remaining half being empty, the target is not in the array.
+
+```bash
+$ kata02
+Usage of kata02:
+  -algorithm string
+        choose from: exponential, interpolation, loop, loopslicing, recursive, recursiveslicing, standard (default "interpolation")
+  -haystack value
+        comma-separated, sorted, list of integers e.g. 1,5,7
+  -needle int
+        an integer to search for in haystack e.g. 5
+```
+
+```bash
+$ kata02 --needle 5 --haystack 1,3,5,7
+2
+```
+
+```bash
+$ make bench
+...
+pkg: github.com/arvenil/kata/bsearch/algorithms
+BenchmarkSearch/interpolation-12                 2656200               449 ns/op
+BenchmarkSearch/loop-12                          3742628               327 ns/op
+BenchmarkSearch/exponential-12                   3817282               308 ns/op
+BenchmarkSearch/loopslicing-12                   4105732               293 ns/op
+BenchmarkSearch/recursive-12                     2615310               459 ns/op
+BenchmarkSearch/recursiveslicing-12              3311100               358 ns/op
+BenchmarkSearch/standard-12                      2132502               558 ns/op
+...
+```
+
+# Kata19
+
+A word-ladder puzzle begins with two words,
+and to solve the puzzle one must find a chain of other words to link the two,
+in which two adjacent words (that is, words in successive steps) differ by one letter.
+
+```bash
+$ kata19
+Usage of kata19:
+  -d string
+        path to dictionary (default "/usr/share/dict/words")
+  -json
+        print results as json
+  -p value
+        two words separated by comma e.g. dog,cat
+  -template string
+        pretty-print results using a Go template
+```
+
+```bash
+$ kata19 -p dog,cat -p gold,lead
+start  end   word-ladder            error (if any)
+dog    cat   [dog dot cot cat]     
+gold   lead  [gold goad load lead]  
+```
+
+```json
+$ kata19 -p above,below -json | jq .
+[
+  {
+    "Start": "above",
+    "End": "below",
+    "Words": [
+      "above",
+      "amove",
+      "amoke",
+      "smoke",
+      "smoky",
+      "sooky",
+      "booky",
+      "booly",
+      "bolly",
+      "bally",
+      "balli",
+      "balai",
+      "balao",
+      "baloo",
+      "balow",
+      "below"
+    ]
+  }
+]
+```

bsearch/algorithms/algorithm.go

@@ -5,6 +5,6 @@ package algorithms
 // The slice must be sorted in ascending order.
 // Algorithm has name.
 type Algorithm interface {
-	Search(n int, v []int) int
+	Search(n int, h []int) int
 	Name() string
 }

bsearch/doc.go

@@ -1,8 +1,6 @@
 /*
 Package bsearch provides different implementations of binary algorithms.
 
-Wikipedia
-
 In computer science, binary algorithms, also known as half-interval algorithms, logarithmic algorithms, or binary chop,
 is a algorithms algorithm that finds the position of a target value within a sorted array.
 Binary algorithms compares the target value to the middle element of the array.
@@ -11,6 +9,8 @@ and the algorithms continues on the remaining half, again taking the middle elem
 and repeating this until the target value is found.
 If the algorithms ends with the remaining half being empty, the target is not in the array.
 
+https://en.wikipedia.org/wiki/Binary_search_algorithm
+
 Algorithm
 
 Binary algorithms works on sorted arrays.
@@ -32,8 +32,6 @@ All variables follow idiomatic naming as follows:
 
 Pseudocode
 
-https://en.wikipedia.org/wiki/Binary_search_algorithm
-
     function binary_search(A, n, T) is
         L := 0
         R := n − 1
@@ -47,6 +45,8 @@ https://en.wikipedia.org/wiki/Binary_search_algorithm
                 return m
         return unsuccessful
 
+https://en.wikipedia.org/wiki/Binary_search_algorithm
+
 CodeKata
 
 http://codekata.com/kata/kata02-karate-chop/

cmd/kata02/main.go

@@ -16,19 +16,28 @@ var (
 )
 
 func init() {
-	flag.IntVar(&needle, "needle", 0, "an integer to algorithms for")
-	flag.Var(&haystack, "haystack", "comma-separated, sorted, list of integers")
+	flag.IntVar(&needle, "needle", 0, "an integer to search for in haystack e.g. 5")
+	flag.Var(&haystack, "haystack", "comma-separated, sorted, list of integers e.g. 1,5,7")
 	name := algorithms.Slice[0].Name()
 	flag.StringVar(&algorithm, "algorithm", name, fmt.Sprintf("choose from: %s", algorithms.Slice))
 }
 
 func main() {
 	flag.Parse()
 
+	// At least one flag needs to be passed otherwise print Usage().
+	if flag.NFlag() == 0 {
+		flag.Usage()
+		os.Exit(1)
+	}
+
+	// Check if algorithm is valid.
 	a, ok := algorithms.Map[algorithm]
 	if !ok {
 		fmt.Printf("algorithm '%s' doesn't exist, choose from: %s\n", algorithm, algorithms.Slice)
 		os.Exit(1)
 	}
+
+	// Search for needle in haystack.
 	fmt.Println(a.Search(needle, haystack))
 }

cmd/kata19/main.go

@@ -16,11 +16,18 @@ var (
 
 func init() {
 	flag.StringVar(&dictionary, "d", "/usr/share/dict/words", "path to dictionary")
-	flag.Var(&pairs, "p", "two words separated by comma e.g. 'dog,cat'")
+	flag.Var(&pairs, "p", "two words separated by comma e.g. dog,cat")
 }
 
 func main() {
 	flag.Parse()
+
+	// At least one flag needs to be passed otherwise print Usage().
+	if flag.NFlag() == 0 {
+		flag.Usage()
+		os.Exit(1)
+	}
+
 	if len(pairs) == 0 {
 		fmt.Println("at least one pair of words is required e.g. '-p dog,cat'")
 		os.Exit(1)

doc.go

@@ -1,4 +1,68 @@
 /*
-Package kata .
+Kata 形🤺
+
+Kata is a Japanese word (型 or 形) meaning literally "form"
+referring to a detailed choreographed pattern of movements made to be practised alone,
+and within groups and in unison when training.
+It is practised in Japanese martial arts as a way to memorize and perfect the movements being executed.
+
+Commands
+
+kata02
+
+In computer science, binary algorithms, also known as half-interval algorithms, logarithmic algorithms, or binary chop,
+is a algorithms algorithm that finds the position of a target value within a sorted array.
+Binary algorithms compares the target value to the middle element of the array.
+If they are not equal, the half in which the target cannot lie is eliminated
+and the algorithms continues on the remaining half, again taking the middle element to compare to the target value,
+and repeating this until the target value is found.
+If the algorithms ends with the remaining half being empty, the target is not in the array.
+
+	Usage of kata02:
+	  -algorithm string
+			choose from: exponential, interpolation, loop, loopslicing, recursive, recursiveslicing, standard (default "interpolation")
+	  -haystack value
+			comma-separated, sorted, list of integers e.g. 1,5,7
+	  -needle int
+			an integer to search for in haystack e.g. 5
+
+kata19
+
+A word-ladder puzzle begins with two words,
+and to solve the puzzle one must find a chain of other words to link the two,
+in which two adjacent words (that is, words in successive steps) differ by one letter.
+
+	Usage of kata19:
+	  -d string
+			path to dictionary (default "/usr/share/dict/words")
+	  -json
+			print results as json
+	  -p value
+			two words separated by comma e.g. dog,cat
+	  -template string
+			pretty-print results using a Go template
+
+Benchmark
+
+cmd/kata02:
+	pkg: github.com/arvenil/kata/bsearch/algorithms
+	BenchmarkSearch/interpolation-12                 2656200               449 ns/op
+	BenchmarkSearch/loop-12                          3742628               327 ns/op
+	BenchmarkSearch/exponential-12                   3817282               308 ns/op
+	BenchmarkSearch/loopslicing-12                   4105732               293 ns/op
+	BenchmarkSearch/recursive-12                     2615310               459 ns/op
+	BenchmarkSearch/recursiveslicing-12              3311100               358 ns/op
+	BenchmarkSearch/standard-12                      2132502               558 ns/op
+
+cmd/kata19:
+	$ time kata19 -p dog,cat -p godo,loto -p kot,pies -p gold,lead -p above,below -p soup,rice
+	start  end    word-ladder                                                                                        error (if any)
+	dog    cat    [dog dot cot cat]
+	godo   loto   []                                                                                                 could not find 'godo' in dictionary
+	kot    pies   []                                                                                                 words 'kot'(3) and 'pies'(4) have different length
+	gold   lead   [gold goad load lead]
+	above  below  [above amove amoke smoke smoky sooky booky booly bolly bally balli balai balao baloo balow below]
+	soup   rice   [soup roup roue role rile rice]
+	kata19 -p dog,cat -p godo,loto -p kot,pies -p gold,lead -p above,below -p   5.44s user 0.50s system 197% cpu 3.010 total
 */
 package kata

ladder/doc.go

@@ -1,12 +1,12 @@
 /*
 Package ladder implements word-ladder puzzle solver.
 
-Wikipedia
-
 A word-ladder puzzle begins with two words,
 and to solve the puzzle one must find a chain of other words to link the two,
 in which two adjacent words (that is, words in successive steps) differ by one letter.
 
+https://en.wikipedia.org/wiki/Word_ladder
+
 Algorithm
 
 A* (pronounced "A-star") is an informed algorithms algorithm, or a best-first algorithms,
@@ -67,10 +67,10 @@ Pseudocode
         // Open set is empty but goal was never reached
         return failure
 
-Links
+https://en.wikipedia.org/wiki/A*_search_algorithm
+
+CodeKata
 
     http://codekata.com/kata/kata19-word-chains/
-    https://en.wikipedia.org/wiki/Word_ladder
-    https://en.wikipedia.org/wiki/A*_search_algorithm
 */
 package ladder