Initial commit

.github/workflows/go.yml

@@ -0,0 +1,23 @@
+# This workflow will build a golang project
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go
+
+name: Go
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Go
+      uses: actions/setup-go@v5
+      with:
+        go-version: '1.23'
+
+    - name: Test
+      run: go test -cover -v ./...

.gitignore

@@ -0,0 +1,26 @@
+# Taken from URL: https://github.com/github/gitignore/blob/main/Go.gitignore
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+go.work
+go.work.sum
+
+# env file
+.env

Dockerfile

@@ -0,0 +1,18 @@
+# See URL: https://hub.docker.com/_/golang
+# Use the Go image to build the binary only
+FROM golang:1.23.0 AS builder
+ENV CGO_ENABLED=0
+ENV GOOS=linux
+WORKDIR /go/src/poker-evaluator/
+COPY . .
+
+RUN make
+
+# See URL: https://hub.docker.com/_/alpine
+# Use this image (~50MB) to run the "poker-evaluator-cli", as the Go image contains too much bloat,
+# which isn't needed for running the application in production and the image which can be uploaded
+# to a public/private Docker register is then small
+FROM alpine:3.20.3
+
+COPY --from=builder /go/src/poker-evaluator/poker-evaluator-cli ./
+ENTRYPOINT ["./poker-evaluator-cli"]

LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 SoftwareSpot Apps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Makefile

@@ -0,0 +1,22 @@
+# If the "VERSION" environment variable is not set, then use this value instead
+VERSION?=1.0.0
+TIME=$(shell date +%FT%T%z)
+GOVERSION=$(shell go version | awk '{print $$3}' | sed s/go//)
+
+LDFLAGS=-ldflags "\
+	-X github.com/softwarespot/poker-evaluator/internal/version.Version=${VERSION} \
+	-X github.com/softwarespot/poker-evaluator/internal/version.Time=${TIME} \
+	-X github.com/softwarespot/poker-evaluator/internal/version.User=${USER} \
+	-X github.com/softwarespot/poker-evaluator/internal/version.GoVersion=${GOVERSION} \
+	-s \
+	-w \
+"
+
+build:
+	@echo building to poker-evaluator-cli
+	@go build $(LDFLAGS) -o poker-evaluator-cli
+
+test:
+	@go test -cover -v ./...
+
+.PHONY: build test

README.md

@@ -0,0 +1,205 @@
+# Poker evaluator
+
+This project showcases my proficiency in Go by creating a clear and readable
+poker hand evaluator. The primary focus is on writing clean, maintainable code
+that effectively demonstrates the logic behind evaluating various poker hands.
+
+## Game play
+
+-   Provide 2 poker hands with 5 cards in each hand.
+-   Each card must start with the rank and then the suit e.g. `5C` as in the
+    `5 of Clubs`.
+-   Cards are case-insensitive. Therefore, `aH` is the same as `Ah` or `AH`.
+
+### Ranks (values)
+
+-   2-9 are the same, e.g. `2` or `8`
+-   10 is `T`
+-   Jack is `J`
+-   Queen is `Q`
+-   King is `K`
+-   Ace is `A`
+
+### Suits
+
+-   Clubs are `C`
+-   Diamonds are `D`
+-   Hearts are `H`
+-   Spades are `S`
+
+## Prerequisites
+
+-   Go 1.23.0 or above
+-   make (if you want to use the `Makefile` provided)
+-   Docker
+
+## Dependencies
+
+**IMPORTANT:** No 3rd party dependencies are used.
+
+I could easily use [Cobra](https://github.com/spf13/cobra) (and usually I do,
+because it allows me to write powerful CLIs), but I felt it was too much for
+such a tiny project. I only ever use dependencies when it's say an adapter for
+an external service e.g. Redis, MySQL or Prometheus.
+
+## Run not using Docker
+
+```bash
+go run . "AH AC AD QC QD" "QD QH QC AD AC"
+```
+
+Output the result as JSON, instead of text
+
+```bash
+go run . --json "AH AC AD QC QD" "QD QH QC AD AC"
+```
+
+or when using `make`
+
+```bash
+make
+
+# As text
+./poker-evaluator-cli "AH AC AD QC QD" "QD QH QC AD AC"
+
+# As JSON
+./poker-evaluator-cli --json "AH AC AD QC QD" "QD QH QC AD AC"
+```
+
+### Version
+
+Display the version of the application and exit.
+
+```bash
+make
+
+# As text
+./poker-evaluator-cli --version
+
+# As JSON
+./poker-evaluator-cli --json --version
+```
+
+### Help
+
+Display the help text and exit.
+
+```bash
+make
+
+./poker-evaluator-cli --help
+```
+
+## Run using Docker
+
+1. Build the Docker image with the tag `poker-evaluator`.
+
+```bash
+docker build -t poker-evaluator .
+```
+
+2. Run the Docker image with the provided arguments.
+
+```bash
+# As text
+docker run --rm poker-evaluator "AH AC AD QC QD" "QD QH QC AD AC"
+
+# As JSON
+docker run --rm poker-evaluator --json "AH AC AD QC QD" "QD QH QC AD AC"
+```
+
+### Version
+
+Display the version of the application and exit.
+
+```bash
+# As text
+docker run --rm poker-evaluator --version
+
+# As JSON
+docker run --rm poker-evaluator --json --version
+```
+
+### Help
+
+Display the help text and exit.
+
+```bash
+docker run --rm poker-evaluator --help
+```
+
+## Tests
+
+Tests are written as [Table-Driven Tests](https://go.dev/wiki/TableDrivenTests).
+
+```bash
+go test -cover -v ./...
+```
+
+or when using `make`
+
+```bash
+make test
+```
+
+### Coverage
+
+For the `poker` package (found under `internal`), the test coverage is about
+97%. This isn't to say there aren't any "bugs" 😀, but that it's better than 0%
+and is an indication that it's passing the
+[Poker rules](https://en.wikipedia.org/wiki/List_of_poker_hands).
+
+```bash
+go test -cover -v github.com/softwarespot/poker-evaluator/internal/poker
+```
+
+### Linting
+
+Docker
+
+```bash
+docker run --rm -v $(pwd):/app -w /app golangci/golangci-lint:latest golangci-lint run -v --tests=false --disable-all -E durationcheck,errorlint,exhaustive,gocritic,gosimple,ineffassign,misspell,predeclared,revive,staticcheck,unparam,unused,whitespace --max-issues-per-linter=10000 --max-same-issues=10000
+```
+
+Local
+
+```bash
+golangci-lint run --tests=false --disable-all -E durationcheck,errorlint,exhaustive,gocritic,gosimple,ineffassign,misspell,predeclared,revive,staticcheck,unparam,unused,whitespace --max-issues-per-linter=10000 --max-same-issues=10000
+```
+
+## Additional information
+
+This section documents any additional information which might be deemed
+important for the reviewer.
+
+### Decisions made
+
+-   Despite using 1.23.0+ and the `slices` pkg being available, I have opted not
+    to use it, and instead went for how I've been writing Go code before the
+    `slices` pkg existed. Although for production code, I have started to use it
+    where applicable.
+-   I haven't used an assertion library, as I have never used one in production
+    code and have opted for creating my own simple test helpers.
+-   The `Hand.Compare()` func returns an `int` as an alias type of `Winner`, as I
+    thought since it returns 3 exclusive values, that it should be similar to that
+    of [https://pkg.go.dev/cmp#Compare].
+-   Naming is hard, so I have tried my best to name funcs, structs, variables
+    etc... as best I can.
+
+### Project setup
+
+Commands used to setup the project's directory.
+
+```bash
+mkdir poker-evaluator
+cd poker-evaluator
+go mod init github.com/softwarespot/poker-evaluator
+touch README.md
+touch LICENSE
+touch Dockerfile
+```
+
+### License
+
+The code has been licensed under the [MIT](https://opensource.org/license/mit)
+license.

cmd/execute.go

@@ -0,0 +1,24 @@
+package cmd
+
+import "flag"
+
+func Execute(args []string) error {
+	var showHelp bool
+	flagBoolVarP(&showHelp, "help", "h", false, "Display the help text and exit")
+
+	var showVersion bool
+	flagBoolVarP(&showVersion, "version", "v", false, "Display the version of the application and exit")
+
+	var asJSON bool
+	flagBoolVarP(&asJSON, "json", "j", false, "Output the result as JSON")
+	flag.Parse()
+
+	if showHelp {
+		cmdHelp()
+		return nil
+	}
+	if showVersion {
+		return cmdVersion(asJSON)
+	}
+	return cmdPlay(args, asJSON)
+}

cmd/help.go

@@ -0,0 +1,23 @@
+package cmd
+
+import "fmt"
+
+func cmdHelp() {
+	helpText := `Usage: ./poker-evaluator-cli [OPTIONS] HAND1 HAND2
+
+Compare two poker hands and determine the winning hand (unless there is a tie).
+
+Arguments:
+  HAND1       The first hand to evaluate (e.g. "AH AC AD QC QD").
+  HAND2       The second hand to evaluate (e.g. "QD QH QC AD AC").
+
+Options:
+  -h, --help      Show this help text and exit.
+  -v, --version   Display the version of the application and exit.
+  -j, --json      Output the result as JSON.
+
+Examples:
+  ./poker-evaluator-cli "AH AC AD QC QD" "QD QH QC AD AC"
+  ./poker-evaluator-cli --json "AH AC AD QC QD" "QD QH QC AD AC"`
+	fmt.Println(helpText)
+}

cmd/helpers.go

@@ -0,0 +1,11 @@
+package cmd
+
+import (
+	"flag"
+)
+
+// The naming has been taken from "pflag" i.e. used in "cobra". URL: https://pkg.go.dev/github.com/spf13/pflag#BoolVarP
+func flagBoolVarP(p *bool, name, shorthand string, value bool, usage string) {
+	flag.BoolVar(p, name, value, usage)
+	flag.BoolVar(p, shorthand, value, usage)
+}