This closes qax-os#1358, made a refactor with breaking changes, see details:

This made a refactor with breaking changes:

Motivation and Context

When I decided to add set horizontal centered support for this library to resolve qax-os#1358, the reason I made this huge breaking change was:

- There are too many exported types for set sheet view, properties, and format properties, although a function using the functional options pattern can be optimized by returning an anonymous function, these types or property set or get function has no binding categorization, so I change these functions like `SetAppProps` to accept a pointer of options structure.
- Users can not easily find out which properties should be in the `SetSheetPrOptions` or `SetSheetFormatPr` categories
- Nested properties cannot proceed modify easily

Introduce 5 new export data types:
`HeaderFooterOptions`, `PageLayoutMarginsOptions`, `PageLayoutOptions`, `SheetPropsOptions`, and `ViewOptions`

Rename 4 exported data types:
- Rename `PivotTableOption` to `PivotTableOptions`
- Rename `FormatHeaderFooter` to `HeaderFooterOptions`
- Rename `FormatSheetProtection` to `SheetProtectionOptions`
- Rename `SparklineOption` to `SparklineOptions`

Remove 54 exported types:
`AutoPageBreaks`, `BaseColWidth`, `BlackAndWhite`, `CodeName`, `CustomHeight`, `Date1904`, `DefaultColWidth`, `DefaultGridColor`, `DefaultRowHeight`, `EnableFormatConditionsCalculation`, `FilterPrivacy`, `FirstPageNumber`, `FitToHeight`, `FitToPage`, `FitToWidth`, `OutlineSummaryBelow`, `PageLayoutOption`, `PageLayoutOptionPtr`, `PageLayoutOrientation`, `PageLayoutPaperSize`, `PageLayoutScale`, `PageMarginBottom`, `PageMarginFooter`, `PageMarginHeader`, `PageMarginLeft`, `PageMarginRight`, `PageMarginsOptions`, `PageMarginsOptionsPtr`, `PageMarginTop`, `Published`, `RightToLeft`, `SheetFormatPrOptions`, `SheetFormatPrOptionsPtr`, `SheetPrOption`, `SheetPrOptionPtr`, `SheetViewOption`, `SheetViewOptionPtr`, `ShowFormulas`, `ShowGridLines`, `ShowRowColHeaders`, `ShowRuler`, `ShowZeros`, `TabColorIndexed`, `TabColorRGB`, `TabColorTheme`, `TabColorTint`, `ThickBottom`, `ThickTop`, `TopLeftCell`, `View`, `WorkbookPrOption`, `WorkbookPrOptionPtr`, `ZeroHeight` and `ZoomScale`

Remove 2 exported constants:
`OrientationPortrait` and `OrientationLandscape`

Change 8 functions:
- Change the `func (f *File) SetPageLayout(sheet string, opts ...PageLayoutOption) error` to `func (f *File) SetPageLayout(sheet string, opts *PageLayoutOptions) error`
- Change the `func (f *File) GetPageLayout(sheet string, opts ...PageLayoutOptionPtr) error` to `func (f *File) GetPageLayout(sheet string) (PageLayoutOptions, error)`
- Change the `func (f *File) SetPageMargins(sheet string, opts ...PageMarginsOptions) error` to `func (f *File) SetPageMargins(sheet string, opts *PageLayoutMarginsOptions) error`
- Change the `func (f *File) GetPageMargins(sheet string, opts ...PageMarginsOptionsPtr) error` to `func (f *File) GetPageMargins(sheet string) (PageLayoutMarginsOptions, error)`
- Change the `func (f *File) SetSheetViewOptions(sheet string, viewIndex int, opts ...SheetViewOption) error` to `func (f *File) SetSheetView(sheet string, viewIndex int, opts *ViewOptions) error`
- Change the `func (f *File) GetSheetViewOptions(sheet string, viewIndex int, opts ...SheetViewOptionPtr) error` to `func (f *File) GetSheetView(sheet string, viewIndex int) (ViewOptions, error)`
- Change the `func (f *File) SetWorkbookPrOptions(opts ...WorkbookPrOption) error` to `func (f *File) SetWorkbookProps(opts *WorkbookPropsOptions) error`
- Change the `func (f *File) GetWorkbookPrOptions(opts ...WorkbookPrOptionPtr) error` to `func (f *File) GetWorkbookProps() (WorkbookPropsOptions, error)`

Introduce new function to instead of existing functions:
- New function `func (f *File) SetSheetProps(sheet string, opts *SheetPropsOptions) error` instead of `func (f *File) SetSheetPrOptions(sheet string, opts ...SheetPrOption) error` and `func (f *File) SetSheetFormatPr(sheet string, opts ...SheetFormatPrOption

Author: xuri

chart.go

@@ -469,30 +469,30 @@ var (
 	}
 )
 
-// parseFormatChartSet provides a function to parse the format settings of the
+// parseChartOptions provides a function to parse the format settings of the
 // chart with default value.
-func parseFormatChartSet(formatSet string) (*formatChart, error) {
-	format := formatChart{
-		Dimension: formatChartDimension{
+func parseChartOptions(opts string) (*chartOptions, error) {
+	options := chartOptions{
+		Dimension: chartDimensionOptions{
 			Width:  480,
 			Height: 290,
 		},
-		Format: formatPicture{
+		Format: pictureOptions{
 			FPrintsWithSheet: true,
 			XScale:           1,
 			YScale:           1,
 		},
-		Legend: formatChartLegend{
+		Legend: chartLegendOptions{
 			Position: "bottom",
 		},
-		Title: formatChartTitle{
+		Title: chartTitleOptions{
 			Name: " ",
 		},
 		VaryColors:   true,
 		ShowBlanksAs: "gap",
 	}
-	err := json.Unmarshal([]byte(formatSet), &format)
-	return &format, err
+	err := json.Unmarshal([]byte(opts), &options)
+	return &options, err
 }
 
 // AddChart provides the method to add chart in a sheet by given chart format
@@ -881,13 +881,13 @@ func parseFormatChartSet(formatSet string) (*formatChart, error) {
 //	        fmt.Println(err)
 //	    }
 //	}
-func (f *File) AddChart(sheet, cell, format string, combo ...string) error {
+func (f *File) AddChart(sheet, cell, opts string, combo ...string) error {
 	// Read sheet data.
 	ws, err := f.workSheetReader(sheet)
 	if err != nil {
 		return err
 	}
-	formatSet, comboCharts, err := f.getFormatChart(format, combo)
+	options, comboCharts, err := f.getChartOptions(opts, combo)
 	if err != nil {
 		return err
 	}
@@ -898,11 +898,11 @@ func (f *File) AddChart(sheet, cell, format string, combo ...string) error {
 	drawingID, drawingXML = f.prepareDrawing(ws, drawingID, sheet, drawingXML)
 	drawingRels := "xl/drawings/_rels/drawing" + strconv.Itoa(drawingID) + ".xml.rels"
 	drawingRID := f.addRels(drawingRels, SourceRelationshipChart, "../charts/chart"+strconv.Itoa(chartID)+".xml", "")
-	err = f.addDrawingChart(sheet, drawingXML, cell, formatSet.Dimension.Width, formatSet.Dimension.Height, drawingRID, &formatSet.Format)
+	err = f.addDrawingChart(sheet, drawingXML, cell, options.Dimension.Width, options.Dimension.Height, drawingRID, &options.Format)
 	if err != nil {
 		return err
 	}
-	f.addChart(formatSet, comboCharts)
+	f.addChart(options, comboCharts)
 	f.addContentTypePart(chartID, "chart")
 	f.addContentTypePart(drawingID, "drawings")
 	f.addSheetNameSpace(sheet, SourceRelationship)
@@ -913,12 +913,12 @@ func (f *File) AddChart(sheet, cell, format string, combo ...string) error {
 // format set (such as offset, scale, aspect ratio setting and print settings)
 // and properties set. In Excel a chartsheet is a worksheet that only contains
 // a chart.
-func (f *File) AddChartSheet(sheet, format string, combo ...string) error {
+func (f *File) AddChartSheet(sheet, opts string, combo ...string) error {
 	// Check if the worksheet already exists
 	if f.GetSheetIndex(sheet) != -1 {
 		return ErrExistsWorksheet
 	}
-	formatSet, comboCharts, err := f.getFormatChart(format, combo)
+	options, comboCharts, err := f.getChartOptions(opts, combo)
 	if err != nil {
 		return err
 	}
@@ -945,8 +945,8 @@ func (f *File) AddChartSheet(sheet, format string, combo ...string) error {
 	f.prepareChartSheetDrawing(&cs, drawingID, sheet)
 	drawingRels := "xl/drawings/_rels/drawing" + strconv.Itoa(drawingID) + ".xml.rels"
 	drawingRID := f.addRels(drawingRels, SourceRelationshipChart, "../charts/chart"+strconv.Itoa(chartID)+".xml", "")
-	f.addSheetDrawingChart(drawingXML, drawingRID, &formatSet.Format)
-	f.addChart(formatSet, comboCharts)
+	f.addSheetDrawingChart(drawingXML, drawingRID, &options.Format)
+	f.addChart(options, comboCharts)
 	f.addContentTypePart(chartID, "chart")
 	f.addContentTypePart(sheetID, "chartsheet")
 	f.addContentTypePart(drawingID, "drawings")
@@ -960,45 +960,45 @@ func (f *File) AddChartSheet(sheet, format string, combo ...string) error {
 	return err
 }
 
-// getFormatChart provides a function to check format set of the chart and
+// getChartOptions provides a function to check format set of the chart and
 // create chart format.
-func (f *File) getFormatChart(format string, combo []string) (*formatChart, []*formatChart, error) {
-	var comboCharts []*formatChart
-	formatSet, err := parseFormatChartSet(format)
+func (f *File) getChartOptions(opts string, combo []string) (*chartOptions, []*chartOptions, error) {
+	var comboCharts []*chartOptions
+	options, err := parseChartOptions(opts)
 	if err != nil {
-		return formatSet, comboCharts, err
+		return options, comboCharts, err
 	}
 	for _, comboFormat := range combo {
-		comboChart, err := parseFormatChartSet(comboFormat)
+		comboChart, err := parseChartOptions(comboFormat)
 		if err != nil {
-			return formatSet, comboCharts, err
+			return options, comboCharts, err
 		}
 		if _, ok := chartValAxNumFmtFormatCode[comboChart.Type]; !ok {
-			return formatSet, comboCharts, newUnsupportedChartType(comboChart.Type)
+			return options, comboCharts, newUnsupportedChartType(comboChart.Type)
 		}
 		comboCharts = append(comboCharts, comboChart)
 	}
-	if _, ok := chartValAxNumFmtFormatCode[formatSet.Type]; !ok {
-		return formatSet, comboCharts, newUnsupportedChartType(formatSet.Type)
+	if _, ok := chartValAxNumFmtFormatCode[options.Type]; !ok {
+		return options, comboCharts, newUnsupportedChartType(options.Type)
 	}
-	return formatSet, comboCharts, err
+	return options, comboCharts, err
 }
 
 // DeleteChart provides a function to delete chart in spreadsheet by given
 // worksheet name and cell reference.
-func (f *File) DeleteChart(sheet, cell string) (err error) {
+func (f *File) DeleteChart(sheet, cell string) error {
 	col, row, err := CellNameToCoordinates(cell)
 	if err != nil {
-		return
+		return err
 	}
 	col--
 	row--
 	ws, err := f.workSheetReader(sheet)
 	if err != nil {
-		return
+		return err
 	}
 	if ws.Drawing == nil {
-		return
+		return err
 	}
 	drawingXML := strings.ReplaceAll(f.getSheetRelationshipsTargetByID(sheet, ws.Drawing.RID), "..", "xl")
 	return f.deleteDrawing(col, row, drawingXML, "Chart")

comment.go

@@ -23,15 +23,15 @@ import (
 	"strings"
 )
 
-// parseFormatCommentsSet provides a function to parse the format settings of
+// parseCommentOptions provides a function to parse the format settings of
 // the comment with default value.
-func parseFormatCommentsSet(formatSet string) (*formatComment, error) {
-	format := formatComment{
+func parseCommentOptions(opts string) (*commentOptions, error) {
+	options := commentOptions{
 		Author: "Author:",
 		Text:   " ",
 	}
-	err := json.Unmarshal([]byte(formatSet), &format)
-	return &format, err
+	err := json.Unmarshal([]byte(opts), &options)
+	return &options, err
 }
 
 // GetComments retrieves all comments and returns a map of worksheet name to
@@ -93,8 +93,8 @@ func (f *File) getSheetComments(sheetFile string) string {
 // comment in Sheet1!$A$30:
 //
 //	err := f.AddComment("Sheet1", "A30", `{"author":"Excelize: ","text":"This is a comment."}`)
-func (f *File) AddComment(sheet, cell, format string) error {
-	formatSet, err := parseFormatCommentsSet(format)
+func (f *File) AddComment(sheet, cell, opts string) error {
+	options, err := parseCommentOptions(opts)
 	if err != nil {
 		return err
 	}
@@ -123,19 +123,19 @@ func (f *File) AddComment(sheet, cell, format string) error {
 	}
 	commentsXML := "xl/comments" + strconv.Itoa(commentID) + ".xml"
 	var colCount int
-	for i, l := range strings.Split(formatSet.Text, "\n") {
+	for i, l := range strings.Split(options.Text, "\n") {
 		if ll := len(l); ll > colCount {
 			if i == 0 {
-				ll += len(formatSet.Author)
+				ll += len(options.Author)
 			}
 			colCount = ll
 		}
 	}
-	err = f.addDrawingVML(commentID, drawingVML, cell, strings.Count(formatSet.Text, "\n")+1, colCount)
+	err = f.addDrawingVML(commentID, drawingVML, cell, strings.Count(options.Text, "\n")+1, colCount)
 	if err != nil {
 		return err
 	}
-	f.addComment(commentsXML, cell, formatSet)
+	f.addComment(commentsXML, cell, options)
 	f.addContentTypePart(commentID, "comments")
 	return err
 }
@@ -144,11 +144,12 @@ func (f *File) AddComment(sheet, cell, format string) error {
 // worksheet name. For example, delete the comment in Sheet1!$A$30:
 //
 //	err := f.DeleteComment("Sheet1", "A30")
-func (f *File) DeleteComment(sheet, cell string) (err error) {
+func (f *File) DeleteComment(sheet, cell string) error {
+	var err error
 	sheetXMLPath, ok := f.getSheetXMLPath(sheet)
 	if !ok {
 		err = newNoExistSheetError(sheet)
-		return
+		return err
 	}
 	commentsXML := f.getSheetComments(filepath.Base(sheetXMLPath))
 	if !strings.HasPrefix(commentsXML, "/") {
@@ -173,7 +174,7 @@ func (f *File) DeleteComment(sheet, cell string) (err error) {
 		}
 		f.Comments[commentsXML] = comments
 	}
-	return
+	return err
 }
 
 // addDrawingVML provides a function to create comment as
@@ -279,9 +280,9 @@ func (f *File) addDrawingVML(commentID int, drawingVML, cell string, lineCount,
 
 // addComment provides a function to create chart as xl/comments%d.xml by
 // given cell and format sets.
-func (f *File) addComment(commentsXML, cell string, formatSet *formatComment) {
-	a := formatSet.Author
-	t := formatSet.Text
+func (f *File) addComment(commentsXML, cell string, opts *commentOptions) {
+	a := opts.Author
+	t := opts.Text
 	if len(a) > MaxFieldLength {
 		a = a[:MaxFieldLength]
 	}
@@ -291,10 +292,10 @@ func (f *File) addComment(commentsXML, cell string, formatSet *formatComment) {
 	comments := f.commentsReader(commentsXML)
 	authorID := 0
 	if comments == nil {
-		comments = &xlsxComments{Authors: xlsxAuthor{Author: []string{formatSet.Author}}}
+		comments = &xlsxComments{Authors: xlsxAuthor{Author: []string{opts.Author}}}
 	}
-	if inStrSlice(comments.Authors.Author, formatSet.Author, true) == -1 {
-		comments.Authors.Author = append(comments.Authors.Author, formatSet.Author)
+	if inStrSlice(comments.Authors.Author, opts.Author, true) == -1 {
+		comments.Authors.Author = append(comments.Authors.Author, opts.Author)
 		authorID = len(comments.Authors.Author) - 1
 	}
 	defaultFont := f.GetDefaultFont()

docProps.go

@@ -64,19 +64,20 @@ import (
 //	    HyperlinksChanged: true,
 //	    AppVersion:        "16.0000",
 //	})
-func (f *File) SetAppProps(appProperties *AppProperties) (err error) {
+func (f *File) SetAppProps(appProperties *AppProperties) error {
 	var (
 		app                *xlsxProperties
+		err                error
+		field              string
 		fields             []string
-		output             []byte
 		immutable, mutable reflect.Value
-		field              string
+		output             []byte
 	)
 	app = new(xlsxProperties)
 	if err = f.xmlNewDecoder(bytes.NewReader(namespaceStrictToTransitional(f.readXML(defaultXMLPathDocPropsApp)))).
 		Decode(app); err != nil && err != io.EOF {
 		err = newDecodeXMLError(err)
-		return
+		return err
 	}
 	fields = []string{"Application", "ScaleCrop", "DocSecurity", "Company", "LinksUpToDate", "HyperlinksChanged", "AppVersion"}
 	immutable, mutable = reflect.ValueOf(*appProperties), reflect.ValueOf(app).Elem()
@@ -94,7 +95,7 @@ func (f *File) SetAppProps(appProperties *AppProperties) (err error) {
 	app.Vt = NameSpaceDocumentPropertiesVariantTypes.Value
 	output, err = xml.Marshal(app)
 	f.saveFileList(defaultXMLPathDocPropsApp, output)
-	return
+	return err
 }
 
 // GetAppProps provides a function to get document application properties.
@@ -167,23 +168,24 @@ func (f *File) GetAppProps() (ret *AppProperties, err error) {
 //	    Language:       "en-US",
 //	    Version:        "1.0.0",
 //	})
-func (f *File) SetDocProps(docProperties *DocProperties) (err error) {
+func (f *File) SetDocProps(docProperties *DocProperties) error {
 	var (
 		core               *decodeCoreProperties
-		newProps           *xlsxCoreProperties
+		err                error
+		field, val         string
 		fields             []string
-		output             []byte
 		immutable, mutable reflect.Value
-		field, val         string
+		newProps           *xlsxCoreProperties
+		output             []byte
 	)
 
 	core = new(decodeCoreProperties)
 	if err = f.xmlNewDecoder(bytes.NewReader(namespaceStrictToTransitional(f.readXML(defaultXMLPathDocPropsCore)))).
 		Decode(core); err != nil && err != io.EOF {
 		err = newDecodeXMLError(err)
-		return
+		return err
 	}
-	newProps, err = &xlsxCoreProperties{
+	newProps = &xlsxCoreProperties{
 		Dc:             NameSpaceDublinCore,
 		Dcterms:        NameSpaceDublinCoreTerms,
 		Dcmitype:       NameSpaceDublinCoreMetadataInitiative,
@@ -200,7 +202,7 @@ func (f *File) SetDocProps(docProperties *DocProperties) (err error) {
 		ContentStatus:  core.ContentStatus,
 		Category:       core.Category,
 		Version:        core.Version,
-	}, nil
+	}
 	if core.Created != nil {
 		newProps.Created = &xlsxDcTerms{Type: core.Created.Type, Text: core.Created.Text}
 	}
@@ -226,7 +228,7 @@ func (f *File) SetDocProps(docProperties *DocProperties) (err error) {
 	output, err = xml.Marshal(newProps)
 	f.saveFileList(defaultXMLPathDocPropsCore, output)
 
-	return
+	return err
 }
 
 // GetDocProps provides a function to get document core properties.