README

   1 what is Guerilla Scripting?
   2 ===========================
   3
   4 GS is a userscript injecting engine, somewhat like GreaseMonkey, but
   5 aimed at knowledgeable power users. GS was modelled after Opera 12
   6 userscript engine, but with support for some GreaseMonkey API.
   7
   8 GS has absolutely no GUI controls, as power users using developer console
   9 anyway. ;-) it has it's own command in developer console (shift+f2):
  10 "guerilla". this is the preferred (and the only one) way to dynamically
  11 control GS (except some preferences in about:config page).
  12
  13 you probably will not need anything except "guerilla reset", though,
  14 which resets GS caches. you may need that if GS is not able to see
  15 changes in your script, and you certainly will need it if you changed
  16 one of the @require'd or @library files.
  17
  18 GS also don't have any l10n, and probably will not have any. as there is
  19 no GUI and no user-visible dialogs, i don't see any real value in adding
  20 l10n to GS.
  21
  22
  23 how Guerilla Scripting works?
  24 =============================
  25
  26 contrary to GreaseMonkey, GS doesn't need any registration of
  27 userscripts. simply copy your script in GS scripts directory with your
  28 file manager, and GS should see it. to remove script, simply delete it or
  29 change it's extension to someting that is not ".js".
  30
  31 if GS is unable to see new/updated/removed script, do "guerilla reset" in
  32 developer console.
  33
  34 there is no itegration with any sites, nor automatic script updates from
  35 teh internets. GS will *never* connect to any internet site on it's own,
  36 it doesn't do any automatic installation or updating of userscripts.
  37
  38
  39 is Guerilla Scripting secure?
  40 =============================
  41
  42 the only way to add a userscript to GS is to MANUALLY copy it in GS
  43 scripts directory (which is in your profile dir, named "guerillajs"). so
  44 if you wrote all the scripts by yourself or got them from the friend you
  45 can trust to, there should be no security breaches.
  46
  47 GS will not do any connections to any sites on it's own. but note that
  48 userscripts are free to connect to any site they want (exactly as in
  49 GreaseMonkey), and additionally, userscripts are free to read you local
  50 files too. please, note that GreaseMonkey userscripts can't read your
  51 local files ( they can try, but the request will fail), so you shouldn't
  52 simply copy GreaseMonkey userscripts to GS without understanging what
  53 they are doing under the hood.
  54
  55 the reason for giving GS userscripts access to local files is the
  56 difference in addon target group. while GreaseMonkey is aimed at casual
  57 users, GS is aimed at knowledgeable power users, who may want to squeeze
  58 some more power from their userscripts.
  59
  60 WARNING! you should NEVER EVER install userscripts downloaded from
  61 internet to GS, unless you know for sure what that scripts do and how.
  62 if you'll install some malicious script downloaded from internet, that
  63 script can breach your privacy, steal or alter your private data and so
  64 on.
  65
  66 please note that GreaseMonkey scripts can do privacy violation to some
  67 extent too, that is nature of userscripts.
  68
  69
  70 API differences to GreaseMonkey
  71 ===============================
  72
  73 some GreaseMonkey API aren't implemented, and some implemented in
  74 slightly different way. script @metas altered too.
  75
  76 API that should work the same in GS and GreaseMonkey:
  77   unsafeWindow
  78   GM_log
  79   GM_getValue
  80   GM_setValue
  81   GM_deleteValue
  82   GM_listValues
  83   GM_xmlhttpRequest
  84   GM_addStyle
  85   GM_openInTab(url[, background]) -- if `background` is boolean
  86
  87 extended API:
  88   GM_openInTab(url, options)
  89   options is an object which can contain such fields:
  90     bool background -- open tab in background
  91     bool afterCurrent -- open tab after current one,
  92                          if current is userscript tab
  93
  94 API that doesn't work (i.e. exists, but does nothing):
  95   GM_getResourceText
  96   GM_getResourceURL
  97   GM_registerMenuCommand
  98   GM_setClipboard
  99
 100 additional API:
 101   conlog (same as GM_log)
 102   logError (logs error message to error console)
 103   GM_generateUUID (same as in Scriptish)
 104   GM_cryptoHash (same as in Scriptish)
 105   GM_safeHTMLParser (same as in Scriptish)
 106
 107
 108 @meta differences to GreaseMonkey
 109 =================================
 110
 111 GS understands very small amount of @metas, and simply skips all keywords
 112 it doesn't know.
 113
 114 working:
 115   @include
 116   @exclude
 117   @noframe
 118   @run-at
 119
 120 different:
 121   @require -- this works COMPLETELY different, see below
 122
 123 new:
 124   @libraries -- see below
 125
 126
 127 changed @meta: @require
 128 =======================
 129
 130 @require now can require only js files. all js files you want to @require
 131 should reside in the directory named after your script. let me give a
 132 sample.
 133
 134 let's assume you has script named "myscript.js" with such contents:
 135
 136 // ==UserScript==
 137 // @require somecode.js
 138 // ==/UserScript==
 139
 140 GS will look for file "./myscript/somecode.js", relative to "myscript.js"
 141 directory.
 142
 143 if any @required file is absent, GS will refuse to run such userscript.
 144
 145 multiple @require for same file are allowed, but file will be loaded only
 146 once, first time GS sees @require with it.
 147
 148
 149 new @meta: @library
 150 ===================
 151
 152 userscripts can load common libraries. this is almost the same as
 153 @require, only search path differs. libraries are always looked in
 154 "./libs/" directory.
 155
 156 GS will load all @libraries first, and @require next, regardless of the
 157 declaration order.
 158
 159
 160 known bugs
 161 ==========
 162
 163 GS looks like restartless addon, but disabling it and enabling again will
 164 not do any good yet. GS may stop working at all or work unstable/buggy.
 165 i plan to fix that, but can't give any timeline.
 166
 167 if you changed @required file, but didn't touch main one, GS may not
 168 notice the change. this probably will not be fixed, as monitoring
 169 filesystem is costly, and will slow down GS.
 170
 171 probably many other bugs i didn't found yet.
 172
 173
 174
 175 good luck, and happy hacking!
 176 Ketmar Dark  <ketmar@ketmar.no-ip.org>