/jEdit/tags/jedit-4-5-pre1/doc/users-guide/bsh-commands.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="bsh-commands">
<!-- jEdit buffer local properties:
      :indentSize=1:noTabs=yes:maxLineLen=72:tabSize=2:
      :xml.root=users-guide.xml:
      jEdit 3.2 Macro Guide, (C) 2001 John Gellene
      Thu Jun 21 23:49:14 EDT 2001 @200 /Internet Time/ -->

    <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>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.</para>
    </note>

    <section id="bsh-commands-output">
        <title>Output Commands</title>

        <itemizedlist>
            <!-- 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. </para>
            </listitem>

            <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>
        </itemizedlist>
    </section>

    <section id="bsh-commands-file">
        <title>File Management Commands</title>

        <itemizedlist>
            <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>cp</function></funcdef>

                        <paramdef>String
                        <parameter>fromFile</parameter></paramdef>

                        <paramdef>String
                        <parameter>toFile</parameter></paramdef>
                    </funcprototype>
                </funcsynopsis>

                <para>Copy <parameter>fromFile</parameter> to
                <parameter>toFile</parameter>.</para>
            </listitem>

            <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>void <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>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>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>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>
    </section>

    <section id="bsh-commands-serial">
        <title>Component Commands</title>

        <itemizedlist>
            <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>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>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>
    </section>

    <section id="bsh-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>. An 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>
        Returns 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, reloads 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>
    </section>

    <section id="bsh-commands-script">
        <title>Script Execution Commands</title>

        <itemizedlist>
            <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>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>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>org.gjt.sp.jedit.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>void
                        <function>setAccessibility</function></funcdef>

                        <paramdef>boolean <parameter>flag</parameter></paramdef>
                    </funcprototype>
                </funcsynopsis>

                <para>If <parameter>flag</parameter> is <literal>true</literal>,
                BeanShell scripts are allowed to change and modify private
                variables, and call private methods. The default is
                <literal>false</literal>.</para>
            </listitem>

            <listitem>
                <funcsynopsis>
                    <funcprototype>
                        <funcdef>void
                        <function>setStrictJava</function></funcdef>

                        <paramdef>boolean <parameter>flag</parameter></paramdef>
                    </funcprototype>
                </funcsynopsis>

                <para>If <parameter>flag</parameter> is <literal>true</literal>,
                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" />.</para>
            </listitem>

            <!-- <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>void <function>server</function></funcdef>
          <paramdef>int <parameter>port</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        Creates 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> -->

            <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>
        </itemizedlist>
    </section>

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

        <itemizedlist>
            <listitem>
                <funcsynopsis>
                    <funcprototype>
                        <funcdef><function>bind</function></funcdef>

                        <paramdef>org.gjt.sp.jedit.bsh.This
                            <parameter>ths</parameter></paramdef>

                        <paramdef>org.gjt.sp.jedit.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>clear</function></funcdef>

                        <void />
                    </funcprototype>
                </funcsynopsis>

                <para>Clear all variables, methods, and imports from this
                namespace. If this namespace is the root, it will be reset to
                the default imports.</para>
            </listitem>

            <listitem>
                <funcsynopsis>
                    <funcprototype>
                        <funcdef>org.gjt.sp.jedit.bsh.This
                            <function>extend</function></funcdef>

                        <paramdef>org.gjt.sp.jedit.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>void
                        <function>importObject</function></funcdef>

                        <paramdef>Object
                        <parameter>object</parameter></paramdef>
                    </funcprototype>
                </funcsynopsis>

                <para>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 a
                BeanShell namespace, for example:</para>

                <informalexample>
                    <programlisting>Map map = new HashMap();
    importObject( map );
    put("foo", "bar");
    print( get("foo") ); // "bar"</programlisting>
                </informalexample>
            </listitem>

            <listitem>
                <funcsynopsis>
                    <funcprototype>
                        <funcdef>org.gjt.sp.jedit.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><function>setNameSpace</function></funcdef>

                        <paramdef>org.gjt.sp.jedit.bsh.Namespace
                        <parameter>namespace</parameter></paramdef>
                    </funcprototype>
                </funcsynopsis>

                <para>Set the namespace of the current scope to
                <parameter>namespace</parameter>.</para>
            </listitem>

            <listitem>
                <funcsynopsis>
                    <funcprototype>
                        <funcdef>org.gjt.sp.jedit.bsh.This
                            <function>super</function></funcdef>

                        <paramdef>String
                        <parameter>scopename</parameter></paramdef>
                    </funcprototype>
                </funcsynopsis>

                <para>Returns a reference 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>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>
        </itemizedlist>
    </section>

    <section id="bsh-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>
    </section>
</chapter>