https://github.com/c-cube/calculon

Library for writing IRC bots in OCaml, a collection of plugins, and a dramatic robotic actor.
https://github.com/c-cube/calculon

futurama irc irc-bot lwt ocaml pluggable

Last synced: 2 months ago
JSON representation

Library for writing IRC bots in OCaml, a collection of plugins, and a dramatic robotic actor.

• Host: GitHub
• URL: https://github.com/c-cube/calculon
• Owner: c-cube
• License: mit
• Created: 2017-01-20T19:03:15.000Z (almost 8 years ago)
• Default Branch: main
• Last Pushed: 2024-01-20T03:08:41.000Z (12 months ago)
• Last Synced: 2024-10-13T01:46:09.392Z (3 months ago)
• Topics: futurama, irc, irc-bot, lwt, ocaml, pluggable
• Language: OCaml
• Homepage: https://c-cube.github.io/calculon/
• Size: 1.26 MB
• Stars: 28
• Watchers: 6
• Forks: 5
• Open Issues: 8
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        

# Calculon [![build](https://github.com/c-cube/calculon/actions/workflows/main.yml/badge.svg)](https://github.com/c-cube/calculon/actions/workflows/main.yml)

Library for writing IRC bots in OCaml, a collection of plugins, and a dramatic robotic actor.

The core library is called `calculon`.

![calculon logo](https://raw.github.com/c-cube/calculon/master/media/calculon.jpg)

## Build

```

make build

```

## Introduction to the Code

Let's assume calculon is loaded, via:

```ocaml

# #require "calculon";;

```

### Main

The typical `main` entry point would look like  this.

Calculon works by gathering a list of

*plugins* (see the module `Plugin`), some configuration (see `Config`)

and running the package in a loop using [irc-client](https://github.com/johnelse/ocaml-irc-client/).

```ocaml non-deterministic=command

module C = Calculon

let plugins : C.Plugin.t list = [

  C.Plugin_social.plugin;

  C.Plugin_factoids.plugin;

  (* etc. *)

]

let () =

  let conf = C.Config.of_argv () in

  C.Run_main.main conf plugins |> Lwt_main.run

```

### Plugins

A plugin contains a set of *commands*.

A command is is a rule that matches a IRC message with some regex, and decides

whether or not to fire with a reply. They are defined in the module `Command`.

For instance, the following module will reply to messages

starting with `!hello` by replying `"hello "`. This is a simple

command, as the function `Command.make_simple` indicates: it returns a `string

option` to indicate whether or not to respond to any line starting with

`!prefix`. More elaborate commands are possible using `Command.make`.

```ocaml

open Calculon

let cmd_hello : Command.t =

  Command.make_simple ~descr:"hello world" ~cmd:"hello" ~prio:10

    (fun (input_msg:Core.privmsg) _ ->

       let who = input_msg.Core.nick in

       Lwt.return (Some ("hello " ^ who))

    )

let plugin_hello : Plugin.t = Plugin.of_cmd cmd_hello

```

Basic plugins are stateless, built from one or more commands with `Plugin.of_cmd`

and `Plugin.of_cmds`.

Other plugins can be stateful (typically, they can have some persistent

state, or more "custom" schemes).

The constructor `Plugin.stateful` is used to make such plugins.

All the persistent state is stored in a single json file.

See for instance the existing plugins `Plugin_factoids` and `Plugin_movie`

to see how to use `Plugin.stateful`.