curlyq 0.0.4 → 0.0.6

data/lib/curly/curl/html.rb

@@ -65,7 +65,13 @@ module Curl
       @external_links_only = options[:external_links_only]
 
       @curl = TTY::Which.which('curl')
-      @url = url
+      @url = url.nil? ? options[:url] : url
+    end
+
+    def parse(source)
+      @body = source
+      { url: @url, code: @code, headers: @headers, meta: @meta, links: @links, head: @head, body: source,
+        source: source.strip, body_links: content_links, body_images: content_images }
     end
 
     def curl
@@ -118,10 +124,15 @@ module Curl
     ##
     ## @return     [Array] array of matches
     ##
-    def extract(before, after)
-      before = /#{Regexp.escape(before)}/ unless before.instance_of?(Regexp)
-      after = /#{Regexp.escape(after)}/ unless after.instance_of?(Regexp)
-      rx = /(?<=#{before.source})(.*?)(?=#{after.source})/m
+    def extract(before, after, inclusive: false)
+      before = /#{Regexp.escape(before)}/ unless before.is_a?(Regexp)
+      after = /#{Regexp.escape(after)}/ unless after.is_a?(Regexp)
+
+      if inclusive
+        rx = /(#{before.source}.*?#{after.source})/m
+      else
+        rx = /(?<=#{before.source})(.*?)(?=#{after.source})/m
+      end
       @body.scan(rx).map { |r| @clean ? r[0].clean : r[0] }
     end
 
@@ -232,11 +243,11 @@ module Curl
           when /source/
             next unless %i[all srcset].include?(type)
 
-            srcsets = img[:attrs].filter { |k| k[:key] =~ /srcset/i }
+            srcsets = img[:attrs].filter { |k| k == 'srcset' }
             if srcsets.count.positive?
               srcset = []
-              srcsets.each do |src|
-                src[:value].split(/ *, */).each do |s|
+              srcsets.each do |k, v|
+                v.split(/ *, */).each do |s|
                   image, media = s.split(/ /)
                   srcset << {
                     src: image,
@@ -252,15 +263,14 @@ module Curl
             end
           when /img/
             next unless %i[all img].include?(type)
-
-            width = img[:attrs].select { |a| a[:key] == 'width' }.first[:value]
-            height = img[:attrs].select { |a| a[:key] == 'height' }.first[:value]
-            alt = img[:attrs].select { |a| a[:key] == 'alt' }.first[:value]
-            title = img[:attrs].select { |a| a[:key] == 'title' }.first[:value]
+            width = img[:attrs]['width']
+            height = img[:attrs]['height']
+            alt = img[:attrs]['alt']
+            title = img[:attrs]['title']
 
             output << {
               type: 'img',
-              src: img[:attrs].filter { |a| a[:key] =~ /src/i }.first[:value],
+              src: img[:attrs]['src'],
               width: width || 'unknown',
               height: height || 'unknown',
               alt: alt,
@@ -313,8 +323,9 @@ module Curl
     ## @param      el    [Nokogiri] element to convert
     ##
     def nokogiri_to_tag(el)
-      attributes = el.attribute_nodes.map do |a|
-        { key: a.name, value: a.name =~ /^(class|rel)$/ ? a.value.split(/ /) : a.value }
+      attributes = {}
+      attributes = el.attribute_nodes.each_with_object({}) do |a, hsh|
+        hsh[a.name] = a.name =~ /^(class|rel)$/ ? a.value.split(/ /) : a.value
       end
 
       {
@@ -343,12 +354,16 @@ module Curl
     ##
     ## @return     [Array] array of matched elements
     ##
-    def search(path, source: @source)
+    def search(path, source: @source, return_source: false)
       doc = Nokogiri::HTML(source)
       output = []
-      doc.search(path).each do |el|
-        out = nokogiri_to_tag(el)
-        output.push(out)
+      if return_source
+        output = doc.search(path).to_html
+      else
+        doc.search(path).each do |el|
+          out = nokogiri_to_tag(el)
+          output.push(out)
+        end
       end
       output
     end
@@ -390,12 +405,12 @@ module Curl
           attrs = tag['attrs'].strip.to_enum(:scan, /(?ix)
                                              (?<key>[@a-z0-9-]+)(?:=(?<quot>["'])
                                              (?<value>[^"']+)\k<quot>|[ >])?/i).map { Regexp.last_match }
-          attrs.map! { |a| { key: a['key'], value: a['key'] =~ /^(class|rel)$/ ? a['value'].split(/ /) : a['value'] } }
+          attributes = attrs.each_with_object({}) { |a, hsh| hsh[a['key']] = a['key'] =~ /^(class|rel)$/ ? a['value'].split(/ /) : a['value'] }
         end
         {
           tag: tag['tag'],
           source: tag.to_s,
-          attrs: attrs,
+          attrs: attributes,
           content: @clean ? tag['content']&.clean : tag['content'],
           tags: content_tags(tag['content'])
         }
@@ -480,6 +495,7 @@ module Curl
     ##
     def content_links
       links = []
+
       link_tags = @body.to_enum(:scan, %r{<a ?(?<tag>.*?)>(?<text>.*?)</a>}).map { Regexp.last_match }
       link_tags.each do |m|
         href = m['tag'].match(/href=(["'])(.*?)\1/)
@@ -534,7 +550,7 @@ module Curl
     ## @return [String] page source
     ##
     def curl_dynamic_html
-      browser = @browser.normalize_browser_type if @browser.is_a?(String)
+      browser = @browser.is_a?(String) ? @browser.normalize_browser_type : @browser
       res = nil
 
       driver = Selenium::WebDriver.for browser
@@ -607,7 +623,7 @@ module Curl
     ##
     def curl_html(url = nil, source: nil, headers: nil,
                   headers_only: false, compressed: false, fallback: false)
-      unless url.nil?
+      if !url.nil?
         flags = 'SsL'
         flags += @headers_only ? 'I' : 'i'
         agents = [
@@ -620,8 +636,8 @@ module Curl
         compress = @compressed ? '--compressed' : ''
         @source = `#{@curl} -#{flags} #{compress} #{headers} '#{@url}' 2>/dev/null`
         agent = 0
-        while source.nil? || source.empty?
-          source = `#{@curl} -#{flags} #{compress} -A "#{agents[agent]}" #{headers} '#{@url}' 2>/dev/null`
+        while @source.nil? || @source.empty?
+          @source = `#{@curl} -#{flags} #{compress} -A "#{agents[agent]}" #{headers} '#{@url}' 2>/dev/null`
           break if agent >= agents.count - 1
         end
 
@@ -630,49 +646,50 @@ module Curl
           Process.exit 1
         end
 
-        if @fallback && (@source.nil? || @source.empty?)
-          @source = curl_dynamic_html(@url, @fallback, @headers)
+        headers = { 'location' => @url }
+        lines = @source.split(/\r\n/)
+        code = lines[0].match(/(\d\d\d)/)[1]
+        lines.shift
+        lines.each_with_index do |line, idx|
+          if line =~ /^([\w-]+): (.*?)$/
+            m = Regexp.last_match
+            headers[m[1]] = m[2]
+          else
+            @source = lines[idx..].join("\n")
+            break
+          end
         end
-      end
 
-      return false if source.nil? || source.empty?
-
-      @source.strip!
+        if headers['content-encoding'] =~ /gzip/i && !compressed
+          warn 'Response is gzipped, you may need to try again with --compressed'
+        end
 
-      headers = { 'location' => @url }
-      lines = @source.split(/\r\n/)
-      code = lines[0].match(/(\d\d\d)/)[1]
-      lines.shift
-      lines.each_with_index do |line, idx|
-        if line =~ /^([\w-]+): (.*?)$/
-          m = Regexp.last_match
-          headers[m[1]] = m[2]
-        else
-          @source = lines[idx..].join("\n")
-          break
+        if headers['content-type'] =~ /json/
+          return { url: @url, code: code, headers: headers, meta: nil, links: nil,
+                   head: nil, body: @source.strip, source: @source.strip, body_links: nil, body_images: nil }
         end
+      else
+        @source = source unless source.nil?
       end
 
-      if headers['content-encoding'] =~ /gzip/i && !compressed
-        warn 'Response is gzipped, you may need to try again with --compressed'
-      end
+      @source = curl_dynamic_html(@url, @fallback, @headers) if @fallback && (@source.nil? || @source.empty?)
 
-      if headers['content-type'] =~ /json/
-        return { url: @url, code: code, headers: headers, meta: nil, links: nil,
-                 head: nil, body: @source.strip, source: @source.strip, body_links: nil, body_images: nil }
-      end
+      return false if @source.nil? || @source.empty?
+
+      @source.strip!
 
-      head = source.match(%r{(?<=<head>)(.*?)(?=</head>)}mi)
+      head = @source.match(%r{(?<=<head>)(.*?)(?=</head>)}mi)
 
       if head.nil?
         { url: @url, code: code, headers: headers, meta: nil, links: nil, head: nil, body: @source.strip,
           source: @source.strip, body_links: nil, body_images: nil }
       else
+        @body = @source.match(%r{<body.*?>(.*?)</body>}mi)[1]
         meta = meta_tags(head[1])
         links = link_tags(head[1])
-        body = @source.match(%r{<body.*?>(.*?)</body>}mi)[1]
-        { url: @url, code: code, headers: headers, meta: meta, links: links, head: head[1], body: body,
-          source: @source.strip, body_links: body_links, body_images: body_images }
+
+        { url: @url, code: code, headers: headers, meta: meta, links: links, head: head[1], body: @body,
+          source: @source.strip, body_links: nil, body_images: nil }
       end
     end
 

data/lib/curly/hash.rb

@@ -2,6 +2,33 @@
 
 # Hash helpers
 class ::Hash
+  def to_data(url: nil, clean: false)
+    if key?(:body_links)
+      {
+        url: self[:url] || url,
+        code: self[:code],
+        headers: self[:headers],
+        meta: self[:meta],
+        meta_links: self[:links],
+        head: clean ? self[:head]&.strip&.clean : self[:head],
+        body: clean ? self[:body]&.strip&.clean : self[:body],
+        source: clean ? self[:source]&.strip&.clean : self[:source],
+        title: self[:title],
+        description: self[:description],
+        links: self[:body_links],
+        images: self[:body_images]
+      }
+    else
+      self
+    end
+  end
+
+  def to_html
+    if key?(:source)
+      self[:source]
+    end
+  end
+
   # Extract data using a dot-syntax path
   #
   # @param      path  [String] The path
@@ -10,6 +37,7 @@ class ::Hash
   #
   def dot_query(path)
     res = stringify_keys
+
     out = []
     q = path.split(/(?<![\d.])\./)
     q.each do |pth|
@@ -18,7 +46,7 @@ class ::Hash
       ats = []
       at = []
       while pth =~ /\[[+&,]?\w+ *[\^*$=<>]=? *\w+/
-        m = pth.match(/\[(?<com>[,+&])? *(?<key>\w+) *(?<op>[\^*$=<>]{1,2}) *(?<val>\w+) */)
+        m = pth.match(/\[(?<com>[,+&])? *(?<key>\w+) *(?<op>[\^*$=<>]{1,2}) *(?<val>[^,&\]]+) */)
         comp = [m['key'], m['op'], m['val']]
         case m['com']
         when ','
@@ -28,22 +56,27 @@ class ::Hash
           at.push(comp)
         end
 
-        pth.sub!(/\[(?<com>[,&+])? *(?<key>\w+) *(?<op>[\^*$=<>]{1,2}) *(?<val>\w+)/, '[')
+        pth.sub!(/\[(?<com>[,&+])? *(?<key>\w+) *(?<op>[\^*$=<>]{1,2}) *(?<val>[^,&\]]+)/, '[')
       end
       ats.push(at) unless at.empty?
       pth.sub!(/\[\]/, '')
 
+      res = res[0] if res.is_a?(Array)
+
       return false if el.nil? && ats.empty? && !res.key?(pth)
 
       res = res[pth] unless pth.empty?
 
+      return false if res.nil?
+
       if ats.count.positive?
         while ats.count.positive?
           atr = ats.shift
-
+          res = [res] if res.is_a?(Hash)
           keepers = res.filter do |r|
             evaluate_comp(r, atr)
           end
+
           out.concat(keepers)
         end
       else
@@ -52,6 +85,7 @@ class ::Hash
 
       out = out[eval(el)] if out.is_a?(Array) && el =~ /^[\d.,]+$/
     end
+
     out
   end
 
@@ -60,13 +94,15 @@ class ::Hash
   ##
   ## @param      r     [Hash] hash of source elements and
   ##                   comparison operators
-  ## @param      atr   [String] The attribute to compare
+  ## @param      atr   [Array] Array of arrays conaining [attribute,comparitor,value]
   ##
   ## @return     [Boolean] whether the comparison passes or fails
   ##
   def evaluate_comp(r, atr)
     keep = true
 
+    r = r.symbolize_keys
+
     atr.each do |a|
       key = a[0].to_sym
       val = if a[2] =~ /^\d+$/
@@ -118,7 +154,7 @@ class ::Hash
   end
 
   ##
-  ## Test if a hash contains a tag matching filter queries
+  ## Test if a tag contains an attribute matching filter queries
   ##
   ## @param      tag_name    [String] The tag name
   ## @param      classes     [String] The classes to match
@@ -184,10 +220,26 @@ class ::Hash
     end
   end
 
-  # Turn all keys into string
+  # Turn all keys into symbols
+  #
+  # If the hash has both a string and a symbol for key,
+  # keep the symbol value, discarding the string value
+  #
+  # @return     [Hash] a copy of the hash where all its
+  #             keys are strings
+  #
+  def symbolize_keys
+    each_with_object({}) do |(k, v), hsh|
+      next if k.is_a?(String) && key?(k.to_sym)
+
+      hsh[k.to_sym] = v.is_a?(Hash) ? v.symbolize_keys : v
+    end
+  end
+
+  # Turn all keys into strings
   #
   # If the hash has both a string and a symbol for key,
-  # keep the string value, discarding the symnbol value
+  # keep the string value, discarding the symbol value
   #
   # @return     [Hash] a copy of the hash where all its
   #             keys are strings

data/lib/curly/version.rb

@@ -1,3 +1,3 @@
 module Curly
-  VERSION = '0.0.4'
+  VERSION = '0.0.6'
 end

data/src/_README.md

@@ -10,7 +10,7 @@ _If you find this useful, feel free to [buy me some coffee][donate]._
 [donate]: https://brettterpstra.com/donate
 <!--END GITHUB-->
 
-The current version of `curlyq` is <!--VER-->0.0.3<!--END VER-->.
+The current version of `curlyq` is <!--VER-->0.0.4<!--END VER-->.
 
 CurlyQ is a utility that provides a simple interface for curl, with additional features for things like extracting images and links, finding elements by CSS selector or XPath, getting detailed header info, and more. It's designed to be part of a scripting pipeline, outputting everything as structured data (JSON or YAML). It also has rudimentary support for making calls to JSON endpoints easier, but it's expected that you'll use something like `jq` to parse the output.
 
@@ -39,12 +39,41 @@ Run `curlyq help` for a list of subcommands. Run `curlyq help SUBCOMMAND` for de
 @cli(bundle exec bin/curlyq help)
 ```
 
+### Query and Search syntax
+
+You can shape the results using `--search` (`-s`) and `--query` (`-q`) on some commands.
+
+A search uses either CSS or XPath syntax to locate elements. For example, if you wanted to locate all of the `<article>` elements with a class of `post` inside of the div with an id of `main`, you would run `--search '#main article.post'`. Searches can target tags, ids, and classes, and can accept `>` to target direct descendents. You can also use XPaths, but I hate those so I'm not going to document them.
+
+Queries are specifically for shaping CurlyQ output. If you're using the `html` command, it returns a key called `images`, so you can target just the images in the response with `-q 'images'`. The queries accept array syntax, so to get the first image, you would use `-q 'images[0]'`. Ranges are accepted as well, so `-q 'images[1..4]'` will return the 2nd through 5th images found on the page. You can also do comparisons, e.g. `images[rel=me]'` to target only images with a `rel` attribute of `me`.
+
+The comparisons for the query flag are:
+
+- `<` less than
+- `>` greater than
+- `<=` less than or equal to
+- `>=` greater than or equal to
+- `=` or `==` is equal to
+- `*=` contains text
+- `^=` starts with text
+- `$=` ends with text
+
 #### Commands
 
 curlyq makes use of subcommands, e.g. `curlyq html [options] URL` or `curlyq extract [options] URL`. Each subcommand takes its own options, but I've made an effort to standardize the choices between each command as much as possible.
 
 ##### extract
 
+Example: 
+
+    curlyq extract -i -b 'Adding' -a 'accessing the source.' 'https://stackoverflow.com/questions/52428409/get-fully-rendered-html-using-selenium-webdriver-and-python'
+
+    [
+      "Adding <code>time.sleep(10)</code> in various places in case the page had not fully loaded when I was accessing the source."
+    ]
+
+This specifies a before and after string and includes them (`-i`) in the result.
+
 ```
 @cli(bundle exec bin/curlyq help extract)
 ```
@@ -52,36 +81,212 @@ curlyq makes use of subcommands, e.g. `curlyq html [options] URL` or `curlyq ext
 
 ##### headlinks
 
+Example:
+
+    curlyq headlinks -q '[rel=stylesheet]' https://brettterpstra.com
+
+    {
+      "rel": "stylesheet",
+      "href": "https://cdn3.brettterpstra.com/stylesheets/screen.7261.css",
+      "type": "text/css",
+      "title": null
+    }
+
+This pulls all `<links>` from the `<head>` of the page, and uses a query `-q` to only show links with `rel="stylesheet"`.
+
 ```
 @cli(bundle exec bin/curlyq help headlinks)
 ```
 
 ##### html
 
+The html command (aliased as `curl`) gets the entire text of the web page and provides a JSON response with a breakdown of:
+
+- URL, after any redirects
+- Response code
+- Response headers as a keyed hash
+- Meta elements for the page as a keyed hash
+- All meta links in the head as an array of objects containing (as available): 
+    - rel
+    - href
+    - type
+    - title
+- source of `<head>`
+- source of `<body>`
+- the page title (determined first by og:title, then by a title tag)
+- description (using og:description first)
+- All links on the page as an array of objects with: 
+    - href
+    - title
+    - rel
+    - text content
+    - classes as array
+- All images on the page as an array of objects containing:
+    - class
+    - all attributes as key/value pairs
+    - width and height (if specified)
+    - src
+    - alt and title
+
+You can add a query (`-q`) to only get the information needed, e.g. `-q images[width>600]`.
+
+Example:
+
+    curlyq html -s '#main article .aligncenter' -q 'images[1]' 'https://brettterpstra.com'
+
+    [
+      {
+        "class": "aligncenter",
+        "original": "https://cdn3.brettterpstra.com/uploads/2023/09/giveaway-keyboardmaestro2024-rb_tw.jpg",
+        "at2x": "https://cdn3.brettterpstra.com/uploads/2023/09/giveaway-keyboardmaestro2024-rb@2x.jpg",
+        "width": "800",
+        "height": "226",
+        "src": "https://cdn3.brettterpstra.com/uploads/2023/09/giveaway-keyboardmaestro2024-rb.jpg",
+        "alt": "Giveaway Robot with Keyboard Maestro icon",
+        "title": "Giveaway Robot with Keyboard Maestro icon"
+      }
+    ]
+
+The above example queries the full html of the page, but narrows the elements using `--search` and then takes the 2nd image from the results.
+
+    curlyq html -q 'meta.title'  https://brettterpstra.com/2024/01/10/introducing-curlyq-a-pipeline-oriented-curl-helper/
+
+    Introducing CurlyQ, a pipeline-oriented curl helper - BrettTerpstra.com
+
+The above example curls the page and returns the title attribute found in the meta (`-q 'meta.title'`).
+
 ```
 @cli(bundle exec bin/curlyq help html)
 ```
 
 ##### images
 
+The images command returns only the images on the page as an array of objects. It can be queried to match certain requirements (see Query and Search syntax above).
+
+The base command will return all images on the page, including OpenGraph images from the head, `<img>` tags from the body, and `<srcset>` tags along with their child images.
+
+OpenGraph images will be returned with the structure:
+
+    {
+        "type": "opengraph",
+        "attrs": null,
+        "src": "https://cdn3.brettterpstra.com/uploads/2024/01/curlyq_header-rb_tw.jpg"
+      }
+
+`img` tags will be returned with the structure:
+
+    {
+        "type": "img",
+        "src": "https://cdn3.brettterpstra.com/uploads/2024/01/curlyq_header-rb.jpg",
+        "width": "800",
+        "height": "226",
+        "alt": "Banner image for CurlyQ",
+        "title": "CurlyQ, curl better",
+        "attrs": [
+          {
+            "class": [
+              "aligncenter"
+             ], // all attributes included
+          }
+        ]
+      }
+
+
+
+`srcset` images will be returned with the structure:
+
+    {
+        "type": "srcset",
+            "attrs": [
+              {
+                "key": "srcset",
+                "value": "https://cdn3.brettterpstra.com/uploads/2024/01/curlyq_header-rb_tw.jpg 1x, https://cdn3.brettterpstra.com/uploads/2024/01/curlyq_header-rb@2x.jpg 2x"
+              }
+            ],
+            "images": [
+              {
+                "src": "https://cdn3.brettterpstra.com/uploads/2024/01/curlyq_header-rb_tw.jpg",
+                "media": "1x"
+              },
+              {
+                "src": "https://cdn3.brettterpstra.com/uploads/2024/01/curlyq_header-rb@2x.jpg",
+                "media": "2x"
+              }
+          ]
+        }
+    }
+
+Example:
+
+    curlyq images -t img -q '[alt$=screenshot]' https://brettterpstra.com
+
+This will return an array of images that are `<img>` tags, and only show the ones that have an `alt` attribute that ends with `screenshot`.
+
+    curlyq images -q '[width>750]' https://brettterpstra.com
+
+This example will only return images that have a width greater than 750 pixels. This query depends on the images having proper `width` attributes set on them in the source.
+
 ```
 @cli(bundle exec bin/curlyq help images)
 ```
 
 ##### json
 
+The `json` command just returns an object with header/response info, and the contents of the JSON response after it's been read by the Ruby JSON library and output. If there are fetching or parsing errors it will fail gracefully with an error code.
+
 ```
 @cli(bundle exec bin/curlyq help json)
 ```
 
 ##### links
 
+Returns all the links on the page, which can be queried on any attribute.
+
+Example:
+
+    curlyq links -q '[content*=twitter]' 'https://stackoverflow.com/questions/52428409/get-fully-rendered-html-using-selenium-webdriver-and-python'
+
+    [
+      {
+        "href": "https://twitter.com/stackoverflow",
+        "title": null,
+        "rel": null,
+        "content": "Twitter",
+        "class": [
+          "-link",
+          "js-gps-track"
+        ]
+      }
+    ]
+
+This example gets all links from the page but only returns ones with link content containing 'twitter' (`-q '[content*=twitter]'`).
+
 ```
 @cli(bundle exec bin/curlyq help links)
 ```
 
 ##### scrape
 
+Loads the page in a web browser, allowing scraping of dynamically loaded pages that return nothing but scripts when `curl`ed. The `-b` (`--browser`) option is required and should be 'chrome' or 'firefox' (or just 'c' or 'f'). The selected browser must be installed on your system.
+
+Example:
+
+    curlyq scrape -b firefox -q 'links[rel=me&content*=mastodon][0]' https://brettterpstra.com/2024/01/10/introducing-curlyq-a-pipeline-oriented-curl-helper/
+
+    {
+      "href": "https://nojack.easydns.ca/@ttscoff",
+      "title": null,
+      "rel": [
+        "me"
+      ],
+      "content": "Mastodon",
+      "class": [
+        "u-url"
+      ]
+    }
+
+This example scrapes the page using firefox and finds the first link with a rel of 'me' and text containing 'mastodon'.
+
 ```
 @cli(bundle exec bin/curlyq help scrape)
 ```
@@ -90,12 +295,45 @@ curlyq makes use of subcommands, e.g. `curlyq html [options] URL` or `curlyq ext
 
 Full-page screenshots require Firefox, installed and specified with `--browser firefox`.
 
+Type defaults to `full`, but will only work if `-b` is Firefox. If you want to use Chrome, you must specify a `--type` as 'visible' or 'print'.
+
+The `-o` (`--output`) flag is required. It should be a path to a target PNG file (or PDF for `-t print` output). Extension will be modified automatically, all you need is the base name.
+
+Example:
+
+    curlyq screenshot -b f -o ~/Desktop/test https://brettterpstra.com/2024/01/10/introducing-curlyq-a-pipeline-oriented-curl-helper/
+
+    Screenshot saved to /Users/ttscoff/Desktop/test.png
+
+
 ```
 @cli(bundle exec bin/curlyq help screenshot)
 ```
 
 ##### tags
 
+Return a hierarchy of all tags in a page. Use `-t` to limit to a specific tag.
+
+    curlyq tags --search '#main .post h3' -q 'attrs[id*=what]' https://brettterpstra.com/2024/01/10/introducing-curlyq-a-pipeline-oriented-curl-helper/
+
+    [
+      {
+        "tag": "h3",
+        "source": "<h3 id=\"whats-next\">What’s Next</h3>",
+        "attrs": [
+          {
+            "id": "whats-next"
+          }
+        ],
+        "content": "What’s Next",
+        "tags": [
+
+        ]
+      }
+    ]
+
+The above command filters the tags based on a CSS query, then further filters them to just tags with an id containing 'what'.
+
 ```
 @cli(bundle exec bin/curlyq help tags)
 ```