home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _316f6862cb14b99c063422bc8e7a12dc < prev    next >
Text File  |  2000-03-23  |  9KB  |  261 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Sort::PolySort -- general rules-based sorting of lists</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Sort::PolySort -- general rules-based sorting of lists</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <UL>
  26.  
  27.         <LI><A HREF="#methods">METHODS</A></LI>
  28.         <LI><A HREF="#specs">Specs</A></LI>
  29.         <LI><A HREF="#parsing scheme">Parsing Scheme</A></LI>
  30.         <LI><A HREF="#named specs">Named Specs</A></LI>
  31.     </UL>
  32.  
  33.     <LI><A HREF="#errors">ERRORS</A></LI>
  34.     <LI><A HREF="#notes">NOTES</A></LI>
  35.     <LI><A HREF="#author">AUTHOR</A></LI>
  36.     <LI><A HREF="#copyright">COPYRIGHT</A></LI>
  37. </UL>
  38. <!-- INDEX END -->
  39.  
  40. <HR>
  41. <P>
  42. <H1><A NAME="name">NAME</A></H1>
  43. <PRE>
  44.         Sort::PolySort -- general rules-based sorting of lists</PRE>
  45. <P>
  46. <HR>
  47. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  48. <UL>
  49. <LI>Linux</LI>
  50. <LI>Solaris</LI>
  51. <LI>Windows</LI>
  52. </UL>
  53. <HR>
  54. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  55. <PRE>
  56.         use Sort::PolySort;
  57.         $s=new Sort::PolySort;                  # defaults to 'name'
  58.         @people=('John Doe','Jane Doll','John Quasimodo Doe');
  59.         print join(", ",$s->sort(@people),"\n";
  60. </PRE>
  61. <PRE>
  62.  
  63.         use Sort::PolySort;
  64.         $s=new Sort::PolySort('dateus');        # sets internal
  65.         @dates=$s->sort(@dates);                # uses internal
  66.         $s->by('email');                        # sets internal
  67.         @names=$s->sortby('name',@names);       # overrides internal
  68.         @emails=$s->sort(@emails);              # internal is still 'email'</PRE>
  69. <P>
  70. <HR>
  71. <H1><A NAME="description">DESCRIPTION</A></H1>
  72. <P>This module provides methods to sort a list of strings based on 
  73. parsing the strings according to a configurable set of specifications.</P>
  74. <P>
  75. <H2><A NAME="methods">METHODS</A></H2>
  76. <P>The following methods are available:</P>
  77. <DL>
  78. <DT><STRONG><A NAME="item_new"><EM>new</EM></A></STRONG><BR>
  79. <DD>
  80. Creates a new polysort object. Takes optional arguement of initial
  81. named spec set (defaults to <EM>name</EM>).
  82. <P></P>
  83. <DT><STRONG><A NAME="item_by"><EM>by</EM></A></STRONG><BR>
  84. <DD>
  85. Configures for the named set of sorting specs. Arguement is name of spec set.
  86. <P></P>
  87. <DT><STRONG><A NAME="item_sort"><EM>sort</EM></A></STRONG><BR>
  88. <DD>
  89. Sorts by the previously-set (by <EM>new</EM> or <EM>by</EM>) specs. Arguement is a
  90. list of items to sort. Returns the sorted list, leaving the original
  91. unchanged.
  92. <P></P>
  93. <DT><STRONG><A NAME="item_sortby"><EM>sortby</EM></A></STRONG><BR>
  94. <DD>
  95. Sorts by the given (named) set of specs. The specs are only changed for
  96. this particular sort, so future calls to <EM>sort</EM> will use whatever
  97. specs were in effect before the <EM>sortby</EM> call. First arguement is
  98. name of spec set, second arguement is a list of items to sort. Returns
  99. the sorted list, leaving the original unchanged.
  100. <P></P>
  101. <DT><STRONG><A NAME="item_get"><EM>get</EM></A></STRONG><BR>
  102. <DD>
  103. Returns an associative array of the current sort specs. See <A HREF="#notes">NOTES</A>.
  104. <P></P>
  105. <DT><STRONG><A NAME="item_set"><EM>set</EM></A></STRONG><BR>
  106. <DD>
  107. Sets the current sort specs to the given associative array. Specs not
  108. appearing in the passed array retain their previous values, so this
  109. method can be used along with <EM>get</EM> to keep state during a subroutine
  110. call or to alter particular specs to get new sorting
  111. results. Arguement is an associative array. See <A HREF="#notes">NOTES</A>.
  112. <P></P></DL>
  113. <P>
  114. <H2><A NAME="specs">Specs</A></H2>
  115. <P>The following specifications are local to each Sort::PolySort object:</P>
  116. <DL>
  117. <DT><STRONG><A NAME="item_GLOBTOP"><CODE>GLOBTOP</CODE></A></STRONG><BR>
  118. <DD>
  119. Lump last two levels together?
  120. <P></P>
  121. <DT><STRONG><A NAME="item_LEVELS"><CODE>LEVELS</CODE></A></STRONG><BR>
  122. <DD>
  123. Number of levels to consider (0=all)
  124. <P></P>
  125. <DT><STRONG><A NAME="item_R2L"><CODE>R2L</CODE></A></STRONG><BR>
  126. <DD>
  127. Count fields right to left?
  128. <P></P>
  129. <DT><STRONG><A NAME="item_NUMERIC"><CODE>NUMERIC</CODE></A></STRONG><BR>
  130. <DD>
  131. Do numerical sort?
  132. <P></P>
  133. <DT><STRONG><A NAME="item_CASE"><CODE>CASE</CODE></A></STRONG><BR>
  134. <DD>
  135. Do case-sensitive sort?
  136. <P></P>
  137. <DT><STRONG><A NAME="item_DELIM1"><CODE>DELIM1</CODE></A></STRONG><BR>
  138. <DD>
  139. Primary element delimiter (must not be null).
  140. <P></P>
  141. <DT><STRONG><A NAME="item_DELIM2"><CODE>DELIM2</CODE></A></STRONG><BR>
  142. <DD>
  143. Secondary element delimiter (can be null).
  144. <P></P></DL>
  145. <P>
  146. <H2><A NAME="parsing scheme">Parsing Scheme</A></H2>
  147. <P>The following order is followed to determine the keys used to sort the
  148. given array:</P>
  149. <OL>
  150. <LI>
  151. <EM>DELIM2</EM> (if given)
  152. <P>Remove up to leftmost (rightmost if <EM>R2L</EM> is true) occurance of <EM>DELIM2</EM> 
  153. (will be brought back later).</P>
  154. <P></P>
  155. <LI>
  156. <EM>DELIM1</EM>
  157. <P>Split remainder at all occurances of <EM>DELIM1</EM>.</P>
  158. <P></P>
  159. <LI>
  160. <EM>GLOBTOP</EM> (if true)
  161. <P>Rejoin left (right if <EM>R2L</EM> is true) 2 elements (always joined left-to-right, 
  162. regardless of <EM>R2L</EM>).</P>
  163. <P></P>
  164. <LI>
  165. <EM>R2L</EM> (if true)
  166. <P>Reverse list of elements.</P>
  167. <P></P>
  168. <LI>
  169. <EM>LEVELS</EM>
  170. <P>Store first <EM>LEVELS</EM> (all if =0) elements (last 2 considered as a 
  171. single element if <EM>GLOBTOP</EM> is true).</P>
  172. <P></P>
  173. <LI>
  174. <EM>DELIM2</EM> (if true)
  175. <P>Store string from left of <EM>DELIM2</EM> as next element.</P>
  176. <P></P>
  177. <LI>
  178. <EM>LEVELS</EM> (unless 0)
  179. <P>Rejoin remaining elements (in original order, regardless of <EM>R2L</EM>) and 
  180. store as next element.</P>
  181. <P></P></OL>
  182. <P>
  183. <H2><A NAME="named specs">Named Specs</A></H2>
  184. <P>The following (case-sensitive) names are used by <EM>new</EM>, <EM>by</EM> and
  185. <EM>sortby</EM> to represent pre-defined sets of specs:</P>
  186. <DL>
  187. <DT><STRONG><A NAME="item_datebr"><EM>datebr</EM></A></STRONG><BR>
  188. <DD>
  189. by European (dd/mm/yy) date
  190. <P></P>
  191. <DT><STRONG><A NAME="item_dateus"><EM>dateus</EM></A></STRONG><BR>
  192. <DD>
  193. by US-style (mm/dd/yy) date
  194. <P></P>
  195. <DT><STRONG><A NAME="item_email"><EM>email</EM></A></STRONG><BR>
  196. <DD>
  197. by user for each machine (all parts of FQDN)
  198. <P></P>
  199. <DT><STRONG><A NAME="item_email2"><EM>email2</EM></A></STRONG><BR>
  200. <DD>
  201. by user for each top-level domain (last 2 atoms)
  202. <P></P>
  203. <DT><STRONG><A NAME="item_emaild"><EM>emaild</EM></A></STRONG><BR>
  204. <DD>
  205. by user for each domain-name (next-to-last atom)
  206. <P></P>
  207. <DT><STRONG><A NAME="item_ip"><EM>ip</EM></A></STRONG><BR>
  208. <DD>
  209. by numerical (aaa.bbb.ccc.ddd) ip address
  210. <P></P>
  211. <DT><STRONG><A NAME="item_name"><EM>name</EM></A></STRONG><BR>
  212. <DD>
  213. by last name/first name/middle name or initials
  214. <P></P></DL>
  215. <P>
  216. <HR>
  217. <H1><A NAME="errors">ERRORS</A></H1>
  218. <P>The following errors may occur:</P>
  219. <DL>
  220. <DT><STRONG><A NAME="item_No_specname_given"><STRONG>No specname given</STRONG></A></STRONG><BR>
  221. <DD>
  222. <EM>by</EM> or <EM>sortby</EM> wasn't passed a specname.
  223. <P></P>
  224. <DT><STRONG><A NAME="item_Never_heard_of_specname_%60%60foo%27%27"><STRONG>Never heard of specname ``foo''</STRONG></A></STRONG><BR>
  225. <DD>
  226. <EM>new</EM>, <EM>by</EM>, or <EM>sortby</EM> was passed a name that was not in the list of
  227. known specnames.
  228. <P></P></DL>
  229. <P>
  230. <HR>
  231. <H1><A NAME="notes">NOTES</A></H1>
  232. <P>The whole parsing method is pretty perverse, but honestly was the first
  233. thing that came to mind. It works, but is not very fast or extensible.
  234. Enough interested folks mailed me that I wanted to get this out now, but
  235. it's dyin' for a rewrite. So this is just a beta. The main interface will
  236. remain the same, but the parser will be rewritten and the spec variables
  237. changed. Accessor methods will change as a result (using <CODE>%s=$s-</CODE>get; ...
  238. ;$s-><A HREF="#item_set"><CODE>set(%s)</CODE></A> will probably still work to save state, though). And accessor
  239. methods wll be added so that new names spec sets can be added at runtime
  240. or known ones modified. And new named spec sets will be added. And on and
  241. on and on...</P>
  242. <P>
  243. <HR>
  244. <H1><A NAME="author">AUTHOR</A></H1>
  245. <P>Daniel Macks <<A HREF="mailto:dmacks@netspace.org">dmacks@netspace.org</A>></P>
  246. <P>
  247. <HR>
  248. <H1><A NAME="copyright">COPYRIGHT</A></H1>
  249. <P>Copyright (c) 1996 by Daniel Macks. All rights reserved.
  250. This module is free software; you may redistribute it
  251. and/or modify it under the same terms as Perl itself.</P>
  252. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  253. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  254. <STRONG><P CLASS=block> Sort::PolySort -- general rules-based sorting of lists</P></STRONG>
  255. </TD></TR>
  256. </TABLE>
  257.  
  258. </BODY>
  259.  
  260. </HTML>
  261.