github.com/diamondburned/arikawa/v2@v2.1.0/README.md (about)

     1  # arikawa
     2  
     3  [![ Pipeline Status ][pipeline_img    ]][pipeline    ]
     4  [![ Coverage        ][coverage_img    ]][pipeline    ]
     5  [![ Report Card     ][goreportcard_img]][goreportcard]
     6  [![ Godoc Reference ][pkg.go.dev_img  ]][pkg.go.dev  ]
     7  [![ Examples        ][examples_img    ]][examples    ]
     8  [![ Discord Gophers ][dgophers_img    ]][dgophers    ]
     9  [![ Hime Arikawa    ][himeArikawa_img ]][himeArikawa ]
    10  
    11  A Golang library for the Discord API.
    12  
    13  [dgophers]:     https://discord.gg/7jSf85J
    14  [dgophers_img]: https://img.shields.io/badge/Discord%20Gophers-%23arikawa-%237289da?style=flat-square
    15  
    16  [examples]:     https://github.com/diamondburned/arikawa/tree/v2/_example
    17  [examples_img]: https://img.shields.io/badge/Example-__example%2F-blueviolet?style=flat-square
    18  
    19  [pipeline]:     https://gitlab.com/diamondburned/arikawa/pipelines
    20  [pipeline_img]: https://gitlab.com/diamondburned/arikawa/badges/v2/pipeline.svg?style=flat-square
    21  [coverage_img]: https://gitlab.com/diamondburned/arikawa/badges/v2/coverage.svg?style=flat-square
    22  
    23  [pkg.go.dev]:     https://pkg.go.dev/github.com/diamondburned/arikawa/v2
    24  [pkg.go.dev_img]: https://pkg.go.dev/badge/github.com/diamondburned/arikawa/v2
    25  
    26  [himeArikawa]:     https://hime-goto.fandom.com/wiki/Hime_Arikawa
    27  [himeArikawa_img]: https://img.shields.io/badge/Hime-Arikawa-ea75a2?style=flat-square
    28  
    29  [goreportcard]:     https://goreportcard.com/report/github.com/diamondburned/arikawa
    30  [goreportcard_img]: https://goreportcard.com/badge/github.com/diamondburned/arikawa?style=flat-square
    31  
    32  
    33  ## Examples
    34  
    35  ### [Simple](https://github.com/diamondburned/arikawa/tree/v2/_example/simple)
    36  
    37  Simple bot example without any state. All it does is logging messages sent into
    38  the console. Run with `BOT_TOKEN="TOKEN" go run .`. This example only
    39  demonstrates the most simple needs; in most cases, bots should use the state or
    40  the bot router.
    41  
    42  ### [Undeleter](https://github.com/diamondburned/arikawa/tree/v2/_example/undeleter)
    43  
    44  A slightly more complicated example. This bot uses a local state to cache
    45  everything, including messages. It detects when someone deletes a message,
    46  logging the content into the console.
    47  
    48  This example demonstrates the PreHandler feature of the state library.
    49  PreHandler calls all handlers that are registered (separately from the session),
    50  calling them before the state is updated.
    51  
    52  ### Bare Minimum Bot
    53  
    54  The least amount of code for a basic ping-pong bot. It's similar to Serenity's
    55  Discord bot example in the README.
    56  
    57  ```go
    58  package main
    59  
    60  import (
    61  	"os"
    62  
    63  	"github.com/diamondburned/arikawa/v2/bot"
    64  	"github.com/diamondburned/arikawa/v2/gateway"
    65  )
    66  
    67  func main() {
    68  	bot.Run(os.Getenv("DISCORD_TOKEN"), &Bot{},
    69  		func(ctx *bot.Context) error {
    70  			ctx.HasPrefix = bot.NewPrefix("!")
    71  		},
    72  	)
    73  }
    74  
    75  type Bot struct {
    76  	Ctx *bot.Context
    77  }
    78  
    79  func (b *Bot) Ping(*gateway.MessageCreateEvent) (string, error) {
    80  	return "Pong!", nil
    81  }
    82  ```
    83  
    84  ### [Advanced Bot](https://github.com/diamondburned/arikawa/tree/v2/_example/advanced_bot)
    85  
    86  A complex example demonstrating the reflect-based command router that's
    87  built-in. The router turns exported struct methods into commands, its arguments
    88  into command arguments, and more.
    89  
    90  The library is documented in details in the [package
    91  documentation](https://pkg.go.dev/github.com/diamondburned/arikawa/bot).
    92  
    93  
    94  ## Comparison: Why not discordgo?
    95  
    96  Discordgo is great. It's the first library that I used when I was learning Go.
    97  Though there are some things that I disagree on. Here are some ways that this
    98  library is different:
    99  
   100  - Better package structure: this library divides the Discord library up into
   101  smaller packages.
   102  - Cleaner API/Gateway structure separation: this library separates fields that
   103  would only appear in Gateway events, so to not cause confusion.
   104  - Automatic un-pagination: this library automatically un-paginates endpoints
   105  that would otherwise not return everything fully.
   106  - Flexible underlying abstractions: this library allows plugging in different
   107  JSON and Websocket implementations, as well as direct access to the HTTP 
   108  client.
   109  - Flexible API abstractions: because packages are separated, the developer could
   110  choose to use a lower level package (such as `gateway`) or a higher level
   111  package (such as `state`).
   112  - Pre-handlers in the state: this allows the developers to access items from the
   113  state storage before they're removed.
   114  - Pluggable state storages: although only having a default state storage in the
   115  library, it is abstracted with an interface, making it possible to implement a
   116  custom remote or local state storage.
   117  - REST-updated state: this library will call the REST API if it can't find
   118  things in the state, which is useful for keeping it updated.
   119  - No code generation: just so the library is a lot easier to maintain.
   120  
   121  
   122  ## Testing
   123  
   124  The package includes integration tests that require `$BOT_TOKEN`. To run these
   125  tests, do:
   126  
   127  ```sh
   128  export BOT_TOKEN="<BOT_TOKEN>"
   129  go test -tags integration -race ./...
   130  ```