# Interface TextResourceFactory

public interface TextResourceFactory
Creates `TextResource`s backed by sources such as strings, files, and archive entries.

Example usages:

    def sourcedFromString = resources.text.fromString("some text content")

    def sourcedFromFile = resources.text.fromFile("path/to/file.txt")

    task someTask {} // assumption: produces a text file and declares it as output
    def sourcedFromTask = resources.text.fromFile(someTask)

    def sourcedFromArchiveEntry =
      resources.text.fromArchiveEntry("path/to/archive.zip", "path/to/archive/entry.txt")

    configurations { someConfig } // assumption: contains a single archive
    def sourcedFromConfiguration =
      resources.text.fromArchiveEntry(configurations.someConfig, "path/to/archive/entry.txt")

    def sourceFromUri = resources.text.fromUri("https://example.com/resource")

    def sourceFromInsecureUri = resources.text.fromInsecureUri("http://example.com/resource")

File based factory methods optionally accept a character encoding. If no encoding is specified, the platform's default encoding is used.

Since:
  2.2

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TextResource`
  `fromArchiveEntry(Object archive, String path)`
  Same as `fromArchiveEntry(archive, path, Charset.defaultCharset().name())`.
  `TextResource`
  `fromArchiveEntry(Object archive, String entryPath, String charset)`
  Creates a text resource backed by the archive entry at the given path within the given archive.
  `TextResource`
  `fromFile(Object file)`
  Same as `fromFile(file, Charset.defaultCharset())`.
  `TextResource`
  `fromFile(Object file, String charset)`
  Creates a text resource backed by the given file.
  `TextResource`
  `fromInsecureUri(Object uri)`
  Creates a text resource backed by the given uri.
  `TextResource`
  `fromString(String string)`
  Creates a text resource backed by the given string.
  `TextResource`
  `fromUri(Object uri)`
  Creates a text resource backed by the given uri.

- ## Method Details

  - ### fromString

    TextResource fromString(String string)
    Creates a text resource backed by the given string.
    Parameters:
      `string` - a string
    Returns:
      a text resource backed by the given string
    Since:
      2.2

  - ### fromFile

    TextResource fromFile(Object file, String charset)
    Creates a text resource backed by the given file.
    Parameters:
      `file` - a text file evaluated as per `Project.files(Object...)`
      `charset` - the file's character encoding (e.g. `"utf-8"`)
    Returns:
      a text resource backed by the given file
    Since:
      2.2

  - ### fromFile

    TextResource fromFile(Object file)
    Same as `fromFile(file, Charset.defaultCharset())`.
    Since:
      2.2
    See Also:
      - `fromFile(Object, String)`

  - ### fromArchiveEntry

    TextResource fromArchiveEntry(Object archive, String entryPath, String charset)
    Creates a text resource backed by the archive entry at the given path within the given archive. The archive format is determined based on the archive's file extension. If the archive format is not supported or cannot be determined, any attempt to access the resource will fail with an exception.
    Parameters:
      `archive` - an archive file evaluated as per `Project.files(Object...)`
      `entryPath` - the path to an archive entry
      `charset` - the archive entry's character encoding (e.g. `"utf-8"`)
    Returns:
      a text resource backed by the archive entry at the given path within the given archive
    Since:
      2.2

  - ### fromArchiveEntry

    TextResource fromArchiveEntry(Object archive, String path)
    Same as `fromArchiveEntry(archive, path, Charset.defaultCharset().name())`.
    Since:
      2.2

  - ### fromUri

    TextResource fromUri(Object uri)
    Creates a text resource backed by the given uri.
    Parameters:
      `uri` - a URI as evaluated by `Project.uri(Object)`
    Returns:
      a text resource backed by the given uri
    Since:
      4.8

  - ### fromInsecureUri

    TextResource fromInsecureUri(Object uri)
    Creates a text resource backed by the given uri. NOTE: This method allows insecure protocols (like HTTP) to be used. Only use this method if you're comfortable with the dangers.
    Parameters:
      `uri` - a URI as evaluated by `Project.uri(Object)`
    Returns:
      a text resource backed by the given uri
    Since:
      6.0
    See Also:
      - `fromUri(Object)`