plugin:cli
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
plugin:cli [2019-01-12 13:37] – Added bugtracker LarsDW223 | plugin:cli [2023-04-15 21:12] (current) – Aleksandr | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Command Line Interface | + | ====== |
---- plugin ---- | ---- plugin ---- | ||
description: | description: | ||
- | author | + | author |
- | email : C.P.Jobling@Swansea.ac.uk | + | email : Schplurtz-AT-Laposte•net |
type : syntax | type : syntax | ||
- | lastupdate : 2010-08-07 | + | lastupdate : 2020-08-18 |
- | compatible : Detritus | + | compatible : elenor of tsort, detritus, frusterick manners, greebo, hogfather, igor, jack jackrum |
depends | depends | ||
conflicts | conflicts | ||
- | similar | + | similar |
- | tags : code, cli, syntax, | + | tags : code, cli, syntax, |
- | + | downloadurl: | |
- | downloadurl: | + | bugtracker : https:// |
- | bugtracker: | + | sourcerepo : https:// |
+ | donationurl: | ||
+ | screenshot_img : | ||
---- | ---- | ||
- | This plugin brings a Command Line Interface formatter to [[wiki: | + | ===== Description ===== |
- | The assumptions made are | + | This plugin brings a Command Line Interface formatter to DokuWiki |
- | - all user commands start with a prompt | + | allowing you to format the output of a transcript say for a user |
+ | manual or on-line tutorial. It is designed to work with the output | ||
+ | of a standard Unix Bash Shell, but is suitable to document | ||
+ | other kinds of CLI interaction, | ||
+ | and Ruby, Matlab, etc. | ||
+ | |||
+ | The assumptions made are | ||
+ | - all user commands start with a prompt | ||
- the CLI prompt will end in a recognizable character (typically ' | - the CLI prompt will end in a recognizable character (typically ' | ||
- user commands will follow the CLI prompt on the same line | - user commands will follow the CLI prompt on the same line | ||
- | - lines that do not start with a prompt are outputs from the CLI((this turns out to be a problem for the Ruby interactive shell //irb// which seems to prefix every line with a prompt!)) | + | |
+ | | ||
- | A key design feature is that it should be possible to display a CLI transcript (e.g. output from a history file or copy of text from a console window) for display with the mimumum of additional markup. | + | A key design feature is that it should be possible to display a CLI transcript (e.g. output from a history file or copy of text from a console window) for display with the mimumum of additional markup. |
- | It is possible to adjust the style of the display using a style sheet. For details refer to [[#style.css]]. | + | Very complicated prompts can be recognized with regexp; see [[# |
- | ==== Notes ==== | + | ===== Installation ===== |
- | * My version of this page -- which could be more recently updated -- can be found [[http:// | + | Install the plugin using the [[extension|Extension Manager Plugin]] and the download URL above, which points to latest |
- | * Since 7 August 2010 the source for this plugin code has been hosted at GitHub at https:// | + | ===== Examples/Usage ===== |
- | cd ../ | + | A simple Bash Shell interaction: |
- | git clone git:// | + | |
+ | <cli> | ||
+ | user@host: | ||
+ | conf lang | ||
+ | info.txt | ||
+ | user@host: | ||
+ | </ | ||
+ | {{ https:// | ||
+ | Next example shows that ''< | ||
+ | <cli> | ||
+ | user@host: | ||
+ | <cli type=dos> | ||
+ | (C) Copyright 1995-2006 Pasquale J. Villani and The FreeDOS Project. | ||
+ | D: = LINUX\FS/ | ||
+ | E: = LINUX\FS/ | ||
+ | " | ||
+ | C:\>dir | ||
+ | | ||
+ | | ||
+ | | ||
+ | TMP < | ||
+ | CONFIG | ||
+ | AUTOEXEC BAT | ||
+ | 2 file(s) | ||
+ | 1 dir(s) | ||
+ | C:\>echo pouet | ||
+ | pouet | ||
+ | C:\>rem This is a remark and does nothing | ||
+ | C:\>echo But this rem is not a remark. | ||
+ | But this rem is not a remark. | ||
+ | C:\>exit | ||
+ | </ | ||
+ | user@host: | ||
+ | Back to normal again | ||
+ | user@host: | ||
+ | </ | ||
- | =====Acknowledgements===== | + | {{ https:// |
- | A similar feature is to be found in [[http:// | + | Custom prompts, when there are no satisfying defaults |
+ | <cli prompt=" | ||
+ | SQL> select | ||
+ | | ||
+ | | ||
+ | | ||
+ | |||
+ | D | ||
+ | - | ||
+ | X | ||
+ | |||
+ | SQL> | ||
+ | </cli> | ||
- | Several improvements suggested by Stephane Chazelas and Andy Webber. | + | {{ https:// |
+ | ===== Syntax ===== | ||
+ | The full syntax: | ||
+ | <cli prompt=' | ||
+ | session transcript | ||
+ | </ | ||
+ | * //prompt// --- [optional] the prompt used by the CLI. See configuration below for the description of the syntax. If omitted, the default value is used. | ||
+ | * // | ||
+ | * //comment// --- [optional] the comment used by the CLI. See configuration below for the description of the syntax. If omitted, the default value is used. | ||
+ | * // | ||
+ | * //class// --- [optional] Class to add to the html block. This allows to create all sorts of custom [[#style]]. | ||
+ | Each of the values may be enclosed in single ('' | ||
+ | Within single quotes, «\\» stands for «\» and «\' | ||
+ | Within double quotes, «\\» stands for «\» and «%%\" | ||
+ | In unquoted strings, the following characters must be \-escaped to be part of the string: «'' | ||
- | ===== Syntax ===== | + | There may be spaces around the equal sign. |
+ | The following examples are all equivalent: | ||
+ | <cli comment=\"\ > | ||
+ | <cli comment | ||
+ | <cli ' | ||
- | A simple Bash Shell interaction: | + | The opening '' |
- | < | + | Values are always set in this order: default, shortcut, individual settings. I.e. if you write something like |
- | user@host:~/somedir $ ls # List current directory | + | '' |
- | conf lang | + | |
- | info.txt manager.dat renderer.php | + | |
- | | + | |
- | | + | |
- | Should be rendered: | + | Default values match most unix shells use. |
- | < | ||
- | <pre class=" | ||
- | <span class=" | ||
- | <span class=" | ||
- | <span class=" | ||
- | <span class=" | ||
- | </ | ||
- | </ | ||
- | The full syntax: | + | ===== Configuration and Settings ===== |
- | <cli prompt=' | + | The plugin has 9 configuration settings. The first 3 are the default prompts and comment |
- | transcript | + | |
- | </ | + | |
- | * // | + | * // |
- | * //comment// --- [optional] | + | * //continue// is a description of the continue prompt. It uses the same syntax as //prompt//. |
- | * //continue// -- [optional] | + | * //comment// is a description of the comment marker. Also a string or regexp. It is matched only to the part of each transcript lines **after** |
- | * The defaults above match Bourne shell ${PS1} and ${PS2} prompts and comments | + | |
- | The opening '' | + | If any of these is empty, then the cli plugin uses a harcoded internal value that corresponds to the defaults shown below. |
- | See the plugin in action [[http://www.cpjobling.org.uk/dokuwiki/test:cli|here]]. The sample page shows examples from a number | + | Default values: |
+ | * //prompt// ''/ | ||
+ | * //continue// ''/ | ||
+ | * //comment// ''/ | ||
- | ===== Configuration ===== | + | The next three settings (namedprompt, |
- | The plugin has no configuration settings, although you may want to review the default colour scheme in [[# | + | name: |
+ | It is not necessary that values are given for the three of them. The defaults below define shortcuts for interactive Ruby (irb), Cisco-like CLI (nospace), MS-DOS and powershell (dos), and Python (python). | ||
+ | * // | ||
+ | irb:/(?x) ^ ( > | irb.*?: | ||
+ | nospace:/ | ||
+ | dos:/ | ||
+ | </ | ||
+ | * // | ||
+ | irb:@(?x) ^ ( \?> | irb.*?: | ||
+ | R:/^\+ / | ||
+ | python:... | ||
+ | nospace: | ||
+ | </ | ||
+ | * // | ||
+ | irb:/# | ||
+ | dos:/ | ||
+ | </ | ||
- | ===== Installation ===== | + | As you can see, for python, you only have to define a // |
- | Search | + | The last set of configuration options, // |
- | ==== Sources: | + | ==== odt support |
- | | + | When exporting a page to odt with the [[odt]] plugin, font colours are taken from the CSS **default** style. Computer output is blue, prompt is green, user input red and comments orange. You may change the default colours for both html and odt by [[# |
- | To install | + | * // |
+ | * // | ||
+ | * // | ||
- | The folder will contain: | + | ==== style ==== |
- | | + | |
- | syntax.php | + | |
- | The plugin | + | You may customize the colours of the text and also the border, background, padding, margin, font etc... well, pretty much anything customizable with CSS. Where to create your CSS files is documented in [[devel: |
+ | <code css userstyle.css> | ||
+ | # | ||
+ | /* This changes the default style */ | ||
+ | background-color: | ||
+ | span.cli_prompt | ||
+ | span.cli_command { color: white } | ||
+ | span.cli_comment { color: grey } | ||
+ | span.cli_output | ||
+ | /* retro green and retro green with prompt in reverse video */ | ||
+ | & | ||
+ | background-color: | ||
+ | span.cli_prompt | ||
+ | span.cli_command { color: #8fe35f } | ||
+ | span.cli_comment { color: #69a845 } | ||
+ | span.cli_output | ||
+ | & | ||
+ | span.cli_prompt | ||
+ | } | ||
+ | } | ||
+ | /* retro ochre and retro ochre with prompt in reverse video */ | ||
+ | & | ||
+ | background-color: | ||
+ | span.cli_prompt | ||
+ | span.cli_command { color: #ffbf0e } | ||
+ | span.cli_comment { color: #a87f0d } | ||
+ | span.cli_output | ||
+ | & | ||
+ | span.cli_prompt | ||
+ | } | ||
+ | } | ||
+ | /* Just for fun, but should be useless */ | ||
+ | & | ||
+ | text-transform: | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | Here are some examples | ||
+ | <cli> | ||
+ | me@mycomputer (0) $ ls # list files | ||
+ | README i prompt-plugin.txt | ||
+ | basic-usage.png lang style.css | ||
+ | conf plugin.info.txt syntax.php | ||
+ | dos-example.png prompt-examples.txt | ||
+ | </ | ||
+ | {{ https:// | ||
+ | <cli green uppercase> | ||
+ | me@mycomputer (0) $ ls -adtr * # list files with weid args | ||
+ | README i prompt-plugin.txt | ||
+ | basic-usage.png lang style.css | ||
+ | conf plugin.info.txt syntax.php | ||
+ | dos-example.png prompt-examples.txt | ||
+ | </ | ||
+ | {{ https:// | ||
- | ===== Details ===== | + | <cli type=dos retro-ochre reverse> |
+ | C: | ||
+ | | ||
+ | | ||
+ | TMP < | ||
+ | CONFIG | ||
+ | AUTOEXEC BAT | ||
+ | 2 file(s) | ||
+ | 1 dir(s) | ||
+ | C:\>echo pouet | ||
+ | pouet | ||
+ | C:\>rem This is a remark and does nothing | ||
+ | </ | ||
- | ==== syntax.php ==== | + | {{ https:// |
- | <code php> | + | ---- |
- | <?php | + | |
- | /** | + | |
- | * Command Line Interface (CLI) Plugin | + | |
- | | + | |
- | * Syntax: | + | |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
- | * | + | |
- | * Acknowledgements: | + | |
- | | + | |
- | | + | |
- | | + | |
- | * | + | |
- | * @license | + | |
- | * @author | + | |
- | */ | + | |
- | + | ||
- | if(!defined(' | + | |
- | if(!defined(' | + | |
- | require_once(DOKU_PLUGIN.' | + | |
- | + | ||
- | /** | + | |
- | * All DokuWiki plugins to extend the parser/ | + | |
- | * need to inherit from this class | + | |
- | */ | + | |
- | class syntax_plugin_cli extends DokuWiki_Syntax_Plugin { | + | |
- | + | ||
- | var $prompt_str = '$ '; | + | |
- | var $prompt_cont = '/ | + | |
- | var $prompt_continues = false; | + | |
- | var $comment_str = '#'; | + | |
- | + | ||
- | /** | + | |
- | * return some info | + | |
- | */ | + | |
- | function getInfo(){ | + | |
- | return array( | + | |
- | ' | + | |
- | ' | + | |
- | ' | + | |
- | ' | + | |
- | ' | + | |
- | ' | + | |
- | ); | + | |
- | } | + | |
- | + | ||
- | /** | + | |
- | * What kind of syntax are we? | + | |
- | */ | + | |
- | function getType(){ | + | |
- | return ' | + | |
- | } | + | |
- | + | ||
- | /** | + | |
- | * What kind of syntax do we allow (optional) | + | |
- | */ | + | |
- | // function getAllowedTypes() { | + | |
- | // return array(); | + | |
- | // } | + | |
- | + | ||
- | // override default accepts() method to allow nesting | + | |
- | // - ie, to get the plugin accepts its own entry syntax | + | |
- | function accepts($mode) { | + | |
- | if ($mode == substr(get_class($this), | + | |
- | return parent:: | + | |
- | } | + | |
- | + | ||
- | /** | + | |
- | * What about paragraphs? (optional) | + | |
- | */ | + | |
- | function getPType(){ | + | |
- | return ' | + | |
- | } | + | |
- | + | ||
- | /** | + | |
- | * Where to sort in? | + | |
- | */ | + | |
- | function getSort(){ | + | |
- | return 601; | + | |
- | } | + | |
- | + | ||
- | + | ||
- | /** | + | |
- | * Connect pattern to lexer | + | |
- | */ | + | |
- | function connectTo($mode) { | + | |
- | | + | |
- | '" | + | |
- | ' | + | |
- | ' | + | |
- | ' | + | |
- | /* | + | |
- | * The [)]? and |[(?:] is to work around a bug in lexer.php | + | |
- | * wrt nested (...) | + | |
- | */ | + | |
- | } | + | |
- | + | ||
- | function postConnect() { | + | |
- | | + | |
- | } | + | |
- | + | ||
- | + | ||
- | /** | + | |
- | * Handle the match | + | |
- | */ | + | |
- | function handle($match, | + | |
- | switch ($state) { | + | |
- | case DOKU_LEXER_ENTER : | + | |
- | $args = substr($match, | + | |
- | return array($state, | + | |
- | case DOKU_LEXER_MATCHED : | + | |
- | break; | + | |
- | case DOKU_LEXER_UNMATCHED : | + | |
- | return array($state, | + | |
- | case DOKU_LEXER_EXIT : | + | |
- | return array($state, | + | |
- | case DOKU_LEXER_SPECIAL : | + | |
- | break; | + | |
- | } | + | |
- | return array(); | + | |
- | } | + | |
- | + | ||
- | /** | + | |
- | * Create output | + | |
- | */ | + | |
- | function render($mode, | + | |
- | if($mode == ' | + | |
- | | + | |
- | | + | |
- | case DOKU_LEXER_ENTER : | + | |
- | $args = $match; | + | |
- | | + | |
- | | + | |
- | | + | |
- | case DOKU_LEXER_UNMATCHED : | + | |
- | | + | |
- | | + | |
- | case DOKU_LEXER_EXIT : | + | |
- | | + | |
- | | + | |
- | } | + | |
- | | + | |
- | } | + | |
- | return false; | + | |
- | } | + | |
- | + | ||
- | | + | |
- | /* | + | |
- | * extracts value from $args for $param | + | |
- | * xxx = " | + | |
- | * xxx = a\ b -> a b | + | |
- | * xxx = ' | + | |
- | * | + | |
- | * returns null if value is empty. | + | |
- | */ | + | |
- | if (preg_match("/ | + | |
- | '" | + | |
- | ' | + | |
- | ' | + | |
- | ' | + | |
- | | + | |
- | case "'": | + | |
- | | + | |
- | | + | |
- | | + | |
- | case '"': | + | |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
- | } | + | |
- | if ($result != "" | + | |
- | | + | |
- | } | + | |
- | } | + | |
- | + | ||
- | | + | |
- | // process args to CLI tag: sets $comment_str and $prompt_str | + | |
- | if (!is_null($prompt = $this-> | + | |
- | | + | |
- | if (!is_null($comment = $this-> | + | |
- | | + | |
- | } | + | |
- | + | ||
- | function _render_conversation($match, | + | |
- | $prompt_continues = false; | + | |
- | $lines = preg_split('/ | + | |
- | if ( trim($lines[0]) == "" | + | |
- | if ( trim($lines[count($lines)]) == "" | + | |
- | foreach ($lines as $line) { | + | |
- | $index = strpos($line, | + | |
- | if ($index === false) { | + | |
- | if ($this-> | + | |
- | if (preg_match($this-> | + | |
- | } | + | |
- | if ($this-> | + | |
- | // format prompt | + | |
- | $renderer-> | + | |
- | // Split line into command + optional comment (only end-of-line comments supported) | + | |
- | $command = preg_split($this-> | + | |
- | $commands = explode($this-> | + | |
- | // Render command | + | |
- | $renderer-> | + | |
- | // Render comment if there is one | + | |
- | if ($commands[1]) { | + | |
- | $renderer-> | + | |
- | $renderer-> | + | |
- | } | + | |
- | $renderer-> | + | |
- | } else { | + | |
- | // render as output | + | |
- | $renderer-> | + | |
- | $this-> | + | |
- | } | + | |
- | } else { | + | |
- | $this-> | + | |
- | // format prompt | + | |
- | $prompt = substr($line, | + | |
- | $renderer-> | + | |
- | // Split line into command + optional comment (only end-of-line comments supported) | + | |
- | $commands = explode($this-> | + | |
- | // Render command | + | |
- | | + | |
- | // Render comment if there is one | + | |
- | if ($commands[1]) { | + | |
- | | + | |
- | $renderer-> | + | |
- | } | + | |
- | | + | |
- | } | + | |
- | } | + | |
- | } | + | |
- | } | + | |
- | //Setup VIM: ex: et ts=4 enc=utf-8 sw=4 : | + | |
- | ?> | + | |
- | </ | + | A few technical details. |
+ | ''< | ||
- | ==== style.css ==== | + | <cli type=dos retro-ochre reverse> |
+ | is rendered as | ||
+ | <code html> | ||
+ | <pre class="cli dos retro-ochre reverse"> | ||
+ | < | ||
+ | | | | ||
+ | | +---- type=dos. added as a class | ||
+ | | | ||
+ | +-------- class cli is always present | ||
+ | --> | ||
+ | </ | ||
- | These may be modified to suit your own requirements. | + | A full example: |
- | < | + | < |
- | /* plugin:cli */ | + | <cli retro-ochre> |
+ | me@mycomputer (0) $ dosemu # let's go back in the 80s | ||
+ | <cli type=dos> | ||
+ | C:>rem This is a remark and does nothing | ||
+ | C:>echo pouet | ||
+ | pouet | ||
+ | C:> | ||
+ | </cli> | ||
+ | me@mycomputer (0) $ | ||
+ | </cli> | ||
+ | </ | ||
- | .cli_output { | + | Will produce this html code |
- | color: blue; | + | |
- | } | + | |
- | .cli_comment | + | <code html> |
- | color: brown; | + | <pre class=" |
- | } | + | <span class=" |
+ | <div class=" | ||
+ | <span class=" | ||
+ | <span class=" | ||
+ | <span class=" | ||
+ | <span class=" | ||
+ | </ | ||
+ | <span class=" | ||
+ | </ | ||
+ | </ | ||
- | .cli_prompt { | ||
- | color: green; | ||
- | } | ||
- | .cli_command { | + | ===== Development ===== |
- | color: red; | + | |
- | } | + | |
- | // nested CLI | ||
- | pre.cli pre.cli { | ||
- | background-color: | ||
- | } | ||
- | /* end plugin:cli */ | + | === Change Log === |
- | </ | + | |
+ | {{rss> | ||
- | ===== Revision History ===== | ||
- | * 2007-09-10 --- First release | + | === ToDo/Wish List === |
- | * 2008-13-02 --- Several improvements to lexing and white space handling as suggested by Stephane Chazelas; continuation prompt support and whitespace handling improvements added by Andy Webber. | + | |
- | * 2010-07-08 --- Hosting moved to GitHub. Note, hosting of examples at http:// | + | |
- | ===== To Do ===== | + | Please, create an issue on [[https://github.com/ |
- | + | ||
- | * It would be nice to support end of line markers for long command strings | + | |
- | * Doesn' | + | |
- | ===== Bugs ===== | + | ===== FAQ ===== |
- | * Care needed for CLI's that use > to end a prompt -- done. | ||
- | * Doesn' | ||
- | * Ruby's multiple output line decorators are likely to cause problems. | ||
- | * Bound to be others ... this is my first DokuWiki plugin (actually it's my first attempt at PHP coding ^_^) | ||
- | * following codes don't display right | ||
- | < | ||
- | <cli prompt="#"> | ||
- | # rpm -ivh darcs-1.0.9-3.fc6.i386.rpm | ||
- | Preparing... | ||
- | | ||
- | </ | ||
- | </ | ||
- | ===== Comments Please | + | ===== Discussion |
- | I modified | + | Please, discuss on the [[https://forum.dokuwiki.org/|forum]]. |
- | <code php> | + | |
- | if ( trim($lines[0]) == "" | + | |
- | if ( trim($lines[count($lines)]) == "" | + | |
- | </ | + | |
- | This is just a quick hack and needs more afterthought, | + | |
- | I also did not like the "empty lines got removed" | ||
- | <code php> | + | ---- |
- | $lines = preg_split('/ | + | |
- | </ | + | |
- | The previous comment still applies. | ||
- | Added to new release ... CPJ | + | ===== Acknowledgements ===== |
- | I would like to be able to have multiple prompts | + | This plugin was originally written in 2007 by [[https:// |
- | on configuration mode: | + | |
- | < | + | Several improvements suggested by Stephane Chazelas and Andy Webber. |
- | router> | + | |
- | router#conf t | + | |
- | router(conf)# | + | |
- | </ | + | |
- | It should be noted that after install | + | More than 12 years after its creation, this plugin was modernized |
- | + | ||
- | One more : to make background color effective, change line in style.css | + | |
- | <code css> | + | |
- | pre.cli pre.cli { | + | |
- | </ | + | |
- | to | + | |
- | <code css> | + | |
- | div.dokuwiki pre.cli { | + | |
- | </ | + | |
plugin/cli.1547296666.txt.gz · Last modified: 2019-01-12 13:37 by LarsDW223