home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD5.iso / workbench / libs / rexmooslib.lha / MOOS / Docs / english / rexx_stem.doc < prev    next >
Encoding:
Text File  |  1997-02-03  |  11.1 KB  |  438 lines
  1.  
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. --background--
  6. --general--
  7. rexx_stem.library/StemCopy
  8. rexx_stem.library/StemInsert
  9. rexx_stem.library/StemRead
  10. rexx_stem.library/StemRemove
  11. rexx_stem.library/StemSearch
  12. rexx_stem.library/StemSort
  13. rexx_stem.library/StemWrite
  14.  
  15.  
  16. --background--                                                  --background--
  17.  
  18.  $(C): (1996, Rocco Coluccelli, Bologna)
  19.  $VER: rexx_stem.library 37.00 (30.01.97)
  20.  
  21.     rexx_stem.library
  22.  
  23.     This sub-library of the rexxMOOS.library let ARexx programmers
  24.     perform very powerfull manipulation over stem and compound symbols.
  25.  
  26.         StemCopy()
  27.         StemInsert()
  28.         StemRead()
  29.         StemRemove()
  30.         StemSearch()
  31.         StemSort()
  32.         StemWrite()
  33.  
  34.     NOTES
  35.  
  36.         Is part of the MOOS package.
  37.  
  38.     TODO
  39.  
  40.         StemToString()
  41.  
  42.     BUGS
  43.  
  44. --general--                                                        --general--
  45.  
  46.     Stem & Compound symbols.
  47.  
  48.     Let's refresh our memory about stem and compound symbols as used into
  49.     the ARexx language. Those entities are very usefull when we need to
  50.     build a vector or a structure. Here is the general form to specify a
  51.     compound symbol:
  52.  
  53.         stem.level_1.level_2.level_3 ...
  54.  
  55.     All functions of this library that accept one or more stem as inputs
  56.     arguments let you specify them using the following convention:
  57.  
  58.         stem.levels_sx.#.levels_dx  The "#" locate where will be placed
  59.                                     numbers to get each stem's entries.
  60.                                     "levels_sx" and "levels_dx" are one
  61.                                     or more, dot separated, levels. This
  62.                                     mean that we can work at every level
  63.                                     of a stem.
  64.  
  65.         stem.levels_sx.count        The total number of entries at this
  66.                                     level from 0 to count-1. This entry
  67.                                     must be present to let functions know
  68.                                     how many values are in each stem at
  69.                                     any level.
  70.  
  71.     Refer to the ARexx documentation to find more information about the
  72.     use of stem and compound symbols.
  73.  
  74. rexx_stem.library/StemCopy                          rexx_stem.library/StemCopy
  75.  
  76.     NAME
  77.  
  78.         StemCopy -- Copy a stem into another.
  79.  
  80.     SYNOPSIS
  81.  
  82.         success = StemCopy(options)
  83.  
  84.     FUNCTION
  85.  
  86.         StemCopy() take a source stem and copy its entries into a
  87.         destination stem. By default the source stem will be appended
  88.         at the end of the destination.
  89.  
  90.     INPUTS
  91.  
  92.         options - "FromStem/A,ToStem/A,FromPos/K/N,ToPos/K/N,Tot/K/N"
  93.  
  94.             "FromStem/A"  - The source stem.
  95.  
  96.             "ToStem/A"    - The destination stem, will receive entries
  97.                             from the source stem.
  98.  
  99.             "FromPos/K/N" - First entry, in the source stem, to be
  100.                             copied. (default is 0)
  101.  
  102.             "ToPos/K/N"   - Position where start to copy all entries.
  103.                             The existing entries will be overwritten.
  104.                             (default is last entry, append source stem
  105.                             to destination)
  106.  
  107.             "Tot/K/N"     - How many entries, from the source stem,
  108.                             need to copy into the destination.
  109.                             (default is all entries)
  110.  
  111.     RESULT
  112.  
  113.         success - boolean value (1 mean all done, ok).
  114.  
  115.     EXAMPLE
  116.  
  117.         from. = "From stem...."; from.count = 5; to.count = 12
  118.         DO i = 0 FOR to.count
  119.             to.i.post = "to stem" i
  120.         END
  121.         IF StemCopy('from. to.#.post ToPos 2') THEN
  122.             DO i = 0 FOR to.count
  123.                 SAY "TO."i".POST ==" to.i.post
  124.             END
  125.  
  126.     NOTES
  127.  
  128.     BUGS
  129.  
  130.     SEE ALSO
  131.  
  132.         rexx_stem.library/StemInsert()
  133.  
  134. rexx_stem.library/StemInsert                      rexx_stem.library/StemInsert
  135.  
  136.     NAME
  137.  
  138.         StemInsert -- Insert a stem into another.
  139.  
  140.     SYNOPSIS
  141.  
  142.         success = StemInsert(from,options)
  143.  
  144.     FUNCTION
  145.  
  146.         StemInsert() take a source stem and insert its entries into a
  147.         destination stem.
  148.  
  149.     INPUTS
  150.  
  151.         from    - The source stem.
  152.  
  153.         options - "ToStem/A,FromPos/K/N,ToPos/K/N,Tot/K/N"
  154.  
  155.             "ToStem/A"    - The destination stem, will receive entries
  156.                             from the source stem.
  157.  
  158.             "FromPos/K/N" - First entry, in the source stem, to be
  159.                             inserted. (default is 0)
  160.  
  161.             "ToPos/K/N"   - Position where start to insert all entries.
  162.                             The existing entries will be shifted down
  163.                             before inserting the others from the source.
  164.                             (default is after the last entry of the
  165.                             destination stem)
  166.  
  167.             "Tot/K/N"     - How many entries, from the source stem,
  168.                             need to insert into the destination.
  169.                             (default is all entries)
  170.  
  171.     RESULT
  172.  
  173.         success - boolean value (1 mean all done, ok).
  174.  
  175.     EXAMPLE
  176.  
  177.         in. = "empty"; in.count = 6
  178.         DO i = 0 FOR in.count; SAY in.i; END
  179.         IF StemInsert('in.','out. FromPos 3 Tot 4') THEN
  180.             DO i = 0 FOR out.count
  181.                 SAY out.i
  182.             END
  183.  
  184.     NOTES
  185.  
  186.     BUGS
  187.  
  188.     SEE ALSO
  189.  
  190. rexx_stem.library/StemRead                          rexx_stem.library/StemRead
  191.  
  192.     NAME
  193.  
  194.         StemRead -- Read a file putting its lines into a stem.
  195.  
  196.     SYNOPSIS
  197.  
  198.         success = StemRead(filepath,options)
  199.  
  200.     FUNCTION
  201.  
  202.         The function read the given file line by line and put
  203.         them into a specified stem.
  204.  
  205.     INPUTS
  206.  
  207.         filepath - Relative or absolute path. This argument must
  208.                    be provided and the file must exists.
  209.  
  210.         options  - "OutStem/A,Del=Delete/S"
  211.  
  212.             "OutStem/A" - The stem to put readed lines in.
  213.  
  214.             "Delete/S"  - Delete the file after read.
  215.  
  216.     RESULT
  217.  
  218.         success - boolean value (1 mean all done, ok).
  219.  
  220.     EXAMPLE
  221.  
  222.         IF StemRead("S:User-Startup","txt.") THEN
  223.             DO n = 0 FOR txt.count
  224.                 SAY txt.n
  225.             END
  226.  
  227.     NOTES
  228.  
  229.         The maximum length for a line must be less than 8192 characters.
  230.  
  231.     SEE ALSO
  232.  
  233.         rexx_stem.library/StemWrite()
  234.  
  235. rexx_stem.library/StemRemove                      rexx_stem.library/StemRemove
  236.  
  237.     NAME
  238.  
  239.         StemRemove -- Remove a block of entries.
  240.  
  241.     SYNOPSIS
  242.  
  243.         success = StemRemove(options)
  244.  
  245.     FUNCTION
  246.  
  247.         This function take a stem and remove a block of entries.
  248.         The stem will be repacked updating also the dimension (count).
  249.  
  250.     INPUTS
  251.  
  252.         options - "InStem/A,FromPos/K/N,ToPos/K/N,Tot/K/N"
  253.  
  254.             "InStem/A"    - The stem to perform removing on.
  255.  
  256.             "FromPos/K/N" - The first entry to be removed.
  257.                             (default is 0)
  258.  
  259.             "ToPos/K/N"   - The last entry to be removed. All other
  260.                             entries, from ToPos+1 to the last, will
  261.                             take place over the deleted ones.
  262.                             (default is last entry of the stem)
  263.  
  264.             "Tot/K/N"     - Instead of using ToPos you can specify
  265.                             how many entries need to remove.
  266.                             (default is all entries)
  267.  
  268.     RESULT
  269.  
  270.         success - boolean value (1 mean all done, ok).
  271.  
  272.     EXAMPLE
  273.  
  274.         in. = "empty"; in.2 = "full"; in.4 = "full"; in.count = 10
  275.         DO i = 0 FOR in.count; SAY in.i; END
  276.         IF StemRemove('in. FromPos 3 Tot 5') THEN
  277.             DO i = 0 FOR in.count
  278.                 SAY in.i
  279.             END
  280.  
  281.     NOTES
  282.  
  283.         Using this function to remove ALL entries from a stem is
  284.         a non-sense, use the instruction DROP instead.
  285.  
  286.     BUGS
  287.  
  288.     SEE ALSO
  289.  
  290.         rexx_stem.library/StemInsert()
  291.  
  292. rexx_stem.library/StemSearch                      rexx_stem.library/StemSearch
  293.  
  294.     NAME
  295.  
  296.         StemSearch -- Search a pattern into the given stem.
  297.  
  298.     SYNOPSIS
  299.  
  300.         success = StemSearch(pattern,options)
  301.  
  302.     FUNCTION
  303.  
  304.         StemSearch() do a pattern matching over entries of a given stem.
  305.         It will fill an output stem with all found entries.
  306.  
  307.     INPUTS
  308.  
  309.         pattern - The pattern to search for (standard AmigaDOS).
  310.  
  311.         options - "InStem/A,OutStem/A,Pos/K/N,Case/S"
  312.  
  313.             "InStem/A"  - Stem where perform the pattern matching.
  314.  
  315.             "OutStem/A" - Output stem for all matched entries.
  316.  
  317.             "Pos/K/N"   - Start searching from the entry at "Pos"...
  318.                           (default is the first entry)
  319.  
  320.             "Case/S"    - Do search case sensitive.
  321.                           (default NoCase)
  322.  
  323.     RESULT
  324.  
  325.         success - boolean value (1 mean all done, ok).
  326.  
  327.     EXAMPLE
  328.  
  329.         in. = "empty"; in.2 = "String"; in.5 = "string"
  330.         in.count = 10
  331.         IF StemSearch("st#?","in. out.") THEN
  332.             DO n = 0 FOR out.count; SAY out.n; END
  333.  
  334.     NOTES
  335.  
  336.     BUGS
  337.  
  338.     SEE ALSO
  339.  
  340.         dos.library/MatchPattern, dos.library/MatchPatternNoCase
  341.  
  342. rexx_stem.library/StemSort                          rexx_stem.library/StemSort
  343.  
  344.     NAME
  345.  
  346.         StemSort -- Sort entries into the given stem.
  347.  
  348.     SYNOPSIS
  349.  
  350.         success = StemSort(options)
  351.  
  352.     FUNCTION
  353.  
  354.         StemSort() perform a sorting of entries found into a stem.
  355.         It can fill an output stem with all sorted entries. The sort
  356.         function is, by default, case insensitive.
  357.  
  358.     INPUTS
  359.  
  360.         options - "InStem/A,OutStem,Descend/S,NoDupes/S,Case/S"
  361.  
  362.             "InStem/A"  - Stem to be sorted. All entries will be
  363.                           overwritten by the sorted ones.
  364.  
  365.             "OutStem"   - Optionally you can give an output stem
  366.                           where store all sorted entries leaving
  367.                           the InStem untouched.
  368.  
  369.             "Descend/S" - Sort in alphabetical descend order (default
  370.                           is "Ascend").
  371.  
  372.             "NoDupes/S" - Remove duplicates entries. 
  373.  
  374.             "Case/S"    - Force sort to be case sensitive.
  375.  
  376.     RESULT
  377.  
  378.         success - boolean value (1 mean all done, ok).
  379.  
  380.     EXAMPLE
  381.  
  382.         in.count = 20
  383.         DO n = 0 FOR in.count; in.n = ERRORTEXT(n); SAY in.n; END
  384.         IF StemSort("in. out.") THEN
  385.             DO n = 0 FOR out.count
  386.                 SAY out.n
  387.             END
  388.  
  389.     NOTES
  390.  
  391.         Use the tqsort() function to sort case sensitive and a built-in
  392.         Tqsort for sorting case insensitive.
  393.  
  394.     SEE ALSO
  395.  
  396. rexx_stem.library/StemWrite                        rexx_stem.library/StemWrite
  397.  
  398.     NAME
  399.  
  400.         StemWrite -- Write the given stem into a file.
  401.  
  402.     SYNOPSIS
  403.  
  404.         success = StemWrite(filepath,options)
  405.  
  406.     FUNCTION
  407.  
  408.         The function write entries from a given stem to a file.
  409.  
  410.     INPUTS
  411.  
  412.         filepath - Relative or absolute path. This argument must
  413.                    be provided.
  414.  
  415.         options  - "InStem/A,Append/S"
  416.  
  417.             "InStem/A" - The source stem to take entries from.
  418.  
  419.             "Append/S" - Don't overwrite the output file if exists.
  420.  
  421.     RESULT
  422.  
  423.         success - boolean value (1 mean all done, ok).
  424.  
  425.     EXAMPLE
  426.  
  427.         txt. = "Prova StemWrite()"; txt.count = 20
  428.         IF StemWrite("T:prova","txt.") THEN
  429.             SAY "All done..."
  430.  
  431.     NOTES
  432.  
  433.     SEE ALSO
  434.  
  435.         rexx_stem.library/StemRead()
  436.  
  437.  
  438.