SYNOPSIS
    non-object-oriented (Perl 5.22 and later):

      use Sys::OsRelease;

      Sys::OsRelease->init();
      my $id = Sys::OsRelease->id();
      my $id_like = Sys::OsRelease->id_like();

    object-oriented (Perl 5.22 and later):

      use Sys::OsRelease;

      my $osrelease = Sys::OsRelease->instance();
      my $id = $osrelease->id();
      my $id_like = $osrelease->id_like();

    non-object-oriented (Perl up to 5.20):

      use Sys::OsRelease::Lite;

      Sys::OsRelease::Lite->init();
      my $id = Sys::OsRelease::Lite->id();
      my $id_like = Sys::OsRelease::Lite->id_like();

    object-oriented (Perl up to 5.20):

      use Sys::OsRelease::Lite;

      my $osrelease = Sys::OsRelease::Lite->instance();
      my $id = $osrelease->id();
      my $id_like = $osrelease->id_like();

DESCRIPTION
    Sys::OsRelease is a helper library to read the /etc/os-release file, as
    defined by FreeDesktop.Org. The os-release file is used to define an
    operating system environment. It has been in widespread use among Linux
    distributions since 2017 and BSD variants since 2020. It was started on
    Linux systems which use the systemd software, but then spread to other
    Linux, BSD and Unix-based systems. Its purpose is to identify the system
    to any software which needs to know. It differentiates between
    Unix-based operating systems and even between Linux distributions.

    Sys::OsRelease is implemented with a singleton model, meaning there is
    only one instance of the class. Instead of instantiating an object with
    new(), the instance() class method returns the one and only instance.
    The first time it's called, it instantiates it. On following calls, it
    returns a reference to the singleton instance.

    This module maintains minimal prerequisites, and only those which are
    usually included with Perl. (Suggestions of new features and code will
    have to follow this rule.) That is intended to be acceptable for
    establishing system or container environments which contain Perl
    programs. It can also be used for installing or configuring software
    that needs to know about the system environment.

  The os-release Standard
    FreeDesktop.Org's os-release standard is at
    <https://www.freedesktop.org/software/systemd/man/os-release.html>.

    Current attributes recognized by Sys::OsRelease are: NAME ID ID_LIKE
    PRETTY_NAME CPE_NAME VARIANT VARIANT_ID VERSION VERSION_ID
    VERSION_CODENAME BUILD_ID IMAGE_ID IMAGE_VERSION RELEASE_TYPE HOME_URL
    DOCUMENTATION_URL SUPPORT_URL BUG_REPORT_URL PRIVACY_POLICY_URL
    SUPPORT_END LOGO ANSI_COLOR ANSI_COLOR_REVERSE VENDOR_NAME VENDOR_URL
    EXPERIMENT EXPERIMENT_URL DEFAULT_HOSTNAME ARCHITECTURE SYSEXT_LEVEL
    CONFEXT_LEVEL SYSEXT_SCOPE CONFEXT_SCOPE PORTABLE_PREFIXES
    PORTABLE_SCOPE

    If other attributes are found in the os-release file, they will be
    accepted. Folded to lower case, the attribute names are used as keys in
    an internal hash structure.

  Sys::OsRelease or Sys::OsRelease::Lite?
    Due to restrictions of the Dist::Zilla build environment and its
    dependencies, Sys::OsRelease 0.4.0 had to follow an increase in the
    minimum Perl version from 5.10 to 5.22. For systems with Perl older than
    5.22, see below about Sys::OsRelease::Lite which repackages
    Sys::OsRelease without the Dist::Zilla version limitation in order to
    retain support for legacy Perl installations.

    Sys::OsRelease::Lite is the same module in all but name. A release
    script filters the source code of Sys::OsRelease to change its name.
    Then Sys::OsRelease::Lite is built with ExtUtils::MakeMaker to maintain
    compatibility back to Perl 5.10. The two are released in parallel with
    the same version number.

METHODS
  Class methods
    *Sys::OsRelease* uses a singleton model. So there is only one instance.
    Class methods manage the singleton instance, or import those methods to
    another cooperating class' namespace.

    Class methods must be called using the class name, like
    "Sys::OsRelease-"instance()> .

    init([key => value, ...])
     initializes the singleton instance without returning a value.
     Parameters are passed to the instance() method. This method is for
     cases where method calls will be via the class name, and the program
     doesn't need a reference to the instance.

     Under normal circumstances no parameters are needed. See instance() for
     possible parameters.

    new([key => value, ...])
     initializes the singleton instance and returns a reference to it.
     Parameters are passed to the instance() method. This is equivalent to
     using the instance() method, made available if new() sounds more
     comfortable.

     Under normal circumstances no parameters are needed. See instance() for
     possible parameters.

    instance([key => value, ...])
     initializes the singleton instance and returns a reference to it.

     Under normal circumstances no parameters are needed. Possible optional
     parameters are as follows:

     common_id
      supplies an arrayref to use as a list of additional common strings
      which should be recognized by the platform() method, if they occur in
      the ID_LIKE attribute in the os-release file. By default, "debian" and
      "fedora" are regonized by platform() as common names and it will
      return them instead of the system's ID attribute.

     search_path
      supplies an arrayref of strings with directories to use as the search
      path for the os-release file.

     file_name
      supplies a string with the basename of the file to look for the
      os-release file. Obviously the default file name is "os-release".
      Under normal circumstances there is no need to set this. Currently
      this is only used for testing, where suffixes are added for copies of
      various different systems' os-release files, to indicate which system
      they came from.

    defined_instance()
     returns true if the singleton instance is defined, false if it is not
     yet defined or has been cleared.

    clear_instance()
     removes the singleton instance of the class if it was defined. Under
     normal circumstances it is not necessary to call this since the class
     destructor will call it automatically. It is currently only used for
     testing, where it is necessary to clear the instance before loading a
     new one with different parameters.

     Since this class is based on the singleton model, there is only one
     instance. The instance(), new() and init() methods will only initialize
     the instance if it is not already initialized.

    import_singleton()
     The singleton-management methods *init*, *new*, *instance*,
     *defined_instance* and *clear_instance* can be imported by another
     class by using the import_singleton() method. That was done for
     Sys::OsPackage, to allow it to avoid copying those methods. But other
     classes with a similar need to minimize module dependencies which
     already use *Sys::OsRelease* can do this too. This helps maintain
     minimal prerequisites among modules working to set up Perl on
     containers or new systems.

  Instance methods
    Object methods, including auto-generated accessors described above,
    access the data from the singleton instance, either read from an
    os-release file or empty to indicate no os-release file was found on the
    system.

    Instance methods may be called either via the class name or a reference
    to the singleton instance. Each of these functions can determine whether
    they were called as a class or object method, and obtain the reference
    to the singleton instance if needed.

    platform()
     returns a string with the platform type. On systems with
     /etc/os-release (or os-release in any location from the standard) this
     is usually from the ID field. On systems that use the ID_LIKE field,
     systems that claim to be like "debian" or "fedora" (always in lower
     case) will return those names for the platform.

     The list of recognized common platforms can be modified by passing a
     "common_id" parameter to instance()/new() with an arrayref containing
     additional names to recognize as common. For example, "centos" is
     another possibility. It was not included in the default because CentOS
     is discontinued. Both Rocky Linux and Alma Linux have ID_LIKE fields of
     "rhel centos fedora", which will match "fedora" with the default
     setting, but could be configured via "common_id" to recognize "centos"
     since it's listed first in ID_LIKE.

     On systems where an os-release file doesn't exist or isn't found, the
     platform string will fall back to Perl's $Config{osname} setting for
     the system.

    osrelease_path()
     returns the path where os-release was found.

     The default search path is /etc, /usr/lib and /run/host as defined by
     the standard. The search path can be replaced by providing a
     "search_path" parameter to instance()/new() with an arrayref containing
     the directories to search. This feature is currently only used for
     testing purposes.

    found_attrs()
     returns a list of attribute names found in the os-release file, empty
     if os-release doesn't exist on the platform.

    has_attr(name)
     returns a boolean which is true if the attribute named by the string
     parameter exists in the os-release data for the current system. The
     attribute name is case insensitive.

    get(name)
     is a read-only accessor which returns the value of the os-release
     attribute named by the string parameter, or undef if it doesn't exist.

    has_config(name)
     returns a boolean which is true if Sys::OsRelease contains a
     configuration setting named by the string parameter.

    config(name, [value])
     is a read/write accessor for the configuration setting named by the
     string parameter "name". If no value parameter is provided, it returns
     the value of the parameter, or undef if it doesn't exist. If a value
     parameter is provided, it assigns that to the configuration setting and
     returns the same value.

  Auto-generated Accessor Methods
    For convenience, *Sys::OsRelease* generates read-only accessor methods
    for each of the standard attribute names, converted to lower case. For
    example, from the list above they are *name()*, *id()*, *id_like()*,
    etc. The auto-generated methods do not require any parameters, and
    ignore any if provided.

    Accessor methods are not generated for non-standard atttributes because
    it would be unreliable to try to call methods named for transient data
    that may or may not exist on a given platform, and for the possibility
    they could conflict with existing functions in the *Sys::OsRelease*
    namespace. Use the *found_attrs()*, *has_attr()* and *get()* methods to
    detect and access non-standard attributes.

    The current full list is at the os-release standard
    <https://www.freedesktop.org/software/systemd/man/latest/os-release.html
    > which includes descriptions of each attribute.

    name()
    id()
    id_like()
    pretty_name()
    cpe_name()
    variant()
    variant_id()
    version()
    version_id()
    version_codename()
    build_id()
    image_id()
    image_version()
    release_type()
    home_url()
    documentation_url()
    support_url()
    bug_report_url()
    privacy_policy_url()
    support_end()
    logo()
    ansi_color()
    ansi_color_reverse()
    vendor_name()
    vendor_url()
    experiment()
    experiment_url()
    default_hostname()
    architecture()
    sysext_level()
    confext_level()
    sysext_scope()
    confext_scope()
    portable_prefixes()
    portable_scope()

SEE ALSO
    FreeDesktop.Org's os-release standard:
    <https://www.freedesktop.org/software/systemd/man/os-release.html>

    GitHub repository for Sys::OsRelease:
    <https://github.com/ikluft/Sys-OsRelease>

    Related modules:

    Sys::OsPackage
     installs Perl modules, for example as dependencies of a script, via OS
     packages if available or otherwise via CPAN - uses Sys::OsRelease to
     determine OS type

    System::Info
     system information collected from multiple sources including system
     architecture, hardware, OS release data

    Sys::OsRelease::Lite
     This is a repackaging of Sys::OsRelease for older versions of Perl
     before 5.22. This was made because dependencies of Dist::Zilla forced
     it to bump its minimum Perl version to 5.22, which in turn forced
     Sys::OsRelease to follow. Sys::OsRelease::Lite provides Sys::OsRelease
     with the same source code, implemented with a filter on the source code
     changing the name of the module. The name change is just to prevent a
     namespace collision in CPAN, but is otherwise the same module. It is
     packaged with ExtUtils::MakeMaker to maintain availability back to Perl
     5.10. Compatibility was at the time still being maintained via CPAN
     testing back to 5.10. The use case was systems with RHEL 6 on Perl
     5.10.1 and RHEL 7 on Perl 5.16, or similar variations on enterprise or
     other infrastructure installations.

BUGS AND LIMITATIONS
    Please report bugs via GitHub at
    <https://github.com/ikluft/Sys-OsRelease/issues>

    Patches and enhancements may be submitted via a pull request at
    <https://github.com/ikluft/Sys-OsRelease/pulls>

LICENSE INFORMATION
    This module is distributed in the hope that it will be useful, but it is
    provided “as is” and without any express or implied warranties. For
    details, see the full text of the license in the file LICENSE or at
    <https://www.perlfoundation.org/artistic-license-20.html>.

