Discussion: Simplify the API for newcomers

[Hombre-x]

As @TonioGela and @armanbilge suggested, the API is bloated with difficult concepts such as Resources or context abstractions.

To ensure that newcomers are not hindered in their encounter with these things, some deletion - refactoring - changing of the API was suggested to improve the experience with the library in general.

This PR aims to open a discussion to merge some of these changes and further discuss if some more changes are required to accomplish this goal of enhancing the experience of new users.

What has been done so far:

• Delete the readStream function to get rid of the Stream type and concepts.
• Squash the WithCharset method with their standalone variant (similar to os-lib) style.
• Changed the signature of the tempFile and tempDirectory to not return a Resource.
• Refactored some tests to deal with the new API.

Whats left to discuss:

The As variant of the three standalone methods was unchanged as I think we should talk before If I may get rid only of the typeclass use and instead add the codec as a dependency in the parameters, or, get rid of the methods entirely as well as with its example in the documentation.

[TonioGela]

The simplification looks good, but I think you can do further, for example:

-def list(path: Path): Stream[IO, Path] = files.list(path)
+def list(path: Path): IO[List[Path]] = files.list(path).compile.toList

-  def open(path: Path, flags: Flags): Resource[IO, FileHandle[IO]] =
-   files.open(path, flags)

-  def readCursor(path: Path, flags: Flags): Resource[IO, ReadCursor[IO]] =
-   files.readCursor(path, flags)

The As variant of the three standalone methods was unchanged as I think we should talk before If I may get rid only of the typeclass use and instead add the codec as a dependency in the parameters, or, get rid of the methods entirely as well as with its example in the documentation.

The thing is that I don't think any newcomer will ever use this methods, nor write a codec for something, BUT if we write a short tutorial on "how to implement your own saving format for your application" I might be in favor of keeping it there. It's not the main goal of this library, but we can discuss it.

Keep up with the good work. I'm willing to also see the site/doc changes that you're doing.
Cheers.

[zetashift]

For read weren't we going to default to UTF-8?

EDIT: nvm see it correctly now!

[TonioGela]

For read weren't we going to default to UTF-8?

EDIT: nvm see it correctly now!

What have you seen? I'm asking it because I forgot what we decided about it, and forcing users to specify UTF-8 everywhere is a no-go.

[Hombre-x]

I guess he saw that the read method wasn't overloaded 🤔

[TonioGela]

I guess he saw that the read method wasn't overloaded 🤔

Okay, but do we have just a single read method now? The one that doesn't default to utf-8? That's a no-go.

[zetashift]

Okay, but do we have just a single read method now? The one that doesn't default to utf-8? That's a no-go.
We default to utf8:

shellfish/core/src/main/scala/io/chrisdavenport/shellfish/FilesOs.scala

Line 52 in 7291083

def read(path: Path): IO[String] = files.readUtf8(path).compile.string

I guess he saw that the read method wasn't overloaded 🤔
Yup, exactly what happened :P

[lenguyenthanh]

I added a small name-shedding comment, which shouldn't block this pr.
Great works @Hombre-x and everyone!

[Hombre-x]

Names changed 😀