README

NAME
    File::LsColor - Colorize input filenames just like ls does

SYNOPSIS
        use File::LsColor qw(:all);
        # Is equal to:
        use File::LsColor qw(
          ls_color
          ls_color_custom
          ls_color_default
          ls_color_internal
          get_ls_colors
          can_ls_color
          ls_color_lookup
          parse_ls_colors
        );


        my @files = glob("$ENV{HOME}/*");

        print "$_\n" for ls_color @files;

        # or specify own pattern

        @files = ls_color_custom('*.pl=38;5;196;1:*.pm=38;5;220', @files);

        # or use the internal mappings

        @files = ls_color_internal(@files);

        # or use the defaults (only ANSI colors)

        @files = ls_color_default(@files);


        # returns a hashref with all defined filetypes and their attributes
        my $ls_colors = get_ls_colors();

        # what's the defined attributes for directories?

        my $dir_color = can_ls_color('di');

        # can we apply attributes to this filetype?
        my $filetype = shift;
        printf "%s can be colored.\n" if can_ls_color($filetype);

        # apply terminal color even if we can't use LS_COLORS to do so.
        my $file_with_extension = 'foobar.flac';
        printf "%s looks nice.\n", can_ls_color($file_with_extension)
          ? ls_color($file_with_extension)
          : Term::ExtendedColor::fg(32, $file_with_extension);

DESCRIPTION
    This module provides functionality for using the LS_COLORS variable for
    colorizing output in a way that's immediately recognized.

    Say that you have a list of filenames that's the result of some complex
    operation, and you wish to present the result to the user.

    If said files have an extension and that extension is present in the
    users LS_COLORS variable, they will be colored just like they would have
    been if the filenames were output from ls(1) or tree(1).

EXPORTS
    None by default.

FUNCTIONS
  ls_color()
    Arguments: @files | \@files

    Returns: @files | @files

    Returns a list of filenames colored as specified by the environment
    "LS_COLORS" variable. If the "LS_COLORS" variable is not set, throws an
    exception. In this case, "ls_color_internal()" can be used.

    In scalar context a string joined by '' is returned.

  ls_color_default()
    The same thing as "ls_color()", but uses the default LS_COLORS values
    from GNU ls. Those are only ANSI colors.

  ls_color_internal()
    The same as "ls_color()", with one minor difference; Instead of using
    the LS_COLORS variable from the environment, an internal specification
    is used. This specification contains about 250 extensions as of this
    writing.

  ls_color_custom()
    The first argument to "ls_color_custom()" should be a valid LS_COLORS
    definition, like so:

      ls_color_custom("*.pl=38;5;196:*.pm=38;5;197;1", @perl_files);

  get_ls_colors()
    Returns a hash reference where a key is the extension and its value is
    the attributes attached to it.

  can_ls_color()
    Arguments: $file Returns: $attributes

    Given a valid name, returns the defined attributes associated with it.
    Else, returns undef.

  ls_color_lookup()
    The same as can_ls_color(), exportable because of compatibility reasons.

  parse_ls_colors()
  Arguments: $string
  Returns:   \%hash
    Returns a hashref with extension => attribute mappings, i.e:

        '7z'  => '01;31',
        'aac' => '00;36',
        'ace' => '01;31',
        'anx' => '01;35',
        'arj' => '01;31',

AUTHOR
      Magnus Woldrich
      CPAN ID: WOLDRICH
      m@japh.se
      http://japh.se
      https://github.com/trapd00r

REPORTING BUGS
    Report bugs on <https://github.com/trapd00r/File-LsColor> or to
    m@japh.se

CONTRIBUTORS
    None required yet.

COPYRIGHT
    Copyright 2011, 2018, 2019- the File::LsColor "AUTHOR" and
    "CONTRIBUTORS" as listed above.

LICENSE
    This library is free software; you may redistribute it and/or modify it
    under the same terms as Perl itself.