hsh User Manual

Copyright (C) 2010 Alexander Taler (dissent@0--0.org)
This file is part of hsh.
hsh is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
hsh is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with hsh. If not, see http://www.gnu.org/licenses/ .

Contents

  1. Introduction
    1. Installation
    2. General Usage
  2. Display Elements
    1. Input Area
    2. Job Output View
    3. Job List Views
  3. Command Line Syntax
    1. Prog
    2. Glob Expansion (*,?)
    3. Environment Variables ($)
    4. Named Directories (~)
    5. Job Reference (%)
    6. \ Escapes
    7. Quoted Tokens
    8. etc.
  4. Configuration
  5. Trouble Shooting
    1. Facilities
    2. Common Issues

Introduction

hsh is the {Happy|Human|History} shell, a command-line driven user interface to your system. It is inspired by the traditional shells (Bourne shell, C shell etc.) but replaces the scrolling terminal style output with a full-screen curses interface.

The interface consists of two main areas, the input area occupying the bottom few lines, and the main view above. The main view may display one of a variety of different views, including job output, job lists, or error messages, while the input area is always visible. The user may switch focus between the main view and the input area, as identified by the location of the cursor. The effects of keystrokes is different depending on the location of focus. The interface is dynamic, and will update automatically according to events such as changes to running jobs or user keystrokes.

Installation

hsh has a very simple manual installation. The src and doc directories may be placed anywhere on the filesystem. The src/hsh.bin script is then used to start hsh. A .hsh directory will be created in the user's home directory.

General Usage

Keystrokes in curses are a funny thing, and hsh is restricted by how curses does things. Throughout this document keystrokes are specified using a keyname, which can be a case-sensitive letter, a single special character, like $, a multicharacter special key name like F1 or PgUp. Additionally a C- may be prepended to indicate that the control key is held while typing the character, or a M- to indicate that the Meta or Alt key is held while typing the character, or Escape was typed immediately prior to it. For example the basic editing keystrokes (other optional setups will be added) are defined as:

C-f or Right Move forward one character along the line.
C-b or Left Move backward one character along the line.
C-a Move to the beginning of the line
C-e Move to the end of the line
F1 or C-h Switch to the welcome/help page.
F2 Switch to the job output view.
F3 Switch to the list of session jobs.
F4 Switch to the list of running session jobs.
F5 Switch to the command history.
F6 Switch to the list of all jobs.
F10 Switch to the last exception view.

Display Elements

Input Area

The input area is at the bottom of the screen, and is where you type your commands for launching jobs. By default the input area has five lines of text, with the following uses:

The cursor position is restricted to the single line of input text.

In addition to character entry and standard editing keystrokes, the following keystrokes are accepted:

Up Move back one row in history
Down Move forward one row in history
C-c Clear the currently typed command. Don't run it, but save it in history.
Tab or C-i Complete what is currently being typed as much as possible.
Enter or C-m or C-j Execute the currently typed command, creating a new job.
PgUp Move the main view up one page.
PgDn Move the main view down one page.

Job Output View

This is a main view which contains the output of a single job. The top lines contain information about the job, and the rest of the view contains the job's output. When the output is larger than the available area the cursor keys can be used to change the viewed area.

By default the header line colours are white on blue, and they contain the following information:

  1. Line 1: context (user@host:directory) and unexpanded command
  2. Line 2: expanded command
  3. Line 3: job id, process id and state - output index - input mode - tail modee

The output area shows text in three different colours, white text is for stdout, red text is for stderr, and yellow text is for manually entered stdin (described just below). By default the top of the output is shown when the job is loaded, and the user needs to manually move the output to see the bottom. However, tail mode may be enabled to cause the output view to constantly update so that the end of the output is visible.

When a job is started, stdin is left open, and the job view may be used to manually send job to the process's stdin. Two input modes are supported, 'character' sends input to the process a character at a time, and 'line' allows editing of each line and sends input only when enter is pressed. Additionally, stdin may be closed explicitly. This is useful for interactive processes, such as shells, or those which prompt for information.

Full screen curses applications are handled differently. hsh recognizes that the process wants control of the terminal by identifying escape sequences in the output and marks it as being in 'exclusive' mode. When a job requiring exclusive mode receives the focus, hsh relinquishes the terminal and allows the user to interact with the process directly. You can then return to hsh by terminating the process, or typing C-z. (C-z may not work correctly if hsh is running inside another shell.)

In addition to the standard movement keystrokes, the following keystrokes are recognized in the job output view:

M-i Cycle input mode. Switches between 'silent', 'line' and 'character'.
M-c Close stdin.
M-t Toggle tail mode
Enter Submit a line in 'line' input mode.

Job List Views

The job list views show a list of jobs, excluding their output. There are several such views, and more may be configured if desired. The default ones are: the session list which contains all jobs executed in this session; the running jobs list which shows all jobs created in this session whose processes are still alive; the command history which shows just the commands and includes jobs which were never executed; and the job history list which shows all jobs executed in this an other sessions.

A more restricted set of movement keys are supported, so that the cursor highlights a single job. (The highlighted job is not necessarily the same as the job currently in the job output view.)

The session list and running jobs list show the execution context, unexpanded command job id and status for each job, while the command history shows just the job id and unexpanded command.

In addition to movement keystrokes, the following keystrokes are supported:

Enter or C-m or C-j Within session list and running jobs list, this shows the highlighted job in the job output view. Within command history it copies the highlighted command to the input area.
Delete or Backspace or C-d Only in session list this deletes the highlighted job.
Command Line Syntax

hsh's command line syntax is still very young and not fully developed. I expect it to depart from that of other shells, since it will not be a programming language. Following the norms for process launching, the command line generates a list of parameters, the first of which is the program to execute, the remaining ones intended to govern the programs operation. There are additional shell syntax tokens to complicate this.

Parameters are the coarsest level of separation on the command-line, and are delimited by whitespace.

Prog - the first element

The first element of the command line specifies the program to run. If this starts with a . then the program will be searched for relative to the cwd directory. If it starts with a / then it will be searched for absolutely withing the filesystem. If it starts with a + then it will be searched for as a builtin only. Otherwise, it will be searched for relative to all entries of the PATH environment variable.

This differs from other shells in the handling of prog names containg a /, but not starting with a / or ., eg imagemagick/mogrify. hsh will search for such things relative to the path, while other shells will search for it relative to the cwd.

Glob Expansion (*,?)

Within a parameter the '*' and '?' cause the text to be matched against filenames, searching from the current directory. '*' matches 0 or more characters, while '?' matches exactly one character. If multiple filenames match the pattern, then it will expand to multiple parameters, and if no filenames match, it will expand to nothing.

Environment Variables ($)

A '$' specifies an environment variable expansion. The name of the variable may optionally be enclosed in braces ('{' and '}'), if not it terminates on the first non-alphanumeric, non-'_' character. In the executed command this will be replaced by the value of the environment variable. This syntax is intended to duplicate that of other shells.

Named Directories (~)

A '~' specifies a named directory expansion, and is followed by the name of the directory. The name may be optionally enclosed in braces ('{' and '}'), and if not terminates on the first non-alphanumeric, non-'_' character. In the executed command this token is replaced by the user's home directory. If no name is given, the current user's home directory is used. This syntax is intended to duplicate that of other shells.

Job Reference (%)

A '%' specifies a job reference expansion, and differs greatly from other shells. It can be used to access the output, input and pid of the job. The reference has the following syntax:

  '%' ['{'] [ job-id ] job-field [ ',' job-field ]* ['}']

job-id: optional numerical job id, defaulting to the currently visible job.
job-field: specifies what to expand. Multiple job-fields may be specified separated by commas, which will result in an expansion to multiple parameters. Possible values of job-field are:

Some typical examples:

kill %p Send the term signal to the currently visible job, if it's running.
ls src/hsh
egrep -v '\.pyc$' %fo
Look at the directory listing, then remove all files ending with '.pyc'.
sed 's/^\([^:]*\):.*/\1/' /etc/passwd
finger %to
Get login information for all system users.

\ Escapes

The \ character can be used to 'escape' the next character, indicating that it should be taken literally and not subject to any special interpretation by hsh, including any expansions, or parameter splitting in the case of whitespace.

Quoted Tokens

Two types of quoted tokens are supported, which are useful to simplify entry when multiple characters must be entered without special interpretation. Text surrounded by double quotes ('"') will not be split on whitespace into multiple parameters. Text surrounded by single quotes (''') will not be split on whitespace, and additionally will not be subject to any expansion.

etc.

More things will definitely be added to the command-line syntax in the future.

Configuration

The user level configuration has not yet been defined. Keybind lists and visual configuration files exist in the source code, and the user configuration will follow this mechanism. It is acceptable to modify these files currently in the installation, although this will create difficulty in managing the source. This area is high priority to address, which is why this documentation section was created. :)

The source code files of interest are hsh/curses_display/keybinds.py and hsh/config.py.

It is expected that many configurable options will be added.

Trouble Shooting

Facilities

hsh provides several facilities for tracking down problems:

Unusual events or user errors can trigger an alert message on the bottom line of the display.

Exceptions in the main thread are caught and displayed in the Exception View. hsh continues to run after the exception, although its runtime integrity may be compromised. The exception view is available on F10 by default. Try running +cause_internal_error for a harmless look at the exception view.

A log file is created as ~/.hsh/debug.log, which includes various debugging information, most importantly the stack traces of any logs.

The +debug_dump builtin can be used to examine internal data structures using python code directly. (This facility could do with some improvement.)

Common Issues

Sometimes (particularly during development) a job's output will stop appearing. This is typically due to an error in the job's output processing thread. Take a look in the debug.log file for any exception traces from the processing thread. (This issue really needs an alert message.)