jtag 0.1.19 → 0.1.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71af8eca8dc4710dbb6d924c08a68cc834ab90e15f29d533809bdc1a2e269c6a
-  data.tar.gz: 964a8e7a5bc147edbd6006d2721ec57d89ca11fd77e77b189f5c0bfa8e6691db
+  metadata.gz: dce6f0470ef8fd405ee64a347ff3248c12080d76b7d260f2767ea0df6a99754e
+  data.tar.gz: e6bbedc5133afafb194165e07a830feacab40d6409a11d2f76dc974e42df26f3
 SHA512:
-  metadata.gz: 13c13c4f35e36c9a9015082a370127bcc2e83f0d7682e1821390fc949534b45d0d134cadcbbe057a669582f16039cc7e7cc1a6f05e1d17edeec92f9663d371b0
-  data.tar.gz: 3c0b420b164c1f5fe67e09a6bd4827195c84fe51a8adb6ae153189ec18d75dc649820b3b7c539b780d37d1d311acc2309beeae4f3df59795a57039253ea8f12b
+  metadata.gz: 2ae0e91ccbc3af0622c323fff774f0624927f16d9573a4170ba9f37ea08ebde9cf2cb92092f498bd4fbbd22179fa37e63d1ba01ad802995d8638b32567a95ab2
+  data.tar.gz: 355dd96ef61e1b14e1bd17e03ac39b6d39afb118d1733eb6fd7b0ca48fd1ed170b9668d009e8c8157e3fcd020be7d184cab04d1760914349722f6726a044d006

data/.irbrc

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+`gem rdoc binbundle --ri`
+
+# rubocop:disable Style/MixinUsage
+include JekyllTag # standard:disable all
+# rubocop:enable Style/MixinUsage

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+### 0.1.19
+
+2024-09-16 13:15
+
+#### NEW
+
+- Allows piping of file lists. For actions to which it applies, you can pipe a file list, either from a previous jtag command or from another source (newline separated) to act on only those files, e.g. `jtag posts_tagged keyboard | jtag tags`
+
+#### FIXED
+
+- File.exists? => File.exist? for Ruby 3
+
+### 1.0
+
+Initial release

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+gemspec
+

data/Jekyll/plugins/autotag_gen.rb

@@ -0,0 +1,58 @@
+#
+# Author: Brett Terpstra
+# Page generator for /data/tags.json, a list of all the tags on your blog and a list of the top 50 tags.
+# Part of the AutoTag tool for Jekyll, but usable in other applications
+#
+# Looks for a tags_json.html template in your _layouts folder, see the example provided.
+# Provides page.json_tags and page.json_tags_count as arrays for looping
+#
+# Config options for _config.yml
+# tag_excludes: array of tags to exclude from all listings
+# tags_json_dir: alternate of folder for the data.json file. Set to blank for root, defaults to 'data'
+#
+# If using tags.json with a javascript application, be sure you have the proper headers defined in .htaccess:
+# AddType application/json               json
+# ExpiresByType application/json         "access plus 0 seconds"
+
+require 'json'
+
+module Jekyll
+
+  class AutoTag < Page
+    def initialize(site, base, dir)
+      @site = site
+      @base = base
+      @dir = dir
+      @name = 'tags.json'
+      self.process(@name)
+      self.read_yaml(File.join(base, '_layouts'), 'tags_json.html')
+      tags_with_counts = site.tags.delete_if {|k,v|
+        site.config['tag_excludes'].include?(k) unless site.config['tag_excludes'].nil?
+      }.sort_by { |k,v| v.count }.reverse
+
+      self.data['json_tags'] = tags_with_counts.sort {|a,b| a[0].downcase <=> b[0].downcase }.map {|k,v| k }
+      self.data['json_tags_count'] = []
+      tags_with_counts.each { |k,v|
+        self.data['json_tags_count'] << {
+          "name" => k,
+          "count" => v.count
+        }
+      }
+    end
+  end
+  class AutoTagGenerator < Generator
+    safe true
+    def generate(site)
+      if site.layouts.key? 'tags_json'
+        dir = site.config['tag_json_dir'] || 'data'
+        write_tag_json(site, dir)
+      end
+    end
+    def write_tag_json(site, dir)
+      index = AutoTag.new(site, site.source, dir)
+      index.render(site.layouts, site.site_payload)
+      index.write(site.dest)
+      site.pages << index
+    end
+  end
+end

data/Jekyll/source/_layouts/tags_json.html

@@ -0,0 +1,11 @@
+---
+layout: nil
+---
+{
+	"tags_count": [{% for tag in page.json_tags_count %}
+		{"name":"{{tag.name}}","count":{{tag.count}}},{% endfor %}
+		false],
+	"tags": [{% for tag in page.json_tags %}
+		"{{tag}}",{% endfor %}
+		false]
+}

data/README.md

@@ -0,0 +1,159 @@
+# jTag
+
+*Because you can't be too careful these days.*
+
+**jTag** is a command line application for manipulating Jekyll tags in the YAML headers. It can perform mass operations such as tag addition, removal, merging and sorting. It can also suggest relevant tags based on the content of the post matched against your existing tag set (requires a plugin/template in your Jekyll install).
+
+Configuration includes a persistent blacklist and synonym definitions. Tags manually added to posts are automatically whitelisted for the auto-tagger. The auto-tagger can update your posts directly, or be used to provide suggestions for a working post that you can manually insert in the post.
+
+**NOTE:** jTag works by modifying the YAML headers of your posts directly. There's no undo. Back up your posts (which is a good idea anyway). The best way to this is with git.
+
+If you're not already using git to manage your blog (i.e. not deploying via git), just add the non-public parts of the directory (the source files) to a repo and make a commit when you finish post. A local repo would be fine in most cases, but a remote repo offers a little extra peace of mind. Mine is set up so that a gen_deploy Rake task automatically creates a snapshot every time I publish, in addition to my own commits.
+
+
+The jTag tool is at 0.1.6 at the time of this writing. It's been tested, but never used by anyone but me until today. I'll be adding features and updating as I go, so please [let me know about bugs][support].
+
+First, though, let's cover the plugin side, which hasn't needed to change since I first wrote it. Set it up and forget it.
+
+## Generating a tag index
+
+To use jtag, we need to generate an index of all the tags on a Jekyll/OctoPress blog in JSON format. I chose JSON because it could be used in JavaScript apps easily and would make the data useful for more than just jTag. The code for both the template and the plugin can be found in the [Jekyll folder of the GitHub repository](https://github.com/ttscoff/jtag/tree/master/Jekyll).
+
+### Plugin: autotag_gen.rb
+
+This plugin is a Page generator which creates `/data/tags.json`, which is a list of all the tags on your blog, as well as a list of the top 50 tags with a count of how many times they appear across your blog. You can [download the plugin here](https://github.com/ttscoff/jtag/blob/master/Jekyll/plugins/autotag_gen.rb).
+
+The plugin looks for the `tags_json.html` template in your _layouts folder. See the example provided. It provides the following, which can be used in the liquid template:
+
+- `page.json_tags`
+- `page.json_tags_count`
+
+In your blog's `_config.yml`, you can optionally add rules for excluding tags or using an alternate destination:
+
+- `tag_excludes:` array of tags to exclude from all listings
+- `tags_json_dir:` alternate folder for the `data.json` file. Set to blank for root, defaults to 'data'
+
+Side note: if you're also using tags.json with JavaScript on your site, be sure you have the proper headers defined in `.htaccess`:
+
+
+    AddType application/json               json
+    ExpiresByType application/json         "access plus 0 seconds"
+
+### Template: tags_json.html
+
+Place [the template](https://github.com/ttscoff/jtag/blob/master/Jekyll/source/_layouts/tags_json.html) in `source/_layouts/tags_json.html`.
+
+Now you can do a full build of your blog and the `data/tags.json` file will be ready for deploy.
+
+## jTag
+
+jTag is currently at version 0.1.6 It will be a work in progress for a while as I make it more efficient and figure out the best ways to integrate it into my blogging workflow.It grabs all of the tags on your blog (the `tags.json` file) and compares them to the text you give it. It handles matching plurals and different conjugations of words so that you get tag results even if they're not an exact match.
+
+### Installation/Configuration
+
+The gem is hosted on [rubygems.org](https://rubygems.org/gems/jtag). To install, either add the jtag dependency to your Gemfile in your Jekyll folder (`gem "jtag", "~> 0.1.6"`) and run `bundle`, or run `gem install jtag`. If you're not using a ruby version manager, you may need to use `sudo gem install jtag` to install it in your system Ruby configuration.
+
+Run `jtag config` to ensure it's loaded and create the configuration folder and files in `~/.config/jtag`.
+
+The only configuration option required is the location (url without protocol) of your `tags.json` file. It's set in `~/.config/jtag/config.yml`:
+
+    tags_location: brettterpstra.com/data/tags.json
+
+There are three other files that are generated in `~/.config/jtag/`, and they can be edited as needed:
+
+- **blacklist.txt**
+
+    This is a blacklist. Tags in this list will never show up in automatic results. If it already exists in the post it's merged in, but it won't be created. There are some tags that are relatively generic in terminology and would be triggered on almost every post. They're usually tags that I'd enter myself anyway. For example, I have a tag for Gabe Weatherhead's show, [Generational]([70decibels]): "generational." Because jTag stems the word before scanning for it, anything based off the root "generi" will trigger that tag. Thus, it's blacklisted and added manually on the infrequent occasions that I'm on the show.
+
+    The easiest way to add a tag to the blacklist is to run `jtag blacklist TAGNAME`. You can blacklist multiple tags at once, just separate them with a space. The blacklist is stored in `~/.config/jtag/blacklist.txt` and can be edited manually if needed.
+- **stopwords.txt**
+
+    This is a predefined list of common words that will most likely never be tags. They're "stemmed" down to their root, so that "thing," "things," and "thingy" are all blocked by one line. If you find your results are missing a particular tag, scan the `~/.config/jtag/stopwords.txt` file for the culprit.
+- **synonyms.yml**
+
+    The `synonyms.yml` file is a YAML file that defines alternate spellings, punctuations or related topics which determine when a tag is used. For example, my tag for Mountain Lion is "mountainlion" because I like single-word, lowercase tags. That isn't going to be found in the text of my posts, though, so I add synonyms like this:
+
+
+        mountainlion:
+        - Mountain Lion
+        - 10.8
+        - OS X 10.8
+
+
+    You can add as many as you like. When an attached term is found in the text, it will include the parent tag.
+
+## Usage
+
+**Note:** jTag requires that YAML headers exist in the post being processed. I may add the option to pass just content text and get back an appropriate auto-tag response, but for now you at least need a yaml `---` header and terminator.
+
+jTag is built using subcommands, each with it's own options and parameters. You can get help for jTag with `jtag help`, and documentation for each command with `jtag help command`.
+
+### Commands
+
+    jtag [-t] command [options] [arguments] filename(s)
+
+    help      - Shows a list of commands or help for one command
+
+    add       - Add tags to post(s)
+    remove    - Remove tags from post(s)
+    merge     - Merge multiple tags into one
+
+    config    - Update and notify user of configuration files location
+    blacklist - Blacklist a specific tag
+
+    search      - List all tags, optionally filter for keywords/regular expressions (boolean OR search)
+    sort      - Sort the existing tags for posts
+    tag       - Generate a list of recommended tags, optionally updating the file
+    tags      - Show the current tags for posts
+
+Use the global `-t` option with jTag to run it in "test" mode. No files will be overwritten if the command starts with `jtag -t (command)`. All results will be written to STDOUT for inspection. If you run it with `-t` and pass `-f fmt` to relevant commands with a single file argument, it will output just the tag results in your selected format. This makes it possible to script jTag into other applications.
+
+`config`
+: Use **config** to install configuration files, replace missing ones, or reset to defaults (--reset).
+
+`blacklist`
+: Use **blacklist** to quickly add or remove (run with `-r`) a tag from the blacklist.
+
+`add`
+: Use **add** on a single file, a glob pattern or the results of a grep, ack or find command (using xargs) to add one or more tags to the specified posts. With this, you can quickly add tags to an individual post, or add a tag to any posts that contain certain words in its content or title.
+
+        find source/_posts -name "*marky*" | xargs jtag add markdownifier
+
+`remove`
+: Use **remove** to remove tags on select files, or run it on an entire folder to purge tags from your system.
+
+`merge`
+: You can use **merge** to prune your taxonomy. Have two tags that only differ by capitalization or pluralization? Run something like `jtag merge Markdown markdown _posts/*.md` and all instances of "Markdown" will be converted to "markdown," avoiding duplicates should they arise. You can merge as many tags as you want, the last one in the list will be the one that replaces them all.
+
+`search`
+: Use **search** to list all of the tags on your blog, optionally filtering the list with a keyword as the argument. Multiple keywords will be combined in an boolean OR fashion, so any tags that match any of the keywords will be returned. Keywords can also be quoted regular expressions (e.g. "^mark" to find only tags that _start_ with "mark").
+
+Add the **-c** option to get tags back with a number representing how many posts they appear in. This command is a tool to help you find the proper punctuation, capitalization and pluralization of existing tags to ensure consistency.
+
+        $ jtag search -f list markdown
+        markdown
+        multimarkdown
+        markdownservices
+        markdownifier
+        markdownediting
+        markdownrules
+
+`tag`
+: Use **tag** to suggest tags for your post based on its content. Suggested tags will be mixed with any existing tags (which are automatically whitelisted) and it will return a YAML array block to add to your post. By default, it will write the tags to the file automatically. If you use the -t global switch (`jtag -t tag post.md`) it will just give you the output (in YAML by default) and let you copy/paste it.
+
+`tags`
+: Use **tags** to see the current tags on a post or posts. They'll be listed with the filename as a header and the tags below. This is just handy for quickly confirming operations.
+
+`sort`
+: The **sort** command is a convenience method to alphabetize the tags in your post. It can safely be run on your entire `_posts` folder just to tidy things up.
+
+Any command that outputs a list of tags has the option (`-f, --format`)to change the format to one of `csv`, `list` (plain text), `json` or `yaml` (default). Hopefully this will provide some scripting and integration options in the future.
+
+### Bash completion
+
+If you're interested, there's also a quick script you can drop into `.bash_profile` and get [jtag tab-completion in Bash](https://github.com/ttscoff/jtag/blob/master/jtag.completion.bash).
+
+[support]: https://github.com/ttscoff/jtag/issues/
+
+
+![](http://cdn3.brettterpstra.com/uploads/2013/08/jtag.jpg)

data/Rakefile

@@ -0,0 +1,113 @@
+require 'rake/clean'
+require 'rubygems'
+require 'rubygems/package_task'
+require 'rdoc/task'
+require 'cucumber'
+require 'cucumber/rake/task'
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc","lib/**/*.rb","bin/**/*")
+  rd.title = 'jTag'
+end
+
+spec = eval(File.read('jtag.gemspec'))
+
+Gem::PackageTask.new(spec) do |pkg|
+end
+CUKE_RESULTS = 'results.html'
+CLEAN << CUKE_RESULTS
+desc 'Run features'
+Cucumber::Rake::Task.new(:features) do |t|
+  opts = "features --format html -o #{CUKE_RESULTS} --format progress -x"
+  opts += " --tags #{ENV['TAGS']}" if ENV['TAGS']
+  t.cucumber_opts =  opts
+  t.fork = false
+end
+
+desc 'Run features tagged as work-in-progress (@wip)'
+Cucumber::Rake::Task.new('features:wip') do |t|
+  tag_opts = ' --tags ~@pending'
+  tag_opts = ' --tags @wip'
+  t.cucumber_opts = "features --format html -o #{CUKE_RESULTS} --format pretty -x -s#{tag_opts}"
+  t.fork = false
+end
+
+task :cucumber => :features
+task 'cucumber:wip' => 'features:wip'
+task :wip => 'features:wip'
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*_test.rb']
+end
+desc 'Install the gem in the current ruby'
+task :install, :all do |t, args|
+  args.with_defaults(:all => false)
+  if args[:all]
+    sh "~/scripts/ruby-all gem install pkg/*.gem"
+    # sh "sudo gem install pkg/*.gem"
+  else
+    sh "gem install pkg/*.gem"
+  end
+end
+
+desc 'Install the gem in the all rubies'
+task :installall do |t, args|
+  Rake::Task[:install].invoke(true)
+end
+
+desc 'Development version check'
+task :ver do |t|
+  system "grep VERSION lib/#{spec.name}/version.rb"
+end
+
+desc 'Bump incremental version number'
+task :bump, :type do |t, args|
+  args.with_defaults(:type => "inc")
+  version_file = "lib/#{spec.name}/version.rb"
+  raise "File not found" unless File.exist? version_file
+  content = IO.read(version_file)
+  content.sub!(/VERSION = '(\d+)\.(\d+)\.(\d+)(\.\S+)?'/) {|m|
+    major = $1.to_i
+    minor = $2.to_i
+    inc = $3.to_i
+    pre = $4
+
+    case args[:type]
+    when /^maj/
+      major += 1
+      minor = 0
+      inc = 0
+    when /^min/
+      minor += 1
+      inc = 0
+    else
+      inc += 1
+    end
+
+    $stdout.puts "At version #{major}.#{minor}.#{inc}#{pre}"
+    "VERSION = '#{major}.#{minor}.#{inc}#{pre}'"
+  }
+  File.open(version_file, 'w+') {|f|
+    f.puts content
+  }
+end
+
+def alias_task(tasks)
+    tasks.each do |new_name, old_name|
+        task new_name, [*Rake.application[old_name].arg_names] => [old_name]
+    end
+end
+
+alias_task [
+    [:i, :install],
+    [:ia, :installall],
+    [:p, :package],
+    [:c, :clobber]
+]
+
+
+task :build => [:package]
+task :default => [:clobber,:rdoc,:package]
+task :gobig => [:default,:installall]
+