feat: add a Decode function

This is just an improvement to the API ergonomics, to avoid having to
declare a CMW object before invoking the deserialisation logic.

Consequently, the existing (*CMW)Deserialize method has been deprecated
and will be retired at some point in the future.

Signed-off-by: Thomas Fossati <[email protected]>

Author: thomas-fossati

cmw.go

@@ -273,6 +273,19 @@ func (o *CMW) UnmarshalCBOR(b []byte) error {
 	return nil
 }
 
+// Decode decodes a JSON- or CBOR-encoded CMW to a CMW object.
+// On success, a pointer to the newly allocated CMW structure is returned.
+func Decode(b []byte) (*CMW, error) {
+	var o CMW
+	if err := o.Deserialize(b); err != nil {
+		return nil, err
+	}
+	return &o, nil
+}
+
+// Deserialize deserializes a JSON- or CBOR-encoded CMW into the target CMW object.
+//
+// Deprecated: use Decode instead.
 func (o *CMW) Deserialize(b []byte) error {
 	if len(b) == 0 {
 		return errors.New("empty buffer")

collection_test.go

@@ -166,21 +166,19 @@ func Test_Collection_CBOR_Deserialize_and_iterate(t *testing.T) {
 	}
 }
 
-func Test_Collection_Deserialize_JSON_ok(t *testing.T) {
+func Test_Collection_Decode_JSON_ok(t *testing.T) {
 	tv := mustReadFile(t, "testdata/collection-ok.json")
 
-	var c CMW
-	err := c.Deserialize(tv)
+	c, err := Decode(tv)
 	assert.NoError(t, err)
 	assert.Equal(t, KindCollection, c.GetKind())
 	assert.Equal(t, FormatJSONCollection, c.GetFormat())
 }
 
-func Test_Collection_Deserialize_CBOR_ok(t *testing.T) {
+func Test_Collection_Decode_CBOR_ok(t *testing.T) {
 	tv := mustReadFile(t, "testdata/collection-cbor-ok.cbor")
 
-	var c CMW
-	err := c.Deserialize(tv)
+	c, err := Decode(tv)
 	assert.NoError(t, err)
 	assert.Equal(t, KindCollection, c.GetKind())
 	assert.Equal(t, FormatCBORCollection, c.GetFormat())

example_test.go

@@ -116,8 +116,6 @@ func Example_decode_JSON_record() {
 }
 
 func Example_roundtrip_JSON_collection() {
-	var o CMW
-
 	ex := []byte(`{
   "bretwaldadom": [
     "application/eat-ucs+cbor",
@@ -143,7 +141,7 @@ func Example_roundtrip_JSON_collection() {
   ]
 }`)
 
-	err := o.Deserialize(ex)
+	o, err := Decode(ex)
 	if err != nil {
 		log.Fatalf("unmarshal JSON collection failed: %v", err)
 	}

monad_test.go

@@ -82,9 +82,7 @@ func Test_Deserialize_monad_ok(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			var actual CMW
-
-			err := actual.Deserialize(tt.tv)
+			actual, err := Decode(tt.tv)
 			assert.NoError(t, err)
 			err = actual.monad.validate()
 			assert.NoError(t, err)
@@ -410,8 +408,7 @@ func Test_UnmarshalCBOR_tag_ko(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			var cmw CMW
-			err := cmw.Deserialize(tt.tv)
+			_, err := Decode(tt.tv)
 			assert.EqualError(t, err, tt.expectedErr)
 		})
 	}