feat: add embedded file utilities

Author: mekramy

README.md

@@ -1,11 +1,6 @@
 # Flexible File System
 
-![GitHub Tag](https://img.shields.io/github/v/tag/go-universal/fs?sort=semver&label=version)
-[![Go Reference](https://pkg.go.dev/badge/github.com/go-universal/fs.svg)](https://pkg.go.dev/github.com/go-universal/fs)
-[![License](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/go-universal/fs/blob/main/LICENSE)
-[![Go Report Card](https://goreportcard.com/badge/github.com/go-universal/fs)](https://goreportcard.com/report/github.com/go-universal/fs)
-![Contributors](https://img.shields.io/github/contributors/go-universal/fs)
-![Issues](https://img.shields.io/github/issues/go-universal/fs)
+![GitHub Tag](https://img.shields.io/github/v/tag/go-universal/fs?sort=semver&label=version) [![Go Reference](https://pkg.go.dev/badge/github.com/go-universal/fs.svg)](https://pkg.go.dev/github.com/go-universal/fs) [![License](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/go-universal/fs/blob/main/LICENSE) [![Go Report Card](https://goreportcard.com/badge/github.com/go-universal/fs)](https://goreportcard.com/report/github.com/go-universal/fs) ![Contributors](https://img.shields.io/github/contributors/go-universal/fs) ![Issues](https://img.shields.io/github/issues/go-universal/fs)
 
 The `fs` package provides a flexible file system abstraction for working with both local and embedded file systems. It offers various utilities for file operations such as checking existence, reading files, searching, and more.
 
@@ -40,7 +35,7 @@ Creates a `FlexibleFS` instance backed by the provided embedded file system.
 //go:embed *.go
 var embeds embed.FS
 
-fs := fs.NewEmbed(embeds)
+fs := fs.NewEmbed(embeds, "prefix")
 ```
 
 ## Exists
@@ -125,6 +120,30 @@ if err != nil {
 fmt.Println("Found files:", results)
 ```
 
+## PathOf
+
+Joins the provided path parts into a single normalized path, applying the file system's prefix if applicable.
+
+```go
+fullPath := embeddedFs.PathOf("relative", "path", "to", "file")
+```
+
+## Prefix
+
+Returns the path prefix for embedded file system.
+
+```go
+prefix := fs.Prefix()
+```
+
+## IsEmbedded
+
+Returns true if the file system is an embedded file system.
+
+```go
+isEmbedded := fs.IsEmbedded()
+```
+
 ## FS
 
 Returns the underlying `fs.FS` interface of the file system.

fs.go

@@ -33,6 +33,17 @@ type FlexibleFS interface {
 	// path. It returns a slice of paths of the found files and an error if any occurs.
 	Lookup(dir, pattern string) ([]string, error)
 
+	// PathOf joins the provided path parts into a single normalized path,
+	// applying the file system's prefix if applicable. It ensures the resulting
+	// path is consistent with the file system's internal structure and prefixing rules.
+	PathOf(parts ...string) string
+
+	// Prefix returns the path prefix for embedded file system.
+	Prefix() string
+
+	// IsEmbedded returns true if the file system is an embedded file system.
+	IsEmbedded() bool
+
 	// FS returns the underlying fs.FS interface of the file system.
 	FS() fs.FS
 

fs_flexible.go

@@ -12,22 +12,32 @@ import (
 
 // flexible is a concrete implementation of the FlexibleFS interface.
 type flexible struct {
-	files fs.FS
+	files      fs.FS
+	prefix     string
+	isEmbedded bool
 }
 
 // NewDir creates a FlexibleFS instance backed by the local file system
 // at the specified directory path.
 func NewDir(path string) FlexibleFS {
-	return &flexible{files: os.DirFS(path)}
+	return &flexible{
+		files:      os.DirFS(path),
+		prefix:     "",
+		isEmbedded: false,
+	}
 }
 
 // NewEmbed creates a FlexibleFS instance backed by the provided embedded
 // file system.
-func NewEmbed(embeddedFS embed.FS) FlexibleFS {
-	return &flexible{files: embeddedFS}
+func NewEmbed(embeddedFS embed.FS, prefix string) FlexibleFS {
+	return &flexible{
+		files:      embeddedFS,
+		prefix:     prefix,
+		isEmbedded: true,
+	}
 }
 
-func (f flexible) Exists(path string) (bool, error) {
+func (f *flexible) Exists(path string) (bool, error) {
 	path = normalizePath(path)
 	info, err := fs.Stat(f.files, path)
 
@@ -42,17 +52,17 @@ func (f flexible) Exists(path string) (bool, error) {
 	return !info.IsDir(), nil
 }
 
-func (f flexible) Open(path string) (fs.File, error) {
+func (f *flexible) Open(path string) (fs.File, error) {
 	path = normalizePath(path)
 	return f.files.Open(path)
 }
 
-func (f flexible) ReadFile(path string) ([]byte, error) {
+func (f *flexible) ReadFile(path string) ([]byte, error) {
 	path = normalizePath(path)
 	return fs.ReadFile(f.files, path)
 }
 
-func (f flexible) Find(dir, pattern string) (*string, error) {
+func (f *flexible) Find(dir, pattern string) (*string, error) {
 	var result string
 	dir = normalizePath(dir)
 
@@ -87,7 +97,7 @@ func (f flexible) Find(dir, pattern string) (*string, error) {
 	return &result, nil
 }
 
-func (f flexible) Search(dir, phrase, ignore, ext string) (*string, error) {
+func (f *flexible) Search(dir, phrase, ignore, ext string) (*string, error) {
 	var result string
 	var err error
 	dir = normalizePath(dir)
@@ -143,7 +153,7 @@ func (f flexible) Search(dir, phrase, ignore, ext string) (*string, error) {
 	return &result, nil
 }
 
-func (f flexible) Lookup(dir, pattern string) ([]string, error) {
+func (f *flexible) Lookup(dir, pattern string) ([]string, error) {
 	var result []string
 	dir = normalizePath(dir)
 
@@ -177,10 +187,25 @@ func (f flexible) Lookup(dir, pattern string) ([]string, error) {
 	return result, nil
 }
 
-func (f flexible) FS() fs.FS {
+func (f *flexible) PathOf(parts ...string) string {
+	if f.prefix == "" {
+		return normalizePath(append([]string{"."}, parts...)...)
+	}
+	return normalizePath(append([]string{".", f.prefix}, parts...)...)
+}
+
+func (f *flexible) Prefix() string {
+	return f.prefix
+}
+
+func (f *flexible) IsEmbedded() bool {
+	return f.isEmbedded
+}
+
+func (f *flexible) FS() fs.FS {
 	return f.files
 }
 
-func (f flexible) Http() http.FileSystem {
+func (f *flexible) Http() http.FileSystem {
 	return http.FS(f.files)
 }

fs_test.go

@@ -85,7 +85,7 @@ func TestDir(t *testing.T) {
 }
 
 func TestEmbed(t *testing.T) {
-	fs := fs.NewEmbed(embeds)
+	fs := fs.NewEmbed(embeds, "")
 	invalid := "missing.go"
 	valid := "fs.go"