mq-ruby 0.1.22 → 0.1.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc8e68991b67c4916d01b6d7fec5a0f7084211e58ca5e43b0b45ac10c5024e53
-  data.tar.gz: 84a83775b49f9cd44f6c43e15ec91266255199cc960519c1f5a5ad31a0bb5c6b
+  metadata.gz: 82df60dcb72de275f0c80ef1747279648ea70d46b0dbc971635cd9d86bd7c7a6
+  data.tar.gz: f4807fec7ba9bcbab543ffd248e6cda4fa847adae1e699df95571536c6c6010a
 SHA512:
-  metadata.gz: 260de2ebb6141a23dec7406f4fe80203902865996392709b5b64788c305cd903115d5016cb36296dfccba53f3a2f57f20ab21ff356fd84a407bf19de3edc2547
-  data.tar.gz: 77b526b5c24d7bae085d1c5297aa370882eddfa4c4ad0bf2101d3ac53f78757d2429af55d974e98bc507d6cca39a150a01b5f66109b2c71d8d65ce6fa1723e71
+  metadata.gz: e9c91a433c96fa4f7904eae06a5a62fe03ccaf1e29820e39f103172f04ecc5cccb4a87e6e1047cbf5e05b2b13f32c48c9911aaa9fcc99108afb200a2c3c91347
+  data.tar.gz: ff45547b349deb0125b9aa3caf9022331b18e0b547b84a83bfe4542eec8296b5a2f4354304a41904899f0b5ac089f782d94974527813573eefa6631e929d5a88

data/Cargo.lock

@@ -845,9 +845,9 @@ checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
 
 [[package]]
 name = "mq-lang"
-version = "0.5.31"
+version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2b51f7340c495c7d3327bec83c45ea26335dae91acb1392cc45ce2fcc2130194"
+checksum = "945450433662b786c8ce51f19ab70891dc442da43d39967c51537927e7f7305a"
 dependencies = [
  "base64",
  "chrono",
@@ -877,14 +877,15 @@ dependencies = [
  "toml",
  "toon-format",
  "url",
+ "web-sys",
  "yaml-rust2",
 ]
 
 [[package]]
 name = "mq-macros"
-version = "0.5.31"
+version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d749dc5c73bcce7a6a978636aef01de4700e0e790d88b5a514ae2d5df393cb77"
+checksum = "18f40d74822fe55553384f385363530300ea41ceadd598baf68fe0373bbb1fae"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -893,9 +894,9 @@ dependencies = [
 
 [[package]]
 name = "mq-markdown"
-version = "0.5.31"
+version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fc96ff6f0490a589fae25145cbc61b883c7fd2d4b042f545eab954c37ed3a167"
+checksum = "791c374af833381678f62652884282f70043110e35b8a4a9f76c72cefca2def2"
 dependencies = [
  "ego-tree",
  "itertools 0.14.0",
@@ -909,7 +910,7 @@ dependencies = [
 
 [[package]]
 name = "mq-ruby"
-version = "0.1.22"
+version = "0.1.23"
 dependencies = [
  "magnus",
  "mq-lang",
@@ -1551,9 +1552,9 @@ checksum = "756daf9b1013ebe47a8776667b466417e2d4c5679d441c26230efd9ef78692db"
 
 [[package]]
 name = "toon-format"
-version = "0.4.4"
+version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6d25e33e50b37f95f3b55b6e664218cac7e1a50f056a75bb4c7a6cccfbc8a8c4"
+checksum = "8f89570c1a68d73941f728cca32a4345b2ffca36667ad921af336c60309a3e7e"
 dependencies = [
  "indexmap",
  "serde",
@@ -1681,6 +1682,16 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "web-sys"
+version = "0.3.83"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b32828d774c412041098d182a8b38b16ea816958e07cf40eec2bc080ae137ac"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "web_atoms"
 version = "0.2.3"

data/Cargo.toml

@@ -10,7 +10,7 @@ name = "mq-ruby"
 publish = false
 readme = "README.md"
 repository = "https://github.com/harehare/mq"
-version = "0.1.22"
+version = "0.1.23"
 
 [lib]
 crate-type = ["cdylib"]
@@ -18,6 +18,6 @@ name = "mq_ruby"
 
 [dependencies]
 magnus = {version = "0.8"}
-mq-lang = "0.5.31"
-mq-markdown = "0.5.31"
+mq-lang = "0.6.0"
+mq-markdown = "0.6.0"
 

data/README.md

@@ -5,40 +5,536 @@
 
 Ruby bindings for [mq](https://mqlang.org/), a jq-like command-line tool for processing Markdown.
 
-## Ruby API
+## Installation
 
-Once complete, the Ruby API will look like this:
+Add to your Gemfile:
+
+```ruby
+gem 'mq-ruby'
+```
+
+## Basic Usage
 
 ```ruby
 require 'mq'
 
-# Basic usage
 markdown = <<~MD
   # Main Title
+
   ## Section 1
+
   Some content here.
+
   ## Section 2
+
   More content.
 MD
 
+# Run a raw mq query string
 result = MQ.run('.h2', markdown)
-result.values.each do |heading|
-  puts heading
-end
+result.values.each { |h| puts h }
+# => ## Section 1
+# => ## Section 2
+
+# Access result as a single string
+puts result.text
 # => ## Section 1
 # => ## Section 2
 
-# With options
+# Count matched nodes
+puts result.length  # => 2
+
+# Index into results (1-based)
+puts result[1]  # => ## Section 1
+```
+
+## Query Builder
+
+`MQ::Query` provides a Ruby DSL for building mq query strings programmatically.
+Queries are built by chaining methods and can be passed directly to `MQ.run`.
+
+```ruby
+# Equivalent to MQ.run('.h2', markdown)
+result = MQ.run(MQ::Query.h2, markdown)
+
+# Chain with filters and transformations
+query = MQ::Query.h2
+  .select { contains("Installation") }
+  .to_text
+
+result = MQ.run(query, markdown)
+```
+
+### Selectors
+
+#### Heading Selectors
+
+```ruby
+MQ::Query.h1        # .h1  — level-1 headings
+MQ::Query.h2        # .h2  — level-2 headings
+MQ::Query.h3        # .h3
+MQ::Query.h4        # .h4
+MQ::Query.h5        # .h5
+MQ::Query.h6        # .h6
+MQ::Query.heading   # .heading — any heading
+```
+
+#### Block Element Selectors
+
+```ruby
+MQ::Query.paragraph   # .p
+MQ::Query.code        # .code       — fenced code blocks
+MQ::Query.blockquote  # .blockquote
+MQ::Query.hr          # .hr         — horizontal rules
+MQ::Query.list        # .[]         — list items
+MQ::Query.table       # .table
+MQ::Query.table_align # .table_align
+MQ::Query.math        # .math       — math blocks
+MQ::Query.html        # .html       — raw HTML blocks
+MQ::Query.definition  # .definition — link definitions
+MQ::Query.footnote    # .footnote
+MQ::Query.toml        # .toml       — TOML front matter
+MQ::Query.yaml        # .yaml       — YAML front matter
+```
+
+#### Inline Element Selectors
+
+```ruby
+MQ::Query.text          # .text
+MQ::Query.strong        # .strong    — bold
+MQ::Query.emphasis      # .emphasis  — italic
+MQ::Query.delete        # .delete    — strikethrough
+MQ::Query.link          # .link
+MQ::Query.image         # .image
+MQ::Query.code_inline   # .code_inline
+MQ::Query.math_inline   # .math_inline
+MQ::Query.link_ref      # .link_ref
+MQ::Query.image_ref     # .image_ref
+MQ::Query.footnote_ref  # .footnote_ref
+MQ::Query.line_break    # .break
+```
+
+#### Task List Selectors
+
+```ruby
+MQ::Query.task  # .task — any task list item
+MQ::Query.todo  # .todo — unchecked task items
+MQ::Query.done  # .done — checked task items
+```
+
+#### Indexed Selectors
+
+```ruby
+MQ::Query.list_at(0)         # .[0]     — first list item
+MQ::Query.list_at(2)         # .[2]     — third list item
+MQ::Query.table_row(0)       # .[0][]   — all cells in row 0
+MQ::Query.table_col(1)       # .[][1]   — all cells in column 1
+MQ::Query.table_cell(0, 1)   # .[0][1]  — cell at row 0, column 1
+```
+
+#### MDX Selectors
+
+```ruby
+MQ::Query.mdx_jsx_flow_element  # .mdx_jsx_flow_element
+MQ::Query.mdx_text_expression   # .mdx_text_expression
+MQ::Query.mdx_jsx_text_element  # .mdx_jsx_text_element
+MQ::Query.mdx_flow_expression   # .mdx_flow_expression
+MQ::Query.mdx_js_esm            # .mdx_js_esm
+```
+
+#### Attribute Selectors
+
+Access specific attributes of nodes directly:
+
+```ruby
+MQ::Query.code.lang    # .code | .lang  — language of code blocks
+MQ::Query.link.url     # .link | .url   — URL of links
+MQ::Query.image.alt    # .image | .alt  — alt text of images
+MQ::Query.link.title   # .link | .title — title of links
+
+# All available attribute selectors (class-level)
+MQ::Query.value    # .value
+MQ::Query.lang     # .lang
+MQ::Query.meta     # .meta
+MQ::Query.fence    # .fence
+MQ::Query.url      # .url
+MQ::Query.alt      # .alt
+MQ::Query.depth    # .depth   — heading depth
+MQ::Query.level    # .level
+MQ::Query.ordered  # .ordered — list ordered flag
+MQ::Query.checked  # .checked — task item checked state
+MQ::Query.column   # .column  — table cell column index
+MQ::Query.row      # .row     — table cell row index
+MQ::Query.align    # .align   — table alignment
+```
+
+#### Instance-level Attribute Access (for chaining)
+
+```ruby
+# After selecting a node, chain attribute selectors:
+MQ::Query.code.lang        # .code | .lang
+MQ::Query.link.url         # .link | .url
+MQ::Query.heading.depth    # .heading | .depth
+MQ::Query.task.checked     # .task | .checked
+MQ::Query.list.item_index  # .[] | .index  (item_index avoids naming conflict)
+MQ::Query.list.ordered     # .[] | .ordered
+MQ::Query.table.column     # .table | .column
+MQ::Query.table.row        # .table | .row
+MQ::Query.table_align.align           # .table_align | .align
+MQ::Query.mdx_jsx_flow_element.mdx_name  # .mdx_jsx_flow_element | .name
+```
+
+#### Recursive Selector
+
+```ruby
+MQ::Query.recursive  # .. — matches all nodes recursively
+```
+
+#### Dict Property Selector
+
+```ruby
+MQ::Query.property("title")  # ."title"
+query.property("key")        # | ."key"
+```
+
+### Pipe Operator
+
+Chain two queries with `|`:
+
+```ruby
+query = MQ::Query.h2 | MQ::Query.to_text
+# => ".h2 | to_text()"
+
+query = MQ::Query.h2 | MQ::Query.select { contains("API") } | MQ::Query.to_text
+# => '.h2 | select(contains("API")) | to_text()'
+```
+
+### Filtering with `select`
+
+```ruby
+# Block form (recommended)
+MQ::Query.h2.select { contains("Feature") }
+# => '.h2 | select(contains("Feature"))'
+
+# Combine conditions with & (and) and | (or)
+MQ::Query.h2.select { contains("API") & starts_with("## ") }
+# => '.h2 | select(contains("API") and starts_with("## "))'
+
+MQ::Query.h2.select { contains("A") | contains("B") }
+# => '.h2 | select(contains("A") or contains("B"))'
+
+# Negation
+MQ::Query.select { negate(contains("draft")) }
+# => 'select(not(contains("draft")))'
+
+# Class-level select (no leading selector)
+MQ::Query.select { is_mdx }
+# => "select(is_mdx())"
+
+# String or Filter argument
+MQ::Query.h2.select('contains("Feature")')
+MQ::Query.h2.select(MQ::Filter.new('contains("Feature")'))
+```
+
+### Mapping with `map`
+
+```ruby
+MQ::Query.list.map { contains("important") }
+# => '.[] | map(contains("important"))'
+```
+
+### Transformation Methods
+
+#### Output
+
+```ruby
+.to_text           # to_text()          — plain text
+.to_markdown       # to_markdown()      — markdown string
+.to_mdx            # to_mdx()           — MDX string
+.to_html           # to_html()          — HTML string
+.to_string         # to_string()        — string coercion
+.to_number         # to_number()        — numeric coercion
+.to_array          # to_array()
+.to_bytes          # to_bytes()
+.to_markdown_string # to_markdown_string()
+```
+
+#### String Operations
+
+```ruby
+.trim              # trim()
+.ltrim             # ltrim()
+.rtrim             # rtrim()
+.downcase          # downcase()
+.upcase            # upcase()
+.ascii_downcase    # ascii_downcase()
+.ascii_upcase      # ascii_upcase()
+.len               # len()
+.utf8bytelen       # utf8bytelen()
+.explode           # explode()          — string to codepoints
+.implode           # implode()          — codepoints to string
+.url_encode        # url_encode()
+.intern            # intern()
+
+.split(",")        # split(",")
+.gsub("pat", "r")  # gsub("pat", "r")  — regex replace all
+.replace("a", "b") # replace("a", "b") — literal replace
+.test("\\d+")      # test("\\d+")      — regex test → bool
+.capture("(\\w+)") # capture("(\\w+)") — regex capture
+.slice(0, 5)       # slice(0, 5)
+.index("sub")      # index("sub")      — position of substring
+.rindex("sub")     # rindex("sub")     — last position
+.repeat(3)         # repeat(3)
+```
+
+#### Collection Operations
+
+```ruby
+.length            # length
+.len               # len()
+.add               # add
+.first             # first
+.last              # last
+.empty             # empty
+.reverse           # reverse
+.sort              # sort
+.compact           # compact           — remove nils
+.uniq              # uniq
+.flatten           # flatten
+.keys              # keys
+.values            # values
+.entries           # entries
+.children          # .children
+.join(", ")        # join(", ")
+.nth(2)            # nth(2)
+.limit(5)          # limit(5)
+.range(3)          # range(3)
+.del("key")        # del("key")
+.insert(0, "val")  # insert(0, "val")
+```
+
+#### Math Operations
+
+```ruby
+.abs               # abs()
+.ceil              # ceil()
+.floor             # floor()
+.round             # round()
+.trunc             # trunc()
+.sqrt              # sqrt()
+.ln                # ln()
+.log10             # log10()
+.exp               # exp()
+.pow(2)            # pow(2)
+.min(0)            # min(0)
+.max(100)          # max(100)
+.negate_val        # negate()          — numeric negation
+.is_nan            # is_nan()
+```
+
+#### Type / Logic
+
+```ruby
+.type              # type
+.coalesce("default") # coalesce("default")
+.debug             # debug
+```
+
+#### Encoding
+
+```ruby
+.base64            # base64()
+.base64d           # base64d()
+.base64url         # base64url()
+.base64urld        # base64urld()
+.md5               # md5()
+.sha256            # sha256()
+.sha512            # sha512()
+.from_hex          # from_hex()
+.to_hex            # to_hex()
+```
+
+#### Path Operations
+
+```ruby
+.basename          # basename()
+.dirname           # dirname()
+.extname           # extname()
+.stem              # stem()
+.path_join("sub")  # path_join("sub")
+```
+
+#### Dict Operations
+
+```ruby
+.get("key")            # get("key")
+.set("key", "val")     # set("key", "val")
+.property("key")       # ."key"
+```
+
+#### Markdown Attribute Operations
+
+```ruby
+.update("New content")          # update("New content")
+.attr("lang")                   # attr("lang")
+.set_attr("lang", "ruby")       # set_attr("lang", "ruby")
+.get_title                      # get_title
+.get_url                        # get_url
+.set_check(true)                # set_check(true)
+.set_ref("myref")               # set_ref("myref")
+.set_code_block_lang("python")  # set_code_block_lang("python")
+.set_list_ordered(true)         # set_list_ordered(true)
+```
+
+#### Markdown Construction
+
+```ruby
+.to_code("ruby")               # to_code("ruby")
+.to_code                       # to_code(null)   — no language
+.to_code_inline                # to_code_inline()
+.to_h(2)                       # to_h(2)          — convert to heading level 2
+.to_hr                         # to_hr()
+.to_link("url", "text", "title")  # to_link(...)
+.to_link("url", "text")           # to_link(...)   — empty title
+.to_link("url")                   # to_link(...)   — current value as text
+.to_image("url", "alt", "title")  # to_image(...)
+.to_math                       # to_math()
+.to_math_inline                # to_math_inline()
+.to_strong                     # to_strong()
+.to_em                         # to_em()
+.to_md_text                    # to_md_text()
+.to_md_list(0)                 # to_md_list(0)    — nesting level
+.to_md_name("component")       # to_md_name("component")
+.to_md_table_row("A", "B", "C")   # to_md_table_row(...)
+.to_md_table_cell("val", 0, 1)    # to_md_table_cell(...)
+```
+
+### Filter DSL
+
+All filter methods return a `MQ::Filter` that can be combined with `&` (and) and `|` (or).
+
+#### String Matching
+
+```ruby
+contains("text")       # contains("text")
+starts_with("## ")     # starts_with("## ")
+ends_with(".")         # ends_with(".")
+test("\\d+")           # test("\\d+")        — regex test
+```
+
+#### Regex
+
+```ruby
+is_regex_match("\\d+")      # is_regex_match("\\d+")
+is_not_regex_match("\\d+")  # is_not_regex_match("\\d+")
+```
+
+#### Comparison Operators
+
+These compare the current pipeline value against the argument:
+
+```ruby
+eq("value")   # eq("value")    — equal
+ne("value")   # ne("value")    — not equal
+gt(5)         # gt(5)          — greater than
+gte(5)        # gte(5)         — greater than or equal
+lt(5)         # lt(5)          — less than
+lte(5)        # lte(5)         — less than or equal
+```
+
+#### Type Checks
+
+```ruby
+is_mdx   # is_mdx()
+is_none  # is_none()
+is_nan   # is_nan()
+type     # type
+```
+
+#### Other
+
+```ruby
+negate(contains("draft"))  # not(contains("draft"))
+length                     # length
+empty                      # empty
+add                        # add
+```
+
+### Combining Filters
+
+```ruby
+MQ::Query.h2.select { contains("API") & negate(contains("Internal")) }
+# => '.h2 | select(contains("API") and not(contains("Internal")))'
+
+MQ::Query.h2.select { starts_with("## ") | ends_with("!") }
+# => '.h2 | select(starts_with("## ") or ends_with("!"))'
+
+# Three-way AND
+MQ::Query.h2.select {
+  contains("API") & negate(contains("Internal")) & starts_with("## ")
+}
+```
+
+## Options
+
+```ruby
 options = MQ::Options.new
+options.input_format = MQ::InputFormat::MARKDOWN  # default
+options.input_format = MQ::InputFormat::MDX
+options.input_format = MQ::InputFormat::TEXT
 options.input_format = MQ::InputFormat::HTML
+options.input_format = MQ::InputFormat::RAW
+options.input_format = MQ::InputFormat::NULL
+
+result = MQ.run('.h1', content, options)
+```
 
-result = MQ.run('.h1', '<h1>Hello</h1><p>World</p>', options)
-puts result.text  # => # Hello
+## HTML to Markdown
 
-# HTML to Markdown conversion
-html = '<h1>Title</h1><p>Paragraph</p>'
+```ruby
+html = '<h1>Title</h1><p>This is a <strong>test</strong>.</p>'
 markdown = MQ.html_to_markdown(html)
-puts markdown  # => # Title\n\nParagraph
+# => "# Title\n\nThis is a **test**."
+
+# With conversion options
+options = MQ::ConversionOptions.new
+options.use_title_as_h1 = true
+options.extract_scripts_as_code_blocks = true
+options.generate_front_matter = true
+
+markdown = MQ.html_to_markdown(html, options)
+```
+
+## Examples
+
+```ruby
+require 'mq'
+
+content = File.read('README.md')
+
+# Extract all h2 headings containing "API"
+MQ.run(MQ::Query.h2.select { contains("API") }, content).values
+
+# Get all code block languages used
+MQ.run(MQ::Query.code.lang, content).values
+
+# Get all link URLs
+MQ.run(MQ::Query.link.url, content).values
+
+# Extract headings as plain text (no # prefix)
+MQ.run(MQ::Query.h2.to_text, content).values
+
+# Find unchecked task items
+MQ.run(MQ::Query.todo, content).values
+
+# Get the first list item
+MQ.run(MQ::Query.list_at(0), content).values
+
+# Count h2 headings
+MQ.run(MQ::Query.h2.length, content).values
+
+# Extract YAML front matter
+MQ.run(MQ::Query.yaml, content).values
 ```
 
 ## License

data/lib/mq/query.rb

@@ -0,0 +1,556 @@
+# frozen_string_literal: true
+
+module MQ
+  # Programmatic query builder for constructing mq queries in Ruby.
+  #
+  # @example Basic selector
+  #   MQ::Query.h2
+  #   # => ".h2"
+  #
+  # @example Selector with filter
+  #   MQ::Query.h2.select { contains("Feature") }
+  #   # => '.h2 | select(contains("Feature"))'
+  #
+  # @example Pipe operator
+  #   MQ::Query.h2 | MQ::Query.to_text
+  #   # => ".h2 | to_text()"
+  #
+  # @example Attribute access
+  #   MQ::Query.link.url
+  #   # => ".link | .url"
+  #
+  # @example Complex chain
+  #   MQ::Query.h2
+  #     .select { contains("Section") & starts_with("##") }
+  #     .to_text
+  #   # => '.h2 | select(contains("Section") and starts_with("##")) | to_text()'
+  #
+  # @example Using with MQ.run
+  #   result = MQ.run(MQ::Query.h2.select { contains("Feature") }, content)
+  class Query
+    def initialize(expr = "")
+      @expr = expr.to_s
+    end
+
+    # Pipe two queries together using the | operator.
+    #
+    # @param other [Query, #to_query] the query to pipe into
+    # @return [Query]
+    def |(other)
+      self.class.new("#{@expr} | #{other.to_query}")
+    end
+
+    # Append a select() filter.
+    #
+    # @param filter [Filter, String, nil] filter expression (or use block)
+    # @yield block evaluated in {FilterDSL} context
+    # @return [Query]
+    def select(filter = nil, &block)
+      filter_str = resolve_filter(filter, &block)
+      pipe_with("select(#{filter_str})")
+    end
+
+    # Append a map() transformation.
+    #
+    # @param filter [Filter, String, nil] filter expression (or use block)
+    # @yield block evaluated in {FilterDSL} context
+    # @return [Query]
+    def map(filter = nil, &block)
+      filter_str = resolve_filter(filter, &block)
+      pipe_with("map(#{filter_str})")
+    end
+
+    def to_text        = pipe_with("to_text()")
+    def to_markdown    = pipe_with("to_markdown()")
+    def to_mdx         = pipe_with("to_mdx()")
+    def to_html        = pipe_with("to_html()")
+    def to_string      = pipe_with("to_string()")
+    def to_number      = pipe_with("to_number()")
+    def to_array       = pipe_with("to_array()")
+    def to_bytes       = pipe_with("to_bytes()")
+    def to_markdown_string = pipe_with("to_markdown_string()")
+
+    def length         = pipe_with("length")
+    def len            = pipe_with("len()")
+    def utf8bytelen    = pipe_with("utf8bytelen()")
+    def add            = pipe_with("add")
+    def first          = pipe_with("first")
+    def last           = pipe_with("last")
+    def empty          = pipe_with("empty")
+    def reverse        = pipe_with("reverse")
+    def sort           = pipe_with("sort")
+    def compact        = pipe_with("compact")
+    def uniq           = pipe_with("uniq")
+    def flatten        = pipe_with("flatten")
+    def keys           = pipe_with("keys")
+    def values         = pipe_with("values")
+    def entries        = pipe_with("entries")
+    def children       = pipe_with(".children")
+
+    def split(separator)
+      pipe_with("split(#{separator.inspect})")
+    end
+
+    def join(separator)
+      pipe_with("join(#{separator.inspect})")
+    end
+
+    def nth(n)
+      pipe_with("nth(#{n})")
+    end
+
+    def limit(n)
+      pipe_with("limit(#{n})")
+    end
+
+    def range(n)
+      pipe_with("range(#{n})")
+    end
+
+    def slice(start, stop)
+      pipe_with("slice(#{start}, #{stop})")
+    end
+
+    def index(value)
+      pipe_with("index(#{value.inspect})")
+    end
+
+    def rindex(value)
+      pipe_with("rindex(#{value.inspect})")
+    end
+
+    def del(value)
+      pipe_with("del(#{value.inspect})")
+    end
+
+    def insert(idx, val)
+      pipe_with("insert(#{idx}, #{val.inspect})")
+    end
+
+    def repeat(n)
+      pipe_with("repeat(#{n})")
+    end
+
+    def trim           = pipe_with("trim()")
+    def ltrim          = pipe_with("ltrim()")
+    def rtrim          = pipe_with("rtrim()")
+    def downcase       = pipe_with("downcase()")
+    def upcase         = pipe_with("upcase()")
+    def ascii_downcase = pipe_with("ascii_downcase()")
+    def ascii_upcase   = pipe_with("ascii_upcase()")
+    def explode        = pipe_with("explode()")
+    def implode        = pipe_with("implode()")
+    def url_encode     = pipe_with("url_encode()")
+    def intern         = pipe_with("intern()")
+
+    def gsub(pattern, replacement)
+      pipe_with("gsub(#{pattern.inspect}, #{replacement.inspect})")
+    end
+
+    def replace(from, to)
+      pipe_with("replace(#{from.inspect}, #{to.inspect})")
+    end
+
+    def test(pattern)
+      pipe_with("test(#{pattern.inspect})")
+    end
+
+    def capture(pattern)
+      pipe_with("capture(#{pattern.inspect})")
+    end
+
+    def abs            = pipe_with("abs()")
+    def ceil           = pipe_with("ceil()")
+    def floor          = pipe_with("floor()")
+    def round          = pipe_with("round()")
+    def trunc          = pipe_with("trunc()")
+    def sqrt           = pipe_with("sqrt()")
+    def ln             = pipe_with("ln()")
+    def log10          = pipe_with("log10()")
+    def exp            = pipe_with("exp()")
+    def negate_val     = pipe_with("negate()")
+    def is_nan         = pipe_with("is_nan()")
+
+    def pow(n)
+      pipe_with("pow(#{n})")
+    end
+
+    def min(other)
+      pipe_with("min(#{other})")
+    end
+
+    def max(other)
+      pipe_with("max(#{other})")
+    end
+
+    # --- Type / logic ---
+
+    def type           = pipe_with("type")
+    def debug          = pipe_with("debug")
+
+    def coalesce(default)
+      pipe_with("coalesce(#{default.inspect})")
+    end
+
+    def base64         = pipe_with("base64()")
+    def base64d        = pipe_with("base64d()")
+    def base64url      = pipe_with("base64url()")
+    def base64urld     = pipe_with("base64urld()")
+    def md5            = pipe_with("md5()")
+    def sha256         = pipe_with("sha256()")
+    def sha512         = pipe_with("sha512()")
+    def from_hex       = pipe_with("from_hex()")
+    def to_hex         = pipe_with("to_hex()")
+    def to_hex_str     = pipe_with("to_hex()")
+
+    def basename       = pipe_with("basename()")
+    def dirname        = pipe_with("dirname()")
+    def extname        = pipe_with("extname()")
+    def stem           = pipe_with("stem()")
+
+    def path_join(other)
+      pipe_with("path_join(#{other.inspect})")
+    end
+
+    def get(key)
+      pipe_with("get(#{key.inspect})")
+    end
+
+    def set(key, val)
+      pipe_with("set(#{key.inspect}, #{val.inspect})")
+    end
+
+    # Access a dict property by key (generates ."key" selector)
+    def property(key)
+      pipe_with(".\"#{key}\"")
+    end
+
+    # Attribute selectors (access attributes of selected nodes)
+    # These generate attribute selector syntax (.url, .lang, etc.)
+
+    def value          = pipe_with(".value")
+    def lang           = pipe_with(".lang")
+    def meta           = pipe_with(".meta")
+    def fence          = pipe_with(".fence")
+    def url            = pipe_with(".url")
+    def alt            = pipe_with(".alt")
+    def title          = pipe_with(".title")
+    def ident          = pipe_with(".ident")
+    def label          = pipe_with(".label")
+    def depth          = pipe_with(".depth")
+    def level          = pipe_with(".level")
+    def item_index     = pipe_with(".index")
+    def ordered        = pipe_with(".ordered")
+    def checked        = pipe_with(".checked")
+    def column         = pipe_with(".column")
+    def row            = pipe_with(".row")
+    def align          = pipe_with(".align")
+    def mdx_name       = pipe_with(".name")
+
+    def update(content)
+      pipe_with("update(#{content.inspect})")
+    end
+
+    def attr(name)
+      pipe_with("attr(#{name.inspect})")
+    end
+
+    def set_attr(name, val)
+      pipe_with("set_attr(#{name.inspect}, #{val.inspect})")
+    end
+
+    def get_title      = pipe_with("get_title")
+    def get_url        = pipe_with("get_url")
+
+    def set_check(val)
+      pipe_with("set_check(#{val})")
+    end
+
+    def set_ref(ref)
+      pipe_with("set_ref(#{ref.inspect})")
+    end
+
+    def set_code_block_lang(lang)
+      pipe_with("set_code_block_lang(#{lang.inspect})")
+    end
+
+    def set_list_ordered(val)
+      pipe_with("set_list_ordered(#{val})")
+    end
+
+    # Convert current value to a code block with the given language.
+    def to_code(lang = nil)
+      lang ? pipe_with("to_code(#{lang.inspect})") : pipe_with("to_code(null)")
+    end
+
+    def to_code_inline = pipe_with("to_code_inline()")
+
+    # Convert current value to a heading of the given depth (1-6).
+    def to_h(depth)
+      pipe_with("to_h(#{depth})")
+    end
+
+    def to_hr          = pipe_with("to_hr()")
+
+    # Create a link node. With all three args no auto-prepend occurs.
+    # With two args the current value becomes the link text.
+    def to_link(url, text = nil, link_title = "")
+      if text
+        pipe_with("to_link(#{url.inspect}, #{text.inspect}, #{link_title.inspect})")
+      else
+        pipe_with("to_link(#{url.inspect}, #{link_title.inspect})")
+      end
+    end
+
+    # Create an image node. With all three args no auto-prepend occurs.
+    # With two args the current value becomes the alt text.
+    def to_image(url, img_alt = nil, img_title = "")
+      if img_alt
+        pipe_with("to_image(#{url.inspect}, #{img_alt.inspect}, #{img_title.inspect})")
+      else
+        pipe_with("to_image(#{url.inspect}, #{img_title.inspect})")
+      end
+    end
+
+    def to_math        = pipe_with("to_math()")
+    def to_math_inline = pipe_with("to_math_inline()")
+    def to_strong      = pipe_with("to_strong()")
+    def to_em          = pipe_with("to_em()")
+    def to_md_text     = pipe_with("to_md_text()")
+
+    # Convert current value to a list item at the given nesting level.
+    def to_md_list(list_level)
+      pipe_with("to_md_list(#{list_level})")
+    end
+
+    # Convert current value to a markdown element with the given node name.
+    def to_md_name(node_name)
+      pipe_with("to_md_name(#{node_name.inspect})")
+    end
+
+    # Build a table row from the given cell values.
+    def to_md_table_row(*cells)
+      pipe_with("to_md_table_row(#{cells.map(&:inspect).join(', ')})")
+    end
+
+    # Build a table cell with content, row index, and column index.
+    def to_md_table_cell(content, r, c)
+      pipe_with("to_md_table_cell(#{content.inspect}, #{r}, #{c})")
+    end
+
+    # Returns the mq query string.
+    # @return [String]
+    def to_query = @expr
+    alias to_s to_query
+
+    class << self
+      # --- Heading selectors: h1 through h6 ---
+      (1..6).each { |n| define_method("h#{n}") { new(".h#{n}") } }
+
+      # Generic heading (any level)
+      def heading    = new(".heading")
+
+      # Block element selectors
+      def code       = new(".code")
+      def paragraph  = new(".p")
+      def blockquote = new(".blockquote")
+      def hr         = new(".hr")
+      def image      = new(".image")
+      def link       = new(".link")
+      def text       = new(".text")
+      def strong     = new(".strong")
+      def emphasis   = new(".emphasis")
+      def delete     = new(".delete")
+      def math       = new(".math")
+      def table      = new(".table")
+      def table_align = new(".table_align")
+      def html       = new(".html")
+      def definition = new(".definition")
+      def footnote   = new(".footnote")
+      def toml       = new(".toml")
+      def yaml       = new(".yaml")
+
+      # Inline element selectors
+      def code_inline  = new(".code_inline")
+      def math_inline  = new(".math_inline")
+      def link_ref     = new(".link_ref")
+      def image_ref    = new(".image_ref")
+      def footnote_ref = new(".footnote_ref")
+      def line_break   = new(".break")
+
+      # Task list selectors
+      def task       = new(".task")
+      def todo       = new(".todo")
+      def done       = new(".done")
+
+      # --- List selector ---
+      def list       = new(".[]")
+
+      # List item at a specific index: .[n]
+      def list_at(n)
+        new(".[#{n}]")
+      end
+
+      # --- Table selectors with row/column indexing ---
+
+      # All cells in a specific row: .[n][]
+      def table_row(n)
+        new(".[#{n}][]")
+      end
+
+      # All cells in a specific column: .[][n]
+      def table_col(n)
+        new(".[][#{n}]")
+      end
+
+      # A specific cell: .[row][col]
+      def table_cell(r, c)
+        new(".[#{r}][#{c}]")
+      end
+
+      # --- MDX selectors ---
+      def mdx_jsx_flow_element  = new(".mdx_jsx_flow_element")
+      def mdx_text_expression   = new(".mdx_text_expression")
+      def mdx_jsx_text_element  = new(".mdx_jsx_text_element")
+      def mdx_flow_expression   = new(".mdx_flow_expression")
+      def mdx_js_esm            = new(".mdx_js_esm")
+
+      # Recursive / deep selector (..)
+      def recursive  = new("..")
+
+      # --- Attribute selectors (as standalone starting points) ---
+      def value      = new(".value")
+      def node_values = new(".values")
+      def lang       = new(".lang")
+      def meta       = new(".meta")
+      def fence      = new(".fence")
+      def url        = new(".url")
+      def alt        = new(".alt")
+      def depth      = new(".depth")
+      def level      = new(".level")
+      def ordered    = new(".ordered")
+      def checked    = new(".checked")
+      def column     = new(".column")
+      def row        = new(".row")
+      def align      = new(".align")
+
+      # Dict property selector: ."key"
+      def property(key)
+        new(".\"#{key}\"")
+      end
+
+      # Class-level select (no leading selector)
+      #
+      # @param filter [Filter, String, nil]
+      # @yield block evaluated in {FilterDSL} context
+      # @return [Query]
+      def select(filter = nil, &block)
+        filter_str = new.send(:resolve_filter, filter, &block)
+        new("select(#{filter_str})")
+      end
+
+      def to_text     = new("to_text()")
+      def to_markdown = new("to_markdown()")
+    end
+
+    private
+
+    def pipe_with(expr)
+      @expr.empty? ? self.class.new(expr) : self.class.new("#{@expr} | #{expr}")
+    end
+
+    def resolve_filter(filter, &block)
+      if block_given?
+        Filter.build(&block)
+      elsif filter.respond_to?(:to_query)
+        filter.to_query
+      else
+        filter.to_s
+      end
+    end
+  end
+
+  # Represents a boolean filter expression for use inside select() and map().
+  #
+  # Filters can be combined with & (and) and | (or):
+  #   contains("foo") & starts_with("bar")
+  #   # => 'contains("foo") and starts_with("bar")'
+  class Filter
+    def initialize(expr)
+      @expr = expr.to_s
+    end
+
+    # Build a filter expression by evaluating a block in {FilterDSL} context.
+    # @yield block in FilterDSL context
+    # @return [String]
+    def self.build(&block)
+      result = FilterDSL.new.instance_eval(&block)
+      result.respond_to?(:to_filter) ? result.to_filter : result.to_s
+    end
+
+    # Combine two filters with boolean AND.
+    def &(other) = self.class.new("#{@expr} and #{other}")
+
+    # Combine two filters with boolean OR.
+    def |(other) = self.class.new("#{@expr} or #{other}")
+
+    def to_filter = @expr
+    alias to_query to_filter
+    alias to_s to_filter
+  end
+
+  # DSL context for building filter expressions inside select/map blocks.
+  #
+  # All methods return a {Filter} that can be combined with & and |.
+  #
+  # @example String matching
+  #   MQ::Query.h2.select { contains("Feature") & starts_with("##") }
+  #
+  # @example Comparison
+  #   MQ::Query.list.select { gt(5) }
+  #
+  # @example Negation
+  #   MQ::Query.select { negate(contains("draft")) }
+  class FilterDSL
+    # String matching
+    def contains(text)    = Filter.new("contains(#{text.inspect})")
+    def starts_with(text) = Filter.new("starts_with(#{text.inspect})")
+    def ends_with(text)   = Filter.new("ends_with(#{text.inspect})")
+    def test(pattern)     = Filter.new("test(#{pattern.inspect})")
+
+    # Regex matching
+    def is_regex_match(pattern)     = Filter.new("is_regex_match(#{pattern.inspect})")
+    def is_not_regex_match(pattern) = Filter.new("is_not_regex_match(#{pattern.inspect})")
+
+    # Comparison operators
+    # These compare the current pipeline value against the given argument.
+    def eq(value)  = Filter.new("eq(#{value.inspect})")
+    def ne(value)  = Filter.new("ne(#{value.inspect})")
+    def gt(value)  = Filter.new("gt(#{value.inspect})")
+    def gte(value) = Filter.new("gte(#{value.inspect})")
+    def lt(value)  = Filter.new("lt(#{value.inspect})")
+    def lte(value) = Filter.new("lte(#{value.inspect})")
+
+    # Type checks
+    def is_mdx  = Filter.new("is_mdx()")
+    def is_none = Filter.new("is_none()")
+    def is_nan  = Filter.new("is_nan()")
+    def type    = Filter.new("type")
+
+    # String transforms usable in filter context
+    def length         = Filter.new("length")
+    def ascii_downcase = Filter.new("ascii_downcase()")
+    def ascii_upcase   = Filter.new("ascii_upcase()")
+    def trim           = Filter.new("trim()")
+    def empty          = Filter.new("empty")
+    def add            = Filter.new("add")
+
+    # Negate a filter expression with not().
+    # Use +negate+ instead of +not+ since +not+ is a Ruby keyword.
+    #
+    # @example
+    #   MQ::Query.select { negate(contains("draft")) }
+    #   # => 'select(not(contains("draft")))'
+    def negate(filter) = Filter.new("not(#{filter})")
+  end
+end

data/lib/mq.rb

@@ -1,12 +1,8 @@
 # frozen_string_literal: true
 
-begin
-  # Try to load the compiled extension
-  RUBY_VERSION =~ /(\d+\.\d+)/
-  require_relative "mq/#{Regexp.last_match(1)}/mq_ruby"
-rescue LoadError
-  require_relative "mq/mq_ruby"
-end
+require_relative "mq/mq_ruby"
+
+require_relative "mq/query"
 
 module MQ
   class Error < StandardError; end
@@ -46,15 +42,17 @@ module MQ
   end
 
   class << self
-    # Run an mq query on the provided content
+    # Run an mq query on the provided content.
+    # Accepts either a query string or a {Query} object.
     #
-    # @param code [String] The mq query string
+    # @param code [String, Query] The mq query string or Query builder object
     # @param content [String] The markdown/HTML/text content to process
     # @param options [Options, nil] Optional configuration options
     # @return [Result] The query results
     def run(code, content, options = nil)
+      query = code.respond_to?(:to_query) ? code.to_query : code
       options_hash = options&.to_h
-      _run(code, content, options_hash)
+      _run(query, content, options_hash)
     end
 
     # Convert HTML to Markdown

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mq-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.22
+  version: 0.1.23
 platform: ruby
 authors:
 - Takahiro Sato
@@ -78,6 +78,7 @@ files:
 - README.md
 - extconf.rb
 - lib/mq.rb
+- lib/mq/query.rb
 - src/lib.rs
 - src/result.rs
 - src/value.rs
@@ -94,14 +95,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Ruby bindings for mq Markdown processing
 test_files: []