Read Me

Namelur version 0.1

Random name generator library with rule files. Fast, lightweight and easy. Can generate rule files from custom text, you can easily use it into your application and use one of the attached rule files for rpg/fantasy/star wars/etc. name generation.

Licensed under GPL

1. API documentation
Read the comments on the 'namelur.h' header file.

2. Features

    * very small memory usage and very fast generation algorithm
    * rule files (called NAR rule file) for scripting the generation of names
    * auto-generation of NAR rule files basing on words contained in any file
    * powerful command line tool (rulname) to create NAR files



3. Rulname command line tool
I have written the rulname command line tool to strip text from any file and to generate the proper NAR rule file. It can also be used to generate random names basing on a NAR rule file.

rulname [-h] [-o] filewithtext [destination.nar]
rulname [-h] [-o]  [-nnames] [-imins] [-amaxs] [-sseed] [-t]

-h                 Shows this syntax explanation page
-o                 Suppress non-data output
filewithtext       Input text file. All the valid syllables will be read and
                   used to generate a NAR rule file
destination.nar    Destination NAR file. If not specified NAR file output will
                   be sent to stdout (unless maxnames is specified)
-rnarfile          Source NAR file to be read for random name generation (not
                   necessary if 'filewithtext' was specified)
-nnames            Output 'names' number of random names to stdout
-imins -amaxs      Minimum/maximum number of syllables
-sseed             Specify a seed number to feed the internal random generator
                   If not specified the current time will be used as seed
-t                 Separate each name through a tab instead of a newline

Note: rulname has 2 behaviours:

    * when you specify a source file, it will produce the NAR file
    * when you specify a NAR file (or a source file + maxnames) random names will be generated



4. Rule files (*.NAR)
Each rule file contains plain ASCII text, lines that cannot be interpreted are skipped. Comments should be entered using #

# Example of comment
v12 a 6 e 7 i 7 o7 u 4
c3 b 7 c 7 d 7 f 7 g 7 h 7 

The first part of each valid line must contain 'v' or 'c' (vowel or consonant) followed by the number of repeat times (e.g. the density).
Must follow pairs of a string and a rule code. Each string cannot be longer than 3 characters, following are the rule codes for the consonant/vowel:

  1     can be at end of word (EOW)
  2     can be at beginning of word (BOW)
  4     can be in middle of word (MOW)

Since the rule code works as a binary encoding (middle) (beginning) (end), we also have (as combination of the previous codes):

  5     can be in middle or at ending of word (MEW)
  6     can be at beginning or ending (BEW)
  7     can be anywhere in word (AIW)

No particular error checking is performed, so you should void to:

    * use wrong syntax
    * use more than 3 characters per consonant/vowel
    * use a bad rule code, since only the lower 8 bits are considered
    * miss a possible position (e.g. be sure that there always can be a beginning, a middle and an ending)



In both lists, duplicates increase the likelihood of the occurence.

To have "no vowel at the end", use the special sequence:

v1 ]

You can specify more than 1 empty vowels anyway, like in 'v3 ]'

5. Working scheme of rulname (from text to NAR files)
When you use rulname or the namelur lib itself to parse a file, it will:

    * isolate a word
    * split it into syllables
    * save each syllable into the array without making duplicates but using a reference count and the relative position in the word
    * iterate till there are more words

This will let you produce random names of the same style of the source text. I suggest you to use a very large text file as basis, convert it to a NAR file and use that.

6. Using Namelur in your application
You'll need 'namelur.c' 'nraformat.c' and 'namelur.h' plus my common includes 'cppcompat.h' and the RWops library. If you run under win32 you'll also need the custom vsscanf implentation (provviden).

Sorry but i have not used the standard C libraries for that, I always use RWops because it allows me to easily handles all types of stream with automatic caching. A version not bound to RWops is planned.

7. Disclaimer
I guess there are bugs. A lot of them. The worst thing that can happen is a bad crash, anyway read the license for the real disclaimer notice.

8. History
The idea was given by David A. Wheeler's Totro, a javascript name generator. First I mocked up a C conversion, then I added more features coming up with the current Namelur.
I let it run to choose a good name for itself and after 3-4 runs I finally got a nice name, Namelur!

9. Contact
I would be happy to answer your feedback on the project Forum.

Please help me debugging!
Also, I have not put a great effort on porting and some minor changes are needed since the used RWops library is already portable.

10. Subversion control (SVN)
The online Subversion source code repository is available at:

svn.sourceforge.net/viewcvs.cgi/namelur/


If you have a subversion client you can explore the the repository through:

svn://svn.sourceforge.net/viewcvs.cgi/telbless/