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