NAME
    String::Sections - Extract labeled groups of sub-strings from a string.

VERSION
    version 0.2.3

SYNOPSIS
      use String::Sections;

      my $sections = String::Sections->new();
      my $result = $sections->load_list( @lines );
      # TODO
      # $sections->load_string( $string );
      # $sections->load_filehandle( $fh );
      #
      # $sections->merge( $other_sections_object );

      my @section_names = $result->section_names();
      if ( $result->has_section( 'section_label' ) ) {
        my $string_ref = $result->section( 'section_label' );
        ...
      }

DESCRIPTION
    Data Section sports the following default data markup

      __[ somename ]__
      Data
      __[ anothername ]__
      More data

    This module is designed to behave as a work-alike, except on already
    extracted string data.

METHODS
  new
  new( %args )
      my $object = String::Sections->new();

      my $object = String::Sections->new( attribute_name => 'value' );

  load_list ( @strings )
      my @strings = <$fh>;

      my $result = $string_section->load_list( @strings );

    This method handles data as if it had been slopped in unchomped from a
    filehandle.

    Ideally, each entry in @strings will be terminated with $/ , as the
    collated data from each section is concatenated into a large singular
    string, e.g.:

      $result = $string_section->load_list("__[ Foo ]__\n", "bar\n", "baz\n" );
      $section_foo = $result->section('Foo')
      # bar
      # baz

      $result = $s_s->load_list("__[ Foo ]__\n", "bar", "baz" );
      $result->section('Foo');
      # barbaz

      $object->load_list("__[ Foo ]__", "bar", "baz" ) # will not work by default.

    This behaviour may change in the future, but this is how it is with the
    least effort for now.

  load_string
    TODO

  load_filehandle( $fh )
      my $result = $object->load_filehandle( $fh )

  header_regex
  empty_line_regex
  document_end_regex
  line_escape_regex
  default_name
  stop_at_end
  ignore_empty_prelude
  enable_escapes
ATTRIBUTES
  header_regex
  empty_line_regex
  document_end_regex
  line_escape_regex
  default_name
  stop_at_end
  ignore_empty_prelude
  enable_escapes
PRIVATE METHODS
  __add_line
  _default_header_regex
  _default_empty_line_regex
  _default_document_end_regex
  _default_line_escape_regex
  _default_default_name
  _default_stop_at_end
  _default_ignore_empty_prelude
  _default_enable_escapes
PRIVATE FUNCTIONS
  _croak
  _isa_regexp
  _isa_boolean
  _isa_boolean
  _regex_type
  _string_type
  _boolean_type
DEVELOPMENT
    This code is still new and under development.

    All the below facets are likely to change at some point, but don't
    largely contribute to the API or usage of this module.

    *   Needs Perl 5.10.1

        To make some of the development features easier.

Recommended Use with Data::Handle
    This modules primary inspiration is Data::Section, but intending to
    split and decouple many of the internal parts to add leverage to the
    various behaviors it contains.

    Data::Handle solves part of a problem with Perl by providing a more
    reliable interface to the __DATA__ section in a file that is not impeded
    by various things that occur if its attempted to be read more than once.

    In future, I plan on this being the syntax for connecting Data::Handle
    with this module to emulate Data::Section:

      my $dh = Data::Handle->new( __PACKAGE__ );
      my $ss = String::Sections->new( stop_at_end => 1 );
      my $result = $ss->load_filehandle( $dh );

    This doesn't implicitly perform any of the inheritance tree magic
    Data::Section does, but its also planned on making that easy to do when
    you want it with "->merge( $section )"

    For now, the recommended code is not so different:

      my $dh = Data::Handle->new( __PACKAGE__ );
      my $ss = String::Sections->new( stop_at_end => 1 );
      my $result  = $ss->load_list( <$dh> );

    Its just somewhat less efficient.

SIGNIFICANT CHANGES
  Since 0.1.x
   API
    In 0.1.x, "API" was

        my $section = String::Sections->new();
        $section->load_*( $source );
        $section->section_names

    This was inherently fragile, and allowed weird things to occur when
    people tried to get data from it without it being populated yet.

    So starting with 0.2.0, the "API" is

        my $section = String::Sections->new();
        my $result  = $section->load_*( $source );
        $result->section_names;

    And the main class is a factory for "String::Sections::Result" objects.

AUTHOR
    Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by Kent Fredric <kentnl@cpan.org>.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.