kwebble/Durcruq

Durcruq 1.0.1 (development version)

Open source software to generate semi-random texts from building blocks you
provide.

Copyright © 2014 Rob Schlüter

Licensed under the Apache License, Version 2.0. For details see the LICENSE
file.

The source code of this project is hosted on GitHub:
https://github.com/kwebble/Durcruq

You can contact me through the contact form on my website:
http://kwebble.com/about


Status
------

Initial release.


Description
===========

The software can generate texts based on structured input text that defines the 
possible values for parts of the text.  
  
It was created to have more realistic texts for demo versions of websites and 
mobile applications then the often used Lorem Ipsum text. But you can use it to 
generate all kinds of texts, like test data, product names or project titles.

There are versions for:

* Java
* JavaScript, including a jQuery plugin  


Input text syntax
-----------------

The text is generated from input text you supply. This text must be made up of
1 or more lines with selectable text parts. When a text is requested it is 
generated from one of these lines. 

Selectable text parts are defined by surrounding text with square brackets:
[the text].
Inside a part, possible values are separated with a pipe (|) character. An
example: 

    This is [a line of|some] text.

This defines a text with 1 selectable part, with the values "a line of" and
"some". Form this input these 2 different lines can be generated:

* This is a line of text.
* This is some text.

If a selectable part contains only 1 value, that part is considered optional 
and its text will be included or left out. Example:

    This text has a [small] optional part.
    
can produce:
* This text has a optional part.
* This text has a small optional part.

To add an optional value as one of the allowed values either put a separator at
the beginning or end of the selectable part. That creates an empty value to 
choose from. Example:

    This text has a [small|nice|] optional part.</code>
    
can produce:
* This text has a small optional part.
* This text has a nice optional part.
* This text has a optional part.

Selectable parts can be nested:

    This is [a [single|short] line of|some] text."

can produce:
* This is a single line of text.
* This is a short line of text.
* This is some text.

With each selectable text part the number of unique texts that can be generated 
increases. This input:

    This [simple|free|Java] [text generator|software]
    [is useful|helps|makes it possible] to [create|generate] [demo|sample]
    text for a [website|mobile app].

can produce 3 x 2 x 3 x 2 x 2 x 2 = 144 different texts!


Building from source code
-------------------------

The source code is structured as a Maven 3 project with a separate module for 
every supported programming language.

To perform a build, access to PhantomJS (http://phantomjs.org/) is required to 
execute the JavaScript unit tests. Define the path to the PhantomJS program in 
an environment variable called PHANTOMJS_EXECUTABLE.

Build the project with Maven using the command:

    mvn package  

This produces a folder called "target" for every module, containing the 
software.

To create a set of web pages with project documentation use the command:

    mvn site site:stage
    
The web pages are stored in the folder target/staging.
  

Usage in Java
=============

If you use Maven as build tool you can include Durcruq with this Maven
dependency:

    <dependency>
        <groupId>com.kwebble</groupId>
	<artifactId>durcruq</artifactId>
	<version>1.0.1</version>
    </dependency>

If you perform your own build from source code it will produce the JAR file
durcruq-java-1.0.1.jar in the target folder of the java module.

Include this JAR file in your software to use the text generator.

The build also produces archives with JavaDoc and source code:
- durcruq-java-1.0.1-javadoc.jar
- durcruq-java-1.0.1-sources.jar



Examples:
--------

To generate text from a collection of lines first create a Randomizer object 
that uses your input lines: 

    String[] input = new String[] {
        "[Error|Warning]: file access [not allowed|prohibited].",
        "Call the [help desk|[software ]developer] for [support|advice]."
    }

    Randomizer randomizer = new Randomizer(input);
    
To generate a single text:

    String text = randomizer.getText();
    
To generate 3 texts:

    List<String> texts = randomizer.getTexts(3);
    
The input text can also be provided by a InputStream, for example based on a
file:

    Randomizer randomizer = new Randomizer(new FileInputStream("lines.txt"));


Usage in JavaScript
===================

Building the source code will produce the minified JavaScript file 
durcruq-1.0.1.min.js in the target folder of the javascript module.

This script contains both the plain JavaScript function and a jQuery plugin. 

Include the file in the web page to use the text generator. To use the jQuery
plugin make sure the jQuery library is loaded before this script.


Plain JavaScript
----------------

Call the kwebble.TextRandomizer.getText() or kwebble.TextRandomizer.getTexts() 
function to generate text:

    var input = [
        'Click [icon|link|here] for your free [upgrade|support call].',
        'Fill in your [[main] email|home|work] address.'
    ];
    
    // Generate 1 text.
    var text = kwebble.TextRandomizer.getText(input);
	
    // Generate multiple (5) texts.
    var texts = kwebble.TextRandomizer.getTexts(input, 5);


jQuery
------

The durcruq-1.0.1.min.js file contains a jQuery plugin to generate text for
elements selected by jQuery. The plugin syntax is:

    .randomizeText([text], [count])

It replaces each element in the set of matched elements with a generated text.
    
text = the input text to generate the text from. If not supplied the text of the 
contents of the matched element is used.     

count = the number of texts to generate. If not supplied 1 text is generated.

The function returns the selected set of elements so it can be used to chain
additional jQuery function calls.


Example: replace the current text with a generated version based on the 
contents of the matched element. 

    <div id="text">
        <p>[The first|A] paragraph of text</p>
        <p>The [second|next] paragraph of text</p>
    </div>
    
    $('#text').randomizeText();


Example: replace the current text with 4 generated versions based on the 
contents of the matched element.

    <div id="text">
      <p>New [text generator|software] now available for [free|download].</p>
    </div>

    $('#text').randomizeText(4);

Since the div is selected the input text includes the opening and closing 
paragraph tags <p> and </p>. These are also present in the generated text, so 
the call will result in 4 paragraphs. 

   
Example: replace the current text with a generated text based on the supplied text.

    <div id="text">just a placeholder</div>

    $('#text').randomizeText('This is [a [single|short] line of|some] text.');

Here the supplied input text is used, not the contents of the selected HTML
element.  

    
Example: fill the element with 2 generated versions based on the supplied text.

    <div id="text"></div>

    $('#text').randomizeText('<p>Welcome to the [[rocket] launch|game].</p>', 2);


Example: fill the element with generated text based on one of the lines of the
supplied text.

    <div id="text"></div>

    $('#text').randomizeText([
        '<p>Welcome to the [[rocket] launch|game].</p>',
        '<p>Enjoy our annual [festival|celebration].</p>',
    ]);