Debug.Assert(!overrideUrl.Contains("?")) about sharpbucket

[asherber]

I'm interested in this as well. If filtering is a possibility, can we have a discussion about the design and what method signatures would look like?

[asherber]

I was looking some more at the Bitbucket filter language, and also at the design of SharpBucket. First off @anh-duc-le, the code you cite is just checking to make sure that there is no ? character before any passed-in parameters are added, which makes sense. It doesn't prevent the user of filters.

Because the filter language is relatively complex, I suggest that the best way to implement it is to allow the user to pass in a string with exactly the filter they want. The alternative would be to spend time writing some kind of filter builder for SharpBucket, and those can get complicated quickly. The only difference from the syntax specified here would be that any strings should have single quotes instead of double quotes. This allows the user to pass in a filter like foo='bar' instead of foo=\"bar\". SharpBucket would replace all single quotes with double quotes before sending the query to Bitbucket.

Here's a simple implementation, for the RepositoriesEndPoint. I have verified that this works as expected.

internal class FilterQuery: Dictionary<string, object>
{
    public FilterQuery(string filter) 
    {
        Add("q", filter.Replace('\'', '"'));
    }
}

public List<Repository> ListRepositories(string accountName, string filter, int max=0)
{
    var overrideUrl = _baseUrl + accountName + "/";
    return GetPaginatedValues<Repository>(overrideUrl, max, new FilterQuery(filter));
}

var filter = "project.key = 'foo' and name ~ 'bar' and created_on > 2018-06-01";
var repos = endPoint.ListRepositories("accountId", filter);

If this approach looks okay, I'll implement for the supported endpoints/resources (repositories, branches, tags, pull requests) and submit a PR.

[asherber]

This approach could also be extended to allow for sorting in addition to filtering. I've got most of the work done but will hold off on the PR for feedback here.

[mnivet]

I'm agree that creating a filter builder is not trivial and it's something that may be added later.
And exposing a raw string for the filter feature is a good proposition to quickly offer the feature to users.

But converting single quotes into double quotes may be a not so good idea.
First because it's not as "raw" as we can expect from an API that ask for a string
And mainly because we have no idea about how escaping should be done with that conversion.

Exemple: I want to search for Pull requests that contains the text "Mike doesn't approve" as the reason, then I will write my code like that:

var filter = "reason = \"Mike doesn't approve\"";
var repos = endPoint.ListPullRequests("accountId", "repository", filter);

And it won't work if you replace single quotes by doubles quotes magically behind that raw string

[asherber]

Good point, I was hasty in just converting single quotes to doubles.

I still think that using single quotes as the string delimiter is a good way to go -- it allows the user to write the vast majority of query strings without having to escape anything, and it follows the SQL convention that most users will be familiar with.

What if we keep with SQL conventions and handle escaping like this:

var filter = "reason = 'Mike doesn''t approve";

To me, that approach feels better than always having to escape double quotes, and the usage can easily be explained in the docs (and glossed in the XML docs as well).

[mnivet]

Handling double single quotes is better but IMO it's not the goal of SharpBucket to natively use another way to write raw filter strings than what Bitbkucket do.

Actual Bitbucket documentation doesn't explain how to escape double quotes in their filter language. Maybe it use standard backslash escaping ? Maybe not.
Adding another transformation layer above something that is not fully known is not confortable.

I would be more comfortable to provide a static helper that allow to explicitly convert single quotes strings into double quotes strings for people that want to write strings with simple quotes like you suggest, than to do that by default in the exposed methods. Like that if an edge case is broken by that additional transformation layer, it can be easily bypassed by the caller that found that edge case.

So, what I expect is something like:

var filter = FilterBuilder.FromSingleQuotedString("reason = 'Mike doesn''t approve'");
var repos = endPoint.ListPullRequests("accountId", "repository", filter);

[asherber]

Okay, I see your point and will make the changes.

[mnivet]

Pull Request #86 is merged