= Interacting with the shell

== Shell usage

[[connection]]
=== Connection

You need to connect using telnet, SSH or _directly_ to use the
shell.  The last method is a special mode using the JVM input and output.

==== Telnet access

Telnet connection is done on port 5000:

[subs="attributes,specialcharacters", options="nowrap"]
----
(! 520)-> telnet localhost 5000
Trying ::1...
Connected to localhost.
Escape character is '^]'.
   ______
 .~      ~. |`````````,       .'.                   ..'''' |         |
|           |'''|'''''      .''```.              .''       |_________|
|           |    `.       .'       `.         ..'          |         |
 `.______.' |      `.   .'           `. ....''             |         | {crash-version}

Follow and support the project on http://vietj.github.com/crash
Welcome to julien.local + !
It is {localdatetime} now
----

The +bye+ command disconnect from the shell.

==== SSH access

SSH connection is done on port 2000 with the password *_crash_*:

----
juliens-macbook-pro:~ julien$ ssh -p 2000 -l root localhost
root@localhost's password:
CRaSH {crash-version} (http://vietj.github.com/crash)
Welcome to juliens-macbook-pro.local!
It is {localdatetime} now.
%
----

The +bye+ command disconnect from the shell.

==== Native access

A third mode is available for standalone CRaSH usage where it uses the
JVM native input and output. When you run in standalone, CRaSh will be available just after the JVM is launched.

=== Features

* Line edition: the current line can be edited via left and right arrow keys
* History: the key up and key down enable history browsing
* Quoting: simple quotes or double quotes allow to insert blanks in command options and arguments, for instance
+"old boy"+ or +'old boy'+. One quote style can quote another, like `"hi, it's me"`.
* Completion: an advanced completion system is available

== Command usage

=== Getting basic help

The +help+ command will display the list of known commands by the shell.

----
% help
Try one of these commands with the -h or --help switch:

NAME      DESCRIPTION
help      provides basic help
repl      list the repl or change the current repl
cron      cron management
dashboard a monitoring dashboard
date      show the current time
egrep     search file(s) for lines that match a pattern
env       display the term env
filter    a filter for a stream of map
java      various java language commands
jdbc      JDBC connection
jmx       Java Management Extensions
jndi      Java Naming and Directory Interface
jpa       Java persistance API
jvm       JVM informations
jul       java.util.logging commands
mail      interact with emails
man       format and display the on-line manual pages
shell     shell related command
sleep     sleep for some time
sort      sort a map
system    vm system properties commands
thread    JVM thread commands
----

=== Command line usage

The basic CRaSH usage is like any shell, you just type a command with its options and arguments. However it is possible
 to compose commands and create powerful combinations.

==== Basic command usage

Typing the command followed by options and arguments will do the job

----
% ls /
...
----

==== Command help display

Any command help can be displayed by using the -h argument:

----
% help -h
usage: help [-h | --help]

   [-h | --help] this help
----

In addition of that, commands can have a complete manual that can be displayed thanks to the +man+ command:

----
% man help
NAME
       help - provides basic help

SYNOPSIS
       help [-h | --help]

PARAMETERS
       [-h | --help]
           Display this help message
----

== Command pipeline

A CRaSH command is able to consume and produce a stream of object, allowing complex interactions between commands
where they can exchange stream of compatible objets. Such commands are called _pipe_ commands.

=== Pipe commands

A pipe commands is a command that can consume and/or produce two type of objects:

* the _consumed_ type: the type of the object that the command consumes
* the _produced_ type: the type of the object that the command produces

The Java generic declaration notation is used to denote the command capabilities: +<C, P>+, for instance
the _filter_ is a +<Map, Map>+ pipe.

Non pipe command consumes the +java.lang.Void+ type and produces the +java.lang.Object+ type: +<Void, Object>+ . Such
commands will discard any input and can produce any kind of object.

The types consumed and produced by a command are documented in the _STREAM_ section of its manual, let's
read the +system propls+ manual:

----
% man system propls
NAME
       system propls - list the vm system properties

SYNOPSIS
       system [-h | --help] propls [-f | --filter]

STREAM
       system propls <java.lang.Void, java.util.Map>

PARAMETERS
       [-h | --help]
           Display this help message

       [-f | --filter]
           filter the property with a regular expression on their name
----

The system propls_ command is a command that:

* consumes no object (+Void+)
* produces system properties as +<java.util.Map>+ objects with two entries _NAME_ and _VALUE_

Such command is often referred as a _producer_ command as it produces a stream of objects that will
either be rendered in the shell or consumed by other commands.

Other pipe commands are usually _filters_ because they consumes and produces objects, for instance
the _filter_ command consumes +Map+ objects and produces +Map+ objects:

----
% man filter
NAME
       filter - a filter for a stream of map

SYNOPSIS
       filter [-p | --pattern] [-h | --help]

STREAM
       filter <java.util.Map, java.util.Map>

PARAMETERS
       [-p | --pattern]
           format <key>:<value>

       [-h | --help]
           Display this help message
----

This command consumers any map it receives and produces a subset of the maps based on the _pattern_, providing opportunity
for applying other filters down the road.

=== Creating a pipeline

This operation can be achieved with the pipe operator `|` and we can combine the +system propls+ and
the +filter+ command together:

----
% system propls | filter -p NAME:*Hosts

NAME               VALUE
---------------------------------------------------------
http.nonProxyHosts local|*.local|169.254/16|*.169.254/16
socksNonProxyHosts local|*.local|169.254/16|*.169.254/16
ftp.nonProxyHosts  local|*.local|169.254/16|*.169.254/16
----

This work naturally because we have the same type +Map+ shared by the two commands. When the type
does not match, several scenarios can happen, depending on the type declared by the piped command:

* +Void+ : all objects are discarded
* a super type of the produced type : the objects are consumed since they are acceptable by the command
* +org.crsh.text.Chunk+ : the chunk is an object representing some textual data. In this case the object
+toString()+ method is called and the returning string is transformed into a Chunk object

=== Pipeline commands

Here is a quick overview of various commands that can interract with the object pipe

==== Thread

The +thread+ command manipulates +java.lang.Thread+ objects:

* +thread ls+ : produces threads
* +thread interrupt+ : interrupts threads
* +thread stop+ : stop threads
* +thread dump+ : dump thread stacktrace

==== Jul command

The +Jul+ command manipulates +java.util.logging.Logger+ objects:

* +jul ls+ : produces logger objects
* +jul send+ : consumes logger object and sends a message
* +jul tail+ : produces log record objects
* +jul set+ : consumes logger object and sets the log level
* +jul add+ : create new logger and produces them

==== JDBC command

The +jdbc+ command manipulates tables as +java.util.Map+ objects:

* +jdbc select+ : execute a query and produce a stream of map
* +jdbc props+ : display the connection properties as a single map
* +jdbc info+ : describe the database as a stream of map

==== System command

* +system propls+ : produces a stream of map with the current system properties

==== Filter command

Filter maps based on value patterns.

==== Sort command

Buffer a stream and sort it based on keys.

==== JMX command

todo.

==== Egrep command

todo.

==== Jvm command

todo.