diff options
| -rw-r--r-- | README.md | 43 | ||||
| -rw-r--r-- | shard.yml | 2 | ||||
| -rw-r--r-- | src/xdg_basedir.cr | 2 |
3 files changed, 24 insertions, 23 deletions
@@ -12,9 +12,9 @@ for those kinds of files. If you've ever seen a program that stores its configurations in the `.config` directory, that program is, at least in part, following this specification. -This crystal interface to the specification provides methods for simply listing -the base directories, as well as a helper method for easily building file paths -relative to them. +This crystal interface to the specification provides two low-level methods, +which simply list the base directories of a certain type, as well as a helper +method for easily building file paths relative to them. installation @@ -36,7 +36,7 @@ usage Suppose you're writing a program called `program_name`, and you want to read one of its configuration files, `file_name.conf`. After reading, you want to -perform some operation on the contents of the file, and then write the new +first perform some operation on the contents of the file and then write the new contents back to `file_name.conf`. Using this module, that might look something like the following: @@ -46,27 +46,28 @@ require "xdg_basedir" # Note: for simplicity's sake, exception handling has been ignored for the # calls to File.read and File.write -# typically, files in the XDG Base Directories will be first sorted into -# directories, based on the program that uses them. This isn't always the case -# however, and so it is not enforced +# files within the XDG Base Directories will typically be further sorted into +# subdirectories, with those directories named for the program or application +# which `owns` them. This is not always the case however, and so isn't enforced read_path = XDGBasedir.full_path("program_name/file_name.conf", :config, :read) -# the specification dictates that base directory locations be determined using -# both the state of the filesystem and the state of certain environment -# variables. it's thus possible that an appropriate base directory won't be -# found, so a nil check is required +# the specification dictates that the locations of base directories should be +# determined using both the state of the filesystem and the state of certain +# environment variables. it's thus possible that an appropriate base directory +# won't be found, and so a nil check is required if read_path contents = File.read(read_path) # ...do something with the contents here... - # write_path here is not necessarily the same as read_path above. full_path - # above will check through the hierarchy of fallback base directories and, if - # it finds the target, return the path into the directory where it was found. - # there is only one base directory for writing, however, and so it is always - # returned here. this means that the first time program_name is run, it might - # read in some system-wide config, write back a user-specific config, and - # then read the user-specific version thereafter + # write_path here is not necessarily the same as read_path above. the above + # call to full_path will check through a hierarchy of fallback base + # directories and, if it finds the target file in one of them, will return a + # path into the directory where it was found. there is only one base + # directory for writing config files, however, and so it is always returned + # here. in practice, this means that the first time program_name is run, it + # might read in some system-wide config file and then write back a + # user-specific one write_path = XDGBasedir.full_path("program_name/file_name.conf", :config, :write) @@ -77,9 +78,9 @@ if read_path end ``` -The `full_path` method takes an argument *type*, which was set above to -`:config`. This argument indicates the type of files that are stored in the -base directory that should be selected. There are four possible types: +The `full_path` method takes an argument *type* (set to `:config` in the +example above). This argument indicates that only base directories containing +files of that *type* should be selected. There are four possible types: - `:data` directories are used for storing and retrieving persistent files across multiple runs of a program. @@ -1,5 +1,5 @@ name: xdg_basedir -version: 1.0.1 +version: 1.0.2 authors: - katherine <shmibs@airen_no_jikken.icu> diff --git a/src/xdg_basedir.cr b/src/xdg_basedir.cr index e6e7b89..942ad36 100644 --- a/src/xdg_basedir.cr +++ b/src/xdg_basedir.cr @@ -20,7 +20,7 @@ # For more details, please refer to the specification, which is available # online [here](https://specifications.freedesktop.org/basedir-spec/0.7/). module XDGBasedir - VERSION = "1.0.1" + VERSION = "1.0.2" # get the base directory into which files of a given *type* should be written # |