pike.git / refdoc / chapters / hilfe.xml

version» Context lines:

pike.git/refdoc/chapters/hilfe.xml:1: + <!-- FIXME: I'd like this file to be generated from the actual strings in Hilfe.pmod +  and all examples autogenerated in a wrapper like the one in testhilfe.pike --> + <chapter title="Hilfe">    -  + <p>Hilfe stands for Hubbes Incremental LPC Front End, and is an + incremental Pike evaluator. As the name hints Hilfe has its roots back + when Pike was called LPC, but none of the code from that Hilfe + remains. Hilfe is one of the most useful tools for Pike developers, + since it enables them to try various Pike constructions and see how + they work. Even the most experienced Pike programmer can forget how + the return data structure of a function looks like or if + or | is the + best way to merge to mappings for a specific purpose. + </p> +  + <section title="Basic operations"> +  + <p>In short hilfe is a command line version of pike, allowing you to +  do real time evaluation of pike code. Simply write a line of pike +  code and press return. If you gave hilfe a complete block of code +  it will be evaluated and the result will be returned. Side effects will +  also be effective, hence changing a variable will indeed change the +  variables value. You are of course not limited to basic variable +  types like integers and strings, or reference data types like +  mappings and arrays. You can just as well define functions and +  classes, enabling you to experiment with inherits, operator +  overloading and other object oriented things. To start hilfe, just +  execute the pike binary without any arguments.</p> +  + <example> + bash$ pike + Pike v7.3 release 49 running Hilfe v3.5 (Incremental Pike Frontend) + > int a=5; + > a+3.3; + (1) Result: 8.300000 + > (string)(enumerate(32)[*]+65); + (2) Result: "ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`" + > string b=(string)(enumerate(32)[*]+65); + > b/(a+3.3); + (3) Result: ({ /* 4 elements */ +  "ABCDEFGH", +  "IJKLMNOPQ", +  "RSTUVWXY", +  "Z[\\]^_`" +  }) + > + </example> +  + <p>A history of the 512 last entered lines is kept in Hilfe. You can + browse this list with your arrow keys up/down. When you exit Hilfe + your history will be saved in .hilfe_history in the directory set + in environment variable $HOME or $USERPROFILE. Next time hilfe is + started the history is imported.</p> +  + <p>A history of the last returned results is kept and can be accessed + from your hilfe expressions with the variable <expr>__</expr>. You can + either "address" your results with absolute addresses, e.g. + <expr>__[2]</expr> to get the second result ever, or with relative + addresses, e.g. <expr>__[-1]</expr> to get the last result. The last + result is also available in the variable <expr>_</expr>, thus + <expr>_==__[-1]</expr> is true. The magic <expr>_</expr> and + <expr>__</expr> variable can be shadowed with local definitions to + disable them, e.g. by typing <expr>int _;</expr>. The result history + is ten entries long by default, but it could easily be altered by + using the <tt>set history</tt> command. Note that some Pike code only + works when there is at most one object created from a class (e.g. the + Perl module), which means that the result history must be turned off. + Otherwise the previous object will remain in the history during the + next nine results.</p> +  + <p>You can put a .hilferc file in the directory set in your + environment variable $HOME or $USERPROFILE. The contents of this file + will be evaluated in hilfe during each startup. It may contain both + commands and Pike expressions.</p> +  + <p>One must however always remember that code entered in Hilfe does + not always work exactly as if it was written in a stand alone Pike + program. All variables are kept in a mapping so that their values can + be view and altered by subsequent code lines. Every expression is + compiled and evaluated in a wrapper which then returns the return + value to Pike. Use the <tt>dump wrapper</tt> command after a line has + been evaluated to see the actual code compiled.</p> +  + <example> + > int a=5; + > a+3.3; + (1) Result: 8.300000 + > dump wrapper + Last compiled wrapper: + 001: #pragma unpragma_strict_types + 002: mapping(string:mixed) ___hilfe = ___Hilfe->variables; + 003: # 1 + 004: mixed ___HilfeWrapper() { return (([mapping(string:int)]___hilfe)->a)+3.3; ; } + 005: + > + </example> +  + <p>Note that there are a few symbols that you can not define, since + they are used by Hilfe.</p> +  + <matrix> + <r><c><expr>___hilfe</expr></c><c>A mapping containing all defined symbols.</c></r> + <r><c><expr>___Hilfe</expr></c><c>The Hilfe object.</c></r> + <r><c><expr>___HilfeWrapper</expr></c><c>A wrapper around the entered expression.</c></r> + </matrix> +  + </section> +  + <section title="Commands"> +  + <p>In addition to be able to enter Pike expressions, there are also a + few commands available which controls Hilfe. To avoid having the + commands shadowed by Pike declarations with the same name, it is also + possible to add a dot in front of the command.</p> +  + <example> + > int help=3; + Hilfe Warning: Command "help" no longer reachable. Use ".help" instead. + > help + >> +2; + (1) Result: 5 + > + </example> +  + <subsection title="Help"> +  + <p>The help command displays a very short introduction to Pike and + lists all the available commands with a brief explaination.</p> +  + <example> + > help +  + Pike v7.3 release 49 running Hilfe v3.5 (Incremental Pike Frontend) + Hilfe is a tool to evaluate Pike code interactively and + incrementally. Any Pike function, expression or variable declaration + can be entered at the command line. There are also a few extra + commands: +  +  dump - Dump variables and other info. +  exit - Exit Hilfe. +  help - Show help text. +  new - Clears the Hilfe state. +  quit - Exit Hilfe. +  set - Change Hilfe settings. +  start - Start a subsystem. +  stop - Stop a subsystem. +  . - Abort current input batch. +  + Enter "help me more" for further Hilfe help. + > + </example> +  + <p>In addition to this elementary help there are a few extra arguments + that can be given to help to see other help pages. "<tt>help me + more</tt>" returns a brief summary of everything in this manual + chapter. "<tt>help hilfe todo</tt>" shows the items in the bug section + below. "<tt>help about hilfe</tt>" show the Hilfe CVS id string and + some other version information. In addition to these three arguments + it is also possible to type help follow with the name of any other + command. That will display the documentation for that command.</p> +  + </subsection> +  + <subsection title="Exit and Quit"> + <p>It is possible to end a Hilfe session by entering the command + <tt>exit</tt> or <tt>quit</tt>. It is also possible to exit by using + Control+D. Note that no history will be saved if Control+C is used to + terminate Hilfe.</p> + </subsection> +  + <subsection title="."> + </subsection> +  + <subsection title="dump"> + </subsection> +  + <subsection title="new"> + </subsection> +  + <subsection title="set"> + </subsection> +  + <subsection title="start and stop"> + </subsection> +  + </section> +  + <section title="Subsystems"> +  + <subsection title="Backend"> + </subsection> +  + <subsection title="Logging"> + </subsection> +  + </section> +  + <section title="Bugs and possible improvements"> +  + <ul> + <li>Hilfe can not handle sscanf statements like +  <expr>int a = sscanf("12", "%d", int b);</expr></li> + <li>The variable scope is not correctly adjusted for sscanf +  constructions like <expr>sscanf(x, "%2d%2d", int a, int b);</expr></li> + <li><expr>int x=x;</expr> does not generate an error when <expr>x</expr> is undefined.</li> + <li>Hilfe can not handle enums.</li> + <li>Hilfe can not handle typedefs.</li> + <li>Hilfe can not handle implicit lambdas.</li> + <li>Hilfe can not handle unnamed classes.</li> + <li>Hilfe can not handle named lambdas.</li> + <li>Hilfe should possibly handle imports better, e.g. overwrite the +  local variables/constants/functions/programs.</li> + <li>Filter exit/quit from history. Could be done by adding a 'pop' +  method to Readline.History and calling it from StdinHilfe's +  destroy.</li> + <li>Add some better multiline edit support.</li> + <li>Tab completion of variable and module names.</li> + </ul> +  + </section> +  + </chapter>