README.md 6.87 KB
Newer Older
Michael Rouse's avatar
No link  
Michael Rouse committed
1
[![Time Slime][time-slime-logo]](#)
Michael Rouse's avatar
Spacing  
Michael Rouse committed
2

Michael Rouse's avatar
Logo  
Michael Rouse committed
3
[![Time Slime - Scooby Doo Villain][time-slime-villain]](http://scoobydoo.wikia.com/wiki/Time_Slime)
4

Michael Rouse's avatar
Michael Rouse committed
5
Time Slime is a [C library](#library-documentation) for implementation of a basic time sheet program.
6

Michael Rouse's avatar
Michael Rouse committed
7
It uses an SQLITE database to store logs, and allows you to clock in/out as well as add a set number of hours.
8

Michael Rouse's avatar
Michael Rouse committed
9
There is also a [shell interface](#terminal-usage) for using only the library from the terminal.
10

Michael Rouse's avatar
Michael Rouse committed
11
 
12

Michael Rouse's avatar
Michael Rouse committed
13
# Getting Started
14

Michael Rouse's avatar
Michael Rouse committed
15 16 17
To use this as a library in another program, you need the `timeslime.h` and `timeslime.c` files.

If your project already includes SQLITE, then replace this line, in `timeslime.h`:
Michael Rouse's avatar
Michael Rouse committed
18
```c
Michael Rouse's avatar
Michael Rouse committed
19 20 21
#include "third_party/sqlite3/sqlite3.h"
```
With:
Michael Rouse's avatar
Michael Rouse committed
22
```c
Michael Rouse's avatar
Michael Rouse committed
23 24 25 26 27 28 29
#include "path/to/sqlite3.h"
```
Pointing to your `sqlite3.h` file.

If your project is NOT using SQLITE, then you need to take `third_party/sqlite3/sqlite3.h` and `third_party/sqlite3/sqlite3.c` as well,
and change the path to `sqlite3.h` in `timeslime.h` based on where you place the files.

Michael Rouse's avatar
Michael Rouse committed
30 31
## Building
To build the command line utility, you can just run:
Michael Rouse's avatar
Michael Rouse committed
32

Michael Rouse's avatar
Michael Rouse committed
33
> make
Michael Rouse's avatar
Michael Rouse committed
34

Michael Rouse's avatar
Michael Rouse committed
35 36
on Windows or Linux.

Michael Rouse's avatar
Michael Rouse committed
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
 

# Library Documentation

The Time Slime library has the following functions available for use:
```c
TIMESLIME_STATUS_t TimeSlime_Initialize(char directory_for_database[]);

TIMESLIME_STATUS_t TimeSlime_Close(void);

TIMESLIME_STATUS_t TimeSlime_AddHours(float hours, TIMESLIME_DATE_t date);

TIMESLIME_STATUS_t TimeSlime_ClockIn(TIMESLIME_DATETIME_t time);

TIMESLIME_STATUS_t TimeSlime_ClockOut(TIMESLIME_DATETIME_t time);

TIMESLIME_STATUS_t TimeSlime_GetReport(TIMESLIME_DATE_t start, TIMESLIME_DATE_t end, TIMESLIME_REPORT_t **out);

void TimeSlime_FreeReport(TIMESLIME_REPORT_t **report);

char*  TimeSlime_StatusCode(TIMESLIME_STATUS_t status);
```

### Time Slime Status
`TIMESLIME_STATUS_t` is a type alias for `int`, and can be one of the following (defined in `timeslime.h`):
Michael Rouse's avatar
Michael Rouse committed
62

Michael Rouse's avatar
Michael Rouse committed
63 64 65 66 67 68 69 70 71 72 73 74 75
|Value|Description|
|-----|------------|
|`TIMESLIME_OK`|No problems or errors|
|`TIMESLIME_UNKOWN_ERROR`|Unkown error prevented function from finishing|
|`TIMESLIME_SQLITE_ERROR`|Problem executing SQLITE actions|
|`TIMESLIME_INVALID_YEAR`|Invalid year in parameter object|
|`TIMESLIME_INVALID_MONTH`|Invalid month in parameter object|
|`TIMESLIME_INVALID_DAY`|Invalid day in parameter object|
|`TIMESLIME_INVALID_HOUR`|Invalid hour in parameter object|
|`TIMESLIME_INVALID_MINUTE`|Invalid minute in parameter object|
|`TIMESLIME_ALREADY_CLOCKED_IN`|Unable to clock in since a clock out action has not been performed|
|`TIMESLIME_NOT_CLOCKED_IN`|Unable to clock out since a clock in action has not been performed|
|`TIMESLIME_NO_ENTIRES`|No time sheet entries were found for a given date range|
Michael Rouse's avatar
Michael Rouse committed
76 77
|`TIMESLIME_NOT_INITIALIZED`|`TimeSlime_Initialize(char[])` has not been called yet|

Michael Rouse's avatar
Michael Rouse committed
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97

If you want to get a string key that represents a status code,
use the `TimeSlime_StatusCode(TIMESLIME_STATUS_t)` method, and pass in the status code. A string will be returned.

## Inititialization
The `TimeSlime_Initialize(char[])` function needs to be called before any other Time Slime methods. This is responsible for creating the SQLITE database if it does not exist.

The parameter passed to this should be the directory to place the the `timeslime.db` file (**WITHOUT** a trailing slash).

## Closing
The `TimeSlime_Close()` function needs to be called before exiting your program, it is responsible for safely disposing of allocated memory.


## Adding Hours
It might be desired to add a set number of hours to a time sheet for a specific date (rather than clocking in and out).

This is where the `TimeSlime_AddHours(float, TIMESLIME_DATE_t)` functions comes in.

The function accepts a `float`, which is the number of hours worked. Then a `TIMESLIME_DATE_t` struct, which is the date to add the hours to.

Michael Rouse's avatar
Michael Rouse committed
98
[See more about `TIMESLIME_DATE_t`](#library-datatypes).
Michael Rouse's avatar
Michael Rouse committed
99 100 101 102 103 104

## Clocking In and Out
To clock in and out of the time sheet, use the `TimeSlime_ClockIn(TIMESLIME_DATETIME_t)` and `TimeSlime_ClockOut(TIMESLIME_DATETIME_t)` functions.

Each function accepts a `TIMESLIME_DATETIME_t` struct, which represents the date and time that the clock in, clock out should be performed on.

Michael Rouse's avatar
Michael Rouse committed
105
[See more about `TIMESLIME_DATETIME_t`](#library-datatypes).
Michael Rouse's avatar
Michael Rouse committed
106 107 108 109 110 111 112 113 114 115


## Reports
Generating a report will show you how many hours have been worked per day for a certain date range.

`TimeSlime_GetReport(TIMESLIME_DATE_t start, TIMESLIME_DATE_t end, TIMESLIME_REPORT_t **out)`
will generate a report between the `start` and `end` dates.

The result will be placed in the `TIMESLIME_REPORT_t` pointer, and this needs to be passed a pointer to that pointer.

116 117
When you are done, use `TimeSlime_FreeReport(TIMESLIME_REPORT_t**)` to clear allocated memory.

Michael Rouse's avatar
Michael Rouse committed
118
[See more about `TIMESLIME_DATE_t` and `TIMESLIME_REPORT_t`](#library-datatypes).
Michael Rouse's avatar
Michael Rouse committed
119 120 121 122

 

# Library Datatypes
123
To avoid conflicts with other libraries, Time Slime defines custom datatypes for use with the library.
Michael Rouse's avatar
Michael Rouse committed
124 125

## Date and DateTime
126
The Date and DateTime structs are passed to several Time Slime functions.
Michael Rouse's avatar
Michael Rouse committed
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151

```c
struct TIMESLIME_DATE_STRUCT
{
    int year;
    int month;
    int day;
};
typedef struct TIMESLIME_DATE_STRUCT TIMESLIME_DATE_t;

struct TIMESLIME_DATETIME_STRUCT
{
    int year;
    int month;
    int day;
    int hour;
    int minute;
};
typedef struct TIMESLIME_DATETIME_STRUCT TIMESLIME_DATETIME_t;
```

Time Slime also defines some helpful directives to easily create these for the current time.

```c
#define TIMESLIME_DATE_NOW         (TIMESLIME_DATE_t){ 0, 0, 0}
152
#define TIMESLIME_TIME_NOW         (TIMESLIME_DATETIME_t){ 0, 0, 0, -1, -1 }
Michael Rouse's avatar
Michael Rouse committed
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
```

## Report
The `TIMESLIME_STATUS_REPORT_t` struct looks like:
```c
// Report Entry
struct TIMESLIME_REPORT_ENTRY_STRUCT
{
    float Hours;
    char Date[];
};
typedef struct TIMESLIME_REPORT_ENTRY_STRUCT TIMESLIME_REPORT_ENTRY_t;

// Time Sheet Report
struct TIMESLIME_REPORT_STRUCT
{
    int NumberOfEntries;
    TIMESLIME_REPORT_ENTRY_t Entries[];
};
typedef struct TIMESLIME_REPORT_STRUCT TIMESLIME_REPORT_t;
```


 

# Terminal Usage
Michael Rouse's avatar
Michael Rouse committed
179 180 181
Once build, if you add the executable (in the `build` folder) to your system `PATH`, you can run it with the following commands:

```shell
182 183 184
# Show information and command help
> timeslime help

Michael Rouse's avatar
Michael Rouse committed
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200
# Add an amount of time to the current date
> timeslime add [hours]

# Add an amount of time to a specific date
> timeslime add [hours] [date]

# Clock in
> timeslime clock in

# Clock out
> timeslime clock out

# Run a report
> timeslime report [start-date] [end-date]
```

Michael Rouse's avatar
Logo  
Michael Rouse committed
201 202
> **IMPORTANT**: All dates must be formatted as either `YYYY-MM-DD` or `YYYY/MM/DD`

203 204 205 206 207 208 209 210
 

# Todo
- [ ] Better report formatting (done?)
- [ ] Allow second parameter of a report to be "today"
- [ ] Shell program to prompt user for choices if no parameters (or not all parameters) are given (but works on all systems)
- [ ] Imrpove logging

Michael Rouse's avatar
Logo  
Michael Rouse committed
211 212 213 214 215 216 217 218 219 220

 

 

Font used in logo is [*Liquidism*](https://www.dafont.com/liquidism.font?fpp=50)


[time-slime-logo]: extras/images/logo.png
[time-slime-villain]: extras/images/Time_Slime.jpg