Copyright: "Copyright (C) 1993-94-95 Yves Roumazeilles"


YGrep Search Engine
The YGrep Search Engine

The YGrep Search Engine (YGREP.DLL) is the name of a Dynamic Link Library built for MS-Windows by Yves Roumazeilles and which is able to provide two search functionalities:

Approximative Search

Regular Expression Search

It can be found bundled with some applications like ClusterView. But, more to the point, you can use it to enhance your own applications.

New features

Alphabetical list of functions

Function groups

Structures

Registration information

Future developments

FTP and Compuserve availability

Common questions and features

The YGrep Search Engine was brought to life to by an effort to materialize the knowledge I acquired in text processing in the recent years.

On one hand, as I am sure you already infered, AGREP is the traditional name for Approximative Search. The notion has been brought to light - at least mine - by Ricardo Baeza-Yates and Gaston H.Gonnet under the name of Shift-Or (or Shift-Add) search method. To my knowledge, the name of agrep was originally adopted by Sun Wu and Udi Manber for a Unix utility implementing a similar algorithm.

On the other hand, Regular Expression Search is based on old work by many researchers on automaton logic. Many implementations have already been found on Unix systems (under the application names of ed(1) and grep(1)) and others including Vax-VMS, DOS, CP/M, etc. They often differ from the original one from Unix, but most power users now recognize easily the common syntax and appreciate its powerful capabilities.

I added some extensions which were not in the original Unix version. In that I was following the interface specification of various authors including David Conroy (original author of the superb MicroEmacs editor which I advise you to use in its more recent version by Daniel Lawrence for your MS Windows editing tasks), Ozan S. Yigit and Karl Hoorsfish. To that I had to add my own salt and pepper to get a working interface. The original version of this Regular Expression Search was inserted in the YR-Emacs public domain text editor I wrote on the basis of the afore mentionned MicroEmacs editor.

I apologize for omitting many of the other sources of my little knowledge in the field of programming.


New API
New features

Version 4.06 solves the problem of not getting a hit for regular expression ".*" when matching against an empty string.

Version 4.05 solves a no-match-case search problem in regular expressions.

Version 4.04 is the first version allowing full text substitution with the new functions:

AGrepSubstitute

RGrepSubstitute

SAGrepSubstitute

SRGrepSubstitute

Users will certainly prefer them to the old AGrepSubsBuild and RGrepSubsBuild which are still available for upward compatiblity.

Version 4.03 is adding improved documentation and some important new download instructions. Support on Compuserve has been added from our new address there (101233,1032).

Both are dwarfed by the apparition of the first 32-bit programming model version of the YGrep Search Engine. If you downloaded only the 16-bit version, you should look into the Windows 95 part of your BBS, FTP site or library.

Version 4.02 is adding the important new layer of functions with only scalar parameters. This allows to use more easily the YGrep Search Engine with Visual Basic and other programming languages which have difficulties calling too complex functions or functions with very complex parameters.

Version 4.01 is more or less a maintenance release with bug removal, performance improvements, documentation improvements, size reduction, help file improvements.

In version 4.00, the name was changed from AGrep Search Engine to YGrep Search Engine, in order to avoid confusion with existing Unix/Linux utility named agrep.

I also removed some bugs, optimized out a few bytes, removed some compilation warnings, and did a lot of field testing with the beta testers.

In version 3.02, the following functions were added:

AGrepSubsBuild

RGrepSubsBuild

InitWordCharTable

AddWordChar

RemoveWordChar

You may also have noticed that the documentation has been improved a lot. Many typos were removed, and many little errors were corrected (including - shame on me! - the removal of a subject page having nothing to do with the whole subject). A database of common questions and features has been added to this help file to improve the efficiency of your bug busting and your understanding of the operation of the whole YGrep Search Engine.

You may not have noticed, but the performance was improved, some bugs were found by the users (yes! it's you) and removed. Thanks for your help!

A new version of the YGrep Search Engine for MS-DOS is now available.


Future developments

If you register conveniently, and keep on following the evolution of the YGrep Search Engine, you will see the following expected future developments real soon now:

 New improved memory management strategies for the registered versions

 Possible new ways to look for data


FTP Availability
FTP and Compuserve availability

The YGrep Search Engine is available through FTP (Internet file download). The reference storage is on the famous SimTel server:

ftp.coast.net           directory: SimTel/win3/dll             file: yg405win.zip

ftp.coast.net           directory: SimTel/win95/dll           file: yg406w95.zip

As you certainly recognized, one is for the 16-bit version (Windows 3.1) and the other is for the 32-bit version (WIN32S, Windows 95, Windows NT 3.51). But they don't have both the same version since the 16-bit version is now becoming obsolete. If you're interested in getting the 16-bit version anyhow (it still is registered in the different registration processes), you should contact the author directly.

However, SimTel is a rather famous location and people tend to overwhelm the capacity of the machine there. I suggest that you use one of the mirror sites (they keep a full copy of the original site among other things). Here are some of my preferred mirror sites:

src.doc.ic.ac.uk (155.198.1.40)              directory: /computing/systems/ibmpc/simtel-win95/dll

nic.switch.ch (130.59.1.40)                    directory: /mirror/simtel/win95/dll

ftp.unicamp.br 143.106.10.54)               directory: /pub/simtel/win95/dll

plaza.aarnet.edu.au (139.130.23.2)       directory: /micros/pc/SimTel/win95/dll

romulus.ucs.uoknor.edu (129.15.10.20) directory: /mirrors/Simtel/win95/dll

micros.hensa.ac.uk (194.80.32.51)        directory: /mirrors/simtel/win95/dll

ftp.jussieu.fr (134.157.0.130)                 directory: /pub7/pc/Simtel/win95/dll

Of course, you can also make an Archie search if you have access to it. And you will easily find the most appropriate file server near to you.

You can aslo join me by email for help or updated information...

The YGrep Search Engine is also available from Compuserve. You should look into the library of the "Windows Shareware Forum" (GO WINSHARE). The YGrep Search Engine can be found (and downloaded) from the "[22] Programming/Dev. tools" section. If you cannot find it here, reach me by Compuserve mail.


YGrep Search Engine approximative search

The approximative search is allowing you to find a text without knowing the exact form of what you are looking for. For example, you can look for text without taking into account the case of the letters (without making a difference between uppercase and lowercase letters).

The operation is centered on the fact that in most cases you know a text string which is "approximately" what you are looking for in your files. Additionaly, you are able to say that you expect this text string to have a certain number of errors.

For example, the string 'East Germany' is approximately identical to 'West Germany', but there are 2 errors (the first two letters of the words) and 10 matches.


Regular expression search

The regular expression search is allowing you to find a text based on a description which will help you be more precise than with Approximative Search, but also more difficult to handle before you get used to it.

To give you a first look at what can be done (without going too far into the regular expressions syntax), here are a few of the possibilities.

You can search for pattern in the beginning (or in the end) of the lines, ignoring the similar patterns which appears in the middle. You can search for telephone numbers (XXX-X-XXX-XXXX), dates (XX/XX/XX), times (XX:XX), three-figure-numbers (XXX), or any other strictly formed field of numbers. but you can also look for patterns a little more evasive like: four letter-words containing no figures, but beginning with an S letter either in lower- or uppercase and in the end of a line (that is defined by the pattern '\<[Ss][^0-9_][^0-9_][^0-9_]\>$').

For an extended specification of the regular expression used, see also Regular Expressions


YGrep regular expressions
YGrep Search Engine regular expressions

The YGrep Search Engine regular expression routines support the full range of Unix regular expressions as defined in ed(1) and in grep(1).

Specification

 ^ 	A circumflex as the first character of the pattern forces matches to beginning of lines.

$ 	A dollar as the last character of the pattern forces matches to end of lines.

. 	A period anywhere in the string matches any single character.

*	An expression followed by a asterisk matches zero or more occurrences of that expression.

+	An expression followed by a plus sign matches one or more occurrences of that expression.

-	An expression followed by a minus sign optionally matches that expression.

[]	A string enclosed in square brackets matches any character in that string, but no others. If the first character of the string is a circumflex the expression matches any character except the characters in the string. A range of characters may be specified by two characters separated by a -.

\<	A backslash followed by an opening < matches the beginning of a word.

\>	A backslash followed by a closing > matches the end of a word.

\(	A backslash followed by an opening ( describes the beginning of a tagged sub-expression (see Substitution Expressions, it has no effect on search-only expressions).

\)	A backslash followed by a closing ) describes the end of a tagged sub-expression (see Substitution Expressions, it has no effect on search-only expressions).

\	A backslash folowed by any other character quotes that character. This allows a search for a character that is usually a regular expression specifier.

Examples

^Windows	matches all lines starting with Windows

Grep$      	matches all lines ending with Grep

H..p        	matches all lines containing Help, Hoop, Harp, etc.

^W.n       	matches all lines starting with Win, Won, etc.

\$            	matches a dollar sign

fo*          	matches f, fo, foo, etc.

fo+          	matches fo, foo, etc.

[xyz]       	matches x, y and z

a[^xyz]c  	matches abc, arc and aXb but not axb

([0-9])      	matches (0), (1), (2), (3), (4), (5), (6), (7), (8) and (9)

([0-9]*)    	matches (), (0), (123), (2512), etc.

\<[Aa].*\>     	matches any non-empty word beginning with either a or A


YGrep substitution expressions
YGrep Search Engine substitution expressions

The YGrep Search Engine regular expression substitution routines support a small set of expressions to define how the substitution will be performed.

Specification

&           	An ampersand in the substituted string forces insertion of the full matched pattern.

\number 	A backslash followed by a number forces the insertion of the tag matched with the equivalent number in the pattern.

\&	 	An escape sequence to allow the insertion of the & character (while removing its matched pattern meaning).

Examples

Patterns	Substitution

Windows             	MS-&     	replaces all occurences of Windows with MS-Windows

\(dows\)\([Ww]in\) 	\2\1        	allows to reorder the pattern dowsWin into the normal Windows regardless of the letter-casing of the W in the beginning of the word

Note that \0 is equivalent to & and they both match the whole found string.


YGrep Search Engine Limitations

The YGrep Search Engine is limited in both the length of the pattern it can manage and in the maximum number of errors it accepts.

The length of the pattern is limited to 512 letters maximum.

The number of errors is limited to 256 maximum.

Both of them are limited by the following formula:

length_of_pattern <= 512 / (log2(number_of_errors) + 1)

The simple meaning of this formula is that if you have a long pattern, you cannot have a large number of errors. For example, with a 256 character pattern you must limit yourself to 1 error only. In most cases, this is not too limiting, but it should be noticed.

To partly overcome that constraint it is also possible to use the non-cased text search fonctionality.

Should you need to have a limitation placed higher or lower, please, contact the author for a customized version (this is not much more expensive than a standard package) or a source code license.


Registration Fee
Single User Registration Fee

Yes! We remind you the single user license fee is only a mere 95FF or US$20.


Registering The YGrep Search Engine

The YGrep Search Engine is distributed as ShareWare. It is not free or public domain. This means you may copy and distribute it freely but should you find it useful and use it beyond an initial evaluation period of 30 days you are both legally and morally obliged to pay the registration fee or license fee.

Yes, I want to register now!

Yves Roumazeilles - the author     	France - money transfers / no credit cards

Public (Software) Library              	US - credit card orders

Compuserve SWREG registration	Worldwide - CIS customers

What you get when registering

This is the important question. Here is the list:

- updated and optimized full YGrep Search Engine with the license to use it on a single computer. This will include a complete registered MS-Windows DLL, and libraries for MS-DOS (small, compact, medium, and large memory models).

- user documentation on plain paper (more than 60 pages of code, reference data, advice and answers to questions)

- an immediate notice when a new release is ready on the market.

- rebate coupons for upgrading to new releases.

- source code of the this help file to allow you to easily build the help file for YOUR application. This will reduce your work when preparing your application to ship and you may find interesting ideas on how to build a nice help file for MS-Windows.

- source code for useful resources you can use in your application (dialogs, etc) in relation with the YGrep Search Engine.

- sample files for different languages when available.

- a registration number to identify yourself when contacting us.

- support through fax, phone and Email.

- access to our database of bug reports between releases. No release is done while this database contains even a single bug. We do not ship products we know contain bugs. But after shipping, users may discover ugly things in our code, and we trace them while we hunt them.

Commercial software and shareware developpers

You can get a complete Developper Kit for a flat rate including unlimited royalty-free right to distribute the registered Dynamic Link Library in your product. This allows you to include it in your nice universal text editor or encryption package.

Customized versions can also be obtained from the author (me, of course) upon request and after acceptance of a specific quotation (most customizations can be obtained for about twice the Developper Kit registration license fee).

Remember that you can also ask for source licenses which will include full C source code, with full resources, definition files (everything you need to rebuild the YGrep Search Engine from scratch). I cannot give more. Well! May be not give, because you pay for it. But, it's a bargain you could discuss with me if you need this.

Acknowledgments

I would like to thank the following people whose help has been invaluable during the development of the YGrep Search Engine:

Christian Lescuyer provided the original idea and a large amount of time for product testing (even in alpha state).

Anne Elisabeth Halpern proved that the concept was usable by exploiting it during years in the process of preparing her litterature thesis about Michaud (belgian french-writing poet and painter). She provided permanent confidence even when her own work was overwhelming.

Martin Heller for his excellent book "Advanced Windows Programming" published by John Wiley & Sons. This is the most useful book about Windows programming I ever found. If you intend to do MS Windows programming, you NEED it.

The whole WIN3-L@UICVM.BITNET internet mailing list who provided help when I was stopped in the development process. Not all the subscribers (more than 2000 currently) provided help, but a dozen of them are very proficient and helpful. I can remember and thank Walter Knopf, Yossi Oren, Yoav Chernobroda and Vance Gloster, and many others...


Registration Form - YR
Registration form

Yves Roumazeilles - author

Select "File-Print Topic" from the menu bar to print this form. You will then be able to fill it. You can accompany you order with check. Credit cards are NOT accepted. You can order by phone or fax.

Please use the form when ordering by mail.

NAME:  __________________________________________

COMPANY:  ______________________________________

ADDRESS:  ______________________________________
                   ______________________________________
                   ______________________________________

TOWN:  __________________________________________

CITY:  ___________________________________________

POSTCODE:  ________  COUNTRY/STATE:  ____________

TELEPHONE: _______________________

FAX:               _______________________

EMAIL:           _______________________

YGrep Search Engine
Single user license ($20 or 95 French Francs)	  ________
Developer kit license ($295 or 1410 French Francs)	  ________

BitList Engine
Single user license ($20 or 95 French Francs)	  ________
Developer kit license ($295 or 1410 French Francs)	  ________

ClusterView Application
Single user license ($20 or 95 French Francs)	  ________

Shipping/Handling to Europe ($4 or 20 French Francs)	  ________

Shipping/Handling outside of Europe ($6 or 30 French Francs)	  ________

==========

Sub-Total....	  ________

European residents, apply VAT/TVA 18.6% (on sub-total)	  ________

==========

Total...........	  ________

Here, shipping/handling costs are applied once even for multiple orders.

Make cheques payable to: Yves Roumazeilles

If you wish to pay in other currencies than French Francs or dollars, apply the normal change rate to French Francs and add a 6% increase to cover the costs my bank charges me. Thank you.

Mail to:

Yves Roumazeilles
63 rue des Moines
75017 PARIS
     (FRANCE)

This address is also the place where you can get information of various kinds (about the status of the shipment of the order, registration options, product details, technical support, volume discounts, dealer pricing, etc.)

Phone: +33-1-42.28.74.51
Fax: +33-1-30.73.24.40
Email: 101233.1032@compuserve.com, (or Roumazeilles@sagem.fr)
Compuserve ID: 101233,1032


Registration Form - PsL
Registration form

Public (Software) Library - registration service

Select "File-Print Topic" from the menu bar to print this form. You will then be able to fill it.

You can order with MC, Visa, Amex, or Discovery from the Public (Software) Library by callingYou can accompany you order with check. Credit cards are NOT accepted. You can order by phone or fax. But these numbers are for placing an order only!

Please use the form when ordering by mail.

NAME:  __________________________________________

COMPANY:  ______________________________________

ADDRESS:  ______________________________________
                   ______________________________________
                   ______________________________________

TOWN:  __________________________________________

CITY:  ____________________________________________

POSTCODE:  ________  COUNTRY/STATE:  ____________

TELEPHONE:  _______________________

FAX:               _______________________

EMAIL:           _______________________

YGrep Search Engine (item/product #11244)
Single user license ($20)	  ________
Developer kit license ($295)	  ________

BitList Engine (item/product #11245)
Single user license ($20)	  ________
Developer kit license ($295)	  ________

ClusterView Application (item/product #11246)
Single user license ($20)	  ________

Shipping/Handling to Europe ($4)	per license	  ________

Shipping/Handling outside of Europe ($6) per license	  ________

==========

Sub-Total....	  ________

==========

Total...........	  ________

Contact one of the following:

by phone: 800-2424-PsL or Intl+1+713-524-6394

or by FAX: Intl+1+713-524-6398

or by CIS/Compuserve Email to 71355,470

or send mail to:
PsL
P.O. Box 35705
Houston, TX 77235-5705
     (United States of America)

Remember! The above numbers are for orders only. You cannot expect any kind of support through them. If you call there, not only will you be left without an appropriate answer, but I will have to pay for the useless call. PLEASE, if you do not like the long distance calls involved with my address in France, do prefer sending a Fax (it won't hang your phone too long), sending an Internet Email (it won't cost too much, and Compuserve, BIX, AOL all have Internet gateways for your mail - I know you are paying for that, I won't overuse it, but any Email with the product name in its subject field gets a very high priority).

Any questions about the status of the shipment of the order, registration options, product details, technical support, volume discounts, dealer pricing, site licenses etc, must be directed to:

Yves Roumazeilles
63 rue des Moines
75017 PARIS
     (FRANCE)
Phone: +33-1-42.28.74.51
Fax: +33-1-30.73.24.40
Email: 101233.1032@compuserve.com (or Roumazeilles@sagem.fr)
Compuserve ID: 101233,1032

To insure that you get the latest version, PsL will notify us the day of your order and we will ship the product directly to you.


Registration Instructions - Compuserve
Registration instructions

Compuserve SWREG - registration service

This is the on-line registration service for Compuserve customers. It allows on-line, immediate, direct registration.

You should GO SWREG, to join the Shareware Registration Forum. You will then be asked the reference of the software product you want to get. Take it from the following list:

YGrep Search Engine v4.0 (item/product #)
Single user license ($20)      	Id# 7811
Developer kit license ($295)	No Id# yet

ClusterView v2.0 Windows 3.1 Application (item/product #)
Single user license ($20)      	Id# 7812

ClusterView v2.0 Win32/WinNT/Win95 Application (item/product #)
Single user license ($20)      	Id# 7814

Shipping/Handling to Europe ($4)      	per license

Shipping/Handling outside of Europe ($6) per license

Any questions about the status of the shipment of the order, registration options, product details, technical support, volume discounts, dealer pricing, site licenses etc, must be directed to:

Yves Roumazeilles
63 rue des Moines
75017 PARIS
     (FRANCE)
Phone: +33-1-42.28.74.51
Fax: +33-1-30.73.24.40
Internet Email: 101233.1032@compuserve.com (or roumazeilles@sagem.fr)
Compuserve ID: 101233,1032

To insure that you get the latest version, Compuserve will notify us the day of your order and we will ship the product directly to you.


Copyright and User License
Application Copyright and User License

The YGrep Search Engine Dynamic Link Library (DLL) and its documentation files and manuals are copyrighted (C) 1992-93-94-95 by Yves Roumazeilles. Their use is subject to the acceptance of the User License terms.

All the names used here are trademarks and registered trademarks of their respective owners.

Registration Fee

If you are using the YGrep Search Engine after the initial 30 day evaluation period, you must pay the license to continue using the package. This payement is named registration fee.

For use by corporations and other institutions, please contact the author for a licensing arrangement. Customizing and other special licensing are available upon request.

If you want to get the full source code of the library or of one of its components, please contact the author for a licensing arrangement.

Shareware User License

The program files and the associated documentation (e.g. this documentation) are copyrighted by the author. The copyright owner hereby licenses you to use the software given these restrictions:

*	The program shall be supplied in its original, unmodified form, which includes this documentation.

*	For-profit use without a license is prohibited.

*	The program may not be included - or bundled - with other goods or services. The licensed version is ready there for this purpose.

*	No fee is charged. An exception is granted for not-for-profit user's group, which are permitted to charge a small fee (under $5) for materials, handling, postage and general costs. No other organization is permitted to charge any amount for distribution of copies of the software or documentation, or to include copies of the software or documentation with sales of their own products.

There is no warranty of any kind (either implied or not). The copyright owner may not be held liable for any damages, including any lost profits or other incidental or consequential damages arising out of or inability to use the software. By using the software, you agree to this.


Common Questions and Features

If you have some problem while using the YGrep Search Engine it's the right place to look for a solution. The most common problems encountered by users (both end users and developpers) are stored in this unstructured database (in my mind unstructured means "with strictly no order").

 Note 001	I cannot load the DLL, while I could some time ago.

 Note 002	How do I initialize the expiration date?

 Note 003	I am not sure what a [z-a] pattern would match.

 Note 004	My application seems to slow down while using the YGrep Search Engine and then stops because of lack of memory.

 Note 004	After some number of searches, I cannot get anything other than "not enough memory" messages.

 Note 005	YGrepEmpty takes too much time in executing.

 Note 006	The YGrep Search Engine is great, but I would like to have it under MS-DOS.

 Note 007	In some cases, I get a General Protection Fault from either AGrep or RGrep.

 Note 008	CompileAGrep does not accept my large patterns or patterns with a large number of allowed errors.

 Note 008	What are the limitations of the YGrep Search Engine?

 Note 009	I only want to match patterns with no regular expressions, no approximation.

 Note 010	How do I know the version level of a specific YGREP.DLL?

 Note 011	In some cases, AGrep (or RGrep) will never return when called.

 Note 012	I am not able to find explanations about how to use the AGrepInit function.

 Note 013	I cannot compile with the Small or Compact memory model.

 Note 013	I keep on getting stack overflows from the application I built.

 Note 014	I do not find all the matches in the line. There are 12 of them and the returned value is less than that.

 Note 015	I work with FoxPro (or another programming language) which cannot call the YGrep Search Engine functions


Note 001
I cannot load the DLL, while I could some time ago.

The YGrep Search Engine shareware edition package is distributed for an evaluation period of 30 days. The software automagically detects the end of the period and stops accepting load requests. The expiration date of the shareware license has been reached... You should register now. I will send you immediately an up-to-date and unlimited package.

If you are using a registered package, you have certainly changed something in your computer/application configuration to stop the DLL loading process. It is a process which des not need many things and little memory, for sure.


Note 002
How do I initiliaze the expiration date?

You do not have to. The software automagically determines it and stores it appropriately.


Note 003
I am not sure what a [z-a] pattern would match.

While [a-z] matches any lower case letter, the [z-a] matches nothing at all. You have to be cautious with the order of the letter you put between the brackets when you define a set.

But if you give all the intermediate letters, the order is meaningless. [abcdefghij] is equivalent to [bcadefihgj] and to [a-j].


Note 004
My application seems to slow down while using the YGrep Search Engine and then stops because of lack of memory.

After some number of searches, I cannot get anything other than "not enough memory" messages.

If you're an end-user.

The application calling the YGrep Search Engine has a bug in it. Call your product support and you can shorten the response time by stating that it could be related to "a memory leak in YGrep Search Engine, for not using AGrepEmpty". Then wait for a correction of the bug.

If you're a developper.

Did you remember to call the appropriate AGrepEmpty function after you no longer need the AGREPINFO structure? It is necessary to free memory used by data structures pointed to by elements of AGREPINFO, before freeing the structure itself.

This is a two step process, first release indirect memory by calling AGrepEmpty:

AGrepEmpty( aGI );

Then, free the structure by calling the traditional memory de-allocator free:

free( aGI );


Note 005
AGrepEmpty takes too much time in executing.

Some low-memory configuration may have difficulties in freeing memory with AGrepEmpty. This leads to long waiting time while running through this routine (up to 2 seconds in slow PC with low-memory condition).

You can either try to reduce the overall memory use of the application by unlocking as much global memory as possible before calling the AGrep family routines, or we can provide a customized YGrep Search Engine which would only use local memory instead. The difference may not appear great in most cases, but could specifically help your project.

You can also try to preserve an AGREPINFO structure after compiling a pattern to avoid repetitively calling CompileAgrep/AgrepEmpty.


Note 006
The YGrep Search Engine is great, but I would like to have it under MS-DOS.

That's not a problem. If you cannot find it on your usual BBS or Internet site, ask me. I have already available MS-DOS and Windows versions of the YGrep Search Engine.

Furthermore, when you register, you get both versions simultaneously. That's a bargain!


Note 007
In some cases, I get a General Protection Fault from either AGrep or RGrep.

It is always possible that you found a bug in the YGrep Search Engine. However, the most current cause of this kind of behaviour appears to be a program compiling an expression and then providing the optimized data structure to the wrong function (e.g. calling AGrep with an RGREPINFO structure, or RGrep with an AGREPINFO structure). Both types of structures are positively incompatible with each other and should not be used with the wrong library function.

Another very common situation appears when a user forget that the Windows version MUST be compiled in the Large memory model. All others (Tiny, Small, Medium, or Compact) are not currently supported. In the future, the Medium memory model could become also available. But, there appears to be no hurry.

The MS-DOS version  has not this limitation. You can use any of the models.


Note 008
CompileAGrep does not accept my large patterns or patterns with a large number of allowed errors.

What are the limitations of the YGrep Search Engine?

That's normal. there are some limitations you will have to live with. If necessary, you can contact the author (me) in order to get a specifically customized version.


Note 009
I only want to match patterns with no regular expressions, no approximation.

That's quite normal! Look at the AGrep with a parameter of 0 errors (k=0). This will be detected and will call strstr with the only difference that you still are able to use the 'Match case' capability. However, if you look for sheer efficiency, you should be thinking of calling directly strstr from your compiler library. It has the advantage of avoiding you the optimization test at the entry of AGrep before calling strstr. This is a very small speed improvement, but sometimes...


Note 010
How do I know the version of a specific YGREP.DLL?

There are two ways. The simplest is to look at the date of the file YGREP.DLL. However, you could encounter files whose date have been modified by the BBS where you got the YGrep Search Engine (this does not occur when obtaining the original files from the author - when registering). In that case, you should use the YGrepVersion function to get the actual version number.

Additionnally, if you got the appropriate tool, you can find the version number in the header of the YGREP.DLL file (in the library name field). But this may lead to some imprecision as the minor version number is not included in this message.


Note 011
In some cases, AGrep (or RGrep) will never return when called.

First, you may want to look at Note 007 and particularly to notice that you should compile your Windows application for the Large memory only.

In some cases, I observed that users where expecting a result from the calls in too short a time. It's rather uncommon, but AGrep (more than RGrep) can take some time in handling some very long patterns on the slowest machines.

Well! You may have found a bug, of course. Look for your registration number and reach me, please.

If you did not register, here comes the registration form and my address. Registration information


Note 012
I am not able to find explanations about how to use the AGrepInit function

That is normal. Even if this function is declared in the YGREP.H header file, it should not be used. It is reserved for debugging purposes (debugging of the library, not of your application).

Do not look for it.


Note 013
I cannot compile with the Small or Compact memory model

I keep on getting stack overflows from the application I build

The problem is simply that these memory models only allow a single data segment of 64 kbytes. The problem is that the AGREPINFO is a very large data structure. Allocating from the stack or from the static data is a very large stress for such a small space. However, if you alllocate it dynamically (with malloc() or calloc() as in the sample code provided) you may - at least - be able to know that allocation failed.

In some cases, this problem appears as a "stack overflow" at init time for your application (when the application allocates space for the initial stack).


Note 014
I do not find all the matches in the line. There are 12 of them and the returned value is less than that

If you check their description pages, RGrep and AGrep are limited to a certain number of matches. It depends on how many matches can be "documented" in the TagStart/TagEnd fields.

RGrep can only indicate one match (or none). AGrep can only indicate up to MAXTAG matches (or none). If the searched line contains more matches than that, they will come undetected and you will have to advance the search pointer in the line.

The sweeping search example in the reference manual is doing just that.


Note 015
I work with FoxPro (or another programming language) which cannot call the YGrep Search Engine functions

Look at the scalar-parameter-only functions [they have the same name as the original functions - SAGrep() for AGrep() ]. The main difference is that the scalar-parameter-only functions do use an internal XGREPINFO data structures and, therefore, do not need more than null-terminated strings and integers.


Note 016
Note 16

Note 16


Alphabetical list of functions

AddWordChar

AGrep

AGrepEmpty

AGrepInit

AGrepSubsBuild (please prefer the following function)

AGrepSubstitute

CompileAGrep

CompileRGrep

InitWordCharTable

RemoveWordChar

RGrep

RGrepSubsBuild (please prefer the following function)

RGrepSubstitute

SAGrep

SAGrepEmpty

SAGrepSubsBuild (please prefer the following function)

SAGrepSubstitute

SCompileAGrep

SCompileRGrep

SRGrep

SRGrepSubsBuild (please prefer the following function)

SRGrepSubstitute

YGrepVersion


Function groups

Initialization function

Approximative Search functions

Regular Expression Search functions

Functions with only scalar parameters

other functions


Initialization functions

Functions used to initialize the YGrep Search Engine:

The initialization of the Dynamic Link Library (DLL) is done by the internal LibMain function and needs no specific documentation.

Functions used to initialize some ot the behaviour of the AGrep group of functions:

AGrepInit

Functions used to initialize some ot the behaviour of the RGrep group of functions:

AddWordChar

InitWordCharTable

RemoveWordChar


Approximative Search functions

AGrep

AGrepEmpty

AGrepInit

AGrepSubsBuild (please prefer the following function)

AGrepSubstitute

CompileAGrep


Regular Expression Search functions

CompileRGrep

RGrep

RGrepSubsBuild (please prefer the following function)

RGrepSubstitute


Substitution functions

AGrepSubsBuild (please prefer the following function)

AGrepSubstitute

RGrepSubsBuild (please prefer the following function)

RGrepSubstitute


Scalar functions
Scalar functions or functions with only scalar parameters

Some of the functions of the YGrep Search Engine are using a pointer on a complex structure to move around some important internal data between the different functions (AGREPINFO or RGREPINFO).

While being very flexible and memory efficient, these functions are difficult to call in some cases with development tools like FoxPro or Visual Basic. In order to reduce the burden on these tools, there is a set of equivalent functions which use an implicit (and therefore not user visible) parameter. These functions have exactly the same operation as there equivalent with extended parameters, a similar name (the scalar functions have a name with a prepended S - SRGrep is the scalar equivalent of RGrep).

Here is the list of these equivalent functions:

SAGrep

SAGrepEmpty

SAGrepInit

SAGrepSubsBuild (please prefer the following function)

SAGrepSubstitute

SCompileAGrep

SCompileRGrep

SRGrep

SRGrepSubsBuild (please prefer the following function)

SRGrepSubstitute


Other functions

YGrepVersion

Functions with only scalar parameters


Structures

AGREPINFO structure

RGREPINFO structure

XGREPINFO union

LPAGREPINFO type

LPRGREPINFO type

If you don't like twiddling with these types of parameters, you should have a look at the functions with only scalar parameters. They should simplify part of your work at the only expense of generality.


AGREPINFO structure
AGREPINFO

typedef  struct  tagAGrepInfo  {	/* agi */
int	iErrorCode;
char	cPat[WORD_SIZE];
LPSTR	TagStart[MAXTAG];
LPSTR	TagEnd[MAXTAG];
BLIST	uMask;
BLIST	uOvMask;
BLIST	uLimit;
BLIST	uTable[MAXSYM];
int	iBitsPerState;
int	iWordSize;
int	iType;
char	cUPat[WORD_SIZE];
} AGREPINFO;

The AGREPINFO structure contains information about the approximative search to be executed by the AGrep function.

Parameter	Description
iErrorCode	propagated error code
cPat	propagated pattern text string
TagStart	table of tags start
TagEnd	table of tags end
uMask	internal data
uOvMask	internal data
uLimit	internal data
uTable	internal data (characteristic vectors table)
iBitsPerState	internal data
iWordSize	internal data (actual size in bits of BLIST data structures)
iType	MATCH or MISMATCH
cUPat	internal data
Comments

Applications should use CompileAGrep to fill this data structure.


LPAGREPINFO type
LPAGREPINFO

typedef  AGREPINFO FAR*	LPAGREPINFO;

The LPAGREPINFO type is defined to provided a portable pointer to the AGREPINFO structure.


RGREPINFO structure
RGREPINFO

typedef  struct  tagRGrepInfo  {	/* rgi */
int	iErrorCode;
char	cPat[WORD_SIZE];
LPSTR	TagStart[MAXTAG];
LPSTR	TagEnd[MAXTAG];
int	bMatchCase;
int	iCircf;
char	cDFA[MAXDFA];
} RGREPINFO;

The RGREPINFO structure contains information about the approximative search to be executed by the RGrep function.

Parameter	Description
iErrorCode	propagated error code
cPat	propagated pattern text string
TagStart	table of tags start
TagEnd	table of tags end
bMatchCase	propagated match information
iCircf	match at beginning of line?
cDFA	automaton
Comments

Applications should use CompileRGrep to fill this data structure.


LPRGREPINFO type
LPRGREPINFO

typedef  RGREPINFO FAR*	LPRGREPINFO;

The LPRGREPINFO type is defined to provided a portable pointer to the RGREPINFO structure.


YGREPINFO union
YGREPINFO

typedef  struct  tagXGrepInfo  {	/* ygi */
union {
AGREPINFO	aGI;
RGREPINFO	rGI;
} y;
int	iTypeofInfo;	/* 0: empty, 1:AGREP, 2:RGREP */
} XGREPINFO;

The YGREPINFO union is provided as a way to help the user define a common structure for both types of searches.

Comments

This union is not currently used by the YGrep Search Engine. However, when a similar union will be needed, YGREPINFO will be use. Consequently, you can see it as a premium proposed to the users.


CompileAGrep function
CompileAGrep

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL CompileAGrep(LPCSTR lpText, UINT k, BOOL bMatchCase, AGREPINFO FAR* pGI)

LPCSTR  lpPattern;	/* pattern string to look for	*/
UINT  k;	/* number of errors	*/
BOOL  bMatchCase;	/* Match case in comparisons?	*/
AGREPINFO FAR*  pGI;	/* pointer to search information block	*/

The CompileAGrep function reprocesses the pattern in order to prepare approximative search.

Parameter	Description
lpPattern	Specifies the pattern to look for.
k	Specifies the number of errors for approximative match.
bMatchCase	Specifies whether the search operation should be case sensitive.
	Value	Meaning
	TRUE	Force letter case checking
	FALSE	Do not check letter casing
bMatchCase	Specifies whether the search operation should be case sensitive.
pGI	Pointer to an information block as will be used in a later to the AGrep function.
Returns

The returned value is one of the AGERR_* error codes. In case of normal operation (no error), the returned value is AGERR_NO_ERROR.

Comments

Following are the possible returned values for CompileAGrep:

Value	Meaning
AGERR_UNKNOWN_TYPE	YGrep Search Engine internal error (no available information on its origin). This normally results from semi-automatic checks. This error should be expected but should trigger a default action like exiting the application.
AGERR_NO_PATTERN	A pattern was expected and not found as argument.
AGERR_TOO_LONG	AGrep expression is too complex to handle in the internal structures of the YGrep Search Engine.
AGERR_ALLOC_MEM	Not enough memory to build internal structures of the YGrep Search Engine.
AGERR_STATE	Reserved for future use.
When setting the number of errors to 0, the returned value is always AGERR_NO_ERROR (there can be no error).

This function must be called at least once before calling AGrep.

The user is advised that trying to search for a short pattern with a large number may be useless (if more errors are allowed than there are characters in the pattern, the match will be trivial, and trivially detected in AGrep).

See Also

AGrep


AGrep function
AGrep

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL AGrep(LPCSTR lpText, AGREPINFO FAR* pGI)

LPCSTR  lpText;	/* text string to explore	*/
AGREPINFO FAR*  pGI;	/* pointer to search information block	*/

The AGrep function execute the approximative search with the Shift-Or method.

Parameter	Description
lpText	Specifies the text string to be explored (where to search for the pattern)
pGI	Pointer to an information block as built by a previous CompileAGrep call.
Returns

The return value is the number of matches encountered in the explored text string.

If there is no match, the return value is 0.

In case of error, the return value is negative.

When there is one or more matches, the AGREPINFO structure is filled with data describing the match(es).

If there are more than MAXTAG matches, the returned value is MAXTAG. This is caused by the size limitation of the TagStart[ ] and TagEnd[ ] fields.

Comments

Even though the structure of the AGREPINFO block is available, the programmer is advised not to try filling it with information without calling the CompileAGrep function.

If the number of matches is different from 0, it is possible to find the position of the first occurence in the pGI structure. The first matching character is pointed by pGI->TagStart[0] and the first non-matching character is pointed by pGI->TagEnd[0].

See Also

CompileAGrep


AGrepInit function
AGrepInit

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL AGrepInit(AGREPINFO FAR* pGI)

AGREPINFO FAR*  pGI;	/* pointer to search information block	*/

The AGrepInit function should be called before any use of the pGI parameter in any other function of the AGrep family. It is used to initialize internal data structures in this data structure.

Parameter	Description
pGI	Pointer to an information block as built by the CompileAGrep function.
Returns

The returned value is either TRUE in case of success, or FALSE in case of failure.

This function must be called at least once for each of the AGREPINFO structures which will be filled by the CompileAGrep function.

See Also

AGrepEmpty


AGrepEmpty function
AGrepEmpty

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL AGrepEmpty(AGREPINFO FAR* pGI)

AGREPINFO FAR*  pGI;	/* pointer to search information block	*/

The AGrepEmpty function is used to clear the contents of the AGREPINFO structure before releasing memory.

Parameter	Description
pGI	Pointer to an information block as built by the CompileAGrep function.
Returns

The returned value is either TRUE in case of success, or FALSE in case of failure.

This function must be called at least once for each of the AGREPINFO structures filled by the CompileAGrep function. If not, when releasing memory for the AGREPINFO block, its contents are not cleared (mainly pointers in the BLIST fields) and memory leak occurs. The consequence is then a slowdown of Windows while your application consumes more and more memory, and in the end, out-of-memory condition for your application or one of its neighbours.

While programming with the YGrep Search Engine, it must be remembered that internal structures for that dynamic Link Library are rather large and memory handling is an important part of any MS-Windows application.

See Also

AGrepInit


AGrepSubsBuild function
AGrepSubsBuild

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL AGrepSubsBuild(LPCSTR lpPattern, LPCSTR lpDest, int iSize, AGREPINFO FAR* pGI)

LPCSTR  lpPattern;	/* pattern to replace matched strings	*/
LPCSTR  lpDest;	/* destination buffer for building substitution string */
int  iSize;	/* size of the destination buffer	*/
AGREPINFO FAR*  pGI;	/* pointer to search information block	*/

The AGrepSubsBuild function builds the replacement string for the previous match by AGrep based on the pattern argument. It does not operate the replacement in the original string (read comments at the end of this reference page).

To get a full substitution, you should use AGrepSubstitute.

Parameter	Description
lpPattern	Specifies the replacement string to substitute for the previous match detected by AGrep.
lpDest	Specifies the buffer which will receive the substitution string built from the pattern and the matched string.
iSize	Size of the lpDest buffer.
pGI	Pointer to an information block as built by a previous CompileAGrep call and used by a previous AGrep call.
Returns

The returned value is one of the AGERR_* error codes. In case of normal operation (no error), the returned value is AGERR_NO_ERROR.

Comments

The pattern uses a specific syntax to describe regular expressions. It is described under the title of YGrep Search Engine substitution expressions.

Following are the possible returned values for AGrepSubsBuild:

Value	Meaning
AGERR_NO_PREVIOUS	There was no previous pattern searched, or AGrep was not called before, or AGrep was called but did not return success.
AGERR_ NO_PATTERN	There was no pattern provided for substitution.
AGERR_TOO_SHORT	The substitution is building a destination string which is too large for the lpDest buffer as sized by the iSize argument.
AGERR_STATE	Can occur when badly constructed AGREPINFO is forwarded as parameter to this function. Most usually, it comes from forgetting to call the previous functions, or from erroneous AGREPINFO structure.
Before calling this function, you must successively use the CompileAGrep (to initialize the pGI parameter) and AGrep (to perform the search operation preliminary to substituting a string to the match).

After calling AGrepSubsBuild, you are left with a "destination string" which contains the text to insert back into the original string. The insertion is not done by the YGrep Search Engine, because it could involve a large amount of memory management that the programmer/user could prefer doing by himself following the rules he need for his application. The YGrep Search Engine could not follow these rules.

For example, CompileAGrep is used on the pattern "horse" (for the sake of simplicity we have choosen straight text), AGrep is used on the text line "A horse! My kingdom for a horse!". Match is observed on the third character (beginning of the first "horse" word). Then, for substitution you can call AGrepSubsBuild with the pattern "large &". It will return an lpDest string containing "large horse" which you can use to substitute in the original text line (AGrepSubsBuild does not apply the actual  substitution). You can then call again AGrep before substituting again.

The necessity of providing a size limit appears in this example since it is difficult to predict the final size of the lpDest string (here it grows from the 7 characters pattern - "large &" - to the final 11 characters lpDest - "large horse"). The user must provide a buffer large enough for building it.

See Also

CompileAGrep, AGrep, AGrepSubstitute


AGrepSubstitute function
AGrepSubstitute

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL AGrepSubstitute(LPSTR lpText, LPSTR lpPattern, LPCSTR lpDest, int iSize, AGREPINFO FAR* pGI)

LPCSTR  lpText;	/* text previously search with AGrep	*/
LPCSTR  lpPattern;	/* pattern to replace matched strings	*/
LPCSTR  lpDest;	/* destination buffer for building substitution string */
int  iSize;	/* size of the destination buffer	*/
AGREPINFO FAR*  pGI;	/* pointer to search information block	*/

The AGrepSubstitute function substitutes the lpPattern in place of the matched string in the lpText used in the preceeding and successful search by AGrep.

Parameter	Description
lpText	Specifies the text string search with the previous call to Agrep. It will be used as the basis for the substitution of the matched portion detected by Agrep.
lpPattern	Specifies the replacement string to substitute for the previous match detected by AGrep.
lpDest	Specifies the buffer which will receive the result of the substitution process.
iSize	Size of the lpDest buffer.
pGI	Pointer to an information block as built by a previous CompileAGrep call and used by a previous AGrep call.
Returns

The returned value is one of the AGERR_* error codes. In case of normal operation (no error), the returned value is AGERR_NO_ERROR.

Comments

The pattern uses a specific syntax to describe regular expressions. It is described under the title of YGrep Search Engine substitution expressions.

Following are the possible returned values for AGrepSubstitute:

Value	Meaning
AGERR_NO_PREVIOUS	There was no previous pattern searched, or AGrep was not called before, or AGrep was called but did not return success.
AGERR_ NO_PATTERN	There was no pattern provided for substitution.
AGERR_TOO_SHORT	The substitution is building a destination string which is too large for the lpDest buffer as sized by the iSize argument.
AGERR_STATE	Can occur when badly constructed AGREPINFO is forwarded as parameter to this function. Most usually, it comes from forgetting to call the previous functions, or from erroneous AGREPINFO structure.
Before calling this function, you must successively use the CompileAGrep (to initialize the pGI parameter) and AGrep (to perform the search operation preliminary to substituting a string to the match).

For example, CompileAGrep is used on the pattern "horse" (for the sake of simplicity we have choosen straight text), AGrep is used on the text line "A horse! My kingdom for a horse!". Match is observed on the third character (beginning of the first "horse" word). Then, for substitution you can call AGrepSubstitute with the pattern "large &". It will return an lpDest string containing " A large horse! My kingdom for a horse! ".

Notice that only the firstmatch is substituted. It is the reponsibility of the programmer to repeat this process in order to cover all cases in a specific text. You can then call again AGrep before substituting again.

The necessity of providing a size limit appears in this example since it is difficult to predict the final size of the lpDest string (here it grows 6 characters). The user must provide a buffer large enough for building it.

See Also

CompileAGrep, AGrep


CompileRGrep function
CompileRGrep

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL CompileRGrep(LPCSTR lpText, BOOL bMatchCase, RGREPINFO FAR* pGI)

LPCSTR  lpPattern;	/* pattern string to look for	*/
BOOL  bMatchCase;	/* Match case in comparisons?	*/
RGREPINFO FAR*  pGI;	/* pointer to search information block	*/

The CompileRGrep function reprocesses the pattern in order to prepare regular expression search.

Parameter	Description
lpPattern	Specifies the text string describing the pattern to look for.
bMatchCase	Specifies whether the search operation should be case sensitive.
	Value	Meaning
	TRUE	Force letter case checking
	FALSE	Do not check letter casing
bMatchCase	Specifies whether the search operation should be case sensitive.
pGI	Pointer to an information block as will be used in a later to the RGrep function.
Returns

The returned value is one of the AGERR_* error codes. In case of normal operation (no error), the returned value is AGERR_NO_ERROR.

Comments

The pattern uses a specific syntax to describe regular expressions. It is described under the title of YGrep Search Engine Regular Expression.

Following are the possible returned values for CompileRGrep:

Value	Meaning
AGERR_ALLOC_MEM	Insufficient memory to hold data structures for internal operation.
AGERR_STATE	Reserved for future use.
AGERR_NO_PATTERN	There was no pattern provided. CompileRGrep tried to use a previously proposed pattern. But this was the first call to the function.
RGERR_MUNGED_AUTO	Munged automaton. Internal error. Should be sign of memory corruption either by an YGrep Search Engine bug or another undetected program.
RGERR_MISS_BRACKET	Missing closing bracket ']' in expression.
RGERR_EMPTY_ENCL	Empty closure. Do not provide an expression containing only [] (i.e. an empty closure).
RGERR_ILLEGAL_ENCL	Illegal closure. Some characters are not allowed in a closure: ^$<>
RGERR_TOO_MANY_PAR	Too many parenthesis pairs in the expression.
RGERR_NULL_IN_PAR	Null expression inside parenthesis.
RGERR_UNMATCHED	Unmatched parenthesis. There is at least one more closing parenthesis than opening ones.
RGERR_NULL_IN_CRO	Null expression inside < >.
RGERR_CYCLICAL_REF	A reference is done do itself.
RGERR_UNDETERM_REF	A reference is done to an unknown sub-expression.
RGERR_UMATCHED_PAR	Unmatched parenthesis. There is at least one less closing parenthesis than opening ones.
This function must be called at least once before calling RGrep.

See Also

RGrep


RGrep function
RGrep

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL RGrep(LPCSTR lpText, RGREPINFO FAR* pGI)

LPCSTR  lpText;	/* text string to explore	*/
RGREPINFO FAR*  pGI;	/* pointer to search information block	*/

The RGrep function execute the automaton-oriented search with regular expressions compatible with the Unix ed(1) editor.

Parameter	Description
lpText	Specifies the text string to be explored (where to search for the pattern)
pGI	Pointer to an information block as built by a previous CompileRGrep call.
Returns

The return value is the number of matches encountered in the explored text string.

If there is no match, the return value is 0.

In case of error, the return value is negative. The error code can be found in pGI (iErrorCode structure field).

If the number of matches is different from 0, it is possible to find the position of the first occurence in the pGI structure. The first matching character is pointed by pGI->TagStart[0] and the first non-matching character is pointed by pGI->TagEnd[0].

Because there can be no more than one match position stored in the pGI->TagStart[0] field, the returned value is never superior to 1 (only the first match is found, and additional calls to RGrep must be used to find the following ones).

Comments

Following are the possible error values for RGrep when the returned value is negative.

Value	Meaning
RGERR_MUNGED_AUTO	The pGI structure contents have been modified, or never initialized by CompileRGrep..
Even though the structure of the RGREPINFO block is available, the programmer is advised not to try filling it with information without calling the CompileRGrep function.

See Also

CompileRGrep


RGrepSubsBuild function
RGrepSubsBuild

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL RGrepSubsBuild(LPCSTR lpPattern, LPCSTR lpDest, int iSize, RGREPINFO FAR* pGI)

LPCSTR  lpPattern;	/* pattern to replace matched strings	*/
LPCSTR  lpDest;	/* destination buffer for building substitution string */
int  iSize;	/* size of the destination buffer	*/
RGREPINFO FAR*  pGI;	/* pointer to search information block	*/

The RGrepSubsBuild function builds the replacement string for the previous match by RGrep based on the pattern argument. It does not operate the replacement in the original string (read comments at the end of this reference page).

Parameter	Description
lpPattern	Specifies the replacement string to substitute for the previous match detected by RGrep.
lpDest	Specifies the buffer which will receive the substitution string built from the pattern and the matched string.
iSize	Size of the lpDest buffer.
pGI	Pointer to an information block as built by a previous CompileRGrep call and used by a previous RGrep call.
Returns

The returned value is one of the AGERR_* error codes. In case of normal operation (no error), the returned value is AGERR_NO_ERROR.

Comments

The pattern uses a specific syntax to describe regular expressions. It is described under the title of YGrep Search Engine substitution expressions.

Following are the possible returned values for RGrepSubsBuild:

Value	Meaning
AGERR_NO_PREVIOUS	There was no previous pattern searched, or AGrep was not called before, or AGrep was called but did not return success.
AGERR_ NO_PATTERN	There was no pattern provided for substitution.
AGERR_TOO_SHORT	The substitution is building a destination string which is too large for the lpDest buffer as sized by the iSize argument.
AGERR_STATE	Can occur when badly constructed AGREPINFO is forwarded as parameter to this function. Most usually, it comes from forgetting to call the previous functions, or from erroneous AGREPINFO structure.
Before calling this function, you must successively use the CompileRGrep (to initialize the pGI parameter) and RGrep (to perform the search operation preliminary to substituting a string to the match).

After calling RGrepSubsBuild, you are left with a "destination string" which contains the text to insert back into the original string. The insertion is not done by the YGrep Search Engine, because it could involve a large amount of memory management that the programmer/user could prefer doing by himself following the rules he need for his application. The YGrep Search Engine could not follow these rules.

For example, CompileRGrep is used on the pattern "horse" (for the sake of simplicity we have choosen straight text), RGrep is used on the text line "A horse! My kingdom for a horse!". Match is observed on the third character (beginning of the first "horse" word). Then, for substitution you can call RGrepSubsBuild with the pattern "large &". It will return an lpDest string containing "large horse" which you can use to substitute in the original text line (RGrepSubsBuild does not apply the actual  substitution). You can then call again RGrep before substituting again.

The necessity of providing a size limit appears in this example since it is difficult to predict the final size of the lpDest string (here it grows from the 7 characters pattern - "large &" - to the final 11 characters lpDest - "large horse"). The user must provide a buffer large enough for building it.

See Also

CompileRGrep, RGrep


RGrepSubstitute function
RGrepSubstitute

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL RGrepSubstitute(LPSTR lpText, LPSTR lpPattern, LPCSTR lpDest, int iSize, AGREPINFO FAR* pGI)

LPCSTR  lpText;	/* text previously search with RGrep	*/
LPCSTR  lpPattern;	/* pattern to replace matched strings	*/
LPCSTR  lpDest;	/* destination buffer for building substitution string */
int  iSize;	/* size of the destination buffer	*/
RGREPINFO FAR*  pGI;	/* pointer to search information block	*/

The RGrepSubstitute function substitutes the lpPattern in place of the matched string in the lpText used in the preceeding and successful search by RGrep.

Parameter	Description
lpText	Specifies the text string search with the previous call to Rgrep. It will be used as the basis for the substitution of the matched portion detected by Rgrep.
lpPattern	Specifies the replacement string to substitute for the previous match detected by RGrep.
lpDest	Specifies the buffer which will receive the result of the substitution process.
iSize	Size of the lpDest buffer.
pGI	Pointer to an information block as built by a previous CompileRGrep call and used by a previous RGrep call.
Returns

The returned value is one of the AGERR_* error codes. In case of normal operation (no error), the returned value is AGERR_NO_ERROR.

Comments

The pattern uses a specific syntax to describe regular expressions. It is described under the title of YGrep Search Engine substitution expressions.

Following are the possible returned values for RGrepSubstitute:

Value	Meaning
AGERR_NO_PREVIOUS	There was no previous pattern searched, or RGrep was not called before, or RGrep was called but did not return success.
AGERR_ NO_PATTERN	There was no pattern provided for substitution.
AGERR_TOO_SHORT	The substitution is building a destination string which is too large for the lpDest buffer as sized by the iSize argument.
AGERR_STATE	Can occur when badly constructed RGREPINFO is forwarded as parameter to this function. Most usually, it comes from forgetting to call the previous functions, or from erroneous RGREPINFO structure.
Before calling this function, you must successively use the CompileRGrep (to initialize the pGI parameter) and RGrep (to perform the search operation preliminary to substituting a string to the match).

For example, CompileRGrep is used on the pattern "horse" (for the sake of simplicity we have choosen straight text), RGrep is used on the text line "A horse! My kingdom for a horse!". Match is observed on the third character (beginning of the first "horse" word). Then, for substitution you can call RGrepSubstitute with the pattern "large &". It will return an lpDest string containing " A large horse! My kingdom for a horse! ".

Notice that only the firstmatch is substituted. It is the reponsibility of the programmer to repeat this process in order to cover all cases in a specific text. You can then call again RGrep before substituting again.

The necessity of providing a size limit appears in this example since it is difficult to predict the final size of the lpDest string (here it grows 6 characters). The user must provide a buffer large enough for building it.

See Also

CompileRGrep, RGrep


InitWordCharTable function
InitWordCharTable

#include	<windows.h>
#include	<ygrep.h>

void FAR PASCAL InitWordCharTable()

The InitWordCharTable function initializes the table containing the list of characters considered as word characters by the RGrep group of functions.

It takes no parameter.

Returns

No return value.

Comments

The initial characters considered as word characters are 0 to 9, A to Z, a to z and the underscore character( _ ). This list can be modified using the AddWordChar and RemoveWordChar functions. The mostly probable use of these modifications are to include accentuated characters for foreign language, or to remove the underscore characters which is not usually considered a text character out of the programming languages community.


AddWordChar function
AddWordChar

#include	<windows.h>
#include	<ygrep.h>

void FAR PASCAL AddWordChar(LPCSTR lpChars)

LPCSTR  lpChars;	/* text string containing the characters to add	*/

The AddWordChar function adds more characters to the list of word characters for the RGrep group of functions.

Parameter	Description
lpChars	Specifies all the characters to be added to the list of word characters
Returns

No return value

Comments

The characters in the parameter string can be in any order and can be in the full range of the extended (8-bit) ASCII character set (excluding the null character, of course).

See Also

InitWordCharTable, RemoveWordChar.


RemoveWordChar function
RemoveWordChar

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL RemoveWordChar(LPCSTR lpChars)

LPCSTR  lpSrc;	/* text string to explore	*/

The RemoveWordChar function adds more characters to the list of word characters for the RGrep group of functions.

Parameter	Description
lpChars	Specifies all the characters to be removed from the list of word characters
Returns

No return value.

Comments

The characters in the parameter string can be in any order and can be in the full range of the extended (8-bit) ASCII character set (excluding the null character, of course).

See Also

InitWordCharTable, AddWordChar


YGrepVersion function
YGrepVersion

#include	<windows.h>
#include	<ygrep.h>

WORD YGrepVersion()

The YGrepVersion function provides the version number of the DLL.

Parameter	Description
none
Returns

The return WORD value has the following format (when represented as an hexadecimal value):

Vrrr

Where V is the version number (major) and rrr is the release number (minor). For example, version 1.20d is coded as 0x1204.

This value may be used to determine the capabilities/compatiblity of an already loaded version of the YGREP Dynamic Link Library and to insure that it is able to answer to specific calls.

Comments

The application may never call this function. But it can be used to check at run time the availability of certain functions in the Dynamic Link Library.


SCompileAGrep function
SCompileAGrep

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL SCompileAGrep(LPCSTR lpText, UINT k, BOOL bMatchCase)

The SCompileAGrep function is the wrapper with only scalar parameters for the CompileAGrep function.

It has the same operation but using a single internal (not visible pGI parameter).


SAGrep function
SAGrep

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL SAGrep(LPCSTR lpText)

The SAGrep function is the wrapper with only scalar parameters for the AGrep function.

It has the same operation but using a single internal (not visible pGI parameter).


SAGrepInit function
SAGrepInit

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL SAGrepInit()

The SAGrepInit function is the wrapper with only scalar parameters for the AGrepInit function.

It has the same operation but using a single internal (not visible pGI parameter).


SAGrepEmpty function
SAGrepEmpty

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL SAGrepEmpty()

The SAGrepEmpty function is the wrapper with only scalar parameters for the AGrepEmpty function.

It has the same operation but using a single internal (not visible pGI parameter).


SAGrepSubsBuild function
SAGrepSubsBuild

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL SAGrepSubsBuild(LPCSTR lpPattern, LPCSTR lpDest, int iSize, AGREPINFO FAR* pGI)

The SAGrepSubsBuild function is the wrapper with only scalar parameters for the AGrepSubsBuild function.

It has the same operation but using a single internal (not visible pGI parameter).


SAGrepSubstitute function
SAGrepSubstitute

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL SAGrepSubstitute(LPCSTR lpText, LPCSTR lpPattern, LPCSTR lpDest, int iSize, AGREPINFO FAR* pGI)

The SAGrepSubstitute function is the wrapper with only scalar parameters for the AGrepSubstitute function.

It has the same operation but using a single internal (not visible pGI parameter).


SCompileRGrep function
SCompileRGrep

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL SCompileRGrep(LPCSTR lpText, BOOL bMatchCase)

The SCompileRGrep function is the wrapper with only scalar parameters for the CompileRGrep function.

It has the same operation but using a single internal (not visible pGI parameter).


SRGrep function
SRGrep

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL SRGrep(LPCSTR lpText)

The SRGrep function is the wrapper with only scalar parameters for the RGrep function.

It has the same operation but using a single internal (not visible pGI parameter).


SRGrepSubsBuild function
SRGrepSubsBuild

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL SRGrepSubsBuild(LPCSTR lpPattern, LPCSTR lpDest, int iSize)

The SRGrepSubsBuild function is the wrapper with only scalar parameters for the RGrepSubsBuild function.

It has the same operation but using a single internal (not visible pGI parameter).


SRGrepSubstitute function
SRGrepSubstitute

#include	<windows.h>
#include	<ygrep.h>

int FAR PASCAL SRGrepSubstitute(LPCSTR lpPattern, LPCSTR lpDest, int iSize)

The SRGrepSubstitute function is the wrapper with only scalar parameters for the RGrepSubstitute function.

It has the same operation but using a single internal (not visible pGI parameter).


Other packages of the Engine Series

The current package is part of a series of so-called Engines for power programmers and power users. They can be found in all good shareware libraries (Well! At least, they look good to me if they have my packages...).

The Engine Series include the following programmers tools:

YGrep Search Engine

BitList Engine

and an application:

ClusterView

The Engine Series and their documentation files and manuals are copyrighted (C) 1993-94-95 by Yves Roumazeilles.


ClusterView Application

The ClusterView application is an MS-Windows file viewer able to handle multiple files grouped in a structure named a cluster. It is an efficient way to look at groups of files which are too large to be stored in main memory.

The main advantages of this application are:

file viewer for files larger than the memory size AND the swap file size.

file viewer for file groups (named clusters).

search capabilities including approximative search (or search for a pattern with a number of errors) and regular expression search (compatible with Unix GREP search).

This application is a must when you handle large files under MS-Windows and cannot afford large amounts of memory and/or large swap files and/or the performance penalty imposed by most other file viewers.

The ClusterView application uses and demonstrates the capabilities of the AGrep Search Engine in a real-life context.


YGrep Search Engine

The YGrep Search Engine is a text search Dynamic Link Library (DLL)  to be used with any kind of MS-Windows application. It has two possibilities:

approximative search based on Baeza-Yates algorithm to find a pattern which is only partly known (also known as search with erroneous patterns). For example, you can search for "pattern" with 1 error (at most) and it will match "pattern", "pittern" and "Pattern" while stepping over "lantern" (2 errors).

search modelled on the Unix utility named GREP. It is particularly useful for complex searching with the help of its specific search "language" to describe the pattern you look for. For example, you can search for "^pattern" to look for "pattern" at the beginning of a line; or for "[pl]a[nt]tern" to look for either "pattern" or "lantern". An extensive description of the language can be found on any Unix system, or in the help file accompanying the YGrep Search Engine shareware edition on your preferred BBS or Internet site.

Both are particularly useful to improve greatly the search capability of an existing tool such as a text editor, a data base search engine, etc.

Additionnal functionalities allow to apply substitution after pattern recognition by the search functions.


BitList Engine

The BitList Engine is a DLL designed to handle lists of bits (and to a small extent, big numbers). It was built because of the limitations of the ANSI-C bit fields which cannot be larger than an "unsigned long".

The BitList Engine allows you to build very large bit lists and to handle them with a set of functions covering a large range of needs (this is continuously expanding):

constructors/copy-constructors/copy operators

logical operators (AND,OR,NOT,etc.)

arithmetic operations (ADD,SUB,etc.)

shift operations (left and right)

others...

This will be particularly useful to handle large sets (as belong to the programmer's bag of tools) and to work on encryption/compression code.


Author Address

Registration fees can be sent to, and the author can be reached at the following address (Email and duly paid registration fee is the preferred interface if you want a prompt answer):

Yves Roumazeilles

63 rue des Moines

75017 PARIS (FRANCE)

Phone: +33 1-42.28.74.51

Fax:     +33 1-34.30.50.28

CIS: 101233,1032

Email: 10233.1032@compuserve.com

You can also reach our web page at:

http://ourworld.compuserve.com/homepages/Yves_Roumazeilles

For comments, suggestions and bug reports, Email is also available at:

Yves_Roumazeilles @compuserve.com

Yves.Roumazeilles@sagem.fr

Roumazeilles@sagem.fr


Shareware description
What is Shareware?

"Shareware" is a way to distribute software while retaining the best of all worlds. People are invited to freely make copies of the software for evaluation purposes (it's cheap distribution). You are both legally and morally obliged to pay the registration fee if you start using the software after an initial 30 day evaluation period (the author gets money from its work). This respects the rights of the author while avoiding burdenning the users with high costs of traditionnal distribution channels.

Shareware is not free, Shareware is not public domain, but Shareware is not expensive (I actually cannot live from it...)

Remember! The fee is small because the distribution is simple, but the user (YOU) must honestly pay the registration fee. This will allow future releases to hit the market soon with many enhancements.