NAME

Nile::File - Files and folders manager.

SYNOPSIS

    # get app context
    $app = $self->app;

    # get the file content as a single string.
    $content = $app->file->get($file);

    # get the file content as an array of lines.
    @lines = $app->file->get($file);
    
    # get list of specific files in a folder
    @files = $app->file->files("c:/apache/htdocs/nile/", "*.pm, *.cgi");
        
    # get list of specific files in a folder recursively
    # files_tree($dir, $match, $relative, $depth)
    @files = $app->file->files_tree("c:/apache/htdocs/nile/", "*.pm, *.cgi");

    # get list of sub folders in a folder
    #folders($dir, $match, $relative)
    @folders = $self->file->folders("c:/apache/htdocs/nile/", "", 1);
    
    # get list of sub folders in a folder recursively
    #folders_tree($dir, $match, $relative, $depth)
    @folders = $self->file->folders_tree("c:/apache/htdocs/nile/", "", 1);

DESCRIPTION

The file object provides tools for reading files, folders, and most of the functions in the modules File::Spec and File::Basename.

to get file content as single string or array of strings:

    $content = $app->file->get($file);
    @lines = $app->file->get($file);

supports options same as File::Slurp.

To get list of files in a specific folder:

    #files($dir, $match, $relative)
    @files = $app->file->files("c:/apache/htdocs/nile/", "*.pm, *.cgi");
    
    #files_tree($dir, $match, $relative, $depth)
    @files = $app->file->files_tree("c:/apache/htdocs/nile/", "*.pm, *.cgi");

    #folders($dir, $match, $relative)
    @folders = $self->file->folders("c:/apache/htdocs/nile/", "", 1);

    #folders_tree($dir, $match, $relative, $depth)
    @folders = $self->file->folders_tree("c:/apache/htdocs/nile/", "", 1);

Nile::File - Files and folders manager.

get()

    # file($file, $options)
    $content = $app->file->get("/path/file.txt");
    @lines = $app->file->get("/path/file.txt");

    # read file from URL, file($url)
    $content = $app->file->get("http://www.domain.com/path/page.html");

    $bin = $app->file->get("/path/file.bin", binmode => ':raw');
    $utf = $app->file->get("/path/file.txt", binmode => ':utf8');

Reads file contents into a single variable or an array. It also supports reading files from URLs. If the file name passed to the method is a valid URL, it will connect and return the URL content. This method is a wrapper around File::Slurp read_file method when used for reading files.

put()

    # put($file, $options)
    $app->file->put($file, @data);
    $app->file->put($file, {binmode => ':raw'}, $buffer);

    $app->file->put($file, \$buffer);
    # the same as
    $app->file->put($file, $buffer);

    $app->file->put($file, \@lines) ;
    # the same as
    $app->file->put($file, @lines) ;

Writes contents into a file. This method is a wrapper around File::Slurp write_file method. The first argument is the filename. The second argument is an optional hash reference and it contains key/values that can modify the behavior of write_file. The rest of the argument list is the data to be written to the file.

File::Spec supported methods

    $app->file->canonpath;
    $app->file->catdir
    $app->file->catfile
    $app->file->curdir
    $app->file->rootdir
    $app->file->updir
    $app->file->no_upwards
    $app->file->file_name_is_absolute
    $app->file->path
    $app->file->devnull
    $app->file->tmpdir
    $app->file->splitpath
    $app->file->splitdir
    $app->file->catpath
    $app->file->abs2rel
    $app->file->rel2abs
    $app->file->case_tolerant

Wrapper methods around File::Spec functions.

files()

    # files($dir, $match, $relative)
    @files = $app->file->files("c:/apache/htdocs/nile/", "*.pm, *.cgi");

Returns a list of files in a specific folder. The first argument is the path, the second argument is the filename match if not set will match all files, the third argument is the relative flag, if set will include the relative path of the files.

files_tree()

    # files_tree($dir, $match, $relative, $depth)
    @files = $app->file->files_tree("c:/apache/htdocs/nile/", "*.pm, *.cgi");

Returns a list of files in a specific folder. The first argument is the path, the second argument is the filename match if not set will match all files, the third argument is the relative flag, if set will include the relative path of the files.

folders()

    # get list of sub folders in a folder
    # folders($dir, $match, $relative)
    @folders = $self->file->folders("c:/apache/htdocs/nile/", "", 1);
    
    # get list of sub folders in a folder recursively
    #folders_tree($dir, $match, $relative, $depth)
    @folders = $self->file->$folders_tree("c:/apache/htdocs/nile/", "", 1);

Returns a list of sub folders in a folder.

folders_tree()

    # get list of sub folders in a folder recursively
    #folders_tree($dir, $match, $relative, $depth)
    @folders = $self->file->folders_tree("c:/apache/htdocs/nile/", "", 1);

Returns list of sub folders in a folder recursively.

os()

    my $os = $app->file->os;

Returns the name of the operating system.

ds()

    my $ds = $app->file->ds;

Returns the directory separator of the operating system.

fileparse()

    my ($filename, $dirs, $suffix) = $app->file->fileparse($path);
    my ($filename, $dirs, $suffix) = $app->file->fileparse($path, @suffixes);
    my $filename = $app->file->fileparse($path, @suffixes);

Splits a file path into its $dirs, $filename and (optionally) the filename $suffix. See File::Basename

basename()

    my $filename  = $app->file->basename($path);
    my $filename  = $app->file->basename($path, @suffixes);

Returns the last level of a filepath even if the last level is clearly directory. In effect, it is acting like pop() for paths. See File::Basename

dirname()

    my $ds = $app->file->dirname();

Returns the directory separator of the operating system. See File::Basename

path_info()

    my ($name, $dir, $ext, $name_ext) = $app->file->path_info($path);

Splits a file path into its $dir, $name, filename $suffix, and name with suffix.

open()

    $fh = $app->file->open($file);
    $fh = $app->file->open($mode, $file);
    $fh = $app->file->open($mode, $file, $charset);
    $fh = $app->file->open(">", $file, "utf8");

Open file and returns a filehandle.

tempfile()

    #$template = "tmpdirXXXXXX";
    ($fh, $filename) = $app->file->tempfile($template);
    ($fh, $filename) = $app->file->tempfile($template, DIR => $dir);
    ($fh, $filename) = $app->file->tempfile($template, SUFFIX => '.dat');
    ($fh, $filename) = $app->file->tempfile($template, TMPDIR => 1 );

Return name and handle of a temporary file safely. This is a wrapper for the File::Temp tempfile function.

tempdir()

    $tmpdir = $app->file->tempdir($template);
    $tmpdir = $app->file->tempdir($template, DIR => $dir);
    $tmpdir = $app->file->tempdir($template, TMPDIR => 1 );

Return name of a temporary directory safely. This is a wrapper for the File::Temp tempdir function.

gzip()

    $file = "file.txt";
    $app->file->gzip($file);
    # creates file.txt.gz
    
    $input = "file.txt";
    $output = "file.gz";
    $app->file->gzip($input, $output);
    # creates file.gz
    
    # rename file in gzip header to file1.txt
    $app->file->gzip($input, $output, "file1.txt");

Compress and create gzip files from input files.

gunzip()

    $file = "file.txt";
    $app->file->gzip($file);
    # creates file.txt.gz
    
    $input = "file.txt";
    $output = "file.gz";
    $app->file->gzip($input, $output);
    # creates file.gz
    
    # rename file in gzip header to file1.txt
    $app->file->gzip($input, $output, "file1.txt");

Extract gzip files.

zip()

    $file = "file.txt";
    $app->file->zip($file);
    # creates file.zip
    
    $input = "file.txt";
    $output = "file1.zip";
    $app->file->gzip($input, $output);
    # creates file1.zip
    
    # rename file in zip header to file1.txt
    $app->file->zip($input, $output, "file1.txt");

Compress and create zip files from input files.

unzip()

    $file = "/path/file.zip";
    $app->file->unzip($file);
    # extracts files to /path/
    
    $app->file->unzip($file, $dest);
    # extracts files to $dest
    

Extract zip files.

view()

    my $file = $app->file->view($view, $theme);

    # get view file name in the current theme
    my $file = $app->file->view("home");
    # /app/theme/default/view/home.html

    my $file = $app->file->view("home", "Arabic");
    # /app/theme/Arabic/view/home.html

Returns the full file path for a view name.

lang()

    my $file = $app->file->lang($filename, $lang);

    # get language file pth in the current language
    my $file = $app->file->lang("general");
    # /app/lang/en-US/general.xml

    my $file = $app->file->lang("general", "ar");
    # /app/lang/ar/general.xml

Returns the full file path for a language file name.

Bugs

This project is available on github at https://github.com/mewsoft/Nile.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Nile.

SOURCE

Source repository is at https://github.com/mewsoft/Nile.

SEE ALSO

See Nile for details about the complete framework.

AUTHOR

Ahmed Amin Elsheshtawy, احمد امين الششتاوى <mewsoft@cpan.org> Website: http://www.mewsoft.com

COPYRIGHT AND LICENSE

Copyright (C) 2014-2015 by Dr. Ahmed Amin Elsheshtawy احمد امين الششتاوى mewsoft@cpan.org, support@mewsoft.com, https://github.com/mewsoft/Nile, http://www.mewsoft.com

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