add -directive-map-name, -match-func-name, and -match-func-comment to code generator

Author: dengsh12

README.md

@@ -75,8 +75,8 @@ func main() {
 
 # Generate support for third-party modules
 This is a simple example that takes the path of a third-party module source code to generate support for it. For detailed usage of the tool, please run
-`go run ./cmd/generate/ --help`
-Assuming the source code path of that module is `./src`, you can call `go run ./cmd/generate/ --src-path=./src`. The output will be similar to:
+`go run ./cmd/generate/ --help`.
+Assuming the source code path of that module is `./src`, you can call `go run ./cmd/generate/ --src-path=./src -directive-map-name=directives -match-func-name=Match -match-func-comment=comment`. The output will be similar to:
 
 ```go
 /**
@@ -109,8 +109,7 @@ var directives = map[string][]uint{
     },
 }
 
-// Match is a matchFunc for parsing an NGINX config that contains the
-// preceding directives.
+// comment
 func Match(directive string) ([]uint, bool) {
     m, ok := directives[directive]
     return m, ok

cmd/generate/main.go

@@ -19,12 +19,18 @@ func main() {
 	var (
 		sourceCodePath = flag.String("src-path", "",
 			"The path of source code your want to generate support from, it can be either a file or a directory. (required)")
+		directiveMapName = flag.String("directive-map-name", "", "Name of the generated map variable."+
+			" Normally it should start with lowercase to avoid export. (required)")
+		matchFuncName = flag.String("match-func-name", "", "Name of the generated matchFunc."+
+			" Normally it should start with uppercase to export. (required)")
+		matchFnComment = flag.String("match-func-comment", "", "The code comment for generated matchFunc."+
+			" You can add some explanations like which modules included in it. Normally it should start with match-func-name (optional)")
 		filterflags       filterFlag
 		directiveOverride override
 	)
 	flag.Var(&filterflags, "filter",
 		"A list of strings specifying the directives to exclude from the output. "+
-			"An example is: -filter directive1 -filter directive2...(optional)")
+			"An example is: -filter directive1 -filter directive2... (optional)")
 	flag.Var(&directiveOverride, "override",
 		"A list of strings, used to override the output. "+
 			"It should follow the format:{directive:bitmask00|bitmask01...,bitmask10|bitmask11...}"+"\n"+
@@ -33,7 +39,27 @@ func main() {
 
 	flag.Parse()
 
-	err := generator.Generate(*sourceCodePath, os.Stdout, filterflags.filter, directiveOverride)
+	if *sourceCodePath == "" {
+		log.Fatal("src-path can't be empty")
+	}
+
+	if *directiveMapName == "" {
+		log.Fatal("directive-map can't be empty")
+	}
+
+	if *matchFuncName == "" {
+		log.Fatal("match-func can't be empty")
+	}
+
+	config := generator.GenerateConfig{
+		Filter:           filterflags.filter,
+		Override:         directiveOverride,
+		DirectiveMapName: *directiveMapName,
+		MatchFuncName:    *matchFuncName,
+		MatchFuncComment: *matchFnComment,
+	}
+
+	err := generator.Generate(*sourceCodePath, os.Stdout, config)
 	if err != nil {
 		log.Fatal(err)
 	}

internal/generator/generator.go

@@ -11,10 +11,40 @@ import (
 	"io"
 )
 
-// Generate receives a string sourcePath and an io.Writer writer. It will
-// extract all the directives definitions from the .c and .cpp files in
-// sourcePath and its subdirectories, then output the corresponding directive
-// masks map named "directives" and matchFunc named "Match" via writer.
-func Generate(sourcePath string, writer io.Writer, filter map[string]struct{}, override map[string][]Mask) error {
-	return genFromSrcCode(sourcePath, "directives", "Match", writer, filter, override)
+type GenerateConfig struct {
+	// Filter is a map used to exclude directives from generator.
+	// The key of it is the directive names.
+	Filter map[string]struct{}
+
+	// Override is a map used to override the masks from source code of directives.
+	// The key of it is the directive name. The value is the masks we want.
+	// If a directive exists in Override, generator won't consider its definition
+	// in source code.
+	Override map[string][]Mask
+
+	// DirectiveMapName is the name assigned to the variable containing the directives
+	// discovered by generator. The variable name generally starts with a
+	// lowercase to avoid export. Users will use the generated function named by
+	// MatchFuncName to validate the module directives in nginx configurations.
+	DirectiveMapName string
+
+	// MatchFuncName is the name assigned to the matchFunc generated by the generator.
+	// It should generally start with a uppercase to export.
+	// Users will use the generated function named by MatchFuncName
+	// to validate the module directives in nginx configurations.
+	MatchFuncName string
+
+	// MatchFuncComment is the comment appears above the generated MatchFunc.
+	// It may contain some information like what modules are included
+	// in the generated MatchFunc. Generally it should start with MatchFuncName.
+	// If it is empty, no comments will appear above the generated MatchFunc.
+	MatchFuncComment string
+}
+
+// Generate receives a string sourcePath, an io.Writer writer, and a
+// GenerateConfig config. It will extract all the directives definitions
+// from the .c and .cpp files in sourcePath and its subdirectories,
+// then output the corresponding directive masks map and matchFunc via writer.
+func Generate(sourcePath string, writer io.Writer, config GenerateConfig) error {
+	return genFromSrcCode(sourcePath, writer, config)
 }

internal/generator/generator_util.go

@@ -30,6 +30,7 @@ type supportFileTmplStruct struct {
 	Directive2Masks map[string][]Mask
 	MapVariableName string
 	MatchFnName     string
+	MatchFnComment  string
 }
 
 var (
@@ -184,13 +185,13 @@ func getMasksFromPath(path string) (directive2Masks map[string][]Mask, err error
 	return directive2Masks, nil
 }
 
-func genFromSrcCode(codePath string, mapVariableName string, matchFnName string, writer io.Writer,
-	filter map[string]struct{}, override map[string][]Mask) error {
+func genFromSrcCode(codePath string, writer io.Writer, config GenerateConfig) error {
 	directive2Masks, err := getMasksFromPath(codePath)
 	if err != nil {
 		return err
 	}
 
+	filter := config.Filter
 	if len(filter) > 0 {
 		for d := range directive2Masks {
 			if _, found := filter[d]; found {
@@ -199,6 +200,7 @@ func genFromSrcCode(codePath string, mapVariableName string, matchFnName string,
 		}
 	}
 
+	override := config.Override
 	if override != nil {
 		for d := range directive2Masks {
 			if newMasks, found := override[d]; found {
@@ -209,8 +211,9 @@ func genFromSrcCode(codePath string, mapVariableName string, matchFnName string,
 
 	err = supportFileTmpl.Execute(writer, supportFileTmplStruct{
 		Directive2Masks: directive2Masks,
-		MapVariableName: mapVariableName,
-		MatchFnName:     matchFnName,
+		MapVariableName: config.DirectiveMapName,
+		MatchFnName:     config.MatchFuncName,
+		MatchFnComment:  config.MatchFuncComment,
 	})
 	if err != nil {
 		return err

internal/generator/generator_util_test.go

@@ -26,7 +26,7 @@ import (
 var (
 	update = flag.Bool("update", false,
 		`update the expected output of these tests, 
-only use when the expected output is outdated and you are sure your output is correct`)
+ only use when the expected output is outdated and you are sure your output is correct`)
 )
 
 func TestMain(m *testing.M) {
@@ -70,79 +70,133 @@ func getExpectedFilePath(relativePath string) (string, error) {
 }
 
 //nolint:funlen,gocognit
-func TestGenSupFromSrcCode(t *testing.T) {
+func TestGenFromSrcCode(t *testing.T) {
 	t.Parallel()
 	tests := map[string]struct {
 		relativePath string
 		wantErr      bool
-		filter       map[string]struct{}
-		override     map[string][]Mask
+		config       GenerateConfig
 	}{
 		"normalDirectiveDefinition_pass": {
 			relativePath: "normalDefinition",
-			wantErr:      false,
+			config: GenerateConfig{
+				DirectiveMapName: "myDirectives",
+				MatchFuncName:    "MyMatchFn",
+			},
+			wantErr: false,
 		},
 		"unknownBitmask_fail": {
 			relativePath: "unknownBitmask",
-			wantErr:      true,
+			config: GenerateConfig{
+				DirectiveMapName: "directives",
+				MatchFuncName:    "Match",
+			},
+			wantErr: true,
 		},
 		"noDirectivesDefinition_fail": {
 			relativePath: "noDirectives",
-			wantErr:      true,
+			config: GenerateConfig{
+				DirectiveMapName: "directives",
+				MatchFuncName:    "Match",
+			},
+			wantErr: true,
 		},
 		// If one directive was defined in several files, we should keep all
 		// of the bitmask definitions
 		"directiveRepeatDefine_pass": {
 			relativePath: "repeatDefine",
+			config: GenerateConfig{
+				DirectiveMapName: "directives",
+				MatchFuncName:    "Match",
+			},
+			wantErr: false,
 		},
 		// If there are comments in directive definition, we should ignore them
 		"commentsInDefinition_pass": {
 			relativePath: "commentsInDefinition",
+			config: GenerateConfig{
+				DirectiveMapName: "directives",
+				MatchFuncName:    "Match",
+			},
+			wantErr: false,
 		},
 		"genFromSingleFile_pass": {
 			relativePath: "single_file.c",
+			config: GenerateConfig{
+				DirectiveMapName: "directives",
+				MatchFuncName:    "Match",
+			},
+			wantErr: false,
 		},
 		"fullNgxBitmaskCover_pass": {
 			relativePath: "fullNgxBitmaskCover",
+			config: GenerateConfig{
+				DirectiveMapName: "directives",
+				MatchFuncName:    "Match",
+			},
+			wantErr: false,
 		},
 		"testFilter_pass": {
 			relativePath: "filter",
-			filter:       map[string]struct{}{"my_directive_2": {}, "my_directive_3": {}},
+			config: GenerateConfig{
+				DirectiveMapName: "directives",
+				MatchFuncName:    "Match",
+				Filter:           map[string]struct{}{"my_directive_2": {}, "my_directive_3": {}},
+			},
 		},
 		"testOverride_pass": {
 			relativePath: "override",
-			override: map[string][]Mask{
-				"my_directive_1": {
-					Mask{"ngxHTTPMainConf", "ngxConfTake1"},
-					Mask{"ngxHTTPMainConf", "ngxConfTake2"},
-				},
-				"my_directive_3": {
-					Mask{"ngxHTTPMainConf", "ngxConfTake2"},
-					Mask{"ngxHTTPMainConf", "ngxConfTake3"},
+			config: GenerateConfig{
+				DirectiveMapName: "directives",
+				MatchFuncName:    "Match",
+				Override: map[string][]Mask{
+					"my_directive_1": {
+						Mask{"ngxHTTPMainConf", "ngxConfTake1"},
+						Mask{"ngxHTTPMainConf", "ngxConfTake2"},
+					},
+					"my_directive_3": {
+						Mask{"ngxHTTPMainConf", "ngxConfTake2"},
+						Mask{"ngxHTTPMainConf", "ngxConfTake3"},
+					},
 				},
 			},
+			wantErr: false,
 		},
 		"testFilterAndOverride_pass": {
 			relativePath: "filterAndOverride",
-			filter: map[string]struct{}{
-				"my_directive_1": {},
-				"my_directive_2": {},
-				"my_directive_3": {},
-			},
-			override: map[string][]Mask{
-				"my_directive_1": {
-					Mask{"ngxHTTPMainConf", "ngxConfTake1"},
-					Mask{"ngxHTTPMainConf", "ngxConfTake2"},
+			config: GenerateConfig{
+				Filter: map[string]struct{}{
+					"my_directive_1": {},
+					"my_directive_2": {},
+					"my_directive_3": {},
 				},
-				"my_directive_3": {
-					Mask{"ngxHTTPMainConf", "ngxConfTake2"},
-					Mask{"ngxHTTPMainConf", "ngxConfTake3"},
-				},
-				"my_directive_4": {
-					Mask{"ngxHTTPMainConf", "ngxConfTake2"},
-					Mask{"ngxHTTPMainConf", "ngxConfTake3"},
+				Override: map[string][]Mask{
+					"my_directive_1": {
+						Mask{"ngxHTTPMainConf", "ngxConfTake1"},
+						Mask{"ngxHTTPMainConf", "ngxConfTake2"},
+					},
+					"my_directive_3": {
+						Mask{"ngxHTTPMainConf", "ngxConfTake2"},
+						Mask{"ngxHTTPMainConf", "ngxConfTake3"},
+					},
+					"my_directive_4": {
+						Mask{"ngxHTTPMainConf", "ngxConfTake2"},
+						Mask{"ngxHTTPMainConf", "ngxConfTake3"},
+					},
 				},
+				DirectiveMapName: "directives",
+				MatchFuncName:    "Match",
+			},
+			wantErr: false,
+		},
+		"withMatchFuncComment_pass": {
+			relativePath: "withMatchFuncComment",
+			config: GenerateConfig{
+				DirectiveMapName: "myDirectives",
+				MatchFuncName:    "MyMatchFn",
+				MatchFuncComment: "This is a matchFunc",
 			},
+			wantErr: false,
 		},
 	}
 	for name, tc := range tests {
@@ -157,7 +211,7 @@ func TestGenSupFromSrcCode(t *testing.T) {
 
 			var buf bytes.Buffer
 
-			err = genFromSrcCode(codePath, "directives", "Match", &buf, tc.filter, tc.override)
+			err = genFromSrcCode(codePath, &buf, tc.config)
 
 			if tc.wantErr {
 				require.Error(t, err)

internal/generator/testdata/expected/commentsInDefinition

@@ -27,8 +27,7 @@ var directives = map[string][]uint{
     },
 }
 
-// Match is a matchFunc for parsing an NGINX config that contains the
-// preceding directives.
+
 func Match(directive string) ([]uint, bool) {
     m, ok := directives[directive]
     return m, ok

internal/generator/testdata/expected/filter

@@ -24,8 +24,7 @@ var directives = map[string][]uint{
     },
 }
 
-// Match is a matchFunc for parsing an NGINX config that contains the
-// preceding directives.
+
 func Match(directive string) ([]uint, bool) {
     m, ok := directives[directive]
     return m, ok

internal/generator/testdata/expected/filterAndOverride

@@ -22,8 +22,7 @@ var directives = map[string][]uint{
     },
 }
 
-// Match is a matchFunc for parsing an NGINX config that contains the
-// preceding directives.
+
 func Match(directive string) ([]uint, bool) {
     m, ok := directives[directive]
     return m, ok

internal/generator/testdata/expected/fullNgxBitmaskCover

@@ -21,8 +21,7 @@ var directives = map[string][]uint{
     },
 }
 
-// Match is a matchFunc for parsing an NGINX config that contains the
-// preceding directives.
+
 func Match(directive string) ([]uint, bool) {
     m, ok := directives[directive]
     return m, ok