yabasic.xml

Linux下VB解释器

<?xml version="1.0" encoding="ASCII"?>
<!DOCTYPE book SYSTEM "docbook/docbookx.dtd">
<book>
  <bookinfo>
    <title>Yabasic</title>
  </bookinfo>
  <chapter id="chapter_intoduction">
    <title>Introduction</title>
    <sect1>
      <title>About this document</title>
      <para>
      This document describes <application>yabasic</application>.
      You will find information about the <application>yabasic</application> 
      interpreter (the program <command>yabasic</command> under Unix or 
      <command>yabasic.exe</command> under Windows)
      as well as the language (which is, of course, a sort of
<acronym>basic</acronym>) itself.<para>
    </para>
      This document applies to version 2.760 of <application>yabasic</application></para>
      <para>
      However, this document does not contain the latest news about <application>yabasic</application> or a FAQ.
      As such information tends to change rapidly, it is presented online only 
      at <ulink url="http://www.yabasic.de">www.yabasic.de</ulink>.</para>
      <para>
      Although <acronym>basic</acronym> has its reputation as a language for beginning programmers,
      this is not an introduction to programming at large. Rather this text assumes, that
      the reader has some (moderate) experience with writing and starting computer programs.</para>
      <para>
    </para>
    </sect1>

    <sect1>
      <title>About <application>yabasic</application></title>
      <para><application>yabasic</application> is a traditional basic interpreter. It understands most of the typical basic-constructs, like <function>goto</function>, <function>gosub</function>, line numbers, <function>read</function>, <function>data</function> or string-variables with a trailing '<literal>$</literal>'. But on the other hand, <application>yabasic</application> implements some more advanced programming-constructs like subroutines or libraries (but <emphasis>not</emphasis> objects). <application>yabasic</application> works much the same under Unix and Windows.</para>
      <para><application>yabasic</application> puts emphasis on giving results quickly and easily; therefore simple commands are provided to open a graphic window, print the graphics or control the console screen and get keyboard or mouse information. The example below opens a window, draws a circle and prints the graphic:</para>
      <programlisting>
open window 100,100
open printer
circle 50,50,40
text 10,50,"Press any key to get a printout"
clear screen
inkey$
close printer
close window
</programlisting>
      <para>This example has fewer lines, than it would have in many other programming languages. In the end however <application>yabasic</application> lacks behind more advanced and modern programming languages like C++ or Java. But as far as it goes it tends to give you results more quickly and easily.</para>
    </sect1>
  </chapter>

  <chapter id="chapter_program_windows">
    <title>The <application>yabasic</application>-program under Windows</title>
    <sect1>
      <title id="windows_starting">Starting <application>yabasic</application></title>
      <para>Once, <application>yabasic</application> has been set up correctly, there are three ways to start it:</para>
      <orderedlist>
	<listitem>
	  <para><emphasis>Rightclick on your desktop:</emphasis> The desktop menu appears with a submenu named <emphasis>new</emphasis>. From this submenu choose <application>yabasic</application>. This will create a new icon on your desktop. If you rightclick on this icon, its <link linkend="windows_context_menu">context menu</link> will appear; choose <guilabel>Execute</guilabel> to execute the program.</para>
	</listitem>

	<listitem>
	  <para>As a variant of the way described above, you may simply <emphasis>create a file with the ending <filename>.yab</filename></emphasis> (e.g. with your favorite editor). Everything else then works as described above.</para>
	</listitem>

	<listitem>
	  <para><emphasis>From the start-menu:</emphasis> Choose <application>yabasic</application> from your start-menu. A console-window will open and you will be asked to type in your program. Once you are finished, you need to type <literal>return</literal> twice, and <application>yabasic</application> will parse and execute your program.</para>
	  <note>
	    <para>This is <emphasis>not</emphasis> the preferred way of starting <application>yabasic</application> ! Simply because the program, that you have typed, <emphasis>can not be saved</emphasis> and will be lost inevitably ! There is no such thing as a <function>save</function>-command and therefore no way to conserve the program, that you have typed. This mode is only intended for quick hacks, and short programs.</para>
	  </note>
	</listitem>
      </orderedlist>
    </sect1>
    <sect1>
      <title id="windows_options">Options</title>
      <para>Under Windows <application>yabasic</application> will mostly be invoked by double-clicking on an appropriate icon; this way you do not have a chance to specify any of the commandline options below. However, advanced users may add some of those options to the appropriate entries in the registry.</para>
      <para>All the options below may be abbreviated, as long as the abbreviation does not become ambiguous. For example, you may write <literal>-e</literal> instead of <literal>-execute</literal>.</para>
      <variablelist>
	<varlistentry>
	  <term><literal>-help</literal> or <literal>-?</literal></term>
	  <listitem>
	    <para>Prints a short help message, which itself describes two further help-options.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-version</literal></term>
	  <listitem>
	    <para>Prints the version of <application>yabasic</application>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-geometry +<replaceable>X-POSITION</replaceable>+<replaceable>Y-POSITION</replaceable></literal></term>
	  <listitem>
	    <para>Sets the position of the graphic window, that is opened by <function>open window</function> (the <emphasis>size</emphasis> of this window, of course, is specified within the <function>open window</function>-command). An example would be <literal>-geometry +20+10</literal>, which would place the graphic window 10 pixels below the upper border and 20 pixels right of the left border of the screen. This value cannot be changed, once <application>yabasic</application> has been started.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-font <replaceable>NAME-OF-FONT</replaceable></literal></term>
	  <listitem>
	    <para>Name of the font, which will be used for graphic-text; can be any of <literal>decorative, dontcare, modern, roman, script, swiss</literal>. You may append a fontsize (measured in pixels) to any of those fontnames; for example <literal>-font swiss30</literal> chooses a swiss-type font with a size of 30 pixels.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-bind <replaceable>NAME-OF-STANDALONE-PROGRAM</replaceable></literal></term>
	  <listitem>
	    <para>Create a standalone program (whose name is specified by <replaceable>NAME-OF-STANDALONE-PROGRAM</replaceable>) from the <application>yabasic</application>-program, that is specified on the commandline. See the section about <link linkend="ref_standalone">creating a <emphasis>standalone</emphasis>-program</link> for details.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-execute <replaceable>A-PROGRAM-AS-A-SINGLE-STRING</replaceable></literal></term>
	  <listitem>
	    <para>With this option you may specify some <application>yabasic</application>-code to be executed rigth away.This is useful for very short programs, which you do not want to save within a file. If this option is given, <application>yabasic</application> will not read any code from a file. Let's say, you have forgotten some of the square numbers between 1 and 10; in this case the command <literal>yabasic -e 'for a=1 to 10:print a*a:next a'</literal> will give you the answer immediately.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-infolevel <replaceable>INFOLEVEL</replaceable></literal></term>
	  <listitem>
	    <para>Change the <emphasis>infolevel</emphasis> of yabasic, where <replaceable>INFOLEVEL</replaceable> can be one of <literal>debug</literal>, <literal>note</literal>, <literal>warning</literal>, <literal>error</literal> and <literal>fatal</literal> (the default is <literal>warning</literal>). This option changes the amount of debugging-information <application>yabasic</application> produces. However, normally only the author of <application>yabasic</application> (<emphasis>me</emphasis> !) would want to change this.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-doc <replaceable>NAME-OF-A-PROGRAM</replaceable></literal></term>
	  <listitem>
	    <para>Print the <emphasis>embedded documentation</emphasis> of the named program. The embedded documentation of a program consists of all the comments within the program, which start with the special keyword <function><link linkend="ref_doc">doc</link></function>. This documentation can also be seen by choosing the corresponding entry from the context-menu of any <application>yabasic</application>-program.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-librarypath <replaceable>DIRECTORY-WITH-LIBRARIES</replaceable></literal></term>
	  <listitem>
	    <para>Change the directory, wherein libraries will be searched and imported (with the <function><link linkend="ref_import">import</link></function>-command). See also <function><link linkend="ref_import">this entry</link></function> for more information about the way, libraries are searched.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect1>
    <sect1>
      <title id="windows_context_menu">The context Menu</title>
      <para>Like every other icon under Windows, the icon of every <application>yabasic</application>-program has a <emphasis>context menu</emphasis> offering the most frequent operations, that may be applied to a <application>yabasic</application>-program.</para>

      <variablelist>
	<varlistentry>
	  <term><guilabel>Execute</guilabel></term>
	  <listitem>
	    <para>This will invoke <application>yabasic</application> to execute your program. The same happens, if you <emphasis>doubleclick</emphasis> on the icon.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guilabel>Edit</guilabel></term>
	  <listitem>
	    <para><application>notepad</application> will be invoked, allowing you to edit your program.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guilabel>View docu</guilabel></term>
	  <listitem>
	    <para>This will present the embedded documentation of your program. Embedded documentation is created with the special comment <function><link linkend="ref_doc">doc</link></function>.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect1>
  </chapter>



  <chapter id="chapter_program_unix">
    <title>The <application>yabasic</application>-program under Unix</title>
    <sect1>
      <title id="unix_starting">Starting <application>yabasic</application></title>
      <para>If your system administrator (vulgo <emphasis>root</emphasis>) has installed <application>yabasic</application> correctly, there are three ways to start it:</para>

      <orderedlist>

	<listitem>
	  <para>You may use your favorite editor (<application>emacs</application>, <application>vi</application> ?) to put your program into a file (e.g. <filename>foo</filename>). Make sure that the very first line starts with the characters '<literal>#!</literal>'  followed by the full pathname of <application>yabasic</application> (e.g. '<literal>#!/usr/local/bin/yabasic</literal>'). This <emphasis>she-bang</emphasis>-line ensures, that your Unix will invoke <application>yabasic</application> to execute your program (see also the entry for the <link linkend="ref_hash">hash</link>-character). Moreover, you will need to change the permissions of your <application>yabasic</application>-program <filename>foo</filename>, e.g. <literal>chmod u+x foo</literal>. After that you may invoke <application>yabasic</application> to invoke your program by simply typing <literal>foo</literal> (without even mentioning <application>yabasic</application>). However, if your <envar>PATH</envar>-variable does not contain a single dot ('<literal>.</literal>') you will have to type the full pathname of your program: e.g. <filename>/home/ihm/foo</filename> (or at least <filename>./foo</filename>).</para>
	</listitem>

	<listitem>
	  <para>Save your program into a file (e.g. <filename>foo</filename>) and type <literal>yabasic foo</literal>. This assumes, that the directory, where <application>yabasic</application> resides, is contained within your <envar>PATH</envar>-variable.</para>
	</listitem>

	<listitem>
	  <para>Finally your may simply type <userinput>yabasic</userinput> (maybe it will be necessary to include its full pathname). This will make <application>yabasic</application> come up and you will be asked to type in your program. Once you are finished, you need to type <literal>return</literal> twice, and <application>yabasic</application> will parse and execute your program.</para>
	  <note>
	    <para>This is <emphasis>not</emphasis> the preferred way of starting <application>yabasic</application> ! Simply because the program, that you have typed, <emphasis>can not be saved</emphasis> and will be lost inevitably ! There is no such thing as a <function>save</function>-command and therefore no way to conserve the program, that you have typed. This mode is only intended for quick hacks, and short programs, i.e. for using <application>yabasic</application> as some sort of fancy desktop calculator.</para>
	  </note>
	</listitem>
      </orderedlist>
    </sect1>

    <sect1>
      <title id="unix_options">Options</title>
      <para><application>yabasic</application> accepts a number of options on the commandline. All these options below may be abbreviated, as long as the abbreviation does not become ambigous. For example you may write <literal>-e</literal> instead of <literal>-execute</literal>.</para>
      <variablelist>
	<varlistentry>
	  <term><literal>-help</literal> or <literal>-?</literal></term>
	  <listitem>
	    <para>Prints a short help message, which itself describes two further help-options.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-version</literal></term>
	  <listitem>
	    <para>Prints the version of <application>yabasic</application>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-fg <replaceable>FOREGROUND-COLOR</replaceable></literal> or <literal>-foreground <replaceable>FOREGROUND-COLOR</replaceable></literal></term>
	  <listitem>
	    <para>Define the foreground color for the graphics-window (that will be opened with <function><link linkend="ref_open_window">open window</link></function>). The usual X11 colornames, like <emphasis>red</emphasis>, <emphasis>green</emphasis>, &hellip; are accepted. This value cannot be changed, once <application>yabasic</application> has been started.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-bg <replaceable>BACKGROUND-COLOR</replaceable></literal> or <literal>-background <replaceable>BACKGROUND-COLOR</replaceable></literal></term>
	  <listitem>
	    <para>Define the background color for the graphics-window. The usual X11 colornames are accepted. This value cannot be changed, once <application>yabasic</application> has been started.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-geometry +<replaceable>X-POSITION</replaceable>+<replaceable>Y-POSITION</replaceable></literal></term>
	  <listitem>
	    <para>Sets the position of the graphic window, that is opened by <function>open window</function> (the <emphasis>size</emphasis> of this window, of course, is specified with the <function>open window</function>-command). An example would be <literal>+20+10</literal>, which would place the graphic window 10 pixels below the upper border and 20 pixels right of the left border of the screen. Note, that the size of the window may not be specified here (well it may, but it will be ignored anyway). This value cannot be changed, once <application>yabasic</application> has been started.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-display <replaceable>BACKGROUND-COLOR</replaceable></literal></term>
	  <listitem>
	    <para>Specify the <emphasis>display</emphasis>, where the graphics window of yabasic should appear. Normally, however this value will be already present within the environment variable <envar>DISPLAY</envar>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-font <replaceable>NAME-OF-FONT</replaceable></literal></term>
	  <listitem>
	    <para>Name of the font, which will be used for text within the graphics window.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-execute <replaceable>A-PROGRAM-AS-A-SINGLE-STRING</replaceable></literal></term>
	  <listitem>
	    <para>With this option you may specify some <application>yabasic</application>-code to be executed rigth away.This is useful for very short programs, which you do not want to save to a file. If this option is given, <application>yabasic</application> will not read any code from a file. E.g. <programlisting>yabasic -e 'for a=1 to 10:print a*a:next a'</programlisting> prints the square numbers from 1 to 10.
</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-bind <replaceable>NAME-OF-STANDALONE-PROGRAM</replaceable></literal></term>
	  <listitem>
	    <para>Create a standalone program (whose name is specified by <replaceable>NAME-OF-STANDALONE-PROGRAM</replaceable>) from the <application>yabasic</application>-program, that is specified on the commandline. See the section about <link linkend="ref_standalone">creating a <emphasis>standalone</emphasis>-program</link> for details.</para>
	  </listitem>
	</varlistentry>


	<varlistentry>
	  <term><literal>-infolevel <replaceable>INFOLEVEL</replaceable></literal></term>
	  <listitem>
	    <para>Change the <emphasis>infolevel</emphasis> of yabasic where <replaceable>INFOLEVEL</replaceable> can be one of <literal>debug</literal>, <literal>note</literal>, <literal>warning</literal>, <literal>error</literal> and <literal>fatal</literal> (the default is <literal>warning</literal>). This option changes the amount of debugging-information <application>yabasic</application> produces. However, normally only the author of <application>yabasic</application> (<emphasis>me</emphasis> !) would want to change this.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-doc <replaceable>NAME-OF-A-PROGRAM</replaceable></literal></term>
	  <listitem>
	    <para>Print the <emphasis>embedded documentation</emphasis> of the named program. The embedded documentation of a program consists of all the comments within the program, which start with the special keyword <function><link linkend="ref_doc">doc</link></function>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>-librarypath <replaceable>DIRECTORY-WITH-LIBRARIES</replaceable></literal></term>
	  <listitem>
	    <para>Change the directory from which libraries will be imported (with the <function><link linkend="ref_import">import</link></function>-command). See also this entry for more information about the way, libraries will be searched.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect1>

    <sect1>
      <title id="unix_setting_defaults">Setting defaults</title>
      <para>If you want to set some options <emphasis>once for all</emphasis>, you may put them into your X-Windows resource file. This is usually the file <filename>.Xresources</filename> or some such within your home directory (type <userinput>man X</userinput> for details).</para>
      <para>Here is a sample section, which may appear within this file:</para>
      <programlisting>
yabasic*foreground: blue
yabasic*background: gold
yabasic*geometry: +10+10
yabasic*font: 9x15
</programlisting>
      <para>This will set the foreground color of the graphic-window to <emphasis>blue</emphasis> and the background color to <emphasis>gold</emphasis>. The window will appear at position <emphasis>10,10</emphasis> and the text font will be <emphasis>9x15</emphasis>.</para>
    </sect1>
  </chapter>


  <chapter id="chapter_topics">
    <title>Some features of <application>yabasic</application>, explained by topic</title>
    <para>This chapter has sections for some of the major features of <application>yabasic</application> and names a few commands related with each area. So, depending on your interest, you find the most important commands of this area named; the other commands from this area may then be discovered through the links in the <emphasis>see also</emphasis>-section.</para>
    <sect1>
      <title><function>print</function>, <function>input</function> and others</title>
      <para>The <function><link linkend="ref_print">print</link></function>-command is used to put text on the text screen. Here, the term <wordasword>text screen</wordasword> stands for your terminal (under Unix) or the console window (under Windows).</para>
      <para>At the bottom line, <function>print</function> simply outputs its argument to the text window. However, once you have called <function><link linkend="ref_clear_screen">clear screen</link></function> you may use advanced features like printing colors or copying areas of text with <function><link linkend="ref_getscreen">getscreen$</link></function> or <function><link linkend="ref_putscreen">putscreen</link></function>.</para>
      <para>You may ask the user for input with the <function><link linkend="ref_input">input</link></function>-command; use <function><link linkend="ref_inkey">inkey$</link></function> to get each key as soon as it is pressed.</para>
    </sect1>

    <sect1>
      <title>Control statements: loops, <function>if</function> and <function>switch</function></title>
      <para>Of course, <application>yabasic</application> has the <function><link linkend="ref_goto">goto</link></function>- and <function><link linkend="ref_gosub">gosub</link></function>-statements; you may go to a <function><link linkend="ref_label">label</link></function> or a <emphasis>line number</emphasis> (which is just a special kind of label). <function><link linkend="ref_goto">goto</link></function>, despite its bad reputation (<citation><function>goto</function> considered harmful</citation>), has still its good uses; however in many cases you are probably better off with loops like <function><link linkend="ref_repeat">repeat</link></function>-<function><link linkend="ref_until">until</link></function>, <function><link linkend="ref_while">while</link></function>-<function><link linkend="ref_wend">wend</link></function> or <function><link linkend="ref_do">do</link></function>-<function><link linkend="ref_loop">loop</link></function>; you may leave any of these loops with the <function><link linkend="ref_break">break</link></function>-statement or start the next iteration immediately with <function><link linkend="ref_continue">continue</link></function>.</para>
      <para>Decisions can be made with the <function><link linkend="ref_if">if</link></function>-statement, which comes either in a <emphasis>short</emphasis> and a <emphasis>long</emphasis> form. The short form has no <function><link linkend="ref_then">then</link></function>-keyword and extends up to the end of the line. The long form extends up to the final <function><link linkend="ref_endif">endif</link></function> and may use some of the keywords <function><link linkend="ref_then">then</link></function> (which introduces the long form), <function><link linkend="ref_else">else</link></function> or <function><link linkend="ref_elsif">elsif</link></function>.</para>
      <para>If you want to test the result of an expression against many different values, you should probably use the <function><link linkend="ref_switch">switch</link></function>-statement.</para>
    </sect1>


    <sect1>
      <title>Drawing and painting</title>
      <para>You need to call <function><link linkend="ref_open_window">open window</link></function> before you may draw anything with either <function><link linkend="ref_line">line</link></function>, <function><link linkend="ref_circle">circle</link></function>, <function><link linkend="ref_rectangle">rectangle</link></function> or <function><link linkend="ref_triangle">triangle</link></function>; all of these statements may be decorated with <function><link linkend="ref_clear">clear</link></function> or <function><link linkend="ref_fill">fill</link></function>. If you want to change the colour for drawing, use <function><link linkend="ref_colour">colour</link></function>. Note however, that there can only be a single window open at any given moment in time.</para>
      <para>Everything you have drawn can be send to your printer too, if you use the <function><link linkend="ref_open_printer">open printer</link></function> command.</para>
      <para>To allow for some (very) limited version of animated graphics, <application>yabasic</application> offers the commands <function><link linkend="ref_getbit">getbit$</link></function> and <function><link linkend="ref_putbit">putbit</link></function>, which retrieve rectangular regions from the graphics-window into a string or vice versa.</para>
      <para>If you want to sense mouse-clicks, you may use the <function><link linkend="ref_inkey">inkey$</link></function>-function.</para>
    </sect1>

    <sect1>
      <title>Reading from and writing to files</title>
      <para>Before you may read or write a file, you need to <function><link linkend="ref_open">open</link></function> it; once you are done, you should <function><link linkend="ref_close">close</link></function> it. Each open file is designated by a simple number, which might be stored within a variable and must be supplied if you want to access the file. This is simply done by putting a hash ('<literal>#</literal>') followed by the number of the file after the keyword <function><link linkend="ref_input">input</link></function> (for reading from) or <function><link linkend="ref_print">print</link></function> (for writing to a file) respectively.</para>
      <para>If you need more control, you may consider reading and writing one byte at a time, using the multi-purpose commands <function><link linkend="ref_peek">peek</link></function> and <function><link linkend="ref_poke">poke</link></function>.</para>
    </sect1>

    <sect1>
      <title>Subroutines and Libraries</title>
      <para>The best way to break any <application>yabasic</application>-program into smaller, more manageable chunks are <emphasis>subroutines</emphasis> and <emphasis>libraries</emphasis>. They are <application>yabasic</application>'s most advanced means of structuring a program.</para>
      <para>Subroutines are created with the command <function><link linkend="ref_sub">sub</link></function>. they accept parameters and may return a value. Subroutines can be called much like any builtin function of <application>yabasic</application>; therefore they allow to <emphasis>extend</emphasis> the language itself.</para>
      <para>Once you have created a set of related subroutines and you feel that they could be useful in other programs too, you may collect them into a <emphasis>library</emphasis>. Such a library is contained within a separate file and may be included in any of your programs, using the keyword <function><link linkend="ref_import">import</link></function>.</para>
    </sect1>