Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/markdumay/go-workspace

Simplify the platform-aware access to the Cache, Config, Home, Workspace, and Temp folders for an application
https://github.com/markdumay/go-workspace

configuration golang

Last synced: about 1 month ago
JSON representation

Simplify the platform-aware access to the Cache, Config, Home, Workspace, and Temp folders for an application

Host: GitHub
URL: https://github.com/markdumay/go-workspace
Owner: markdumay
Created: 2021-09-20T05:10:59.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2023-05-30T14:03:14.000Z (over 1 year ago)
Last Synced: 2024-12-16T08:43:40.417Z (2 months ago)
Topics: configuration, golang
Language: Go
Homepage: https://pkg.go.dev/go.markdumay.org/workspace
Size: 91.8 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 2
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        # go-workspace



    Simplify the platform-aware access to the Cache, Config, Home, Workspace, and Temp folders for a Go application

    






    

        

    

    

        

    

    

        

    

    

        

    

    

        

    

    

        

    

    

        

    





  About •

  Built With •

  Prerequisites •

  Installation •

  Usage •

  Contributing •

  Donate •

  License



## About

go-workspace is a Go package to simplify the access to the Cache, Config, Home, Workspace, and Temp folders for an application. It uses common settings for Unix, macOS, Plan 9, and Windows. In addition, it supports the substitution of configurable keywords, such as `$CACHE`, `$HOME`, `$workspaceRoot`, and `$TEMP`. Finally, go-workspace sets the workspace folder to the correct path when ran from source.

## Built With

The project uses the following core software components:

* [Testify][testify_url] - Go unit-testing toolkit with common assertions and mocks.

## Prerequisites

go-workspace requires Go version 1.16 or later to be installed on your system.

## Installation

```console

go get -u go.markdumay.org/workspace

```

## Usage

Import go-workspace into your application to start using the package. The following code snippet illustrates the basic usage of go-workspace. Please refer to the [package documentation][package] for more details.

```go

	const appName = "my_app"

	// initialize the application directories

	dirs, e := NewAppDirs(appName)

	if e != nil {

		fmt.Println("ERROR: cannot initialize application directories")

		os.Exit(1)

	}

	// show the cache directory for 'user', expected output (macOS):

	// /Users/user/Library/Caches/my_app

	fmt.Println(dirs.Cache())

	// show the absolute path of 'test' relative to the home directory, expected output (macOS):

	// /Users/user/test

	fmt.Println(dirs.MakeAbsolute(dirs.Workspace(), "$HOME/test"))

	// show the path of a custom keyword, expected output (macOS):

	// $MYDIR

	w, e := NewDir(Workspace, appName, WithPath("/mydir"), WithAliases([]string{"$MYDIR"}))

	if e != nil {

		fmt.Println("ERROR: cannot initialize workspace directory")

		os.Exit(1)

	}

	dirs.Assign(*w)

	fmt.Println(dirs.Parameterize(dirs.Workspace(), "/mydir"))

```

### Supported Folders

`go-workspace` supports the following five types of folders.

| Type      | Description |

|-----------|-------------|

| Cache     | User-specific cache directory |

| Config    | Current directory (when running from console) or project root (when running from source) |

| Home      | User home directory |

| Workspace | Current directory (when running from console) or project root (when running from source) |

| Temp      | Temp directory |

Unfold one of the below operating systems to see the mapping of the folders to their physical location. The locations are prioritized from left to right in case multiple locations are specified.

Unix

| Type      | Default location                                        |

|-----------|---------------------------------------------------------|

| Cache     | `$XDG_CACHE_HOME/$APP_NAME` or `$HOME/.cache/$APP_NAME` |

| Config    | `$PWD`                                                  |

| Home      | `$HOME/.$APP_NAME`                                      |

| Workspace | `$PWD`                                                  |

| Temp      | `$TMPDIR` or `/tmp`                                     |

macOS

| Type      | Default location                                        |

|-----------|---------------------------------------------------------|

| Cache     | `$HOME/Library/Caches/$APP_NAME` |

| Config    | `$PWD`                                                  |

| Home      | `$HOME/.$APP_NAME`                                      |

| Workspace | `$PWD`                                                  |

| Temp      | `$TMPDIR` or `/tmp`                                     |

Plan 9

| Type      | Default location                                        |

|-----------|---------------------------------------------------------|

| Cache     | `$home/lib/cache/$APP_NAME`                             |

| Config    | `$pwd`                                                  |

| Home      | `$home/.$APP_NAME`                                      |

| Workspace | `$pwd`                                                  |

| Temp      | `/tmp`                                                  |

Windows

| Type      | Default location                                                                                  |

|-----------|---------------------------------------------------------------------------------------------------|

| Cache     | `%LocalAppData%\$APP_NAME`                                                                        |

| Config    | `%cd%`                                                                                            |

| Home      | `%HOME%\$APP_NAME`, `%HOMEDRIVE%\$APP_NAME`, `%HOMEPATH%\$APP_NAME`, or `%USERPROFILE%\$APP_NAME` |

| Workspace | `%cd%`                                                                                            |

| Temp      | `%TMP%`, `%TEMP%`, `%USERPROFILE%`, or the Windows directory                                      |

## Contributing

go-workspace welcomes contributions of any kind. It is recommended to create an issue to discuss your intended contribution before submitting a larger pull request though. Please consider the following guidelines when contributing:

- Address all linting recommendations from `golangci-lint run` (using `.golangci.yml` from the repository).

- Ensure the code is covered by one or more unit tests (using Testify when applicable).

- Follow the recommendations from [Effective Go][effective_go] and the [Uber Go Style Guide][uber_go_guide].

The following steps decribe how to submit a Pull Request:

1. Clone the repository and create a new branch 

    ```console

    $ git checkout https://github.com/markdumay/go-workspace.git -b name_for_new_branch

    ```

2. Make and test the changes

3. Submit a Pull Request with a comprehensive description of the changes

## Donate



## License

The go-workspace codebase is released under the [MIT license][license]. The documentation (including the "README") is licensed under the Creative Commons ([CC BY-NC 4.0)][cc-by-nc-4.0] license.

[cc-by-nc-4.0]: https://creativecommons.org/licenses/by-nc/4.0/

[effective_go]: https://golang.org/doc/effective_go

[testify_url]: https://github.com/stretchr/testify

[uber_go_guide]: https://github.com/uber-go/guide/

[blog]: https://github.com/markdumay

[license]: https://github.com/markdumay/go-workspace/blob/main/LICENSE

[package]: https://pkg.go.dev/go.markdumay.org/workspace

[repository]: https://github.com/markdumay/go-workspace.git