---
title: "Understanding Connector Package Methods"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Understanding Connector Package Methods}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Introduction

We realized it might be confusing for users to understand which method returns which value. This vignette explains what each method does and provides an overview of general rules. This information is also helpful for developers creating their own connector packages, as it outlines what each method should return to maintain consistency and interoperability between different connector packages.

## Methods and Return Values

Below is a table summarizing the methods and their return values:

| Method                    | Return Value                                                      |
|---------------------------|-------------------------------------------------------------------|
| `read_cnt()`              | Content of the file                                               | 
| `write_cnt()`             | `Connector` object                                                |
| `list_content_cnt()`      | Vector of items                                                   |
| `remove_cnt()`            | `Connector` object                                                |
| `download_cnt()`          | `Connector` object                                                |
| `upload_cnt()`            | `Connector` object                                                |
| `create_directory_cnt()`  | `Connector` object, if `open = TRUE`, then new `Connector` object |
| `remove_directory_cnt()`  | `Connector` object                                                |
| `upload_directory_cnt()`  | `Connector` object, if `open = TRUE`, then new `Connector` object |
| `download_directory_cnt()`| `Connector` object                                                |
| `tbl_cnt()`               | Content of the table. Either `dplyr::tbl()` or from `read_cnt()`  |

## Detailed Explanations

### `read_cnt()`
Reads the content of a file and returns it directly. 
This allows users to immediately work with the data without additional steps.

### `write_cnt()`
After writing content to the `Connector`, this method returns the `Connector` object. 
This enables method chaining and provides confirmation that the write operation was successful.

### `list_content_cnt()`
Returns a `character` vector of items (files/directories) in the current `Connector` allowing users to explore the content structure.
 
### `remove_cnt()`
After removing a file or item, this method returns the `Connector` object, allowing for further operations and confirming the removal was successful.

### `download_cnt()`
This method returns the `Connector` object after a download operation to allow for method chaining.

### `upload_cnt()`
Similar to `download_cnt()`, this returns the `Connector` object after an upload, allowing for method chaining.

### `create_directory_cnt()`
This method returns the `Connector` object. If the `open` parameter is set to `TRUE`, it returns a new `Connector` object pointing to the newly created directory.

### `remove_directory_cnt()`
After removing a directory, this method returns the `Connector` object, allowing for further operations and confirming the removal was successful.

### `upload_directory_cnt()` 
Returns the current `Connector` object or a new one if the directory was opened (`open = TRUE`), allowing for immediate use of the uploaded directory.

### `download_directory_cnt()`
Returns the `Connector` object to allow for method chaining.

### `tbl_cnt()`
This method returns the content of a file in a tabular format. 
For file-based connectors, it typically uses `read_cnt()` to get the content. 
For database connections (`DBI`), it returns a `dplyr::tbl()` representation of the data.