github.com/puellanivis/breton@v0.2.16/lib/files/files.go (about)

     1  // Package files implements an abstraction of accessing data via URL/URIs.
     2  //
     3  // The basic usage of the library is fairly straight-forward:
     4  //
     5  //	import (
     6  //		"context"
     7  //		"fmt"
     8  //		"io"
     9  //		"os"
    10  //
    11  //		"github.com/puellanivis/breton/lib/files"
    12  //		_ "github.com/puellanivis/breton/lib/files/plugins"
    13  //	)
    14  //
    15  //	ctx = context.Background()
    16  //
    17  //	r, err := files.Open(ctx, "http://www.example.com")
    18  //	if err != nil {
    19  //		return err
    20  //	}
    21  //	// copy the response.Body from the HTTP request to stdout.
    22  //	if _, err := files.Copy(ctx, os.Stdout, r); err != nil {
    23  //		return err
    24  //	}
    25  //	r.Close()
    26  //
    27  //	w, err := files.Create(ctx, "clipboard:")
    28  //	if err != nil {
    29  //		// will return `os.IsNotExist(err) == true` if not available.
    30  //		return err
    31  //	}
    32  //	fmt.Fprint(w, "write this string to the OS clipboard if available")
    33  //	w.Close()
    34  //
    35  //	fi, err := files.List(ctx, "home:")
    36  //	if err != nil {
    37  //		return err
    38  //	}
    39  //	for _, info := range fi {
    40  //		// will print each filename and size listed in the user.Current().HomeDir
    41  //		fmt.Printf("%s %d\n", info.Name(), info.Size())
    42  //	}
    43  //
    44  // Additionally, there are some helper functions which simply read/write a whole byte slice.
    45  //
    46  //	b, err := files.Read(ctx, "source")
    47  //	if err != nil {
    48  //		return err
    49  //	}
    50  //	// no need to close here.
    51  //
    52  //	err := files.Write(ctx, "destination", b)
    53  //	if err != nil {
    54  //		// will return io.ErrShortWrite if it does not write all of the buffer.
    55  //		return err
    56  //	}
    57  //	// no need to close here.
    58  //
    59  // Or use io.ReaderCloser/io.WriteCloser as a source/destination
    60  //
    61  //	// discard and close all data on the io.ReadCloser
    62  //	if err := files.Discard(io.ReadCloser); err != nil {
    63  //		return err
    64  //	}
    65  //	// no need to close here.
    66  //
    67  //	// read all the data on the io.ReadCloser into a byte-slice, then close the source.
    68  //	b, err := files.ReadFrom(io.ReadCloser)
    69  //	if err != nil {
    70  //		return err
    71  //	}
    72  //	// no need to close here.
    73  //
    74  //	// write all the data from the byte-slice into the io.WriteCloser, then close the source.
    75  //	if err := files.WriteTo(io.WriteCloser, b); err != nil {
    76  //		return err
    77  //	}
    78  //	// no need to close here.
    79  package files
    80  
    81  import (
    82  	"io"
    83  	"os"
    84  )
    85  
    86  // File defines an interface that abstracts the concept of files to allow for multiple types implementation, beyond the local filesystem.
    87  type File interface {
    88  	io.Closer
    89  	Name() string
    90  	Stat() (os.FileInfo, error)
    91  }
    92  
    93  // Reader defines a files.File that is also an io.ReadSeeker
    94  type Reader interface {
    95  	File
    96  	io.ReadSeeker
    97  }
    98  
    99  // Writer defines a files.File that is also an io.Writer with a Sync() function.
   100  type Writer interface {
   101  	File
   102  	io.Writer
   103  	Sync() error
   104  }