EQ2EMu/EQ2/source/depends/boost_1_72_0/libs/process/doc/design.qbk

[section:design Design Rationale]
[section Scope]
This library is meant to give an wrapper around the different OS-specific methods
to launch processes. Its aim is to provide all functionality that is available on 
those systems and allow the user to do all related things, which require using the OS APIs.

[*This library does not try to provide a full library for everything process related] 
In many discussions the proposal was made to build boost.process into a DSEL [footnote Domain Specific Embedded Language] of some sort. 
This is not the goal, it rather provides the facilities to build such a DSEL-Library on top of it. 
Therefore the library also does [*not] force any particular use (such as only asynchronous communication) on its user. 
It rather could be integrated with such a library.  

[endsect] 
[section Interface Style]

Boost.Process does use a very particular style when constructing a process.
This is because a process holds many properties, which are not members of the actual child class. 
Those properties are in many cases not accessible by the father process, for example when using environments. 
Here the child process can modify its own environment, but there is no way for the father process to know.
That means, that a child process has properties that cannot be accessed in C++.

This now leads to the two styles supported and mixed by this library. Overloading and properties. 
Consider that you may want to launch a process passing a number of arguments. This is supported in both styles, and would look like this:

```
system("gcc", "--version"); //overloading
system("gcc", args={"--version"}); //property style.
```

Both styles can also be mixed in some cases.

```
system("gcc", "-c", args+={"main.cpp"});
```

In the following section the avaible styles will be described. Note that the
overload style is implemented via type traits, so the types will be listed. 

[caution There is no guarantee in which order the arguments will be applied! 
There is however a guarantee for arguments belonging together, i.e. the string 
argument and the args property will be evaluated in the order given.]

[endsect]
[section:arg_cmd_style Arguments/Command Style]

When passing arguments to the process, two styles are provided, the cmd-style and the exe-/args-style. 

The cmd style will interpret the string as a sequence of the exe and arguments and parse them as such, while the exe-/args-style will
interpret each string as an argument.

[table:id Cmd vs Exe/Args
    [[String]              [Cmd]       [Exe/Args]]
    [["gcc --version"]     [{"gcc", "--version"}]     [{"\\"gcc --version\\""}]]
] 

When using the overloading variant, a single string will result in a cmd interpretation, 
several strings will yield a exe-args interpretation. Both version can be set explicitly:

```
system("grep -c false /etc/passwd"); //cmd style
system("grep", "-c", "false", "/etc/passwd"); //exe-/args-

system(cmd="grep -c false /etc/passwd"); //cmd style
system(exe="grep", args={"-c", "false", "/etc/passwd"}); //exe-/args-
```

[note If a '"' sign is used in the argument style, it will be passed as part of the argument.
If the same effect it wanted with the cmd syntax, it ought to be escaped, i.e. '\\\"'. ]
[note The `PATH` variable will automatically be searched in the command style, 
but the one of the launching process, not the one passed to the child process.]
[endsect]

[section:plat_ext Extensions]

The simplest form to extend functionality is to provide another handler, which 
will be called on the respective events on process launching. The names are:

*`boost::process::on_setup`
*`boost::process::on_error`
*`boost::process::on_success`


As an example:

```
child c("ls", on_setup([](){cout << "On Setup" << endl;});
```


[note On posix all those callbacks will be handled by this process, not the created one. 
This is different for the posix extensions, which can be executed on the forked process.]
[endsect]

[endsect]