feat: export encode option as Config; update documentation; add an ex…

…ample for NewWithConfig API

Makefile

@@ -9,3 +9,6 @@ release-linux:
 	- mkdir -p draft/linux
 	GOOS=linux GOARCH=amd64 go build -o draft/linux/go-qrcode ./cmd/go-qrcode.go
 	cd draft/linux && tar -zcvf ../go-qrcode.linux.tar.gz .
+
+test-all:
+	go test -v --count=1 ./...

README.md

@@ -95,9 +95,21 @@ func WithBuiltinImageEncoder(format formatTyp) ImageOption
 func WithCustomImageEncoder(encoder ImageEncoder) ImageOption
 ```
 
-use options in `New` and `NewWithSpecV`. 
+use options in `New` and `NewWithConfig`. 
+> NOTICE: NewWithSpecV is deprecated
 ```go
-func New("text", WithQRWidth(x)) // x is uint8 (0 - 255)
+import (
+	qrcode "github.com/yeqown/go-qrcode"
+)
+
+// generating QR Code with source text and output image options.
+qrc, _ := qrcode.New("text", WithQRWidth(x)) // x is uint8 (0 - 255)
+
+// OR generating QR Code with specified ErrorCorrection Level and Encode Mode,
+// output image options are also available.
+qrc, _ := qrcode.NewWithConfig("text", config, WithQRWidth(x))
+
+qrc.Save("path/to/qrcode.png")
 ```
 
 following are some shots:

encoder_option.go

@@ -1,19 +1,23 @@
 package qrcode
 
-func defaultOutputEncoderOption() *outputEncodingOptions {
-	return &outputEncodingOptions{
-		encMode: EncModeAuto,
-		ecLevel: ErrorCorrectionQuart,
+// DefaultConfig with EncMode = EncModeAuto, EcLevel = ErrorCorrectionQuart
+func DefaultConfig() *Config {
+	return &outputEncodingOption{
+		EncMode: EncModeAuto,
+		EcLevel: ErrorCorrectionQuart,
 	}
 }
 
-type outputEncodingOptions struct {
+// Config alias of outputEncodingOption.
+type Config = outputEncodingOption
 
-	// encMode specifies which encMode to use
-	encMode encMode
+type outputEncodingOption struct {
 
-	// ecLevel specifies which ecLevel to use
-	ecLevel ecLevel
+	// EncMode specifies which encMode to use
+	EncMode encMode
+
+	// EcLevel specifies which ecLevel to use
+	EcLevel ecLevel
 
 	// PS: The version (which implicitly defines the byte capacity of the qrcode) is dynamically selected at runtime
 }

example/simple/main.go

@@ -0,0 +1,18 @@
+package main
+
+import "github.com/yeqown/go-qrcode"
+
+func main() {
+	config := qrcode.Config{
+		EncMode: qrcode.EncModeByte,
+		EcLevel: qrcode.ErrorCorrectionQuart,
+	}
+	qrc, err := qrcode.NewWithConfig("github.com/yeqown/qo-qrcode", &config, qrcode.WithQRWidth(40))
+	if err != nil {
+		panic(err)
+	}
+
+	if err = qrc.Save("./a.png"); err != nil {
+		panic(err)
+	}
+}

qrcode.go

@@ -24,27 +24,7 @@ var (
 
 // New generate a QRCode struct to create
 func New(text string, opts ...ImageOption) (*QRCode, error) {
-	dst := defaultOutputImageOption()
-	for _, opt := range opts {
-		opt.apply(dst)
-	}
-
-	encOpts := defaultOutputEncoderOption()
-
-	qrc := &QRCode{
-		content:      text,
-		mode:         encOpts.encMode,
-		ecLv:         encOpts.ecLevel,
-		needAnalyze:  true,
-		outputOption: dst,
-	}
-
-	// initialize QRCode instance
-	if err := qrc.init(); err != nil {
-		return nil, err
-	}
-
-	return qrc, nil
+	return NewWithConfig(text, nil, opts...)
 }
 
 // NewWithSpecV generate a QRCode struct with
@@ -74,22 +54,22 @@ func NewWithSpecV(text string, ver int, ecLv ecLevel, opts ...ImageOption) (*QRC
 
 // NewWithConfig generate a QRCode struct with
 // specified `ver`(QR version) and `ecLv`(Error Correction level)
-func NewWithConfig(text string, encOpts *outputEncodingOptions, opts ...ImageOption) (*QRCode, error) {
-	dstImgOptions := defaultOutputImageOption()
+func NewWithConfig(text string, encOpts *Config, opts ...ImageOption) (*QRCode, error) {
+	dst := defaultOutputImageOption()
 	for _, opt := range opts {
-		opt.apply(dstImgOptions)
+		opt.apply(dst)
 	}
 
 	if encOpts == nil {
-		encOpts = defaultOutputEncoderOption()
+		encOpts = DefaultConfig()
 	}
 
 	qrc := &QRCode{
 		content:      text,
-		mode:         encOpts.encMode,
-		ecLv:         encOpts.ecLevel,
+		mode:         encOpts.EncMode,
+		ecLv:         encOpts.EcLevel,
 		needAnalyze:  true,
-		outputOption: dstImgOptions,
+		outputOption: dst,
 	}
 	// initialize QRCode instance
 	if err := qrc.init(); err != nil {
@@ -181,7 +161,7 @@ func (q *QRCode) init() error {
 func (q *QRCode) analyze() error {
 	if q.mode == EncModeAuto {
 		// choose encode mode (num, alpha num, byte, Japanese)
-	q.mode = analyzeEncodeModeFromRaw(q.rawData)
+		q.mode = analyzeEncodeModeFromRaw(q.rawData)
 	}
 
 	// analyze content to decide version etc.

qrcode_test.go

@@ -3,6 +3,8 @@ package qrcode
 import (
 	"os"
 	"testing"
+
+	"github.com/stretchr/testify/assert"
 )
 
 func TestNew(t *testing.T) {
@@ -57,9 +59,9 @@ func TestNewWithSpecV(t *testing.T) {
 
 func TestNewWithConfig(t *testing.T) {
 
-	encOpts := defaultOutputEncoderOption()
-	encOpts.ecLevel = ErrorCorrectionLow
-	encOpts.encMode = EncModeNumeric
+	encOpts := DefaultConfig()
+	encOpts.EcLevel = ErrorCorrectionLow
+	encOpts.EncMode = EncModeNumeric
 
 	qrc, err := NewWithConfig("1234567", encOpts, WithQRWidth(20))
 	if err != nil {
@@ -81,6 +83,22 @@ func TestNewWithConfig(t *testing.T) {
 	}
 }
 
+// Test_NewWithConfig_UnmatchedEncodeMode NewWithConfig will panic while encMode is
+// not matched to Config.EncMode, for example:
+// cfg.EncMode is EncModeAlphanumeric but source text is bytes encoding.
+func Test_NewWithConfig_UnmatchedEncodeMode(t *testing.T) {
+	cfg := DefaultConfig()
+	cfg.EncMode = EncModeAlphanumeric
+
+	assert.Panics(t, func() {
+		_, err := NewWithConfig("abcs", cfg, WithQRWidth(20))
+		if err != nil {
+			t.Errorf("could not generate QRCode: %v", err)
+			t.Fail()
+		}
+	})
+}
+
 func Test_New_WithOutputOption_bg_fg_width(t *testing.T) {
 	qrc, err := New("Test_New_WithOutputOption_bg_fg_width",
 		WithBgColorRGBHex("#b8de6f"),