goim: github.com/BurntSushi/goim/imdb/search Index | Examples | Files

package search

import "github.com/BurntSushi/goim/imdb/search"

Package search provides a convenient interface that can quickly search an IMDb database loaded with Goim. Each search result corresponds to exactly one entity in the database, where an entity is (currently) either a movie, a TV show, an episode or an actor/actress.

The search interface in this package has two forms. One of them is with regular Go method calls:

neo := New(db).Text("keanu reeves")
s := New(db).Text("the matrix").Years(1999, 2003).Cast(neo)

And the other is with a special query string syntax:

s, err := Query(db, "the matrix {years:1999-2003} {cast:keanu reeves}")

The above two queries are functionally equivalent. (They both return entities with names similar to "the matrix", released in the years 1999-2003 where Keanu Reeves was on the cast.) There are more elaborate examples included in this package. There are even more examples in Goim, which can be seen in the usage information for the search command. See 'goim help search'.

Beta

Please consider this package as beta material. I am reasonably happy with what is here so far and I don't expect to change it. But it hasn't been used much, so I'd like to wait before declaring it stable.

Index

Examples

Package Files

commands.go doc.go search.go

Variables

var Commands []Command

Commands represents all available search directives that are available in a search query string.

type Chooser Uses

type Chooser func([]Result, string) (*Result, error)

Chooser corresponds to a function called by the searcher in this package to resolve ambiguous query parameters. For example, if a TV show is specified with '{show:supernatural}' and there is more than one good hit, then the chooser function will be called.

If the search result returned is nil and the error is nil, then the search will return no results without error.

If an error is returned, then the search stops and the error is passed to the caller of Searcher.Results.

If no chooser function is supplied, then the first search result is always picked. If there are no results, then the query stops and returns no results.

The string provided to the chooser function is a short noun phrase that represents the thing being searched. (e.g., "TV show".)

type Command Uses

type Command struct {
    Name        string
    Synonyms    []string
    Description string
}

Command represents a single search directive available in a search query string. Each command has a canonical name, a list of possibly empty synonyms and a brief description describing what the directive does.

type Credit Uses

type Credit struct {
    ActorId   imdb.Atom
    MediaId   imdb.Atom
    Character string
    Position  int
    Attrs     string
}

Credit represents the credit information available in a search result. This is distinct from the normal imdb.Credit type since it stores atom identifiers instead of the entities themselves.

func (Credit) Valid Uses

func (c Credit) Valid() bool

Valid returns true if and only if this credit belongs to a valid movie and a valid actor.

type Result Uses

type Result struct {
    Entity imdb.EntityKind
    Id     imdb.Atom
    Name   string
    Year   int

    // Arbitrary additional data specific to an entity.
    // e.g., Whether a movie is straight to video or made for TV.
    // e.g., The season and episode number of a TV episode.
    Attrs string

    // Similarity corresponds to the amount of similarity between the name
    // given in the query and the name returned in this result.
    // This is set to -1 when fuzzy searching is not available (e.g., for
    // SQLite or Postgres when the 'pg_trgm' extension isn't enabled).
    Similarity float64

    // If an IMDb rank exists for a search result, it will be stored here.
    Rank imdb.UserRank

    // If the search accesses credit information, then it will be stored here.
    Credit Credit
}

Result represents the data returned for each result of a search.

func (Result) GetEntity Uses

func (sr Result) GetEntity(db csql.Queryer) (imdb.Entity, error)

GetEntity returns a value satisfying the imdb.Entity interface corresponding to the search result. The Entity returned should correspond to the entity type in the search result.

func (Result) String Uses

func (sr Result) String() string

type Searcher Uses

type Searcher struct {
    // contains filtered or unexported fields
}

Searcher represents the parameters of a search.

func New Uses

func New(db *imdb.DB) *Searcher

New returns a bare-bones searcher with no text to search. Once all options are set, the search can be executed with the Results method. Each result returned corresponds to precisely one entity in the database.

(A bare-bones searcher can still have text to search with the Query method.)

Example New finds the top 10 ranked Simpsons episodes with 500 or more votes using methods on a Searcher value.

Code:

var db *imdb.DB // needs to be created with imdb.Open

s := New(db)
s.Votes(500, -1).Sort("rank", "desc").Sort("votes", "desc").Limit(10)
s.Tvshow(New(db).Text("the simpsons"))

results, err := s.Results()
if err != nil {
    log.Fatal(err)
}
for _, result := range results {
    log.Println(result)
}

func Query Uses

func Query(db *imdb.DB, query string) (*Searcher, error)

Query creates a new searcher with the text and options provided in the search query string. The query has two types of items: regular text that is searched against all entity names and directives that set search options. The search options correspond to the method calls on a Searcher value. The list of available directives is in the package level Commands variable.

A directive begins and ends with '{' and '}' and is of the form {NAME[:ARGUMENT]}, where NAME is the name of the directive and argument is an argument for the directive. Each directive either requires no argument or requires a single argument.

Tokens in the query that aren't directives are appended together and used as text to search against all entity names. This text may be empty. If the text contains the wildcards '%' (to match any sequence of characters) or '_' (to match any single character), then the database's substring matching operator is used (always case insensitive). Otherwise, fuzzy searching is used when it's enabled (which is only possible with PostgreSQL and the 'pg_trgm' extension). If fuzzy searching isn't available, regular string equality is used.

Query is the equivalent of calling New(db).Query(query).

It is safe to give untrusted input as a query.

Example Query finds the top 10 ranked Simpsons episodes with 500 or more votes using a query string.

Code:

var db *imdb.DB // needs to be created with imdb.Open

q := `
		{show:the simpsons} {votes:500-}
		{sort:rank desc} {sort:votes desc} {limit:10}
	`
s, err := Query(db, q)
if err != nil {
    log.Fatal(err)
}

results, err := s.Results()
if err != nil {
    log.Fatal(err)
}
for _, result := range results {
    log.Println(result)
}

func (*Searcher) Atom Uses

func (s *Searcher) Atom(id imdb.Atom) *Searcher

Atom specifies that the result returned must have the atom identifier given. Note that this guarantees that the number of results will either be 0 or 1.

func (*Searcher) Billed Uses

func (s *Searcher) Billed(min, max int) *Searcher

Billed specifies that the results---when they correspond to credits---must be in the billed range provided. For example, when showing credits for an actor, this will restrict the results to movies where the actor has a billed position in this range. Similarly for showing credits for a movie. The range is inclusive. Either min or max can be disabled with a value of -1.

func (*Searcher) Cast Uses

func (s *Searcher) Cast(cast *Searcher) *Searcher

Cast specifies a sub-search that will be performed when Results is called. The cast member returned restricts the results of the parent search to only include credits for the cast member. If no cast member is found, then the parent search quits and returns no results.

func (*Searcher) Chooser Uses

func (s *Searcher) Chooser(chooser Chooser) *Searcher

Chooser specifies the function to call when a sub-search returns 2 or more good hits. See the documentation for the Chooser type for details.

func (*Searcher) Credits Uses

func (s *Searcher) Credits(credits *Searcher) *Searcher

Credits specifies a sub-search that will be performed when Results is called. The entity returned restricts the results of the parent search to only include credits for the entity. (Note that TV shows generally don't have credits associated with them.) If no entity is found, then the parent search quits and returns no results.

func (*Searcher) Entity Uses

func (s *Searcher) Entity(e imdb.EntityKind) *Searcher

Entity adds the given entity to the search. Results only belonging to the entities in the search will be returned. This function may called more than once to specify additional entities to allow.

func (*Searcher) Episodes Uses

func (s *Searcher) Episodes(min, max int) *Searcher

Episodes specifies that the results must be in the range of episodes given. The range is inclusive. Either min or max can be disabled with a value of -1.

func (*Searcher) Genre Uses

func (s *Searcher) Genre(name string) *Searcher

Genre adds the named genre to the search. Results only belonging to the genre given are returned. If multiple genres are specified in the search, then they are combined disjunctively. The genre name must correspond to one of the names in imdb.EnumGenres (case insensitive). Otherwise, it will be silently ignored.

func (*Searcher) GoodThreshold Uses

func (s *Searcher) GoodThreshold(diff float64) *Searcher

GoodThreshold sets the threshold at which a result is considered "good" relative to other results returned. This is used to automatically pick a good hit from sub-searches (like for a TV show). Namely, if the difference in similarity between the first and second hits is greater than or equal to the threshold given, then the first hit is automatically returned.

By default, the threshold is set to 0.25.

Set the threshold to 1.0 to disable this behavior.

func (*Searcher) Limit Uses

func (s *Searcher) Limit(n int) *Searcher

Limit restricts the number of results to the limit given. If Limit is never specified, then the search defaults to a limit of 30.

If limit is -1, then it is disabled. (Be Careful!)

func (*Searcher) MPAA Uses

func (s *Searcher) MPAA(name string) *Searcher

MPAA adds the MPAA rating to the search. Only results with the given MPAA rating are returned. If multiple MPAA ratings are specified in the search, then they are combined disjunctively. The MPAA rating must correspond to one of the ratings in imdb.EnumMPAA (case insensitive). Otherwise, it will be silently ignored.

func (*Searcher) NoTvMovies Uses

func (s *Searcher) NoTvMovies() *Searcher

NoTvMovies filters out "made for TV" movies from a search.

func (*Searcher) NoVideoMovies Uses

func (s *Searcher) NoVideoMovies() *Searcher

NoVideoMovies filters out "made for video" movies from a search.

func (*Searcher) Pick Uses

func (s *Searcher) Pick(rs []Result) (*Result, error)

Pick returns the best match in a list of results. If results is empty, then a nil *Result and a nil error are returned.

Pick will try to choose the "best" match by comparing the similarity of the top hit with the similarity of the second hit. If the similarity is greater than the "Good Threshold" (which is settable with GoodThreshold), then the first hit is returned.

Otherwise, this searcher's chooser function is invoked. (And if that isn't set, the first hit is returned.) Any errors returned by the chooser function are returned here.

func (*Searcher) Query Uses

func (s *Searcher) Query(query string) error

Query appends the search query string to the current searcher. See the package level Query function for details on the format of the search query string.

It is safe to give untrusted input as a query.

func (*Searcher) Ranks Uses

func (s *Searcher) Ranks(min, max int) *Searcher

Ranks specifies that the results must be in the range of ranks given. The range is inclusive. Note that the minimum rank is 0 and the maximum is 100. Either min or max can be disabled with a value of -1.

func (*Searcher) Results Uses

func (s *Searcher) Results() (rs []Result, err error)

Results executes the parameters of the search and returns the results.

func (*Searcher) Seasons Uses

func (s *Searcher) Seasons(min, max int) *Searcher

Seasons specifies that the results must be in the range of seasons given. The range is inclusive. Either min or max can be disabled with a value of -1.

func (*Searcher) SimilarThreshold Uses

func (s *Searcher) SimilarThreshold(t float64) *Searcher

SimilarThreshold sets the similarity threshold at which results from a fuzzy text search are cutoff. Results with a similarity threshold lower than what's given won't be returned. The value should be in the inclusive inteval [0, 1.0]. By default, the threshold is set to 0.4.

func (*Searcher) Sort Uses

func (s *Searcher) Sort(column, order string) *Searcher

Sort specifies the order in which to return the results. Note that Sort can be called multiple times. Each call adds the column and order to the current sort criteria.

func (*Searcher) Text Uses

func (s *Searcher) Text(text string) *Searcher

Text adds the given string to the query string as plain text. It is not parsed for search directives.

func (*Searcher) Tvshow Uses

func (s *Searcher) Tvshow(tvs *Searcher) *Searcher

Tvshow specifies a sub-search that will be performed when Results is called. The TV show returned by this sub-search will be used to filter the results of its parent search. If no TV show is found, then the search quits and returns no results. If more than one good matching TV show is found, then the searcher's "chooser" is called. (See the documentation for the Chooser type.)

func (*Searcher) Votes Uses

func (s *Searcher) Votes(min, max int) *Searcher

Votes specifies that the results must be in the range of votes given. The range is inclusive. Either min or max can be disabled with a value of -1.

func (*Searcher) Years Uses

func (s *Searcher) Years(min, max int) *Searcher

Years specifies that the results must be in the range of years given. The range is inclusive. Either min or max can be disabled with a value of -1.

Package search imports 8 packages (graph) and is imported by 1 packages. Updated 2016-07-16. Refresh now. Tools for package owners.