cd0bd92002-07-15Martin Nilsson <!-- 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>