felixdorn / nest
Nest is a simple pseudo-programming language for defining repeatable and non-repeatable events in time.
Requires
- php: ^8.0
- nesbot/carbon: ^2.52
Requires (Dev)
- friendsofphp/php-cs-fixer: ^v3.0.0
- pestphp/pest: ^v1.16.0
- phpstan/phpstan: ^0.12.88
- symfony/var-dumper: ^5.2.0
This package is auto-updated.
Last update: 2024-11-13 21:48:01 UTC
README
Nest
Nest is a simple pseudo-programming language for defining repeatable and non-repeatable events in time.
Here are a couple examples of the syntax:
everyday at 7:00 for 3 minutes
tomorrow at 17:30 for an hour
every monday, saturday and sunday at 2 for 1h until 15/6/2021
Nest outputs a list of time periods.
Here's an example output for once 1/1/2021 from 15:00 to 16:00
:
[ ["starts_at" => "2021-01-01 15:00:00", "ends_at" => "2021-01-01 16:00:00"] ]
Features
- Natural syntax
- Error reporting
- Fast
Already know this stuff? Jump to the API documentation
Reproducibility
The same code could lead to a completely different output based on the current time.
Therefore, when storing Nest code, you should also store the current time if reproducibility is an issue for you (it probably is).
Keywords
Once
Once indicates that an event is repeated once at a given date.
for a day once 15/04/2005
Implicit once
You may omit the once keyword if you write it at the start of the program.
15/04/2005
processed as once 2005-04-15
at 6 15/04/2005
throws Syntax error, unexpected 15/04/2005
Every
Every indicates that an event is repeated it takes as a parameter one or many weekdays.
every monday and saturday
See how lists work here.
You may use the shorthand everyday
that compiles to every day of the week
everyday at 6:30
You may also use the shorthand weekend
that compiles to saturday and sunday
every weekend
For
For indicates how long an event lasts.
for one hour
Here's a guide on How you can quantify time in Nest
Here's a list of all the time measurement units you may use:
- minute
- hour
- day
- week
You may pluralize them to keep the sentence grammatically correct but the compiler won't pick up on it if you don't.
Shorthands such as 1h
(1 hour) are also allowed.
Here's a list of all available shorthands:
- m: minute
- h: hour
- d: day
- w: week
- min: minute
In
In sets the date of a non-repeatable event relatively to the current date.
in 5 days
Refer to the for keyword for a guide on time measurement units and how to quantify time.
Between
Between constrains the event between two dates.
between 12/04/2021 and 12/12/2021
If you wish to constrain an event between a time range, use from.
From ... to ...
From constrains the event between a time range.
from 22:00 to 23:05
Until
Until is a shorthand for the between keyword.
until 12/12/2021
The start date is the current time.
At
At defines at which time an event starts. It is often used in combination with for
that sets the duration of the
event.
at 6 for an hour
Lists
A list contains one or many literals such as monday
or 1:00
and these are separated with commas or the word and
.
monday, saturday and sunday
1:00,16:00
tuesday and sunday, monday
monday, saturday, sunday
Quantifying Time
You can use any number from one
to a sixty
in literal form.
for fifty-five minutes
You can use any non-negative integer such as 1
or 42
.
for 10 hours
To represent one unit of time, you may use a simpler form:
for an hour
for a day
The compiler doesn't make a difference if you write
a
oran
sofor a hour
still represents1 hour
even though it is grammatically incorrect.
API
Installation
If you don't have composer, you can download it here.
composer require felixdorn/nest
Usage
\Felix\Nest\Nest::compile( 'everyday for an hour at 12', \Carbon\CarbonPeriod::create( \Carbon\Carbon::now(), \Carbon\Carbon::now()->addWeek() ) # Optionally, you can also pass the current time as a third parameter. # \Carbon\Carbon::now() )
If your event does not have fixed boundaries set using between ... and ...
or until ...
, it repeats indefinitely.
Therefore, you need to set manual boundaries at compile-time hence the second CarbonPeriod
parameter. You can omit it
if you know that your event has fixed boundaries.