Add GECOM encoder (#16)

README.md

@@ -1,14 +1,20 @@
 # gedcom
 
-Go package to parse GEDCOM files.
+Go package to parse and produce GEDCOM files.
 
 [![Test Status](https://github.com/iand/gedcom/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/iand/gedcom/actions/workflows/test.yml)
 [![Go Report Card](https://goreportcard.com/badge/github.com/iand/gedcom)](https://goreportcard.com/report/github.com/iand/gedcom)
 [![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white)](https://pkg.go.dev/github.com/iand/gedcom)
 
+## Purpose
+
+The `gedcom` package provides tools for working with GEDCOM files in Go. GEDCOM (Genealogical Data Communication) is a standard format used for exchanging genealogical data between software applications. This package includes functionality for both parsing existing GEDCOM files and generating new ones.
+
+The package includes a streaming decoder for reading GEDCOM files and an encoder for creating GEDCOM files from Go structs.
+
 ## Usage
 
-The package provides a Decoder with a single Decode method that returns a Gedcom struct. Use the NewDecoder method to create a new decoder.
+The package provides a `Decoder` with a single `Decode` method that returns a Gedcom struct. Use the `NewDecoder` method to create a new decoder.
 
 This example shows how to parse a GEDCOM file and list all the individuals. In this example the entire input file is read into memory, but the decoder is streaming so it should be able to deal with very large files: just pass an appropriate Reader.
 
@@ -39,17 +45,33 @@ The structures produced by the Decoder are in [types.go](types.go) and correspon
 
 This package does not implement the entire GEDCOM specification, I'm still working on it. It's about 80% complete which is enough for about 99% of GEDCOM files. It has not been extensively tested with non-ASCII character sets nor with pathological cases such as the [GEDCOM 5.5 Torture Test Files](http://www.geditcom.com/gedcom.html).
 
+### Using the Encoder
+
+In addition to decoding GEDCOM files, this package also provides an Encoder for generating GEDCOM files from the structs in [types.go](types.go). You can create an encoder using the `NewEncoder` method, which writes to an `io.Writer`.
+
+To see an example of how to use the encoder, refer to [encoder_example.go](encoder_example.go). This example illustrates how to create individual and family records, populate them with data, and encode them into a valid GEDCOM file.
+
+You can run the example using the following command:
+
+```bash
+go run encoder_example.go
+```
+
 ## Installation
 
 Simply run
 
-	go get github.com/iand/gedcom
+Run the following in the directory containing your project's `go.mod` file:
+
+```bash
+go get github.com/iand/gedcom@latest
+```
 
-Documentation is at [http://godoc.org/github.com/iand/gedcom](http://godoc.org/github.com/iand/gedcom)
+Documentation is at [https://pkg.go.dev/github.com/iand/gedcom](https://pkg.go.dev/github.com/iand/gedcom)
 
 ## Authors
 
-* [Ian Davis](http://github.com/iand) - <http://iandavis.com/>
+* [Ian Davis](http://github.com/iand)
 
 
 ## Contributors

cmp_test.go

@@ -0,0 +1,84 @@
+package gedcom
+
+import "github.com/google/go-cmp/cmp"
+
+// familyXrefComparer is a Comparer that compares FamilyLinkRecords only by Family xref
+var familyXrefComparer = cmp.Comparer(func(a, b *FamilyLinkRecord) bool {
+	if a == nil {
+		return b == nil
+	}
+
+	if b == nil {
+		return a == nil
+	}
+
+	if a.Family == nil {
+		return b.Family == nil
+	}
+
+	if b.Family == nil {
+		return a.Family == nil
+	}
+
+	return a.Family.Xref == b.Family.Xref
+})
+
+// individualXrefComparer is a Comparer that compares IndividualRecords only by xref
+var individualXrefComparer = cmp.Comparer(func(a, b *IndividualRecord) bool {
+	if a == nil {
+		return b == nil
+	}
+
+	if b == nil {
+		return a == nil
+	}
+
+	return a.Xref == b.Xref
+})
+
+// sourceXrefComparer is a Comparer that compares CitationRecords only by source xref
+var sourceXrefComparer = cmp.Comparer(func(a, b *CitationRecord) bool {
+	if a == nil {
+		return b == nil
+	}
+
+	if b == nil {
+		return a == nil
+	}
+
+	if a.Source == nil {
+		return b.Source == nil
+	}
+
+	if b.Source == nil {
+		return a.Source == nil
+	}
+
+	return a.Source.Xref == b.Source.Xref
+})
+
+// eventIgnoreComparer is a Comparer that ignores event comparisons
+var eventIgnoreComparer = cmp.Comparer(func(a, b []*EventRecord) bool {
+	return true
+})
+
+// mediaFileNameCompare is a Comparer that compares MediaRecord only by first file name
+var mediaFileNameCompare = cmp.Comparer(func(a, b *MediaRecord) bool {
+	if a == nil {
+		return b == nil
+	}
+
+	if b == nil {
+		return a == nil
+	}
+
+	if len(a.File) == 0 {
+		return len(b.File) == 0
+	}
+
+	if len(b.File) == 0 {
+		return len(a.File) == 0
+	}
+
+	return a.File[0].Name == b.File[0].Name
+})

decoder.go

@@ -225,6 +225,8 @@ func makeRootParser(d *Decoder, g *Gedcom) parser {
 				obj := d.media(xref)
 				g.Media = append(g.Media, obj)
 				d.pushParser(makeMediaParser(d, obj, level))
+			case "TRLR":
+				g.Trailer = &Trailer{}
 			default:
 				g.UserDefined = append(g.UserDefined, UserDefinedTag{
 					Tag:   tag,

decoder_test.go

@@ -68,11 +68,6 @@ func TestIndividual(t *testing.T) {
 		t.Fatalf("unexpected error: %v", err)
 	}
 
-	// Create a comparison option that ignores events
-	eventOpt := cmp.Comparer(func(a, b []*EventRecord) bool {
-		return true
-	})
-
 	// Create a comparison option that compares just names
 	nameOpt := cmp.Comparer(func(a, b *NameRecord) bool {
 		if a == nil {
@@ -86,69 +81,6 @@ func TestIndividual(t *testing.T) {
 		return a.Name == b.Name
 	})
 
-	// Create a comparison option that compares families by xref
-	familyOpt := cmp.Comparer(func(a, b *FamilyLinkRecord) bool {
-		if a == nil {
-			return b == nil
-		}
-
-		if b == nil {
-			return a == nil
-		}
-
-		if a.Family == nil {
-			return b.Family == nil
-		}
-
-		if b.Family == nil {
-			return a.Family == nil
-		}
-
-		return a.Family.Xref == b.Family.Xref
-	})
-
-	// Create a comparison option that compares citations by source xref only
-	sourceOpt := cmp.Comparer(func(a, b *CitationRecord) bool {
-		if a == nil {
-			return b == nil
-		}
-
-		if b == nil {
-			return a == nil
-		}
-
-		if a.Source == nil {
-			return b.Source == nil
-		}
-
-		if b.Source == nil {
-			return a.Source == nil
-		}
-
-		return a.Source.Xref == b.Source.Xref
-	})
-
-	// Create a comparison option that compares media files by name only
-	fileOpt := cmp.Comparer(func(a, b *MediaRecord) bool {
-		if a == nil {
-			return b == nil
-		}
-
-		if b == nil {
-			return a == nil
-		}
-
-		if len(a.File) == 0 {
-			return len(b.File) == 0
-		}
-
-		if len(b.File) == 0 {
-			return len(a.File) == 0
-		}
-
-		return a.File[0].Name == b.File[0].Name
-	})
-
 	individuals := []*IndividualRecord{
 		{
 			Xref: "PERSON1",
@@ -308,7 +240,7 @@ func TestIndividual(t *testing.T) {
 		},
 	}
 
-	if diff := cmp.Diff(individuals, g.Individual, eventOpt, familyOpt, nameOpt, sourceOpt, fileOpt); diff != "" {
+	if diff := cmp.Diff(individuals, g.Individual, nameOpt, eventIgnoreComparer, familyXrefComparer, sourceXrefComparer, mediaFileNameCompare); diff != "" {
 		t.Errorf("submitter mismatch (-want +got):\n%s", diff)
 	}
 }