Merge pull request #9 from daniel-tran/0.6.0

Version 0.6.0

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change Log
 
+## 0.6.0
+- Added text searching functionality into Base Extractor
+- Added a dedicated area for experimental functionality and helper scripts
+  - With enough refinement, some of these might become new features in future releases
+- Added translation support for: NRSVUE
+- Removed translation support for: CJB
+
 ## 0.5.0
 - Added CSV Extractor and CSV Downloader
 - Added csv_file_interface module to assist with CSV file access

CONTRIBUTING.md

@@ -63,7 +63,7 @@ Some parts of the library have a repeatable process for adding on new features a
 ## Supporting a new translations
 - Add a new translation code to the appropriate method under `meaningless\utilities\common.py`.
 - Add a new test case to `system_tests_bible_translations.py` for the new translation. This is used to validate end-to-end correctness.
-  - Add all the necessary test data files under `test\static\system_tests_bible_translations` in a new folder named according to the new translation.
+  - Add all the necessary test data files under `test\static\system_tests_bible_translations` in a new folder named according to the new translation. You can use the helper script under `experimental\system_test_helper.py` to make this process easier.
 - Make appropriate modifications to the Web Extractor to account for translation-specific components, such as double spaces and in-line translation notes.
   - Add unit tests for the Web Extractor to test these specific changes.
   - Run all the Web Extractor unit tests to ensure stable behaviour with said changes.
@@ -73,7 +73,7 @@ Some parts of the library have a repeatable process for adding on new features a
 ## Adding a new extractor or downloader
 - Add a new file interface under `meaningless\utilities` with the following two standalone methods:
   - `def write(data_file, document)`
-    - `data_file` is a string corresponnding to the file path to write to.
+    - `data_file` is a string corresponding to the file path to write to.
     - `document` is a dictionary with the structure shown below.
     - Returns 1 when successful.
   - `def read(data_file)`

README.md

@@ -10,6 +10,7 @@ Features include:
   - YAML/JSON/XML/CSV files for persistent storage of Bible passages or as input for other applications and scripts.
 - Handling of edge case passages, such as those with tabular data and omitted passages in certain translations.
 - Flags to enable particular content modifications, such as ignoring passage numbers.
+- Filtering on Bible passages from a local file based on a given text input or regular expression.
 
 **Now accepting feature requests!** If you want to see a certain feature included, please create an issue describing all the necessary details.
 
@@ -38,7 +39,6 @@ You can view the API documentation as static HTML documents from `docs\index.htm
 - ASV
 - AKJV
 - BRG
-- CJB
 - EHV
 - ESV
 - ESVUK
@@ -60,6 +60,7 @@ You can view the API documentation as static HTML documents from `docs\index.htm
 - NLV
 - NOG
 - NRSV
+- NRSVUE
 - WEB
 - YLT
 
@@ -386,6 +387,56 @@ Ecclesiastes,1,2,"² “Meaningless! Meaningless!”
     Everything is meaningless.”",English (EN),NIV
 ```
 
+## Text searching within files
+All file-based extractors support passage filtering by search text or by regular expression.
+
+The section below is a simple example that prints passages containing "meaningless" from Ecclesiastes 1:
+```python
+from meaningless import YAMLDownloader, YAMLExtractor
+
+if __name__ == '__main__':
+    downloader = YAMLDownloader()
+    downloader.download_chapter('Ecclesiastes', 1)
+
+    bible = YAMLExtractor()
+    print(bible.find_text_in_chapter('meaningless', 'Ecclesiastes', 1))
+```
+
+Output:
+```
+² “Meaningless! Meaningless!”
+    says the Teacher.
+“Utterly meaningless!
+    Everything is meaningless.”
+¹⁴ I have seen all the things that are done under the sun; all of them are meaningless, a chasing after the wind.
+```
+
+The section below is another simple example that prints passages containing "meaningless" or "wisdom" from Ecclesiastes 1:
+```python
+from meaningless import YAMLDownloader, YAMLExtractor
+
+if __name__ == '__main__':
+    downloader = YAMLDownloader()
+    downloader.download_chapter('Ecclesiastes', 1)
+
+    bible = YAMLExtractor()
+    print(bible.find_text_in_chapter('meaningless|wisdom', 'Ecclesiastes', 1, is_regex=True))
+```
+
+Output:
+```
+² “Meaningless! Meaningless!”
+    says the Teacher.
+“Utterly meaningless!
+    Everything is meaningless.”
+¹³ I applied my mind to study and to explore by wisdom all that is done under the heavens. What a heavy burden God has laid on mankind!
+¹⁴ I have seen all the things that are done under the sun; all of them are meaningless, a chasing after the wind.
+¹⁶ I said to myself, “Look, I have increased in wisdom more than anyone who has ruled over Jerusalem before me; I have experienced much of wisdom and knowledge.”
+¹⁷ Then I applied myself to the understanding of wisdom, and also of madness and folly, but I learned that this, too, is a chasing after the wind.
+¹⁸ For with much wisdom comes much sorrow;
+    the more knowledge, the more grief.
+```
+
 # Q&A
 
 ## How to report potential bugs and other feedback?

VERSION.txt

@@ -1 +1 @@
-0.5.0
+0.6.0

docs/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '0.5.0',
+    VERSION: '0.6.0',
     LANGUAGE: 'None',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/genindex.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Index &#8212; Meaningless 0.5.0 documentation</title>
+    <title>Index &#8212; Meaningless 0.6.0 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
@@ -37,6 +37,7 @@ <h1 id="index">Index</h1>
  <a href="#B"><strong>B</strong></a>
  | <a href="#C"><strong>C</strong></a>
  | <a href="#D"><strong>D</strong></a>
+ | <a href="#F"><strong>F</strong></a>
  | <a href="#G"><strong>G</strong></a>
  | <a href="#I"><strong>I</strong></a>
  | <a href="#J"><strong>J</strong></a>
@@ -138,6 +139,74 @@ <h2 id="D">D</h2>
   </ul></td>
 </tr></table>
 
+<h2 id="F">F</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="meaningless.html#meaningless.bible_csv_extractor.CSVExtractor.find_text_in_book">find_text_in_book() (meaningless.bible_csv_extractor.CSVExtractor method)</a>
+
+      <ul>
+        <li><a href="meaningless.html#meaningless.bible_json_extractor.JSONExtractor.find_text_in_book">(meaningless.bible_json_extractor.JSONExtractor method)</a>
+</li>
+        <li><a href="meaningless.html#meaningless.bible_xml_extractor.XMLExtractor.find_text_in_book">(meaningless.bible_xml_extractor.XMLExtractor method)</a>
+</li>
+        <li><a href="meaningless.html#meaningless.bible_yaml_extractor.YAMLExtractor.find_text_in_book">(meaningless.bible_yaml_extractor.YAMLExtractor method)</a>
+</li>
+      </ul></li>
+      <li><a href="meaningless.html#meaningless.bible_csv_extractor.CSVExtractor.find_text_in_chapter">find_text_in_chapter() (meaningless.bible_csv_extractor.CSVExtractor method)</a>
+
+      <ul>
+        <li><a href="meaningless.html#meaningless.bible_json_extractor.JSONExtractor.find_text_in_chapter">(meaningless.bible_json_extractor.JSONExtractor method)</a>
+</li>
+        <li><a href="meaningless.html#meaningless.bible_xml_extractor.XMLExtractor.find_text_in_chapter">(meaningless.bible_xml_extractor.XMLExtractor method)</a>
+</li>
+        <li><a href="meaningless.html#meaningless.bible_yaml_extractor.YAMLExtractor.find_text_in_chapter">(meaningless.bible_yaml_extractor.YAMLExtractor method)</a>
+</li>
+      </ul></li>
+      <li><a href="meaningless.html#meaningless.bible_csv_extractor.CSVExtractor.find_text_in_chapters">find_text_in_chapters() (meaningless.bible_csv_extractor.CSVExtractor method)</a>
+
+      <ul>
+        <li><a href="meaningless.html#meaningless.bible_json_extractor.JSONExtractor.find_text_in_chapters">(meaningless.bible_json_extractor.JSONExtractor method)</a>
+</li>
+        <li><a href="meaningless.html#meaningless.bible_xml_extractor.XMLExtractor.find_text_in_chapters">(meaningless.bible_xml_extractor.XMLExtractor method)</a>
+</li>
+        <li><a href="meaningless.html#meaningless.bible_yaml_extractor.YAMLExtractor.find_text_in_chapters">(meaningless.bible_yaml_extractor.YAMLExtractor method)</a>
+</li>
+      </ul></li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="meaningless.html#meaningless.bible_csv_extractor.CSVExtractor.find_text_in_passage">find_text_in_passage() (meaningless.bible_csv_extractor.CSVExtractor method)</a>
+
+      <ul>
+        <li><a href="meaningless.html#meaningless.bible_json_extractor.JSONExtractor.find_text_in_passage">(meaningless.bible_json_extractor.JSONExtractor method)</a>
+</li>
+        <li><a href="meaningless.html#meaningless.bible_xml_extractor.XMLExtractor.find_text_in_passage">(meaningless.bible_xml_extractor.XMLExtractor method)</a>
+</li>
+        <li><a href="meaningless.html#meaningless.bible_yaml_extractor.YAMLExtractor.find_text_in_passage">(meaningless.bible_yaml_extractor.YAMLExtractor method)</a>
+</li>
+      </ul></li>
+      <li><a href="meaningless.html#meaningless.bible_csv_extractor.CSVExtractor.find_text_in_passage_range">find_text_in_passage_range() (meaningless.bible_csv_extractor.CSVExtractor method)</a>
+
+      <ul>
+        <li><a href="meaningless.html#meaningless.bible_json_extractor.JSONExtractor.find_text_in_passage_range">(meaningless.bible_json_extractor.JSONExtractor method)</a>
+</li>
+        <li><a href="meaningless.html#meaningless.bible_xml_extractor.XMLExtractor.find_text_in_passage_range">(meaningless.bible_xml_extractor.XMLExtractor method)</a>
+</li>
+        <li><a href="meaningless.html#meaningless.bible_yaml_extractor.YAMLExtractor.find_text_in_passage_range">(meaningless.bible_yaml_extractor.YAMLExtractor method)</a>
+</li>
+      </ul></li>
+      <li><a href="meaningless.html#meaningless.bible_csv_extractor.CSVExtractor.find_text_in_passages">find_text_in_passages() (meaningless.bible_csv_extractor.CSVExtractor method)</a>
+
+      <ul>
+        <li><a href="meaningless.html#meaningless.bible_json_extractor.JSONExtractor.find_text_in_passages">(meaningless.bible_json_extractor.JSONExtractor method)</a>
+</li>
+        <li><a href="meaningless.html#meaningless.bible_xml_extractor.XMLExtractor.find_text_in_passages">(meaningless.bible_xml_extractor.XMLExtractor method)</a>
+</li>
+        <li><a href="meaningless.html#meaningless.bible_yaml_extractor.YAMLExtractor.find_text_in_passages">(meaningless.bible_yaml_extractor.YAMLExtractor method)</a>
+</li>
+      </ul></li>
+  </ul></td>
+</tr></table>
+
 <h2 id="G">G</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>

docs/index.html

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
 
-    <title>Meaningless - API Documentation &#8212; Meaningless 0.5.0 documentation</title>
+    <title>Meaningless - API Documentation &#8212; Meaningless 0.6.0 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>