Page Menu
Home
Phabricator
Search
Configure Global Search
Log In
Files
F13179060
D13134.diff
No One
Temporary
Actions
View File
Edit File
Delete File
View Transforms
Subscribe
Mute Notifications
Award Token
Flag For Later
Size
10 KB
Referenced Files
None
Subscribers
None
D13134.diff
View Options
diff --git a/src/docs/article/command_execution.diviner b/src/docs/article/command_execution.diviner
--- a/src/docs/article/command_execution.diviner
+++ b/src/docs/article/command_execution.diviner
@@ -6,33 +6,33 @@
= Overview =
-PHP has several built-in mechanisms for executing system commands, like exec(),
-system(), and the backtick operator. However, these mechanisms often make it
-difficult to get all the information you need to handle error conditions,
-properly escaping commands is cumbersome, and they do not provide more advanced
-features like parallel execution and timeouts.
+PHP has several built-in mechanisms for executing system commands, like
+`exec()`, `system()`, and the backtick operator. However, these mechanisms
+often make it difficult to get all the information you need to handle error
+conditions, properly escaping commands is cumbersome, and they do not provide
+more advanced features like parallel execution and timeouts.
This document describes how to use the APIs in libphutil to execute commands
without encountering these problems.
-= Simple Commands: execx() and exec_manual() =
+= Simple Commands: `execx()` and `exec_manual()` =
-@{function:execx} and @{function:exec_manual} are replacements for exec(),
-system(), shell_exec(), and the backtick operator. The APIs look like this:
+@{function:execx} and @{function:exec_manual} are replacements for `exec()`,
+`system()`, `shell_exec()`, and the backtick operator. The APIs look like this:
list($stdout, $stderr) = execx('ls %s', $path);
list($err, $stdout, $stderr) = exec_manual('ls %s', $path);
-The major advantages of these methods over the exec() family are that you can
+The major advantages of these methods over the `exec()` family are that you can
easily check return codes, capture both stdout and stderr, and use a simple
-sprintf()-style formatting string to properly escape commands.
+`sprintf()`-style formatting string to properly escape commands.
@{function:execx} will throw a @{class:CommandException} if the command you
execute terminates with a nonzero exit code, while @{function:exec_manual}
returns the error code. If you use @{function:exec_manual}, you must manually
check the error code.
-= Advanced Commands: ExecFutures =
+= Advanced Commands: `ExecFutures` =
If you need more advanced features like parallel execution, command timeouts,
and asynchronous I/O, use @{class:ExecFuture}.
@@ -46,13 +46,13 @@
libphutil.
In addition to futures-based parallelism, you can set a timeout on an
-ExecFuture, which will kill the command if it takes longer than the specified
-number of seconds to execute:
+@{class:ExecFuture}, which will kill the command if it takes longer than the
+specified number of seconds to execute:
$future->setTimeout(30);
If the command runs longer than the timeout, the process will be killed and the
-future will resolve with a failure code (ExecFuture::TIMED_OUT_EXIT_CODE).
+future will resolve with a failure code (`ExecFuture::TIMED_OUT_EXIT_CODE`).
You can also write to the stdin of a process by using the
@{method:ExecFuture::write} method.
diff --git a/src/docs/article/core_quick_reference.diviner b/src/docs/article/core_quick_reference.diviner
--- a/src/docs/article/core_quick_reference.diviner
+++ b/src/docs/article/core_quick_reference.diviner
@@ -9,8 +9,8 @@
= Language Capabilities =
-Functions @{function:id}, @{function:head} and @{function:newv} address language
-grammar and implementation limitations.
+Functions @{function:id}, @{function:head} and @{function:newv} address
+language grammar and implementation limitations.
You can efficiently merge a vector of arrays with @{function:array_mergev}.
@@ -41,4 +41,5 @@
= Lunar Phases =
@{class:PhutilLunarPhase} calculates lunar phases, allowing you to harden an
-application against threats from werewolves, werebears, and other werecreatures.
+application against threats from werewolves, werebears, and other
+werecreatures.
diff --git a/src/docs/article/developing_xhpast.diviner b/src/docs/article/developing_xhpast.diviner
--- a/src/docs/article/developing_xhpast.diviner
+++ b/src/docs/article/developing_xhpast.diviner
@@ -5,13 +5,13 @@
= XHPAST Development Builds =
-To develop XHPAST, you need to install flex and bison. These install out of most
-package systems, with the caveat that you need flex 2.3.35 (which is NEWER than
-flex 2.3.4) and some package systems don't have it yet. If this is the case
-for you, you can grab the source here:
+To develop XHPAST, you need to install flex and bison. These install out of
+most package systems, with the caveat that you need flex 2.3.35 (which is NEWER
+than flex 2.3.4) and some package systems don't have it yet. If this is the
+case for you, you can grab the source here:
http://flex.sourceforge.net/
-When building, run "make scanner parser all" instead of "make" to build the
+When building, run `make scanner parser all` instead of `make` to build the
entire toolchain. By default the scanner and parser are not rebuild, to avoid
requiring normal users to install flex and bison.
diff --git a/src/docs/article/overview.diviner b/src/docs/article/overview.diviner
--- a/src/docs/article/overview.diviner
+++ b/src/docs/article/overview.diviner
@@ -35,23 +35,23 @@
Some of the major components of libphutil are:
- **Core Utilities**: a collection of useful functions like @{function:ipull}
- which simplify common data manipulation;
+ which simplify common data manipulation;
- **Filesystem**: classes like @{class:Filesystem} which provide a strict API
- for filesystem access and throw exceptions on failure, making it easier to
- write robust code which interacts with files;
+ for filesystem access and throw exceptions on failure, making it easier to
+ write robust code which interacts with files;
- **Command Execution**: libphutil provides a powerful system command
- primitive in @{class:ExecFuture} which makes it far easier to write
- command-line scripts which execute system commands
- (see @{article:Command Execution});
+ primitive in @{class:ExecFuture} which makes it far easier to write
+ command-line scripts which execute system commands
+ (see @{article:Command Execution});
- **@{function:xsprintf}**: allows you to define `sprintf()`-style functions
- which use custom conversions; and
- - **Library System**: an introspectable, inventoried system for organizing PHP
- code and managing dependencies, supported by static analysis.
+ which use custom conversions; and
+ - **Library System**: an introspectable, inventoried system for organizing
+ PHP code and managing dependencies, supported by static analysis.
= Extending and Contributing =
Information on extending and contributing to libphutil is available in the
Phabricator documentation:
- - to get started as a contributor, see @{article@phabcontrib:Contributor
+ - To get started as a contributor, see @{article@phabcontrib:Contributor
Introduction}.
diff --git a/src/docs/article/using_futures.diviner b/src/docs/article/using_futures.diviner
--- a/src/docs/article/using_futures.diviner
+++ b/src/docs/article/using_futures.diviner
@@ -1,5 +1,5 @@
@title Using Futures
-@group futures
+@group future
Overview of how futures work in libphutil.
@@ -29,7 +29,7 @@
You create a future by instantiating the relevant class and ask it to return the
result by calling `resolve()`:
- $gzip_future = new ExecFuture("gzip %s", $some_file);
+ $gzip_future = new ExecFuture('gzip %s', $some_file);
$gzip_future->start();
// The future is now executing in the background, and you can continue
@@ -75,8 +75,8 @@
@{class:FutureIterator} takes a list of futures and runs them in parallel,
**returning them in the order they resolve, NOT the original list order**. This
-allows your program to begin any followup computation as quickly as possible: if
-the slowest future in the list happens to be the first one, you can finish
+allows your program to begin any follow-up computation as quickly as possible:
+if the slowest future in the list happens to be the first one, you can finish
processing all the other futures while waiting for it.
You can also limit how many futures you want to run at once. For instance, to
diff --git a/src/docs/book/libphutil.book b/src/docs/book/libphutil.book
--- a/src/docs/book/libphutil.book
+++ b/src/docs/book/libphutil.book
@@ -1,39 +1,87 @@
{
- "name" : "libphutil",
- "title" : "libphutil Technical Documentation",
- "short" : "libphutil Tech Docs",
- "preface" : "Technical documentation for developers using libphutil.",
- "root" : "../../../",
- "uri.source" :
+ "name": "libphutil",
+ "title": "libphutil Technical Documentation",
+ "short": "libphutil Tech Docs",
+ "preface": "Technical documentation for developers using libphutil.",
+ "root": "../../../",
+ "uri.source":
"https://secure.phabricator.com/diffusion/PHU/browse/master/%f$%l",
- "rules" : {
- "(\\.php$)" : "DivinerPHPAtomizer",
- "(\\.diviner$)" : "DivinerArticleAtomizer"
+ "rules": {
+ "(\\.diviner$)": "DivinerArticleAtomizer",
+ "(\\.php$)": "DivinerPHPAtomizer"
},
- "exclude" : [
+ "exclude": [
"(^externals/)",
+ "(^resources/)",
"(^scripts/)",
- "(^support/)",
- "(^resources/)"
+ "(^support/)"
],
- "groups" : {
- "overview" : {
- "name" : "libphutil Overview"
+ "groups": {
+ "overview": {
+ "name": "libphutil Overview"
},
- "util" : {
- "name" : "Core Utilities",
- "include": "(^src/utils/)"
+ "aphront": {
+ "name": "Aphront",
+ "include": "(^src/aphront/)"
+ },
+ "auth": {
+ "name": "Authentication",
+ "include": "(^src/auth/)"
+ },
+ "conduit": {
+ "name": "Conduit",
+ "include": "(^src/conduit/)"
+ },
+ "console": {
+ "name": "Console",
+ "include": "(^src/console/)"
+ },
+ "daemon": {
+ "name": "Daemons",
+ "include": "(^src/daemon/)"
+ },
+ "error": {
+ "name": "Errors",
+ "include": "(^src/error/)"
+ },
+ "filesystem": {
+ "name": "Filesystem",
+ "include": "(^src/filesystem/)"
},
- "library" : {
+ "future": {
+ "name": "Futures",
+ "include": "(^src/future/)"
+ },
+ "internationalization": {
+ "name": "Internationalization",
+ "include": "(^src/internationalization/)"
+ },
+ "lexer": {
+ "name": "Lexers",
+ "include": "(^src/lexer/)"
+ },
+ "library": {
"name": "libphutil Library System",
"include": "(^src/moduleutils/)"
},
- "auth" : {
- "name": "Authentication",
- "include": "(^src/auth/)"
+ "parser": {
+ "name": "Parsers",
+ "include": "(^src/parser/)"
},
- "utf8" : {
+ "phage": {
+ "name": "Phage",
+ "include": "(^src/phage/)"
+ },
+ "remarkup": {
+ "name": "Remarkup",
+ "include": "(^src/markup/)"
+ },
+ "utf8": {
"name": "Handling Unicode and UTF-8"
+ },
+ "util": {
+ "name": "Core Utilities",
+ "include": "(^src/utils/)"
}
}
}
File Metadata
Details
Attached
Mime Type
text/plain
Expires
Thu, May 9, 8:54 PM (1 w, 6 d ago)
Storage Engine
blob
Storage Format
Encrypted (AES-256-CBC)
Storage Handle
6277324
Default Alt Text
D13134.diff (10 KB)
Attached To
Mode
D13134: Minor documentation improvements
Attached
Detach File
Event Timeline
Log In to Comment