FARR plugin: Bakko

[ewemoa]

Bakko - Transformations of FARR Text Field Content

Introduction

  The main point of this plugin is to provide a customizable means for transforming the main FARR window's text field content.  At the moment, "customizable" means that the user can write a bit of JavaScript to operate on the text field content.  It's also possible that people could share these bits of JavaScript

Usage Examples

  1. Bring up FARR and type some text into the text field.

  2. A statusbar icon should appear at (or near) the bottom right of the FARR main window,  Click (currently, left-click) on this icon to bring up some possible transformations.

  3. Some or all of the following may appear -- try one by clicking on the corresponding context menu item.

       Evaluate
         original text:
           2 / 3
         replaced with:
           0.6666666666666666
         original text:
           (1 + 2 + 3) * (-1 + Math.pow(2, 3)) // note: use of JavaScript
         replaced with:
           42

       Factor
         original text:
           6
         replaced with:
           1 * 2 * 3

       ROT13
         original text:
           or fher gb qevax lbhe binygvar
         replaced with:
           be sure to drink your ovaltine

       Sanitize Amazon.com URL
         original text:
           http://www.amazon.com/Mythical-Man-Month-Software-Engineering-Anniversary/dp/0201835959/ref=stuff
         replaced with:
           http://www.amazon.com/Mythical-Man-Month-Software-Engineering-Anniversary/dp/0201835959/

  4. There is rudimentary support for access to a history of text strings which were successfully operated on (but not the results).  The strings in the history may be accessed via the History submenu of the statusbar menu.  NOTE: The history does not currently survive plugin reloads nor FARR restarts.

Creating a Transformation

  Each transformation is implemented as a JavaScript file living in the directory %PLUGINDIR%\transformations\.  Before reading further, I suggest opening up one of the samples in a text editor -- the following description may be easier to follow.  Choosing the shortest sample may be a good idea

  The JavaScript file gets eval()-ed (nasty word, eh?) and the plugin expects the eval() result to be an object.

  The samples accomplish this by starting the file w/:

    (function () {

  and ending it w/:

      return {name: name,
              caption: caption,
              hint: hint,
              icon: icon,
              launch: launch,
              display: display,
              code: code};
    } ());

  (In case it wasn't obvious, what evaluation of that does (as I understand it), is to call a function which returns an object.)

  In between, define the following (some optional):

    name
      string
        no spaces

    caption(stxt)
      function
        returns a string for the menu item's caption.  currently, the returned string gets truncated and " ..." is appended if it is too long (see source of plugin for details).
        stxt is the string value of the content of FARR's main window text field at the time the context menu is being constructed.

    hint(stxt) optional
      function
        returns a string for the hint of the menu item.
        stxt is the string value of the content of FARR's main window text field at the time the context menu is being constructed.

    icon(stxt) optional
      function
        returns a string of the path to an icon for the menu item.
        stxt is the string value of the content of FARR's main window text field at the time the context menu is being constructed.

    launch(stxt)
      function
        returns a string used by FARR to execute the transformation code -- typically returns values looking like:
          farr://pcommand bakko xform <name> <stxt>
        stxt is the string value of the content of FARR's main window text field at the time the context menu is being constructed.

    display(stxt) (optional)
      function
        returns a boolean, true if the transformation should show up in the context menu, false if not.
        stxt is the string value of the content of FARR's main window text field at the time the context menu is being constructed.

    code(argtxt)
      function
        returns a string or null. 
          a string value represents a successful transformation and FARR's main window text field should be replaced with it. 
          a null value means failure.
        argtxt is currently the same as stxt (as mentioned above).

  The transformation has access to variables and functions within the plugin's (function () {} ()) scope (I think).  What this means is that displayname, aliasstr, pu, and the like may all be used within transformations. 

  If something isn't clear (or you think there are mistakes) here, I suggest asking on the forums and/or "Use the source, Luke"

Tips

  Having a hotkey defined to bring up FARR with clipboard content pasted in FARR's main window can be handy.

Bugs

  Probably

Credits

  Thanks go out to:

    mouser
    ecaradec
    Plugin authors that provided source and/or comments on the forums
    DC Forums participants
    DC Supporters


Download

  Experimental - please ensure that the parent directory of the contained fscript.js file is named Bakko.

[nitrix-ud]

 

i don't know if/how i'll use Bakko, but it is really really impressive 

[ewemoa]

Thanks for the feedback

On the off-chance that a little more exposition might spark additional interest, below are some more comments.

To give a more concrete sense of what transformations look like, I'll post source to a couple. 

First, consider the amazon.com URL "sanitizer" (really all it does is to remove everything starting at the ref= portions of many an amazon.com URL):

Code: Javascript [Select]

1. /*global params, pu */ // jslint be quiet
2. (function () {
3.   var name;
4.   // NOTE: no spaces in name
5.   name = "SanitizeAmazonURL";
6.   function caption(stxt) {
7.     return "Sanitize Amazon.com URL";
8.   }
9.   function hint(stxt) {
10.     return ""; // XXX
11.   }
12.   function icon(stxt) {
13.     return pu.pidir + "\\icons\\sanitize.ico";
14.   }
15.   function launch(stxt) {
16.     return "farr://pcommand " +
17.            aliasstr + " " +
18.            "xform " +
19.            name + " " + // NOTE: no spaces in name
20.            stxt;
21.   }
22.   function display(stxt) {
23.     var m;
24.     m = /^https?:\/\/.*\/ref=.*$/.exec(stxt);
25.     if (m === null) {
26.       return false;
27.     } else {
28.       return true;
29.     }
30.   }
31.   function code(argtxt) {
32.     var m;
33.     // http://www.amazon.com/Mythical-Man-Month-Software-Engineering-Anniversary/dp/0201835959/ref=stuff
34.     // ->
35.     // http://www.amazon.com/Mythical-Man-Month-Software-Engineering-Anniversary/dp/0201835959/
36.     m = /^(.*\/)ref=.*$/.exec(argtxt);
37.     if (m === null) {
38.       pu.displayAlertMessage("Failed to sanitize URL");
39.       return null;
40.     } else {
41.       return m[1];
42.     }
43.   }
44.   return {name: name,
45.           caption: caption,
46.           hint: hint,
47.           icon: icon,
48.           launch: launch,
49.           display: display,
50.           code: code};
51. } ());

Next, consider the following which attempts to convert some wikimedia (e.g. wikipedia.org) http URLs to corresponding(?) https URLs -- note, that this one is not yet available in the archive.

Code: Javascript [Select]

1. /*global params, pu */ // jslint be quiet
2. /*
3.    A number of Wikimedia-provided http URLs appear to have https
4.    counterparts.  This transformation attempts to provide a
5.    bridge between these.
6.  
7.    Examples:
8.  
9.      http://en.wikipedia.org/wiki/Magnetite
10.        ->
11.          https://secure.wikimedia.org/wikipedia/en/wiki/Magnetite
12.  
13.      http://ja.wikipedia.org/wiki/Test
14.        ->
15.          https://secure.wikimedia.org/wikipedia/ja/wiki/Test
16.  
17.      Although note that FARR may not handle some non-ASCII so well...
18.  
19.      http://en.wiktionary.org/wiki/test
20.        ->
21.          https://secure.wikimedia.org/wiktionary/en/wiki/test
22.  */
23. (function () {
24.   // XXX: select text after transformed?
25.   var name, snametable;
26.   // NOTE: no spaces in name
27.   name = "SecureWikimediaURL";
28.   // What is currently handled...
29.   //      *.wikipedia.org
30.   //      *.wikisource.org
31.   //      *.wikiversity.org
32.   //      *.wiktionary.org
33.   //      *.wikinews.org
34.   //      *.wikiquote.org
35.   //      *.wikibooks.org
36.   //
37.   // XXX: what to do about:
38.   //      mediawiki.org
39.   //      commons.wikimedia.org
40.   //      meta.wikimedia.org
41.   //      wikimediafoundation.org
42.   //      species.wikimedia.org
43.   //      incubator.wikimedia.org
44.   snametable = {
45.     "wikipedia": true,
46.     "wikisource": true,
47.     "wikiversity": true,
48.     "wiktionary": true,
49.     "wikinews": true,
50.     "wikiquote": true,
51.     "wikibooks": true
52.   };
53.   function caption(stxt) {
54.     return "Secure Wikimedia URL";
55.   }
56.   function hint(stxt) {
57.     return ""; // XXX
58.   }
59.   function icon(stxt) {
60.     return pu.pidir + "\\icons\\secure.ico";
61.   }
62.   function launch(stxt) {
63.     return "farr://pcommand " +
64.            aliasstr + " " +
65.            "xform " +
66.            name + " " + // NOTE: no spaces in name
67.            stxt;
68.   }
69.   function display(stxt) {
70.     var m, sname;
71.     m = /^http:\/\/([^\/]+\.)*([a-zA-Z]+)\.org\/wiki\//.exec(stxt);
72.     if (m !== null) {
73.       sname = m[2];
74.       if (snametable[sname]) {
75.         return true;
76.       }
77.     }
78.     return false;
79.   }
80.   function code(argtxt) {
81.     var m, lname, sname, what;
82.     // XXX: synchronize (more?) w/ regexp in display()?
83.     m = /^http:\/\/([a-zA-Z]+)\.([a-zA-Z]+)\.org\/wiki\/(.*)$/.exec(argtxt);
84.     if (m === null) {
85.       pu.displayAlertMessage("Failed to 'secure' URL");
86.       return null;
87.     } else {
88.       lname = m[1];
89.       sname = m[2];
90.       what = m[3];
91.       return "https://secure.wikimedia.org/" +
92.              sname + "/" +
93.              lname + "/" +
94.              "wiki/" + what;
95.     }
96.   }
97.   return {name: name,
98.           caption: caption,
99.           hint: hint,
100.           icon: icon,
101.           launch: launch,
102.           display: display,
103.           code: code};
104. } ());

[ewemoa]

FWIW, what I tend to use the plugin for are the following transformations:

• wikimedia http URL -> https URL
• evaluator
• prime factorization

The evaluator just hands things to Javascript to evaluate -- so although the examples documented in the OP are for mathematical calculations, one can actually do a fair bit more.  What I tend to use this for is small bits of testing.  For example, recently mouser added %APPDRIVE% support for FARR and I wanted to see if it worked.  What I ended up doing to test this was to type the following into FARR's main window text edit field:

FARR.getStrValue("resolve:%APPDRIVE%");

and then choose the "Evaluate" context menu item.  This saved me a tiny amount of time and effort changing code in a plugin and reloading it.

I did something similar to test mouser's implementation of %PLUGINDIR% too

[mouser]

There is also the new Ctrl+T hotkey to bring up tray menu when you are in the search edit box, which makes it easier to bring up Bakko.

[ewemoa]

Right.  Thanks mouser for adding this hotkey!  Very helpful

[mouser]

ewe, how about this: https://www.donation...?topic=14496.new#new

[ewemoa]

IIUC, what is suggested is to take something like:

FindAndRunRobot.exe

and change it into:

FindAndRunRobot.exe +sall

Does that sound about right and if so is there any difference whether +sall is prepended or appended?

I guess the other ones listed under "Special Search Modifier Keywords" could be done too...

[mouser]

exactly right; wont make a dif but putting it at end makes more sense to me.

[ewemoa]

Here's a proof-of-concept implementation (showall.js) -- no icon and some problems exist, but FWIW:

Code: Javascript [Select]

1. /*global params, pu */ // jslint be quiet
2. (function () {
3.   var name;
4.   // NOTE: no spaces in name
5.   name = "ShowALLResults";
6.   function caption(stxt) {
7.     return "Show All Results";
8.   }
9.   function hint(stxt) {
10.     return ""; // XXX
11.   }
12.   function icon(stxt) {
13.     return pu.pidir + "\\icons\\showall.ico";
14.   }
15.   function launch(stxt) {
16.     return "farr://pcommand " +
17.            aliasstr + " " +
18.            "xform " +
19.            name + " " + // NOTE: no spaces in name
20.            stxt;
21.   }
22.   function display(stxt) {
23.     var m;
24.     // XXX: need a better regexp?
25.     m = /\+sall/.exec(stxt);
26.     if (m !== null) {
27.       return false;
28.     } else {
29.       return true;
30.     }
31.   }
32.   function code(argtxt) {
33.     return argtxt + " +sall";
34.   }
35.   return {name: name,
36.           caption: caption,
37.           hint: hint,
38.           icon: icon,
39.           launch: launch,
40.           display: display,
41.           code: code};
42. } ());

[ewemoa]

I made similar transformations for +alias and -alias.  (I wonder if it's going too far to remove +alias if adding -alias and vice versa...)

Then I noticed that the tray icon for Bakko disappeared after I used -alias 

[ewemoa]

The detection of +sall/+alias/-alias currently uses regular expressions and it's probably not quite right.

I was thinking that may be applying:

[Select]

FARR.getStrValue("Search.keywords")

appropriately might work better.  (I use it in the Akete plugin and there it seems to be fine.)

However, I noticed that the return value doesn't appear to contain the leading + or - characters.

Any chance there's some other existing (reliable) method of obtaining the keywords along w/ the leading (+/-) characters?