karaf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbono...@apache.org
Subject svn commit: r1545391 - /karaf/trunk/manual/src/main/webapp/users-guide/using-console.conf
Date Mon, 25 Nov 2013 20:20:29 GMT
Author: jbonofre
Date: Mon Nov 25 20:20:28 2013
New Revision: 1545391

URL: http://svn.apache.org/r1545391
Log:
[KARAF-2496] Add documentation about subshell and completion mode

Modified:
    karaf/trunk/manual/src/main/webapp/users-guide/using-console.conf

Modified: karaf/trunk/manual/src/main/webapp/users-guide/using-console.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/using-console.conf?rev=1545391&r1=1545390&r2=1545391&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/using-console.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/using-console.conf Mon Nov 25 20:20:28
2013
@@ -2,54 +2,309 @@ h1. Using the console
 
 h2. Viewing available commands
 
-To see a list of the available commands in the console enter
+To see a list of the available commands in the console, you can use the {{help}}:
+
+{code}
+karaf@root()> help
+COMMANDS
+bundle
+bundle:capabilities               Displays OSGi capabilities of a given bundles.
+bundle:classes                    Displays a list of classes contained in the bundle
+...
+{code}
+
+You have the list of all commands with a short description.
+
+You can use the tab key to get a quick list of all commands:
+
 {code}
-help
+karaf@root()> Display all 280 possibilities? (y or n)
+...
 {code}
 
-This will show the list of all karaf commands together with a short description.
+h2. Subshell and completion mode
 
-The list of all karaf commands and their usage is also available in the [Commands section|/commands/commands].
+The commands have a scope and a name. For instance, the command {{feature:list}} has {{feature}}
as scope, and {{list}} as name.
 
-h2. Tab completion
+Karaf "groups" the commands by scope. Each scope form a subshell.
 
-The Karaf shell offers Tab completion at almost any place in the shell. So another way to
see all commands is to {{<tab>}} key at the empty prompt.
+You can directly execute a command with its full qualified name (scope:name):
 
 {code}
-karaf@root> Display all 208 possibilities? (y or n)
-add-role                            add-url                             add-user        
                   addbundle
-addfilter                           addregion                           append-property 
                   bundle:capabilities
-bundle:headers                      bundle:info                         bundle:install  
                   bundle:list bundle:refresh
+karaf@root()> feature:list
 ...
-karaf@root>
 {code}
 
-The {{<tab>}} key toggles autocompletion anywhere on the line, so if you want to see
the commands in the {{osgi}} group, type the first letters and hit {{<tab>}}.
-Depending on the commands, autocompletion may be available for options and arguments too.
+or enter in a subshell and type the command contextual to the subshell:
+
+{code}
+karaf@root()> feature
+karaf@root(feature)> list
+{code}
+
+You can note that you enter in a subshell directly by typing the subshell name (here {{feature}}).
You can "switch" directly from a subshell to another:
+
+{code}
+karaf@root()> feature
+karaf@root(feature)> bundle
+karaf@root(bundle)>
+{code}
+
+The prompt displays the current subshell between ().
+
+The {{exit}} command goes to the parent subshell:
+
+{code}
+karaf@root()> feature
+karaf@root(feature)> exit
+karaf@root()>
+{code}
+
+The completion mode defines the behaviour of the tab key and the help command.
+
+You have three different modes available:
+
+* GLOBAL
+* FIRST
+* SUBSHELL
+
+You can define your default completion mode using the completionMode property in {{etc/org.apache.karaf.shell.cfg}}
file. By default, you have:
+
+{code}
+completionMode = GLOBAL
+{code}
+
+You can also change the completion mode “on the fly” (while using the Karaf shell
console) using the {{shell:completion}} command:
+
+{code}
+karaf@root()> shell:completion
+GLOBAL
+karaf@root()> shell:completion FIRST
+karaf@root()> shell:completion
+FIRST
+{code}
+
+{{shell:completion}} can inform you about the current completion mode used. You can also
provide the new completion mode that you want.
+
+GLOBAL completion mode is the default one in Karaf 3.0.0 (mostly for transition purpose).
+
+GLOBAL mode doesn’t really use subshell: it’s the same behavior as in previous
Karaf versions.
+
+When you type the tab key, whatever in which subshell you are, the completion will display
all commands and all aliases:
+
+{code}
+karaf@root()> <TAB>
+karaf@root()> Display all 273 possibilities? (y or n)
+...
+karaf@root()> feature
+karaf@root(feature)> <TAB>
+karaf@root(feature)> Display all 273 possibilities? (y or n)
+{code}
+
+FIRST completion mode is an alternative to the GLOBAL completion mode.
+
+If you type the tab key on the root level subshell, the completion will display the commands
and the aliases from all subshells (as in GLOBAL mode).
+However, if you type the tab key when you are in a subshell, the completion will display
only the commands of the current subshell:
+
+{code}
+karaf@root()> shell:completion FIRST
+karaf@root()> <TAB>
+karaf@root()> Display all 273 possibilities? (y or n)
+...
+karaf@root()> feature
+karaf@root(feature)> <TAB>
+karaf@root(feature)>
+info install list repo-add repo-list repo-remove uninstall version-list
+karaf@root(feature)> exit
+karaf@root()> log
+karaf@root(log)> <TAB>
+karaf@root(log)>
+clear display exception-display get log set tail
+{code}
+
+SUBSHELL completion mode is the real subshell mode.
+
+If you type the tab key on the root level, the completion displays the subshell commands
(to go into a subshell), and the global aliases.
+Once you are in a subshell, if you type the TAB key, the completion displays the commands
of the current subshell:
+
+{code}
+karaf@root()> shell:completion SUBSHELL
+karaf@root()> <TAB>
+karaf@root()>
+* bundle cl config dev feature help instance jaas kar la ld lde log log:list man package
region service shell ssh system
+karaf@root()> bundle
+karaf@root(bundle)> <TAB>
+karaf@root(bundle)>
+capabilities classes diag dynamic-import find-class headers info install list refresh requirements
resolve restart services start start-level stop
+uninstall update watch
+karaf@root(bundle)> exit
+karaf@root()> camel
+karaf@root(camel)> <TAB>
+karaf@root(camel)>
+backlog-tracer-dump backlog-tracer-info backlog-tracer-start backlog-tracer-stop context-info
context-list context-start context-stop endpoint-list route-info route-list route-profile
route-reset-stats
+route-resume route-show route-start route-stop route-suspend
+{code}
+
+h2. Unix like environment
+
+Karaf console provides a full Unix like environment.
+
+h3. Help or man
+
+We already saw the usage of the {{help}} command to display all commands available.
+
+But you can also use the {{help}} command to get details about a command:
+
+{code}
+karaf@root()> help feature:list
+DESCRIPTION
+        feature:list
+
+        Lists all existing features available from the defined repositories.
+
+SYNTAX
+        feature:list [options]
 
-h2. Getting help for a command
+OPTIONS
+        -o, --ordered
+                Display a list using alphabetical order
+        --help
+                Display this help message
+        -i, --installed
+                Display a list of all installed features only
+
+{code}
 
-To view help on a particular command, type the command followed by {{--help}} or use the
{{help}} command followed by the name of the command:
+It's very similar to the {{man}} command on Unix. You can also use the {{man}} command (which
is an lias to the {{help}} command):
 
 {code}
-karaf@root> features:list --help
+karaf@root()> man feature:list
 DESCRIPTION
-        features:list
+        feature:list
 
         Lists all existing features available from the defined repositories.
 
 SYNTAX
-        features:list [options]
+        feature:list [options]
 
 OPTIONS
+        -o, --ordered
+                Display a list using alphabetical order
         --help
-                       Display this help message
+                Display this help message
         -i, --installed
-                       Display a list of all installed features only
+                Display a list of all installed features only
 {code}
 
-h2. More...
+You can also use another form to get the command help, by using the {{--help}} option to
the command:
+
+{code}
+karaf@root()> feature:list --help
+DESCRIPTION
+        feature:list
+
+        Lists all existing features available from the defined repositories.
+
+SYNTAX
+        feature:list [options]
+
+OPTIONS
+        -o, --ordered
+                Display a list using alphabetical order
+        --help
+                Display this help message
+        -i, --installed
+                Display a list of all installed features only
+
+{code}
 
-You'll find a more in-depth guide to the shell syntax in the [developers guide|/developers-guide/shell-syntax].
+h3. Completion
+
+When you type the tab key, Karaf tries to complete:
+
+* the subshell
+* the commands
+* the aliases
+* the command arguments
+* the command option
+
+h3. Key binding
+
+Like on most Unix environment, Karaf console support some key bindings:
+
+* the arrows key to navigate in the commands history
+* CTRL-D to logout/shutdown Karaf
+* CTRL-R to search previously executed command
+* CTRL-U to remove the current line
+
+h3. Pipe
+
+You can pipe the output of one command as input to another one. It's a pipe, using the |
character:
+
+{code}
+karaf@root()> feature:list|grep -i karaf
+standard                      | 3.0.0-SNAPSHOT  | x         | standard-3.0.0-SNAPSHOT   
      | Karaf standard feature
+war                           | 3.0.0-SNAPSHOT  |           | standard-3.0.0-SNAPSHOT   
      | Turn Karaf as a full WebContainer
+kar                           | 3.0.0-SNAPSHOT  | x         | standard-3.0.0-SNAPSHOT   
      | Provide KAR (KARaf archive) support
+webconsole                    | 3.0.0-SNAPSHOT  |           | standard-3.0.0-SNAPSHOT   
      | Base support of the Karaf WebConsole
+ssh                           | 3.0.0-SNAPSHOT  | x         | standard-3.0.0-SNAPSHOT   
      | Provide a SSHd server on Karaf
+scheduler                     | 3.0.0-SNAPSHOT  |           | standard-3.0.0-SNAPSHOT   
      | Provide a scheduler service in Karaf to fire event
+jasypt-encryption             | 3.0.0-SNAPSHOT  |           | standard-3.0.0-SNAPSHOT   
      | Advanced encryption support for Karaf security
+{code}
+
+h3. Grep, more, find, ...
+
+Karaf console provides some core commands similar to Unix environment:
+
+* {{shell:head}} displays the first line of the input
+* {{shell:source}} executes commands contained in a script
+* {{shell:alias}} creates an alias to an existing command
+* {{shell:history}} prints the commands history
+* {{shell:cat}} displays the content of a file or URL
+* {{shell:if}} allows you to use conditions (if, then, else blocks) in script
+* {{shell:tac}} captures stdin and returns it as a string
+* {{shell:clear}} clears the current console display
+* {{shell:info}} prints various information about the current Karaf instance
+* {{shell:tail}} displays the last lines of the input
+* {{shell:completion}} displays or change the current completion mode
+* {{shell:java}} executes a Java application
+* {{shell:threads}} prints the current thread
+* {{shell:date}} displays the current date (optionally using a format)
+* {{shell:watch}} periodically executes a command and refresh the output
+* {{shell:each}} executes a closure on a list of arguments
+* {{shell:more}} is a file pager
+* {{shell:wc}} prints newline, words, and byte counts for each file
+* {{shell:echo}} echoes and prints arguments to stdout
+* {{shell:new}} creates a new Java object
+* {{shell:edit}} calls a text editor on the current file or URL
+* {{shell:printf}} formats and prints arguments
+* {{shell:exec}} executes a system command
+* {{shell:sleep}} sleeps for a bit then wakes up
+* {{shell:grep}} prints lines matching the given pattern
+* {{shell:sort}} writes sorted concatenation of all files to stdout
+
+You don't have to use the full qualified name of the command, you can directly use the command
name:
+
+{code}
+karaf@root(shell)> head --help
+DESCRIPTION
+        shell:head
+
+        Displays the first lines of a file.
+
+SYNTAX
+        shell:head [options] [paths or urls]
+
+ARGUMENTS
+        paths or urls
+                A list of file paths or urls to display separated by whitespaces.
+
+OPTIONS
+        -n
+                The number of lines to display, starting at 1.
+        --help
+                Display this help message
+
+{code}
 
-The console can also be easily extended by creating new commands as explained in the [developers
guide|/developers-guide/extending-console].
+Again, you can find details and all options of these commands using {{help}} command or {{--help}}
option.
\ No newline at end of file



Mime
View raw message