structured_log 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c79556fbe921de0e1c558d92fb818e2092908840
+  data.tar.gz: ba191522d9991ee4760ffa4554a0b653b040a97d
+SHA512:
+  metadata.gz: cd84786ce35b895802ca4ba41104ee01cbcb951e67cd5ac1a0bef6a935b12daba757f7f698975cf56fe6633e5d5e03f5fb2e41e85e57d2d24a6019a747f0cc15
+  data.tar.gz: 4783e18a64c266c1fa0587e18da3e53a0b7fb6c96fee0d2bec23ac1764adea28f210e7ffce310addfb138fde6c59d6cca599642c75d9200a67d55a25a1134c55

data/.gitignore

@@ -0,0 +1,9 @@
+.idea
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.2.6
+before_install: gem install bundler -v 1.16.1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at BurdetteLamar@Yahoo.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in structured_log.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,27 @@
+PATH
+  remote: .
+  specs:
+    structured_log (0.9.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.3)
+    markdown_helper (2.0.0)
+    minitest (5.11.3)
+    rake (10.5.0)
+
+PLATFORMS
+  x64-mingw32
+  x86-mingw32
+
+DEPENDENCIES
+  bundler (~> 1.16.2)
+  diff-lcs (~> 1.3)
+  markdown_helper (~> 2.0.0)
+  minitest (~> 5.0)
+  rake (~> 10.0)
+  structured_log!
+
+BUNDLED WITH
+   1.16.2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Burdette Lamar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 burdettelamar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,620 @@
+<!-- >>>>>> BEGIN GENERATED FILE (include): SOURCE readme_files/README.template.md -->
+# Structured Log
+
+<img src="images/structured.png" height="70" alt="Structured Log">
+
+Class <code>StructuredLog</code> offers structured (as opposed to flat) logging.  Nested sections (blocks) in Ruby code become nested XML elements in the log.
+
+This sectioning allows you to group actions in your program, and that grouping carries over into the log.
+
+Optionally, each section may include:
+<ul>
+<li>A timestamp.
+<li>A duration.
+<li>The ability to rescue and log an exception.
+</ul>
+
+And of course the class offers many ways to log data.
+
+## About the Examples
+
+A working example is worth a thousand words (maybe).
+
+Each of the following sections features an example Ruby program, followed by its output log.
+
+
+## Sections
+
+### Nested Sections
+<img src="images/nesting.jpg" height="70" alt="Nesting">
+
+Use nested sections to give structure to your log.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/sections.rb -->
+```sections.rb```:
+```ruby
+require 'structured_log'
+
+StructuredLog.open('sections.xml') do |log|
+  # Any code can be here.
+  log.section('Outer') do
+    # Any code can be here.
+    log.section('Mid') do
+      # Any code can be here.
+      log.section('Inner') do
+        # Any code can be here.
+      end
+      # Any code can be here.
+    end
+    # Any code can be here.
+  end
+  # Any code can be here.
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/sections.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/sections.xml -->
+```sections.xml```:
+```xml
+<log>
+  <section name='Outer'>
+    <section name='Mid'>
+      <section name='Inner'/>
+    </section>
+  </section>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/sections.xml -->
+
+### Text
+<img src="images/text.jpg" height="70" alt="Text">
+
+Add text to a <code>section</code> element by passing a string argument.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/text.rb -->
+```text.rb```:
+```ruby
+require 'structured_log'
+
+text = 'This section has text.'
+StructuredLog.open('text.xml') do |log|
+  log.section('with_text', text) do
+    # Any code can be here.
+  end
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/text.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/text.xml -->
+```text.xml```:
+```xml
+<log>
+  <section name='with_text'>
+    This section has text.
+  </section>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/text.xml -->
+
+### Attributes
+<img src="images/attributes.png" height="70" alt="Attributes">
+
+Add attributes to a <code>section</code> element by passing a hash argument.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/attributes.rb -->
+```attributes.rb```:
+```ruby
+require 'structured_log'
+
+attributes = {:a => 0, :b => 1}
+StructuredLog.open('attributes.xml') do |log|
+  log.section('with_attributes', attributes) do
+    log.comment('This section has attributes a and b.')
+  end
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/attributes.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/attributes.xml -->
+```attributes.xml```:
+```xml
+<log>
+  <section name='with_attributes' a='0' b='1'>
+    <comment>
+      This section has attributes a and b.
+    </comment>
+  </section>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/attributes.xml -->
+
+### Timestamps and Durations
+<img src="images/time.png" height="70" alt="Time">
+
+Add a timestamp or duration to a <code>section</code> element by passing a special symbol argument.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/time.rb -->
+```time.rb```:
+```ruby
+require 'structured_log'
+
+StructuredLog.open('time.xml') do |log|
+  log.section('Section with timestamp', :timestamp) do
+    log.comment('This section has a timestamp.')
+  end
+  log.section('Section with duration', :duration) do
+    log.comment('This section has a duration.')
+    sleep 1
+  end
+  log.section('Section with both', :duration, :timestamp) do
+    log.comment('This section has both.')
+    sleep 1
+  end
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/time.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/time.xml -->
+```time.xml```:
+```xml
+<log>
+  <section name='Section with timestamp' timestamp='2018-06-09-Sat-11.38.13.373'>
+    <comment>
+      This section has a timestamp.
+    </comment>
+  </section>
+  <section name='Section with duration' duration_seconds='1.016'>
+    <comment>
+      This section has a duration.
+    </comment>
+  </section>
+  <section name='Section with both' timestamp='2018-06-09-Sat-11.38.14.389' duration_seconds='1.000'>
+    <comment>
+      This section has both.
+    </comment>
+  </section>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/time.xml -->
+
+### Rescued Section
+<img src="images/rescue.jpg" height="70" alt="Rescue">
+
+Add rescuing to a <code>section</code> element by passing a special symbol argument.
+
+For the rescued exception, the class, message, and backtrace are logged.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/rescue.rb -->
+```rescue.rb```:
+```ruby
+require 'structured_log'
+
+StructuredLog.open('rescue.xml') do |log|
+  log.section('Section with rescue', :rescue) do
+    log.comment('This section will terminate because of the failure.')
+    fail 'This exception will be rescued and logged.'
+    log.comment('This comment will not be reached.')
+  end
+  log.section('Another section') do
+    log.comment('This comment will be reached and logged, because of rescue above.')
+  end
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/rescue.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/rescue.xml -->
+```rescue.xml```:
+```xml
+<log>
+  <section name='Section with rescue'>
+    <comment>
+      This section will terminate because of the failure.
+    </comment>
+    <rescued_exception timestamp='2018-06-09-Sat-11.38.12.889' class='RuntimeError'>
+      <message>
+        This exception will be rescued and logged.
+      </message>
+      <backtrace>
+        <![CDATA[
+C:/Users/Burdette/Documents/GitHub/structured_log/readme_files/scripts/rescue.rb:6:in `block (2 levels) in <main>'
+C:/Ruby22-x64/lib/ruby/gems/2.2.0/gems/structured_log-0.1.0/lib/structured_log.rb:58:in `block in section'
+C:/Ruby22-x64/lib/ruby/gems/2.2.0/gems/structured_log-0.1.0/lib/structured_log.rb:116:in `put_element'
+C:/Ruby22-x64/lib/ruby/gems/2.2.0/gems/structured_log-0.1.0/lib/structured_log.rb:57:in `section'
+C:/Users/Burdette/Documents/GitHub/structured_log/readme_files/scripts/rescue.rb:4:in `block in <main>'
+C:/Ruby22-x64/lib/ruby/gems/2.2.0/gems/structured_log-0.1.0/lib/structured_log.rb:38:in `open'
+C:/Users/Burdette/Documents/GitHub/structured_log/readme_files/scripts/rescue.rb:3:in `<main>'
+]]>
+      </backtrace>
+    </rescued_exception>
+  </section>
+  <section name='Another section'>
+    <comment>
+      This comment will be reached and logged, because of rescue above.
+    </comment>
+  </section>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/rescue.xml -->
+
+### Potpourri
+<img src="images/potpourri.png" height="70" alt="Potpourri">
+
+Pass any mixture of arguments to method <code>section</code>.
+
+The section name must be first; after that, anything goes.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/potpourri.rb -->
+```potpourri.rb```:
+```ruby
+require 'structured_log'
+
+attributes = {:a => 0, :b => 1}
+more_attributes = {:c => 2, :d => 3}
+text = 'This section has a potpourri.'
+float = 3.14159
+boolean = false
+fixnum = 1066
+time = Time.new
+exception = RuntimeError.new('Oops!')
+
+StructuredLog.open('potpourri.xml') do |log|
+  log.section('All together now', 'Order does not matter except in aggregating text and attributes.')  do
+    args = [attributes, :rescue, text, float, :duration, more_attributes, boolean, :timestamp, fixnum, time, exception]
+    log.section('Potpourri', *args) do
+    end
+    log.section('Reverse potpourri', *args.reverse) do
+    end
+  end
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/potpourri.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/potpourri.xml -->
+```potpourri.xml```:
+```xml
+<log>
+  <section name='All together now'>
+    Order does not matter except in aggregating text and attributes.
+    <section name='Potpourri' a='0' b='1' c='2' d='3' timestamp='2018-06-09-Sat-11.38.11.279' duration_seconds='0.000'>
+      This section has a potpourri.3.14159false10662018-06-09 11:38:11
+      -0500#&lt;RuntimeError: Oops!&gt;
+    </section>
+    <section name='Reverse potpourri' timestamp='2018-06-09-Sat-11.38.11.279' c='2' d='3' a='0' b='1' duration_seconds='0.000'>
+      #&lt;RuntimeError: Oops!&gt;2018-06-09 11:38:11 -05001066false3.14159This
+      section has a potpourri.
+    </section>
+  </section>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/potpourri.xml -->
+
+## Data
+
+### Hash-LIke Objects
+<img src="images/hash.png" height="30" alt="Hash">
+
+Use method <code>put_each_pair</code>, or its alias <code>put_hash</code>, to log an object that <code>respond_to?(:each_pair)</code>.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/hash.rb -->
+```hash.rb```:
+```ruby
+require 'structured_log'
+
+hash = {
+    :a => 'z',
+    :aa => 'zz',
+    :aaa => 'zzz',
+    :aaaa => 'zzzz',
+}
+StructuredLog.open('hash.xml') do |log|
+  log.put_hash('my_hash', hash)
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/hash.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/hash.xml -->
+```hash.xml```:
+```xml
+<log>
+  <each_pair name='my_hash' class='Hash'>
+    <![CDATA[
+a => z
+aa => zz
+aaa => zzz
+aaaa => zzzz
+]]>
+  </each_pair>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/hash.xml -->
+
+### Array-Like Objects
+<img src="images/array.jpg" height="30" alt="Array">
+
+Use method <code>put_each_with_index</code>, or its aliases <code>put_array</code> and <code>put_set</code>, to log an object that <code>respond_to?(:each_with_index)</code>.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/array.rb -->
+```array.rb```:
+```ruby
+require 'structured_log'
+
+array = %w/foo bar baz bat/
+StructuredLog.open('array.xml') do |log|
+  log.put_array('my_array', array)
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/array.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/array.xml -->
+```array.xml```:
+```xml
+<log>
+  <each_with_index name='my_array' class='Array'>
+    <![CDATA[
+     0 foo
+     1 bar
+     2 baz
+     3 bat
+]]>
+  </each_with_index>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/array.xml -->
+
+### Other Objects
+<img src="images/data.png" height="70" alt="Data">
+
+Use method <code>put_data</code> to log any object.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/data.rb -->
+```data.rb```:
+```ruby
+require 'structured_log'
+
+data = {
+    :float => 3.14,
+    :fixnum => 1066,
+    :false => false,
+    :time => Time.new,
+    :exception => RuntimeError.new('Oops!'),
+    :nil => nil,
+}
+StructuredLog.open('data.xml') do |log|
+  data.each_pair do |type, datum|
+    name = "my_#{type}"
+    log.put_data(name, datum)
+  end
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/data.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/data.xml -->
+```data.xml```:
+```xml
+<log>
+  <data name='my_float' class='Float'>
+    <![CDATA[3.14]]>
+  </data>
+  <data name='my_fixnum' class='Fixnum'>
+    <![CDATA[1066]]>
+  </data>
+  <data name='my_false' class='FalseClass'>
+    <![CDATA[false]]>
+  </data>
+  <data name='my_time' class='Time'>
+    <![CDATA[2018-06-09 11:38:10 -0500]]>
+  </data>
+  <data name='my_exception' class='RuntimeError'>
+    <![CDATA[#<RuntimeError: Oops!>]]>
+  </data>
+  <data name='my_nil' class='NilClass'>
+    <![CDATA[nil]]>
+  </data>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/data.xml -->
+
+### Formatted Text
+
+Use method <code>put_cdata</code> to log a string (possibly multi-line) as CDATA.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/cdata.rb -->
+```cdata.rb```:
+```ruby
+require 'structured_log'
+
+text = <<EOT
+
+Method put_cdata puts the data verbatim:
+
+* Nothing is added or subtracted.
+* Not even whitespace.
+
+So you can use the method to log a formatted string.
+
+(You'll need to add your own leading and trailing newlines, if desired.)
+
+EOT
+StructuredLog.open('cdata.xml') do |log|
+  log.put_cdata(text)
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/cdata.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/cdata.xml -->
+```cdata.xml```:
+```xml
+<log>
+  <![CDATA[
+Method put_cdata puts the data verbatim:
+
+* Nothing is added or subtracted.
+* Not even whitespace.
+
+So you can use the method to log a formatted string.
+
+(You'll need to add your own leading and trailing newlines, if desired.)
+]]>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/cdata.xml -->
+
+### Comment
+<img src="images/comment.png" height="70" alt="Comment">
+
+Use method <code>comment</code> to log a comment.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/comment.rb -->
+```comment.rb```:
+```ruby
+require 'structured_log'
+
+StructuredLog.open('comment.xml') do |log|
+  log.comment('My comment can be any text.')
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/comment.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/comment.xml -->
+```comment.xml```:
+```xml
+<log>
+  <comment>
+    My comment can be any text.
+  </comment>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/comment.xml -->
+
+## Custom Logging
+<img src="images/custom.png" width="70" alt="Custom">
+
+At the heart of class <code>StructuredLog</code> is method <code>put_element</code>.  It logs an element, possibly with children, attributes, and text.  Several methods call it, and you can too.
+
+Basically, it's just like method <code>section</code>, except that you choose the element name (instead of the fixed name <code>section</code>).
+
+Otherwise, it handles a block and all the same arguments as <code>section</code>.
+
+### Section
+
+Create a custom section by calling method <code>put_element</code> with a block.  The custom section will have children if you call logging methods within the block.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/custom_section.rb -->
+```custom_section.rb```:
+```ruby
+require 'structured_log'
+
+StructuredLog.open('custom_section.xml') do |log|
+  log.section('With blocks') do
+    log.put_element('section_with_children') do
+      log.put_element('child', :rank => 'Older')
+      log.put_element('child', :rank => 'Younger')
+    end
+    log.put_element('section_with_duration', :duration, 'Block contains timed code to be timed.') do
+      sleep 1
+    end
+    log.put_element('section_with_rescue', :rescue, 'Block contains code to be rescued if necessary.') do
+    end
+  end
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/custom_section.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/custom_section.xml -->
+```custom_section.xml```:
+```xml
+<log>
+  <section name='With blocks'>
+    <section_with_children>
+      <child rank='Older'/>
+      <child rank='Younger'/>
+    </section_with_children>
+    <section_with_duration duration_seconds='1.016'>
+      Block contains timed code to be timed.
+    </section_with_duration>
+    <section_with_rescue>
+      Block contains code to be rescued if necessary.
+    </section_with_rescue>
+  </section>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/custom_section.xml -->
+
+### Entry
+
+Create a custom entry by calling method <code>put_element</code> without a block.  The custom entry will not have children.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/custom_entry.rb -->
+```custom_entry.rb```:
+```ruby
+require 'structured_log'
+
+StructuredLog.open('custom_entry.xml') do |log|
+  log.section('Without blocks') do
+    log.put_element('element_with_text', 'No child elements, just this text.')
+    log.put_element('element_with_attributes', {:a => 0, :b => 1})
+    log.put_element('element_with_timestamp', :timestamp)
+    log.put_element('element_with_data', 3.14159)
+  end
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/custom_entry.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/custom_entry.xml -->
+```custom_entry.xml```:
+```xml
+<log>
+  <section name='Without blocks'>
+    <element_with_text>
+      No child elements, just this text.
+    </element_with_text>
+    <element_with_attributes a='0' b='1'/>
+    <element_with_timestamp timestamp='2018-06-09-Sat-11.38.09.357'/>
+    <element_with_data>
+      3.14159
+    </element_with_data>
+  </section>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/custom_entry.xml -->
+
+## Uncaught Exception
+<img src="images/exception.png" width="70" alt="Exception">
+
+Finally, what about an uncaught exception, one not rescued by <code>:rescue</code>?
+
+When an exception is raised in a section that does not have <code>:rescue</code>, the logger rescues and logs it anyway, just as if there were an invisible "outermost section" with <code>:rescue</code> (which, in fact, there is).
+
+Just as for a rescued exception, the log includes the exception's class, message, and backtrace.
+
+<!-- >>>>>> BEGIN INCLUDED FILE (ruby): SOURCE readme_files/scripts/exception.rb -->
+```exception.rb```:
+```ruby
+require 'structured_log'
+
+StructuredLog.open('exception.xml') do |log|
+  fail('Oops!')
+end
+```
+<!-- <<<<<< END INCLUDED FILE (ruby): SOURCE readme_files/scripts/exception.rb -->
+
+<!-- >>>>>> BEGIN INCLUDED FILE (xml): SOURCE readme_files/logs/exception.xml -->
+```exception.xml```:
+```xml
+<log>
+  <uncaught_exception timestamp='2018-06-09-Sat-11.38.10.967' class='RuntimeError'>
+    <message>
+      Oops!
+    </message>
+    <backtrace>
+      <![CDATA[
+C:/Users/Burdette/Documents/GitHub/structured_log/readme_files/scripts/exception.rb:4:in `block in <main>'
+C:/Ruby22-x64/lib/ruby/gems/2.2.0/gems/structured_log-0.1.0/lib/structured_log.rb:38:in `open'
+C:/Users/Burdette/Documents/GitHub/structured_log/readme_files/scripts/exception.rb:3:in `<main>'
+]]>
+    </backtrace>
+  </uncaught_exception>
+</log>
+```
+<!-- <<<<<< END INCLUDED FILE (xml): SOURCE readme_files/logs/exception.xml -->
+<!-- <<<<<< END GENERATED FILE (include): SOURCE readme_files/README.template.md -->