Skip to content

Commit

Permalink
Merge branch 'cleanup-readme'
Browse files Browse the repository at this point in the history
  • Loading branch information
@Phanabani
Phanabani committed Apr 19, 2021
2 parents c18b933 + 338efd6 commit 053f6c1
Show file tree
Hide file tree
Showing 3 changed files with 202 additions and 59 deletions.
111 changes: 52 additions & 59 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -106,49 +106,13 @@ You can enable it on the bot page of your application (https:\/\/discord.com/dev

## Config

Sandpiper can be configured with a JSON file at `./sandpiper/config.json`.
Sandpiper can be configured with a JSON file at `sandpiper/config.json`.
[sandpiper/config_example.json](sandpiper/config_example.json) contains
default values and can be used as a template. `bot_token` is the only required
field.

### Config Fields

#### Root

Fields in the root JSON object.

Key | Value
--- | -----
`bot_token` *(string)* | Your [Discord bot's](https://discord.com/developers/docs/topics/oauth2#bots) access token

#### Bot

Fields in `(root).bot` which describe the bot itself. See also
the [discord.py bot documentation](https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#bot)
for more info on how these fields are used.

Key | Value
--- | -----
`command_prefix` *(string)* | What users type to run a command
`description` *(string)* | Description of the bot (used in help messages)

#### Logging

Fields in `(root).logging` which describe how logging is performed. Sandpiper
uses rotating logging to write log files which rotate in specified intervals.
See also the
[TimedRotatingFileHandler documentation](https://docs.python.org/3/library/logging.handlers.html#timedrotatingfilehandler)
for more info on how these fields are used.

Key | Value
--- | -----
`sandpiper_logging_level` *(string)* | Sandpiper's most verbose logging level. Must be one of ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').
`discord_logging_level` *(string)* | discord.py's most verbose logging level. Must be one of ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').
`output_file` *(string)* | Absolute or relative (to sandpiper module) filepath to output logs to (including filename)
`when` *(string)* | Type of time interval for rotating log files. Must be one of ('S', 'M', 'H', 'D', 'midnight')
`interval` *(integer)* | Number of specified time intervals that must elapse before rotating to a new log file
`backup_count` *(integer)* | Number of backup log files to retain (deletes oldest after limit is reached)
`format` *(string)* | Format string used when writing log messages ([format string reference](https://docs.python.org/3/library/logging.html#logrecord-attributes))
See [Config](docs/config.md) for detailed information about setting up the
config file.

## Commands and features

Expand All @@ -158,8 +122,18 @@ In servers, commands must be prefixed with the configured command prefix
### Unit conversion

Convert measurements written in regular messages! Just surround a measurement
in {curly brackets} and Sandpiper will convert it for you. You can put
multiple measurements in a message as long as each is put in its own brackets.
in curly brackets -- like this: `{5 ft}` -- and Sandpiper will convert it for
you. You can put multiple measurements in a message as long as each is put in
its own brackets.

Many measurements are converted by default without needing to specify an output
unit. Read [Default unit mappings](docs/default_unit_mappings.md) to see all
currently supported default conversions.

You can explicitly specify an output unit like this: `{2 tonnes > lbs}`.
This opens up to you nearly any unit conversion you may need.

Lastly, you can do math in conversions, too! `{2.3 ft + 5 in}`

#### Examples

Expand All @@ -172,41 +146,60 @@ multiple measurements in a message as long as each is put in its own brackets.
> Lou lives about **{15km}** from me and TJ's staying at a hotel **{1.5km}**
> away, so he and I are gonna meet up and drive over to Lou.
#### Supported units:
> I weigh about 9.3 stone. For you americans, that's **{9.3 stone > lbs}**
> my two favorite songs are **{5min+27s}** and **{4min+34s}**. that's a total
> time of **{5min+27s + 4min+34s > s}** seconds
Metric | Imperial
------ | --------
Kilometer `km` | Mile `mi`
Meter `m` | Foot `ft or '`
Centimeter `cm` | Inch `in or "`
Kilogram `kg` | Pound `lbs`
Celsius `C or degC or °C` | Fahrenheit `F or degF or °F`
> hey sandpiper what's {30 * 7}?
### Time conversion

Just like [unit conversion](#unit-conversion), you can also convert times
between timezones! Surround a time in {curly brackets} and Sandpiper will
convert it to the different timezones of users in your server.
between timezones! Surround a time in curly brackets `{5:30pm}` and Sandpiper
will convert it to the different timezones of users in your server.

Times can be formatted in 12- or 24-hour time and use colon separators (HH:MM).
12-hour times can optionally include AM or PM to specify what half of the day
you mean. If you don't specify, AM will be assumed.

You can use the keywords `now`, `midnight`, and `noon` instead of a numeric time.

You can put multiple times in a message as long as each is put in its own brackets.

To use this feature, you and your friends need to set your timezones with the
`timezone set` command (see the [bio commands section](#setting-your-info)
for more info).
You can explicitly specify input and output timezones very similarly to
how units are specified in unit conversion:

Timezone specification | How to write | What it does
---------------------- | ------------ | ------------
Input timezone | `{5:45 PM London}` | Converts 5:45 PM in London time to all timezones of users in your server
Output timezone | `{5:45 PM > Los Angeles}` | Converts 5:45 PM from your timezone to Los Angeles time
Input & output timezone | `{5:45 PM Amsterdam > Helsinki}` | Converts 5:45 PM in Amsterdam time to Helsinki time

To use this feature without having to specify input/output timezones every time,
you and your friends need to set your timezones with the `timezone set` command
(see the [bio commands section](#setting-your-info) for more info).

#### Examples

> do you guys wanna play at {9pm}?
> do you guys wanna play at **{9pm}**?
> I wish I could, but I'm busy from {14} to {17:45}
> I wish I could, but I'm busy from **{14}** to **{17:45}**
> yeah I've gotta wake up at {5} for work tomorrow, so it's an early bedtime
> yeah I've gotta wake up at **{5}** for work tomorrow, so it's an early bedtime
> for me
> ugh I have a 2 hr meeting at **{noon}** tomorrow
> my flight took off at **{7pm new york}** and landed at **{8 AM london}**
> what time is it in dubai right now? **{now > dubai}**
> the game's releasing at **{1 PM > new york}** for americans and
> **{1500 > london}** for europeans
> hey alex, jaakko's getting on at **{8 pm helsinki > amsterdam}**
### Bios

Store some info about yourself to help your friends get to know you more easily!
Expand Down Expand Up @@ -295,13 +288,13 @@ python -m pip install -r requirements-dev.txt
#### Run unit tests

```bash
python -m sandpiper.tests
python -m pytest --pyargs sandpiper
```

#### Run tests with code coverage

```bash
coverage run -m sandpiper.tests
coverage run -m pytest --pyargs sandpiper
coverage html
```

Expand Down
45 changes: 45 additions & 0 deletions docs/config.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Config

Sandpiper can be configured with a JSON file at `sandpiper/config.json`.
[sandpiper/config_example.json](sandpiper/config_example.json) contains
default values and can be used as a template. `bot_token` is the only required
field.

## Config Fields

### Root

Fields in the root JSON object.

Key | Value
--- | -----
`bot_token` *(string)* | Your [Discord bot's](https://discord.com/developers/docs/topics/oauth2#bots) access token

### Bot

Fields in `(root).bot` which describe the bot itself. See also
the [discord.py bot documentation](https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#bot)
for more info on how these fields are used.

Key | Value
--- | -----
`command_prefix` *(string)* | What users type to run a command
`description` *(string)* | Description of the bot (used in help messages)

### Logging

Fields in `(root).logging` which describe how logging is performed. Sandpiper
uses rotating logging to write log files which rotate in specified intervals.
See also the
[TimedRotatingFileHandler documentation](https://docs.python.org/3/library/logging.handlers.html#timedrotatingfilehandler)
for more info on how these fields are used.

Key | Value
--- | -----
`sandpiper_logging_level` *(string)* | Sandpiper's most verbose logging level. Must be one of ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').
`discord_logging_level` *(string)* | discord.py's most verbose logging level. Must be one of ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').
`output_file` *(string)* | Absolute or relative (to sandpiper module) filepath to output logs to (including filename)
`when` *(string)* | Type of time interval for rotating log files. Must be one of ('S', 'M', 'H', 'D', 'midnight')
`interval` *(integer)* | Number of specified time intervals that must elapse before rotating to a new log file
`backup_count` *(integer)* | Number of backup log files to retain (deletes oldest after limit is reached)
`format` *(string)* | Format string used when writing log messages ([format string reference](https://docs.python.org/3/library/logging.html#logrecord-attributes))
105 changes: 105 additions & 0 deletions docs/default_unit_mappings.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
# Default unit mappings

When no output unit is specified, Sandpiper will try to convert to another
related unit. Some units convert two ways (Celsius <-> Fahrenheit), and others
map only one way for simplicity (Kelvin -> Celsius).

## Two-way

The units in each row will convert to each other.

### Length
Metric | Imperial
------ | --------
Kilometre `km` | Mile `mi`
Metre `m` | Foot `ft or '`
Centimetre `cm` | Inch `in or "`

### Area
Metric | Imperial
------ | --------
Hectare `ha` | Acre `acre`

### Speed
Metric | Imperial
------ | --------
Kilometre per hour `kph or km/h` | Mile per hour `mph or mi/h`

### Mass
Metric | Imperial
------ | --------
Gram `g` | Ounce `oz`
Kilogram `kg` | Pound `lb or lbs`

### Volume
Metric | Imperial
------ | --------
Litre `L` | Gallon (US) `gal`
Millilitre `ml` | Cup `cup`

### Pressure
Metric | Imperial
------ | --------
Pascal `pascal` | Pound\[-force] per square inch `psi`

### Temperature
Metric | Imperial
------ | --------
Celsius `C or degC or °C` | Fahrenheit `F or degF or °F`

### Energy
Metric | Imperial
------ | --------
Joule `J` | Foot pound `ft_lb or foot_pound`

### Angle
Radian | Degree
------ | --------
Radian `rad` | Degree `deg`



## One-way

Only the units on the left will map to the unit on the right.

### Length
From | To
---- | ---
Yard `yd` | Metre `m`

### Speed
From | To
---- | ---
Metre per second `mps or m/s` | Kilometre per hour `kph or km/h`
Foot per second `ft/s` | Mile per hour `mph or mi/h`

### Mass
From | To
---- | ---
Stone `stone` | Kilogram `kg`

### Volume
From | To
---- | ---
Pint `pint` | Litre `L`
Fluid ounce `floz` | Millilitre `ml`

### Pressure
From | To
---- | ---
Atmosphere `atm` | Pound\[-force] per square inch `psi`
Bar `bar` | Pound\[-force] force per square inch `psi`

### Temperature
From | To
---- | ---
Kelvin `K` | Celsius `C or degC or °C`

### Time
From | To
---- | ---
Second `s or sec` | Minute `min`
Minute `min` | Hour `h or hr`
Hour `h or hr` | Day `day`
Day `day` | Week `week`

0 comments on commit 053f6c1

Please sign in to comment.