diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..06965af --- /dev/null +++ b/.editorconfig @@ -0,0 +1,39 @@ +root = true + +# Language indent/EOL/charset overlap with .vscode/settings.json. +# Rulers, renderWhitespace, detectIndentation, mergeEditor, and +# language-server settings cannot be expressed here — they stay in +# settings.json. + +[*] +charset = utf-8 +end_of_line = lf +indent_size = 2 +indent_style = tab +insert_final_newline = true +trim_trailing_whitespace = true + +# [json] +[*.json] +indent_size = 2 +indent_style = space + +# [markdown] +[*.md] +indent_size = 2 +indent_style = space + +# [shellscript] +[*.{bash,sh,zsh}] +indent_size = 2 +indent_style = space + +# [yaml] +[*.{yaml,yml}] +indent_size = 2 +indent_style = space + +# [zig] +[*.zig] +indent_size = 4 +indent_style = space diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..b6d4b9c --- /dev/null +++ b/.gitattributes @@ -0,0 +1,68 @@ +# .gitattributes — Zig (GitHub-hosted) +# +# Sources: GitHub Docs (line endings), git-scm gitattributes (no built-in +# zig diff driver), ziglang conventions for artefacts, github-linguist overrides. + +# Default: detect text, normalize to LF in the repository +* text=auto + +# --- Source --- +*.zig text eol=lf +*.zon text eol=lf +build.zig text eol=lf +build.zig.zon text eol=lf + +# --- Scripts --- +*.bash text eol=lf +*.bat text eol=crlf +*.cmd text eol=crlf +*.ps1 text eol=crlf +*.sh text eol=lf +*.zsh text eol=lf + +# --- Docs / meta --- +*.adoc text +*.markdown text diff=markdown +*.md text diff=markdown +*.txt text +AUTHORS text +CHANGELOG text +CHANGES text +CONTRIBUTING text +COPYING text +LICENSE text +NEWS text +README text +TODO text +.gitattributes text +.gitignore text + +# --- Serialisation --- +*.json text +*.toml text +*.xml text +*.yaml text +*.yml text + +# --- Binary --- +*.a binary +*.exe binary +*.o binary +*.obj binary +*.so binary + +# --- Archives / images (common) --- +*.gif binary +*.gz binary +*.ico binary +*.jpeg binary +*.jpg binary +*.png binary +*.tar binary +*.zip binary + +# --- GitHub Linguist --- +# Prefer .gitignore for these; mark if ever committed +**/.zig-cache/** linguist-generated +**/zig-cache/** linguist-generated +**/zig-out/** linguist-generated diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..7ce3330 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,57 @@ +name: CI + +on: + push: + branches: + - master + - dev + - boilerplate + - idiomatic + - rc1 + - rc2 + - rc3 + pull_request: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + lint: + name: Lint & Format + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Zig + uses: mlugg/setup-zig@v2 + with: + version: 0.16.0 + + - name: Check Formatting + run: zig fmt --check . + + test: + name: Build & Test (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Zig + uses: mlugg/setup-zig@v2 + with: + version: 0.16.0 + + - name: Run Unit Tests + run: zig build test --global-cache-dir .zig-cache + + - name: Run Example + run: zig build run-example --global-cache-dir .zig-cache diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d14c0b1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,24 @@ +# Synesis Information Systems .gitignore for Zig projects + + +# directories (by name) + +/.zig-cache/ +/scratch/ +/zig-out/ + + +# directories (by pattern) + + +# files (by name) + +.DS_Store + + +# files (by pattern) + +*~ +*.sw[pon] +*.tmp +*.zip diff --git a/.vimrc b/.vimrc new file mode 100644 index 0000000..3b044aa --- /dev/null +++ b/.vimrc @@ -0,0 +1,64 @@ +" Synesis C/C++ & Zig project .vimrc — aligned with .vscode/settings.json + +set nocompatible +filetype indent plugin on +syntax enable +set autoindent +set backspace=indent,eol,start +set hlsearch +set incsearch +set number + +" files.insertFinalNewline +set eol +set fixeol + +" editor.renderWhitespace: all +set list +set listchars=tab:->,trail:-,extends:>,precedes:<,nbsp:+ + +" editor.detectIndentation: false — global defaults (editor.tabSize: 4, insertSpaces: true) +set tabstop=4 +set shiftwidth=4 +set softtabstop=4 +set expandtab +set colorcolumn=76 + +if has('termguicolors') + " set termguicolors +endif + +function! s:ConfigureColorColumn() abort + highlight ColorColumn ctermbg=236 guibg=#2a2a2a cterm=NONE gui=NONE +endfunction + +call s:ConfigureColorColumn() +autocmd ColorScheme * call s:ConfigureColorColumn() + +" files.trimTrailingWhitespace +autocmd BufWritePre * %s/\s\+$//e + +augroup sis_c_cxx_zig + autocmd! + " [bat] + autocmd FileType bat,dosbatch setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=60,76 + + " [c] / [cpp] + autocmd FileType c,cpp setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=60,64,68,72,76 + + " [cmake] + autocmd FileType cmake setlocal noexpandtab tabstop=4 shiftwidth=4 softtabstop=4 + + " [json] / [markdown] / [ruby] / [yaml] + autocmd FileType json,markdown,ruby,yaml setlocal expandtab tabstop=2 shiftwidth=2 softtabstop=2 + + " [shellscript] + autocmd FileType bash,sh,zsh setlocal expandtab tabstop=2 shiftwidth=2 softtabstop=2 colorcolumn=60,76 + + " [toml] + autocmd FileType toml setlocal noexpandtab tabstop=2 shiftwidth=2 softtabstop=2 + + " [zig] + autocmd FileType zig setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=76 + +augroup END diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..50947dc --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,36 @@ +{ + "[json]": { + "editor.insertSpaces": true, + "editor.tabSize": 2, + }, + "[markdown]": { + "editor.insertSpaces": true, + "editor.tabSize": 2, + }, + "[toml]": { + "editor.insertSpaces": false, + "editor.tabSize": 2, + }, + "[zig]": { + "editor.codeActionsOnSave": { + "source.fixAll": "explicit", + "source.organizeImports": "explicit", + }, + "editor.defaultFormatter": "ziglang.vscode-zig", + "editor.formatOnSave": true, + "editor.insertSpaces": true, + "editor.suggest.insertMode": "replace", + "editor.tabSize": 4, + }, + "cmake.configureOnOpen": false, + "debug.allowBreakpointsEverywhere": true, + "editor.detectIndentation": false, + "editor.insertSpaces": false, + "editor.renderWhitespace": "all", + "editor.rulers": [ 76 ], + "editor.tabSize": 2, + "files.insertFinalNewline": true, + "files.trimTrailingWhitespace": true, + "git.mergeEditor": false, + "zig.zls.enabled": "on", +} diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 0000000..73311e3 --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,21 @@ +# libpath.Zig - Authors + + +## Major Contributors + +| Name | GitHub | +| ----------- | --------------------------------- | +| Matt Wilson | [mwsis](https://github.com/mwsis) | + + +## Defect reports, fixes and suggestions (for which we are very grateful) + +| Name | GitHub | +| ------- | ------ | +| \ | | + + +Contributions are welcomed. + + + diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 0000000..5b06a97 --- /dev/null +++ b/CHANGES.md @@ -0,0 +1,9 @@ +# libpath.Zig - Changes + + +## 0.0.1 - 18th September 2026 + +* initial project scaffolding; + + + diff --git a/EXAMPLES.md b/EXAMPLES.md new file mode 100644 index 0000000..e926d78 --- /dev/null +++ b/EXAMPLES.md @@ -0,0 +1,9 @@ +# libpath.Zig - Examples + + +| Name | Source | Summary | +| ---------- | -------------------------------------------- | ---------------------------------------------------- | +| **libver** | [examples/libver.zig](./examples/libver.zig) | Prints the **libpath.Zig** package version | + + + diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3198002 --- /dev/null +++ b/LICENSE @@ -0,0 +1,30 @@ +libpath.Zig - BSD 3-Clause License + +Copyright (c) 2026, Matthew Wilson and Synesis Information Systems +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. diff --git a/NEWS.md b/NEWS.md new file mode 100644 index 0000000..0fb021b --- /dev/null +++ b/NEWS.md @@ -0,0 +1,9 @@ +# libpath.Zig - News + + +| Date | News Item | Details | +| ------------------- | --------- | ------- | +| 18th September 2026 | [**libpath.Zig** 0.0.1](https://github.com/synesissoftware/libpath.Zig/releases/tag/0.0.1) | Initial scaffolding | + + + diff --git a/README.md b/README.md index 3bd5589..a4ef7f9 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,123 @@ -# libpath.Zig +# libpath.Zig + Path parsing library, for Zig + +![Language](https://img.shields.io/badge/Zig-F7A41D?style=flat&logo=zig&logoColor=white) +[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) +[![GitHub release](https://img.shields.io/github/v/release/synesissoftware/libpath.Zig.svg)](https://github.com/synesissoftware/libpath.Zig/releases/latest) +[![Last Commit](https://img.shields.io/github/last-commit/synesissoftware/libpath.Zig)](https://github.com/synesissoftware/libpath.Zig/commits/master) +[![CI](https://github.com/synesissoftware/libpath.Zig/actions/workflows/ci.yml/badge.svg)](https://github.com/synesissoftware/libpath.Zig/actions/workflows/ci.yml) + + +## Table of Contents + +- [Introduction](#introduction) +- [Installation](#installation) +- [Components](#components) +- [Examples](#examples) +- [Project Information](#project-information) + - [Where to get help](#where-to-get-help) + - [Contribution guidelines](#contribution-guidelines) + - [Dependencies](#dependencies) + - [Efferent (fan-out)](#efferent-fan-out) + - [Development Dependencies](#development-dependencies) + - [Afferent (fan-in)](#afferent-fan-in) + - [Related projects](#related-projects) + - [License](#license) + + +## Introduction + +**libpath** provides a multi-language, I/O-free model of Unix and Windows file-system path *forms* — parsing, classifying, and comparing them under selectable OS rule sets — as a reliable foundation for applications and path-consuming libraries (notably **recls**). + +**libpath.Zig** is the **Zig** implementation. This repository is a packaging skeleton; the path API is not implemented yet. + + +## Installation + +Add **libpath.Zig** to your `build.zig.zon`: + +```zig +.{ + .name = "my-project", + .version = "0.1.0", + .dependencies = .{ + .libpath = .{ + .url = "https://github.com/synesissoftware/libpath.Zig/archive/refs/tags/0.0.1.tar.gz", + // .hash = "...", + }, + }, +} +``` + +Then import and expose the module in your `build.zig`: + +```zig +const libpath_dep = b.dependency("libpath", .{ + .target = target, + .optimize = optimize, +}); +exe.root_module.addImport("libpath", libpath_dep.module("libpath")); +``` + + +## Components + +Skeleton; path API not yet implemented. The package currently exports `VERSION`. + + +## Examples + +See [EXAMPLES.md](./EXAMPLES.md). Run the sample with: + +```bash +zig build run-example +``` + + +## Project Information + + +### Where to get help + +[GitHub Page](https://github.com/synesissoftware/libpath.Zig "GitHub Page") + + +### Contribution guidelines + +Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/libpath.Zig. + + +### Dependencies + + +#### Efferent (fan-out) + +None. + + +#### Development Dependencies + +None. + + +#### Afferent (fan-in) + +None (currently). + + +### Related projects + +* [**libpath**](https://github.com/synesissoftware/libpath/); +* [**libpath.Go**](https://github.com/synesissoftware/libpath.Go/); +* [**libpath.Python**](https://github.com/synesissoftware/libpath.Python/); +* [**libpath.Ruby**](https://github.com/synesissoftware/libpath.Ruby/); +* [**libpath.Rust**](https://github.com/synesissoftware/libpath.Rust/); + + +### License + +**libpath.Zig** is released under the 3-clause BSD license. See [LICENSE](./LICENSE) for details. + + + diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..92828dc --- /dev/null +++ b/TODO.md @@ -0,0 +1,30 @@ +# libpath.Zig - TODO + + +## Table of Contents + +- [Functional improvements](#functional-improvements) +- [Performance improvements](#performance-improvements) +- [Packaging improvements](#packaging-improvements) + + +## Functional improvements + +* [ ] implement parse / **PathDescriptor**; +* [ ] classification for Unix and Windows path forms; +* [ ] equate and compare; +* [ ] Windows lattice (relative, volume-relative, slash-rooted, drive-rooted, UNC); +* [ ] consume **libpath-concepts** fixtures; + + +## Performance improvements + +* \ diff --git a/build.zig b/build.zig new file mode 100644 index 0000000..1ce8842 --- /dev/null +++ b/build.zig @@ -0,0 +1,50 @@ +const std = @import("std"); + +pub fn build(b: *std.Build) void { + const target = b.standardTargetOptions(.{}); + const optimize = b.standardOptimizeOption(.{}); + + // Create a module for other packages to import + const libpath_module = b.addModule("libpath", .{ + .root_source_file = b.path("src/root.zig"), + .target = target, + .optimize = optimize, + }); + + // Static library using the module + const lib = b.addLibrary(.{ + .name = "libpath", + .linkage = .static, + .root_module = libpath_module, + }); + b.installArtifact(lib); + + // Unit tests using the module + const lib_unit_tests = b.addTest(.{ + .root_module = libpath_module, + }); + const run_lib_unit_tests = b.addRunArtifact(lib_unit_tests); + + const test_step = b.step("test", "Run unit tests"); + test_step.dependOn(&run_lib_unit_tests.step); + + // Example: libver + const example = b.addExecutable(.{ + .name = "libver", + .root_module = b.createModule(.{ + .root_source_file = b.path("examples/libver.zig"), + .target = target, + .optimize = optimize, + }), + }); + example.root_module.addImport("libpath", libpath_module); + b.installArtifact(example); + + const run_example = b.addRunArtifact(example); + if (b.args) |args| { + run_example.addArgs(args); + } + + const run_example_step = b.step("run-example", "Run the libver example"); + run_example_step.dependOn(&run_example.step); +} diff --git a/build.zig.zon b/build.zig.zon new file mode 100644 index 0000000..1193ba2 --- /dev/null +++ b/build.zig.zon @@ -0,0 +1,22 @@ +.{ + .authors = .{ + "Matt Wilson ", + }, + .description = "Path parsing library, for Zig", + .fingerprint = 0x3763d74327cb85ea, + .name = .libpath, + .paths = .{ + "AUTHORS.md", + "CHANGES.md", + "EXAMPLES.md", + "LICENSE", + "NEWS.md", + "README.md", + "TODO.md", + "build.zig", + "build.zig.zon", + "examples", + "src", + }, + .version = "0.0.1", +} diff --git a/examples/libver.zig b/examples/libver.zig new file mode 100644 index 0000000..47e09ab --- /dev/null +++ b/examples/libver.zig @@ -0,0 +1,11 @@ +const std = @import("std"); +const libpath = @import("libpath"); + +pub fn main(init: std.process.Init) !void { + var buffer: [256]u8 = undefined; + var stdout_impl = std.Io.File.stdout().writer(init.io, &buffer); + const stdout = &stdout_impl.interface; + + try stdout.print("libpath.Zig version: {s}\n", .{libpath.VERSION}); + try stdout.flush(); +} diff --git a/src/root.zig b/src/root.zig new file mode 100644 index 0000000..1209966 --- /dev/null +++ b/src/root.zig @@ -0,0 +1,15 @@ +//! Path parsing library, for Zig. +//! +//! **libpath** provides an I/O-free model of Unix and Windows file-system +//! path forms. This package is a scaffolding skeleton; parse, classify, +//! equate, and compare are not implemented yet. + +/// Package version. +pub const VERSION = "0.0.1"; + +const std = @import("std"); +const testing = std.testing; + +test "version" { + try testing.expectEqualStrings("0.0.1", VERSION); +}