svn commit: r1788377 - /felix/site/trunk/content/documentation/subprojects/apache-felix-gogo.mdtext

[gn...@apache.org]

Author: gnodet
Date: Fri Mar 24 08:32:01 2017
New Revision: 1788377

URL: http://svn.apache.org/viewvc?rev=1788377&view=rev
Log:
[FELIX-5595] Improve documentation of felix gogo shell

Modified:
    felix/site/trunk/content/documentation/subprojects/apache-felix-gogo.mdtext

Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-gogo.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-gogo.mdtext?rev=1788377&r1=1788376&r2=1788377&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-gogo.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-gogo.mdtext Fri Mar 24 08:32:01 2017
@@ -1,32 +1,195 @@
 Title: Apache Felix Gogo
 
-Apache Felix Gogo is a subproject of Apache Felix implementing the OSGi RFC 147, which describes a standard shell for OSGi-based environments. See [RFC 147 Overview]({{ refs.rfc-147-overview.path }}) for more information.
+Apache Felix Gogo is a subproject of Apache Felix implementing a command line shell for OSGi. It is used in many OSGi runtimes and servers (Felix distro, Eclipse IDE, Apache Karaf, ...).
 
-## Using Gogo with the Felix Framework
+## Overview
 
 The Gogo subproject consists of three bundles:
 
-1. *runtime* \- implements the core command processing functionality.
-1. *shell* \- provides a simple textual user interface to interact with the command processor.
-1. *command* \- implements a set of basic commands.
-
-As of the Apache Felix Framework 3.0.0, Gogo is included as the default shell in the framework distribution. To use it, you just start the framework like normal:
-
-
-    $ cd felix-framework-3.0.0
-    $ java -jar bin/felix.jar
-    _______________
-    Welcome to Apache Felix Gogo
-    
-    g! lb
-    START LEVEL 1
-       ID|State      |Level|Name
-        0|Active     |    0|System Bundle (3.0.0)
-        1|Active     |    1|Apache Felix Bundle Repository (1.6.2)
-        2|Active     |    1|Apache Felix Gogo Command (0.6.0)
-        3|Active     |    1|Apache Felix Gogo Runtime (0.6.0)
-        4|Active     |    1|Apache Felix Gogo Shell (0.6.0)
-    g! 
+- *runtime* \- implements the core command processing functionality.
+- *command* \- implements a set of basic commands.
+- *jline* \- Advanced textual user interface with features like completion and colors
+- *shell* \- provides a simple textual user interface to interact with the command processor.
+
+## Working with the sources
+
+You can find the [sources on apache svn](https://svn.apache.org/repos/asf/felix/trunk/gogo/) there is also [a mirror at github](https://github.com/apache/felix/tree/trunk/gogo).
+
+Clone
+	git clone https://github.com/apache/felix
+
+Build
+	cd gogo
+	mvn clean install
+
+## Using Gogo with the Felix Framework
+
+Gogo is included as the default shell in the felix framework distribution. To use it, you just start the framework like normal:
 
+	$ java -jar bin/felix.jar
+	_______________
+	Welcome to Apache Felix Gogo
+	
+	g! 
 
 Gogo shell integration in the framework distribution is also discussed in the [framework usage document]({{ refs.apache-felix-framework-usage-documentation.path }})
+
+## Built in shell features
+
+- TAB 
+
+   Completion for commands and parameters
+   
+- Cursor left, Cursor right
+
+   Edit inside current line
+   
+- Cursor up, Cursor down
+
+   Scroll through history
+   
+- Ctrl-C
+
+   Interrupt execution of current command
+   
+- Ctrl-D
+
+   Exit the shell
+   
+- Ctrl-R
+
+   Search in history
+   
+- *\[command1\]* | *\[command2\]*
+
+   Pipe output of command1 as input of command2
+
+## Basic commands
+
+- cat *\[URI\]*
+
+  Read URI and print to stdout
+  
+- cd *\[path\]*
+
+  Change working directory
+
+- diag *\[bundleid\]*
+
+   Shows why a bundle is not working
+
+- help
+
+   Show the available commands
+   
+- help *\[command\]*
+
+   Shows detailed help about a command
+
+- head *\[bundleid\]*
+
+   Print bundle headers
+   
+- history
+
+   Shows the history of executed commands
+
+- inspect capability service *\[bundleid\]*
+
+   Lists all services provided by a bundle
+   
+- inspect requirement service *\[bundleid\]*
+
+   Lists all services required by a bundle
+   
+- install *\[URI\]*
+
+   Install a bundle from file or URI
+   
+- lb
+
+   List bundles
+
+- *\[command1\]* | less
+
+   Show output of command1 in a paged view
+   
+- less *\[file\]*
+
+   Show file in a paged view
+   
+- ls *\[directory\]*
+
+   Show directory contents
+   
+- start *\[bundleid\]*
+
+   Start the given bundle
+
+- stop *\[bundleid\]*
+
+   Stop the given bundle
+   
+- tac
+
+   Capture stdin as string and optionally write to file
+   
+- tail *\[file\]*
+
+   Shows the last lines of a file. Using -f allows to follow the file changes.
+
+- uninstall *\[bundleid\]*
+
+   Uninstall given bundle
+   
+## Changing shell colors
+
+The colors of the command shell cane be adjusted by setting a property in an init script or directly on the shell.
+
+HIGHLIGHTER_COLORS = "rs=35:st=32:nu=32:co=32:va=36:vn=36:fu=94:bf=91:re=90"
+
+The property above forms a map from highlight type to ANSI color code.
+
+These are the highlight types
+
+- rs : Reserved words
+- st : Strings
+- nu : Numbers
+- co : Constants
+- va : Variable
+- vn : Variable name
+- fu : Function
+- bf : Bad function
+- un : Unknown
+- re : Repair
+
+The colors of the ls output can be adjusted using
+
+LS_COLORS = "dr=1;91:ex=1;92:sl=1;96:ot=34;43"
+
+The color types are these:
+
+- dr : Directory
+- ex : Executable
+- sl : Symbolic Link
+- ot : Other
+
+Last but not least grep can also be adjusted
+
+GREP_COLORS = "mt=1;31:fn=35:ln=32:se=36"
+
+Types:
+
+- mt : Hits in the text (sets both ms and mc)
+- ms : Matching text in selected line
+- mc : Matching text in context line
+- fn : File names
+- ln : Line numbers
+- se : Selected lines
+- sl : Whole selected line
+- cx : Context lines
+- rv : If set and match is inverted, the meaning of sl and cx is inverted
+   
+## Origin in RFC 147
+ 
+Gogo is based on the OSGi RFC 147, which describes a standard shell for OSGi-based environments. See [RFC 147 Overview]({{ refs.rfc-147-overview.path }}) for more information. Unfortunately this RFC was never made a standard.