1<!DOCTYPE book 2 PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 "http://www.docbook.org/xml/4.1.2/docbookx.dtd"> 4 5<book> 6 <bookinfo> 7 <title> 8 JLine 9 </title> 10 <copyright> 11 <year>2002, 2003, 2004, 2005, 2006, 2007</year> 12 <holder>Marc Prud'hommeaux</holder> 13 </copyright> 14 </bookinfo> 15 <part id="manual"> 16 <title>JLine Manual</title> 17 18 <chapter id="introduction"> 19 <title>Introduction</title> 20 <para> 21 JLine is a Java library for handling console input. 22 It is similar in functionality to BSD editline and GNU 23 readline. People familiar with the readline/editline 24 capabilities for modern shells (such as bash and tcsh) will 25 find most of the command editing features of JLine to 26 be familiar. 27 </para> 28 </chapter> 29 30 <chapter id="license"> 31 <title>License and Terms of Use</title> 32 <para> 33 JLine is distributed under the BSD license, meaning that 34 you are completely free to redistribute, modify, or sell it 35 with almost no restrictins. 36 For more information on the BSD license, see 37 <ulink url="http://www.opensource.org/licenses/bsd-license.php" 38 >http://www.opensource.org/licenses/bsd-license.php</ulink>. 39 </para> 40 <para> 41 For information on obtaining the software under another 42 license, contact the copyright holder: 43 <ulink url="mailto:[email protected]">[email protected]</ulink>. 44 </para> 45 </chapter> 46 47 <chapter id="obtaining"> 48 <title>Obtaining JLine</title> 49 <para> 50 JLine is hosted on SourceForge, and is located at 51 <ulink url="http://jline.sf.net">http://jline.sf.net</ulink>. 52 The latest release can be downloaded from 53 <ulink url= 54 "http://sourceforge.net/project/showfiles.php?group_id=64033">http://sourceforge.net/project/showfiles.php?group_id=64033</ulink>. 55 API documentation can be found in the 56 <ulink url="apidocs">apidocs/</ulink> directory. 57 </para> 58 </chapter> 59 60 <chapter id="installation"> 61 <title>Installation</title> 62 <para> 63 JLine has no library dependencies, aside from a JVM 64 of version 1.2 or higher. To install JLine, download the 65 <filename>jline.jar</filename> file, and either place it in 66 the system-wide java extensions directory, or 67 manually add it to your 68 <computeroutput>CLASSPATH</computeroutput>. 69 The extensions directory is dependent on your operating 70 system. Some few examples are: 71 <itemizedlist> 72 <listitem><para> 73 Macintosh OS X: 74 <filename>/Library/Java/Extensions</filename> or 75 <filename>/System/Library/Java/Extensions</filename> 76 </para></listitem> 77 <listitem><para> 78 Microsoft Windows: 79 <filename>JAVAHOME\jre\lib\ext</filename> 80 (example: 81 <filename>C:\j2sdk1.4.1_03\jre\lib\ext</filename>) 82 </para></listitem> 83 <listitem><para> 84 UNIX Systems: 85 <filename>JAVAHOME/jre/lib/ext</filename> 86 (example: 87 <filename>/usr/local/java/jre/lib/ext</filename>) 88 </para></listitem> 89 </itemizedlist> 90 </para> 91 <para> 92 JLine is not 100% pure Java. On Windows, it relies on a 93 <filename>.dll</filename> file to initialize the terminal 94 to be able to accept unbuffered input. However, 95 no installation is necessary for this: when initialized, 96 JLine will dynamically extract the DLL to a temporary 97 directory and load it. For more details, see the 98 documentation for the <classname>jline.WindowsTerminal</classname> class. 99 </para> 100 <para> 101 On UNIX systems (including Macintosh OS X), JLine will 102 execute the <filename>stty</filename> command to initialize 103 the terminal to allow unbuffered input. For more details, 104 see the documentation for the <classname>jline.UnixTerminal</classname> class. 105 </para> 106 <para> 107 For both Windows and UNIX systems, JLine will fail to 108 initialize if it is run inside a strict security manager 109 that does not allow the loading of libraries, writing 110 to the file system, or executing external programs. However, 111 for most console applications, this is usually not the case. 112 </para> 113 </chapter> 114 <chapter id="supported_platforms"> 115 <title>Supported Platforms</title> 116 <para> 117 JLine should work on any Windows system, or any 118 minimally compliant POSIX system (includling Linux and 119 Macintosh OS X). 120 </para> 121 <para> 122 The platforms on which JLine has been confirmed to work are: 123 <itemizedlist> 124 <listitem><para> 125 Microsoft Windows XP 126 </para></listitem> 127 <listitem><para> 128 RedHat Linux 9.0 129 </para></listitem> 130 <listitem><para> 131 Debian Linux 3.0 132 </para></listitem> 133 <listitem><para> 134 Macintosh OS X 10.3 135 </para></listitem> 136 </itemizedlist> 137 </para> 138 <para> 139 Please report successes or failures to the author: 140 <ulink url="mailto:[email protected]">[email protected]</ulink>. 141 </para> 142 </chapter> 143 <chapter id="features"> 144 <title>Features</title> 145 <section id="features_history"> 146 <title>Command History</title> 147 <para> 148 </para> 149 </section> 150 <section id="features_completion"> 151 <title>Tab completion</title> 152 <para> 153 </para> 154 </section> 155 <section id="features_line_editing"> 156 <title>Line editing</title> 157 <para> 158 </para> 159 </section> 160 <section id="features_keybindings"> 161 <title>Custom Keybindings</title> 162 <para> 163 You can create your own keybindings by creating a 164 <filename>HOME/.jlinebindings.properties"</filename> 165 file. You can override the location of this file with 166 the "<computeroutput>jline.keybindings</computeroutput>" 167 system property. 168 </para> 169 <!-- 170 <para> 171 The default keybindings are as follows: 172 <programlisting> 173 </programlisting> 174 </para> 175 --> 176 </section> 177 <section id="features_masking"> 178 <title>Character masking</title> 179 <para> 180 </para> 181 </section> 182 </chapter> 183 <chapter id="api"> 184 <title>API</title> 185 <para> 186 This section discusses some common usages of the JLine API. 187 For in-depth usage of the JLine API, see the 188 <ulink url="apidocs">apidocs</ulink>. 189 </para> 190 <section id="reading_password"> 191 <title>Reading a password from the console</title> 192 <para> 193 A common task that console applications need to do is 194 read in a password. While it is standard for software 195 to not echo password strings as they are typed, 196 the Java core APIs surprisingly do not provide any 197 means to do this. 198 </para> 199 <para> 200 JLine can read a password with the following code: 201 <programlisting> 202String password = new <classname>jline.ConsoleReader</classname>().readLine(new Character('*')); 203 </programlisting> 204 This will replace every character types on the console 205 with a star character. 206 </para> 207 <para> 208 Alternately, you can have it not echo password 209 character at all: 210 <programlisting> 211String password = new <classname>jline.ConsoleReader</classname>().readLine(new Character(0)); 212 </programlisting> 213 </para> 214 <para> 215 The <filename>jline-demo.jar</filename> file contains 216 a sample application that reads the password. To run 217 the sample, execute: 218 <programlisting> 219java -cp jline-demo.jar jline.example.PasswordReader "*" 220 </programlisting> 221 </para> 222 </section> 223 </chapter> 224 <chapter id="faq"> 225 <title>Frequently Asked Questions</title> 226 <section id="faq_unsupported_platform"><title> 227 Can I disable JLine if it isn't working on my platform? 228 </title> 229 <para> 230 You can disable JLine by setting the System property 231 "<computeroutput>jline.terminal</computeroutput>" 232 to 233 "<classname>jline.UnsupportedTerminal</classname>". For example: 234 <programlisting> 235java -Djline.terminal=jline.UnsupportedTerminal jline.example.Example simple 236 </programlisting> 237 </para> 238 </section> 239 <section id="faq_custom_keybindings"><title> 240 How do I customize the key bindings? 241 </title> 242 <para> 243 You can create your own keybindings by creating a 244 <filename>HOME/.jlinebindings.properties"</filename> 245 file. You can override the location of this file with 246 the "<computeroutput>jline.keybindings</computeroutput>" 247 system property. To examine the format to use, see the 248 <filename>src/jline/keybindings.properties</filename> 249 file in the source distribution. 250 </para> 251 </section> 252 <section id="faq_jline_as_default"><title> 253 Can I use JLine as the default console input stream for 254 all applications? 255 </title> 256 <para> 257 No, but you can use the <classname>jline.ConsoleRunner</classname> application 258 to set up the system input stream and continue on 259 the launch another program. For example, to use JLine 260 as the input handler for the popular 261 <ulink url="http://www.beanshell.org">BeanShell</ulink> 262 console application, you can run: 263 <programlisting> 264java <classname>jline.ConsoleRunner</classname> <ulink url="http://www.beanshell.org/manual/standalonemode.html">bsh.Interpreter</ulink> 265 </programlisting> 266 </para> 267 </section> 268 <section id="faq_jline_beanshell"><title> 269 Can I use JLine as the input handler for <ulink url="http://www.beanshell.org">BeanShell</ulink>? 270 </title> 271 <para> 272 Yes. Try running: 273 <programlisting> 274java <classname>jline.ConsoleRunner</classname> <ulink url="http://www.beanshell.org/manual/standalonemode.html">bsh.Interpreter</ulink> 275 </programlisting> 276 </para> 277 </section> 278 <section id="faq_jline_jdb"><title> 279 Can I use JLine as the input handler for <ulink url="http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/jdb.html">jdb</ulink> (the java debugger)? 280 </title> 281 <para> 282 Yes. Try running: 283 <programlisting> 284java <classname>jline.ConsoleRunner</classname> com.sun.tools.example.debug.tty.TTY <emphasis>args</emphasis> 285 </programlisting> 286 </para> 287 </section> 288 <section id="faq_pure_java"><title> 289 Is JLine <trademark>100% pure Java</trademark>? 290 </title> 291 <para> 292 No: JLine uses a couple small native methods in the Windows 293 platform. On Unix, it is technically pure java, but relies 294 on the execution of external (non-java) programs. See the 295 <link linkend="installation">installation section</link> 296 for more details. 297 </para> 298 </section> 299 <section id="faq_password"><title> 300 How do I make it so password characters are no echoed 301 to the screen? 302 </title> 303 <para> 304 See <link linkend="reading_password"/>. 305 </para> 306 </section> 307 <section id="faq_cursrs"><title> 308 Is JLine a full-featured curses implementation? 309 </title> 310 <para> 311 No: JLine has no ability to position the cursor on the 312 console. It might someday evolve into a plausible 313 Java curses implementation. 314 </para> 315 </section> 316 </chapter> 317 </part> 318 319 <appendix id="known_bugs"> 320 <title>Known Bugs</title> 321 <itemizedlist> 322 <listitem><para> 323 Clearing the screen (CTRL-L) doesn't currently work on Windows. 324 </para></listitem> 325 </itemizedlist> 326 </appendix> 327 328 <appendix id="contributors"> 329 <title>Contributors</title> 330 <para> 331 The following people have contributed to improving JLine over the 332 years: 333 </para> 334 <itemizedlist> 335 <listitem><para> 336 Marc Prud'hommeaux 337 </para></listitem> 338 <listitem><para> 339 Damian Steer 340 </para></listitem> 341 <listitem><para> 342 Dale Kemp 343 </para></listitem> 344 <listitem><para> 345 Jun Liu 346 </para></listitem> 347 <listitem><para> 348 [email protected] 349 </para></listitem> 350 <listitem><para> 351 Simon Patarin 352 </para></listitem> 353 <listitem><para> 354 Amy Isard 355 </para></listitem> 356 <listitem><para> 357 Ryan Bell 358 </para></listitem> 359 <listitem><para> 360 Marc Herbert 361 </para></listitem> 362 <listitem><para> 363 Christian Salm 364 </para></listitem> 365 </itemizedlist> 366 </appendix> 367 368 <appendix id="todo"> 369 <title>Future enhancements</title> 370 <itemizedlist> 371 <listitem><para> 372 Add localization for all strings. 373 </para></listitem> 374 <listitem><para> 375 Create a BNFCompletor that can handle any BNF. 376 </para></listitem> 377 </itemizedlist> 378 </appendix> 379 380 <appendix id="changelog"> 381 <title>Change Log</title> 382 <itemizedlist> 383 <title>0.9.93 2007-11-13</title> 384 <listitem><para> 385 Fixed backspace handling on Unix/OS X. 386 </para></listitem> 387 </itemizedlist> 388 <itemizedlist> 389 <title>0.9.92 2007-10-30</title> 390 <listitem><para> 391 JLine now works with 64-bit Windows systems. 392 </para></listitem> 393 </itemizedlist> 394 <itemizedlist> 395 <title>0.9.91 2007-03-11</title> 396 <listitem><para> 397 Added ConsoleReader.setUsePagination() method which allows 398 configuration of pagination when the number of rows of 399 candidates exceeds the height of the detected terminal, thanks 400 to a patch by Damian Steer. 401 </para></listitem> 402 <listitem><para> 403 Better support for UTF-8 inputs (issue #1623521). 404 </para></listitem> 405 <listitem><para> 406 Improved list of supported keys on Windows (issue #1649790). 407 </para></listitem> 408 </itemizedlist> 409 <itemizedlist> 410 <title>0.9.5 2006-03-08</title> 411 <listitem><para> 412 Fixed problem with "stty" on Solaris, which doesn't 413 understand "stty size" to query the terminal size. It now 414 uses "stty -a", which supposedly outputs a POSIX standard 415 format. 416 </para></listitem> 417 <listitem><para> 418 Support HOME and END keys, thanks to a patch by 419 Dale Kemp. 420 </para></listitem> 421 </itemizedlist> 422 <itemizedlist> 423 <title>0.9.1 2005-01-29</title> 424 <listitem><para> 425 Fixed problem with the 0.9.0 distribution that 426 failed to include the Windows jline.dll in the jline.jar, 427 rendering it inoperable on Windows. 428 </para></listitem> 429 <listitem><para> 430 Implemented proper interception or arrow keys on Windows, 431 meaning that history can now be navigated with the UP 432 and DOWN keys, and line editing can take place with 433 the LEFT and RIGHT arrow keys. 434 </para></listitem> 435 </itemizedlist> 436 <itemizedlist> 437 <title>0.9.0 2005-01-23</title> 438 <listitem><para> 439 Changed license from GPL to BSD. 440 </para></listitem> 441 <listitem><para> 442 Made "CTRL-L" map to clearing the screen. 443 </para></listitem> 444 </itemizedlist> 445 <itemizedlist> 446 <title>0.8.1 2003-11-18</title> 447 <listitem><para> 448 Fixed accidental dependency on JVM 1.4. 449 </para></listitem> 450 </itemizedlist> 451 <itemizedlist> 452 <title>0.8.0 2003-11-17</title> 453 <listitem><para> 454 Windows support using a native .dll 455 </para></listitem> 456 <listitem><para> 457 A new ClassNameCompletor 458 </para></listitem> 459 <listitem><para> 460 Many doc improvements 461 </para></listitem> 462 </itemizedlist> 463 <itemizedlist> 464 <title>0.6.0 2003-07-08</title> 465 <listitem><para> 466 Many bugfixes 467 </para></listitem> 468 <listitem><para> 469 Better release system 470 </para></listitem> 471 <listitem><para> 472 Automatically set terminal property by 473 issuing stty on UNIX systems 474 </para></listitem> 475 <listitem><para> 476 Additional tab-completion handlers 477 </para></listitem> 478 <listitem><para> 479 Tested on Debian Linux and Mac OS 10.2 480 </para></listitem> 481 <listitem><para> 482 Example includes dictionary, filename, and simple completion 483 </para></listitem> 484 </itemizedlist> 485 <itemizedlist> 486 <title>0.3.0 2002-10-05</title> 487 <listitem><para> 488 Initial release 489 </para></listitem> 490 </itemizedlist> 491 </appendix> 492</book> 493