first init

Author: jiacai2050

Diff for: .gitattributes

@@ -0,0 +1,2 @@
+# https://github.com/github-linguist/linguist/blob/master/docs/overrides.md#documentation
+examples/* -linguist-documentation

Diff for: .github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - "**.zig"
+      - ".github/workflows/**"
+  push:
+    branches:
+      - main
+    paths:
+      - "**.zig"
+      - ".github/workflows/**"
+
+jobs:
+  examples:
+    timeout-minutes: 10
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: goto-bus-stop/setup-zig@v2
+        with:
+          version: 0.11.0
+      - name: Run examples(Unix)
+        if: matrix.os != 'windows-latest'
+        working-directory: examples
+        run: zig build run-all --summary all
+
+      - name: Run examples(Windows)
+        if: matrix.os == 'windows-latest'
+        working-directory: examples
+        run: zig.exe build run-all --summary all

Diff for: .github/workflows/pages.yml

@@ -0,0 +1,49 @@
+name: Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "**.md"
+      - ".github/workflows/**"
+  pull_request:
+    paths:
+      - "**.md"
+      - ".github/workflows/**"
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: '0.4.10'
+          # mdbook-version: 'latest'
+      - run: mdbook build
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book
+
+  lint:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v3
+        with:
+          node-version: "14"
+      - name: Prettier check
+        run: |
+          # if you encounter error, rerun the command below and commit the changes
+          make lint
+          git diff --exit-code

Diff for: .gitignore

@@ -0,0 +1,3 @@
+book
+zig-out/
+zig-cache/

Diff for: Makefile

@@ -0,0 +1,6 @@
+
+lint:
+	npx [email protected] --write .
+
+run-all:
+	cd examples && zig build run-all --summary all

Diff for: README.md

@@ -0,0 +1,3 @@
+# Zig Cookbook
+
+Zig cookbook is a collection of simple Zig programs that demonstrate good practices to accomplish common programming tasks.

Diff for: book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["ZigCC"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Zig cookbook"

Diff for: examples/.tool-versions

@@ -0,0 +1 @@
+zig 0.11.0

Diff for: examples/build.zig

@@ -0,0 +1,38 @@
+const std = @import("std");
+const fs = std.fs;
+const allocPrint = std.fmt.allocPrint;
+const print = std.debug.print;
+
+pub fn build(b: *std.Build) !void {
+    var run_all_step = b.step("run-all", "Run all examples");
+    try addExample(b, run_all_step);
+}
+
+fn addExample(b: *std.Build, run_all: *std.build.Step) !void {
+    const src_dir = try fs.cwd().openIterableDir("src", .{});
+
+    var it = src_dir.iterate();
+    while (try it.next()) |entry| {
+        switch (entry.kind) {
+            .file => {
+                const name = std.mem.trimRight(u8, entry.name, ".zig");
+                print("Add example {s}...", .{name});
+
+                const exe = b.addExecutable(.{
+                    .name = try allocPrint(b.allocator, "examples-{s}", .{name}),
+                    .root_source_file = .{ .path = try allocPrint(b.allocator, "src/{s}.zig", .{name}) },
+                    .target = .{},
+                    .optimize = .Debug,
+                });
+                const run_step = &b.addRunArtifact(exe).step;
+                b.step(try allocPrint(b.allocator, "run-{s}", .{name}), try allocPrint(
+                    b.allocator,
+                    "Run example {s}",
+                    .{name},
+                )).dependOn(run_step);
+                run_all.dependOn(run_step);
+            },
+            else => {},
+        }
+    }
+}

Diff for: examples/src/01-01.zig

@@ -0,0 +1,19 @@
+const std = @import("std");
+const fs = std.fs;
+const print = std.debug.print;
+
+pub fn main() !void {
+    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
+    defer arena.deinit();
+    const allocator = arena.allocator();
+
+    const file = try fs.cwd().openFile("build.zig", .{});
+    defer file.close();
+
+    const rdr = file.reader();
+    var line_no: usize = 0;
+    while (try rdr.readUntilDelimiterOrEofAlloc(allocator, '\n', 4096)) |line| {
+        line_no += 1;
+        print("{d}--{s}\n", .{ line_no, line });
+    }
+}

Diff for: examples/src/01-02.zig

@@ -0,0 +1,42 @@
+const std = @import("std");
+const fs = std.fs;
+const print = std.debug.print;
+
+const filename = "/tmp/zig-cookbook-01-02.txt";
+const file_size = 4096;
+
+pub fn main() !void {
+    if (.windows == @import("builtin").os.tag) {
+        std.debug.print("MMap is not supported in Windows\n", .{});
+        return;
+    }
+
+    const file = try fs.cwd().createFile(filename, .{
+        .read = true,
+        .truncate = true,
+        .exclusive = false, // Set to true will ensure this file is created by us
+    });
+    defer file.close();
+
+    // Before mmap, we need to ensure file isn't empty
+    try file.setEndPos(file_size);
+
+    const md = try file.metadata();
+    print("File size: {d}\n", .{md.size()});
+
+    var ptr = try std.os.mmap(
+        null,
+        20,
+        std.os.PROT.READ | std.os.PROT.WRITE,
+        std.os.MAP.PRIVATE,
+        file.handle,
+        0,
+    );
+    defer std.os.munmap(ptr);
+
+    // Write file via mmap
+    std.mem.copyForwards(u8, ptr, "hello zig cookbook");
+
+    // Read file via mmap
+    print("File body: {s}", .{ptr});
+}

Diff for: src/01-01-read-file-line-by-line.md

@@ -0,0 +1,15 @@
+# Read file line by line
+
+There is a Reader type in Zig, which provides various methods to read file.
+
+```zig
+    const file = try fs.cwd().openFile("build.zig", .{});
+    defer file.close();
+
+    const rdr = file.reader();
+    var line_no: usize = 0;
+    while (try rdr.readUntilDelimiterOrEofAlloc(allocator, '\n', 4096)) |line| {
+        line_no += 1;
+        print("{d}--{s}\n", .{ line_no, line });
+    }
+```

Diff for: src/01-02-mmap-file.md

@@ -0,0 +1 @@
+# Mmap file

Diff for: src/SUMMARY.md

@@ -0,0 +1,5 @@
+# Summary
+
+- [File System]()
+  - [Read file line by line](./01-01-read-file-line-by-line.md)
+  - [Mmap file](./01-02-mmap-file.md)