Cron

https://github.com/yys190/cron
Admin
Cron is a Go library that implements a cron spec parser and job runner, providing robust scheduling...
Tokens:43,553
Snippets:481
Trust Score:4.1
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Create, Add, and Start a Cron Scheduler

Source: https://github.com/yys190/cron/blob/master/_autodocs/00-START-HERE.md

This snippet demonstrates the basic setup for creating a new cron scheduler, adding a function to run on a specific schedule, and starting the scheduler. Ensure you defer the Stop() method to clean up resources.

```go
import "github.com/robfig/cron/v3"

// Create scheduler
c := cron.New()

// Add a job
c.AddFunc("0 * * * *", func() {
    fmt.Println("Every hour")
})

// Run it
c.Start()
defer c.Stop()
```

--------------------------------

### Install Cron V3

Source: https://github.com/yys190/cron/blob/master/README.md

Use 'go get' to download the specific tagged release of Cron V3. Requires Go 1.11 or later.

```bash
go get github.com/robfig/cron/v3@v3.0.0
```

--------------------------------

### Initialize and Start Cron Job

Source: https://github.com/yys190/cron/blob/master/_autodocs/00-START-HERE.md

Basic initialization of a cron instance and adding a job that runs hourly. Ensure to stop the cron instance when done.

```go
c := cron.New()
c.AddFunc("@hourly", myFunc)
c.Start()
defer c.Stop()
```

--------------------------------

### Basic Cron Scheduling in Go

Source: https://github.com/yys190/cron/blob/master/_autodocs/README.md

Demonstrates how to create a new cron scheduler, add functions or custom jobs to run on a schedule, start the scheduler, and keep it running.

```go
import "github.com/robfig/cron/v3"

c := cron.New()

// Run function on schedule
c.AddFunc("0 30 * * * *", func() {
    log.Println("Runs every hour at :30")
})

// Run custom job
type MyJob struct{}
func (j *MyJob) Run() { log.Println("Job running") }

c.AddJob("@daily", &MyJob{})

c.Start()
defer c.Stop()

// Keep scheduler running
select {}
```

--------------------------------

### Start the Cron Scheduler

Source: https://github.com/yys190/cron/blob/master/doc.md

Starts the cron scheduler, causing all jobs to be invoked according to their schedules.

```go
func (c *Cron) Start()
```

--------------------------------

### Start

Source: https://github.com/yys190/cron/blob/master/doc.md

Start the cron scheduler in its own goroutine, or no-op if already started.

```APIDOC
## Start

### Description
Starts the cron scheduler in a separate goroutine. If the scheduler has already been started, this operation has no effect.

### Signature
```go
func (c *Cron) Start()
```
```

--------------------------------

### Start

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/cron.md

Starts the cron scheduler in its own goroutine, or does nothing if already started. Jobs are executed asynchronously in separate goroutines according to their schedules.

```APIDOC
## Start()

### Description
Starts the cron scheduler in its own goroutine, or does nothing if already started. Jobs are executed asynchronously in separate goroutines according to their schedules.

### Parameters
None

### Method
None (This is a method signature, not an HTTP endpoint)

### Endpoint
None (This is a method signature, not an HTTP endpoint)

### Returns
None

### Example
```go
c := cron.New()
c.AddFunc("@hourly", func() { fmt.Println("Every hour") })
c.Start()  // Scheduler now runs in background

// Can add jobs to a running scheduler
c.AddFunc("@daily", func() { fmt.Println("Every day") })
```
```

--------------------------------

### Slash (/) Examples for Step Values

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

The slash (/) specifies step values, dividing a range into intervals. It can be used as '*/N' for every N values, 'N/M' for starting at N and stepping by M, or 'N-X/M' for a range with steps.

```text
*/15 * * * *         Every 15 minutes
```

```text
0 */4 * * *          Every 4 hours (0, 4, 8, 12, 16, 20)
```

```text
0 0 */2 * *          Every other day at midnight
```

```text
5 * * * *            At 5 minutes past every hour
```

```text
15 */3 * * *         At :15 of every 3rd hour (0:15, 3:15, 6:15, ...)
```

```text
0 9-17 * * *         Every hour from 9am-5pm
```

```text
0 9-17/2 * * *       Every 2 hours from 9am-5pm (9, 11, 1, 3, 5)
```

--------------------------------

### Start Cron Scheduler

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/cron.md

Starts the cron scheduler in a background goroutine. Jobs are executed asynchronously. This method is idempotent; it does nothing if the scheduler is already running.

```go
c := cron.New()
c.AddFunc("@hourly", func() { fmt.Println("Every hour") })
c.Start()  // Scheduler now runs in background

// Can add jobs to a running scheduler
c.AddFunc("@daily", func() { fmt.Println("Every day") })
```

--------------------------------

### Complete Custom Cron Configuration

Source: https://github.com/yys190/cron/blob/master/_autodocs/configuration.md

This example demonstrates a comprehensive configuration for the cron scheduler, including setting a specific timezone, a custom parser for Quartz-style cron expressions (with optional seconds), and a chain of middleware like recovery and skip-if-still-running. It also shows how to add jobs using various supported formats.

```go
package main

import (
    "log"
    "os"
    "time"
    "github.com/robfig/cron/v3"
)

func main() {
    // Set up logger
    logger := log.New(os.Stdout, "scheduler: ", log.LstdFlags)

    // Set up parser for Quartz-style (optional seconds)
    parser := cron.NewParser(
        cron.SecondOptional | cron.Minute | cron.Hour |
        cron.Dom | cron.Month | cron.Dow | cron.Descriptor)

    // Create cron with all custom options
    nyc, _ := time.LoadLocation("America/New_York")
    c := cron.New(
        cron.WithLocation(nyc),
        cron.WithParser(parser),
        cron.WithChain(
            cron.Recover(cron.VerbosePrintfLogger(logger)),
            cron.SkipIfStillRunning(cron.VerbosePrintfLogger(logger)),
        ),
        cron.WithLogger(cron.VerbosePrintfLogger(logger)),
    )

    // Add jobs - can use various formats now
    c.AddFunc("@hourly", func() {})                        // Descriptor
    c.AddFunc("30 * * * *"), func() {})                    // Standard 5-field
    c.AddFunc("0 0 * * *"), func() {})                     // Standard 5-field
    c.AddFunc("30 10 * * *"), func() {})                   // Optional seconds omitted
    c.AddFunc("30 0 10 * * *"), func() {})                 // Optional seconds included

    c.Start()
    defer c.Stop()

    select {} // Keep the program running
}
```

--------------------------------

### Custom Logger Implementation Example

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/logger.md

Provides a basic implementation of the Logger interface using Go's standard log package. This can be used to integrate custom logging logic.

```go
type MyLogger struct{}

func (l MyLogger) Info(msg string, keysAndValues ...interface{}) {
    log.Printf("[INFO] %s %v\n", msg, keysAndValues)
}

func (l MyLogger) Error(err error, msg string, keysAndValues ...interface{}) {
    log.Printf("[ERROR] %s: %v %v\n", msg, err, keysAndValues)
}

c := cron.New(cron.WithLogger(MyLogger{}))
```

--------------------------------

### Cron Logging Configuration

Source: https://github.com/yys190/cron/blob/master/_autodocs/README.md

Provides examples for configuring verbose logging for debugging using `VerbosePrintfLogger` and error-only logging for production using `PrintfLogger`.

```go
import (
    "log"
    "os"
    "github.com/robfig/cron/v3"
)

// Verbose logging for debugging
logger := cron.VerbosePrintfLogger(
    log.New(os.Stdout, "cron: ", log.LstdFlags))
c := cron.New(cron.WithLogger(logger))

// Error logging only for production
errLogger := cron.PrintfLogger(
    log.New(os.Stderr, "cron: ", log.LstdFlags))
c := cron.New(cron.WithLogger(errLogger))
```

--------------------------------

### Create and Run Cron Scheduler

Source: https://github.com/yys190/cron/blob/master/_autodocs/QUICK_REFERENCE.md

Demonstrates how to create a cron scheduler with a specific timezone, logger, and job recovery. It then adds two jobs: one hourly and one for weekdays at 9 AM. The scheduler is started and kept running.

```go
package main

import (
    "log"
    "os"
    "time"
    "github.com/robfig/cron/v3"
)

func main() {
    // Create scheduler with timezone and logging
    nyc, _ := time.LoadLocation("America/New_York")
    logger := cron.VerbosePrintfLogger(
        log.New(os.Stdout, "cron: ", log.LstdFlags))
    
    c := cron.New(
        cron.WithLocation(nyc),
        cron.WithChain(cron.Recover(logger)),
        cron.WithLogger(logger))

    // Add jobs
    c.AddFunc("@hourly", func() {
        log.Println("Hourly job")
    })

    c.AddFunc("0 9 * * 1-5", func() {
        log.Println("Weekday 9am")
    })

    // Run scheduler
    c.Start()
    defer c.Stop()

    // Keep running
    select {}
}
```

--------------------------------

### Implementing and Using a Custom Job

Source: https://github.com/yys190/cron/blob/master/_autodocs/types.md

Example of defining a custom Job type with a Run method and adding it to a cron scheduler. Ensure the Job type has a `Run()` method.

```go
type DatabaseBackup struct {
    Path string
}

func (j *DatabaseBackup) Run() {
    // Perform backup
}

c := cron.New()
c.AddJob("@daily", &DatabaseBackup{Path: "/data"})

```

--------------------------------

### Cron Error Handling Examples

Source: https://github.com/yys190/cron/blob/master/_autodocs/QUICK_REFERENCE.md

Illustrates different error handling scenarios in cron. It shows how parse errors are returned, how job panics can be recovered using a wrapper, and how to perform a graceful shutdown by waiting for running jobs to complete.

```go
// Parse errors are returned
id, err := c.AddFunc("invalid spec", func() {})
if err != nil {
    log.Printf("Failed to add job: %v", err)
}

// Job panics are recovered (if Recover() wrapper used)
c := cron.New(cron.WithChain(cron.Recover(logger)))
c.AddFunc("@hourly", func() {
    panic("Something went wrong!")  // Logged, not propagated
})

// Graceful shutdown
ctx := c.Stop()
<-ctx.Done()  // Wait for running jobs
```

--------------------------------

### Cron Schedule Examples

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

Common cron schedule expressions for various frequencies and specific times.

```cron
0 * * * *

```

```cron
0 0 * * *

```

```cron
0 0 * * 0

```

```cron
0 0 1 * *

```

```cron
30 9-17 * * *

```

```cron
0 9 * * 1-5

```

```cron
*/15 * * * *

```

```cron
0 0 * 1 *

```

```cron
0,30 * * * *

```

```cron
0 9,12,15,18 * * *

```

```cron
0 0 1-7 * MON

```

```cron
0 0 ? * 1

```

```cron
@every 30m

```

```cron
@hourly

```

```cron
@daily

```

--------------------------------

### Parse and Get Next Run Time

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/schedule.md

Example of parsing a standard cron expression and calculating the next run time. This is useful for scheduling jobs based on a crontab-like format.

```go
schedule, _ := cron.ParseStandard("30 * * * *")
now := time.Now()
nextRun := schedule.Next(now)
fmt.Printf("Next run: %s\n", nextRun)  // 30 minutes past the hour
```

--------------------------------

### Create and Use a Custom JobWrapper in Go

Source: https://github.com/yys190/cron/blob/master/_autodocs/types.md

Example of creating a custom `LogTime` JobWrapper that logs the execution duration of a job. It then shows how to chain this wrapper when creating a new cron instance.

```go
// Custom wrapper
func LogTime(logger Logger) cron.JobWrapper {
    return func(j cron.Job) cron.Job {
        return cron.FuncJob(func() {
            start := time.Now()
            j.Run()
            logger.Info("job took", "duration", time.Since(start))
        })
    }
}

c := cron.New(cron.WithChain(LogTime(logger)))
```

--------------------------------

### Add Fixed Schedule Jobs

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

Use predefined descriptors to add jobs that run at fixed times. Examples include @yearly, @monthly, @weekly, @daily, and @hourly.

```go
c.AddFunc("@yearly", func() {})    // January 1, midnight
c.AddFunc("@monthly", func() {})   // First of month, midnight
c.AddFunc("@weekly", func() {})    // Sunday, midnight
c.AddFunc("@daily", func() {})     // Every day, midnight
c.AddFunc("@hourly", func() {})    // Every hour
```

--------------------------------

### Asterisk (*) Examples

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

The asterisk (*) matches all possible values for a given field. Examples show its use for matching every minute, hour, day, or specific day of the week.

```text
* * * * *     Every minute
```

```text
0 * * * *     Every hour (at :00)
```

```text
0 0 * * *     Every day at midnight
```

```text
0 0 * * 0     Every Sunday at midnight
```

--------------------------------

### Create Parser with ParseOptions

Source: https://github.com/yys190/cron/blob/master/_autodocs/types.md

Example of creating a new cron parser with specific ParseOption flags. This configuration includes minute, hour, day of month, month, day of week, and descriptor options, but excludes seconds.

```go
// Standard parser without seconds
opts := cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow | cron.Descriptor
parser := cron.NewParser(opts)
```

--------------------------------

### Comma (,) Examples for Lists

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

The comma (,) is used to separate individual values within a field, creating a list of specific times or dates. Examples show lists for hours, days of the month, months, and days of the week.

```text
0 9,12,15 * * *      Run at 9am, noon, and 3pm
```

```text
0 * 1,15 * *         Run on the 1st and 15th of month
```

```text
0 * * JAN,APR,JUL *  Run in January, April, and July
```

```text
0 * * * MON,WED,FRI  Run on Monday, Wednesday, Friday
```

--------------------------------

### Configure Cron with Custom Loggers

Source: https://github.com/yys190/cron/blob/master/_autodocs/configuration.md

Use `WithLogger` to set a custom logger. Examples show verbose logging for development, error-only logging for production, and disabling logs.

```go
import (
    "log"
    "os"
    "github.com/robfig/cron/v3"
)

// Verbose logging for development
devLogger := cron.VerbosePrintfLogger(
    log.New(os.Stdout, "cron: ", log.LstdFlags))
c := cron.New(cron.WithLogger(devLogger))

// Error logging only for production
errLogger := cron.PrintfLogger(
    log.New(os.Stderr, "cron: ", log.LstdFlags))
c := cron.New(cron.WithLogger(errLogger))

// No logging
c := cron.New(cron.WithLogger(cron.DiscardLogger))
```

--------------------------------

### Configure Cron with Job Wrapper to Skip if Still Running

Source: https://github.com/yys190/cron/blob/master/doc.md

Installs a job wrapper for all jobs added to the cron instance. This specific wrapper prevents a new job run if the previous one has not yet completed.

```go
cron.New(cron.WithChain(
	cron.SkipIfStillRunning(logger),
))

```

--------------------------------

### Parse Cron with Descriptors

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/parser.md

Initialize the parser with the Descriptor option enabled to parse predefined schedules and intervals. Examples show parsing '@yearly', '@daily', '@hourly', and various '@every' durations.

```go
parser := cron.NewParser(cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow | cron.Descriptor)

// Predefined
s, _ := parser.Parse("@yearly")
s, _ := parser.Parse("@daily")
s, _ := parser.Parse("@hourly")

// Intervals
s, _ := parser.Parse("@every 30m")
s, _ := parser.Parse("@every 1h30m")
s, _ := parser.Parse("@every 2h")
```

--------------------------------

### Get All Cron Entries

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/cron.md

Returns a snapshot of all currently scheduled cron entries. This includes their IDs, schedules, and next/previous run times.

```go
c := cron.New()
c.AddFunc("@hourly", func() {})
c.AddFunc("@daily", func() {})
c.Start()

entries := c.Entries()
for _, entry := range entries {
    fmt.Printf("ID: %d, Next: %s, Prev: %s\n", entry.ID, entry.Next, entry.Prev)
}
```

--------------------------------

### Define Custom JobWrapper in Go

Source: https://github.com/yys190/cron/blob/master/_autodocs/types.md

Implement a custom JobWrapper to add behavior like logging execution time to jobs. This example shows how to create a wrapper that logs the duration of a job's execution.

```go
type JobWrapper func(Job) Job
```

--------------------------------

### Using DefaultLogger

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/logger.md

Demonstrates how to use the default logger, which logs to stdout with a 'cron: ' prefix and standard timestamp format. This is the logger used if none is explicitly provided.

```go
// DefaultLogger is automatically used
c := cron.New()

// Equivalent to explicitly setting:
c := cron.New(
    cron.WithLogger(cron.DefaultLogger))
```

--------------------------------

### Create a New Cron Scheduler

Source: https://github.com/yys190/cron/blob/master/doc.md

Instantiate a new Cron scheduler with optional configurations. Use options to customize behavior like logging, time zones, and job wrapping.

```go
c := cron.New()
c.AddFunc("* * * * ?", func() { fmt.Println("Every minute") })
c.Start()

// Example with options
c2 := cron.New(cron.WithSeconds(), cron.WithLocation(time.UTC))
c2.AddFunc("* * * * * *", func() { fmt.Println("Every second, UTC") })
c2.Start()
```

--------------------------------

### Hyphen (-) Examples for Ranges

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

The hyphen (-) defines an inclusive range for a field. Examples demonstrate its use for time ranges within a day, months, and days of the week.

```text
0 9-17 * * *     Every hour from 9am to 5pm (inclusive)
```

```text
0 * * JAN-MAR *  January through March
```

```text
0 * * * 1-5      Monday through Friday
```

```text
0 */5 * * *      Every 5 minutes (combined with slash below)
```

--------------------------------

### Cron Startup Log Event

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/logger.md

Logs when Cron.Start() or Cron.Run() is called.

```log
2024-01-15 10:30:45 start
```

--------------------------------

### Create Standard Parser

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/parser.md

Creates a standard parser including minute, hour, day of month, month, and day of week fields. Used for typical cron schedule parsing.

```go
// Standard parser without descriptors
parser := cron.NewParser(
    cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow)
schedule, err := parser.Parse("0 0 15 */3 *")
```

--------------------------------

### Location

Source: https://github.com/yys190/cron/blob/master/doc.md

Location gets the time zone location.

```APIDOC
## Location

### Description
Gets the time zone location that the Cron scheduler is configured to use.

### Signature
```go
func (c *Cron) Location() *time.Location
```

### Returns
- ***time.Location**: The time zone location.
```

--------------------------------

### Create a Cron Scheduler

Source: https://github.com/yys190/cron/blob/master/_autodocs/QUICK_REFERENCE.md

Instantiate a new cron scheduler. Options include setting a specific timezone, enabling the seconds field, using a custom parser, applying job decorators like recovery or skip-if-running, or enabling verbose logging.

```go
// Basic
c := cron.New()
```

```go
// With timezone
nyc, _ := time.LoadLocation("America/New_York")
c := cron.New(cron.WithLocation(nyc))
```

```go
// With seconds field
c := cron.New(cron.WithSeconds())
```

```go
// With custom parser
parser := cron.NewParser(cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow | cron.Descriptor)
c := cron.New(cron.WithParser(parser))
```

```go
// With job decorators
c := cron.New(cron.WithChain(
    cron.Recover(logger),
    cron.SkipIfStillRunning(logger),
))
```

```go
// With logging
c := cron.New(cron.WithLogger(cron.VerbosePrintfLogger(logger)))
```

--------------------------------

### Get Cron Scheduler's Time Location

Source: https://github.com/yys190/cron/blob/master/doc.md

Returns the time.Location associated with the cron scheduler.

```go
func (c *Cron) Location() *time.Location
```

--------------------------------

### Create a New Parser with Options

Source: https://github.com/yys190/cron/blob/master/doc.md

NewParser returns a Parser that uses the given ParseOptions.

```go
func NewParser(options ParseOption) Parser
```

--------------------------------

### Customize Cron Construction with Options

Source: https://github.com/yys190/cron/blob/master/_autodocs/types.md

Use functional options to customize Cron behavior during initialization. Options are applied in the order they are provided.

```go
c := cron.New(
    cron.WithLocation(time.UTC),
    cron.WithSeconds(),
    cron.WithLogger(logger),
)
```

--------------------------------

### Custom Cron Parser with WithParser

Source: https://github.com/yys190/cron/blob/master/_autodocs/configuration.md

Use WithParser to define a custom cron parser, for example, to include optional seconds.

```go
c := cron.New(cron.WithParser(cron.NewParser(
    cron.Second | cron.Minute | cron.Hour |
    cron.Dom | cron.Month | cron.Dow | cron.Descriptor)))

```

--------------------------------

### Create and Apply Job Chain using NewChain

Source: https://github.com/yys190/cron/blob/master/_autodocs/configuration.md

Utilize NewChain to create a reusable job wrapper chain for clarity and apply it using WithChain. This groups multiple behaviors like recovery and delay.

```go
// Using NewChain for clarity
chain := cron.NewChain(
    cron.Recover(logger),
    cron.DelayIfStillRunning(logger),
)
c := cron.New(cron.WithChain(chain...))
```

--------------------------------

### Invalid Cron Field Count

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

Cron expressions must have exactly 5 fields. This example shows an incorrect number of fields.

```cron
0 0 0 0 0           # Field count mismatch (5 fields required)
```

--------------------------------

### Invalid Cron Step and Range

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

Cron expressions do not allow a step of 0. Additionally, the start value in a range cannot be greater than the end value.

```cron
*/0 * * * *         # Step of 0 not allowed
```

```cron
5-2 * * * *         # Start > end (5-2)
```

--------------------------------

### Create Cron with Chain

Source: https://github.com/yys190/cron/blob/master/_autodocs/types.md

Construct a `Chain` with desired `JobWrapper`s and apply it globally to a new `Cron` instance using `cron.WithChain`. Wrappers are applied in reverse order of definition.

```go
chain := cron.NewChain(
    cron.Recover(logger),
    cron.SkipIfStillRunning(logger),
)
c := cron.New(cron.WithChain(chain...))
```

--------------------------------

### Run

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/cron.md

Runs the cron scheduler in the current goroutine (blocking), or does nothing if already running. This is an alternative to Start() when you want synchronous execution control.

```APIDOC
## Run()

### Description
Runs the cron scheduler in the current goroutine (blocking), or does nothing if already running. This is an alternative to `Start()` when you want synchronous execution control.

### Parameters
None

### Method
None (This is a method signature, not an HTTP endpoint)

### Endpoint
None (This is a method signature, not an HTTP endpoint)

### Returns
None

### Example
```go
c := cron.New()
c.AddFunc("@hourly", func() { fmt.Println("Every hour") })
// This blocks until Stop() is called
c.Run()
```
```

--------------------------------

### Invalid Cron Duration

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

The `@every` syntax requires a duration of at least 1 second. This example shows an invalid duration of 0 seconds.

```cron
@every 0s           # Duration must be >= 1 second
```

--------------------------------

### Cron Parsing Rules: Named Values

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

Examples demonstrating the use of named values for months and days of the week in cron expressions. These are case-insensitive.

```cron
0 0 1 JAN *

```

```cron
0 0 * JAN-MAR *

```

```cron
0 0 * * MON,WED,FRI

```

--------------------------------

### Create a New Cron Scheduler

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/cron.md

Instantiate a new Cron scheduler. Options can customize the timezone, cron spec parser, chaining behavior, and logger. Defaults to local time zone and a standard 5-field cron parser.

```go
c := cron.New()
```

```go
loc, _ := time.LoadLocation("America/New_York")
c := cron.New(cron.WithLocation(loc))
```

```go
c := cron.New(
    cron.WithSeconds(),
    cron.WithLogger(cron.VerbosePrintfLogger(logger)),
)
```

--------------------------------

### Parse Cron with List, Range, and Step Syntax

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/parser.md

Demonstrates parsing cron expressions that combine list, range, and step syntax for minutes, hours, and weekdays.

```go
parser := cron.NewParser(cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow)

// List: minutes 0, 15, 30, 45
parser.Parse("0,15,30,45 * * * *")

// Range: hours 9 to 17
parser.Parse("0 9-17 * * *")

// Step with range: every 15 minutes from minute 0
parser.Parse("0,15,30,45 * * * *")  // Or use step:
parser.Parse("*/15 * * * *")

// Combined: minute 0, hours 9-17, weekdays only
parser.Parse("0 9-17 * * 1-5")
```

--------------------------------

### Invalid Cron Day Name and Timezone

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

Cron expressions require valid day names and valid timezone identifiers. These examples show invalid inputs for both.

```cron
* * * * FUNDAY      # Invalid day name
```

```cron
CRON_TZ=Invalid/Tz 0 0 * * *  # Invalid timezone
```

--------------------------------

### Create Minimal Parser

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/parser.md

Creates a minimal parser accepting only day of month, month, and day of week. Useful for schedules that do not require minute or hour precision.

```go
// Minimal parser: only day, month, day-of-week
parser := cron.NewParser(cron.Dom | cron.Month | cron.Dow)
schedule, err := parser.Parse("15 */3 *")
```

--------------------------------

### Default Cron Configuration

Source: https://github.com/yys190/cron/blob/master/_autodocs/configuration.md

This snippet shows how to create a cron scheduler using all default settings. The defaults include the machine's local timezone, a standard 5-field cron spec parser with descriptors, no chain applied, and a default logger that outputs to stdout with errors only.

```go
c := cron.New()  // Uses all defaults above
```

--------------------------------

### Create Cron Parser with Custom Options

Source: https://github.com/yys190/cron/blob/master/doc.md

Use NewParser to create a Parser with specific options. It panics if multiple optional fields are provided.

```go
func NewParser(options ParseOption) Parser
```

```go
// Standard parser without descriptors
specParser := NewParser(Minute | Hour | Dom | Month | Dow)
sched, err := specParser.Parse("0 0 15 */3 *")
```

```go
// Same as above, just excludes time fields
subsParser := NewParser(Dom | Month | Dow)
sched, err := specParser.Parse("15 */3 *")
```

```go
// Same as above, just makes Dow optional
subsParser := NewParser(Dom | Month | DowOptional)
sched, err := subsParser.Parse("15 */3")
```

--------------------------------

### Invalid Cron Value Ranges

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

Each cron field has a specific valid range. These examples demonstrate values outside the allowed ranges for minutes, hours, days, and months.

```cron
60 * * * *          # Minute out of range (max 59)
```

```cron
* 24 * * *          # Hour out of range (max 23)
```

```cron
* * 32 * *          # Day of range (max 31)
```

```cron
* * * 13 *          # Month out of range (max 12)
```

```cron
* * * * 7           # Day of week out of range (max 6)
```

--------------------------------

### Get Cron Time Zone Location

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/cron.md

Retrieves the time zone location configured for the Cron instance. This is useful for verifying the scheduler's time zone settings.

```go
nyc, _ := time.LoadLocation("America/New_York")
c := cron.New(cron.WithLocation(nyc))
loc := c.Location()
fmt.Println(loc.String())  // Output: America/New_York
```

--------------------------------

### Run Cron Scheduler (Blocking)

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/cron.md

Runs the cron scheduler in the current goroutine, blocking execution. This is an alternative to `Start()` for synchronous control. The scheduler will continue running until `Stop()` is called.

```go
c := cron.New()
c.AddFunc("@hourly", func() { fmt.Println("Every hour") })
// This blocks until Stop() is called
c.Run()
```

--------------------------------

### Question Mark (?) Examples

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

The question mark (?) serves as an alternative to '*' for day-of-month and day-of-week fields, allowing one to be unspecified when the other is defined. It is useful for OR logic when both fields might otherwise have wildcards.

```text
0 0 15 * ?    Run on the 15th of every month at midnight
```

```text
0 0 ? * 0     Run every Sunday at midnight
```

```text
0 0 * * 1-5   Run every weekday at midnight
```

```text
0 0 ? * 1-5   Same as above (day-of-month unspecified)
```

--------------------------------

### Initialize Cron with Error Recovery

Source: https://github.com/yys190/cron/blob/master/_autodocs/00-START-HERE.md

Configure cron to recover from panics during job execution using a provided logger.

```go
c := cron.New(cron.WithChain(cron.Recover(logger)))
```

--------------------------------

### Create New Cron Instance

Source: https://github.com/yys190/cron/blob/master/doc.md

Returns a new Cron job runner. Options can be provided to customize time zone, parser, and job wrapping behavior.

```go
func New(opts ...Option) *Cron
```

--------------------------------

### Create a Cron Scheduler with a Custom Logger

Source: https://github.com/yys190/cron/blob/master/doc.md

WithLogger returns a cron.Option that sets the Logger for the cron scheduler.

```go
func WithLogger(logger Logger) Option
```

--------------------------------

### Compose Job Wrappers with Chain Globally

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/chain.md

Create a cron instance with a chain of wrappers applied globally. This chain includes panic recovery, skipping overlapping runs, and logging. Use this when you want consistent behavior for all jobs added to the cron instance.

```go
import (
    "github.com/robfig/cron/v3"
    "log"
    "os"
)

logger := cron.VerbosePrintfLogger(
    log.New(os.Stdout, "cron: ", log.LstdFlags))

// Chain that recovers from panics, skips overlapping runs, and logs everything
c := cron.New(cron.WithChain(
    cron.Recover(logger),
    cron.SkipIfStillRunning(logger),
))

// Add a potentially long-running job
c.AddFunc("@every 10m", func() {
    // If this takes longer than 10 minutes, the next run will be skipped
    // If it panics, the panic is recovered and logged
    performExpensiveOperation()
})

c.Start()
defer c.Stop().Done()
```

--------------------------------

### Get Specific Cron Entry by ID

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/cron.md

Retrieves a snapshot of a specific cron entry using its ID. Returns a zero Entry if the ID is not found. The `Valid()` method can be used to check if the entry exists.

```go
c := cron.New()
id, _ := c.AddFunc("@hourly", func() {})
c.Start()

entry := c.Entry(id)
if entry.Valid() {
    fmt.Printf("Next run: %s\n", entry.Next)
}
```

--------------------------------

### Import Cron V3 in Go

Source: https://github.com/yys190/cron/blob/master/README.md

Import the Cron V3 library into your Go program using the provided import path.

```go
import "github.com/robfig/cron/v3"
```

--------------------------------

### Control Cron Scheduler

Source: https://github.com/yys190/cron/blob/master/_autodocs/QUICK_REFERENCE.md

Manage the lifecycle of the cron scheduler. Start it in the background, run it in a blocking manner, or stop it gracefully, waiting for ongoing jobs to complete. Includes methods for inspecting and removing scheduled entries.

```go
// Start in background
c.Start()
```

```go
// Or run blocking
c.Run()
```

```go
// Stop gracefully
ctx := c.Stop()
<-ctx.Done()  // Wait for jobs to complete
```

```go
// Inspect entries
entries := c.Entries()
entry := c.Entry(jobID)
```

```go
// Remove a job
c.Remove(jobID)
```

--------------------------------

### Apply Job Wrappers to a Single Job

Source: https://github.com/yys190/cron/blob/master/_autodocs/configuration.md

Decorate an individual job with a chain of wrappers using NewChain and Then, rather than applying them globally to all jobs. This allows for specific behavior on a per-job basis.

```go
c := cron.New()

job := &MyJob{}
decorated := cron.NewChain(
    cron.Recover(logger),
    cron.SkipIfStillRunning(logger),
).Then(job)

c.Schedule(schedule, decorated)
```

--------------------------------

### Advanced Cron Parsing Options

Source: https://github.com/yys190/cron/blob/master/_autodocs/README.md

Demonstrates enabling the seconds field for Quartz-like cron expressions and creating a custom parser that supports optional seconds and descriptors.

```go
// Enable seconds field (Quartz format)
c := cron.New(cron.WithSeconds())
c.AddFunc("*/5 * * * * *", func() {})  // Every 5 seconds

// Custom parser with optional seconds
parser := cron.NewParser(
    cron.SecondOptional | cron.Minute | cron.Hour |
    cron.Dom | cron.Month | cron.Dow | cron.Descriptor)
c := cron.New(cron.WithParser(parser))
```

--------------------------------

### Create a Cron Scheduler with a Job Chain

Source: https://github.com/yys190/cron/blob/master/doc.md

WithChain returns a cron.Option that sets a chain of JobWrappers for the cron scheduler.

```go
func WithChain(wrappers ...JobWrapper) Option
```

--------------------------------

### Add Cron Job with Specific Time Zone (Tokyo) using SetLocation

Source: https://github.com/yys190/cron/blob/master/doc.md

Schedules a job to run at 6 AM in Asia/Tokyo. This example first sets the cron instance's location to America/New_York, then uses the CRON_TZ prefix to override it for the specific job.

```go
# Runs at 6am in Asia/Tokyo
c := cron.New(cron.WithLocation(nyc))
c.SetLocation("America/New_York")
c.AddFunc("CRON_TZ=Asia/Tokyo 0 6 * * ?", ...)

```

--------------------------------

### Create a Cron Scheduler with a Custom Parser

Source: https://github.com/yys190/cron/blob/master/doc.md

WithParser returns a cron.Option that sets the ScheduleParser for the cron scheduler.

```go
func WithParser(p ScheduleParser) Option
```

--------------------------------

### Minimal Logger for Production

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/logger.md

For production environments, use `PrintfLogger` with a standard Go logger directed to `os.Stderr` for minimal logging, typically only showing errors. This reduces log verbosity.

```go
import (
    "log"
    "os"
    "github.com/robfig/cron/v3"
)

logger := log.New(os.Stderr, "cron: ", log.LstdFlags)
c := cron.New(cron.WithLogger(cron.PrintfLogger(logger)))
```

--------------------------------

### Create a Custom Cron Parser

Source: https://github.com/yys190/cron/blob/master/_autodocs/types.md

Instantiate a Parser with specific options to control which cron fields are supported. This parser can then be used to parse cron specifications.

```go
parser := cron.NewParser(
    cron.SecondOptional | cron.Minute | cron.Hour |
    cron.Dom | cron.Month | cron.Dow | cron.Descriptor)
schedule, _ := parser.Parse("@hourly")
```

--------------------------------

### NewParser Constructor

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/parser.md

Creates a Parser with custom options. Panics if more than one optional field is configured.

```APIDOC
## NewParser(options ParseOption) Parser

Creates a Parser with custom options. Panics if more than one optional field is configured.

### Parameters
- **options** (`ParseOption`) - Required - Bitwise combination of ParseOption constants specifying which fields to accept.

### Returns
- `Parser` - A new parser configured with the given options.

### Panics
- If both `SecondOptional` and `DowOptional` are specified. Only one optional field is allowed.

### Examples:

```go
// Standard parser without descriptors
parser := cron.NewParser(
    cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow)
schedule, err := parser.Parse("0 0 15 */3 *")

// Parser with seconds (required)
parser := cron.NewParser(
    cron.Second | cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow)
schedule, err := parser.Parse("0 0 0 15 */3 *")

// Parser with seconds (optional)
parser := cron.NewParser(
    cron.SecondOptional | cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow)
schedule, err := parser.Parse("0 0 15 */3 *")      // Omit seconds
schedule, err := parser.Parse("0 0 0 15 */3 *")    // Include seconds

// Minimal parser: only day, month, day-of-week
parser := cron.NewParser(cron.Dom | cron.Month | cron.Dow)
schedule, err := parser.Parse("15 */3 *")
```
```

--------------------------------

### Cron Initial Schedule Calculation Log Event

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/logger.md

Logged for each entry at scheduler startup, showing the current time and the next scheduled run time. Includes 'now', 'entry', and 'next' details.

```log
2024-01-15 10:30:45 schedule now=2024-01-15T10:30:45Z entry=1 next=2024-01-15T10:31:00Z
```

--------------------------------

### Run

Source: https://github.com/yys190/cron/blob/master/doc.md

Run the cron scheduler, or no-op if already running.

```APIDOC
## Run

### Description
Manually triggers the execution of the cron scheduler. If the scheduler is already running, this operation has no effect.

### Signature
```go
func (c *Cron) Run()
```
```

--------------------------------

### Calculate Next Run Time

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/schedule.md

The `Next` method calculates the next activation time for a `ConstantDelaySchedule` based on a given reference time. The result is rounded to the nearest second boundary.

```go
schedule := cron.Every(5 * time.Minute)
now := time.Now()
nextRun := schedule.Next(now)
// nextRun is at least 5 minutes from now, rounded to the second
```

--------------------------------

### Create a Job from a Function

Source: https://github.com/yys190/cron/blob/master/doc.md

FuncJob is an adapter to allow the use of ordinary functions as Job.

```go
func (f FuncJob) Run()
```

--------------------------------

### Configure Cron with Panic Recovery

Source: https://github.com/yys190/cron/blob/master/README.md

To opt into panic recovery for jobs and configure the panic logger, use the WithChain option with cron.Recover. This ensures that panics within jobs are caught and logged.

```go
cron.New(cron.WithChain(
  cron.Recover(logger),  // or use cron.DefaultLogger
))

```

--------------------------------

### Calculate the Next Scheduled Time

Source: https://github.com/yys190/cron/blob/master/doc.md

Next returns the next activation time after the given time.

```go
func (schedule ConstantDelaySchedule) Next(t time.Time) time.Time
```

```go
func (s *SpecSchedule) Next(t time.Time) time.Time
```

--------------------------------

### Parse Cron Expressions

Source: https://github.com/yys190/cron/blob/master/_autodocs/QUICK_REFERENCE.md

Demonstrates parsing cron expressions using standard 5-field format, a custom parser including seconds and descriptors, and a minimal parser.

```go
// Standard 5-field (default)
schedule, _ := cron.ParseStandard("0 * * * *")
```

```go
// Custom parser with seconds
parser := cron.NewParser(
    cron.SecondOptional | cron.Minute | cron.Hour |
    cron.Dom | cron.Month | cron.Dow | cron.Descriptor)
schedule, _ := parser.Parse("0 0 * * *")     // Optional seconds omitted
schedule, _ := parser.Parse("0 0 0 * * *")   // Optional seconds included
```

```go
// Minimal parser
parser := cron.NewParser(cron.Dom | cron.Month | cron.Dow)
schedule, _ := parser.Parse("15 */3 *")
```

--------------------------------

### Create Cron with Seconds Field (Optional)

Source: https://github.com/yys190/cron/blob/master/README.md

Construct a new Cron instance that includes an optional seconds field, retaining the behavior of older versions.

```go
cron.New(cron.WithSeconds())
```

--------------------------------

### Apply Single Job Wrapper with Recover

Source: https://github.com/yys190/cron/blob/master/_autodocs/configuration.md

Use WithChain to apply a single JobWrapper, such as Recover, to all jobs. This provides panic recovery for all scheduled tasks.

```go
// Single wrapper
c := cron.New(cron.WithChain(
    cron.Recover(logger),
))
```

--------------------------------

### Cron Day-of-Month and Day-of-Week Logic (AND)

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

Illustrates AND logic where both Day-of-Month and Day-of-Week fields must match specific values for the job to run.

```cron
0 0 15 * 0

```

--------------------------------

### Decorate a Job with a Chain of Wrappers

Source: https://github.com/yys190/cron/blob/master/doc.md

Then decorates the given job with all JobWrappers in the chain. This is equivalent to m1(m2(m3(job))) for a chain m1, m2, m3.

```go
func (c Chain) Then(j Job) Job
```

--------------------------------

### New

Source: https://github.com/yys190/cron/blob/master/doc.md

New returns a new Cron job runner, modified by the given options. Available options include Time Zone, Parser, and Chain.

```APIDOC
## New

### Description
Returns a new Cron job runner, modified by the given options.

### Signature
```go
func New(opts ...Option) *Cron
```

### Options
- **Time Zone**: The time zone in which schedules are interpreted. Defaults to `time.Local`.
- **Parser**: Converts cron spec strings into cron schedules. Defaults to accepting standard cron specs.
- **Chain**: Wraps submitted jobs to customize behavior. Defaults to a chain that recovers panics and logs them to stderr.
```

--------------------------------

### WithChain

Source: https://github.com/yys190/cron/blob/master/doc.md

Specifies Job wrappers to apply to all jobs added to this cron.

```APIDOC
## func WithChain(wrappers ...JobWrapper) Option

### Description
Specifies a list of Job wrappers to be applied to all jobs managed by the cron instance.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Add Interval Jobs

Source: https://github.com/yys190/cron/blob/master/_autodocs/spec-format.md

Use the @every descriptor with a duration to schedule jobs that run at fixed intervals. The duration format follows Go's time.ParseDuration syntax (e.g., 30m, 1h30m). Intervals less than 1 second are rounded up to 1 second.

```go
c.AddFunc("@every 30m", func() {})      // Every 30 minutes
c.AddFunc("@every 1h30m", func() {})    // Every 1.5 hours
c.AddFunc("@every 2h", func() {})       // Every 2 hours
```

--------------------------------

### Manage Cron Job with EntryID

Source: https://github.com/yys190/cron/blob/master/_autodocs/types.md

Demonstrates adding a job, retrieving its EntryID, and then using that ID to access the entry details or remove the job. This is useful for dynamic job management.

```go
c := cron.New()
id, _ := c.AddFunc("@hourly", func() {})
entry := c.Entry(id)  // Later retrieval
c.Remove(id)           // Later removal
```

--------------------------------

### Create ConstantDelaySchedule with Every

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/schedule.md

Use the `Every` constructor to create a schedule that runs at a fixed interval. Durations less than one second are rounded up to one second, and fractional seconds are truncated. This snippet also shows how to use the schedule with a new cron instance.

```go
schedule := cron.Every(5 * time.Minute)

// Every hour
schedule := cron.Every(1 * time.Hour)

// Less than 1 second gets rounded up
schedule := cron.Every(100 * time.Millisecond)  // Becomes 1 second

c := cron.New()
id := c.Schedule(schedule, myJob)
c.Start()
```

--------------------------------

### Initialize Cron with Specific Timezone

Source: https://github.com/yys190/cron/blob/master/_autodocs/00-START-HERE.md

Initialize a cron instance with a specific timezone to ensure jobs run according to that location's time.

```go
loc, _ := time.LoadLocation("America/New_York")
c := cron.New(cron.WithLocation(loc))
```

--------------------------------

### Add FuncJob to Cron

Source: https://github.com/yys190/cron/blob/master/_autodocs/types.md

Demonstrates automatic wrapping of a function literal as a job using AddFunc, and manual wrapping of a custom function into a job.

```go
// Automatic wrapping via AddFunc
c.AddFunc("@hourly", func() {
    fmt.Println("Running")
})

// Manual wrapping if needed
job := cron.FuncJob(func() { fmt.Println("Custom") })
c.Schedule(schedule, job)
```

--------------------------------

### Create a Chain of JobWrappers

Source: https://github.com/yys190/cron/blob/master/_autodocs/api-reference/chain.md

Construct a Chain by providing multiple JobWrapper functions. This chain can then be used with the cron scheduler to apply multiple behaviors to jobs.

```go
// Create a chain that recovers from panics and skips if still running
chain := cron.NewChain(
    cron.Recover(logger),
    cron.SkipIfStillRunning(logger),
)

// Use with Cron
c := cron.New(cron.WithChain(chain...))

```

--------------------------------

### Cron Configuration Options

Source: https://github.com/yys190/cron/blob/master/_autodocs/QUICK_REFERENCE.md

Customize cron behavior using options such as setting the timezone, enabling the seconds field, providing a custom parser, chaining job decorators, or specifying a custom logger.

```go
// Set timezone
WithLocation(time.UTC)
```

```go
// Enable seconds field
WithSeconds()
```

```go
// Custom parser
WithParser(parser)
```

```go
// Job decorators
WithChain(Recover(logger))
```

```go
// Custom logger
WithLogger(VerbosePrintfLogger(logger))
```

--------------------------------

### Manually Run All Pending Jobs

Source: https://github.com/yys190/cron/blob/master/doc.md

Runs all jobs that are ready to run based on their schedule.

```go
func (c *Cron) Run()
```

--------------------------------

### Create a Chain of Job Wrappers

Source: https://github.com/yys190/cron/blob/master/doc.md

NewChain returns a Chain consisting of the given JobWrappers.

```go
func NewChain(c ...JobWrapper) Chain
```
Tokens:
Raw