sshare/README.md

# SSHare

Upload files to a server via ssh

## Installing

SSHare is not available on [PyPI](https://pypi.org).
To install it you will need to clone the repo and use pip to install it
```
git clone https://forge.monodon.me/Gnarwhal/sshare.git
cd sshare
pip install ./
```

By default, the only dependency SSHare has is the system's `ssh` (and `scp`) commands.
Beyond that it only utilises the python standard library.

### Additional Functionality

The base install is fairly bare bones in terms of functionality.
Included in the [`examples/`](https://forge.monodon.me/Gnarwhal/sshare_plugins) submodule, there is a sampling of
plugins which provide some additional conveniences

Refer to the above documentation for information on installing plugins

## Documentation - End User

Getting started with SSHare is about getting familiar with configuring SSHare.
SSHare configuration is all done in the `${XDG_CONFIG_DIR}/sshare` if set, or in `~/.config/sshare` otherwise.
In this directory are two important items: the `config.toml` file and the `plugins/` directory.

### `plugins/`

The `plugins/` directory is home to all external plugins. Installing a plugin is as simple as saving the
the plugin's `.py` file to the `plugins/`.

### `config.toml`

The configuration file can be broken down into three major components: `spec`, `config`, and `flags`.

#### `spec`

```toml

[spec.default]
name = [ "time", "extension" ]

[spec.example]
flag = { short = "e", long = "example" }
name = [ "preserve", "extension" ]

[spec.noshort]
flag = { long = "only" }
name = [ "time" ]
help = "No short flag, only long flag >:("
```

The `spec` section is a collection of different runtime specifications. The name of a specification is
unimportant with the exception of `default`, which is run when no other spec is activated. In each specification
that isn't `default`, there is a `flag` attribute that sets which command line arguments activate the
specification. The `flag` attribute must have one or both of `short` or `long`, where `short` will be set the flag
`-{short}` and `long` will set the flag `--{long}`. The `name` attribute of a specification is an array of name type
plugins which controls the order in which said plugins are executed. Specifications can also provide a brief description
in the `help` attribute, which will be displayed when `sshare --help` is run. In the example above,
running `sshare --help` would give
```
options:
  -e, --example         Use example spec
  --only                No short flag, only long flag >:(
```
#### `config`

```toml
[config.ssh]
host = "example.com"
path = "/directory/to/store/files/in"
port = 22
```

The `config` section is used to set configuration options for plugins. Refer to documentation for a plugin to see
what options can be set here. Documentation for default plugins is included [below](#Default-Plugins).

#### `flags`

```toml
[flags.file]
file = { short = "f" }

[flags.stdin]
stdin = { short = "" }

[flags.example]
option = { short = "o", long = "ooooption" }
```

The `flags` section is used to bind plugin arguments to a command line argument. They are specified in the same way
as the `flag` option for `spec`s. If `long` is left unspecified, the long flag will be set to the default provided by
the plugin. In the example above, running `sshare --help` would give:
```
options:
  -f file, --file file  Upload a file
  -, --stdin            Upload from stdin
  -o xmpl, --ooooption xmpl
                        This is not a real plugin that exists
```

### Default Plugins

#### `command_line`

A `logger` plugin which prints to the command line. No configuration needed.

#### `extension`

A `name` plugin which appends the source type to the end of the file name (i.e. `txt`, `png`, etc...). No configuration needed.

#### `file`

A `source` plugin which provides a file to be uploaded. File is specified with the `--file {file_path}` argument. No configuration needed.

#### `preserve`

A `name` plugin which preserves the name of the source in the uploaded file. No configuration needed.

#### `print_location`

A `feedback` plugin which prints the location that sources can be accessed from. No configuration needed.

#### `ssh`

An `upload` plugin which uploads the sources to the server using `ssh`.

##### Configuration
| Attribute | Type   | Default | Description                                          |
|-----------|--------|---------|------------------------------------------------------|
| host      | string | None    | The hostname to ssh into                             |
| path      | string | None    | The path of the directory to upload the sources into |
| port      | int    | 22      | The port to ssh into                                 |
| user      | string | $USER   | The user to ssh as                                   |

#### `stdin`

A `source` plugin which reads from stdin. No configuration needed.

#### `time`

A `name` plugin which adds the current unix time to the name of the of the uploaded file.

##### Configuration
| Attribute | Type   | Default | Description                                          |
|-----------|--------|---------|------------------------------------------------------|
| format    | int    | 62      | The base between 2 and 62 to represent the number in |

##### `uri`

A `location` plugin which constructs the resulting URI that the uploaded file can be accessed from.

##### Configuration
| Attribute | Type   | Default | Description                                          |
|-----------|--------|---------|------------------------------------------------------|
| protocol  | string | https   | The protocol of the URI                              |
| host      | string | None    | The hostname the file can be accessed from           |
| port      | int    | 22      | The port the file can be accessed at                 |
| path      | string | None    | The path the file can be accessed at                 |

## Documentation - Plugin Development

Coming soon...