Mercurial > irccd

annotate doc/src/format.md @ 817:ebe561276c33

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: start reworking, continue #752 @8h
author David Demelier <markand@malikania.fr>
date Mon, 19 Nov 2018 07:04:42 +0100
parents
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
817
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 Plugins can be configured using a powerful template syntax, this allows editing
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 the plugin messages to override them.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
3
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 The syntax is `?{}` where `?` is replaced by one of the token defined below.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 Braces are mandatory and cannot be ommited. To write a literal template
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 construct, prepend the token twice.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
7
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 The following templates are available:
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
9
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 - `%`, date and time (see Time section),
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 - `#{name}`, name will be substituted from the keywords (see Keywords section),
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 - `${name}`, name will be substituted from the environment variable (see
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 Environment variables),
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 - `@{attributes}`, the attributes will be substituted to IRC colors (see
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 Attributes).
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
16
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 # Time
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
18
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 When you can use patterns, the date and time may be used just like `strftime(3)`
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 so for the hours and minutes, you can use **%H:%M**.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
21
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 # Environment variables
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
23
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 If supported, you can use environment variables like **${HOME}**. Please note
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 that braces are mandatory.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
26
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 # IRC attributes
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
28
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
29 The attribute format is composed of three parts, foreground, background and
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 modifiers, each separated by a comma.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
31
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
32 note: attributes and colors are not supported by all IRC clients.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
33
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
34 warning: do not use colors and attributes outside IRC (e.g. for storing text in
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 files) because escape codes are only valid in IRC context.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
36
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
37 ## Available colors
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
38
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
39 - white,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
40 - black,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 - blue,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
42 - green,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 - red,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
44 - brown,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
45 - purple,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 - orange,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
47 - yellow,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 - lightgreen,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
49 - cyan,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 - lightcyan,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
51 - lightblue,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
52 - pink,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 - grey,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
54 - lightgrey.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
55
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 ## Available attributes
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
57
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 - bold,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
59 - italic,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 - strike,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 - reset,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
62 - underline,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 - underline2,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
64 - reverse.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
65
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
66 # Shell attributes
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
67
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 Like IRC attributes, it's possible to specify colors and attributes in some
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
69 places such as logger configuration.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
70
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 Warning: colors are not supported on all platforms.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
72
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
73 ## Available colors
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
74
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
75 - black,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
76 - red,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 - green,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
78 - orange,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
79 - blue,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 - purple,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 - cyan,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
82 - white,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 - default.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
84
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
85 ## Available attributes
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
86
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
87 - bold,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
88 - dim,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
89 - underline,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
90 - blink,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
91 - reverse,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
92 - hidden.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
93
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
94 # Keywords
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
95
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
96 Keywords are arbitrary names that are replaced depending on the context. They
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
97 are usually available to configure plugins.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
98
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
99 ## Predefined keywords
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
100
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 Here's the list of keywords that a lot of plugins uses:
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
102
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
103 - #{channel}, the channel name,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
104 - #{command}, the command to invoke the plugin, e.g. `!ask`,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
105 - #{message}, a message (depending on context),
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
106 - #{origin}, the full user, e.g. `markand!~mkd@localhost`,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
107 - #{nickname}, the short nickname,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
108 - #{plugin}, the plugin name,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
109 - #{server}, the current server name,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
110 - #{topic}, the topic,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
111 - #{target}, a target, e.g. a person who gets kicked.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
112
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
113 warning: these keywords can be overriden by plugins.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
114
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
115 # Examples
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
116
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
117 Valid constructs:
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
118
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
119 - `\#{target}, welcome`: if target is set to "irccd", becomes "irccd, welcome",
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
120 - `@{red}#{target}`: if target is specified, it is written in red.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
121
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
122 Invalid or literals constructs:
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
123
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
124 - `\#{target}`: will output "#{target}",
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
125 - `##`: will output "##",
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
126 - `#target`: will output "#target",
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
127 - `#{target`: will throw an error.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
128
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
129 Colors & attributes:
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
130
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
131 - `@{red,blue}`: will write text red on blue background,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
132 - `@{default,yellow}`: will write default color text on yellow background,
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
133 - `@{white,black,bold,underline}`: will write white text on black in both bold
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
134 and underline.
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
135
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
136 Using the logger plugin:
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
137
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
138 For instance, using the **logger** plugin, it's possible to customize the
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
139 pattern to use when someone joins a channel like that:
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
140
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
141 #{origin} joined #{channel}
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
142
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
143 The keyword **#{origin}** will be substituted to the nickname and **#{channel}**
ebe561276c33 doc: start reworking, continue #752 @8h
David Demelier <markand@malikania.fr>
parents:
diff changeset
144 to the channel name.