refact: refactored the package into multiple specialized sub-packages

cmdutils/cmd_utils.go

@@ -0,0 +1,24 @@
+// Copyright 2015 go-swagger maintainers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cmdutils
+
+// CommandLineOptionsGroup represents a group of user-defined command line options.
+//
+// This is for instance used to configure command line arguments in API servers generated by go-swagger.
+type CommandLineOptionsGroup struct {
+	ShortDescription string
+	LongDescription  string
+	Options          interface{}
+}

cmdutils/doc.go

@@ -0,0 +1,16 @@
+// Copyright 2015 go-swagger maintainers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package cmdutils brings helpers for CLIs produced by go-openapi
+package cmdutils

cmdutils_iface.go

@@ -0,0 +1,22 @@
+// Copyright 2015 go-swagger maintainers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package swag
+
+import "github.com/go-openapi/swag/cmdutils"
+
+// CommandLineOptionsGroup represents a group of user-defined command line options.
+//
+// Deprecated: use [cmdutils.CommandLineOptionsGroup] instead.
+type CommandLineOptionsGroup = cmdutils.CommandLineOptionsGroup

cmdutils_iface_test.go

@@ -0,0 +1 @@
+package swag

conv/doc.go

@@ -14,11 +14,13 @@
 
 // Package conv exposes utilities to convert types.
 //
-// Convert and Format families of functions are essentially a shorthand to `strconv` functions,
+// The Convert and Format families of functions are essentially a shorthand to [strconv] functions,
 // using the decimal representation of numbers.
 //
-// * from string representation to value ("Convert*") and reciprocally ("Format*")
-// * from pointer to value ([Value]) and reciprocally ([Pointer])
-// * from slice of values to slice of pointers ([PointerSlice]) and reciprocally ([ValueSlice])
-// * from map of values to map of pointers ([PointerMap]) and reciprocally ([ValueMap])
+// Features:
+//
+//   - from string representation to value ("Convert*") and reciprocally ("Format*")
+//   - from pointer to value ([Value]) and reciprocally ([Pointer])
+//   - from slice of values to slice of pointers ([PointerSlice]) and reciprocally ([ValueSlice])
+//   - from map of values to map of pointers ([PointerMap]) and reciprocally ([ValueMap])
 package conv

doc.go

@@ -16,33 +16,60 @@
 //
 // You may also use it standalone for your projects.
 //
+// NOTE: all features that were previously exposed as package-level members (constants, variables,
+// functions and types) are now deprecated and are superseded by equivalent features in
+// more specialized sub-packages.
+//
 // Here is what is inside:
 //
-//				Package conv:
-//					* convert between value and pointers for builtin types
-//					* convert from string to builtin types (wraps strconv)
+// Package [conv]:
+//
+//   - convert between value and pointers for builtin types
+//   - convert from string to builtin types (wraps strconv)
+//
+// Package [fileutils]:
+//
+//   - file upload type
+//   - search in path
+//
+// Package [jsonname]:
+//
+//   - json names for go properties
+//
+// Package [jsonutils]:
+//
+//   - fast json concatenation
+//   - read and write JSON from and to dynamic go data structures
+//
+// Package [loading]:
+//
+//   - load from file or http
+//
+// Package [mangling]:
+//
+//   - name mangling to generate clean identifiers
+//
+// Package [netutils]:
+//
+//   - host, port from address
+//
+// Package [stringutils]:
+//
+//   - find string in list
+//   - join/split arrays of query parameters
 //
-//				Package typeutils:
-//				  *  check the zero value for any type
+// Package [typeutils]:
 //
-//				Package jsonutils:
-//				  * fast json concatenation
-//				  * read and write JSON from and to dynamic go data structures
+//   - check the zero value of any type
 //
-//				Package yamlutils:
-//				  * converting YAML to JSON
-//			    * loading YAML into a dynamic YAML document
+// Package [yamlutils]:
 //
-//				Package loading:
-//				  * load from file or http
+//   - converting YAML to JSON
+//   - loading YAML into a dynamic YAML document
 //
-//				Package swag:
-//				  * search in path
-//		      * host, port from address
-//				  * name mangling
-//	       * file upload type
+// ---
 //
-// This repo has only few dependencies outside of the standard library:
+// This repo has a few dependencies outside of the standard library:
 //
 //   - YAML utilities depend on gopkg.in/yaml.v2
 //   - JSON utilities depend on [mailru/easyjson]

fileutils/doc.go

@@ -0,0 +1,21 @@
+// Copyright 2015 go-swagger maintainers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package fileutils exposes utilities to deal with files and paths.
+//
+// Currently, there is:
+//   - [File] to represent an abstraction of an uploaded file.
+//     For instance, this is used by [github.com/go-openapi/runtime.File].
+//   - path search utilities (e.g. finding packages in the GO search path)
+package fileutils

file.go → fileutils/file.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package swag
+package fileutils
 
 import "mime/multipart"
 

file_test.go → fileutils/file_test.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package swag
+package fileutils
 
 import (
 	"io"

path.go → fileutils/path.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package swag
+package fileutils
 
 import (
 	"os"
@@ -21,10 +21,8 @@ import (
 	"strings"
 )
 
-const (
-	// GOPATHKey represents the env key for gopath
-	GOPATHKey = "GOPATH"
-)
+// GOPATHKey represents the env key for gopath
+const GOPATHKey = "GOPATH"
 
 // FindInSearchPath finds a package in a provided lists of paths
 func FindInSearchPath(searchPath, pkg string) string {

path_test.go → fileutils/path_test.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package swag
+package fileutils
 
 import (
 	"os"

fileutils_iface.go

@@ -0,0 +1,44 @@
+// Copyright 2015 go-swagger maintainers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package swag
+
+import "github.com/go-openapi/swag/fileutils"
+
+// GOPATHKey represents the env key for gopath
+//
+// Deprecated: use [fileutils.GOPATHKey] instead.
+const GOPATHKey = fileutils.GOPATHKey
+
+// File represents an uploaded file.
+//
+// Deprecated: use [fileutils.File] instead.
+type File = fileutils.File
+
+// FindInSearchPath finds a package in a provided lists of paths.
+//
+// Deprecated: use [fileutils.FindInSearchPath] instead.
+func FindInSearchPath(searchPath, pkg string) string {
+	return fileutils.FindInSearchPath(searchPath, pkg)
+}
+
+// FindInGoSearchPath finds a package in the $GOPATH:$GOROOT
+//
+// Deprecated: use [fileutils.FindInGoSearchPath] instead.
+func FindInGoSearchPath(pkg string) string { return fileutils.FindInGoSearchPath(pkg) }
+
+// FullGoSearchPath gets the search paths for finding packages
+//
+// Deprecated: use [fileutils.FullGoSearchPath] instead.
+func FullGoSearchPath() string { return fileutils.FullGoSearchPath() }

fileutils_iface_test.go

@@ -0,0 +1,52 @@
+// Copyright 2015 go-swagger maintainers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package swag
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestFileUtilsIface(t *testing.T) {
+	t.Run("deprecated functions should work", func(t *testing.T) {
+		t.Run("with test package path", func(t *testing.T) {
+			const tgt = "testpath"
+
+			td, err := os.MkdirTemp("", tgt) //nolint:usetesting // as t.TempDir in testing not yet fully working (on windows)
+			require.NoError(t, err)
+			t.Cleanup(func() {
+				_ = os.RemoveAll(td)
+			})
+
+			realPath := filepath.Join(td, "src", "foo", "bar")
+			require.NoError(t, os.MkdirAll(realPath, os.ModePerm))
+
+			assert.NotEmpty(t, FindInSearchPath(td, "foo/bar"))
+		})
+
+		// The following functions are environment-dependant and difficult to test.
+		// Deferred to in-package unit testing.
+		assert.NotPanics(t, func() {
+			_ = FullGoSearchPath()
+		})
+		assert.NotPanics(t, func() {
+			_ = FindInGoSearchPath("github.com/go-openapi/swag")
+		})
+	})
+}

jsonname/doc.go

@@ -0,0 +1,16 @@
+// Copyright 2015 go-swagger maintainers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package jsonname is a provider of json property names from go properties.
+package jsonname

jsonname.go → jsonname/name_provider.go

@@ -12,20 +12,23 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package swag
+package jsonname
 
 import (
 	"reflect"
 	"strings"
 	"sync"
 )
 
-// DefaultJSONNameProvider the default cache for types
+// DefaultJSONNameProvider is the default cache for types.
 var DefaultJSONNameProvider = NewNameProvider()
 
 // NameProvider represents an object capable of translating from go property names
-// to json property names
+// to json property names.
+//
 // This type is thread-safe.
+//
+// See [github.com/go-openapi/jsonpointer.Pointer] for an example.
 type NameProvider struct {
 	lock  *sync.Mutex
 	index map[reflect.Type]nameIndex

jsonname_test.go → jsonname/name_provider_test.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package swag
+package jsonname
 
 import (
 	"reflect"