PageRenderTime 46ms CodeModel.GetById 15ms RepoModel.GetById 0ms app.codeStats 1ms

/jEdit/tags/jedit-4-3-pre5/doc/users-guide/bsh-commands.xml

#
XML | 673 lines | 459 code | 67 blank | 147 comment | 0 complexity | 41316f49473f95c1e6b164566d6fd002 MD5 | raw file
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0
  1. <!-- jEdit 3.2 Macro Guide, (C) 2001 John Gellene -->
  2. <!-- Thu Jun 21 23:49:14 EDT 2001 @200 /Internet Time/ -->
  3. <!-- -->
  4. <!-- jEdit buffer-local properties: -->
  5. <!-- :indentSize=1:noTabs=yes:maxLineLen=72:tabSize=2: -->
  6. <!-- :xml.root=users-guide.xml: -->
  7. <chapter id="bsh-commands"><title>BeanShell Commands</title>
  8. <para>
  9. BeanShell includes a set of <firstterm>commands</firstterm>;
  10. subroutines that
  11. can be called from any script or macro. The following is a summary of
  12. those commands which may be useful within jEdit.
  13. </para>
  14. <note>
  15. <para>
  16. Java classes in plugins cannot make use of BeanShell commands directly. However, these commands can be called from BeanShell code that is part of a plugin, for example the snippets in <filename>actions.xml</filename>, or any BeanShell scripts shipped with the plugin and loaded on startup.
  17. </para>
  18. </note>
  19. <sect1 id="bsh-commands-output"><title>Output Commands</title>
  20. <itemizedlist>
  21. <!-- one day jEdit will provide its own error() implementation -->
  22. <!-- <listitem>
  23. <funcsynopsis>
  24. <funcprototype>
  25. <funcdef>void <function>error</function></funcdef>
  26. <paramdef>String <parameter>errorMsg</parameter></paramdef>
  27. </funcprototype>
  28. </funcsynopsis>
  29. <para>
  30. Writes the string represented by <parameter>errorMsg</parameter>
  31. to the error stream of the current process.
  32. </para>
  33. </listitem> -->
  34. <listitem>
  35. <funcsynopsis>
  36. <funcprototype>
  37. <funcdef>void <function>cat</function></funcdef>
  38. <paramdef>String <parameter>filename</parameter></paramdef>
  39. </funcprototype>
  40. </funcsynopsis>
  41. <para>
  42. Writes the contents of <parameter>filename</parameter>
  43. to the activity log.
  44. </para>
  45. </listitem>
  46. <listitem>
  47. <funcsynopsis>
  48. <funcprototype>
  49. <funcdef>void <function>javap</function></funcdef>
  50. <paramdef>String | Object | Class <parameter>target</parameter></paramdef>
  51. </funcprototype>
  52. </funcsynopsis>
  53. <para>
  54. Writes the public fields and methods of the specified class to
  55. the output stream of the current process. Requires Java 2
  56. version 1.3 or greater.
  57. </para>
  58. </listitem>
  59. <listitem>
  60. <funcsynopsis>
  61. <funcprototype>
  62. <funcdef>void <function>print</function></funcdef>
  63. <paramdef><parameter>arg</parameter></paramdef>
  64. </funcprototype>
  65. </funcsynopsis>
  66. <para>
  67. Writes the string value of the argument to the activity log,
  68. or if run from the <application>Console</application> plugin,
  69. to the current output window. If <parameter>arg</parameter> is
  70. an array, <function>print</function> runs itself recursively
  71. on the array's elements.
  72. </para>
  73. </listitem>
  74. </itemizedlist>
  75. </sect1>
  76. <sect1 id="bsh-commands-file"><title>File Management Commands</title>
  77. <itemizedlist>
  78. <listitem>
  79. <funcsynopsis>
  80. <funcprototype>
  81. <funcdef>void <function>cd</function></funcdef>
  82. <paramdef>String <parameter>dirname</parameter></paramdef>
  83. </funcprototype>
  84. </funcsynopsis>
  85. <para>
  86. Changes the working directory of the BeanShell interpreter
  87. to <parameter>dirname</parameter>.
  88. </para>
  89. </listitem>
  90. <listitem>
  91. <funcsynopsis>
  92. <funcprototype>
  93. <funcdef>void <function>cp</function></funcdef>
  94. <paramdef>String <parameter>fromFile</parameter></paramdef>
  95. <paramdef>String <parameter>toFile</parameter></paramdef>
  96. </funcprototype>
  97. </funcsynopsis>
  98. <para>
  99. Copy <parameter>fromFile</parameter> to <parameter>toFile</parameter>.
  100. </para>
  101. </listitem>
  102. <listitem>
  103. <funcsynopsis>
  104. <funcprototype>
  105. <funcdef>void <function>dir</function></funcdef>
  106. <paramdef>String <parameter>dirname</parameter></paramdef>
  107. </funcprototype>
  108. </funcsynopsis>
  109. <para>
  110. Displays the contents of directory <parameter>dirname</parameter>.
  111. The format of the display is similar to the Unix
  112. <function>ls -l</function> command.
  113. </para>
  114. </listitem>
  115. <listitem>
  116. <funcsynopsis>
  117. <funcprototype>
  118. <funcdef>void <function>mv</function></funcdef>
  119. <paramdef>String <parameter>fromFile</parameter></paramdef>
  120. <paramdef>String <parameter>toFile</parameter></paramdef>
  121. </funcprototype>
  122. </funcsynopsis>
  123. <para>
  124. Moves the file named by <parameter>fromFile</parameter> to
  125. <parameter>toFile</parameter>.
  126. </para>
  127. </listitem>
  128. <listitem>
  129. <funcsynopsis>
  130. <funcprototype>
  131. <funcdef>File <function>pathToFile</function></funcdef>
  132. <paramdef>String <parameter>filename</parameter></paramdef>
  133. </funcprototype>
  134. </funcsynopsis>
  135. <para>
  136. Create a <classname>File</classname> object corresponding to
  137. <function>filename</function>. Relative paths are resolved with
  138. reference to the BeanShell interpreter's working
  139. directory.
  140. </para>
  141. </listitem>
  142. <listitem>
  143. <funcsynopsis>
  144. <funcprototype>
  145. <funcdef>void <function>pwd</function></funcdef>
  146. <void/>
  147. </funcprototype>
  148. </funcsynopsis>
  149. <para>
  150. Writes the current working directory of the BeanShell interpreter
  151. to the output stream of the current process.
  152. </para>
  153. </listitem>
  154. <listitem>
  155. <funcsynopsis>
  156. <funcprototype>
  157. <funcdef>void <function>rm</function></funcdef>
  158. <paramdef>String <parameter>pathname</parameter></paramdef>
  159. </funcprototype>
  160. </funcsynopsis>
  161. <para>
  162. Deletes the file name by <parameter>pathname</parameter>.
  163. </para>
  164. </listitem>
  165. </itemizedlist>
  166. </sect1>
  167. <sect1 id="bsh-commands-serial"><title>Component Commands</title>
  168. <itemizedlist>
  169. <listitem>
  170. <funcsynopsis>
  171. <funcprototype>
  172. <funcdef>JFrame <function>frame</function></funcdef>
  173. <paramdef>Component <parameter>frame</parameter></paramdef>
  174. </funcprototype>
  175. </funcsynopsis>
  176. <para>
  177. Displays the component in a top-level <classname>JFrame</classname>,
  178. centered and packed. Returns the <classname>JFrame</classname> object.
  179. </para>
  180. </listitem>
  181. <listitem>
  182. <funcsynopsis>
  183. <funcprototype>
  184. <funcdef>Object <function>load</function></funcdef>
  185. <paramdef>String <parameter>filename</parameter></paramdef>
  186. </funcprototype>
  187. </funcsynopsis>
  188. <para>
  189. Loads and returns a serialized Java object from
  190. <parameter>filename</parameter>.
  191. </para>
  192. </listitem>
  193. <listitem>
  194. <funcsynopsis>
  195. <funcprototype>
  196. <funcdef>void <function>save</function></funcdef>
  197. <paramdef>Component <parameter>component</parameter></paramdef>
  198. <paramdef>String <parameter>filename</parameter></paramdef>
  199. </funcprototype>
  200. </funcsynopsis>
  201. <para>
  202. Saves <parameter>component</parameter> in serialized form
  203. to <parameter>filename</parameter>.
  204. </para>
  205. </listitem>
  206. <listitem>
  207. <funcsynopsis>
  208. <funcprototype>
  209. <funcdef>Font <function>setFont</function></funcdef>
  210. <paramdef>Component <parameter>comp</parameter></paramdef>
  211. <paramdef>int <parameter>ptsize</parameter></paramdef>
  212. </funcprototype>
  213. </funcsynopsis>
  214. <para>
  215. Set the font size of <parameter>component</parameter> to
  216. <parameter>ptsize</parameter> and returns the new
  217. font.
  218. </para>
  219. </listitem>
  220. </itemizedlist>
  221. </sect1>
  222. <sect1 id="bsh-commands-resource">
  223. <title>Resource Management Commands</title>
  224. <itemizedlist>
  225. <listitem>
  226. <funcsynopsis>
  227. <funcprototype>
  228. <funcdef>URL <function>getResource</function></funcdef>
  229. <paramdef>String <parameter>path</parameter></paramdef>
  230. </funcprototype>
  231. </funcsynopsis>
  232. <para>
  233. Returns the resource specified by <parameter>path</parameter>.
  234. An absolute path must be used to return any resource available in
  235. the current classpath.
  236. </para>
  237. </listitem>
  238. <!-- bsh.classpath not supported in jEdit -->
  239. <!--
  240. <listitem>
  241. <funcsynopsis>
  242. <funcprototype>
  243. <funcdef>void <function>addClassPath</function></funcdef>
  244. <paramdef>String <parameter>path</parameter></paramdef>
  245. </funcprototype>
  246. </funcsynopsis>
  247. </listitem>
  248. <listitem>
  249. <funcsynopsis>
  250. <funcprototype>
  251. <funcdef>void <function>addClassPath</function></funcdef>
  252. <paramdef>URL <parameter>path</parameter></paramdef>
  253. </funcprototype>
  254. </funcsynopsis>
  255. <para>
  256. Adds the directory or jar archive file specified by
  257. <parameter>path</parameter> to the classpath used by the
  258. interpreter.
  259. </para>
  260. </listitem>
  261. <listitem>
  262. <funcsynopsis>
  263. <funcprototype>
  264. <funcdef>void <function>setClassPath</function></funcdef>
  265. <paramdef>URL[] <parameter>paths</parameter></paramdef>
  266. </funcprototype>
  267. </funcsynopsis>
  268. <para>
  269. Changes the classpath for the BeanShell interpreter to the specified
  270. array of directories and/or archives.
  271. </para>
  272. </listitem>
  273. <listitem>
  274. <funcsynopsis>
  275. <funcprototype>
  276. <funcdef>URL[] <function>getClassPath</function></funcdef>
  277. <void/>
  278. </funcprototype>
  279. </funcsynopsis>
  280. <para>
  281. Returns an array containing the current classpath.
  282. </para>
  283. </listitem>
  284. <listitem>
  285. <funcsynopsis>
  286. <funcprototype>
  287. <funcdef>void <function>reloadClasses</function></funcdef>
  288. <paramdef>String <parameter>packagename</parameter></paramdef>
  289. </funcprototype>
  290. </funcsynopsis>
  291. </listitem>
  292. <listitem>
  293. <funcsynopsis>
  294. <funcprototype>
  295. <funcdef>void <function>reloadClasses</function></funcdef>
  296. <void/>
  297. </funcprototype>
  298. </funcsynopsis>
  299. <para>
  300. Reloads the class or package specified by
  301. <parameter>packagename</parameter> in the BeanShell interpreter.
  302. If called without a parameter, reloads all classes
  303. in the interpreter's classpath.
  304. </para>
  305. </listitem>
  306. <listitem>
  307. <funcsynopsis>
  308. <funcprototype>
  309. <funcdef>Class <function>getClass</function></funcdef>
  310. <paramdef>String <parameter>classname</parameter></paramdef>
  311. </funcprototype>
  312. </funcsynopsis>
  313. <para>
  314. This method is similar to the <function>Class.forName()</function>
  315. method of the Java platform, but it uses the classpath of the
  316. current BeanShell interpreter, which can contain additional
  317. classes and packages as well as reloaded classes.
  318. </para>
  319. </listitem> -->
  320. </itemizedlist>
  321. </sect1>
  322. <sect1 id="bsh-commands-script"><title>Script Execution Commands</title>
  323. <itemizedlist>
  324. <listitem>
  325. <funcsynopsis>
  326. <funcprototype>
  327. <funcdef>Thread <function>bg</function></funcdef>
  328. <paramdef>String <parameter>filename</parameter></paramdef>
  329. </funcprototype>
  330. </funcsynopsis>
  331. <para>
  332. Run the BeanShell script named by <parameter>filename</parameter>
  333. in a copy of the existing namespace and in a separate thread. Returns
  334. the <classname>Thread</classname> object so created.
  335. </para>
  336. </listitem>
  337. <listitem>
  338. <funcsynopsis>
  339. <funcprototype>
  340. <funcdef>void <function>exec</function></funcdef>
  341. <paramdef>String <parameter>cmdline</parameter></paramdef>
  342. </funcprototype>
  343. </funcsynopsis>
  344. <para>
  345. Start the external process by calling
  346. <function>Runtime.exec()</function> on
  347. <parameter>cmdline</parameter>. Any output is directed to the
  348. output stream of the calling process.
  349. </para>
  350. </listitem>
  351. <listitem>
  352. <funcsynopsis>
  353. <funcprototype>
  354. <funcdef>Object <function>eval</function></funcdef>
  355. <paramdef>String <parameter>expression</parameter></paramdef>
  356. </funcprototype>
  357. </funcsynopsis>
  358. <para>
  359. Evaluates the string <parameter>expression</parameter> as
  360. a BeanShell script in the interpreter's current namespace.
  361. Returns the result of the evaluation of <constant>null</constant>.
  362. </para>
  363. </listitem>
  364. <listitem>
  365. <funcsynopsis>
  366. <funcprototype>
  367. <funcdef>bsh.This <function>run</function></funcdef>
  368. <paramdef>String <parameter>filename</parameter></paramdef>
  369. </funcprototype>
  370. </funcsynopsis>
  371. <para>
  372. Run the BeanShell script named by <parameter>filename</parameter>
  373. in a copy of the existing namespace. The return value represent
  374. the object context of the script, allowing you to access its variables
  375. and methods.
  376. </para>
  377. </listitem>
  378. <listitem>
  379. <funcsynopsis>
  380. <funcprototype>
  381. <funcdef>void <function>setAccessibility</function></funcdef>
  382. <paramdef>boolean <parameter>flag</parameter></paramdef>
  383. </funcprototype>
  384. </funcsynopsis>
  385. <para>
  386. If <parameter>flag</parameter> is <literal>true</literal>,
  387. BeanShell scripts are allowed to change and modify private variables, and call private methods. The default is <literal>false</literal>.
  388. </para>
  389. </listitem>
  390. <listitem>
  391. <funcsynopsis>
  392. <funcprototype>
  393. <funcdef>void <function>setStrictJava</function></funcdef>
  394. <paramdef>boolean <parameter>flag</parameter></paramdef>
  395. </funcprototype>
  396. </funcsynopsis>
  397. <para>
  398. If <parameter>flag</parameter> is <literal>true</literal>,
  399. BeanShell scripts must follow a much more strict, Java-like syntax, and are not able to use the convenience features described in <xref linkend="macro-tips-BeanShell-convenience" />.
  400. </para>
  401. </listitem>
  402. <!-- <listitem>
  403. <funcsynopsis>
  404. <funcprototype>
  405. <funcdef>void <function>server</function></funcdef>
  406. <paramdef>int <parameter>port</parameter></paramdef>
  407. </funcprototype>
  408. </funcsynopsis>
  409. <para>
  410. Creates a <quote>server</quote> version of the BeanShell
  411. interpreter that shares the same namespace as the current
  412. interpreter. The server interpreter listens on the designated
  413. port.
  414. </para>
  415. <para>
  416. This requires the <classname>bsh.util</classname> package, which
  417. is not included with jEdit. It can be found in the stand-alone
  418. BeanShell distribution, available from <ulink
  419. url="http://www.beanshell.org">http://www.beanshell.org</ulink>.
  420. </para>
  421. <caution><para>
  422. Security of this port is not guaranteed. Use this command
  423. with extreme caution.
  424. </para></caution>
  425. </listitem> -->
  426. <listitem>
  427. <funcsynopsis>
  428. <funcprototype>
  429. <funcdef>void <function>source</function></funcdef>
  430. <paramdef>String <parameter>filename</parameter></paramdef>
  431. </funcprototype>
  432. </funcsynopsis>
  433. <para>
  434. Evaluates the contents of <parameter>filename</parameter>
  435. as a BeanShell script in the interpreter's current namespace.
  436. </para>
  437. </listitem>
  438. </itemizedlist>
  439. </sect1>
  440. <sect1 id="bsh-commands-object">
  441. <title>BeanShell Object Management Commands</title>
  442. <itemizedlist>
  443. <listitem>
  444. <funcsynopsis>
  445. <funcprototype>
  446. <funcdef><function>bind</function></funcdef>
  447. <paramdef>bsh.This <parameter>ths</parameter></paramdef>
  448. <paramdef>bsh.Namespace <parameter>namespace</parameter></paramdef>
  449. </funcprototype>
  450. </funcsynopsis>
  451. <para>
  452. Binds the scripted object <parameter>ths</parameter> to
  453. <parameter>namespace</parameter>.
  454. </para>
  455. </listitem>
  456. <listitem>
  457. <funcsynopsis>
  458. <funcprototype>
  459. <funcdef>void <function>clear</function></funcdef>
  460. <void/>
  461. </funcprototype>
  462. </funcsynopsis>
  463. <para>
  464. Clear all variables, methods, and imports from this namespace.
  465. If this namespace is the root, it will be reset to the default
  466. imports.
  467. </para>
  468. </listitem>
  469. <listitem>
  470. <funcsynopsis>
  471. <funcprototype>
  472. <funcdef>bsh.This <function>extend</function></funcdef>
  473. <paramdef>bsh.This <parameter>object</parameter></paramdef>
  474. </funcprototype>
  475. </funcsynopsis>
  476. <para>
  477. Creates a new BeanShell <classname>This</classname> scripted object
  478. that is a child of the parameter <parameter>object</parameter>.
  479. </para>
  480. </listitem>
  481. <listitem>
  482. <funcsynopsis>
  483. <funcprototype>
  484. <funcdef>void <function>importObject</function></funcdef>
  485. <paramdef>Object <parameter>object</parameter></paramdef>
  486. </funcprototype>
  487. </funcsynopsis>
  488. <para>
  489. Import an object into this namespace. This is somewhat similar to Java 1.5 static class imports, except you can import the methods and fields of a Java object instance into
  490. a BeanShell namespace, for example:
  491. </para>
  492. <informalexample><programlisting><![CDATA[Map map = new HashMap();
  493. importObject( map );
  494. put("foo", "bar");
  495. print( get("foo") ); // "bar"]]></programlisting></informalexample>
  496. </listitem>
  497. <listitem>
  498. <funcsynopsis>
  499. <funcprototype>
  500. <funcdef>bsh.This <function>object</function></funcdef>
  501. <void/>
  502. </funcprototype>
  503. </funcsynopsis>
  504. <para>
  505. Creates a new BeanShell <classname>This</classname> scripted object which
  506. can hold data members. You can use this to create an object for
  507. storing miscellaneous crufties, like so:
  508. </para>
  509. <informalexample><programlisting>crufties = object();
  510. crufties.foo = "hello world";
  511. crufties.counter = 5;
  512. ...</programlisting></informalexample>
  513. </listitem>
  514. <listitem>
  515. <funcsynopsis>
  516. <funcprototype>
  517. <funcdef><function>setNameSpace</function></funcdef>
  518. <paramdef>bsh.Namespace <parameter>namespace</parameter></paramdef>
  519. </funcprototype>
  520. </funcsynopsis>
  521. <para>
  522. Set the namespace of the current scope to
  523. <parameter>namespace</parameter>.
  524. </para>
  525. </listitem>
  526. <listitem>
  527. <funcsynopsis>
  528. <funcprototype>
  529. <funcdef>bsh.This <function>super</function></funcdef>
  530. <paramdef>String <parameter>scopename</parameter></paramdef>
  531. </funcprototype>
  532. </funcsynopsis>
  533. <para>
  534. Returns a reference to the BeanShell <classname>This</classname>
  535. object representing the enclosing method scope specified
  536. by <parameter>scopename</parameter>. This method work similar to
  537. the <function>super</function> keyword but can refer to enclosing
  538. scope at higher levels in a hierarchy of scopes.
  539. </para>
  540. </listitem>
  541. <listitem>
  542. <funcsynopsis>
  543. <funcprototype>
  544. <funcdef>void <function>unset</function></funcdef>
  545. <paramdef>String <parameter>name</parameter></paramdef>
  546. </funcprototype>
  547. </funcsynopsis>
  548. <para>
  549. Removes the variable named by <parameter>name</parameter> from
  550. the current interpreter namespace. This has the effect of
  551. <quote>undefining</quote> the variable.
  552. </para>
  553. </listitem>
  554. </itemizedlist>
  555. </sect1>
  556. <sect1 id="bsh-commands-other"><title>Other Commands</title>
  557. <itemizedlist>
  558. <!-- <listitem>
  559. <funcsynopsis>
  560. <funcprototype>
  561. <funcdef>void <function>exit</function></funcdef>
  562. <void/>
  563. </funcprototype>
  564. </funcsynopsis>
  565. <para>
  566. Calls <function>System.exit(0)</function>.
  567. </para>
  568. <caution><para>
  569. While this command is available, you should always call
  570. <function>jEdit.exit()</function> instead so the application will
  571. shutdown in an orderly fashion.
  572. </para></caution>
  573. </listitem> -->
  574. <listitem>
  575. <funcsynopsis>
  576. <funcprototype>
  577. <funcdef>void <function>debug</function></funcdef>
  578. <void/>
  579. </funcprototype>
  580. </funcsynopsis>
  581. <para>
  582. Toggles BeanShell's internal debug reporting to the
  583. output stream of the current process.
  584. </para>
  585. </listitem>
  586. <listitem>
  587. <funcsynopsis>
  588. <funcprototype>
  589. <funcdef><function>getSourceFileInfo</function></funcdef>
  590. <void/>
  591. </funcprototype>
  592. </funcsynopsis>
  593. <para>
  594. Returns the name of the file or other source from which the
  595. BeanShell interpreter is reading.
  596. </para>
  597. </listitem>
  598. </itemizedlist>
  599. </sect1>
  600. </chapter>