yub.js

Yub.js is an extensible client-side web command-line that comes with loads of useful search engines and shortcuts, reusable commands, and lots of other hidden goodies like stopwatches and inline YouTube videos. It also has a flexible API so you can call yub.js commands from anywhere: for example, you can link directly to commands, or access them right from your browser address bar (just set up a single search shortcut pointing at the yub.js API, and get hundreds of other search shortcuts for free).

The whole thing was designed from the outset to be a single page standalone html document containing everything needed to work out of the box. It can be installed locally and run right from your computer without the need for a server or web hosting. Since then it has grown considerably and development has been split into separate, more manageable files. The standalone html page version is still available, though it is now automatically generated by a ruby script, and comes in minified and source versions. Just save the page directly to your computer or drop it on your server and you're ready to go!

The list of available search engines is completely modular: you can drop in your own list of commonly visited websites by editing or replacing the mods.js file (json). Making your own new commands is easy -- just use the create command (with the name of the new command as an optional argument). Feel free to add your own new functions or extend existing ones by editing functions.js. Oh, and regular expressions are supported everywhere by default.

• 1 Cool Things To Try Out
  • 1.1 The Basics
  • 1.2 More Examples
• 2 Search Engines
  • 2.1 engines.js
  • 2.2 mods.js
  • 2.3 Customization
• 3 Skins
• 4 Installation
• 5 API
• 6 Embedding
• 7 Upcoming Features
• 8 History
• 9 Development
• 10 It Might Not Be For You
• 11 Similar Projects
• 12 Acknowledgements
• 13 License

Cool Things To Try Out

The best way to understand how yub.js works is to jump in and start trying commands. So before getting into boring things like history or internals, let's take a look at some of the cool commands you can try out right away.

The Basics

• get a list of all available search shortcuts by typing list or ls
• enter any full URL to go directly to the site, e.g.: http://commandlinefu.com/ or ftp://ftp.mozilla.org/
• add ! in front of any bare URL to go directly to the site, e.g.: !smh.com.au to go to the Sydney Morning Herald
• use g [searchterm] for a plain vanilla Google Search. Or you might prefer to use y, b, ix, or sp instead
• help is available by typing help or man (optionally including the command you want help with as an argument, e.g. help shuffle)

More Examples

• calc 857*2^3: solve simple mathematical formulas
• calc (25+2)==(28-1): test equivalence
• calc ~32.56: round numbers
• rand 550: return a random number between 0-550
• rand site: go to random website
• rand img: show a random image
• rand git: visit a random GitHub project
• watch ninja cat: watch an embedded playlist of YouTube video results for the search term "ninja cat"
• link flint tigers: get a permalink to the command flint tigers (which searches flickr for pictures of tigers sorted by "interestingness")
• fspell sometext: write out sometext with flickr images
• ascii sometext: write out _sometext in ascii art
• where gn: show the keyword and default search addresses for the command gn
• > am Alice in Wonderland: go directly to the first Google search result for the term "Alice in Wonderland" on Amazon.com
• > wpde Turing complete: read the article on "Turing completeness" in the German Wikipedia
• cat engadget.com: displays a text-only version of the webpage at engadget.com
• pop bbc gn yn bn: pop up individual tabs with BBC News , Google News, Yahoo News, and Bing News, all in one command
• pop gim yim bim -t horses: pop up new tabs showing results of an image search for horses on Google, Yahoo, and Bing

Note: to use the pop command you will probably need to set up an exception in your browser's pop-up blocker for yub.js

Search Engines

engines.js

Default search engines are stored in the engines.js file. This contains a wide variety of general-purpose web shortcuts, search engines, news sources and other interesting stuff that demonstrates the basic features of yub.js and should give you an idea of what kinds of shortcuts might be useful for your own needs.

Things you can expect to find in engines.js are: major search engines (Google, Yahoo, Bing... etc) and their various associated products (images, video, maps, news, weather, machine translation), Wikipedia and its various Wikimedia sister sites (Wiktionary, Wikiquote, Wikinews... etc), a selection of major news organizations (BBC, Deutsche Welle, France 24... etc), major webmail providers (Gmail, Yahoo, Hotmail... etc), documentation for several popular scripting languages (Bash, JS, PHP, Python, Ruby), and a bunch of other useful sites and tools (Down For Everyone Or Just Me?, Whois, What Is My Ip?... etc). A more detailed guide can be found in the wiki.

A nice benefit of using yub.js shortcuts is that https is used by default whenever possible (i.e. everywhere that it is supported).

mods.js

All custom links and shortcuts go in mods.js for convenience. This file is entirely optional, so you can drop things in and out of it as you please. You do not need the mods.js file to use yub.js.

The gigantic mods.js file found in the repository is purely an example for the purposes of demonstrating various features of yub.js, such as unicode regex searches, as well as various local search sites and other interesting stuff that you can cherry-pick for your own uses. At 106 Kb / 870+ entries (as of this writing) it also demonstrates that even with a huge list of custom shortcuts, yub.js runs along smoothly without any noticeable decrease in speed.

Some examples of things that have been dumped indiscriminately in the sample mods.js file:

• International and local versions of the default websites in engines.js
  • For example, all (as of this writing) international Google sites (including Google British Indian Ocean Territory and Google Pitcairn Islands...)
• Multilingual versions of most major international news aggregators and news websites (e.g. BBC, CNN, AFP, Deutsche Welle, Google News, etc)
• Āll international eBay and Amazon sites (e.g. ebin for eBay India, or amuk for Amazon U.K.)
• Links to each of the language dictionaries at WordReference.com
  • Note that each language pair has two separate links -- one for each direction. So, use enes for the English-Spanish dicitonary, and esen for Spanish-English; enko and koen for Korean, enfr and fren for French, etc.
• A large (but not complete) selection of Wikimedia editions -- almost 30 major language versions of Wikipedia, Wikinews, Wikiquotes, Wiktionary, etc
• Complete multilingual collection of Global Voices links
• Complete multilingual collection of WikiHow links
• Most of the major Baidu, Sina, Sogou, Kvasir, and Yandex sites (search, images, maps, etc)

Customization

One thing to note is that some really interesting sites have been left out of engines.js and even mods.js in order to keep the default shortcuts as generally useful as possible. But never fear, you can still add them to your mods.js file! Here are some things you might consider adding to customize mods.js:

• Local classifieds: Both Cragslist and Kjiji have fairly straightforward search systems, but they don't offer sitewide search -- you have to choose your location first. Since it wouldn't make sense to prepackage any particular location (or shudder all of them), just create a cl or kj command for your desired location and drop it in mods.js
• Currency conversion: Create a shortcut to xe.com (or another site) with the following parameters:
  • http://www.xe.com/ucc/convert.cgi?Amount=%s&From=[CURRENCY1]&To=[CURRENCY2] (replace [CURRENCY1] and [CURRENCY2] with the three-letter codes for the currencies of your choice)
• Local library catalogue: Create a shortcut to show search results from your local public or school library
• Blog search: Create a shortcut for search results on a blog you read often, or your personal website
• Local newspapers: The wiki will eventually host links to mods.js files for regional newspapers from around the world (so you'll be able to pick up a mods.js file for South African or Thai or Portuguese newspapers), but in the meantime create your own shortcuts to the local and international newspapers you read most frequently -- most websites have their own search function, but if not you can always link to a Google result for the specific site
• If your favourite radio station has an embeddable stream, you can add a link to it in functions.js and have it pop out under the command-line while you do other stuff

Skins

Theming support is available in the form of custom css files loaded through the skin command. Skins are basically just css files (located in the /css folder), and can be loaded by entering the command skin and the name of the skin (there is no need to add the .css extension).

To return to the default skin, just type skin default. To remove all css, use skin nocss. Skins currently don't persist across yub sessions (this would require setting a cookie, which we've managed to avoid so far), but you can change the link/bookmark to your yub.js instance to something like https://dohliam.github.io/yub/?skin%20terminal to always start yub.js with a particular skin loaded.

To make a new skin, just copy one of the existing skin files to a new file e.g. mynewskin.css and customize to your heart's content! (And don't forget to add your custom skins to the skins gallery in the wiki so others can enjoy them!)

Here are some screenshots of the skins that come with yub.js:

default:

terminal:

mountainlake:

rays:

skyline:

nocss:

Installation

Of course you don't need to install yub.js in order to begin using it. For one-off searches you can easily use the latest version of yub.js hosted here on GitHub. Everything is done entirely on the client side, so none of your queries are sent over the network.

You can even use the API to make the GitHub version the default search for your browser. However, if you use the API any commands you enter will be visible (for example, in the GitHub server logs), so you might prefer to set up a local version of yub.js and run it entirely offline (or on your own site).

There is a detailed guide in the wiki on how to make yub.js your default search engine. You can find step-by-step instructions on how to set up yub.js for Chrome/Chromium and Firefox (if you use a different browser and are able to install yub.js, please consider adding the steps you took to the guide).

One thing to consider when installing yub.js whether you'd like to set it up as a keyword search or use it as your default search engine. The benefit of setting it up as your default is that it basically makes your browser's URL bar itself into a web command-line.

API

One of the most useful features of yub.js is its easy-to-use API, which works just as well on a laptop as it does on a server. Just point a link, bookmark, or keyword search at your yub.js URL and add ? plus your commands or search terms to go directly to the result.

Example 1:

• yub.js URL: http://example.com/yub
• command: weather tokyo
• full URL for this command: http://example.com/yub?weather tokyo

Example 2:

• yub.js URL: file:///home/username/yub/index.html
• command: rand site
• full URL for this command: file:///home/user/yub/index.html?rand site

Embedding

You can embed yub.js on any webpage and get a functional web command-line that looks like this:

Just copy the following code and include it anywhere on the page:

<form method="get" action="#" onsubmit="window.location='https://dohliam.github.io/yub/?'+window.yub.value; return false"><img src="yub.gif" />&nbsp;<input id="yub" type="text" size=27 value="yub.js web command-line" autocomplete="off" style="border-style: none none solid; color:gray; font-family:monospace;" onfocus="this.value=''; this.style.color='black'" onblur="if (this.value=='') {this.value='yub.js: enter commands here';this.style.color='gray'}">&nbsp;<input style="visibility: hidden" type="submit" value="" />

There is probably a more elegant way to do this, but after some testing this seemed to be the only way that works in both Firefox and Chrome. Feel free to experiment and open a pull request if you find something better!

Upcoming Features

There are tons of features that have yet to be implemented. As much as possible, planned new functionality and requested features are being tracked in the issue tracker. If you have an idea, go ahead and add it in (or fork the project and shoot over a pull request)!

It would be awesome to see everyone's custom mods.js files -- links to these can be shared in the wiki, though a separate repository is another possibility in the future if the list gets big enough. In the meantime, let me know if you have a mods.js file you'd like to share -- particularly if it's organized around a specific theme (e.g., collections of social media sites, Swedish newspapers, research databases, tools for historians or marine biologists... etc).

Some planned features that are still in the works:

• theming support (skins) done!
• translation support for multiple languages
• command tagging
• more extensive man entries
• jukebox feature (like watch, but for music)
• pipes!

If you'd like to contribute to adding any of these features (or others I haven't thought of), feel free to submit a pull request.

History

A long time ago (2005 to be exact), a groundbreaking website called YubNub was unveiled that allowed users to write their own commands and shortcuts for various web services. The idea of accessing websites with short bash-like commands was quite compelling and actually addictive, and quickly led to all sorts of creative tools like split and gimyim. Along with many others, I created a bunch of commands and used the site quite heavily for a while.

However, there was one thing that never quite made sense -- why would anyone want to filter every single search they did through a(nother) third party website? In any case, as soon Firefox's keyword search functionality became widely known, the allure of using YubNub shortcuts began to fade -- it was easier to just set up local Firefox keywords for most common searches and then use those instead. So a bookmark file containing dozens of former YubNub commands in the form of search keywords traveled from computer to computer, surviving for almost a decade before it became obvious that this system, too, was entirely too clunky, slow and impractical (e.g., access from another computer was a pain, and keeping the list updated across computers was also not pleasant). What was worse, this method also missed much of the exciting non-search command functionality that YubNub offered.

Nine years later, a visit to YubNub revealed that the service is still running, and according to Wikipedia, even boasted over 22,000 user-contributed commands... as of 2008. Looking at the list of commands leads one to the disheartening conclusion that the once awesome service has become swamped by thousands and thousands of spam entries, stifling any remaining sense of community (the social command-line) that was once one of the most endearing things about the site.

Even more disappointing, many of the coolest commands (e.g., split, gimyim) are no longer even functional. Of course, this should not really be all that surprising -- the architecture of the web has changed a lot since 2005. (In the case of split, both because loading websites in frames has stopped being a normal and acceptable thing to do, and also, as demonstrated by gimyim, because both Google and Yahoo -- as well as virtually every other major website -- now actively discourage attempts to load their content from external sites). Bummer.

Yub.js started out as an attempt to get back some of the functionality of the old YubNub command-line in an entirely client-side application that anyone could tweak or adjust to suit their needs and then run on their local machine -- or drop into the cloud or onto a private server and access from anywhere.

Although I had been kicking this idea around idly for years, it always remained something of a pipe dream, since I wasn't even sure if it was possible to do most of the stuff I wanted to do with JavaScript. Eventually I whipped up a little html page to redirect queries to a few common search engines and "yubSearch" was born.

However, it soon became clear that search shortcuts alone were not enough. A simple command to search through the shortcuts list was followed by other commands to print the date and time, show descriptions for each shortcut, and sort text. A calculator was added, and then a stopwatch. As new commands evolved out of bits and snippets of code and workarounds from all over the place, it became almost a challenge to see what could be cobbled together with pure JavaScript alone. It was no longer just about search shortcuts -- and thus yubSearch became yub.js.

Development has proceeded on a strictly itch-scratching basis, with new functionality being added when and as actually needed. From very early on, yub.js became something of its own development environment, and there are built-in reference tools for JavaScript (as well as other popular scripting languages), linters and an internal command creation syntax that have helped to make common development-related tasks much easier.

At some point, yub.js took on a life of its own. While not exactly Turing complete, it became dangerously close when a patch was contemplated to add Eliza as an engine to respond to conversational prompts...

Development

Yub.js continues to be developed in pure JS without the use of frameworks or external libraries. Although many interesting functions could be added using server-side scripting, frameworks, and other bits of whiz-bang heavy coding artillery, the main goals have always been portability and responsiveness -- you can drop yub.js virtually anywhere: a desktop, a server, a ChromeBook, even a mobile phone, and it will work pretty much exactly the same way. This has proven to be a particular lifesaver on mobile devices where even simple searches (let alone anything more sophisticated) can sometimes be incredibly clumsy and frustrating to work with -- and when mobile websites often hide or dumb down basic features like search.

As mentioned above, however, the code has been literally cobbled together out of spare parts without (until very recently) any thought to making it look pretty, let alone standardized or efficient. Nevertheless, everything chugs along at an incredible speed, thanks to relatively small file sizes and the benefits of running entirely on the client side.

Could it be even faster? Absolutely! A lot of work no doubt remains to be done optimizing and prettifying the existing (admittedly quite ugly) codebase. Will the average user notice these improvements? That's harder to say -- after all, the difference between instantaneous response times and those that are half that speed can be pretty hard to discern. Most of the individual tasks that JavaScript is handling at any given time are incredibly trivial (making lists, redirecting to URLs), so speed has rarely if ever been a concern during actual use.

On the other hand, if things that are slower than they need to be bother you on principle, you may want to take a look at the next section.

It Might Not Be For You

• Cloud sync afficionados: If you are still wondering what the point of all this is when you could just use Firefox Sync or sign in to Chrome with your Google Account, then yub.js may not be for you.

• Bookmarks managers: Cloud sync options for almost all major browsers are now ubiquitous, and if not one of those services, you could always backup your bookmarks file on a server somewhere and be done with it. If that works for you, great -- but frustration with these approaches is what led to yub.js in the first place.

• Sticklers for elegant code: As mentioned before, the code is pretty ugly at the moment -- not on purpose, of course, but since every new feature has been added due to some immediately pressing need, kludges and all sorts of brute force inefficient loops abound. That will hopefully change over time as the code is (slowly) refactored. But if ugly code offends you, you may want to avert your eyes.

• Haters of eval: If you believe that eval is evil under any circumstances (even parsing sanitized mathematical expressions)... then you may want to just remove the calculator function from your version of yub.js.

• Seekers of bash.js: Yub.js is not a port of bash into JavaScript. If you are wondering why yub.js doesn't offer a mount command, or have a way to kill processes, or modprobe your mouse driver... you are probably in the wrong place (perhaps you are looking for unixkcd). On the other hand, if you can think of an appropriate metaphor for mount, kill, or modprobe that would make sense on a web command-line, I'd love to hear from you! 😃

Similar projects

• YubNub (The original inspiration for yub.js)
• Inky (Firefox extension)
• Ubiquity (Firefox extension)
• unixkcd) (A commandline for the comic xkcd)
• JSShell (An actual UNIX-style shell written in JavaScript for the browser)

Acknowledgements

Many thanks to Jon Aquino, and everyone who contributed to YubNub in its heyday, for the web-as-command-line metaphor that was the original inspiration for yub.js.

Minified single-page version made using Uglifier for Ruby.

Table of contents generated by https://github.com/dohliam/tocdown.

The random GitHub repo is based on RandomRepo by RyanDavison.

Background wallpapers for various skins:

• "Untitled" by tiltti, released under a CC-BY license (used in the "mountainlake" skin)
• Mountain Monastery Sunrise by Ronan Shenhav, released under a CC-BY license (used in the "rays" skin)
• Hong Kong from Victoria Peak by Robert Lowe, released under a CC-BY license (used in the "skyline" skin)

License

MIT -- see LICENSE file for details.