From 72dcba75b14d3f6d3766a1ce38d3ca56702cc95e Mon Sep 17 00:00:00 2001 From: katherine Date: Fri, 30 Nov 2018 04:35:31 -0700 Subject: revise documentation for clarity --- README.md | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index a72a85b..056a003 100644 --- a/README.md +++ b/README.md @@ -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. -- cgit v1.2.3