Initial v0.0.0 Release

CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing
+
+## Requirements
+
+- [Go](https://golang.org/dl/) 1.19 or higher
+
+## Getting Started
+
+1. Fork the repository and clone it locally
+2. Run `go mod download` to download dependencies
+3. Run `go test ./...` to run all tests
+
+## Testing
+
+The tests are located in the `matchers`, `devices`, `platforms` and `browser` packages. The tests are using the `assets/test` directory to load the user agents data.
+
+Package follows BDD style test cases. The tests are using the [GoConvey](https://github.com/smartystreets/goconvey) library to write BDD style tests.
+
+## Adding a new browser support
+
+Every browser implements the `BrowserMatcher` interface.
+
+1. Add the file to the `matchers` package.
+2. Add the new browser the list of matchers in `browser.go`. Make sure the order of the matchers is correct. The order of the matchers is important because the first matcher that returns `true` will be used.
+3. Add specific tests for the new browser in the `matchers` package. Make sure to test all the possible user agents for the browser. You can use [this](https://developers.whatismybrowser.com/useragents/explore/) website to find user agents for the browser.
+4. Add the user agents data to [matchers.yml](assets/test/matchers.yml) file.
+5. Add all necerssary functions to `Browser` struct in `browser.go` file.
+
+## Adding a new device support
+
+Every device implements the `DeviceMatcher` interface.
+
+1. Add the file to the `devices` package.
+2. Add the new device to list of `DeviceMatcher` in `device.go`. Make sure the order of the matchers is correct. The order of the matchers is important because the first matcher that returns `true` will be used.
+3. Add specific tests for the new device in the `devices` package. Make sure to test all the possible user agents for the device. You can use [this](https://developers.whatismybrowser.com/useragents/explore/) website to find user agents for the device.
+4. Add the user agents data to [devices.yml](assets/test/devices.yml) file.
+5. Add all necerssary functions to `Device` struct in `device.go` file.
+
+## Adding a new platform support
+
+Every platform implements the `PlatformMatcher` interface.
+
+1. Add the file to the `platforms` package.
+2. Add the new platform to list of `PlatformMatcher` in `platform.go`. Make sure the order of the matchers is correct. The order of the matchers is important because the first matcher that returns `true` will be used.
+3. Add specific tests for the new platform in the `platforms` package. Make sure to test all the possible user agents for the platform. You can use [this](https://developers.whatismybrowser.com/useragents/explore/) website to find user agents for the platform.
+4. Add the user agents data to [platforms.yml](assets/test/platforms.yml) file.
+5. Add all necerssary functions to `Platform` struct in `platform.go` file.
+
+## Adding a new known bot support
+
+1. Add the new bot to [known_bots.yml](assets/internal/known_bots.yml).

README.md

@@ -1,60 +1,157 @@
-# Browser: A browser detection in Go (Golang)
+# Browser
+
+![](logo.png)
 
 ## Why?
 
-I wanted a package to detect the browser, device and platform from the user agent string. I found nothing similar in Go (Golang), so I wrote my package.
+> *Why not?*
 
-### Inspiration
+You need to detect the browser, device and platform from the user agent string in many use cases. I have personally come across the following use cases:
 
-This package is inspired by the ruby gem [fnando/browser](https://github.com/fnando/browser). I have used the ruby gem in my previous projects and I really liked it. All the credit goes to the author of the ruby gem who has done a great job. After much procrastination, I finally decided to write a similar package in Go.
+1. You want to render different HTML for different browsers, devices or platforms.
+2. You want to render OG tags for scraping bots and social media sites.
+3. You want to log the browser, device or platform for your analytics.
+4. You want your backend to behave differently when a Google bot crawls your site for SEO.
 
-## Design
+I wanted a relatively extensible package that I could use in all the above use cases. So, I decided to write this package.
+
+## Inspiration
 
-I have tried to keep the architecture as similar as possible to the ruby gem. But made changes where I felt it was necessary as per the Go standards.
+The ruby gem [fnando/browser](https://github.com/fnando/browser) inspires this package. I have used the gem in some of my previous projects and liked it. All the credit goes to the author of the ruby gem, who has done a great job.
+
+## Design
 
-The package is divided into three parts:
+I have kept the design as similar as possible to the gem but made changes where I felt necessary per the Go.
 
-- **browser**: This package contains the code to detect the browser.
-- **device**: This package contains the code to detect the device from the user agent string.
-- **platform**: This package contains the code to detect the platform from the user agent string.
+The following are the sub-packages:
 
-### Browser
+- **matchers**: This package defines all the browser matchers.
+- **devices**: This package defines all the device matchers.
+- **platforms**: This package defines all the platform matchers.
+- **bots**: This package defines all the bots matchers.
 
 A `Matcher` interface defines a matching behaviour for a user agent string.
 
 ```go
 type Matchers interface {
-    Match() bool
-    Name() string
+    Match() bool    // Match returns true if the user agent string matches the matcher.
+    Name() string   // Name returns the name of the matcher.
 }
 ```
 
-`BrowserMatchers` interface matches the user agent string with the browser. Any new browser can be added by implementing the `BrowserMatchers` interface.
+### Matchers
+
+`BrowserMatcher` interface matches the user agent string with the browser. Implement the `BrowserMatcher` interface to add a new browser.
 
 ```go
 type BrowserMatcher interface {
     Matcher
-    Version() string // FullVersion returns the full version of the browser.
+    Version() string // Version returns the full version of the browser.
 }
 ```
 
-### Device
+### Devices
 
-`DeviceMatchers` interface matches the user agent string with the device. Any new device can be added by implementing the `DeviceMatchers` interface.
+`DeviceMatcher` interface matches the user agent string with the device. Implement the `DeviceMatcher` interface to add a new device.
 
 ```go
 type DeviceMatcher interface {
     Matcher
 }
 ```
 
-### Platform
+### Platforms
 
-`PlatformMatchers` interface matches the user agent string with the platform. Any new platform can be added by implementing the `PlatformMatchers` interface.
+`PlatformMatcher` interface matches the user agent string with the platform. Implement the `PlatformMatcher` interface to add a new device.
 
 ```go
 type PlatformMatcher interface {
     Matcher
     Version() string // Version returns the version of the platform.
 }
 ```
+
+### Bots
+
+`BotMatcher` interface matches the user agent string with the bot. Implement the `BotMatcher` interface to add a new bot.
+
+```go
+type BotMatcher interface {
+    Matcher
+}
+```
+
+### Browser Struct
+
+`Browser` struct abstracts a lot of functionality. It uses the `BrowserMatcher`, `DeviceMatcher`, `PlatformMatcher` and `BotMatcher` interfaces to match the user agent string with the browser, device, platform and bot respectively. All the matchers are executed in the order they are defined in the `Browser` struct. The first matcher that returns `true` will be used.
+
+A ton of helper functions are defined in the `Browser` struct to make it easy to use.
+
+## Usage
+
+```go
+go get github.com/dineshgowda24/browser
+```
+
+### Browser Detection
+
+```go
+b, err := browser.NewBrowser("Mozilla/5.0 (Linux; Android 10; SM-A205U) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.210 Mobile Safari/537.36")
+ if err != nil {
+  // handle error
+ }
+
+ // browser level information
+ fmt.Println(b.Name())           // Chrome
+ fmt.Println(b.Version())        // 90.0.4430.210
+ fmt.Println(b.ShortVersion())   // 90
+ fmt.Println(b.IsBrowserKnown()) // true
+ fmt.Println(b.IsChrome())       // true
+
+ // device level information
+ fmt.Println(b.Device().Name())      // Samsung SM-A205U
+ fmt.Println(b.Device().IsTablet())  // false
+ fmt.Println(b.Device().IsSamsung()) // true
+
+ // platform level information
+ fmt.Println(b.Platform().Name())         // Android
+ fmt.Println(b.Platform().Version())      // 10
+ fmt.Println(b.Platform().IsAndroidApp()) // false
+
+ // bot level information
+ fmt.Println(b.Bot().Name())  // ""
+ fmt.Println(b.Bot().IsBot()) // false
+```
+
+### Bot Detection
+
+```go
+b, err := browser.NewBrowser("APIs-Google (https://developers.google.com/webmasters/APIs-Google.html)")
+if err != nil {
+   // handle error
+}
+
+// browser level information
+fmt.Println(b.Name())           // Unknown Browser
+fmt.Println(b.Version())        // 0.0
+fmt.Println(b.ShortVersion())   // 0
+fmt.Println(b.IsBrowserKnown()) // false
+fmt.Println(b.IsUnknown())      // true
+
+// bot level information
+fmt.Println(b.Bot().Name())  // "APIs-Google"
+fmt.Println(b.Bot().IsBot()) // true
+fmt.Println(b.Bot().Why())   // *bots.Known
+```
+
+## Contributing
+
+If you want to contribute to this project, please read the [CONTRIBUTING.md](CONTRIBUTING.md) file.
+
+## Issues
+
+If you find any issues with this package, please raise an issue. I will fix it as soon as possible. Please read the `Contributing` section if you want to resolve the issue and contribute.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.