From 3f65d48264430428a2165f6a9f5a4e16f823f6b8 Mon Sep 17 00:00:00 2001
From: Zoffix Znet <cpan@zoffix.com>
Date: Thu, 19 May 2016 19:49:39 -0400
Subject: Start new design docs

---
 DESIGN/01-main.md              | 70 ++++++++++++++++++++++++++++++++++++++++++
 DESIGN/specs-and-references.md | 15 +++++++++
 2 files changed, 85 insertions(+)
 create mode 100644 DESIGN/01-main.md
 create mode 100644 DESIGN/specs-and-references.md

(limited to 'DESIGN')

diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md
new file mode 100644
index 0000000..16ecf24
--- /dev/null
+++ b/DESIGN/01-main.md
@@ -0,0 +1,70 @@
+# PURPOSE
+
+The purpose of IRC::Client is to provide serve as a fully-functional IRC
+client that--unlike programs like HexChat or mIRC--provide a programmatic
+interface to IRC. So, for example, to send a message to a channel, instead
+of typing a message in a message box and pressing ENTER, a method is called
+and given a string.
+
+Naturally, such an interface provides vast abilities to automate interactions
+with IRC or implement a human-friendly interface, such as HexChat or mIRC.
+
+# GOALS
+
+An implementation must achieve these goals:
+
+## Ease of Use
+
+For basic use, such as a bot that responds to triggers said in channel,
+the details of the IRC protocol must be as invisible as possible. Just as any
+user can install HexChat and join a channel and talk, similar usability has
+to be achieved by the implementation.
+
+As an example, a HexChat user can glance at the user list or channel topic
+without explicitly issuing `NAMES` or `TOPIC` IRC commands. The implementation
+should thus provide similar simplicity and provide a userlist or topic
+via a convenient method rather than explicit method to send the appropriate
+commands and the requirement of listening for the server response events.
+
+## Client-Generated Events
+
+The implementation must allow the users of the code to emit IRC and custom
+events. For example, given plugins A and B, with A performing processing
+first, plugin A can mark all `NOTICE` IRC events as handled and emit them
+as `PRIVMSG` events instead. From the point of view of second plugin B, no
+`NOTICE` commands ever happen (as they arrive to it as `PRIVMSG`).
+
+Similarly, plugin A can choose to emit custom event `FOOBAR` instead of
+`PRIVMSG`, to which plugin B can choose to respond to.
+
+## Possibility of Non-Blocking Code
+
+The implementation must allow the user to perform responses to events in
+a non-blocking manner if they choose to.
+
+# DESIGN
+
+The implementation consists of Core code responsible for maintaining the
+state of the connected client, parsing of server messages, and sending
+essential messages, as well as relating messages to and from plugins.
+
+The implementation distribution may also include several plugins that may
+be commonly needed by users. Such plugins are not enabled by default and
+the user must request their inclusion with code.
+
+## Core
+
+### Client Object
+
+Client Object represents a connected IRC client and is aware of and can
+manipulate its state, such as disconnecting, joining or parting a channel,
+or sending messages.
+
+A program may have multiple Client Objects, but each of them can be connected
+only to one IRC server.
+
+A relevant Client Object must be easily accessible to the user of the
+implementation. This includes user's plugins responsible for handling
+events.
+
+###
diff --git a/DESIGN/specs-and-references.md b/DESIGN/specs-and-references.md
new file mode 100644
index 0000000..12c1f23
--- /dev/null
+++ b/DESIGN/specs-and-references.md
@@ -0,0 +1,15 @@
+
+# Specs
+
+* [RFC 1459](https://tools.ietf.org/html/rfc1459)
+* [RFC 2810](https://tools.ietf.org/html/rfc2810)
+* [RFC 2811](https://tools.ietf.org/html/rfc2811)
+* [RFC 2812](https://tools.ietf.org/html/rfc2812)
+* [RFC 2813](https://tools.ietf.org/html/rfc2813)
+* [WebIRC](https://irc.wiki/WebIRC)
+* [CTCP SPEC](http://cpansearch.perl.org/src/HINRIK/POE-Component-IRC-6.78/docs/ctcpspec.html)
+* [DCC Description](http://www.irchelp.org/irchelp/rfc/dccspec.html)
+
+# Future
+
+IRCv3 group: http://ircv3.net/
-- 
cgit v1.1