/jEdit/tags/jedit-4-0-pre3/doc/users-guide/bsh-commands.xml

<!-- jEdit 3.2 Macro Guide, (C) 2001 John Gellene                -->
<!-- Thu Jun 21 23:49:14 EDT 2001 @200 /Internet Time/           -->
<!--                                                             -->
<!-- jEdit buffer-local properties:                              -->
<!-- :indentSize=1:noTabs=yes:maxLineLen=72:tabSize=2:           -->

<chapter id="BeanShell-commands"><title>BeanShell Commands</title>

<para>
  BeanShell includes a set of <firstterm>commands</firstterm>;
  subroutines that
  can be called from any script or macro.  The following is a summary of
  those commands which may be useful within jEdit.
</para>

<note>
 <para>
  Plugins, because they are written in Java and not BeanShell,
  cannot make use of BeanShell commands.
 </para>
</note>

<sect1 id="BeanShell-commands-output"><title>Output Commands</title>

  <itemizedlist>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>print</function></funcdef>
          <paramdef><parameter>arg</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Writes the string value of the argument to the activity log,
        or if run from the <application>Console</application> plugin,
        to the current output window.  If <parameter>arg</parameter> is
        an array, <function>print</function> runs itself recursively
        on the array's elements.
      </para>
    </listitem>

    <!-- one day jEdit will provide its own error() implementation -->
    <!-- <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>error</function></funcdef>
          <paramdef>String <parameter>errorMsg</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Writes the string represented by <parameter>errorMsg</parameter>
        to the error stream of the current process.
      </para>
    </listitem> -->

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>cat</function></funcdef>
          <paramdef>String <parameter>filename</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Writes the contents of <parameter>filename</parameter>
        to the activity log.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>javap</function></funcdef>
          <paramdef>String | Object | Class <parameter>target</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Writes the public fields and methods of the specified class to
        the output stream of the current process.  Requires Java 2
        version 1.3 or greater.
      </para>
    </listitem>

  </itemizedlist>

</sect1>

<sect1 id="BeanShell-commands-file"><title>File Management Commands</title>

  <itemizedlist>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>dir</function></funcdef>
          <paramdef>String <parameter>dirname</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Displays the contents of directory <parameter>dirname</parameter>.
        The format of the display is similar to the Unix
        <function>ls -l</function> command.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>File <function>pathToFile</function></funcdef>
          <paramdef>String <parameter>filename</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Create a <classname>File</classname> object corresponding to
        <function>filename</function>.  Relative paths are resolved with
        reference to the BeanShell interpreter's working
        directory.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>cd</function></funcdef>
          <paramdef>String <parameter>dirname</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Changes the working directory of the BeanShell interpreter
        to <parameter>dirname</parameter>.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>pwd</function></funcdef>
          <void/>
        </funcprototype>
      </funcsynopsis>
      <para>
        Writes the current working directory of the BeanShell interpreter
        to the output stream of the current process.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef><function>mv</function></funcdef>
          <paramdef>String <parameter>fromFile</parameter></paramdef>
          <paramdef>String <parameter>toFile</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Moves the file named by <parameter>fromFile</parameter> to
        <parameter>toFile</parameter>.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>rm</function></funcdef>
          <paramdef>String <parameter>pathname</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Deletes the file name by <parameter>pathname</parameter>.
      </para>
    </listitem>

  </itemizedlist>

</sect1>
<sect1 id="BeanShell-commands-serial"><title>Component Commands</title>

  <itemizedlist>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>Object <function>load</function></funcdef>
          <paramdef>String <parameter>filename</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Loads and returns a serialized Java object from
        <parameter>filename</parameter>.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>save</function></funcdef>
          <paramdef>Component <parameter>component</parameter></paramdef>
          <paramdef>String <parameter>filename</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Saves <parameter>component</parameter> in serialized form
        to <parameter>filename</parameter>.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>JFrame <function>frame</function></funcdef>
          <paramdef>Component <parameter>frame</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Displays the component in a top-level <classname>JFrame</classname>,
        centered and packed.  Returns the <classname>JFrame</classname> object.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>Font <function>setFont</function></funcdef>
          <paramdef>Component <parameter>comp</parameter></paramdef>
          <paramdef>int <parameter>ptsize</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Set the font size of <parameter>component</parameter> to
        <parameter>ptsize</parameter> and returns the new
        font.
      </para>
    </listitem>

  </itemizedlist>

</sect1>


<sect1 id="BeanShell-commands-resource">
<title>Resource Management Commands</title>

  <itemizedlist>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>URL <function>getResource</function></funcdef>
          <paramdef>String <parameter>path</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Returns the resource specified by <parameter>path</parameter>.
        A absolute path must be used to return any resource available in
        the current classpath.
      </para>
    </listitem>

    <!-- bsh.classpath not supported in jEdit -->
    <!--
    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>addClassPath</function></funcdef>
          <paramdef>String <parameter>path</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>addClassPath</function></funcdef>
          <paramdef>URL <parameter>path</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Adds the directory or jar archive file specified by
        <parameter>path</parameter> to the classpath used by the
        interpreter.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>setClassPath</function></funcdef>
          <paramdef>URL[] <parameter>paths</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Changes the classpath for the BeanShell interpreter to the specified
        array of directories and/or archives.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>URL[] <function>getClassPath</function></funcdef>
          <void/>
        </funcprototype>
      </funcsynopsis>
      <para>
        Retruns an array containing the current classpath.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>reloadClasses</function></funcdef>
          <paramdef>String <parameter>packagename</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>reloadClasses</function></funcdef>
          <void/>
        </funcprototype>
      </funcsynopsis>
      <para>
        Reloads the class or package specified by
        <parameter>packagename</parameter> in the BeanShell interpreter.
        If called without a parameter, releads all classes
        in the interpreter's classpath.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>Class <function>getClass</function></funcdef>
          <paramdef>String <parameter>classname</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        This method is similar to the <function>Class.forName()</function>
        method of the Java platform, but it uses the classpath of the
        current BeanShell interpreter, which can contain additional
        classes and packages as well as reloaded classes.
      </para>
    </listitem> -->

  </itemizedlist>

</sect1>

<sect1 id="BeanShell-commands-script"><title>Script Execution Commands</title>

  <itemizedlist>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef><function>exec</function></funcdef>
          <paramdef>String <parameter>cmdline</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Start the external process by calling
        <function>Runtime.exec()</function> on
        <parameter>cmdline</parameter>. Any output is directed to the
        output stream of the calling process.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>source</function></funcdef>
          <paramdef>String <parameter>filename</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Evaluates the contents of <parameter>filename</parameter>
        as a BeanShell script in the interpreter's current namespace.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>Object <function>eval</function></funcdef>
          <paramdef>String <parameter>expression</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Evaluates the string <parameter>expression</parameter> as
        a BeanShell script in the interpreter's current namespace.
        Returns the result of the evaluation of <constant>null</constant>.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>bsh.This <function>run</function></funcdef>
          <paramdef>String <parameter>filename</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Run the BeanShell script named by <parameter>filename</parameter>
        in a copy of the existing namespace.  The return value represent
        the object context of the script, allowing you to access its variables
        and methods.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>Thread <function>bg</function></funcdef>
          <paramdef>String <parameter>filename</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Run the BeanShell script named by <parameter>filename</parameter>
        in a copy of the existing namespace and in a separate thread.  Returns
        the <classname>Thread</classname> object so created.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>server</function></funcdef>
          <paramdef>int <parameter>port</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Createes a <quote>server</quote> version of the BeanShell
        interpreter that shares the same namespace as the current
        interpreter.  The server interpreter listens on the designated
        port.
      </para>
      <para>
        This requires the <classname>bsh.util</classname> package, which
        is not included with jEdit. It can be found in the stand-alone
        BeanShell distribution, available from <ulink
        url="http://www.beanshell.org">http://www.beanshell.org</ulink>.
      </para>
      <caution><para>
        Security of this port is not guaranteed.  Use this command
        with extreme caution.
      </para></caution>
    </listitem>

  </itemizedlist>

</sect1>

<sect1 id="BeanShell-commands-object">
<title>BeanShell Object Management Commands</title>

  <itemizedlist>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>bsh.This <function>object</function></funcdef>
          <void/>
        </funcprototype>
      </funcsynopsis>
      <para>
        Creates a new BeanShell <classname>This</classname> scripted object which
        can hold data members. You can use this to create an object for
        storing miscellaneous crufties, like so:
      </para>
      <informalexample><programlisting>crufties = object();
crufties.foo = "hello world";
crufties.counter = 5;
...</programlisting></informalexample>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>bsh.This <function>extend</function></funcdef>
          <paramdef>bsh.This <parameter>object</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Creates a new BeanShell <classname>This</classname> scripted object
        that is a child of the parameter <parameter>object</parameter>.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>bsh.This <function>super</function></funcdef>
          <paramdef>String <parameter>scopename</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Returns a refernece to the BeanShell <classname>This</classname>
        object representing the enclosing method scope specified
        by <parameter>scopename</parameter>.  This method work similar to
        the <function>super</function> keyword but can refer to enclosing
        scope at higher levels in a hierarchy of scopes.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef><function>bind</function></funcdef>
          <paramdef>bsh.This <parameter>ths</parameter></paramdef>
          <paramdef>bsh.Namespace <parameter>namespace</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Binds the scripted object <parameter>ths</parameter> to
        <parameter>namespace</parameter>.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>unset</function></funcdef>
          <paramdef>String <parameter>name</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Removes the variable named by <parameter>name</parameter> from
        the current interpreter namespace.  This has the effect of
        <quote>undefining</quote> the variable.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef><function>setNameSpace</function></funcdef>
          <paramdef>bsh.Namespace <parameter>namespace</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Set the namespace of the current scope to
        <parameter>namespace</parameter>.
      </para>
    </listitem>

  </itemizedlist>

</sect1>

<sect1 id="BeanShell-commands-other"><title>Other Commands</title>

  <itemizedlist>
    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>exit</function></funcdef>
          <void/>
        </funcprototype>
      </funcsynopsis>
      <para>
        Calls <function>System.exit(0)</function>.
      </para>
      <caution><para>
        While this command is available, you should always call
        <function>jEdit.exit()</function> instead so the application will
        shutdown in an orderly fashion.
      </para></caution>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>debug</function></funcdef>
          <void/>
        </funcprototype>
      </funcsynopsis>
      <para>
        Toggles BeanShell's internal debug reporting to the
        output stream of the current process.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef><function>getSourceFileInfo</function></funcdef>
          <void/>
        </funcprototype>
      </funcsynopsis>
      <para>
        Returns the name of the file or other source from which the
        BeanShell interpreter is reading.
      </para>
    </listitem>

  </itemizedlist>

</sect1>

</chapter>