README.adoc
Well Read Faker
===============
:homepage: https://github.com/skalee/well_read_faker
ifdef::env-github[]
image:https://img.shields.io/gem/v/well_read_faker[
Version, link="https://rubygems.org/gems/well_read_faker"]
image:https://img.shields.io/travis/com/skalee/well_read_faker/master[
Build Status, link="https://travis-ci.com/skalee/well_read_faker/branches"]
image:https://img.shields.io/codeclimate/maintainability/skalee/well_read_faker[
Code Climate, link="https://codeclimate.com/github/skalee/well_read_faker"]
image:http://img.shields.io/coveralls/skalee/well_read_faker[
Test Coverage, link="https://coveralls.io/r/skalee/well_read_faker"]
endif::env-github[]
:toc:
== Basic usage
Call +WellReadFaker.paragraph+ to get a random paragraph. For example,
following piece of code:
[source,ruby]
--------------------------------------------------------------------------------
puts WellReadFaker.paragraph
--------------------------------------------------------------------------------
Could print (without newlines):
--------------------------------------------------------------------------------
Thus they prayed, but not as yet would Jove grant them their prayer.
Then Priam, descendant of Dardanus, spoke, saying, "Hear me, Trojans
and Achaeans, I will now go back to the wind-beaten city of Ilius: I
dare not with my own eyes witness this fight between my son and
Menelaus, for Jove and the other immortals alone know which shall fall."
--------------------------------------------------------------------------------
== Custom sources
Well Read Faker comes with "Iliad" bundled as a default source. However,
custom sources can be used:
[source,ruby]
--------------------------------------------------------------------------------
WellReadFaker.add_source :book_in_my_language, "path/to/book", {}
WellReadFaker[:book_in_my_language].paragraph
WellReadFaker.default_source = :book_in_my_language
WellReadFaker.paragraph
WellReadFaker[:iliad].paragraph # Iliad can be still accessed
--------------------------------------------------------------------------------
The second argument passed to +WellReadFaker::add_source+ can be a string
containing a file path, or any object which responds to +#read+, like +File+
instance.
The third argument is optional but can be used to supply additional options,
for example to skip book descriptor or legal notes. See
+lib/well_read_faker/load_bundled_sources.rb+ for examples.
In the source text, paragraphs must be separated with blank lines.
== Note about randomness quality
For given text source, the paragraphs are returned in a random order, but will
not be repeated (in the sense of +String#==+ equality) until all unique
paragraphs from that text are returned exactly once. After that, they are
returned once again in the same order.
Therefore it is guaranteed that if given source text contains +n+ unique
paragraphs, then +n+ subsequent calls of +#paragraph+ method will return
unique values.
For your information, The Iliad contains over 1000 unique paragraphs.
== License
The gem is available as open source under the terms of the
http://opensource.org/licenses/MIT[MIT License].
The gem includes "Iliad", a classical masterpiece by Homer, translated to
English by Samuel Butler. A work is in
https://wiki.creativecommons.org/wiki/Public_domain[public domain] in USA and
in almost whole world (if not whole world) as the translator has died over
100 years ago (not to mention the original author). It has been downloaded from
Project Gutenberg, more details about the work can be found
http://www.gutenberg.org/ebooks/2199[there].