CSKit is a citation parsing and retrieval toolkit for various Christian Science textual resources. It features a pluggable architecture, meaning all the textual data is stored in separate gems.
- King James Bible (cskit-biblekjv-rb)
- Science and Health with Key to the Scriptures (cskit-shkts-rb)
- Christian Science Hymnal (cskit-hymnal-rb)
Clone all repositories with this handy one-liner:
\curl -sSL http://bit.ly/1dyPu88 | bash -s
gem install cskit
, gem install cskit-shkts
, etc
or, with bundler:
gem 'cskit-rb', '~> 1.0.0'
gem 'cskit-shkts-rb', '~> 1.0.0'
# base CSKit library
require 'cskit'
# will make data available from cskit-shkts-rb
require 'cskit/science_health'
Requiring one of the textual resource gems (eg. require 'cskit/science_health'
) will make the resource available as a Volume
. Volume
s provide access to a single textual resource and expose, among other things, a citation parser and a text reader. Use each Volume
's parse_citation
and readings_for
methods to parse citations and retrieve text. You can learn more about these specific components below.
You can ask CSKit which textual resources are currently available via the available_volumes
method:
require 'cskit/science_health'
require 'cskit/bible/kjv'
CSKit.available_volumes # { :science_health => ..., :bible_kjv => ... }
CSKit.volume_available?(:science_health) # true
CSKit.volume_available?(:blarg) # false
Get volume objects directly by using the get_volume
method. Note that CSKit can find volumes by their type as well as by their name. These two statements are equivalent because on failing to find :bible
by name, CSKit will fallback to the last registered volume of the type "bible".
CSKit.get_volume(:bible_kjv)
CSKit.get_volume(:bible)
CSKit uses vocabulary that helps consistently describe the objects in the system. Here are a few definitions that may be helpful to you as you spelunk this documentation and the source code:
- Volume: A textual resource. This should probably have been named "book", but "book of the bible" introduces ambiguity, so "volume" it is.
- Citation: References text in a volume. Parsers generate citation objects, and citation objects are passed to readers.
- Parser: Converts a citation string into a citation object so it can be used to retrieve text.
- Reader: An interface for retrieving text from a volume.
- Lesson: A collection of citations divided into sections. Each section contains a number of citations and their corresponding volumes. Analogous to the weekly Christian Science Bible Lesson.
- Section: A group of citations, possibly refrencing multiple volumes.
- Formatter: Logic for rendering readings.
- Reading: Text for a single citation. Made up of multiple texts.
- Text: A single unit of text, eg. line, verse, etc.
CSKit features a Lesson
class that is capable of reading in a JSON file and assembling text from a series of volumes for a group of citations (i.e. the weekly Bible Lesson):
include CSKit::Lesson
lesson = Lesson.from_file("/path/to/love.json")
You can iterate over the readings in each section using the each_reading
, each_formatted_reading
, and each_formatted_section
methods. Here are examples for each:
each_reading
iterates over each reading in each section for the given volumes. Formatting the text in each reading is up to you - this function returns the raw text only.
lesson.each_reading(:bible, :science_health) do |section, citation, volume, readings|
if volume == :bible
readings.each do |reading|
puts reading.texts.join(" ")
end
end
end
each_formatted_reading
iterates over each section, handing you the formatted text for each group of readings. More on formatters later.
include CSKit::Formatters::ScienceHealth
include CSKit::Formatters::Bible
formatters = {
:science_health => ScienceHealthPlainTextFormatter.new
:bible => BiblePlainTextFormatter.new
}
lesson.each_formatted_reading(formatters) do |section, citation, volume, text|
if volume == :bible
puts "Bible: #{text}"
end
end
each_formatted_section
is similar to each_formatted_reading
but hands you a hash of formatted reading groups by volume instead of yielding each reading group one at a time.
lesson.each_formatted_section(formatters) do |section, text_by_volume|
puts text_by_volume[:bible]
end
Here's an example JSON file for a lesson. Note that each volume name (eg. "bible", "science_health") must match an available volume (see above).
[
{
"section": "1",
"readings": {
"bible": [
"Gen. 12:1-3 the (to :)",
"Gen. 17:1, 2, 5",
"Gen. 22:17 in (to 1st ;), 18",
"Ps. 91:14"
],
"science_health": [
"275:12-17",
"579:10-14",
"507:6-7",
"140:8-12",
"264:15"
]
}
},
{ ... }
]
CSKit contains a number of parsers that can transform a citation string into a citation object. For example, the BibleParser
can read and interpret "Gen. 12:1-3 the (to :)" like so:
include CSKit::Parsers
parser = BibleParser.new
citation = parser.parse("Gen. 12:1-3 the (to :)").to_object
citation.book # "Gen."
citation.chapter_list # [#<Chapter .. >, #<Chapter .. >, ...]
citation.chapter_list.first.tap do |chapter|
chapter.chapter_number # 12
chapter.verse_list # [#<Verse ..>, ...]
chapter.verse_list.first.tap do |verse|
verse.start # 1
verse.finish # 3
verse.starter.fragment # "and in"
verse.terminator.fragment # ":"
verse.terminator.cardinality # 1
end
end
In addition, each volume provides a thin wrapper around the appropriate parser object, so you don't have to create one manually:
volume = CSKit.get_volume(:bible)
volume.parse_citation("Gen. 12:1-3 the (to :)") # returns a citation object
Once you have a citation object, you'll likely want to fetch text - the responsibility of a reader. Readers take in citations and return an array of Reading
objects:
include CSKit::Readers
reader = BibleReader.new(volume)
reader.get_book("Genesis") # #<Book .. >
reader.get_chapter(12, "Genesis"), # #<Chapter .. >
reader.readings_for(citation) # [#<Reading .. >, ... ]
In addition, each volume provides a thin wrapper around the appropriate reader object, so you don't have to create one manually:
volume.readings_for(citation) # [#<Reading .. >, ... ]
Now that you have text in the form of Reading
objects, you might want to format it for display - the responsibility of a formatter. Currently, CSKit contains two formatters, one for the Bible and another for Science and Health. Both of these format Reading
objects as plain text. If you'd like to apply a different style of formatting (eg. HTML), you'll need to create your own class.
Here's a formatting example for the Bible citation we've been using:
include CSKit::Formatters::Bible
readings = reader.readings_for(citation)
# these options are actually the defaults, shown here for demonstration purposes
formatter = BiblePlainTextFormatter.new(
:include_verse_number => true,
:separator => " "
)
formatter.format_readings(readings)
The formatted output (carriage returns added manually for Github display reasons):
1 ...the LORD had said unto Abram, Get thee out of thy country, and from thy kindred,
and from thy father's house, unto a land that I will shew thee: 2 And I will make of thee
a great nation, and I will bless thee, and make thy name great; and thou shalt be a
blessing: 3 And I will bless them that bless thee, and curse him that curseth thee:
For Science and Health, use the ScienceHealthPlainTextFormatter
class.
CSKit needs to parse JSON, so it depends on the json gem.
bundle exec rake
will run the test suite, although at the current time there are no tests :(
- Cameron C. Dutro: http://github.com/camertron
- Project Gutenberg: http://gutenberg.org/
Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0