Text::Fragment - Manipulate fragments in text
version 0.01
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:
$res->[2]{text}
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');
foo = "some value" baz = 0 bar = 3 # FRAGMENT id=bar
and $res->[2]{orig_payload} will contain the payload before being replaced:
$res->[2]{orig_payload}
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', ...});
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.
FRAGMENT
name=val
id
Comment character used is by default # (shell-style comment), but other comment styles are supported (see below).
#
shell
Examples of single-line fragments (the second example uses c-style comment and the third uses cpp-style comment):
c
cpp
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):
html
<!-- BEGIN FRAGMENT id=id4 --> some lines of text <!-- END FRAGMENT id=id4 -->
Another example (using ini-style comment):
ini
; 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.
None are exported by default, but they are exportable.
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):
comment_style => str (default: "shell")
Comment style.
id* => str
Fragment ID.
label => code|str (default: "FRAGMENT")
Comment label.
text* => str
The text to delete fragment from.
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 with a certain ID in text.
If there are multiple occurences of the fragment with the same ID ,
label => str (default: "FRAGMENT")
The text which contain fragments.
Insert or replace a fragment in text.
attrs => hash (default: {})
good_pattern => str
Regex pattern which if found means fragment need not be inserted.
payload* => str
Fragment content.
replace_pattern => str
Regex pattern which if found will be used for placement of fragment.
If fragment needs to be inserted into file, then if replace_pattern is defined then it will be searched. If found, fragment will be placed to replace the pattern. Otherwise, fragment will be inserted at the end (or beginning, see top_style) of file.
replace_pattern
top_style
The text to insert fragment into.
top_style => bool (default: 0)
Whether to append fragment at beginning of file instead of at the end.
Default is false, which means to append at the end of file.
Note that this only has effect if replace_pattern is not defined or replace pattern is not found in file. Otherwise, fragment will be inserted to replace the pattern.
List fragments in text.
Set/unset attributes of a fragment.
attrs* => hash
To delete an attribute in the fragment, you can set the value to undef.
Steven Haryanto <stevenharyanto@gmail.com>
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.
To install Text::Fragment, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Text::Fragment
CPAN shell
perl -MCPAN -e shell install Text::Fragment
For more information on module installation, please visit the detailed CPAN module installation guide.