Convenience type for query strings.

tanaylab · Jun 4, 2024 · 3ec9716 · 3ec9716
1 parent 5db4a0c
commit 3ec9716
Show file tree

Hide file tree

Showing 9 changed files with 72 additions and 30 deletions.
diff --git a/docs/v0.1.0/.documenter-siteinfo.json b/docs/v0.1.0/.documenter-siteinfo.json
@@ -1 +1 @@
-{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-06-01T20:43:25","documenter_version":"1.4.1"}}
+{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-06-04T08:50:31","documenter_version":"1.4.1"}}
diff --git a/docs/v0.1.0/index.html b/docs/v0.1.0/index.html
@@ -1226,6 +1226,12 @@ <h1 id="Index">
 </a>
 </li>
 <li>
+<a href="queries.html#Daf.Queries.QueryString">
+<code>Daf.Queries.QueryString
+</code>
+</a>
+</li>
+<li>
 <a href="queries.html#Daf.Queries.Xor">
 <code>Daf.Queries.Xor
 </code>

diff --git a/docs/v0.1.0/objects.inv b/docs/v0.1.0/objects.inv
diff --git a/docs/v0.1.0/queries.html b/docs/v0.1.0/queries.html
@@ -302,7 +302,7 @@ <h2 id="Construction">
 <div>
 <pre>
 <code class="language-julia hljs">Query(
-    query::Union{AbstractString, Query},
+    query::QueryString,
     operand_only::Maybe{Type{QueryOperation}} = nothing,
 ) &lt;: QueryOperation
 </code>
@@ -510,6 +510,28 @@ <h2 id="Construction">
 </div>
 </section>
 </article>
+<article class="docstring">
+<header>
+<a class="docstring-article-toggle-button fa-solid fa-chevron-down" href="javascript:;" title="Collapse docstring">
+</a>
+<a class="docstring-binding" id="Daf.Queries.QueryString" href="#Daf.Queries.QueryString">
+<code>Daf.Queries.QueryString
+</code>
+</a> — 
+<span class="docstring-category">Type
+</span>
+</header>
+<section>
+<div>
+<p>Most operations that take a query allow passing a string to be parsed into a query, or an actual 
+<a href="queries.html#Daf.Queries.Query">
+<code>Query
+</code>
+</a> object. This type is used as a convenient notation for such query parameters.
+</p>
+</div>
+</section>
+</article>
 <h2 id="Functions">
 <a class="docs-heading-anchor" href="#Functions">Functions
 </a>
@@ -534,7 +556,7 @@ <h2 id="Functions">
 <pre>
 <code class="language-julia hljs">get_query(
     daf::DafReader,
-    query::Union{Query, AbstractString};
+    query::QueryString;
     [cache::Bool = true]
 )::Union{StorageScalar, NamedVector, NamedMatrix}
 </code>
@@ -580,7 +602,7 @@ <h2 id="Functions">
 <pre>
 <code class="language-julia hljs">get_frame(
     daf::DafReader,
-    axis::Union{Query, AbstractString},
+    axis::QueryString,
     [columns::Maybe{Union{AbstractVector{&lt;:AbstractString}, QueryColumns}} = nothing;
     cache::Bool = true]
 )::DataFrame end
@@ -717,7 +739,7 @@ <h2 id="Functions">
 </strong> to say is:
 </p>
 <pre>
-<code class="nohighlight hljs">QueryColumns = AbstractVector{Pair{AbstractString, Union{AbstractString, Query}}}
+<code class="nohighlight hljs">QueryColumns = AbstractVector{Pair{AbstractString, QueryString}}
 </code>
 </pre>
 <p>But what we are 
@@ -751,7 +773,7 @@ <h2 id="Functions">
 <pre>
 <code class="language-julia hljs">full_vector_query(
     axis_query::Query,
-    vector_query::Union{AbstractString, Query},
+    vector_query::QueryString,
     vector_name::Maybe{AbstractString} = nothing,
 )::Query
 </code>
@@ -783,7 +805,7 @@ <h2 id="Functions">
 <section>
 <div>
 <pre>
-<code class="language-julia hljs">query_result_dimensions(query::Union{Query, AbstractString})::Int
+<code class="language-julia hljs">query_result_dimensions(query::QueryString)::Int
 </code>
 </pre>
 <p>Return the number of dimensions (-1 - names, 0 - scalar, 1 - vector, 2 - matrix) of the results of a 
@@ -807,7 +829,7 @@ <h2 id="Functions">
 <section>
 <div>
 <pre>
-<code class="language-julia hljs">is_axis_query(query::Union{Query, AbstractString})::Bool
+<code class="language-julia hljs">is_axis_query(query::QueryString)::Bool
 </code>
 </pre>
 <p>Returns whether the 
@@ -4047,6 +4069,12 @@ <h2 id="Index">
 </a>
 </li>
 <li>
+<a href="queries.html#Daf.Queries.QueryString">
+<code>Daf.Queries.QueryString
+</code>
+</a>
+</li>
+<li>
 <a href="queries.html#Daf.Queries.Xor">
 <code>Daf.Queries.Xor
 </code>

diff --git a/docs/v0.1.0/search_index.js b/docs/v0.1.0/search_index.js
diff --git a/docs/v0.1.0/views.html b/docs/v0.1.0/views.html
@@ -420,7 +420,7 @@ <h1 id="Views">
 </strong> to say is:
 </p>
 <pre>
-<code class="nohighlight hljs">ViewAxes = AbstractVector{Pair{AbstractString, Maybe{Union{AbstractString, Query}}}}
+<code class="nohighlight hljs">ViewAxes = AbstractVector{Pair{AbstractString, Maybe{QueryString}}}
 </code>
 </pre>
 <p>But what we are 
@@ -570,7 +570,7 @@ <h1 id="Views">
 </strong> to say is:
 </p>
 <pre>
-<code class="nohighlight hljs">ViewData = AbstractVector{Pair{DataKey, Maybe{Union{AbstractString, Query}}}}
+<code class="nohighlight hljs">ViewData = AbstractVector{Pair{DataKey, Maybe{QueryString}}}
 </code>
 </pre>
 <p>But what we are 

diff --git a/src/queries.jl b/src/queries.jl
@@ -28,6 +28,7 @@ export OrNot
 export Query
 export QueryColumns
 export QuerySequence
+export QueryString
 export Xor
 export XorNot
 export full_vector_query
@@ -71,7 +72,7 @@ import Base.MathConstants.pi
 
 """
     Query(
-        query::Union{AbstractString, Query},
+        query::QueryString,
         operand_only::Maybe{Type{QueryOperation}} = nothing,
     ) <: QueryOperation
 
@@ -118,6 +119,12 @@ work). For the full list of valid combinations, see [`NAMES_QUERY`](@ref), [`SCA
 """
 abstract type Query <: QueryOperation end
 
+"""
+Most operations that take a query allow passing a string to be parsed into a query, or an actual [`Query`](@ref) object.
+This type is used as a convenient notation for such query parameters.
+"""
+QueryString = Union{Query, AbstractString}
+
 """
 `NAMES_QUERY` :=
 ( [`Names`](@ref) `scalars`
@@ -1608,15 +1615,15 @@ end
 
 function Base.getindex(
     daf::DafReader,
-    query::Union{Query, AbstractString},
+    query::QueryString,
 )::Union{AbstractSet{<:AbstractString}, AbstractVector{<:AbstractString}, StorageScalar, NamedArray}
     return get_query(daf, query)
 end
 
 """
     get_query(
         daf::DafReader,
-        query::Union{Query, AbstractString};
+        query::QueryString;
         [cache::Bool = true]
     )::Union{StorageScalar, NamedVector, NamedMatrix}
 
@@ -1682,7 +1689,7 @@ function query_result_dimensions(query_string::AbstractString)::Int
 end
 
 """
-    is_axis_query(query::Union{Query, AbstractString})::Bool
+    is_axis_query(query::QueryString)::Bool
 
 Returns whether the `query` specifies a (possibly masked) axis. This also verifies the query is syntactically valid,
 though it may still fail if applied to specific data due to invalid data values or types.
@@ -1704,7 +1711,7 @@ function get_is_axis_query(fake_query_state::FakeQueryState)::Bool
 end
 
 """
-    query_result_dimensions(query::Union{Query, AbstractString})::Int
+    query_result_dimensions(query::QueryString)::Int
 
 Return the number of dimensions (-1 - names, 0 - scalar, 1 - vector, 2 - matrix) of the results of a `query`. This also
 verifies the query is syntactically valid, though it may still fail if applied to specific data due to invalid data
@@ -3790,7 +3797,7 @@ In all cases the (full) query must return a value for each entry of the axis.
     Due to Julia's type system limitations, there's just no way for the system to enforce the type of the pairs
     in this vector. That is, what we'd **like** to say is:
 
-        QueryColumns = AbstractVector{Pair{AbstractString, Union{AbstractString, Query}}}
+        QueryColumns = AbstractVector{Pair{AbstractString, QueryString}}
 
     But what we are **forced** to say is:
 
@@ -3804,7 +3811,7 @@ QueryColumns = AbstractVector{<:Pair}
 """
     get_frame(
         daf::DafReader,
-        axis::Union{Query, AbstractString},
+        axis::QueryString,
         [columns::Maybe{Union{AbstractVector{<:AbstractString}, QueryColumns}} = nothing;
         cache::Bool = true]
     )::DataFrame end
@@ -3825,7 +3832,7 @@ specifying `cache = false`, or release the cached data using [`empty_cache!`](@r
 """
 function get_frame(
     daf::DafReader,
-    axis::Union{Query, AbstractString},
+    axis::QueryString,
     columns::Maybe{Union{AbstractVector{<:AbstractString}, QueryColumns}} = nothing;
     cache::Bool = true,
 )::DataFrame
@@ -3889,7 +3896,7 @@ end
 """
     full_vector_query(
         axis_query::Query,
-        vector_query::Union{AbstractString, Query},
+        vector_query::QueryString,
         vector_name::Maybe{AbstractString} = nothing,
     )::Query
 
@@ -3899,7 +3906,7 @@ in views.
 """
 function full_vector_query(
     axis_query::Query,
-    vector_query::Union{AbstractString, Query},
+    vector_query::QueryString,
     vector_name::Maybe{AbstractString} = nothing,
 )::Query
     if vector_name !== nothing && vector_query == "="

diff --git a/src/queries.md b/src/queries.md
@@ -9,6 +9,7 @@ Daf.Queries
 ```@docs
 Daf.Queries.Query
 Daf.Queries.@q_str
+Daf.Queries.QueryString
 ```
 
 ## Functions

diff --git a/src/views.jl b/src/views.jl
@@ -84,7 +84,7 @@ will expose the `batch` axis, but only including the batches whose `age` propert
     Due to Julia's type system limitations, there's just no way for the system to enforce the type of the pairs
     in this vector. That is, what we'd **like** to say is:
 
-        ViewAxes = AbstractVector{Pair{AbstractString, Maybe{Union{AbstractString, Query}}}}
+        ViewAxes = AbstractVector{Pair{AbstractString, Maybe{QueryString}}}
 
     But what we are **forced** to say is:
 
@@ -138,7 +138,7 @@ The order of the axes does not matter, so
     Due to Julia's type system limitations, there's just no way for the system to enforce the type of the pairs
     in this vector. That is, what we'd **like** to say is:
 
-        ViewData = AbstractVector{Pair{DataKey, Maybe{Union{AbstractString, Query}}}}
+        ViewData = AbstractVector{Pair{DataKey, Maybe{QueryString}}}
 
     But what we are **forced** to say is:
 
@@ -251,7 +251,7 @@ function viewer(
 
     for (key, query) in data
         @assert key isa DataKey
-        @assert query isa Maybe{Union{AbstractString, Query}}
+        @assert query isa Maybe{QueryString}
     end
 
     collected_axes::Dict{AbstractString, Fetch{AbstractVector{<:AbstractString}}} = collect_axes(name, daf, axes)
@@ -287,7 +287,7 @@ function collect_scalars(
     return collected_scalars
 end
 
-function prepare_query(maybe_query::Maybe{Union{AbstractString, Query}})::Maybe{Union{AbstractString, Query}}
+function prepare_query(maybe_query::Maybe{QueryString})::Maybe{QueryString}
     if maybe_query isa AbstractString
         maybe_query = strip(maybe_query)  # NOJET
         if maybe_query != "="
@@ -304,7 +304,7 @@ function collect_scalar(
     daf::DafReader,
     collected_scalars::Dict{AbstractString, Fetch{StorageScalar}},
     scalar_name::AbstractString,
-    scalar_query::Maybe{Union{AbstractString, Query}},
+    scalar_query::Maybe{QueryString},
 )::Nothing
     if scalar_name == "*"
         for scalar_name in scalars_set(daf)
@@ -340,7 +340,7 @@ function collect_axes(
     collected_axes = Dict{AbstractString, Fetch{AbstractVector{<:AbstractString}}}()
     for (axis, query) in axes
         @assert axis isa AbstractString
-        @assert query isa Maybe{Union{AbstractString, Query}}
+        @assert query isa Maybe{QueryString}
         collect_axis(view_name, daf, collected_axes, axis, prepare_query(query))
     end
     return collected_axes
@@ -351,7 +351,7 @@ function collect_axis(
     daf::DafReader,
     collected_axes::Dict{AbstractString, Fetch{AbstractVector{<:AbstractString}}},
     axis_name::AbstractString,
-    axis_query::Maybe{Union{AbstractString, Query}},
+    axis_query::Maybe{QueryString},
 )::Nothing
     if axis_name == "*"
         for axis_name in axes_set(daf)
@@ -412,7 +412,7 @@ function collect_vector(
     collected_vectors::Dict{AbstractString, Dict{AbstractString, Fetch{StorageVector}}},
     axis_name::AbstractString,
     vector_name::AbstractString,
-    vector_query::Maybe{Union{AbstractString, Query}},
+    vector_query::Maybe{QueryString},
 )::Nothing
     if axis_name == "*"
         for axis_name in keys(collected_axes)
@@ -483,7 +483,7 @@ function collect_matrix(
     rows_axis_name::AbstractString,
     columns_axis_name::AbstractString,
     matrix_name::AbstractString,
-    matrix_query::Maybe{Union{AbstractString, Query}},
+    matrix_query::Maybe{QueryString},
 )::Nothing
     if rows_axis_name == "*"
         for rows_axis_name in keys(collected_axes)