maddiem4/broco

Browser console, a pseudo-terminal for the browser that uses RequireJS and prototypes.

broco

Browser console, a pseudo-terminal for the browser that uses RequireJS and prototypes.

For a demo, see http://campadrenalin.github.io/broco/.

AMD modules as commands

Broco commands are AMD/RequireJS modules. You can see good templates for how to do this in /src/modules/. Such a module should return a class definition/constructor, which will be instantiated with an instance of broco/logic/console.

The following attributes are considered special:

• _dir - Filters the attributes that are visible for the "get" command. This allows modules to be serialized to JSON without getting into cyclic reference errors, since a lot of modules contain a reference to the console, which contains the modules object... etc.
• _help - Array of lines to be used as static documentation information by the "help" command.
• process(args, response) - A function that takes an argument array and a broco/ui/response object (think STDOUT).

Available modules

While the downstream usefulness of broco is that you can write your own domain-specific modules, we provide some built-in, that you can choose to allow or disallow, defer loading, etc.

• get - Retrieve a variable value stored by the console. Try get .!
• set - Store a variable value. For fun and profit, try changing the 'motd' message and running the motd command again.
• motd - Message of the Day. Very basic demo module that simply spits out some static text.
• fullscreen - Bring the console into fullscreen mode, rather than being locked to an arbitrary height.
• help - Get documentation on stuff. You really should provide documentation on your custom modules: help foo is the idiomatic equivalent of man foo or foo -h.
• load - Load more modules. API is a bit analogous to console.depend(). You don't have to load everything when you first hit the page! Optional features can be optionally used, even at the consumer level. Plus, if you do something hamhanded with the set command, you can reload broken modules and make them good-as-new.

Missing features

Boy, this would be a long list if we were trying to be comprehensive (which is what issue trackers are for, ya turkey). But the highlights are:

• Up and down arrows to seek through history of commands
• Better themeing support (maybe use SASS to generate CSS?)
• Tabs
• Pipes / filtering
• Output collapsing / ability to output multiple switcheable representations of an object

Efficiency

When building an app, it makes sense to use the r.js optimizer to squish it all into a single file - and therefore, a single request. At least for everything you need on page load... optional modules are fine to trickle in later on-demand.

As a demo of this, we include a makefile that builds an "optimized" version of the normal demo page. This will load quite a bit faster over bad connections, when the scripts are not already cached.

Other notes

This is not stable software. The APIs are incredibly liable to change - in fact, the process() API will almost certainly have to change in some way to support piping and filtering. Build on broco at your own risk. However, long-term, it's exactly those builders that we want to empower and cheer on. So if you have a cool use for this software, the author(s) are here for you.

Feel free to contribute and bikeshed, if you care about the source, which you should. At some point I'll find a good way to add financial support to the project - tip4commit looked good until the entire FOSS ecosystem decided to crucify it, and I'd rather not sign up for a service that's about to die. Bitter? Me? Nawwwwww.

broco's Issues

README documentation

This won't be too useful for other projects until there's proper documentation on how to use it. Which should go in the README file.

There is a danger here of overspecifying, or even just jumping too quickly into public use, since the module APIs are subject to change and expansion right now. But release early, release often. As long as people are aware of how shaky the ground is, we should be fine.

Tab completion

The tricky part here is the protocol - tab completing a module name is easy, interacting with a module to provide tool-specific tab completion (in a way that third-parties will enjoy supporting) is another matter entirely.

Multiple spaces don't display in prompt

Not sure yet why this is a problem - possibly the wrong white-space CSS - but if you put multiple spaces into the prompt, it shows up as one, at most.

Document more modules

Pretty much every existing module already has documentation, it's just not exposed to the 'help' module. Let's fix that.

Logo

For the Github Pages demo and branding in general, it would be cool to have a logo at some point. I'm gonna design a logo at some point in Inkscape, in the form of broccoli. Eat your veggies, kids! This isn't a high-priority ticket, but on the other hand, it might make for a nice relaxing break from a day of writing code.

Support for input modes like vi and emacs

This would be a large project, and part of broco that would be considered optional. However, vi mode is cool, and I'm sure there are people who take advantage of emacs.

What we really need is a part of the "prefs" structure devoted to keyboard shortcut handling and, in the case of vi, doing so statefully.

Tabs

Add the ability to have multiple broco tabs, sharing data but with distinct output logs. The primary use case is being able to grep through another tab's logs, without dirtying them up further.

Support up and down arrow movement in console

This is really useful for quickly repeating previous commands, with variations as necessary.

Ability to switch between "normal" and fullscreen mode live

This basically involves changing the way that fullscreen mode works - using a class instead of a CSS include. However, fullscreen support will still be a separate CSS file so that downstream consumers can omit fullscreen capability entirely, by serving neither the module nor the CSS.

This lets us condense demo*.html down into a single index.html file, which we can use in a gh-pages branch.