EnvExpander.h

Go to the documentation of this file.

/**
 * This file is part of ArmarX.
 *
 * ArmarX is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation.
 *
 * ArmarX is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 *
 * @author     Fabian Reister ( fabian dot reister at kit dot edu )
 * @date       2025
 * @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
 *             GNU General Public License
 */
 
#pragma once
 
 
#include <cstdint>
#include <cstdlib>
#include <string>
#include <tuple>
#include <vector>
 
#include <boost/process/environment.hpp>
 
namespace armarx::core::system
{
 
 
    class EnvExpander
    {
    public:
    
        /**
         * Construct an EnvExpander initialized with the current process
         * environment. The instance keeps a working copy of the environment
         * (stored in `env_`) which `apply()` will update when assignments are
         * applied. This allows expansions to optionally see earlier changes.
         */
        EnvExpander();
 
        /**
         * Parse and apply the comma-separated assignment list to the internal
         * environment `env_` and to the process environment via `setenv`.
         *
         * The input format is a comma-separated list of assignments. Each
         * assignment may be a replace (NAME=val), append (NAME+=val) or
         * prepend (NAME=+val). Whitespace around entries is ignored. Values
         * may include environment variable references (e.g. $HOME or ${HOME}),
         * which will be expanded before applying the assignment.
         *
         * Current implementation notes: `apply` uses `expand` to expand the
         * RHS values and then applies the parsed operations. The working copy
         * `env_` is updated so later calls can observe previous changes.
         */
        void apply(const std::string& input, bool expandExisting = true);
 
        /**
         * Return the expanded form of the comma-separated assignment list
         * without modifying the process environment. This mirrors the
         * expansions performed by `apply`.
         *
         * Special behavior: append and prepend operations are returned as
         * explicit replacement assignments combining the existing environment
         * value and the expanded RHS. For example, if the current value of
         * PATH is "/usr/bin" and the input contains "PATH+=/opt/bin", this
         * method returns "PATH=/usr/bin:/opt/bin" (or "PATH=/opt/bin" if
         * PATH was not previously set).
         */
        static std::string expand(const std::string& input);
 
        enum class Operation : std::uint8_t
        {
            Replace,
            Append,
            Prepend
        };
 
        boost::process::environment env_;
 
        // ---------------------------
        // Parsing helpers
        // ---------------------------
 
        static std::vector<std::string> splitAssignments(const std::string& input);
 
        static std::tuple<std::string, Operation, std::string>
        splitOperation(const std::string& assignment);
 
        // ---------------------------
        // Variable expansion with warnings
        // ---------------------------
 
        static std::string expandVariables(const std::string& value);
 
        // ---------------------------
        // Apply update to environment
        // ---------------------------
 
        void applyOperation(const std::string& name, Operation op, const std::string& val);
    };
 
 
} // namespace armarx::core::system