SBO::Lib::Readme(3)

NAME
SBO::Lib::Readme - Routines for interacting with a typical SBo README file.

SYNOPSIS
  use SBO::Lib::Readme qw/ get_readme_contents /;

  print get_readme_contents($sbo);

SUBROUTINES

  ask_opts
  my $opts = ask_opts($sbo, $location);

Users may be prompted to add options if saved options are not to be retrieved, provided that a "README" file associated with the script contains a variable assignment of the form "WORD=" (any case and accounts for quotes). The prompt appears if the SlackBuild accepts the variable name from the environment, the "README" shows an example of calling the SlackBuild with the variable or the phrase "to the script/SlackBuild" follows.

An option string is returned, if set.

  ask_previous
  my $opts = ask_previous($sbo);

ask_previous() takes the name of a SlackBuild and checks for saved options under the "/var/log/sbotools" directory. If options have been saved, the user is prompted for reuse. The saved options are returned if yes.

  ask_user_group
  my $bool = ask_user_group($cmds);

ask_user_group() takes the useradd(1) and groupadd(1) commands found in a "README" file and calls user_group_do_not_exist(); if at least one of the specified users or groups does not exist, it prompts for running the commands. If yes, the $cmds are returned, and "undef" otherwise.

  display_readmes
  display_readmes($sbo, $location);

display_readmes() checks for README files in $location. It displays "README" in all cases, and additional files in alphabetical order upon a single prompt.

  get_readme_contents
  my $contents = get_readme_contents($location);

get_readme_contents() opens the README file in $location and returns its contents. On error, it returns "undef".

  get_user_group
  my @cmds = @{ get_user_group($sbo, $location, $opts) };

get_user_group() searches the "SlackBuild" for $sbo in $location for useradd(1) and groupadd(1) commands, and returns them in an array reference. If no commands are found initially, it searches any "README*" files for them.

Some SlackBuilds allow the user to set user and group names and ID numbers with variables. Optionally pass an option string $opt if interactive or if an existing build options file is to be used.

  user_group_do_not_exist
  my @nonexistent = @{ user_group_do_not_exist(@cmds) };

user_group_do_not_exist() takes an array of sugested commands generated by get_user_group(), returning those that do not exist on the system in an array reference.

  user_prompt
  my ($proceed, $cmds, $opts) = user_prompt($sbo, $location, $get_only);

user_prompt() is the main point of access to the other commands in "Readme.pm". Except in the download-only case, it calls subroutines to find options and commands, and then prompts the user for installation. It returns the answer to the installation prompt (true for 'yes' and false for 'no'), the list of commands and the list of options.

  verify_user_group
  my @cmds = verify_user_group(@preliminary_cmds);

verify_user_group() checks for required options and sanitizes "useradd" and "groupadd" commands found in "SlackBuilds" and "README" files. An array with correct commands is returned.

EXIT CODES
Readme.pm subroutines can return the following exit codes:

  _ERR_USAGE         1   usage errors
  _ERR_SCRIPT        2   script or module bug
  _ERR_OPENFH        6   failure to open file handles
  _ERR_STDIN         16  reading keyboard input failed

SEE ALSO
SBO::Lib(3), SBO::Lib::Build(3), SBO::Lib::Download(3), SBO::Lib::Info(3), SBO::Lib::Pkgs(3), SBO::Lib::Repo(3), SBO::Lib::Solibs(3), SBO::Lib::Tree(3), SBO::Lib::Util(3), groupadd(1), useradd(1)

AUTHORS
SBO::Lib was originally written by Jacob Pipkin <jacob.pipkin@icloud.com> with contributions from Luke Williams <xocel@iquidus.org> and Andreas Guldstrand <andreas.guldstrand@gmail.com>.

MAINTAINER
SBO::Lib is maintained by K. Eugene Carlson <kvngncrlsn@gmail.com>.

LICENSE
The sbotools are licensed under the MIT License.

Copyright (C) 2012-2017, Jacob Pipkin, Luke Williams, Andreas Guldstrand.

Copyright (C) 2024-2026, K. Eugene Carlson.

Copyright (C) 2026, K. Eugene Carlson, Jacob Pipkin.