/ 
Venus-5.01
River stage two • 3 direct dependents • 56 total dependents
⭐ Starred 2 GitHub stars
/ Venus::Os

NAME

Venus::Os - OS Class

ABSTRACT

OS Class for Perl 5

SYNOPSIS

package main;

use Venus::Os;

my $os = Venus::Os->new;

# bless({...}, 'Venus::Os')

# my $name = $os->name;

# "linux"

DESCRIPTION

This package provides methods for determining the current operating system, as well as finding and executing files.

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

METHODS

This package provides the following methods:

call

call(string $name, string @args) (any)

The call method attempts to find the path to the program specified via "which" and dispatches to "mkcall" in Venus::Path and returns the result. Any exception throw is supressed and will return undefined if encountered.

Since 2.80

call example 1
# given: synopsis

package main;

my $app = $os->is_win ? 'perl.exe' : 'perl';

my $call = $os->call($app, '-V:osname');

# "osname='linux';"
call example 2
# given: synopsis

package main;

my $app = $os->is_win ? 'perl.exe' : 'perl';

my @call = $os->call($app, '-V:osname');

# ("osname='linux';", 0)
call example 3
# given: synopsis

package main;

my $call = $os->call('nowhere');

# undef
call example 4
# given: synopsis

package main;

my @call = $os->call($^X, '-V:osname');

# ("osname='linux';", 0)
call example 5
# given: synopsis

package main;

my @call = $os->call($^X, 't/data/sun');

# ("", 1)

find

find(string $name, string @paths) (arrayref)

The find method searches the paths provided for a file matching the name provided and returns all the files found as an arrayref. Returns a list in list context.

Since 2.80

find example 1
# given: synopsis

package main;

my $find = $os->find('cmd', 't/path/user/bin');

# ["t/path/user/bin/cmd"]
find example 2
# given: synopsis

package main;

my $find = $os->find('cmd', 't/path/user/bin', 't/path/usr/bin');

# ["t/path/user/bin/cmd", "t/path/usr/bin/cmd"]
find example 3
# given: synopsis

package main;

my $find = $os->find('zzz', 't/path/user/bin', 't/path/usr/bin');

# []

is_bsd

is_bsd() (boolean)

The is_bsd method returns true if the OS is either "freebsd" or "openbsd", and otherwise returns false.

Since 2.80

is_bsd example 1
# given: synopsis

package main;

# on linux

my $is_bsd = $os->is_bsd;

# false
is_bsd example 2
# given: synopsis

package main;

# on freebsd

my $is_bsd = $os->is_bsd;

# true
is_bsd example 3
# given: synopsis

package main;

# on openbsd

my $is_bsd = $os->is_bsd;

# true

is_cyg

is_cyg() (boolean)

The is_cyg method returns true if the OS is either "cygwin" or "msys", and otherwise returns false.

Since 2.80

is_cyg example 1
# given: synopsis

package main;

# on linux

my $is_cyg = $os->is_cyg;

# false
is_cyg example 2
# given: synopsis

package main;

# on cygwin

my $is_cyg = $os->is_cyg;

# true
is_cyg example 3
# given: synopsis

package main;

# on msys

my $is_cyg = $os->is_cyg;

# true

is_dos

is_dos() (boolean)

The is_dos method returns true if the OS is either "mswin32" or "dos" or "os2", and otherwise returns false.

Since 2.80

is_dos example 1
# given: synopsis

package main;

# on linux

my $is_dos = $os->is_dos;

# false
is_dos example 2
# given: synopsis

package main;

# on mswin32

my $is_dos = $os->is_dos;

# true
is_dos example 3
# given: synopsis

package main;

# on dos

my $is_dos = $os->is_dos;

# true
is_dos example 4
# given: synopsis

package main;

# on os2

my $is_dos = $os->is_dos;

# true

is_lin

is_lin() (boolean)

The is_lin method returns true if the OS is "linux", and otherwise returns false.

Since 2.80

is_lin example 1
# given: synopsis

package main;

# on linux

my $is_lin = $os->is_lin;

# true
is_lin example 2
# given: synopsis

package main;

# on macos

my $is_lin = $os->is_lin;

# false
is_lin example 3
# given: synopsis

package main;

# on mswin32

my $is_lin = $os->is_lin;

# false

is_mac

is_mac() (boolean)

The is_mac method returns true if the OS is either "macos" or "darwin", and otherwise returns false.

Since 2.80

is_mac example 1
# given: synopsis

package main;

# on linux

my $is_mac = $os->is_mac;

# false
is_mac example 2
# given: synopsis

package main;

# on macos

my $is_mac = $os->is_mac;

# true
is_mac example 3
# given: synopsis

package main;

# on darwin

my $is_mac = $os->is_mac;

# true

is_non

is_non() (boolean)

The is_non method returns true if the OS is not recognized, and if recognized returns false.

Since 2.80

is_non example 1
# given: synopsis

package main;

# on linux

my $is_non = $os->is_non;

# false
is_non example 2
# given: synopsis

package main;

# on aix

my $is_non = $os->is_non;

# true

is_sun

is_sun() (boolean)

The is_sun method returns true if the OS is either "solaris" or "sunos", and otherwise returns false.

Since 2.80

is_sun example 1
# given: synopsis

package main;

# on linux

my $is_sun = $os->is_sun;

# false
is_sun example 2
# given: synopsis

package main;

# on solaris

my $is_sun = $os->is_sun;

# true
is_sun example 3
# given: synopsis

package main;

# on sunos

my $is_sun = $os->is_sun;

# true

is_vms

is_vms() (boolean)

The is_vms method returns true if the OS is "vms", and otherwise returns false.

Since 2.80

is_vms example 1
# given: synopsis

package main;

# on linux

my $is_vms = $os->is_vms;

# false
is_vms example 2
# given: synopsis

package main;

# on vms

my $is_vms = $os->is_vms;

# true

is_win

is_win() (boolean)

The is_win method returns true if the OS is either "mswin32" or "dos" or "os2", and otherwise returns false.

Since 2.80

is_win example 1
# given: synopsis

package main;

# on linux

my $is_win = $os->is_win;

# false
is_win example 2
# given: synopsis

package main;

# on mswin32

my $is_win = $os->is_win;

# true
is_win example 3
# given: synopsis

package main;

# on dos

my $is_win = $os->is_win;

# true
is_win example 4
# given: synopsis

package main;

# on os2

my $is_win = $os->is_win;

# true

name

name() (string)

The name method returns the OS name.

Since 2.80

name example 1
# given: synopsis

package main;

# on linux

my $name = $os->name;

# "linux"

# same as $^O

new

new(any @args) (Venus::Os)

The new method constructs an instance of the package.

Since 4.15

new example 1
package main;

use Venus::Os;

my $new = Venus::Os->new;

# bless(..., "Venus::Os")

paths

paths() (arrayref)

The paths method returns the paths specified by the "PATH" environment variable as an arrayref of unique paths. Returns a list in list context.

Since 2.80

paths example 1
# given: synopsis

package main;

my $paths = $os->paths;

# [
#   "/root/local/bin",
#   "/root/bin",
#   "/usr/local/sbin",
#   "/usr/local/bin",
#   "/usr/sbin:/usr/bin",
# ]

quote

quote(string $data) (string)

The quote method accepts a string and returns the OS-specific quoted version of the string.

Since 2.91

quote example 1
# given: synopsis

package main;

# on linux

my $quote = $os->quote("hello \"world\"");

# "'hello \"world\"'"
quote example 2
# given: synopsis

package main;

# on linux

my $quote = $os->quote('hello \'world\'');

# "'hello '\\''world'\\'''"
quote example 3
# given: synopsis

package main;

# on mswin32

my $quote = $os->quote("hello \"world\"");

# "\"hello \\"world\\"\""
quote example 4
# given: synopsis

package main;

# on mswin32

my $quote = $os->quote('hello "world"');

# '"hello \"world\""'

read

read(any $from) (string)

The read method reads from a file, filehandle, or STDIN, and returns the data. To read from STDIN provide the string "STDIN". The method defaults to reading from STDIN.

Since 4.15

read example 1
# given: synopsis

package main;

# on linux

my $read = $os->read;

# from STDIN

# "..."
read example 2
# given: synopsis

package main;

# on linux

my $read = $os->read('STDIN');

# from STDIN

# "..."
read example 3
# given: synopsis

package main;

# on linux

my $read = $os->read('t/data/texts/iso-8859-1.txt');

# from file

# "Hello, world! This is ISO-8859-1."
read example 4
# given: synopsis

package main;

# on linux

open my $fh, '<', 't/data/texts/iso-8859-1.txt';

my $read = $os->read($fh);

# from filehandle

# "Hello, world! This is ISO-8859-1."
read example 5
# given: synopsis

package main;

# on linux

use IO::File;

my $fh = IO::File->new('t/data/texts/iso-8859-1.txt', 'r');

my $read = $os->read($fh);

# from filehandle

# "Hello, world! This is ISO-8859-1."
read example 6
# given: synopsis

package main;

# on linux

my $read = $os->read('t/data/texts/utf-16be.txt');

# from UTF-16BE encoded file

# "Hello, world! こんにちは世界！"
read example 7
# given: synopsis

package main;

# on linux

my $read = $os->read('t/data/texts/utf-16le.txt');

# from UTF-16LE encoded file

# "Hello, world! こんにちは世界！"
read example 8
# given: synopsis

package main;

# on linux

my $read = $os->read('t/data/texts/utf-32be.txt');

# from UTF-32BE encoded file

# "Hello, world! こんにちは世界！"
read example 9
# given: synopsis

package main;

# on linux

my $read = $os->read('t/data/texts/utf-32le.txt');

# from UTF-32LE encoded file

# "Hello, world! こんにちは世界！"
read example 10
# given: synopsis

package main;

# on linux

my $read = $os->read('t/data/texts/utf-8.txt');

# from UTF-8 encoded file

# "Hello, world! こんにちは世界！"
may raise Venus::Os::Error on.read.open.file
# given: synopsis;

$os->read('/path/to/nowhere');

# Error! (on.read.open.file)

syscall

syscall(any @data) (Venus::Os)

The syscall method executes the command and arguments provided, via "system" in perlfunc, and returns the invocant.

Since 4.15

syscall example 1
package main;

use Venus::Os;

my $os = Venus::Os->new;

$os->syscall($^X, '--help');

# bless(..., "Venus::Os")
syscall example 2
package main;

use Venus::Os;

my $os = Venus::Os->new;

$os->syscall('.help');

# Exception! (isa Venus::Os::Error) (see error_on_system_call)

type

type() (string)

The type method returns a string representing the "test" method, which identifies the OS, that would return true if called, based on the name of the OS.

Since 2.80

type example 1
# given: synopsis

package main;

# on linux

my $type = $os->type;

# "is_lin"
type example 2
# given: synopsis

package main;

# on macos

my $type = $os->type;

# "is_mac"
type example 3
# given: synopsis

package main;

# on mswin32

my $type = $os->type;

# "is_win"
type example 4
# given: synopsis

package main;

# on openbsd

my $type = $os->type;

# "is_bsd"
type example 5
# given: synopsis

package main;

# on cygwin

my $type = $os->type;

# "is_cyg"
type example 6
# given: synopsis

package main;

# on dos

my $type = $os->type;

# "is_win"
type example 7
# given: synopsis

package main;

# on solaris

my $type = $os->type;

# "is_sun"
type example 8
# given: synopsis

package main;

# on vms

my $type = $os->type;

# "is_vms"

where

where(string $file) (arrayref)

The where method searches the paths defined by the PATH environment variable for a file matching the name provided and returns all the files found as an arrayref. Returns a list in list context. This method doesn't check (or care) if the files found are actually executable.

Since 2.80

where example 1
# given: synopsis

package main;

my $where = $os->where('cmd');

# [
#   "t/path/user/local/bin/cmd",
#   "t/path/user/bin/cmd",
#   "t/path/usr/bin/cmd",
#   "t/path/usr/local/bin/cmd",
#   "t/path/usr/local/sbin/cmd",
#   "t/path/usr/sbin/cmd"
# ]
where example 2
# given: synopsis

package main;

my $where = $os->where('app1');

# [
#   "t/path/user/local/bin/app1",
#   "t/path/usr/bin/app1",
#   "t/path/usr/sbin/app1"
# ]
where example 3
# given: synopsis

package main;

my $where = $os->where('app2');

# [
#   "t/path/user/local/bin/app2",
#   "t/path/usr/bin/app2",
# ]
where example 4
# given: synopsis

package main;

my $where = $os->where('app3');

# [
#   "t/path/user/bin/app3",
#   "t/path/usr/sbin/app3"
# ]
where example 5
# given: synopsis

package main;

my $where = $os->where('app4');

# [
#   "t/path/user/local/bin/app4",
#   "t/path/usr/local/bin/app4",
#   "t/path/usr/local/sbin/app4",
# ]
where example 6
# given: synopsis

package main;

my $where = $os->where('app5');

# []

which

which(string $file) (string)

The which method returns the first match from the result of calling the "where" method with the arguments provided.

Since 2.80

which example 1
# given: synopsis

package main;

my $which = $os->which('cmd');

# "t/path/user/local/bin/cmd",
which example 2
# given: synopsis

package main;

my $which = $os->which('app1');

# "t/path/user/local/bin/app1"
which example 3
# given: synopsis

package main;

my $which = $os->which('app2');

# "t/path/user/local/bin/app2"
which example 4
# given: synopsis

package main;

my $which = $os->which('app3');

# "t/path/user/bin/app3"
which example 5
# given: synopsis

package main;

my $which = $os->which('app4');

# "t/path/user/local/bin/app4"
which example 6
# given: synopsis

package main;

my $which = $os->which('app5');

# undef

write

write(any $into, string $data, string $encoding) (Venus::Os)

The write method writes to a file, filehandle, STDOUT, or STDERR, and returns the invocant. To write to STDOUT provide the string "STDOUT". To write to STDERR provide the string "STDERR". The method defaults to writing to STDOUT.

Since 4.15

write example 1
# given: synopsis

package main;

# on linux

my $write = $os->write;

# to STDOUT

# ''

# bless(..., "Venus::Os")
write example 2
# given: synopsis

package main;

# on linux

my $write = $os->write(undef, '');

# to STDOUT

# ''

# bless(..., "Venus::Os")
write example 3
# given: synopsis

package main;

# on linux

my $write = $os->write('STDOUT');

# to STDOUT

# ''

# bless(..., "Venus::Os")
write example 4
# given: synopsis

package main;

# on linux

my $write = $os->write('STDOUT', '...');

# to STDOUT

# '...'

# bless(..., "Venus::Os")
write example 5
# given: synopsis

package main;

# on linux

my $write = $os->write('STDERR');

# to STDERR

# ''

# bless(..., "Venus::Os")
write example 6
# given: synopsis

package main;

# on linux

my $write = $os->write('STDERR', '...');

# to STDERR

# '...'

# bless(..., "Venus::Os")
write example 7
# given: synopsis

package main;

# on linux

my $file = 't/data/texts/iso-8859-1.txt';

my $write = $os->write($file, 'Hello, world! This is ISO-8859-1.');

# to file

# "Hello, world! This is ISO-8859-1."

# bless(..., "Venus::Os")
write example 8
# given: synopsis

package main;

# on linux

open my $fh, '<', 't/data/texts/iso-8859-1.txt';

my $write = $os->write($fh, 'Hello, world! This is ISO-8859-1.');

# to file

# "Hello, world! This is ISO-8859-1."

# bless(..., "Venus::Os")
write example 9
# given: synopsis

package main;

# on linux

use IO::File;

my $fh = IO::File->new('t/data/texts/iso-8859-1.txt', 'w');

my $write = $os->write($fh, 'Hello, world! This is ISO-8859-1.');

# to ISO-8859-1 encoded file

# "Hello, world! This is ISO-8859-1."

# bless(..., "Venus::Os")
write example 10
# given: synopsis

package main;

# on linux

my $file = 't/data/texts/utf-16be.txt';

my $write = $os->write($file, 'Hello, world! こんにちは世界！', 'UTF-16BE');

# to UTF-16BE encoded file

# "Hello, world! こんにちは世界！"

# bless(..., "Venus::Os")
write example 11
# given: synopsis

package main;

# on linux

my $file = 't/data/texts/utf-16le.txt';

my $write = $os->write($file, 'Hello, world! こんにちは世界！', 'UTF-16LE');

# to UTF-16LE encoded file

# "Hello, world! こんにちは世界！"

# bless(..., "Venus::Os")
write example 12
# given: synopsis

package main;

# on linux

my $file = 't/data/texts/utf-32be.txt';

my $write = $os->write($file, 'Hello, world! こんにちは世界！', 'UTF-32BE');

# to UTF-32BE encoded file

# "Hello, world! こんにちは世界！"

# bless(..., "Venus::Os")
write example 13
# given: synopsis

package main;

# on linux

my $file = 't/data/texts/utf-32le.txt';

my $write = $os->write($file, 'Hello, world! こんにちは世界！', 'UTF-32LE');

# to UTF-32LE encoded file

# "Hello, world! こんにちは世界！"

# bless(..., "Venus::Os")
write example 14
# given: synopsis

package main;

# on linux

my $file = 't/data/texts/utf-8.txt';

my $write = $os->write($file, 'Hello, world! こんにちは世界！', 'UTF-8');

# to UTF-8 encoded file

# "Hello, world! こんにちは世界！"

# bless(..., "Venus::Os")
may raise Venus::Os::Error on.write.open.file
# given: synopsis;

$os->write('/path/to/nowhere/file.txt', 'content');

# Error! (on.write.open.file)

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

Copyright (C) 2022, Awncorp, awncorp@cpan.org.

This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.