https://github.com/stynh/styme
A zero-dependency library that allows for manipulating dates and times using natural language.
https://github.com/stynh/styme
date datetime datetime-library natural-language time
Last synced: 3 days ago
JSON representation
A zero-dependency library that allows for manipulating dates and times using natural language.
- Host: GitHub
- URL: https://github.com/stynh/styme
- Owner: StynH
- License: mit
- Created: 2025-10-02T08:24:11.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-10-03T17:03:26.000Z (4 months ago)
- Last Synced: 2025-10-03T19:08:35.958Z (4 months ago)
- Topics: date, datetime, datetime-library, natural-language, time
- Language: C#
- Homepage:
- Size: 135 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 
 
STYME is a lightweight, zero-dependency C# library for parsing simple natural-language date/time expressions and applying them to a base date/time.
## Usage Examples
### Basic
```csharp
using STYME;
// By default NaturalDateTime uses the current system time as the base
var parser = new NaturalDateTime();
var result = parser.Parse("add 2 days");
Console.WriteLine(result);
```
Output (example):
```
2025-10-04T14:23:00
```
You can parse expressions relative to a specific `DateTime` using `NaturalDateTime.From`.
```csharp
using STYME;
var baseTime = new DateTime(2020, 1, 1, 0, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("add 1 month");
Console.WriteLine(result);
```
Output:
```
2020-02-01T00:00:00
```
### Add
You can add time using the `add` keyword.
```csharp
using STYME;
var baseTime = new DateTime(2020, 3, 1, 12, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("add 1 year");
Console.WriteLine(result);
```
Output:
```
2021-03-01T00:00:00
```
### Deduct / Subtract
You can subtract time using the `deduct` (or `subtract`) keyword.
```csharp
using STYME;
var baseTime = new DateTime(2020, 3, 1, 12, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("deduct 1 month");
Console.WriteLine(result);
```
Output:
```
2020-02-01T12:00:00
```
### Chaining operations
You can chain multiple operations using `and`.
```csharp
using STYME;
var baseTime = new DateTime(2020, 1, 1, 0, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("add 3 days and deduct 5 hours");
Console.WriteLine(result);
```
Output:
```
2020-01-03T19:00:00
```
### Next
Use `next` to jump to the upcoming occurrence of a day of the week or a month. The time of day is preserved.
```csharp
using STYME;
var baseTime = new DateTime(2025, 1, 1, 8, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("next monday");
Console.WriteLine(result);
```
Output:
```
2025-01-06T08:00:00
```
This operator can also be chained with the `and` operator.
```csharp
using STYME;
var baseTime = new DateTime(2025, 1, 1, 8, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("next friday and add 2 hours");
Console.WriteLine(result);
```
Output:
```
2025-01-03T10:00:00
```
### End of week/month/year
Use `end` to move to the end of the current week, month, or year. Fillers such as `of` and `the` are optional.
```csharp
using STYME;
var baseTime = new DateTime(2025, 6, 15, 20, 45, 0);
var parser = NaturalDateTime.From(baseTime);
var result = parser.Parse("end of the month");
Console.WriteLine(result);
```
Output:
```
2025-06-30T20:45:00
```
### Recurring schedules
You can generate a lazy sequence of future dates using `every`. The sequence is infinite, so add your own break condition.
```csharp
using STYME;
var baseTime = new DateTime(2025, 1, 1, 0, 0, 0);
var parser = NaturalDateTime.From(baseTime);
var schedule = parser.Enumerate("every 2 weeks");
foreach (var occurrence in schedule)
{
Console.WriteLine(occurrence);
// Break when you reach the point you care about.
if (occurrence >= new DateTime(2025, 2, 12))
{
break;
}
}
```
Output:
```
2025-01-01T00:00:00
2025-01-15T00:00:00
2025-01-29T00:00:00
2025-02-12T00:00:00
```
### Supported units with `add` and `deduct`
The `add` and `deduct` expressions support the following units (singular and plural forms):
- `second`, `seconds`
- `minute`, `minutes`
- `hour`, `hours`
- `day`, `days`
- `week`, `weeks`
- `month`, `months`
- `year`, `years`
- `decade`, `decades`
- `century`, `centuries`
- `millennium`, `millennia`
Example:
```csharp
using STYME;
var parser = NaturalDateTime.From(new DateTime(2000, 1, 1));
Console.WriteLine(parser.Parse("add 2 decades")); // 2020-01-01
Console.WriteLine(parser.Parse("deduct 1 century")); // 1900-01-01
```
### Todo
* [x] Add month support (set DateTime to specific month)
* [x] Add day support (i.e. "next friday")
* [ ] Add complex time support (i.e. "quarter past five")
* [ ] Add multiple complex operations (i.e. "add one year then next friday")
## Support
* .NET 8.0 and later
## License
STYME is licensed under the [MIT License](LICENSE).