A Beginners Guide To Euphoria

Appendix A: Predefined Constants

Most values either used by library routines, or returned by library routines, have a special meaning. For example, in graphics library routines like text, the colour blue is represented by the value 1, and obtaining a Euphoria object using gets() successfully will cause the library routine to return a value of 0. To make all these values easy to remember, a Euphoria symbol related to a variable is used to give absolute values a literal name. The declarable symbols are called constants.

Like variables, constants are literals used to reference RAM addresses using a symbolic name. Like variables, constants must be declared before use, and are assigned a value. They also follow the same naming rules that variables, library routines, and other Euphoria symbols do. But the similarities stop here at this point. While variables can have their values changed at any time, a constant can only be given a value once, and is locked with that value for the duration of the program run. As you can see, the name constant fits perfectly to describe this kind of declarable symbol.

When a constant is declared, it is given its permanent value as part of the declaration statement:

   constant variable name = expression

An expression, as you remember, can be a single value, or an arithmetic, logical, or relational expression. You can use other constants, library routines, and variables as part of the expression but once you declare the constant with its value, you cannot use an assignment statement to change the constant's value again. Constants are best used for subjects that are unchangable, such as the value of PI or the speed of light. In externally declared library routines, the include files that define the library routines also contain a list of constant values you can use in place of the absolute values. For example, if you want to draw a bright magenta line, you specify in draw_line() BRIGHT_MAGENTA as the colour to use.

Constants can be local and global, but never private, so they cannot be declared inside type groups or library routines. A demo program is available not only an example of constants being used, but also lists some of the constants that are declared in include files, like image.e, graphics.e and file.e. [note: before running the demo, you will need to make sure the the file "constants.txt" is available, and modify the open() function accordingly]

Demo program 88
integer constants_file, current_record, input_key, update

sequence database, input_record

constant number_of_records = 49,
         field_1_start = 1, field_1_end = 24,
         field_2_start = 25, field_2_end = 35,
         field_3_start = 36, field_3_end = 37,
         field_4_start = 38, field_4_end = 110,
         field_5_start = 111

procedure display_data(sequence record)
     sequence dline1, dline2, dline3, dline4, constant_name, include_file,

     dline1 = "Constant Name: %s\n"
     dline2 = "Constant Description: %s\n"
     dline3 = "Constant Value: %s\n"
     dline4 = "Declared In Include File: %s\n"

     constant_name               = record[field_1_start..field_1_end]
     include_file                = record[field_2_start..field_2_end]
     constant_value              = record[field_3_start..field_3_end]
     library_routines_where_used = record[field_4_start..field_4_end]
     constant_description        = record[field_5_start..length(record)]
     for line = 1 to 7 do
          puts(1,repeat(' ',75) & "\n")
     end for
     puts(1,"\nExamples Of Library Routines Where Used:\n")
     puts(1,library_routines_where_used & "\n")
end procedure

current_record = 1
database = {}
input_key = 0
update = 'y'

constants_file = open("constants.txt","r")

for ix = 1 to number_of_records do
     input_record = gets(constants_file)
     input_record = input_record[1..length(input_record)-1]
     database = append(database,input_record)
end for

puts(1,"Euphoria Constants Dictionary")
puts(1,"Press < and > to move about")
puts(1,"Press Q to quit")

while input_key != 'q' do

     if input_key = '.' or input_key = '>' then
          if current_record < number_of_records then
               current_record = current_record + 1
               update = 'y'
          end if
     end if

     if input_key = ',' or input_key = '<' then
          if current_record > 1 then
               current_record = current_record - 1
               update = 'y'
          end if
     end if

     if update = 'y' then
          update = 'n'
     end if

     input_key = get_key()

end while



Appendix B: Error Messages When Running EX.EXE

During your writing of Euphoria programs, you will encounter error messages. The error messages are generated when using EX.EXE (either directly by calling EX.EXE or indirectly when using BIND.BAT). While the error messages are very easy to understand, first-time users may find some difficulties solving them. This appendix will help explain what the text in EX.ERR means, and will give detailed descriptions of what some of the more commonly seen error messages are saying.

When a program aborts with an error, you will see the following information:

   error message

The first line states the name of the program you were running, with a line number after the colon where the error occurred. The line below is the error message describing the problem. A copy of these two lines are also stored in EX.ERR, which is generated at the time of the error. There is also additional information in the EX.ERR file:

   Global & Local Variables (a list of variables and the values they contain follow)

Sequence variables will be shown with both actual and character values for each element. If include files, type groups, and library routines are used in your program, the variables will be grouped based on the program sections they are declared in. If the error occurred in a procedure, function, type group, whether in an included file or in the program itself, it will be shown as well. For example, you could see the following text if it occurred in a procedure:

   program.ex:nnnn in procedure procedure_name()

But all this is just a snapshot of what was going on at the time the program aborted. The really important information is of course the error message. It tells you WHY the program halted in error. While there are many error messages generated by EX.ERR, here are some that you will encounter often:

   type_check failure, variable is n

this means you tried to assign a value in a variable that does not support the data object type of the value. For example, a sequence variable may be accidentally assigned an atom value, or vice-versa, or an integer variable is being assigned a value that is larger than the accepted integer range.

   sequence found inside character string

this means you have a sequence that has one or more sequence elements. Some library routines only accept sequences that are made up of atom elements.

   subscript value n1 is out of bounds, reading from a length-n2 sequence

this means you have attempted to access an element within a sequence that does not exist. For example, if you try to reference element 10 in a 5 element sequence, you will get this message.

   slice ends past end of sequence (n1 > n2)

this means a range of elements you were trying to extract from a sequence has the end range position n1 going beyond the maximum sequence length n2.

   can't open include file path

this means the include file you supplied in the include statement was not found. You either misspelt the name, or you are using the wrong directory.

   sequence lengths are not the same (n1 != n2)

this means two sequences you are using in an operation, like addition, are of different lengths. n1 is the first sequence length, n2 is the second sequence length. You also get this message if you are using the if statement to directly compare a sequence variable with a sequence value.

   syntax error - expected to see ..., not ...

this means EX.EXE found a symbol that was different from what it expected. For example, if you left out "then" in an "if" statement, you would get this message. You may also see EX.EXE stating <end-of-file> was obtained instead of an expected symbol. This could mean you left out an "end if", "end for", or "end while".

   true/false condition must be an ATOM

this means a sequence was used in a logical or relational expression portion of a statement such as the "while" statement.

   unknown escape character

this means you paired the \ special character operator with another character that Euphoria does not accept as valid when paired.

   may not change the value of a constant

this means you tried to change a constant value. Constants cannot be changed to another value.

   a loop variable name is expected here

this means you used either a reserved word like "global", or a symbol with an illegal character as the control variable that is incremented during the "for" statement loop.

   no value returned from function

this means you forgot to add the "return" statement in the function you created in your program.

   attempt to subscript an atom

this means a value in an object variable was an atom when you tried to reference one or more elements in what you expected to be a sequence.

   slice length is less than 0 (-n1)

this means you attempted to perform a reversed range that went beyond the legal [n+1..n] limit. The value -n1 is the number of elements out of bounds of the legal reversed range limit.

   symbol has not been declared

this means you either misspelt a symbolic name (such as a variable or library routine), forgot to declare it, or forgot to use the "global" keyword with the variable or library routine declared in the include file.

The best way to understand errors is through experience. Good luck!!