xdg 2.2.5 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 362d671dc23fa7a843466aea4041bb87b8ba1352dd0c8e08a7ad7fc2112965ba
-  data.tar.gz: f18294042434eebc17670ffbd8c6c9496763c6c761342968f10089860be6fa03
+  metadata.gz: f9dd4bd211b8f542935dc160abaf263a15bc21db3f15e0f7b37939bc0e3f9a80
+  data.tar.gz: 84a2b790092dd687f031ccdc9631b5d1db0ec0f44847a14677b593274fbddfce
 SHA512:
-  metadata.gz: 530c3295448bdd6f6bd0b06938e64db6528d6ae942280311d2a515a4a547fa46e9e2a84309b37958fdafa99f4aa595d1123cf562388e41982811e9d41ca6d4f2
-  data.tar.gz: 4a652bf22b50a01f6c87627c31770b300e8bd39b5e8e6ff8b2657dbe59495a28151017d5e5d2fe13c2f8d08ff11c7b4c6e3ba237bf28214747d3d0d09808f84f
+  metadata.gz: 70594ce6e1448354f736104f4bbef83529342cbb12667089a0e36d7c9c12cb6780237134a48fdb6302b599ed553a14041a77a24dcbfe3c5fc7f0f0550bf54c97
+  data.tar.gz: 9adb7c577b93ab720a0928bca5dac158d95dcae3e14054cf86f3f013cd1bda38ae4d4852b62cdfbf7507dad5b1b64ccc827358d431dc95a8eacd4934442eaf90

data/LICENSE.md

@@ -0,0 +1,163 @@
+# Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+## 1. Definitions
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by
+Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is
+granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are
+controlled by, or are under common control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this
+License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to
+software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a
+Source form, including but not limited to compiled object code, generated documentation, and
+conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the
+License, as indicated by a copyright notice that is included in or attached to the work (an example
+is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or
+derived from) the Work and for which the editorial revisions, annotations, elaborations, or other
+modifications represent, as a whole, an original work of authorship. For the purposes of this
+License, Derivative Works shall not include works that remain separable from, or merely link (or
+bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any
+modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted
+to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity
+authorized to submit on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent to the Licensor or
+its representatives, including but not limited to communication on electronic mailing lists, source
+code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor
+for the purpose of discussing and improving the Work, but excluding communication that is
+conspicuously marked or otherwise designated in writing by the copyright owner as "Not a
+Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a
+Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+## 2. Grant of Copyright License
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a
+perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and
+distribute the Work and such Derivative Works in Source or Object form.
+
+## 3. Grant of Patent License
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a
+perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer
+the Work, where such license applies only to those patent claims licensable by such Contributor that
+are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or
+a Contribution incorporated within the Work constitutes direct or contributory patent infringement,
+then any patent licenses granted to You under this License for that Work shall terminate as of the
+date such litigation is filed.
+
+## 4. Redistribution
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with
+or without modifications, and in Source or Object form, provided that You meet the following
+conditions:
+
+1. You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+2. You must cause any modified files to carry prominent notices stating that You changed the
+   files; and
+
+3. You must retain, in the Source form of any Derivative Works that You distribute, all copyright,
+   patent, trademark, and attribution notices from the Source form of the Work, excluding those
+   notices that do not pertain to any part of the Derivative Works; and
+
+4. If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative
+   Works that You distribute must include a readable copy of the attribution notices contained
+   within such NOTICE file, excluding those notices that do not pertain to any part of the
+   Derivative Works, in at least one of the following places: within a NOTICE text file
+   distributed as part of the Derivative Works; within the Source form or documentation, if
+   provided along with the Derivative Works; or, within a display generated by the Derivative
+   Works, if and wherever such third-party notices normally appear. The contents of the NOTICE
+   file are for informational purposes only and do not modify the License. You may add Your own
+   attribution notices within Derivative Works that You distribute, alongside or as an addendum to
+   the NOTICE text from the Work, provided that such additional attribution notices cannot be
+   construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or
+different license terms and conditions for use, reproduction, or distribution of Your modifications,
+or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of
+the Work otherwise complies with the conditions stated in this License.
+
+## 5. Submission of Contributions
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the
+Work by You to the Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed with Licensor regarding such
+Contributions.
+
+## 6. Trademarks
+
+This License does not grant permission to use the trade names, trademarks, service marks, or product
+names of the Licensor, except as required for reasonable and customary use in describing the origin
+of the Work and reproducing the content of the NOTICE file.
+
+## 7. Disclaimer of Warranty
+
+Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties or conditions of
+TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely
+responsible for determining the appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+## 8. Limitation of Liability
+
+In no event and under no legal theory, whether in tort (including negligence), contract, or
+otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or
+agreed to in writing, shall any Contributor be liable to You for damages, including any direct,
+indirect, special, incidental, or consequential damages of any character arising as a result of this
+License or out of the use or inability to use the Work (including but not limited to damages for
+loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial
+damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+## 9. Accepting Warranty or Additional Liability
+
+While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee
+for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights
+consistent with this License. However, in accepting such obligations, You may act only on Your own
+behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You
+agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or
+claims asserted against, such Contributor by reason of your accepting any such warranty or
+additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2019 [Alchemists](https://www.alchemists.io).
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
+compliance with the License. You may obtain a [copy](http://www.apache.org/licenses/LICENSE-2.0) of
+the License.
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is
+distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied. See the License for the specific language governing permissions and limitations under the
+License.

data/README.md

@@ -1,146 +1,229 @@
-# XDG Standards for Ruby
+<p align="center">
+  <img src="xdg.png" alt="XDG Icon"/>
+</p>
 
-[Homepage](http://rubyworks.github.com/xdg) |
-[Source Code](http://github.com/rubyworks/xdg) |
-[Report Issue](http://github.com/rubyworks/xdg/issues) |
-[Mailing List](http://googlegroups.com/group.rubyworks-mailinglist) |
-[Chat Room](irc://irc.freenode.net/rubyworks)
+# XDG
 
-[![Build Status](https://secure.travis-ci.org/rubyworks/xdg.png)](http://travis-ci.org/rubyworks/xdg)
+[![Gem Version](https://badge.fury.io/rb/xdg.svg)](http://badge.fury.io/rb/xdg)
+[![Code Climate Maintainability](https://api.codeclimate.com/v1/badges/73c8f06ae65cbe663e1c/maintainability)](https://codeclimate.com/github/bkuhlmann/xdg/maintainability)
+[![Code Climate Test Coverage](https://api.codeclimate.com/v1/badges/73c8f06ae65cbe663e1c/test_coverage)](https://codeclimate.com/github/bkuhlmann/xdg/test_coverage)
+[![Circle CI Status](https://circleci.com/gh/bkuhlmann/xdg.svg?style=svg)](https://circleci.com/gh/bkuhlmann/xdg)
 
+Provides a Ruby implementation of the [XDG Base Directory
+Specification](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html).
 
-## Introduction
+:bulb: If you write a lot of Command Line Interfaces and would like additional syntactic
+sugar that includes what is found in this gem, make sure to check out the
+[Runcom](https://github.com/bkuhlmann/runcom) gem too.
 
-XDG provides an easy to use Ruby library for working with XDG standards.
+<!-- Tocer[start]: Auto-generated, don't remove. -->
 
-Presently, it only supports the XDG Base Directory Standard.
+## Table of Contents
 
-If your program utilizes user or system-wide support files
-(e.g. configuration files), you owe it to yourself to checkout
-the XDG base directory standard.
+  - [Features](#features)
+  - [Requirements](#requirements)
+  - [Setup](#setup)
+  - [Usage](#usage)
+      - [Overview](#overview)
+      - [Variable Defaults](#variable-defaults)
+      - [Variable Behavior](#variable-behavior)
+        - [`$XDG_*_DIRS`](#xdg__dirs)
+        - [`$XDG_*_HOME`](#xdg__home)
+      - [Variable Priority](#variable-priority)
+  - [Tests](#tests)
+  - [Versioning](#versioning)
+  - [Code of Conduct](#code-of-conduct)
+  - [Contributions](#contributions)
+  - [License](#license)
+  - [History](#history)
+  - [Credits](#credits)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
+
+## Features
+
+- Provides a `XDG::Environment` object that adheres to the *XDG Base Directory Specification* with
+  access to the following environment settings:
+  - `$XDG_CACHE_HOME`
+  - `$XDG_CONFIG_HOME`
+  - `$XDG_CONFIG_DIRS`
+  - `$XDG_DATA_HOME`
+  - `$XDG_DATA_DIRS`
 
-You can learn more about the standard at:
-http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
+## Requirements
 
+1. [Ruby 2.6.3](https://www.ruby-lang.org)
 
-## How to Use
+## Setup
 
-For working with XDG base directories, XDG provides a very simple
-yet flexible interface, `XDG[]`. Let's say you want to work
-with the $XDG_CONFIG_HOME directory. Simply use:
+To install, run:
 
-    XDG['CONFIG_HOME']
+    gem install xdg
 
-This will give you access to a number of useful methods all tied
-into the user's personal configuration directory. Some examples:
+Add the following to your Gemfile:
 
-    XDG['CONFIG_HOME'].glob(pattern)
-    XDG['CONFIG_HOME'].select(pattern){ |path| ... }
-    XDG['CONFIG_HOME'].find(pattern){ |path| ... }
+    gem "xdg"
 
-The same holds true for the other base directories.
+## Usage
 
-    XDG['DATA_HOME']
-    XDG['DATA_DIRS']
+The following describes how to use this XDG implementation.
 
-    XDG['CACHE_HOME']
-    XDG['CACHE_DIRS']
+#### Overview
 
-By leaving out the last qualifier, XDG will provide an interface
-that ties into both the `HOME` and `DIRS` paths.
+To get up and running quickly, use `XDG::Environment` as follows:
 
-    XDG['DATA']
-    XDG['CONFIG']
-    XDG['CACHE']
+    xdg = XDG::Environment.new
+    xdg.cache_home # <= Answers computed `$XDG_CACHE_HOME` value.
+    xdg.config_home # <= Answers computed `$XDG_CONFIG_HOME` value.
+    xdg.config_dirs # <= Answers computed `$XDG_CONFIG_DIRS` value.
+    xdg.data_home # <= Answers computed `$XDG_DATA_HOME` value.
+    xdg.data_dirs # <= Answers computed `$XDG_DATA_DIRS` value.
 
-If you know XDG these are pretty much self-explanatory.
-But see the YARD-based API documentation for further specifics.
+The *computed* value, in this case, is either the user-defined value of the key or the default
+value, per specification, when the key is not defined or empty. For more on this, scroll down to the
+*Variable Defaults* section to learn more.
 
-### Extended Functionality
+The `XDG::Environment` wraps the following objects which can be used individually if you
+don't want to load the entire environment:
 
-The Ruby XDG module also provides extended functionality
-not part of the standard specification. These extensions are
-simply add-on functionality deemed useful, or implementations
-of  proposals being discussed for a possible future version of
-the standard.
+    cache = XDG::Cache.new
+    config = XDG::Config.new
+    data = XDG::Data.new
 
-    XDG['CONFIG_WORK']
-    XDG['CACHE_WORK']
+The `cache`, `config`, and `data` objects share the same API which means you can ask each the
+following messages:
 
-See the API documentation to learn more. Note that the extended modules
-are subject to greater potential for change as they are still being refined.
+- `#home` - Answers the home directory as computed via the `$XDG_*_HOME` key.
+- `#directories` - Answers an array directories as computed via the `$XDG_*_DIRS` key.
+- `#all` - Answers an array of *all* directories as computed from the combined `$XDG_*_HOME` and
+  `$XDG_*_DIRS` values (with `$XDG_*_HOME` prefixed at the start of the array).
 
-### Base Directory Mixin
+#### Variable Defaults
 
-XDG provides a convenient base directory mixin that can provide handy a
-interface to a classes.
+The *XDG Base Directory Specification* defines environment variables and associated default values
+when not defined or empty. The following defaults, per specification, are implemented by the
+`XDG` objects:
 
-    class MyAppConfig
-      include XDG::BaseDir::Mixin
+- `$XDG_CACHE_HOME="$HOME/.cache"`
+- `$XDG_CONFIG_HOME="$HOME/.config"`
+- `$XDG_CONFIG_DIRS="/etc/xdg"`
+- `$XDG_DATA_HOME="$HOME/.local/share"`
+- `$XDG_DATA_DIRS="/usr/local/share/:/usr/share/"`
+- `$XDG_RUNTIME_DIR`
 
-      def subdirectory
-        'myapp'
-      end
-    end
+The `$XDG_RUNTIME_DIR` deserves special mention as it's not, *currently*, implemented as part of
+this gem because it is more user/environment specific. Here is how the `$XDG_RUNTIME_DIR` is meant
+to be used should you choose to use it:
 
-    c = MyAppConfig.new
+- *Must* reference user-specific non-essential runtime files and other file objects (such as
+  sockets, named pipes, etc.)
+- *Must* be owned by the user with *only* the user having read and write access to it.
+- *Must* have a Unix access mode of `0700`.
+- *Must* be bound to the user when logging in.
+- *Must* be removed when the user logs out.
+- *Must* be pointed to the same directory when the user logs in more than once.
+- *Must* exist from first login to last logout on the system and not removed in between.
+- *Must* not allow files in the directory to survive reboot or a full logout/login cycle.
+- *Must* keep the directory on the local file system and not shared with any other file systems.
+- *Must* keep the directory fully-featured by the standards of the operating system. Specifically,
+  on Unix-like operating systems AF_UNIX sockets, symbolic links, hard links, proper permissions,
+  file locking, sparse files, memory mapping, file change notifications, a reliable hard link count
+  must be supported, and no restrictions on the file name character set should be imposed. Files in
+  this directory *may* be subjected to periodic clean-up. To ensure files are not removed,
+  they should have their access time timestamp modified at least once every 6 hours of monotonic
+  time or the 'sticky' bit should be set on the file.
+- When not set, applications should fall back to a replacement directory with similar capabilities
+  and print a warning message. Applications should use this directory for communication and
+  synchronization purposes and should not place larger files in it, since it might reside in runtime
+  memory and cannot necessarily be swapped out to disk.
 
-    c.config.home.to_s  #=> '~/.config/myapp'
+#### Variable Behavior
 
+The behavior of most XDG environment variables can be lumped into two categories:
 
-### Legacy API
+- `$XDG_*_HOME`
+- `$XDG_*_DIRS`
 
-Version 2.0+ of library marks a major departure from the earlier
-"fluid" notation of previous releases. Where as one used to do:
+Each is described in detail below.
 
-    XDG.data.home
+##### `$XDG_*_DIRS`
 
-With the new API one now does:
+These variables are used to define a colon (`:`) delimited list of directories. Order is important
+as the first directory defined will take precedent over the following directory and so forth. For
+example, here is a situation where the `XDG_CONFIG_DIRS` key has a custom value:
 
-    XDG['DATA_HOME']
+    XDG_CONFIG_DIRS="/example/one/.config:/example/two/.settings:/example/three/.configuration"
 
-This was done for a few reasons, but primarily because it reflects more
-closely Ruby's interface to the environment variables themselves, e.g.
+    # Yields the following, colon delimited, array:
+    [
+      "/example/one/.config",
+      "/example/two/.settings",
+      "/example/three/.configuration"
+    ]
 
-    ENV['XDG_DATA_HOME']
+In the above example, the `"/example/one/.config"` path takes *highest* priority since it was
+defined first.
 
-If you prefer the older style, a compatibility layer is provided. You will
-need to load:
+##### `$XDG_*_HOME`
 
-    require 'xdg/base_dir/legacy'
+These variables take precidence over the corresponding `$XDG_*_DIRS` environment variables. Using a
+modified version of the `$XDG_*_DIRS` example, shown above, we could have the following setup:
 
-However we STRONGLY RECOMMEND that you do not use the legacy API --use it only
-if you need to keep some old code working and don't have time to update it at
-the moment. Sometime in the future the legacy API will be deprecated.
+    XDG_CONFIG_HOME="/example/priority"
+    XDG_CONFIG_DIRS="/example/one/.config:/example/two/.settings"
 
+    # Yields the following, colon delimited, array:
+    [
+      "/example/priority",
+      "/example/one/.config",
+      "/example/two/.settings"
+    ]
 
-## How to Install
+Due to `XDG_CONFIG_HOME` taking precidence over the `XDG_CONFIG_DIRS`, the path with the *highest*
+priority in this example is: `"/example/priority"`.
 
-Using RubyGems:
+#### Variable Priority
 
-    $ sudo gem install xdg
+Path precedence is determined in the following order (with the first taking highest priority):
 
-Installing the tarball requires Ruby Setup (see http://rubyworks.github.com/setup).
+1. `$XDG_*_HOME` - Will be used if defined. Otherwise, falls back to specification default.
+1. `$XDG_*_DIRS` - Iterates through directories in order defined (with first taking highest
+   priority). Otherwise, falls back to specification default.
 
-    $ tar -xvzf xdg-0.5.2
-    $ cd xdg-0.5.2
-    $ sudo setup.rb all
+## Tests
 
+To test, run:
 
-## Development
+    bundle exec rake
 
-[GitHub](http://github.com) hosts our [source code](http://github.com/rubyworks/xdg)
-and [issue ticket system](http://github.com/rubyworks/xdg/issues).
+## Versioning
 
-To contribute to the project please fork the repository, ideally, create a new
-topic branch for your work, and submit a pull request.
+Read [Semantic Versioning](https://semver.org) for details. Briefly, it means:
 
+- Major (X.y.z) - Incremented for any backwards incompatible public API changes.
+- Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
+- Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.
 
-## Copyright & License
+## Code of Conduct
 
-Copyright (c) 2008 Rubyworks
+Please note that this project is released with a [CODE OF CONDUCT](CODE_OF_CONDUCT.md). By
+participating in this project you agree to abide by its terms.
 
-Distributed under the terms of the *FreeBSD* license.
+## Contributions
 
-See LICENSE.txt file for details.
+Read [CONTRIBUTING](CONTRIBUTING.md) for details.
 
+## License
+
+Copyright 2019 [Alchemists](https://www.alchemists.io).
+Read [LICENSE](LICENSE.md) for details.
+
+## History
+
+Read [CHANGES](CHANGES.md) for details.
+Built with [Gemsmith](https://github.com/bkuhlmann/gemsmith).
+
+## Credits
+
+Developed by [Brooke Kuhlmann](https://www.alchemists.io) at
+[Alchemists](https://www.alchemists.io).