1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
|
Eggdrop Autoscripts
Since it's inception, users have needed to load a Tcl script into
Eggdrop by downloading a Tcl file, editing the file to customize
settings, and then sourceing that file in the config file. In v1.10, the
Autoscripts system was added to make this process a little more
user-friendly. The autoscripts system helps by:
- Centralizing commonly-used scripts in a single location
- Allowing scripts to be downloaded via the partyline
- Allowing script settings to be configured via the partyline
- Allowing user-written scripts to be managed by the autoscripts
system
- Providing a documented API to write autoscripts-compatible scripts
AUTOSCRIPTS USAGE
To view available autoscript commands, type .autoscript on the
partyline. This will open up a special Eggdrop console that doesn't
require you to prefix commands with a '.' . The following sub-commands
are available for use with script:
remote
This command will list scripts hosted on the Eggdrop website that are
available to be downloaded and installed on your Eggdrop.
fetch <script>
This command will download the specified script from the Eggdrop website
and place it into the autoscript/ directory.
list
This command will list scripts locallt present in the autoscripts/
directory, available to be configured and loaded.
config <script>
This command will list settings available for configuration for the
provided script.
set <script> <setting>
This command will set setting for script to the provided value. To
activate this change, use the load command.
load <script>
This command will activate the script for use. You can also use this
command to reload a script after modifying a script variable.
unload <script>
This command will prevent the script from being loaded the next time
Eggdrop starts. To fully unload a script, Eggdrop must be restarted!
clean <script>
This command will delete the script from the filesystem. After running
this command, you will have to re-download and re-configure the script
if you wish to use it again.
update [script]
If no script is specified, this command checks if there any downloaded
script has a newer version available. If a script is specified,
autoscript will fetch and install the updated script.
AUTOSCRIPTS FILE STRUCTURE
An autoscripts package requires (minimum) two files: the Tcl script, and
a json manifest file.
Tcl File
Nothing new or novel here; this is where your Tcl code goes. The one
change to this file is that any setting intended should now be located
in the manifest.json file, not the Tcl script file. All variables will
be added to the global namespace. For this reason, we suggest wrapping a
custom autoscript inside a namespace eval <scriptname> {} statement as
an autoscript best practice, which will lessen the chance of a variable
name colliding with a variable from a separate script.
Manifest.json
Every autoscripts package must have a manifest.json file. This file
contains metadata for the script such as version and description
information, as well as the user-configurable settings for use with th
script. A simple example of a manifest.json file is as follows:
{
"schema": 1,
"name": "woobie",
"version_major": 1,
"version_minor": 0,
"description": "An example script to help developers write autoscript packages",
"long_description": "This is an example script to help understand the autoscript system. Yeah, it doesn't really do anything, but that's besides the point. It could, and that should be enough for anyone"
"config": {
"loaded": 0,
"udef": {
"myflag": {
"type": "flag",
"description": "Activate the script on <channel> by doing"
},
"mystr1": {
"type": "str",
"description": "Flood limit, modify the channel value for this doing",
"value": "{10:6}"
},
"mystr2": {
"type": "str",
"description": "Change that with",
"value": "Just my string"
}
"myint1": {
"type": "int",
"description": "Number of allowed kicks, could be change with",
"value": 4
}
},
"requires": "tls",
"vars": {
"woobie_dict": {
"description": "A setting that accepts a dict as a value",
"value": "{quiet q}"
},
"woobie_setting": {
"description": "A normal setting to enable or disable something",
"value": "1"
},
"woobie_string": {
"description": "A setting taking a string, like a filename or something",
"value": "woobie"
},
"woobie(array)": {
"description": "A setting that is set as an array",
"value":"another string"
}
}
}
}
----------------------------------- -------------------------------------------------------------
schema The schema version of autoscript (currently 1)
name The name of the script. Must match the script name (if the
script is foo.tcl, then this must be foo)
version_major The major version integer (ie, 1 for 1.6)
version_minor The minor version integer (ie, 6 for 1.6)
description A one-line summary of what the script does. This will be
shown when available scripts are listed on the partyline via
.script list.
long_description A longer description of what the script does, similar to a
README. This will be shown when a script is viewed via
.script config.
config-loaded Whether this script is currently loaded or not. It should be
default set to 0.
config-udef-<varname>-type Type of the user-defined channel setting, could be flag, str
or int.
config-udef-<varname>-description Description of user-defined channel setting used by the
script. The description is appended with " .chanset <channel>
<varname> value" in case of int or str, and with " .channel
<channel> +<varname>" when flag
config-udef-<varname>-value Default value of user-defined channel setting used by the
script. This is displayed when configuration settings are
displayed to the user on the partyline.
config-requires Any Tcl package required for use by the script, such as tls,
http, json, etc.
config-vars-<varname> A setting intended to be modified by the user. The
'description' field should describe what the setting does,
and the 'value' field stores the current value. These
settings are displayed when the configuration settings are
displayed to the user on the partyline.
config-vars-<varname>-description A description of the setting, displayed in the configuration
listing for the script.
config-vars-<varname>-value The value the setting is set to
----------------------------------- -------------------------------------------------------------
File placement
Autoscript files are stored in the autoscript directory. The path
structure is eggdrop/autoscript/<scriptname>/[script files]. If the
autoscript fetch command is used, a .tgz file will be downloaded and
extracted to the proper location automatically. If you wish to manually
add a script, create a directory with the same name as the script, and
then place the script and manifest files inside the directory. The
directory name must exactly match the script name (without the .tcl
extension)! If the Tcl script to be loaded is called
myscript_goodversion_specialfeature.tcl, then the directory must also
called myscript_goodversion_specialfeature.
DEVELOPMENT HINTS
- An autoscript should not require a user to manually open the script
in an editor for any reason. Design your script as such!
- Use user defined channel flags to enable/disable a script for a
particular channel, they're easy!
- Don't use global statements. Based on the manifest, variables are
created by autoscript in the global namespace before the script is
loaded. Instead of the global command, use the variable command to
access a global variable inside a proc. And because Tcl is awesome,
each variable must be declared on its own line, not all on a single
line like you can do with global. Sorry!
- While we're talking about variables... make them unique to prevent
collisions! We recommend prefixing the script name in front of a
variable, such as myscript_setting or ms_setting. Alternatively, you
can wrap your autoscript inside a namespace eval <scriptname> {}
statement, which create a private namespace for your script to
operate within.
TCL COMMANDS
The autoscripts Tcl script adds three new commands for use with Tcl
scripts:
egg_loaded
Description: lists all scripts currently loaded via the autoscripts
system
Returns: A Tcl list of script names currently loaded via autoscripts
egg_unloaded
Description: lists all scripts downloaded to the local machine via the
autoscripts system but not currently loaded by Eggdrop
Returns: A Tcl list of script names downloaded but not currently
loaded via autoscripts
egg_all
Description: lists all script downloaded to the localm machine via the
autoscripts system, regardless if they are running or not
Returns: A Tcl list of all script namees download via autoscripts
|
