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