Breaking changes: changed the function signature for 4 exported functions

- Change
    `func (f *File) AddVBAProject(bin string) error`
    to
    `func (f *File) AddVBAProject(file []byte) error`
- Change
    `func (f *File) GetComments() (map[string][]Comment, error)`
    to
    `func (f *File) GetComments(sheet string) ([]Comment, error)`
- Change
    `func (f *File) AddTable(sheet, rangeRef string, opts *TableOptions) error`
    to
    `func (f *File) AddTable(sheet string, table *Table) error`
- Change
    `func (sw *StreamWriter) AddTable(rangeRef string, opts *TableOptions) error`
    to
    `func (sw *StreamWriter) AddTable(table *Table) error`
- Rename exported data type `TableOptions` to `Table`
- Simplify the assert statements in the unit tests
- Update documents for the functions
- Update unit tests

Author: xuri

adjust_test.go

@@ -11,24 +11,24 @@ import (
 func TestAdjustMergeCells(t *testing.T) {
 	f := NewFile()
 	// Test adjustAutoFilter with illegal cell reference
-	assert.EqualError(t, f.adjustMergeCells(&xlsxWorksheet{
+	assert.Equal(t, f.adjustMergeCells(&xlsxWorksheet{
 		MergeCells: &xlsxMergeCells{
 			Cells: []*xlsxMergeCell{
 				{
 					Ref: "A:B1",
 				},
 			},
 		},
-	}, rows, 0, 0), newCellNameToCoordinatesError("A", newInvalidCellNameError("A")).Error())
-	assert.EqualError(t, f.adjustMergeCells(&xlsxWorksheet{
+	}, rows, 0, 0), newCellNameToCoordinatesError("A", newInvalidCellNameError("A")))
+	assert.Equal(t, f.adjustMergeCells(&xlsxWorksheet{
 		MergeCells: &xlsxMergeCells{
 			Cells: []*xlsxMergeCell{
 				{
 					Ref: "A1:B",
 				},
 			},
 		},
-	}, rows, 0, 0), newCellNameToCoordinatesError("B", newInvalidCellNameError("B")).Error())
+	}, rows, 0, 0), newCellNameToCoordinatesError("B", newInvalidCellNameError("B")))
 	assert.NoError(t, f.adjustMergeCells(&xlsxWorksheet{
 		MergeCells: &xlsxMergeCells{
 			Cells: []*xlsxMergeCell{
@@ -272,7 +272,7 @@ func TestAdjustMergeCells(t *testing.T) {
 	}
 	for _, c := range cases {
 		assert.NoError(t, f.adjustMergeCells(c.ws, c.dir, c.num, -1))
-		assert.Equal(t, 0, len(c.ws.MergeCells.Cells), c.label)
+		assert.Len(t, c.ws.MergeCells.Cells, 0, c.label)
 	}
 
 	f = NewFile()
@@ -293,22 +293,23 @@ func TestAdjustAutoFilter(t *testing.T) {
 		},
 	}, rows, 1, -1))
 	// Test adjustAutoFilter with illegal cell reference
-	assert.EqualError(t, f.adjustAutoFilter(&xlsxWorksheet{
+	assert.Equal(t, f.adjustAutoFilter(&xlsxWorksheet{
 		AutoFilter: &xlsxAutoFilter{
 			Ref: "A:B1",
 		},
-	}, rows, 0, 0), newCellNameToCoordinatesError("A", newInvalidCellNameError("A")).Error())
-	assert.EqualError(t, f.adjustAutoFilter(&xlsxWorksheet{
+	}, rows, 0, 0), newCellNameToCoordinatesError("A", newInvalidCellNameError("A")))
+	assert.Equal(t, f.adjustAutoFilter(&xlsxWorksheet{
 		AutoFilter: &xlsxAutoFilter{
 			Ref: "A1:B",
 		},
-	}, rows, 0, 0), newCellNameToCoordinatesError("B", newInvalidCellNameError("B")).Error())
+	}, rows, 0, 0), newCellNameToCoordinatesError("B", newInvalidCellNameError("B")))
 }
 
 func TestAdjustTable(t *testing.T) {
 	f, sheetName := NewFile(), "Sheet1"
 	for idx, reference := range []string{"B2:C3", "E3:F5", "H5:H8", "J5:K9"} {
-		assert.NoError(t, f.AddTable(sheetName, reference, &TableOptions{
+		assert.NoError(t, f.AddTable(sheetName, &Table{
+			Range:             reference,
 			Name:              fmt.Sprintf("table%d", idx),
 			StyleName:         "TableStyleMedium2",
 			ShowFirstColumn:   true,
@@ -323,7 +324,7 @@ func TestAdjustTable(t *testing.T) {
 	assert.NoError(t, f.SaveAs(filepath.Join("test", "TestAdjustTable.xlsx")))
 
 	f = NewFile()
-	assert.NoError(t, f.AddTable(sheetName, "A1:D5", nil))
+	assert.NoError(t, f.AddTable(sheetName, &Table{Range: "A1:D5"}))
 	// Test adjust table with non-table part
 	f.Pkg.Delete("xl/tables/table1.xml")
 	assert.NoError(t, f.RemoveRow(sheetName, 1))
@@ -346,8 +347,8 @@ func TestAdjustHelper(t *testing.T) {
 		AutoFilter: &xlsxAutoFilter{Ref: "A1:B"},
 	})
 	// Test adjustHelper with illegal cell reference
-	assert.EqualError(t, f.adjustHelper("Sheet1", rows, 0, 0), newCellNameToCoordinatesError("A", newInvalidCellNameError("A")).Error())
-	assert.EqualError(t, f.adjustHelper("Sheet2", rows, 0, 0), newCellNameToCoordinatesError("B", newInvalidCellNameError("B")).Error())
+	assert.Equal(t, f.adjustHelper("Sheet1", rows, 0, 0), newCellNameToCoordinatesError("A", newInvalidCellNameError("A")))
+	assert.Equal(t, f.adjustHelper("Sheet2", rows, 0, 0), newCellNameToCoordinatesError("B", newInvalidCellNameError("B")))
 	// Test adjustHelper on not exists worksheet
 	assert.EqualError(t, f.adjustHelper("SheetN", rows, 0, 0), "sheet SheetN does not exist")
 }
@@ -363,7 +364,7 @@ func TestAdjustCalcChain(t *testing.T) {
 	assert.NoError(t, f.InsertRows("Sheet1", 1, 1))
 
 	f.CalcChain.C[1].R = "invalid coordinates"
-	assert.EqualError(t, f.InsertCols("Sheet1", "A", 1), newCellNameToCoordinatesError("invalid coordinates", newInvalidCellNameError("invalid coordinates")).Error())
+	assert.Equal(t, f.InsertCols("Sheet1", "A", 1), newCellNameToCoordinatesError("invalid coordinates", newInvalidCellNameError("invalid coordinates")))
 	f.CalcChain = nil
 	assert.NoError(t, f.InsertCols("Sheet1", "A", 1))
 }

cell.go

@@ -694,8 +694,8 @@ type FormulaOpts struct {
 //	            return
 //	        }
 //	    }
-//	    if err := f.AddTable("Sheet1", "A1:C2", &excelize.TableOptions{
-//	        Name: "Table1", StyleName: "TableStyleMedium2",
+//	    if err := f.AddTable("Sheet1", &excelize.Table{
+//	        Range: "A1:C2", Name: "Table1", StyleName: "TableStyleMedium2",
 //	    }); err != nil {
 //	        fmt.Println(err)
 //	        return

cell_test.go

@@ -571,7 +571,7 @@ func TestSetCellFormula(t *testing.T) {
 	for idx, row := range [][]interface{}{{"A", "B", "C"}, {1, 2}} {
 		assert.NoError(t, f.SetSheetRow("Sheet1", fmt.Sprintf("A%d", idx+1), &row))
 	}
-	assert.NoError(t, f.AddTable("Sheet1", "A1:C2", &TableOptions{Name: "Table1", StyleName: "TableStyleMedium2"}))
+	assert.NoError(t, f.AddTable("Sheet1", &Table{Range: "A1:C2", Name: "Table1", StyleName: "TableStyleMedium2"}))
 	formulaType = STCellFormulaTypeDataTable
 	assert.NoError(t, f.SetCellFormula("Sheet1", "C2", "=SUM(Table1[[A]:[B]])", FormulaOpts{Type: &formulaType}))
 	assert.NoError(t, f.SaveAs(filepath.Join("test", "TestSetCellFormula6.xlsx")))

comment.go

@@ -21,46 +21,43 @@ import (
 	"strings"
 )
 
-// GetComments retrieves all comments and returns a map of worksheet name to
-// the worksheet comments.
-func (f *File) GetComments() (map[string][]Comment, error) {
-	comments := map[string][]Comment{}
-	for n, path := range f.sheetMap {
-		target := f.getSheetComments(filepath.Base(path))
-		if target == "" {
-			continue
-		}
-		if !strings.HasPrefix(target, "/") {
-			target = "xl" + strings.TrimPrefix(target, "..")
-		}
-		cmts, err := f.commentsReader(strings.TrimPrefix(target, "/"))
-		if err != nil {
-			return comments, err
-		}
-		if cmts != nil {
-			var sheetComments []Comment
-			for _, comment := range cmts.CommentList.Comment {
-				sheetComment := Comment{}
-				if comment.AuthorID < len(cmts.Authors.Author) {
-					sheetComment.Author = cmts.Authors.Author[comment.AuthorID]
-				}
-				sheetComment.Cell = comment.Ref
-				sheetComment.AuthorID = comment.AuthorID
-				if comment.Text.T != nil {
-					sheetComment.Text += *comment.Text.T
-				}
-				for _, text := range comment.Text.R {
-					if text.T != nil {
-						run := RichTextRun{Text: text.T.Val}
-						if text.RPr != nil {
-							run.Font = newFont(text.RPr)
-						}
-						sheetComment.Runs = append(sheetComment.Runs, run)
+// GetComments retrieves all comments in a worksheet by given worksheet name.
+func (f *File) GetComments(sheet string) ([]Comment, error) {
+	var comments []Comment
+	sheetXMLPath, ok := f.getSheetXMLPath(sheet)
+	if !ok {
+		return comments, newNoExistSheetError(sheet)
+	}
+	commentsXML := f.getSheetComments(filepath.Base(sheetXMLPath))
+	if !strings.HasPrefix(commentsXML, "/") {
+		commentsXML = "xl" + strings.TrimPrefix(commentsXML, "..")
+	}
+	commentsXML = strings.TrimPrefix(commentsXML, "/")
+	cmts, err := f.commentsReader(commentsXML)
+	if err != nil {
+		return comments, err
+	}
+	if cmts != nil {
+		for _, cmt := range cmts.CommentList.Comment {
+			comment := Comment{}
+			if cmt.AuthorID < len(cmts.Authors.Author) {
+				comment.Author = cmts.Authors.Author[cmt.AuthorID]
+			}
+			comment.Cell = cmt.Ref
+			comment.AuthorID = cmt.AuthorID
+			if cmt.Text.T != nil {
+				comment.Text += *cmt.Text.T
+			}
+			for _, text := range cmt.Text.R {
+				if text.T != nil {
+					run := RichTextRun{Text: text.T.Val}
+					if text.RPr != nil {
+						run.Font = newFont(text.RPr)
 					}
+					comment.Runs = append(comment.Runs, run)
 				}
-				sheetComments = append(sheetComments, sheetComment)
 			}
-			comments[n] = sheetComments
+			comments = append(comments, comment)
 		}
 	}
 	return comments, nil

comment_test.go

@@ -34,29 +34,33 @@ func TestAddComment(t *testing.T) {
 	assert.EqualError(t, f.AddComment("SheetN", Comment{Cell: "B7", Author: "Excelize", Runs: []RichTextRun{{Text: "Excelize: ", Font: &Font{Bold: true}}, {Text: "This is a comment."}}}), "sheet SheetN does not exist")
 	// Test add comment on with illegal cell reference
 	assert.EqualError(t, f.AddComment("Sheet1", Comment{Cell: "A", Author: "Excelize", Runs: []RichTextRun{{Text: "Excelize: ", Font: &Font{Bold: true}}, {Text: "This is a comment."}}}), newCellNameToCoordinatesError("A", newInvalidCellNameError("A")).Error())
-	comments, err := f.GetComments()
+	comments, err := f.GetComments("Sheet1")
 	assert.NoError(t, err)
-	if assert.NoError(t, f.SaveAs(filepath.Join("test", "TestAddComments.xlsx"))) {
-		assert.Len(t, comments, 2)
-	}
+	assert.Len(t, comments, 2)
+	comments, err = f.GetComments("Sheet2")
+	assert.NoError(t, err)
+	assert.Len(t, comments, 1)
+	assert.NoError(t, f.SaveAs(filepath.Join("test", "TestAddComments.xlsx")))
 
 	f.Comments["xl/comments2.xml"] = nil
 	f.Pkg.Store("xl/comments2.xml", []byte(xml.Header+`<comments xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"><authors><author>Excelize: </author></authors><commentList><comment ref="B7" authorId="0"><text><t>Excelize: </t></text></comment></commentList></comments>`))
-	comments, err = f.GetComments()
+	comments, err = f.GetComments("Sheet1")
 	assert.NoError(t, err)
-	assert.EqualValues(t, 2, len(comments["Sheet1"]))
-	assert.EqualValues(t, 1, len(comments["Sheet2"]))
-	comments, err = NewFile().GetComments()
+	assert.Len(t, comments, 2)
+	comments, err = f.GetComments("Sheet2")
 	assert.NoError(t, err)
-	assert.EqualValues(t, len(comments), 0)
+	assert.Len(t, comments, 1)
+	comments, err = NewFile().GetComments("Sheet1")
+	assert.NoError(t, err)
+	assert.Len(t, comments, 0)
 
 	// Test add comments with invalid sheet name
 	assert.EqualError(t, f.AddComment("Sheet:1", Comment{Cell: "A1", Author: "Excelize", Text: "This is a comment."}), ErrSheetNameInvalid.Error())
 
 	// Test add comments with unsupported charset
 	f.Comments["xl/comments2.xml"] = nil
 	f.Pkg.Store("xl/comments2.xml", MacintoshCyrillicCharset)
-	_, err = f.GetComments()
+	_, err = f.GetComments("Sheet2")
 	assert.EqualError(t, err, "XML syntax error on line 1: invalid UTF-8")
 
 	// Test add comments with unsupported charset
@@ -68,6 +72,11 @@ func TestAddComment(t *testing.T) {
 	f.Styles = nil
 	f.Pkg.Store(defaultXMLPathStyles, MacintoshCyrillicCharset)
 	assert.EqualError(t, f.AddComment("Sheet2", Comment{Cell: "A30", Text: "Comment"}), "XML syntax error on line 1: invalid UTF-8")
+
+	// Test get comments on not exists worksheet
+	comments, err = f.GetComments("SheetN")
+	assert.Len(t, comments, 0)
+	assert.EqualError(t, err, "sheet SheetN does not exist")
 }
 
 func TestDeleteComment(t *testing.T) {
@@ -85,23 +94,23 @@ func TestDeleteComment(t *testing.T) {
 
 	assert.NoError(t, f.DeleteComment("Sheet2", "A40"))
 
-	comments, err := f.GetComments()
+	comments, err := f.GetComments("Sheet2")
 	assert.NoError(t, err)
-	assert.EqualValues(t, 5, len(comments["Sheet2"]))
+	assert.Len(t, comments, 5)
 
-	comments, err = NewFile().GetComments()
+	comments, err = NewFile().GetComments("Sheet1")
 	assert.NoError(t, err)
-	assert.EqualValues(t, len(comments), 0)
+	assert.Len(t, comments, 0)
 
 	// Test delete comment with invalid sheet name
 	assert.EqualError(t, f.DeleteComment("Sheet:1", "A1"), ErrSheetNameInvalid.Error())
 	// Test delete all comments in a worksheet
 	assert.NoError(t, f.DeleteComment("Sheet2", "A41"))
 	assert.NoError(t, f.DeleteComment("Sheet2", "C41"))
 	assert.NoError(t, f.DeleteComment("Sheet2", "C42"))
-	comments, err = f.GetComments()
+	comments, err = f.GetComments("Sheet2")
 	assert.NoError(t, err)
-	assert.EqualValues(t, 0, len(comments["Sheet2"]))
+	assert.EqualValues(t, 0, len(comments))
 	// Test delete comment on not exists worksheet
 	assert.EqualError(t, f.DeleteComment("SheetN", "A1"), "sheet SheetN does not exist")
 	// Test delete comment with worksheet part

datavalidation_test.go

@@ -35,7 +35,7 @@ func TestDataValidation(t *testing.T) {
 
 	dataValidations, err := f.GetDataValidations("Sheet1")
 	assert.NoError(t, err)
-	assert.Equal(t, len(dataValidations), 1)
+	assert.Len(t, dataValidations, 1)
 
 	assert.NoError(t, f.SaveAs(resultFile))
 
@@ -47,7 +47,7 @@ func TestDataValidation(t *testing.T) {
 
 	dataValidations, err = f.GetDataValidations("Sheet1")
 	assert.NoError(t, err)
-	assert.Equal(t, len(dataValidations), 2)
+	assert.Len(t, dataValidations, 2)
 
 	assert.NoError(t, f.SaveAs(resultFile))
 
@@ -62,10 +62,10 @@ func TestDataValidation(t *testing.T) {
 	assert.NoError(t, f.AddDataValidation("Sheet2", dv))
 	dataValidations, err = f.GetDataValidations("Sheet1")
 	assert.NoError(t, err)
-	assert.Equal(t, len(dataValidations), 2)
+	assert.Len(t, dataValidations, 2)
 	dataValidations, err = f.GetDataValidations("Sheet2")
 	assert.NoError(t, err)
-	assert.Equal(t, len(dataValidations), 1)
+	assert.Len(t, dataValidations, 1)
 
 	dv = NewDataValidation(true)
 	dv.Sqref = "A5:B6"
@@ -87,7 +87,7 @@ func TestDataValidation(t *testing.T) {
 
 	dataValidations, err = f.GetDataValidations("Sheet1")
 	assert.NoError(t, err)
-	assert.Equal(t, len(dataValidations), 3)
+	assert.Len(t,dataValidations, 3)
 
 	// Test get data validation on no exists worksheet
 	_, err = f.GetDataValidations("SheetN")

errors.go

@@ -129,7 +129,7 @@ var (
 	ErrInvalidFormula = errors.New("formula not valid")
 	// ErrAddVBAProject defined the error message on add the VBA project in
 	// the workbook.
-	ErrAddVBAProject = errors.New("unsupported VBA project extension")
+	ErrAddVBAProject = errors.New("unsupported VBA project")
 	// ErrMaxRows defined the error message on receive a row number exceeds maximum limit.
 	ErrMaxRows = errors.New("row number exceeds maximum limit")
 	// ErrMaxRowHeight defined the error message on receive an invalid row

excelize.go

@@ -16,10 +16,8 @@ import (
 	"archive/zip"
 	"bytes"
 	"encoding/xml"
-	"fmt"
 	"io"
 	"os"
-	"path"
 	"path/filepath"
 	"strconv"
 	"strings"
@@ -460,27 +458,33 @@ func (f *File) UpdateLinkedValue() error {
 }
 
 // AddVBAProject provides the method to add vbaProject.bin file which contains
-// functions and/or macros. The file extension should be .xlsm. For example:
+// functions and/or macros. The file extension should be XLSM or XLTM. For
+// example:
 //
 //	codeName := "Sheet1"
 //	if err := f.SetSheetProps("Sheet1", &excelize.SheetPropsOptions{
 //	    CodeName: &codeName,
 //	}); err != nil {
 //	    fmt.Println(err)
+//	    return
 //	}
-//	if err := f.AddVBAProject("vbaProject.bin"); err != nil {
+//	file, err := os.ReadFile("vbaProject.bin")
+//	if err != nil {
 //	    fmt.Println(err)
+//	    return
+//	}
+//	if err := f.AddVBAProject(file); err != nil {
+//	    fmt.Println(err)
+//	    return
 //	}
 //	if err := f.SaveAs("macros.xlsm"); err != nil {
 //	    fmt.Println(err)
+//	    return
 //	}
-func (f *File) AddVBAProject(bin string) error {
+func (f *File) AddVBAProject(file []byte) error {
 	var err error
 	// Check vbaProject.bin exists first.
-	if _, err = os.Stat(bin); os.IsNotExist(err) {
-		return fmt.Errorf("stat %s: no such file or directory", bin)
-	}
-	if path.Ext(bin) != ".bin" {
+	if !bytes.Contains(file, oleIdentifier) {
 		return ErrAddVBAProject
 	}
 	rels, err := f.relsReader(f.getWorkbookRelsPath())
@@ -509,7 +513,6 @@ func (f *File) AddVBAProject(bin string) error {
 			Type:   SourceRelationshipVBAProject,
 		})
 	}
-	file, _ := os.ReadFile(filepath.Clean(bin))
 	f.Pkg.Store("xl/vbaProject.bin", file)
 	return err
 }