7 files changed, 234 insertions, 0 deletions
diff --git a/docs/examples/fileserver.md b/docs/examples/fileserver.md
new file mode 100644
index 000000000..3ed9d90e7
--- /dev/null
+++ b/docs/examples/fileserver.md
@@ -0,0 +1,22 @@
+## File server
+
+This one serves a local directory in HTTP.
+
+```bash
+deno install --allow-net --allow-read https://deno.land/std/http/file_server.ts
+```
+
+Run it:
+
+```shell
+$ file_server .
+Downloading https://deno.land/std/http/file_server.ts...
+[...]
+HTTP server listening on http://0.0.0.0:4500/
+```
+
+And if you ever want to upgrade to the latest published version:
+
+```shell
+$ file_server --reload
+```
diff --git a/docs/examples/os_signals.md b/docs/examples/os_signals.md
new file mode 100644
index 000000000..5f66f3340
--- /dev/null
+++ b/docs/examples/os_signals.md
@@ -0,0 +1,35 @@
+## Handle OS Signals
+
+> This program makes use of an unstable Deno feature. Learn more about
+> [unstable features](../../runtime/unstable).
+
+[API Reference](https://deno.land/typedoc/index.html#signal)
+
+You can use `Deno.signal()` function for handling OS signals.
+
+```
+for await (const _ of Deno.signal(Deno.Signal.SIGINT)) {
+  console.log("interrupted!");
+}
+```
+
+`Deno.signal()` also works as a promise.
+
+```
+await Deno.signal(Deno.Singal.SIGINT);
+console.log("interrupted!");
+```
+
+If you want to stop watching the signal, you can use `dispose()` method of the
+signal object.
+
+```
+const sig = Deno.signal(Deno.Signal.SIGINT);
+setTimeout(() => { sig.dispose(); }, 5000);
+
+for await (const _ of sig) {
+  console.log("interrupted");
+}
+```
+
+The above for-await loop exits after 5 seconds when sig.dispose() is called.
diff --git a/docs/examples/permissions.md b/docs/examples/permissions.md
new file mode 100644
index 000000000..7d404d5fc
--- /dev/null
+++ b/docs/examples/permissions.md
@@ -0,0 +1,28 @@
+## Inspecting and revoking permissions
+
+> This program makes use of an unstable Deno feature. Learn more about
+> [unstable features](../../runtime/unstable).
+
+Sometimes a program may want to revoke previously granted permissions. When a
+program, at a later stage, needs those permissions, it will fail.
+
+```ts
+// lookup a permission
+const status = await Deno.permissions.query({ name: "write" });
+if (status.state !== "granted") {
+  throw new Error("need write permission");
+}
+
+const log = await Deno.open("request.log", "a+");
+
+// revoke some permissions
+await Deno.permissions.revoke({ name: "read" });
+await Deno.permissions.revoke({ name: "write" });
+
+// use the log file
+const encoder = new TextEncoder();
+await log.write(encoder.encode("hello\n"));
+
+// this will fail.
+await Deno.remove("request.log");
+```
diff --git a/docs/examples/subprocess.md b/docs/examples/subprocess.md
new file mode 100644
index 000000000..80d0cc7da
--- /dev/null
+++ b/docs/examples/subprocess.md
@@ -0,0 +1,74 @@
+## Run subprocess
+
+[API Reference](https://doc.deno.land/https/github.com/denoland/deno/releases/latest/download/lib.deno.d.ts#Deno.run)
+
+Example:
+
+```ts
+// create subprocess
+const p = Deno.run({
+  cmd: ["echo", "hello"],
+});
+
+// await its completion
+await p.status();
+```
+
+Run it:
+
+```shell
+$ deno run --allow-run ./subprocess_simple.ts
+hello
+```
+
+Here a function is assigned to `window.onload`. This function is called after
+the main script is loaded. This is the same as
+[onload](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload)
+of the browsers, and it can be used as the main entrypoint.
+
+By default when you use `Deno.run()` subprocess inherits `stdin`, `stdout` and
+`stderr` of parent process. If you want to communicate with started subprocess
+you can use `"piped"` option.
+
+```ts
+const fileNames = Deno.args;
+
+const p = Deno.run({
+  cmd: [
+    "deno",
+    "run",
+    "--allow-read",
+    "https://deno.land/std/examples/cat.ts",
+    ...fileNames,
+  ],
+  stdout: "piped",
+  stderr: "piped",
+});
+
+const { code } = await p.status();
+
+if (code === 0) {
+  const rawOutput = await p.output();
+  await Deno.stdout.write(rawOutput);
+} else {
+  const rawError = await p.stderrOutput();
+  const errorString = new TextDecoder().decode(rawError);
+  console.log(errorString);
+}
+
+Deno.exit(code);
+```
+
+When you run it:
+
+```shell
+$ deno run --allow-run ./subprocess.ts <somefile>
+[file content]
+
+$ deno run --allow-run ./subprocess.ts non_existent_file.md
+
+Uncaught NotFound: No such file or directory (os error 2)
+    at DenoError (deno/js/errors.ts:22:5)
+    at maybeError (deno/js/errors.ts:41:12)
+    at handleAsyncMsgFromRust (deno/js/dispatch.ts:27:17)
+```
diff --git a/docs/examples/tcp_echo.md b/docs/examples/tcp_echo.md
new file mode 100644
index 000000000..d7c2e9e72
--- /dev/null
+++ b/docs/examples/tcp_echo.md
@@ -0,0 +1,41 @@
+## TCP echo server
+
+This is an example of a simple server which accepts connections on port 8080,
+and returns to the client anything it sends.
+
+```ts
+const listener = Deno.listen({ port: 8080 });
+console.log("listening on 0.0.0.0:8080");
+for await (const conn of listener) {
+  Deno.copy(conn, conn);
+}
+```
+
+When this program is started, it throws PermissionDenied error.
+
+```shell
+$ deno run https://deno.land/std/examples/echo_server.ts
+error: Uncaught PermissionDenied: network access to "0.0.0.0:8080", run again with the --allow-net flag
+► $deno$/dispatch_json.ts:40:11
+    at DenoError ($deno$/errors.ts:20:5)
+    ...
+```
+
+For security reasons, Deno does not allow programs to access the network without
+explicit permission. To allow accessing the network, use a command-line flag:
+
+```shell
+$ deno run --allow-net https://deno.land/std/examples/echo_server.ts
+```
+
+To test it, try sending data to it with netcat:
+
+```shell
+$ nc localhost 8080
+hello world
+hello world
+```
+
+Like the `cat.ts` example, the `copy()` function here also does not make
+unnecessary memory copies. It receives a packet from the kernel and sends back,
+without further complexity.
diff --git a/docs/examples/testing_if_main.md b/docs/examples/testing_if_main.md
new file mode 100644
index 000000000..67be70339
--- /dev/null
+++ b/docs/examples/testing_if_main.md
@@ -0,0 +1,10 @@
+## Testing if current file is the main program
+
+To test if the current script has been executed as the main input to the program
+check `import.meta.main`.
+
+```ts
+if (import.meta.main) {
+  console.log("main");
+}
+```
diff --git a/docs/examples/unix_cat.md b/docs/examples/unix_cat.md
new file mode 100644
index 000000000..7534ef0d0
--- /dev/null
+++ b/docs/examples/unix_cat.md
@@ -0,0 +1,24 @@
+## An implementation of the unix "cat" program
+
+In this program each command-line argument is assumed to be a filename, the file
+is opened, and printed to stdout.
+
+```ts
+for (let i = 0; i < Deno.args.length; i++) {
+  let filename = Deno.args[i];
+  let file = await Deno.open(filename);
+  await Deno.copy(file, Deno.stdout);
+  file.close();
+}
+```
+
+The `copy()` function here actually makes no more than the necessary kernel ->
+userspace -> kernel copies. That is, the same memory from which data is read
+from the file, is written to stdout. This illustrates a general design goal for
+I/O streams in Deno.
+
+Try the program:
+
+```shell
+$ deno run --allow-read https://deno.land/std/examples/cat.ts /etc/passwd
+```