htslib.hts_expr source code

1 /*  expr.c -- filter expression parsing and processing.
2 
3     Copyright (C) 2020 Genome Research Ltd.
4 
5     Author: James Bonfield <jkb@sanger.ac.uk>
6 
7 Permission is hereby granted, free of charge, to any person obtaining a copy
8 of this software and associated documentation files (the "Software"), to deal
9 in the Software without restriction, including without limitation the rights
10 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 copies of the Software, and to permit persons to whom the Software is
12 furnished to do so, subject to the following conditions:
13 
14 The above copyright notices and this permission notice shall be included in
15 all copies or substantial portions of the Software.
16 
17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
23 DEALINGS IN THE SOFTWARE.  */
24 module htslib.hts_expr;
25 
26 import htslib.kstring: kstring_t;
27 
28 @system:
29 nothrow:
30 @nogc:
31 
32 extern (C):
33 
34 /// Holds a filter variable.  This is also used to return the results.
35 /**
36  * Note we cope with zero-but-true in order to implement a basic
37  * "exists(something)" check where "something" may even be zero.
38  *
39  * Eg in the aux tag searching syntax, "[NM]" should return true if
40  * NM tag exists even if zero.
41  * Take care when negating this. "[NM] != 0" will be true when
42  * [NM] is absent, thus consider "[NM] && [NM] != 0".
43  */
44 struct hts_expr_val_t
45 {
46     char is_str; // Use .s vs .d
47     char is_true; // Force true if even zero
48     kstring_t s; // is_str and empty s permitted (eval as false)
49     double d; // otherwise this
50 }
51 
52 /// Frees a hts_expr_val_t type.
53 void hts_expr_val_free(hts_expr_val_t* f);
54 
55 /// Opaque hts_filter_t type.  Definition in hts_expr.c
56 struct hts_filter_t;
57 
58 /// For static initialisation of hts_expr_val_t values
59 
60 /// Creates a filter for expression "str".
61 /** @param str    The filter expression
62  *  @return       A pointer on success, NULL on failure
63  */
64 hts_filter_t* hts_filter_init(const(char)* str);
65 
66 /// Frees an hts_filter_t created via hts_filter_init
67 /** @param filt    The filter pointer.
68  */
69 void hts_filter_free(hts_filter_t* filt);
70 
71 /// Type for expression symbol lookups; name -> value.
72 alias hts_expr_sym_func = int function(
73     void* data,
74     char* str,
75     char** end,
76     hts_expr_val_t* res);
77 
78 /// Evaluates a filter expression and returns the value
79 /** @param filt      The filter, produced by hts_filter_init
80  *  @param data      Arbitrary caller data, passed into sym_func
81  *  @param sym_func  Callback function to lookup variables.
82  *  @param res       Filled out with the result of the filter evaluation
83  *  @return          Returns 0 on success, -1 on failure
84  *
85  *  sym_func and data may be NULL if the caller does not need its own data
86  *  pointer or if it has no variables to lookup.
87  *
88  *  The type of the returned result may be numeric of string, as defined by
89  *  the is_str member.  It can also be explicitly defined to be true even
90  *  for a null value.  This may be used to check for the existence of
91  *  something, irrespective of whether that something evaluates to zero.
92  */
93 int hts_filter_eval(
94     hts_filter_t* filt,
95     void* data,
96     int function() sym_func,
97     hts_expr_val_t* res);
98 
99 /* HTS_EXPR_H */