# Using JythonShell

This chapter describes how to use the Jython Shell created by LeoUser.

# Autocompleter Actions

- Up-Down Arrow moves the selection up or down.
- Tab inserts the current selection.

The completion list shows the best prefix entered after the '.' Any other key withdraws the autocompleter.

# Keystrokes

Enter
  Processes the current line from the prompt to the end, regardless of where the cursor is.
Ctrl Enter

  This keystroke has two meanings:

  1. process the current line with a ':' appended to the end of it, regardless of where the cursor is. This is the behavior if there is character data on the line.
  2. If the line is pure whitespace, then the line is interpreted as a '' string with a length of 0.

# Alt Slash: Dynamic Abbreviations

Executing will dynamically expand a prefix to matching words already entered within the interpreter. For example: cactus cac( keystroke ) will expand cac to cactus. This will cycle through all matches to cac within the buffer upon repeated execution.

Ctrl A
  Moves current position to the end of the prompt.
Ctrl E
  Moves current position to the end of the line.
Ctrl K
  Removes all text from current position to end of the line.
Ctrl N
  Start typing, and then use this keystroke to search downwards only through the history items that match what you've typed so far. If you use this keystroke at a blank prompt, they just behave like normal arrow keys.
Ctrl P
  Start typing, and then use this keystroke to search upwards through only the history items that match what you ve typed so far. If you use this keystroke at a blank prompt, they just behave like normal arrow keys.
Ctrl R
  Opens a search prompt. Begin typing and the system searches your history for lines that contain what you ve typed so far, completing as much as it can.
Ctrl T
  Places triple quotes around the text on the current line.
Ctrl Z
  Suppresses the current output for the duration of the execution statement. This is useful in cases where there is a tremendous amount of output occurring and the user decides that he no longer wishes to see all of it. For gigantic outputs, this can be a shell saver.
Delete
  Removes all text from the prompt to the end of the line.
Down
  Moves the current line down one item in the history. By moving, this means the current line is replaced with history item.
Up
  Moves the current line up one item in the history By moving, this means the current line is replaced with history item.

# Object Introspection

Typing a reference name followed by a ? will create a object view which gives the user a variety of information about the Object in question. Example:

    a = 'meoooowwww'
    a? # Upon Enter, a panel will appear below showing Object information.

# System access

Typing ! at the command prompt followed by the system command you wish to execute will start the command as a process and return a JPID for the process that can be manipulated by the magic command set.

# Magic Commands

Entering one of the following commands will cause its corresponding command to execute:

## %alias anAlias

`%alias` anAlias defines alias name as an alias for cmd. Afterwards, typing alias name params will execute the system command cmd params (from your underlying operating system). Aliases have lower precedence than magic functions and Python normal variables, so if foo is both a Python variable and an alias, the alias can not be executed until you remove the Python using `del foo`.

## %autocall

Toggles autocalling off and on. Autocalling is the ability to do something like:

    dir a

instead of dir( a ).

## %autoindent

Toggles autoindenting off and on.

## %bg

Runs a method/function in a background thread. For example:

    %bg doit()

This executes doit in a thread. The status of the operation can be seen by looking at the jobs object:

    jobs.status()  #Prints the status of the jobs.

Alternatively you can access the status like so:

    jobs[jobnumber].result

jobnumber is printed out when the method/function is about to execute. The result will be the return value of the method/function or it will tell you the job isn't finished yet.

## %cd

Changes the current working directory of the Jython Shell. `..` signifies the parent directory. Absolute and relative paths are allowed.

## %clean

Destroys all JPIDs.

## %clear

Clears the shell of all text and starts over with a fresh prompt.

## %cwd

Shows the current working directory of the Jython Shell.

## %cwd aReference

Sets the reference to a java.io.File instance representing the current directory.

## %deserialize aReference

Deserialize an Object stored on disk into the reference.

## %ed

Same as %edit.

## %edit [options] [args]

Brings up the Jython Shell editor and executes the resulting code.

This command allows you to conveniently edit multi-line code right in your JythonShell session. If called without arguments, `%edit` opens up an empty editor with a temporary file and will execute the contents of this file when you close it (don t forget to save it!). Options:

`-p` | Calls the editor with the same data as the previous time it was used, regardless of how long ago (in your current session) it was.
`-x` | Suppresses execution of the edited code upon exit. This is mainly useful if you are editing programs which need to be called with command line arguments, which you can then do using %run.

If args are given, the following possibilities exist:

- The arguments are numbers or pairs of colon-separated numbers, e.g., `1 4:8 9`. These are interpreted as lines of previous input to be loaded into the editor. The syntax is the same of the %macro command.
- If the argument doesn't start with a number, it is evaluated as a variable and its contents loaded into the editor. You can thus edit any string which contains python code (including the result of previous edits).

## %env

Prints all environment variables.

## %hist [-n] [n1] [n2]

Prints all or part of the history. If given, the `-n` argument signifies that line numbers should not be printed out.

%hist [ -n ]
  Prints the total history or the last 40 items in it.
%hist [ -n ] n1
  Prints the last n1 items in the history.
%hist [ -n ] n1 n2
  Prints the items from index n1 to index n2.

## %kill n

Destroys JPID n.

## %ls

Shows the contents of the current working directory.

## %ls aReference

Shows a java array of File instances. For example:

    %ls a # a now holds a java array of File instances

## %lsmagic

Returns the current available set of magic commands.

## %macro aMacro

Defines a macro that can be executed by using the name given. For example:

    %macro macex 9:10 11 12:13 4

creates a macro called macex and puts line 9-10, 11 12-13 and 4 from the history into it Hence entering macex and typing enter will cause those lines to rexecute.

To see the contents of the macro type: `print macroname`. To remove a macro type: `del macroname`.

## %magic

%magic
  Prints out the description of the magic commands.
%magic %magiccommandname
  Prints the usage/description of the given magic command.

## %p

Same as 'print'.

## %pdb

%pdb
  Starts the Pdb debugger.

%pdb filename

> Runs the file under Pdb in the shell.

%pdb [on|1|off|0 ]

  Toggles automatic startup of Pdb on an exception. Examples:

      %pdb on  --> now on
      %pdb off --> now off
      %pdb 1 --> now on
      %pdb 0 --> now off

## %pdoc anObject

Prints out the doc string of the passed in object if one can be found, otherwise does nothing.

The object may be a module, a method, an object, etc.

## %pfile obj

Attempts to locate the source file of the passed in object and displays the contents of the source in the shell.

## %pinfo aReference

An alias for the ? object viewer syntax. If the references is valid, a widget containing info on the reference will appear.

## %prun statement

Executes a statement entered on the same line in the profile module.

## %ps

%ps
  Prints out all JPID's the JythonShell has collected.
%ps aReference

  Puts a java Set of Processes in the reference. For example:

  > %ps a #a now holds a Set of Processes.

## %r

Repeats the last input.

## %rehash and %rehashx

%rehash
  Updates the alias table with all entries in $PATH. This command does not check execute permissions or whether the contents of $PATH are truly files (instead of directories or something else).
%rehashx
  Updates the alias table with all executable files in $PATH. This command does explicitly check that every entry in $PATH is a file, so it is slower than %rehash.

## %reset

Resets the namespace by removing all names defined by the user. Input/Output history remain in case you need them.

## %run [-n -i -t [-N n] -d [-b n] -p [profile options]] file [args]

Runs the named file inside IPython as a program. Options:

-n:

  Suppresses setting `__name__` to `__main__`. Instead, sets `__name__` to the file's name without extension (as Python does under import).

  This allows running scripts and reloading the definitions in them without calling code protected by:

      if __name__ == __main__:

-i:
  Runs the file in JythonShell's namespace instead of an empty one. This is useful if you are experimenting with code written in a text editor which depends on variables defined interactively.
-t:
  Prints timing information at the end of the run.
-N n:
  If -t is given this option indicates how many times you want the script to run. `n` must be an integer. The final timing report will include total and per run results.

## %save filename n1:n2 n3:n4 ... n5 .. n6 ...

This command uses the same syntax as %macro for line extraction, but instead of creating a macro it saves the resulting string to file whose name is given. It ensures the filename ends with a .py extension, and it asks for confirmation before overwriting existing files.

## %sc [options] varname=command

Runs the given command using `command.getoutput()` and updates the user's interactive namespace with a variable called varname containing the value of the call. Your command can contain shell wildcards, pipes, etc. The `=` is mandatory, and the variable name must be a valid Python identifier. Options:

-l:
  List output. Splits the output on newlines into a list before assigning it to the given variable. By default the output is stored as a single string.
-v:
  Verbose. Prints the contents of the variable.

## %see

%see n
  Shows any output JPID n has collected.
%see n aReference
  Places any output JPID n has collected in the reference.

## %send n aReference

Sends the reference as input to JPID n.

## %serialize aReference

Saves the object referenced by reference as a serialized Object.

## %swing aReference

Places the reference into the editor if the reference is a JComponent subclass. Useful for quick gazing of what a Swing component looks like.

## %sx aCommand

Runs the given command using commands.getoutput(), and returns the result formatted as a list (split on). The output is stored in ipython's regular output cache Out[N] and in the N automatic variables.

## %threads

Shows the threads running and the state they are in. Selecting a thread shows the thread's stack.

## %unalias anAlias

Removes the given alias.

## %url ref aUrl

Loads data from a url into a reference. For example:

    %url a http://python.org

take the data at `http://python.org` and places it in ref.

## %wait n

Suspends the JythonShell until JPID n has finished.

## %who

Prints the list of identifiers that have been defined interactively.

## %who_ls

Returns a sorted list of all interactive variables. If arguments are given, only variables of types matching these arguments are returned. Examples:

    %who_ls
    %who_ls str int  #this prints out variables whose type is str and int

## %whos

Prints a table of identifiers that have been defined interactively.

## %xslt ref1 ref2 ref3

Transforms reference ref2 with the stylesheet in ref1 putting the result in ref3.

# A Note on JPIDs and the CWD

JPIDs are not PIDs of the OS. They are a system by which the JythonShell can keep track of Processes created by it, and means by which the user can manipulate those Processes.

The CWD does not indicate what the process is working in. It is intended to function with the Magic Commands. This system does not interoperate with java.io.File or Jython open. To achieve interoperability the user should use the magic command of the form:

    %cwd reference

This will place a java.io.File in the reference. The File instance is a copy of the CWD File and will allow the user to open, write, create, close streams and such in the JythonShell's CWD