{
    "content": [
        {
            "type": "text",
            "text": "# Template::Plugin::String (perldoc)\n\n## NAME\n\nTemplate::Plugin::String - Object oriented interface for string manipulation\n\n## SYNOPSIS\n\n# create String objects via USE directive\n[% USE String %]\n[% USE String 'initial text' %]\n[% USE String text => 'initial text' %]\n# or from an existing String via new()\n[% newstring = String.new %]\n[% newstring = String.new('newstring text') %]\n[% newstring = String.new( text => 'newstring text' ) %]\n# or from an existing String via copy()\n[% newstring = String.copy %]\n# append text to string\n[% String.append('text to append') %]\n# format left, right or center/centre padded\n[% String.left(20) %]\n[% String.right(20) %]\n[% String.center(20) %]   # American spelling\n[% String.centre(20) %]   # European spelling\n# and various other methods...\n\n## DESCRIPTION\n\nThis module implements a \"String\" class for doing stringy things to text in an object-oriented\nway.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **CONSTRUCTOR METHODS**\n- **INSPECTOR METHODS**\n- **MUTATOR METHODS**\n- **AUTHOR**\n- **COPYRIGHT**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Template::Plugin::String",
        "section": "",
        "mode": "perldoc",
        "summary": "Template::Plugin::String - Object oriented interface for string manipulation",
        "synopsis": "# create String objects via USE directive\n[% USE String %]\n[% USE String 'initial text' %]\n[% USE String text => 'initial text' %]\n# or from an existing String via new()\n[% newstring = String.new %]\n[% newstring = String.new('newstring text') %]\n[% newstring = String.new( text => 'newstring text' ) %]\n# or from an existing String via copy()\n[% newstring = String.copy %]\n# append text to string\n[% String.append('text to append') %]\n# format left, right or center/centre padded\n[% String.left(20) %]\n[% String.right(20) %]\n[% String.center(20) %]   # American spelling\n[% String.centre(20) %]   # European spelling\n# and various other methods...",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 24,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 68,
                "subsections": []
            },
            {
                "name": "CONSTRUCTOR METHODS",
                "lines": 15,
                "subsections": []
            },
            {
                "name": "INSPECTOR METHODS",
                "lines": 34,
                "subsections": []
            },
            {
                "name": "MUTATOR METHODS",
                "lines": 159,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Template::Plugin::String - Object oriented interface for string manipulation\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "# create String objects via USE directive\n[% USE String %]\n[% USE String 'initial text' %]\n[% USE String text => 'initial text' %]\n\n# or from an existing String via new()\n[% newstring = String.new %]\n[% newstring = String.new('newstring text') %]\n[% newstring = String.new( text => 'newstring text' ) %]\n\n# or from an existing String via copy()\n[% newstring = String.copy %]\n\n# append text to string\n[% String.append('text to append') %]\n\n# format left, right or center/centre padded\n[% String.left(20) %]\n[% String.right(20) %]\n[% String.center(20) %]   # American spelling\n[% String.centre(20) %]   # European spelling\n\n# and various other methods...\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This module implements a \"String\" class for doing stringy things to text in an object-oriented\nway.\n\nYou can create a \"String\" object via the \"USE\" directive, adding any initial text value as an\nargument or as the named parameter \"text\".\n\n[% USE String %]\n[% USE String 'initial text' %]\n[% USE String text='initial text' %]\n\nThe object created will be referenced as \"String\" by default, but you can provide a different\nvariable name for the object to be assigned to:\n\n[% USE greeting = String 'Hello World' %]\n\nOnce you've got a \"String\" object, you can use it as a prototype to create other \"String\"\nobjects with the \"new()\" method.\n\n[% USE String %]\n[% greeting = String.new('Hello World') %]\n\nThe \"new()\" method also accepts an initial text string as an argument or the named parameter\n\"text\".\n\n[% greeting = String.new( text => 'Hello World' ) %]\n\nYou can also call \"copy()\" to create a new \"String\" as a copy of the original.\n\n[% greet2 = greeting.copy %]\n\nThe \"String\" object has a \"text()\" method to return the content of the string.\n\n[% greeting.text %]\n\nHowever, it is sufficient to simply print the string and let the overloaded stringification\noperator call the \"text()\" method automatically for you.\n\n[% greeting %]\n\nThus, you can treat \"String\" objects pretty much like any regular piece of text, interpolating\nit into other strings, for example:\n\n[% msg = \"It printed '$greeting' and then dumped core\\n\" %]\n\nYou also have the benefit of numerous other methods for manipulating the string.\n\n[% msg.append(\"PS  Don't eat the yellow snow\") %]\n\nNote that all methods operate on and mutate the contents of the string itself. If you want to\noperate on a copy of the string then simply take a copy first:\n\n[% msg.copy.append(\"PS  Don't eat the yellow snow\") %]\n\nThese methods return a reference to the \"String\" object itself. This allows you to chain\nmultiple methods together.\n\n[% msg.copy.append('foo').right(72) %]\n\nIt also means that in the above examples, the \"String\" is returned which causes the \"text()\"\nmethod to be called, which results in the new value of the string being printed. To suppress\nprinting of the string, you can use the \"CALL\" directive.\n\n[% foo = String.new('foo') %]\n\n[% foo.append('bar') %]         # prints \"foobar\"\n\n[% CALL foo.append('bar') %]    # nothing\n",
                "subsections": []
            },
            "CONSTRUCTOR METHODS": {
                "content": "These methods are used to create new \"String\" objects.\n\nnew()\nCreates a new string using an initial value passed as a positional argument or the named\nparameter \"text\".\n\n[% USE String %]\n[% msg = String.new('Hello World') %]\n[% msg = String.new( text => 'Hello World' ) %]\n\ncopy()\nCreates a new \"String\" object which contains a copy of the original string.\n\n[% msg2 = msg.copy %]\n",
                "subsections": []
            },
            "INSPECTOR METHODS": {
                "content": "These methods are used to examine the string.\n\ntext()\nReturns the internal text value of the string. The stringification operator is overloaded to\ncall this method. Thus the following are equivalent:\n\n[% msg.text %]\n[% msg %]\n\nlength()\nReturns the length of the string.\n\n[% USE String(\"foo\") %]\n[% String.length %]   # => 3\n\nsearch($pattern)\nSearches the string for the regular expression specified in $pattern returning true if found or\nfalse otherwise.\n\n[% item = String.new('foo bar baz wiz waz woz') %]\n[% item.search('wiz') ? 'WIZZY! :-)' : 'not wizzy :-(' %]\n\nsplit($pattern, $limit)\nSplits the string based on the delimiter $pattern and optional $limit. Delegates to Perl's\ninternal \"split()\" so the parameters are exactly the same.\n\n[% FOREACH item.split %]\n...\n[% END %]\n\n[% FOREACH item.split('baz|waz') %]\n...\n[% END %]\n",
                "subsections": []
            },
            "MUTATOR METHODS": {
                "content": "These methods modify the internal value of the string. For example:\n\n[% USE str=String('foobar') %]\n[% str.append('.html') %]   # str => 'foobar.html'\n\nThe value of \"str\" is now '\"foobar.html\"'. If you don't want to modify the string then simply\ntake a copy first.\n\n[% str.copy.append('.html') %]\n\nThese methods all return a reference to the \"String\" object itself. This has two important\nbenefits. The first is that when used as above, the \"String\" object '\"str\"' returned by the\n\"append()\" method will be stringified with a call to its \"text()\" method. This will return the\nnewly modified string content. In other words, a directive like:\n\n[% str.append('.html') %]\n\nwill update the string and also print the new value. If you just want to update the string but\nnot print the new value then use \"CALL\".\n\n[% CALL str.append('.html') %]\n\nThe other benefit of these methods returning a reference to the \"String\" is that you can chain\nas many different method calls together as you like. For example:\n\n[% String.append('.html').trim.format(href) %]\n\nHere are the methods:\n\npush($suffix, ...) / append($suffix, ...)\nAppends all arguments to the end of the string. The \"append()\" method is provided as an alias\nfor \"push()\".\n\n[% msg.push('foo', 'bar') %]\n[% msg.append('foo', 'bar') %]\n\npop($suffix)\nRemoves the suffix passed as an argument from the end of the String.\n\n[% USE String 'foo bar' %]\n[% String.pop(' bar')   %]   # => 'foo'\n\nunshift($prefix, ...) / prepend($prefix, ...)\nPrepends all arguments to the beginning of the string. The \"prepend()\" method is provided as an\nalias for \"unshift()\".\n\n[% msg.unshift('foo ', 'bar ') %]\n[% msg.prepend('foo ', 'bar ') %]\n\nshift($prefix)\nRemoves the prefix passed as an argument from the start of the String.\n\n[% USE String 'foo bar' %]\n[% String.shift('foo ') %]   # => 'bar'\n\nleft($pad)\nIf the length of the string is less than $pad then the string is left formatted and padded with\nspaces to $pad length.\n\n[% msg.left(20) %]\n\nright($pad)\nAs per left() but right padding the \"String\" to a length of $pad.\n\n[% msg.right(20) %]\n\ncenter($pad) / centre($pad)\nAs per left() and right() but formatting the \"String\" to be centered within a space padded\nstring of length $pad. The \"centre()\" method is provided as an alias for \"center()\".\n\n[% msg.center(20) %]    # American spelling\n[% msg.centre(20) %]    # European spelling\n\nformat($format)\nApply a format in the style of \"sprintf()\" to the string.\n\n[% USE String(\"world\") %]\n[% String.format(\"Hello %s\\n\") %]  # => \"Hello World\\n\"\n\nupper()\nConverts the string to upper case.\n\n[% USE String(\"foo\") %]\n[% String.upper %]  # => 'FOO'\n\nlower()\nConverts the string to lower case\n\n[% USE String(\"FOO\") %]\n[% String.lower %]  # => 'foo'\n\ncapital()\nConverts the first character of the string to upper case.\n\n[% USE String(\"foo\") %]\n[% String.capital %]  # => 'Foo'\n\nThe remainder of the string is left untouched. To force the string to be all lower case with\nonly the first letter capitalised, you can do something like this:\n\n[% USE String(\"FOO\") %]\n[% String.lower.capital %]  # => 'Foo'\n\nchop()\nRemoves the last character from the string.\n\n[% USE String(\"foop\") %]\n[% String.chop %]   # => 'foo'\n\nchomp()\nRemoves the trailing newline from the string.\n\n[% USE String(\"foo\\n\") %]\n[% String.chomp %]  # => 'foo'\n\ntrim()\nRemoves all leading and trailing whitespace from the string\n\n[% USE String(\"   foo   \\n\\n \") %]\n[% String.trim %]   # => 'foo'\n\ncollapse()\nRemoves all leading and trailing whitespace and collapses any sequences of multiple whitespace\nto a single space.\n\n[% USE String(\" \\n\\r  \\t  foo   \\n \\n bar  \\n\") %]\n[% String.collapse %]   # => \"foo bar\"\n\ntruncate($length, $suffix)\nTruncates the string to $length characters.\n\n[% USE String('long string') %]\n[% String.truncate(4) %]  # => 'long'\n\nIf $suffix is specified then it will be appended to the truncated string. In this case, the\nstring will be further shortened by the length of the suffix to ensure that the newly\nconstructed string complete with suffix is exactly $length characters long.\n\n[% USE msg = String('Hello World') %]\n[% msg.truncate(8, '...') %]   # => 'Hello...'\n\nreplace($search, $replace)\nReplaces all occurrences of $search in the string with $replace.\n\n[% USE String('foo bar foo baz') %]\n[% String.replace('foo', 'wiz')  %]  # => 'wiz bar wiz baz'\n\nremove($search)\nRemove all occurrences of $search in the string.\n\n[% USE String('foo bar foo baz') %]\n[% String.remove('foo ')  %]  # => 'bar baz'\n\nrepeat($count)\nRepeats the string $count times.\n\n[% USE String('foo ') %]\n[% String.repeat(3)  %]  # => 'foo foo foo '\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Andy Wardley <abw@wardley.org> <http://wardley.org/>\n",
                "subsections": []
            },
            "COPYRIGHT": {
                "content": "Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.\n\nThis module is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "Template::Plugin\n",
                "subsections": []
            }
        }
    }
}