Steven Haryanto > Text-Fragment-0.01 > Text::Fragment

Download:
Text-Fragment-0.01.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.01   Source  

NAME ^

Text::Fragment - Manipulate fragments in text

VERSION ^

version 0.01

SYNOPSIS ^

 use Text::Fragment qw(list_fragments
                       get_fragment
                       set_fragment_attrs
                       insert_fragment
                       delete_fragment);

 my $text = <<_;
 foo = "some value"
 baz = 0
 _

To insert a fragment:

 my $res = insert_fragment(text=>$text, id=>'bar', payload=>'bar = 2');

$res->[2]{text} will now contain:

 foo = "some value"
 baz = 0
 bar = 2 # FRAGMENT id=bar

To replace a fragment:

 $res = insert_fragment(text=>$res->[2], id='bar', payload=>'bar = 3');

$res->[2]{text} will now contain:

 foo = "some value"
 baz = 0
 bar = 3 # FRAGMENT id=bar

and $res->[2]{orig_payload} will contain the payload before being replaced:

 bar = 2

To delete a fragment:

 $res = delete_fragment(text=>$res->[2], id=>'bar');

To list fragments:

 $res = list_fragment(text=>$text);

To get a fragment:

 $res = get_fragment(text=>$text, id=>'bar');

To set fragment attributes:

 $res = se_fragment_attrs(text=>$text, id=>'bar', attrs=>{name=>'val', ...});

DESCRIPTION ^

A fragment is a single line or a group of lines (called payload) with a metadata encoded in the comment that is put adjacent to it (for a single line fragment) or enclosing it (for a multiline fragment). Fragments are usually used in configuration files or code. Here is the structure of a single-line fragment:

    <payload> # <label> <attrs>

Here is the structure of a multi-line fragment:

    # BEGIN <label> <attrs>
    <payload>
    # END <label> [<attrs>]

Label is by default FRAGMENT but can be other string. Attributes are a sequence of name=val separated by whitespace, where name must be alphanums only and val is zero or more non-whitespace characters. There must at least be an attribute with name id, it is used to identify fragment and allow the fragment to be easily replaced/modified/deleted from text. Attributes are optional in the ending comment.

Comment character used is by default # (shell-style comment), but other comment styles are supported (see below).

Examples of single-line fragments (the second example uses c-style comment and the third uses cpp-style comment):

    RSYNC_ENABLE=1 # FRAGMENT id=enable
    some text /* FRAGMENT id=id2 */
    some text // FRAGMENT id=id3 foo=1 bar=2

An example of multi-line fragment (using html-style comment instead of shell):

    <!-- BEGIN FRAGMENT id=id4 -->
    some
    lines
    of
    text
    <!-- END FRAGMENT id=id4 -->

Another example (using ini-style comment):

    ; BEGIN FRAGMENT id=default-settings
    register_globals=On
    extension=mysql.so
    extension=gd.so
    memory_limit=256M
    post_max_size=64M
    upload_max_filesize=64M
    browscap=/c/share/php/browscap.ini
    allow_url_fopen=0
    ; END FRAGMENT

This module has Rinci metadata.

FUNCTIONS ^

None are exported by default, but they are exportable.

delete_fragment(%args) -> [status, msg, result, meta]

Delete fragment in text.

If there are multiple occurences of fragment (which is considered an abnormal condition), all occurences will be deleted.

Arguments ('*' denotes required arguments):

Return value:

Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

get_fragment(%args) -> [status, msg, result, meta]

Get fragment with a certain ID in text.

If there are multiple occurences of the fragment with the same ID ,

Arguments ('*' denotes required arguments):

Return value:

Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

insert_fragment(%args) -> [status, msg, result, meta]

Insert or replace a fragment in text.

Arguments ('*' denotes required arguments):

Return value:

Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

list_fragments(%args) -> [status, msg, result, meta]

List fragments in text.

Arguments ('*' denotes required arguments):

Return value:

Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

set_fragment_attrs(%args) -> [status, msg, result, meta]

Set/unset attributes of a fragment.

If there are multiple occurences of the fragment with the same ID ,

Arguments ('*' denotes required arguments):

Return value:

Returns an enveloped result (an array). First element (status) is an integer containing HTTP status code (200 means OK, 4xx caller error, 5xx function error). Second element (msg) is a string containing error message, or 'OK' if status is 200. Third element (result) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

AUTHOR ^

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2012 by Steven Haryanto.

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

syntax highlighting: