Documentation
¶
Overview ¶
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 ¶
- Variables
- type Chooser
- type Command
- type Credit
- type Result
- type Searcher
- func (s *Searcher) Atom(id imdb.Atom) *Searcher
- func (s *Searcher) Billed(min, max int) *Searcher
- func (s *Searcher) Cast(cast *Searcher) *Searcher
- func (s *Searcher) Chooser(chooser Chooser) *Searcher
- func (s *Searcher) Credits(credits *Searcher) *Searcher
- func (s *Searcher) Entity(e imdb.EntityKind) *Searcher
- func (s *Searcher) Episodes(min, max int) *Searcher
- func (s *Searcher) Genre(name string) *Searcher
- func (s *Searcher) GoodThreshold(diff float64) *Searcher
- func (s *Searcher) Limit(n int) *Searcher
- func (s *Searcher) MPAA(name string) *Searcher
- func (s *Searcher) NoTvMovies() *Searcher
- func (s *Searcher) NoVideoMovies() *Searcher
- func (s *Searcher) Pick(rs []Result) (*Result, error)
- func (s *Searcher) Query(query string) error
- func (s *Searcher) Ranks(min, max int) *Searcher
- func (s *Searcher) Results() (rs []Result, err error)
- func (s *Searcher) Seasons(min, max int) *Searcher
- func (s *Searcher) SimilarThreshold(t float64) *Searcher
- func (s *Searcher) Sort(column, order string) *Searcher
- func (s *Searcher) Text(text string) *Searcher
- func (s *Searcher) Tvshow(tvs *Searcher) *Searcher
- func (s *Searcher) Votes(min, max int) *Searcher
- func (s *Searcher) Years(min, max int) *Searcher
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var Commands []Command
Commands represents all available search directives that are available in a search query string.
Functions ¶
This section is empty.
Types ¶
type Chooser ¶
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 ¶
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 ¶
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.
type Result ¶
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.
type Searcher ¶
type Searcher struct {
// contains filtered or unexported fields
}
Searcher represents the parameters of a search.
func New ¶
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 ¶
Example New finds the top 10 ranked Simpsons episodes with 500 or more votes using methods on a Searcher value.
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)
}
Output:
func Query ¶
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 ¶
Example Query finds the top 10 ranked Simpsons episodes with 500 or more votes using a query string.
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)
}
Output:
func (*Searcher) Atom ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
NoTvMovies filters out "made for TV" movies from a search.
func (*Searcher) NoVideoMovies ¶
NoVideoMovies filters out "made for video" movies from a search.
func (*Searcher) Pick ¶
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 ¶
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 ¶
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) Seasons ¶
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 ¶
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 ¶
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 ¶
Text adds the given string to the query string as plain text. It is not parsed for search directives.
func (*Searcher) Tvshow ¶
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.)
Source Files