Don't use PRNG (for portability to other languages); add documentation

Author: ethanjli

CHANGELOG.md

@@ -10,3 +10,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Programmatic generation of US English word lists.
+- Generation of machine names from 32-bit serial numbers.

README.md

@@ -7,7 +7,29 @@ Devices often assign a (pseudo-)unique serial number to each unit. However, each
 
 ## Usage
 
-TBD
+First, you will need to download machine-name, which is available as a single self-contained executable file. You should visit this repository's [releases page](https://github.com/PlanktoScope/machine-name/releases/latest) and download an archive file for your platform and CPU architecture; for example, on a Raspberry Pi 4, you should download the archive named `machine-name{version number}_linux_arm.tar.gz` (where the version number should be substituted). You can extract the machine-name binary from the archive using a command like:
+```
+tar -xzf machine-name{version number}_{os}_{cpu architecture}.tar.gz machine-name
+```
+
+Then you may need to move the machine-name binary into a directory in your system path, or you can just run the machine-name binary in your current directory (in which case you should replace `machine-name` with `./machine-name` in the commands listed below).
+
+Once you have machine-name, you should run it as follows:
+```
+machine-name name --format=hex --sn=0xd6b82659
+```
+but replacing `0xd6b82659` with a 32-bit hex string representing a serial number. The program will then print the machine name corresponding to that serial number. For example, the following serial numbers will result in the following machine names:
+
+| Serial Number | Machine Name          |
+|---------------|-----------------------|
+| `0xdeadc0de`  | metal-slope-23501     |
+| `0xd6b82659`  | chain-list-27764      |
+| `0x0`         | able-account-0        |
+| `0x1`         | small-ball-26954      |
+| `0x2`         | safe-minute-6738      |
+| `0x3`         | linen-opinion-33692   |
+| `0x4`         | conscious-pocket-1684 |
+| `0x8123`      | clear-field-33719     |
 
 ## Licensing
 

cmd/machinename/main.go

@@ -5,7 +5,6 @@ import (
 	"io/fs"
 	"log"
 	"math/bits"
-	"math/rand"
 	"os"
 	"strconv"
 	"strings"
@@ -69,16 +68,7 @@ var nameCmd = &cli.Command{
 		if err != nil {
 			return errors.Wrapf(err, "couldn't load wordlists for language '%s", c.String("lang"))
 		}
-		shuffleWordlist(first, 0)
-		shuffleWordlist(second, 1)
-		firstSize := uint32(len(first))
-		secondSize := uint32(len(second))
-		quotient := shuffle(parsed)
-		firstIndex := quotient % firstSize
-		quotient /= firstSize
-		secondIndex := quotient % secondSize
-		quotient /= secondSize
-		fmt.Printf("%s-%s-%d\n", first[firstIndex], second[secondIndex], quotient)
+		fmt.Println(computeName(parsed, first, second))
 		return nil
 	},
 }
@@ -127,55 +117,63 @@ func loadWordlist(lang fs.FS, file string) ([]string, error) {
 	return words, nil
 }
 
-func shuffleWordlist(wordlist []string, randSeed int64) {
-	rng := rand.New(rand.NewSource(randSeed)) //nolint:gosec // We need a PRNG to shuffle reproducibly
-	rng.Shuffle(len(wordlist), func(i, j int) {
-		atI := wordlist[i]
-		atJ := wordlist[j]
-		wordlist[i] = atJ
-		wordlist[j] = atI
-	})
+func computeName(sn uint32, first []string, second []string) string {
+	firstSize := uint32(len(first))
+	secondSize := uint32(len(second))
+	quotient := shuffle(sn)
+	firstIndex := quotient % firstSize
+	quotient /= firstSize
+	secondIndex := quotient % secondSize
+	quotient /= secondSize
+	return fmt.Sprintf("%s-%s-%d\n", first[firstIndex], second[secondIndex], quotient)
 }
 
+const (
+	shuffleShift8 = 8
+	shuffleShift4 = 4
+	shuffleShift2 = 2
+	shuffleShift1 = 1
+	shuffleMask8  = 0x0000ff00
+	shuffleMask4  = 0x00f000f0
+	shuffleMask2  = 0x0c0c0c0c
+	shuffleMask1  = 0x22222222
+)
+
 // shuffle performs a one-to-one mapping of the serial number so that consecutive numbers are no
 // longer close to each other.
-//
-//nolint:gomnd // We need a bunch of well-defined bit shifts and masks for this algorithm
 func shuffle(x uint32) uint32 {
 	// This code was copied from the Hacker's Delight website at
 	// https://web.archive.org/web/20160405214331/http://hackersdelight.org/hdcodetxt/shuffle.c.txt
 	// which is licensed released to the public domain - for details, refer to
 	// https://web.archive.org/web/20160309224818/http://www.hackersdelight.org/permissions.htm
-	t := (x ^ (x >> 8)) & 0x0000ff00
-	x = x ^ t ^ (t << 8)
-	t = (x ^ (x >> 4)) & 0x00f000f0
-	x = x ^ t ^ (t << 4)
-	t = (x ^ (x >> 2)) & 0x0c0c0c0c
-	x = x ^ t ^ (t << 2)
-	t = (x ^ (x >> 1)) & 0x22222222
-	x = x ^ t ^ (t << 1)
+	t := (x ^ (x >> shuffleShift8)) & shuffleMask8
+	x = x ^ t ^ (t << shuffleShift8)
+	t = (x ^ (x >> shuffleShift4)) & shuffleMask4
+	x = x ^ t ^ (t << shuffleShift4)
+	t = (x ^ (x >> shuffleShift2)) & shuffleMask2
+	x = x ^ t ^ (t << shuffleShift2)
+	t = (x ^ (x >> shuffleShift1)) & shuffleMask1
+	x = x ^ t ^ (t << shuffleShift1)
 	x = bits.Reverse32(x)
 	return x
 }
 
 /*
 // unshuffle inverts the shuffle operation.
-//
-//nolint:gomnd // We need a bunch of well-defined bit shifts and masks for this algorithm
 func unshuffle(x uint32) uint32 {
 	// This code was copied from the Hacker's Delight website at
 	// https://web.archive.org/web/20160405214331/http://hackersdelight.org/hdcodetxt/shuffle.c.txt
 	// which is licensed released to the public domain - for details, refer to
 	// https://web.archive.org/web/20160309224818/http://www.hackersdelight.org/permissions.htm
 	x = bits.Reverse32(x)
-	t := (x ^ (x >> 1)) & 0x22222222
-	x = x ^ t ^ (t << 1)
-	t = (x ^ (x >> 2)) & 0x0c0c0c0c
-	x = x ^ t ^ (t << 2)
-	t = (x ^ (x >> 4)) & 0x00f000f0
-	x = x ^ t ^ (t << 4)
-	t = (x ^ (x >> 8)) & 0x0000ff00
-	x = x ^ t ^ (t << 8)
+	t := (x ^ (x >> shuffleShift1)) & shuffleMask1
+	x = x ^ t ^ (t << shuffleShift1)
+	t = (x ^ (x >> shuffleShift2)) & shuffleMask2
+	x = x ^ t ^ (t << shuffleShift2)
+	t = (x ^ (x >> shuffleShift4)) & shuffleMask4
+	x = x ^ t ^ (t << shuffleShift4)
+	t = (x ^ (x >> shuffleShift8)) & shuffleMask8
+	x = x ^ t ^ (t << shuffleShift8)
 	return x
 }
 */