github.com/diamondburned/arikawa@v1.3.14/README.md (about)

     1  # arikawa
     2  
     3  [![Pipeline status](https://gitlab.com/diamondburned/arikawa/badges/master/pipeline.svg?style=flat-square)](https://gitlab.com/diamondburned/arikawa/pipelines              )
     4  [![       Coverage](https://gitlab.com/diamondburned/arikawa/badges/master/coverage.svg?style=flat-square)](https://gitlab.com/diamondburned/arikawa/commits/master         )
     5  [![    Report Card](https://goreportcard.com/badge/github.com/diamondburned/arikawa?style=flat-square    )](https://goreportcard.com/report/github.com/diamondburned/arikawa)
     6  [![Godoc Reference](https://img.shields.io/badge/godoc-reference-blue?style=flat-square                  )](https://pkg.go.dev/github.com/diamondburned/arikawa              )
     7  [![       Examples](https://img.shields.io/badge/Example-__example%2F-blueviolet?style=flat-square       )](https://github.com/diamondburned/arikawa/tree/master/_example   )
     8  [![Discord Gophers](https://img.shields.io/badge/Discord%20Gophers-%23arikawa-%237289da?style=flat-square)](https://discord.gg/7jSf85J                                      )
     9  [![   Hime Arikawa](https://img.shields.io/badge/Hime-Arikawa-ea75a2?style=flat-square                   )](https://hime-goto.fandom.com/wiki/Hime_Arikawa                  )
    10  
    11  A Golang library for the Discord API.
    12  
    13  ## Examples
    14  
    15  ### [Simple](https://github.com/diamondburned/arikawa/tree/master/_example/simple)
    16  
    17  Simple bot example without any state. All it does is logging messages sent into
    18  the console. Run with `BOT_TOKEN="TOKEN" go run .`.
    19  
    20  ### [Undeleter](https://github.com/diamondburned/arikawa/tree/master/_example/undeleter)
    21  
    22  A slightly more complicated example. This bot uses a local state to cache
    23  everything, including messages. It detects when someone deletes a message,
    24  logging the content into the console.
    25  
    26  This example demonstrates the PreHandler feature of this library. PreHandler
    27  calls all handlers that are registered (separately from the session), calling 
    28  them before the state is updated.
    29  
    30  ### [Advanced Bot](https://github.com/diamondburned/arikawa/tree/master/_example/advanced_bot)
    31  
    32  A pretty complicated example demonstrating the reflect-based command router
    33  that's built-in. The router turns exported struct methods into commands, its
    34  arguments into command arguments, and more.
    35  
    36  The library has a pretty detailed documentation available in [GoDoc
    37  Reference](https://pkg.go.dev/github.com/diamondburned/arikawa/bot).
    38  
    39  ## Comparison: Why not discordgo?
    40  
    41  Discordgo is great. It's the first library that I used when I was learning Go.
    42  Though there are some things that I disagree on. Here are some ways that this
    43  library is different:
    44  
    45  - Better package structure: this library divides the Discord library up into
    46  smaller packages.
    47  - Cleaner API/Gateway structure separation: this library separates fields that
    48  would only appear in Gateway events, so to not cause confusion.
    49  - Automatic un-pagination: this library automatically un-paginates endpoints
    50  that would otherwise not return everything fully.
    51  - Flexible underlying abstractions: this library allows plugging in different
    52  JSON and Websocket implementations, as well as direct access to the HTTP 
    53  client.
    54  - Flexible API abstractions: because packages are separated, the developer could
    55  choose to use a lower level package (such as `gateway`) or a higher level
    56  package (such as `state`).
    57  - Pre-handlers in the state: this allows the developers to access items from the
    58  state storage before they're removed.
    59  - Pluggable state storages: although only having a default state storage in the
    60  library, it is abstracted with an interface, making it possible to implement a
    61  custom remote or local state storage.
    62  - REST-updated state: this library will call the REST API if it can't find
    63  things in the state, which is useful for keeping it updated.
    64  - No code generation: just so the library is a lot easier to maintain.
    65  
    66  ## Testing
    67  
    68  The package includes integration tests that require `$BOT_TOKEN`. To run these
    69  tests, do:
    70  
    71  ```sh
    72  export BOT_TOKEN="<BOT_TOKEN>"
    73  go test -tags integration ./...
    74  ```