ircmsg

Documentation

Overview

Package ircmsg helps parse and create lines for IRC connections.

Index

• Constants
• Variables
• func EscapeTagValue(inString string) string
• func TruncateUTF8Safe(message string, byteLimit int) (result string)
• func UnescapeTagValue(inString string) string
• type Message
  • func MakeMessage(tags map[string]string, source string, command string, params ...string) (ircmsg Message)
  • func ParseLine(line string) (ircmsg Message, err error)
  • func ParseLineStrict(line string, fromClient bool, truncateLen int) (ircmsg Message, err error)
  • func (msg *Message) AllTags() (result map[string]string)
  • func (msg *Message) ClientOnlyTags() map[string]string
  • func (msg *Message) DeleteTag(tagName string)
  • func (msg *Message) ForceTrailing()
  • func (msg *Message) GetTag(tagName string) (present bool, value string)
  • func (msg *Message) HasTag(tagName string) (present bool)
  • func (ircmsg *Message) Line() (result string, err error)
  • func (ircmsg *Message) LineBytes() (result []byte, err error)
  • func (ircmsg *Message) LineBytesStrict(fromClient bool, truncateLen int) ([]byte, error)
  • func (msg *Message) NUH() (nuh NUH, err error)
  • func (msg *Message) Nick() (nick string)
  • func (msg *Message) SetTag(tagName, tagValue string)
  • func (msg *Message) UpdateTags(tags map[string]string)
• type NUH
  • func ParseNUH(in string) (out NUH, err error)
  • func (nuh *NUH) Canonical() (result string)

Constants

const (
	// "The size limit for message tags is 8191 bytes, including the leading
	//  '@' (0x40) and trailing space ' ' (0x20) characters."
	MaxlenTags = 8191

	// MaxlenTags - ('@' + ' ')
	MaxlenTagData = MaxlenTags - 2

	// "Clients MUST NOT send messages with tag data exceeding 4094 bytes,
	//  this includes tags with or without the client-only prefix."
	MaxlenClientTagData = 4094

	// "Servers MUST NOT add tag data exceeding 4094 bytes to messages."
	MaxlenServerTagData = 4094

	// '@' + MaxlenClientTagData + ' '
	// this is the analogue of MaxlenTags when the source of the message is a client
	MaxlenTagsFromClient = MaxlenClientTagData + 2
)

Variables

var (
	// ErrorLineIsEmpty indicates that the given IRC line was empty.
	ErrorLineIsEmpty = errors.New("Line is empty")

	// ErrorLineContainsBadChar indicates that the line contained invalid characters
	ErrorLineContainsBadChar = errors.New("Line contains invalid characters")

	// ErrorBodyTooLong indicates that the message body exceeded the specified
	// length limit (typically 512 bytes). This error is non-fatal; if encountered
	// when parsing a message, the message is parsed up to the length limit, and
	// if encountered when serializing a message, the message is truncated to the limit.
	ErrorBodyTooLong = errors.New("Line body exceeded the specified length limit; outgoing messages will be truncated")

	// ErrorTagsTooLong indicates that the message exceeded the maximum tag length
	// (the specified response on the server side is 417 ERR_INPUTTOOLONG).
	ErrorTagsTooLong = errors.New("Line could not be processed because its tag data exceeded the length limit")

	// ErrorInvalidTagContent indicates that a tag name or value was invalid
	ErrorInvalidTagContent = errors.New("Line could not be processed because it contained an invalid tag name or value")

	// ErrorCommandMissing indicates that an IRC message was invalid because it lacked a command.
	ErrorCommandMissing = errors.New("IRC messages MUST have a command")

	// ErrorBadParam indicates that an IRC message could not be serialized because
	// its parameters violated the syntactic constraints on IRC parameters:
	// non-final parameters cannot be empty, contain a space, or start with `:`.
	ErrorBadParam = errors.New("Cannot have an empty param, a param with spaces, or a param that starts with ':' before the last parameter")
)

var (
	MalformedNUH = errors.New("NUH is malformed")
)

Functions

func EscapeTagValue

func EscapeTagValue(inString string) string

EscapeTagValue takes a value, and returns an escaped message tag value.

This function is automatically used when lines are created from an Message, so you don't need to call it yourself before creating a line.

func TruncateUTF8Safe

func TruncateUTF8Safe(message string, byteLimit int) (result string)

TruncateUTF8Safe truncates a message, respecting UTF8 boundaries. If a message was originally valid UTF8, TruncateUTF8Safe will not make it invalid; instead it will truncate additional bytes as needed, back to the last valid UTF8-encoded codepoint. If a message is not UTF8, TruncateUTF8Safe will truncate at most 3 additional bytes before giving up.

func UnescapeTagValue

func UnescapeTagValue(inString string) string

UnescapeTagValue takes an escaped message tag value, and returns the raw value.

This function is automatically used when lines are interpreted by ParseLine, so you don't need to call it yourself after parsing a line.

Types

type Message

type Message struct {
	Source  string
	Command string
	Params  []string
	// contains filtered or unexported fields
}

Message represents an IRC message, as defined by the RFCs and as extended by the IRCv3 Message Tags specification with the introduction of message tags.

func MakeMessage

func MakeMessage(tags map[string]string, source string, command string, params ...string) (ircmsg Message)

MakeMessage provides a simple way to create a new Message.

func ParseLine

func ParseLine(line string) (ircmsg Message, err error)

ParseLine creates and returns a message from the given IRC line.

func ParseLineStrict

func ParseLineStrict(line string, fromClient bool, truncateLen int) (ircmsg Message, err error)

ParseLineStrict creates and returns an Message from the given IRC line, taking the maximum length into account and truncating the message as appropriate. If fromClient is true, it enforces the client limit on tag data length (4094 bytes), allowing the server to return ERR_INPUTTOOLONG as appropriate. If truncateLen is nonzero, it is the length at which the non-tag portion of the message is truncated.

func (*Message) AllTags

func (msg *Message) AllTags() (result map[string]string)

AllTags returns all tags as a single map.

func (*Message) ClientOnlyTags

func (msg *Message) ClientOnlyTags() map[string]string

ClientOnlyTags returns the client-only tags (the tags with the + prefix). The returned map may be internal storage of the Message object and should not be modified.

func (*Message) DeleteTag

func (msg *Message) DeleteTag(tagName string)

DeleteTag deletes a tag.

func (*Message) ForceTrailing

func (msg *Message) ForceTrailing()

ForceTrailing ensures that when the message is serialized, the final parameter will be encoded as a "trailing parameter" (preceded by a colon). This is almost never necessary and should not be used except when having to interact with broken implementations that don't correctly interpret IRC messages.

func (*Message) GetTag

func (msg *Message) GetTag(tagName string) (present bool, value string)

GetTag returns whether a tag is present, and if so, what its value is.

func (*Message) HasTag

func (msg *Message) HasTag(tagName string) (present bool)

HasTag returns whether a tag is present.

func (*Message) Line

func (ircmsg *Message) Line() (result string, err error)

Line returns a sendable line created from an Message.

func (*Message) LineBytes

func (ircmsg *Message) LineBytes() (result []byte, err error)

LineBytes returns a sendable line created from an Message.

func (*Message) LineBytesStrict

func (ircmsg *Message) LineBytesStrict(fromClient bool, truncateLen int) ([]byte, error)

LineBytesStrict returns a sendable line, as a []byte, created from an Message. fromClient controls whether the server-side or client-side tag length limit is enforced. If truncateLen is nonzero, it is the length at which the non-tag portion of the message is truncated.

func (*Message) NUH

func (msg *Message) NUH() (nuh NUH, err error)

NUH returns the source of the message as a parsed NUH ("nick-user-host"); if the source is not well-formed as a NUH, it returns an error.

func (*Message) Nick

func (msg *Message) Nick() (nick string)

Nick returns the name component of the message source (typically a nickname, but possibly a server name).

func (*Message) SetTag

func (msg *Message) SetTag(tagName, tagValue string)

SetTag sets a tag.

func (*Message) UpdateTags

func (msg *Message) UpdateTags(tags map[string]string)

UpdateTags is a convenience to set multiple tags at once.

type NUH

type NUH struct {
	Name string
	User string
	Host string
}

NUH holds a parsed name!user@host source ("prefix") of an IRC message. The Name member will be either a nickname (in the case of a user-initiated message) or a server name (in the case of a server-initiated numeric, command, or NOTICE).

func ParseNUH

func ParseNUH(in string) (out NUH, err error)

ParseNUH parses a NUH source of an IRC message into its constituent parts; name (nickname or server name), username, and hostname.

func (*NUH) Canonical

func (nuh *NUH) Canonical() (result string)

Canonical returns the canonical string representation of the NUH.