pathhandler.js is a mix in to easily add the cd, ls and pwd commands as well as path completion. It has Underscore as its dependency for templating, however since all templates it uses are exposed, they could easily be replaced with a different function that accepts an argument object returns html.

By implementing the functions getNode and getChildNodes, this library adds path traversal, discovery and completion just like a bash shell.

The Path Node

PathHandler deals with files/directories a path node with at least the following two fields:

    name: 'localname',
    path: '/full/path/to/localname'

where name is the name of the node and path is the absolute path to the node. PathHandler gets path nodes as the callback argument for getNode and does not modify it itself, so any additional state required can be attached to the node and be relied on as being part of the node when it is provided to getChildNodes or a template.

The Commands

PathHandler is used to add standard unix directory handling commands and path completion to Josh.Shell.


Prints the current directory, as defined by pathhandler.current.

ls [path]

Prints out the listing of all childNodes of the node represented by path. If path is not specified, pathhandler.current is used instead.

cd [path]

Changes pathhandler.current to the node found at path, if one could be found. If path is not specified, pathhandler.current is used instead, resulting in a no-op.


Each template is expected to a function that takes a data object and returns html. The default templates are built with _.template but any templating system can be used as long as follows the same behavior.


Called when getNode returns null as its callback argument.



Called to generate output for a successful ls cmd.



Called to generate output for pwd cmd.



Called to generate the new prompt after any cmd attempt (including after completions).




Contains the current directory. It has to be initialized before activating the shell, since on activation, getPrompt will be called by the shell and requires current to be set to display the prompt. Could be changed manually, but generally is changed as a result of calling cd.


Contains the path completion handler used by PathHandler. Exposed so that other commands added that work on paths, can use it as their completion handler. It is used for the ls and cd commands. The only assumption it makes about paths is that they are separated by /.

Path completion is done by first finding the nearest node, i.e. if a trailing slash is found, it calls getNode with the path, otherwise it will call getNode and upon receiving null, will take the subpath to the nearest slash and call getNode again. If a node is found in either scenario, it then calls getChildnodes to get all all children, i.e. the possible completions and in turn call shell.bestMatch with any partial path after the slash and the list of possible child node names.


Contains a wrapper around pathCompletionHandler that replaces the default completion handler of the shell, so that a completion event without a known command can determine whether to complete as a command name or a path.


Contains the templates described above.


new Josh.PathHandler(shell, config)

Create a new path handler and attach it to a shell instance.

getNode(path, callback)

This method is called with a path and a callback expecting a path node returned if the path is valid. The default implementation always calls callback with null. This is where custom path resolution logic goes and where path nodes are constructed.

getChildNodes(node, callback)

This method is called by the pathCompletionHandler after resolving a path to a node via getNode and expects its callback to be called with an array of pathnodes.


This method is called each time the prompt needs to be re-rendered, which in turn calls templates.prompt with pathhandler,current. Could be replaced for custom prompt behavior beyond altering the template.

Internal Dependencies


External Dependencies