irc - GitLite

KO | EN

gitlite — search

#agents #nextjs #electron #shell #macos #database #ai #css #redis #windows

irc

(★ 577)

the irc crate – usable, async IRC for Rust

File Explorer

ZIP Download

- - ci.yml
- build-bot.rs
- convertconf.rs
- multiserver.rs
- repeater.rs
- simple.rs
- simple_plaintext.rs
- simple_proxy.rs
- tooter.rs
- tweeter.rs
- - caps.rs
  - chan.rs
  - colors.rs
  - command.rs
  - error.rs
  - irc.rs
  - lib.rs
  - line.rs
  - message.rs
  - mode.rs
  - prefix.rs
  - response.rs
- Cargo.toml
- - conn.rs
  - mock.rs
  - mod.rs
  - prelude.rs
  - transport.rs
- error.rs
- lib.rs
.gitignore
.travis.yml
Cargo.toml
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE.md
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`cargo add`

View Details ▼

Add dependencies to a Rust project's `Cargo.toml` manifest.

cargo add {{dependency}}

Add the latest version of a dependency to the current project:

cargo add {{dependency}}@{{version}}

Add a specific version of a dependency:

cargo add {{dependency}} {{[-F|--features]}} {{feature_1,feature_2,...}}

Add a dependency and enable one or more specific features:

🔍

`time`

View Details ▼

Measure how long a command took to run.
Note: `time` can either exist as a shell builtin, a standalone program, or both.
See also: `times`.

time {{command}}

Run the `command` and print the time measurements to `stdout`:

time

Display the current system time and prompt to enter a new time (leave empty to keep unchanged):

time read

Create a very simple stopwatch (only works in Bash):

🔍

`net`

View Details ▼

System utility to view and modify network-related settings.

net {{start|stop}} {{service}}

Start or stop a Windows service synchronously:

net use {{\\smb_shared_folder}} /USER:{{username}}

Make sure an SMB share is available in the current console:

net share

Show the folders currently shared over SMB:

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[ci-badge]: https://github.com/aatxe/irc/actions/workflows/ci.yml/badge.svg
[ci]: https://github.com/aatxe/irc/actions/workflows/ci.yml
[cr-badge]: https://img.shields.io/crates/v/irc.svg
[cr]: https://crates.io/crates/irc
[dl-badge]: https://img.shields.io/crates/d/irc.svg
[doc-badge]: https://docs.rs/irc/badge.svg
[doc]: https://docs.rs/irc

[rfc2812]: http://datatracker.ietf.org/doc/html/rfc2812
[ircv3.1]: http://ircv3.net/irc/3.1.html
[ircv3.2]: http://ircv3.net/irc/3.2.html

"the irc crate" is a thread-safe and async-friendly IRC client library written in Rust. It's
compliant with [RFC 2812][rfc2812], [IRCv3.1][ircv3.1], [IRCv3.2][ircv3.2], and includes some
additional, common features from popular IRCds. You can find up-to-date, ready-to-use documentation
online [on docs.rs][doc].

## Built with the irc crate

the irc crate is being used to build new IRC software in Rust. Here are some of our favorite
projects:

- [alectro][alectro] — a terminal IRC client
- [spilo][spilo] — a minimalistic IRC bouncer
- [irc-bot.rs][ircbot] — a library for writing IRC bots
- [playbot_ng][playbot_ng] — a Rust-evaluating IRC bot in Rust
- [bunnybutt-rs][bunnybutt] — an IRC bot for the [Feed The Beast Wiki][ftb-wiki]
- [url-bot-rs][url-bot-rs] — a URL-fetching IRC bot

[alectro]: https://github.com/aatxe/alectro
[spilo]: https://github.com/aatxe/spilo
[ircbot]: https://github.com/8573/irc-bot.rs
[bunnybutt]: https://github.com/FTB-Gamepedia/bunnybutt-rs
[playbot_ng]: https://github.com/panicbit/playbot_ng
[ftb-wiki]: https://ftb.gamepedia.com/FTB_Wiki
[url-bot-rs]: https://github.com/nuxeh/url-bot-rs

Making your own project? [Submit a pull request](https://github.com/aatxe/irc/pulls) to add it!

## Getting Started

To start using the irc crate with cargo, you can add `irc = "1.0.0"` to your dependencies in or you can use the comman `cargo add irc`.
your Cargo.toml file. The high-level API can be found in [`irc::client::prelude`][irc-prelude].
You'll find a number of examples to help you get started in `examples/`, throughout the
documentation, and below.

[irc-prelude]: https://docs.rs/irc/*/irc/client/prelude/index.html

## Using Futures

The release of v0.14 replaced all existing APIs with one based on async/await.

```rust,no_run,edition2021
use futures::prelude::*;
use irc::client::prelude::*;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    // We can also load the Config at runtime via Config::load("path/to/config.toml")
    let config = Config {
        nickname: Some("the-irc-crate".to_owned()),
        server: Some("chat.freenode.net".to_owned()),
        channels: vec!["#test".to_owned()],
        ..Config::default()
    };
    let mut client = Client::from_config(config).await?;
    client.identify()?;

let mut stream = client.stream()?;

while let Some(message) = stream.next().await.transpose()? {
        print!("{}", message);
    }

Ok(())
}
```

Example Cargo.toml file:
```rust,no_run,edition2021
[package]
name = "example"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
anyhow = "1.0"
futures = "0.3"
irc = "1.0.0"
tokio = { version = "1.0", features = [
    "rt",
    "rt-multi-thread",
    "macros",
    "net",
    "time",
] }
```

## Configuring IRC Clients

As seen above, there are two techniques for configuring the irc crate: runtime loading and
programmatic configuration. Runtime loading is done via the function `Config::load`, and is likely
sufficient for most IRC bots. Programmatic configuration is convenient for writing tests, but can
also be useful when defining your own custom configuration format that can be converted to `Config`.
The primary configuration format is TOML, but if you are so inclined, you can use JSON and/or YAML
via the optional `json_config` and `yaml_config` features respectively. At the minimum, a configuration
requires `nickname` and `server` to be defined, and all other fields are optional. You can find
detailed explanations of the various fields on [docs.rs][config-fields].

[config-fields]: https://docs.rs/irc/*/irc/client/data/config/struct.Config.html#fields

Alternatively, you can look at the example below of a TOML configuration with all the fields:

```toml
owners = []
nickname = "user"
nick_password = "password"
alt_nicks = ["user_", "user__"]
username = "user"
realname = "Test User"
server = "chat.freenode.net"
port = 6697
password = ""
proxy_type = "None"
proxy_server = "127.0.0.1"
proxy_port = 1080
proxy_username = ""
proxy_password = ""
use_tls = true
cert_path = "cert.der"
client_cert_path = "client.der"
client_cert_pass = "password"
encoding = "UTF-8"
channels = ["#rust", "#haskell", "#fake"]
umodes = "+RB-x"
user_info = "I'm a test user for the irc crate."
version = "irc:git:Rust"
source = "https://github.com/aatxe/irc"
ping_time = 180
ping_timeout = 20
burst_window_length = 8
max_messages_in_burst = 15
should_ghost = false
ghost_sequence = []

[channel_keys]
"#fake" = "password"

[options]
note = "anything you want can be in here!"
and = "you can use it to build your own additional configuration options."
key = "value"
```

You can convert between different configuration formats with `convertconf` like so:

```shell
cargo run --example convertconf -- -i client_config.json -o client_config.toml
```

Note that the formats are automatically determined based on the selected file extensions. This
tool should make it easier for users to migrate their old configurations to TOML.

## Contributing
the irc crate is a free, open source library that relies on contributions from its maintainers,
Ariel Weiss ([@aatxe][awe]) and Peter Atashian ([@retep998][bun]), as well as the broader Rust
community. It's licensed under the Mozilla Public License 2.0 whose text can be found in
`LICENSE.md`. To foster an inclusive community around the irc crate, we have adopted a Code of
Conduct whose text can be found in `CODE_OF_CONDUCT.md`. You can find details about how to
contribute in `CONTRIBUTING.md`.

[awe]: https://github.com/aatxe/
[bun]: https://github.com/retep998/