=head1 NAME

Hub::Parse::Transform - 

Part of the L<Hub Library|hublib>

=head1 SYNOPSIS



=head1 DESCRIPTION



=head1 METHODS

=begin html

<table><tr><td>
<a class="methlink" href="#item_abspath">abspath</a>

</td><td>
<a class="methlink" href="#item_fixpath">fixpath</a>

</td><td>
<a class="methlink" href="#item_hashtoattrs">hashtoattrs</a>

</td><td>
<a class="methlink" href="#item_packcgi">packcgi</a>

</td><td>
<a class="methlink" href="#item_siteurl">siteurl</a>

</td></tr><tr><td>
<a class="methlink" href="#item_attrhash">attrhash</a>

</td><td>
<a class="methlink" href="#item_fw">fw</a>

</td><td>
<a class="methlink" href="#item_html">html</a>

</td><td>
<a class="methlink" href="#item_polish">polish</a>

</td><td>
<a class="methlink" href="#item_trimcss">trimcss</a>

</td></tr><tr><td>
<a class="methlink" href="#item_datetime">datetime</a>

</td><td>
<a class="methlink" href="#item_getext">getext</a>

</td><td>
<a class="methlink" href="#item_indenttext">indenttext</a>

</td><td>
<a class="methlink" href="#item_populate">populate</a>

</td><td>
<a class="methlink" href="#item_trimhtmlstyle">trimhtmlstyle</a>

</td></tr><tr><td>
<a class="methlink" href="#item_dhms">dhms</a>

</td><td>
<a class="methlink" href="#item_getname">getname</a>

</td><td>
<a class="methlink" href="#item_jsstr">jsstr</a>

</td><td>
<a class="methlink" href="#item_ps">ps</a>

</td><td>
<a class="methlink" href="#item_unpackcgi">unpackcgi</a>

</td></tr><tr><td>
<a class="methlink" href="#item_fcols">fcols</a>

</td><td>
<a class="methlink" href="#item_getpath">getpath</a>

</td><td>
<a class="methlink" href="#item_mkabsdir">mkabsdir</a>

</td><td>
<a class="methlink" href="#item_relpath">relpath</a>

</td></tr><tr><td>
<a class="methlink" href="#item_findabsolutepath">findAbsolutePath</a>

</td><td>
<a class="methlink" href="#item_getspec">getspec</a>

</td><td>
<a class="methlink" href="#item_nbspstr">nbspstr</a>

</td><td>
<a class="methlink" href="#item_safestr">safestr</a>

</td></tr></table>

=end html


=over 4

=item abspath

B<>

 Usage: abspath PATH
 Usage: abspath PATH NOCHECK


File must exist unless NOCHECK is specified.


=back

=over 4

=item attrhash

B<>



=back

=over 4

=item datetime

B<>

 Usage: datetime TIMESTAMP?, OPTION*


Friendly date-time formats of seconds-since-the-epoch timestamps.

Default is the current time formatted as: MM/DD/YYYY hh:mm:ss.

The decimal portion of HiRest time is truncated.

Uses `localtime` to localize.


B<This example> returns: B<true>:

    datetime( );

B<This example> returns: B<regex>:

    datetime( 1045837284 );

B<This example> returns: B<regex>:

    datetime( 1045837284, -nosec );

B<This example> returns: B<regex>:

    datetime( 1045837284, -noyear );

B<This example> returns: B<regex>:

    datetime( 1045837284, -ampm );

B<This example> returns: B<regex>:

    datetime( 1045837284, -nozeros );

B<This example> returns: B<regex>:

    datetime( 1045837284, -notime );

B<This example> returns: B<regex>:

    datetime( 1045837284, -nodate );

B<This example> returns: B<regex>:

    datetime( 1045837284, -letter );


Combining options



B<This example> returns: B<regex>:

    datetime( 1045837284, -ampm, -nosec );              



B<This example> returns: B<regex>:

    datetime( 1045837284, -nosec, -nozeros, -noyear );


Methods of passing options via tweaks (see Parser.pm)



B<This example> returns: B<regex>:

    datetime( 1045837284, "nosec,noyear" );

=back

=over 4

=item dhms

B<>

Hub::dhms( $seconds, $options, $format )


Format the provided number of seconds in days, hours, minutes, and seconds.



  Examples:                                               Returns:
  ------------------------------------------------------- --------------------
  Hub::dhms( 10 )                                              00d:00h:00m:10s
  Hub::dhms( 60 )                                              00d:00h:01m:00s
  Hub::dhms( 3600 )                                            00d:01h:00m:00s
  Hub::dhms( 86400 )                                           01d:00h:00m:00s
  Hub::dhms( 11 )                                              00d:00h:00m:11s
  Hub::dhms( 71 )                                              00d:00h:01m:11s
  Hub::dhms( 3671 )                                            00d:01h:01m:11s
  Hub::dhms( 90071 )                                           01d:01h:01m:11s
  Hub::dhms( 90071, "--nozeros" )                              1d:1h:1m:11s
  Hub::dhms( 90071, "--nozeros" )                              1d:1h:1m:11s
  Hub::dhms( 90071, "--nozeros", "days ::" )   1days 1:1:11
  Hub::dhms( 90071, "days ::" )                01days 01:01:11


=back

=over 4

=item fcols

B<>

 Usage: fcols STRING, COLS, [OPTIONS]

Divide text into fixed-width columns.



Where OPTIONS can be:


  --split:REGEX                   # Split on regex REGEX (default '\s')
  --flow:ttb|ltr                  # Top-to-bottom or Left-to-right (default 'ttb')
  --pad:NUM                       # Spacing between columns (default 1)
  --padwith:STR                   # Pad with STR (multiplied by --pad)
  --width:NUM                     # Force column width (--pad becomes irrelevant)
  --justify:left|center|right     # Justify within column


Examples:

  1) print fcols( "A B C D E F G", 4, "-flow=ttb" ), "\n";


      A C E G
      B D F


  2) print fcols( "a b c d e f g", 4, "-flow=ltr" ), "\n";


      a b c d
      e f g



=back

=over 4

=item findAbsolutePath

B<>



  findAbsolutePath( "../usr/" )
  findAbsolutePath( "/usr/local" )


  File may or may not exist



=back

=over 4

=item fixpath

B<>

 Usage: fixpath( $path )


Clean up malformed paths (usually do to concatenation logic).


B<Example: This example>:

    fixpath( "../../../users/newuser/web/bin/../src/screens" );

B<matches>:

    ../../../users/newuser/web/src/screens

B<Example: This example>:

    fixpath( "users/newuser/web/" );

B<matches>:

    users/newuser/web

B<Example: This example>:

    fixpath( "users/../web/bin/../src" );

B<matches>:

    web/src

B<Example: This example>:

    fixpath( "users//newuser" );

B<matches>:

    users/newuser

B<Example: This example>:

    fixpath( "users//newuser/./files" );

B<matches>:

    users/newuser/files

B<Example: This example>:

    fixpath( "http://site/users//newuser" );

B<matches>:

    http://site/users/newuser

B<Example: This example>:

    fixpath( '/home/hub/build/../../../out/doc/pod' );

B<matches>:

    /out/doc/pod

=back

=over 4

=item fw

B<fixed-width (default padding is a space)>




Warning, many calls to this method is a performance hit!


usage examples:


  Hub::fw( 5, "Hello World" )                  "Hello"
  Hub::fw( 5, "Hello World", '-clip=0' )       "Hello world"
  Hub::fw( 5, "Hi" )                           "Hi   "
  Hub::fw( 5, "Hi", '-align=r' )               "   Hi"
  Hub::fw( 5, "Hi", '-align=l' )               "Hi   "
  Hub::fw( 5, "Hi", '-align=c' )               "  Hi "
  Hub::fw( 5, "Hi", '-repeat' )                "HHHHH"
  Hub::fw( 5, "Hi", '-pad=x' )                 "Hixxx"
  Hub::fw( 5, "Hi", '-pad=x', '-align=r' )     "xxxHi"


  Depricated:


  Hub::fw( 5, "Hi", "right" )                  "   Hi"
  Hub::fw( 5, "Hi", "repeat" )                 "HHHHH"
  Hub::fw( 5, "Hi", "padding:x" )              "Hixxx"
  Hub::fw( 5, "Hi", "padding:x", "right" )     "xxxHi"



=back

=over 4

=item getext

B<>

  getext( $path )


  example:


      getext( "/foo/bar/filename.ext" )
      getext( "filename.cgi" )


  will return:


      "ext"
      "cgi"



=back

=over 4

=item getname

B<>

  getname( $path )


  Note, if the given path is a full directory path, the last directory is
  still considerred a filename.



  example:


      getname( "../../../users/newuser/web/data/p001/batman-small.jpg" );
      getname( "../../../users/newuser/web/data/p001" );
      getname( "/var/log/*.log" );


  will return:


      "batman-small.jpg"
      "p001"
      "*.log"



=back

=over 4

=item getpath

B<>

  Exract the parent from the given filepath


  for example:


      getpath( "/etc/passwd" )        /etc
      getpath( "/usr/local/bin" )     /usr/local



=back

=over 4

=item getspec

B<>

 Usage: getspec PATH

Given a path to a file, return it's parts (directory, filename, extension);

=back

=over 4

=item hashtoattrs

B<>

 Usage: hashtoattrs

Turn the given hash into an key="value" string.



  {
      'class'     => "foodidly",
      'name'      => "bobsmith",
      'height'    => "5px",
  }


Becomes:


  class="foodidly" name="bobsmith" height="5px"



=back

=over 4

=item html

B<>

  Format a string, replacing spaces with '&nbsp;'


  for example:


      html( "<Hello=world!>" )              "&lt;Hello=World&gt;"



=back

=over 4

=item indenttext

B<>

 Usage: indenttext TEXT, NUM, [PADINGCHAR]

Indent text

=back

=over 4

=item jsstr

B<>

 Usage: jsstr


Format as one long string for use as the rval in javascript (ie put the
backslash continue-ator at the end of each line).


=back

=over 4

=item mkabsdir

B<>

 Usage: mkabsdir DIR

Create the directory specified.


=back

=over 4

=item nbspstr

B<>

  Format a string, replacing spaces with '&nbsp;'


  for example:


      nbspstr( "Hello <not html tags> world!" )


  would return:


      "Hello&nbsp;<not html tags>&nbsp;World"



=back

=over 4

=item packcgi

B<>

 Usage: packcgi $string|\$string

Pack characters into those used for passing by the cgi.


=back

=over 4

=item polish

B<Remove undefined variables>




We will chomp lines so that:


  In between two
  lines with text
  or when



  surrounded spaced out..



Will become:


  In between two
  lines with text
  or when


  surrounded spaced out..




=back

=over 4

=item populate

B<Populate template text with values>


 Usage: populate $text|\$text, \%values [,\%values...] [option]


options:


  -sdref=0                Turn off scalar dereferencing
  -polish=1               Remove unpopulated variable references

B<Example: This example>:

    populate( 'mum', { foo => 'shroo' } );

B<matches>:

    mushroom

B<Example: This example>:

    ref( populate( 'ac', { b => 'bee' }, '-sdref=0' ) );

B<matches>:

    SCALAR

=back

=over 4

=item ps

B<>

 Usage: ps


Aka: Proportional Space


Split the given string up into multiple lines which will not exceed the
specified character width.



Default padding is a space.


B<Example: This example>:

    ps( 10, "this is really short but splits on ten chars" );



B<matches>:

    this is re
    ally short
 but split
    s on ten c
    hars

B<Example: This example>:

    ps( 10, "this is really short but splits on ten chars", 3 );


B<matches>:

    this is re
   ally short
    but split
   s on ten c
   hars

=back

=over 4

=item relpath

B<Relative path>




 Usage: relpath PATH, FROMPATH


OPTIONS:


  -asdir      Specifies that FROMPATH is a directory.  Provided for times when
              FROMPATH does not exist (and hence the -d test will fail).



Return the path to PATH from FROMPATH.


B<Example: This example>:

    relpath( "/home/docs", "/home/docs/install", -asdir );

B<matches>:

    ..

B<Example: This example>:

    relpath( "/home/docs", "/home/docs/README.txt" );

B<matches>:

    .

B<Example: This example>:

    relpath( "/home/src", "/home/docs/install", -asdir );

B<matches>:

    ../../src

B<Example: This example>:

    relpath( "/home/docs/README.txt", "/home/docs", -asdir );

B<matches>:

    README.txt

=back

=over 4

=item safestr

B<>

 Usage: safestr STRING

Pack nogood characters into good ones.  Good characters are letters, numbers,
and the underscore.


B<Example: This example>:

    safestr( 'Dogs (Waters, Gilmour) 17:06' );

B<matches>:

    Dogs_20__28_Waters_2c__20_Gilmour_29__20_17_3a_06

=back

=over 4

=item siteurl

B<>

 Usage: siteurl

Return the target website url.


=back

=over 4

=item trimcss

B<>

 Usage: trimcss

Remove empty css properties

=back

=over 4

=item trimhtmlstyle

B<>

 Usage: trimhtmlstyle

Remove empty style declarations

=back

=over 4

=item unpackcgi

B<>

 Usage: unpackcgi QUERY

Unpack cgi characters into a kv hashref

=back

=head1 INTERNAL

=begin html

<table><tr><td>
<a class="methlink" href="#item__runtweaks">_runTweaks</a>

</td></tr></table>

=end html


=over 4

=item _runTweaks

B<Standard tweaks>




Tweaks allow modification to variable values without modifying the original.



No spaces are allowed in the tweak!


Implemented tweaks:


  tr///               # transliterates search chars with replacement chars
  lc                  # lower case
  uc                  # upper case
  lcfirst             # lower case first letter
  ucfirst             # upper case first letter
  x=                  # repeat the value so many times
  nbspstr             # replace spaces with non-breaking ones
  html                # replace '<' and '>' with '&lt;' and '&gt;'
  jsstr               # escape quotes and end-of-lines with a backslash
  num                 # number (will use zero '0' if empty)
  dt(opts)            # datetime with options (see datetime).

  Hub::dhms(opts)     # day/hour/min/sec with options (see dhms).



  eq                  # equal
  ne                  # not equal
  gt                  # greater than
  lt                  # less than
  if                  # is greater than zero (or non-empty string)


  -                   # minus
  +                   # plus
  *                   # multiply
  /                   # divide
  %                   # mod


  darker(num)         # makes a color darker (default num=0xA)
  lighter(num)        # makes a color lighter (default num=0xA)
  rotate_base         # rotates bases (red -> green, green -> blue, blue -> red)
  inverse             # invert color (like red becomes cyan)


Examples:


               # if v is 'HELLO', it becomes 'hello'
              # if v is '.', it becomes '.....'
          # the value for 'v' is printed when 1 is equal to 2
          # the value for 'v' is printed when 1 isn't equal to 2
            # the value for 'v' is printed when it is equal to 2
       # if v is 's' and c is greater than one, 's' is printed


Tweaks can be chained together, for example:


       # if v is "HELLO", it becomes 'Hello'
    # if v is "hello" and c is greater than 1, it becomes 'HELLO'



=back

=head1 AUTHOR



Ryan Gies

=head1 COPYRIGHT



Copyright (c) 2006 Livesite Networks, LLC.  All rights reserved.

Copyright (c) 2000-2005 Ryan Gies.  All rights reserved.

=head1 UPDATED

This file created by  on  at 

=cut
