home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / dev / amiga_e-2.1b.lha / Amiga_E-2.1b / Docs / Utilities / GetString.doc < prev    next >
Encoding:
Text File  |  1993-10-05  |  5.8 KB  |  173 lines
  1.  
  2.  
  3.                               GetString
  4.                               ~~~~~~~~~
  5.  
  6.                     A small utility  for the Shell
  7.                           By Diego Caravana
  8.  
  9.                          Actual Version: 1.3
  10.  
  11.                                  ---
  12.  
  13.  
  14.                             1. Legal Stuff
  15.                             ==============
  16.  
  17.  GetString  is  placed  in  the Public Domain for the Amiga.
  18.  No  fee  is  requested  to  use it, nor anyone can ask anything for it
  19.  (except for the media).  Feel free to use it, but AT YOUR OWN RISK, as
  20.  I  cannot  be  considered  responsible  for  any damage caused to your
  21.  system.  Have Fun!
  22.  
  23.  
  24.                             2. What is it?
  25.                             ==============
  26.  
  27.  GetString  is a small utility that I have written mainly for me, but I
  28.  think  it can be very useful also for you.  It is a Shell-only program
  29.  and  its  work should be clear:  it opens a string requester and store
  30.  the  result  in  an  environment  variable (either local or global) or
  31.  prints  it,  enabling you to use it in your Shell scripts (or for what
  32.  you want) in a very simple way.
  33.  
  34.  
  35.                             3. How to use
  36.                             =============
  37.  
  38.  It  requires  OS  2.04+  and  the fabulous 'reqtools.library' V38+.
  39.  As said above, GetString is a Shell-only program, so do not try to use
  40.  from  Workbench.   It  uses  the  standard  parser  of OS 2.x.  Try to
  41.  execute  GetString  with  a `?' as argument and you will get something
  42.  like this:
  43.  
  44.     TITLE/A,STRING/K,MSG=MESSAGE/K,VAR=VARIABLE/K,GLOBAL/S,STDOUT/S,
  45.     PUBSCREEN/K
  46.  
  47.  Now, a little explanations of arguments:
  48.  
  49.     TITLE/A         you MUST supply a string that will be the title of
  50.                     the requester; if you do not do, there will be an
  51.                     error.
  52.  
  53.     STRING/K        is a string that will appear in the string gadget
  54.                     inside the requester and then will be the default
  55.                     string returned.
  56.  
  57.     MSG=MESSAGE/K   is a string that appears between the title and the
  58.                     string gadget, a new feature of ReqTools! It should
  59.                     explain even more the target of the requester.
  60.  
  61.     VAR=VARIABLE/K  is the name of the environment variable that will
  62.                     contain the input of the user; it must obey to the
  63.                     rules of DOS; the default is `GetStringResult'.
  64.                     Do not mix with STDOUT keyword.
  65.  
  66.     GLOBAL/S        if present , the variable will be global (setenv);
  67.                     the default is a local variable (set). Do not mix
  68.                     with STDOUT keyword.
  69.  
  70.     STDOUT/S        if present, the resulting string will be printed
  71.                     in  stdout  (i.e.  on  the  Shell  you  started
  72.                     GetString) and not stored in any variable.
  73.  
  74.     PUBSCREEN/K     is the name of the Public Screen on which you want
  75.                     your requester appear.
  76.  
  77.  The  keywords  above  followed by `/K' MUST appear in the command line
  78.  followed by their argument.  Those followed by `/S' act like switches,
  79.  i.e.   if  they  appear,  the  corresponding feature will be enabled.
  80.  Remember to use apices when necessary!
  81.  
  82.  To  find  Public Screens names, I have written PubScreenNames, a small
  83.  utility that you should find in the same place you found GetString.
  84.  
  85.  A simple example of how to use GetString is given below:
  86.  
  87.     ; stuff...
  88.  
  89.     GetString "Insert Date:" STRING "24-02-1972 4:00" VAR tmpDate
  90.     date $tmpDate
  91.     unset tmpDate
  92.  
  93.     ; or even...
  94.  
  95.     date `GetString "Insert Date and Time" STDOUT`
  96.  
  97.     ; even more stuff...
  98.  
  99.  Note  that above in the first GetString line, you must NOT include the
  100.  `$'  sign  before  the  variable  name!   Once  more,  note the use of
  101.  backquote  (a  new  2.0+  feature!)  in the second GetString line:  it
  102.  means  that  what  will  be  printed by the `backquoted' command, will
  103.  became a parameter for date (in this case) and will be no more printed.
  104.  
  105.  Again, note that the title MUST ALWAYS be supplied; this is a feature,
  106.  because  it is fundamental when the requester appears.  Try to imagine
  107.  a requester without a title appearing in front of you...  :)
  108.  
  109.  
  110.                            4. The Language
  111.                            ===============
  112.  
  113.  I  have used E language to write GetString.  What?  E ?!  Yea!  Go and
  114.  see the source !!!  :-)
  115.  But  Why?   Because  it  is  a  very  powerful  simple-to-use language
  116.  dedicated  explicitly  to  our Amiga, influenced by C and Modula-2, so
  117.  you  can  imagine  its  power.  It offers an incredibly vast number of
  118.  features, like high speed in compiling, extremely compact executables,
  119.  inline  assembly,  direct  access  to Amiga Shared Libraries, powerful
  120.  type system, exception handling, etc.
  121.  
  122.  Cool, eh?  Try it, if you do not believe to your eyes ! :-)
  123.  The author of E language is:
  124.  
  125.       Wouter van Oortmerssen ($#%!)
  126.       Levendaal 87
  127.       2311 JG  Leiden
  128.       HOLLAND
  129.   
  130.   If you have access to Email:
  131.  
  132.       Wouter@alf.let.uva.nl    (E-programming support)
  133.   or: Wouter@mars.let.uva.nl   (personal)
  134.   or: Oortmers@gene.fwi.uva.nl (other)
  135.  
  136.  
  137.                             5. The Author
  138.                             =============
  139.  
  140.  If you want to send me bug-reports or a time-bomb *:), I can be
  141.  contacted in the following manners:
  142.  
  143.     by snail-mail
  144.  
  145.         Diego Caravana
  146.  
  147.         V. Liguria, 24
  148.         10071 Borgaro (TO)
  149.         Italy
  150.  
  151.     by e-mail
  152.  
  153.         `Diego Caravana'  on
  154.  
  155.         FIDO       2:334/308
  156.                    2:334/308.9
  157.         AMIGANET   39:101/3
  158.  
  159.         Internet   Diego.Caravana%bbs@osra.sublink.org
  160.  
  161.  To  find  me and the E language stuff, you can call the BBS on which I
  162.  am CoSysOp (located in Turin, Italy):
  163.  
  164.        *The New ATH*
  165.         ~~~~~~~~~~~
  166.         TEL       +39-11-5629284
  167.                   +39-11-5629290
  168.         FIDO      2:334/308
  169.         AMIGANET  39:101/3
  170.         Internet  <soon>
  171.  
  172.  
  173.