// Params describe the action parameters, either path parameters identified via wildcards or query
// string parameters if there is no corresponding path parameter. Each parameter is described via
// the Param function which uses the same DSL as the Attribute DSL. Here is an example:
//
//	Params(func() {
//		Param("id", Integer)		// A path parameter defined using e.g. GET("/:id")
//		Param("sort", String, func() {	// A query string parameter
//			Enum("asc", "desc")
//		})
//	})
//
// Params can be used inside Action to define the action parameters, Resource to define common
// parameters to all the resource actions or API to define common parameters to all the API actions.
//
// If Params is used inside Resource or Action then the resource base media type attributes provide
// default values for all the properties of params with identical names. For example:
//
//     var BottleMedia = MediaType("application/vnd.bottle", func() {
//         Attributes(func() {
//             Attribute("name", String, "The name of the bottle", func() {
//                 MinLength(2) // BottleMedia has one attribute "name" which is a
//                              // string that must be at least 2 characters long.
//             })
//         })
//         View("default", func() {
//             Attribute("name")
//         })
//     })
//
//     var _ = Resource("Bottle", func() {
//         DefaultMedia(BottleMedia) // Resource "Bottle" uses "BottleMedia" as default
//         Action("show", func() {   // media type.
//             Routing(GET("/:name"))
//             Params(func() {
//                 Param("name") // inherits type, description and validation from
//                               // BottleMedia "name" attribute
//             })
//         })
//     })
//
func Params(dsl func()) {
	var params *design.AttributeDefinition
	switch def := dslengine.CurrentDefinition().(type) {
	case *design.ActionDefinition:
		params = newAttribute(def.Parent.MediaType)
	case *design.ResourceDefinition:
		params = newAttribute(def.MediaType)
	case *design.APIDefinition:
		params = new(design.AttributeDefinition)
	default:
		dslengine.IncompatibleDSL()
	}
	params.Type = make(design.Object)
	if !dslengine.Execute(dsl, params) {
		return
	}
	switch def := dslengine.CurrentDefinition().(type) {
	case *design.ActionDefinition:
		def.Params = def.Params.Merge(params) // Useful for traits
	case *design.ResourceDefinition:
		def.Params = def.Params.Merge(params) // Useful for traits
	case *design.APIDefinition:
		def.Params = def.Params.Merge(params) // Useful for traits
	}
}

// licenseDefinition returns true and current context if it is an APIDefinition,
// nil and false otherwise.
func licenseDefinition() (*design.LicenseDefinition, bool) {
	l, ok := dslengine.CurrentDefinition().(*design.LicenseDefinition)
	if !ok {
		dslengine.IncompatibleDSL()
	}
	return l, ok
}

// responseDefinition returns true and current context if it is a ResponseDefinition,
// nil and false otherwise.
func responseDefinition(failIfNotResponse bool) (*design.ResponseDefinition, bool) {
	r, ok := dslengine.CurrentDefinition().(*design.ResponseDefinition)
	if !ok && failIfNotResponse {
		dslengine.IncompatibleDSL(dslengine.Caller())
	}
	return r, ok
}

// actionDefinition returns true and current context if it is an ActionDefinition,
// nil and false otherwise.
func actionDefinition(failIfNotAction bool) (*design.ActionDefinition, bool) {
	a, ok := dslengine.CurrentDefinition().(*design.ActionDefinition)
	if !ok && failIfNotAction {
		dslengine.IncompatibleDSL(dslengine.Caller())
	}
	return a, ok
}

// typeDefinition returns true and current context if it is a UserTypeDefinition,
// nil and false otherwise.
func typeDefinition(failIfNotMT bool) (*design.UserTypeDefinition, bool) {
	m, ok := dslengine.CurrentDefinition().(*design.UserTypeDefinition)
	if !ok && failIfNotMT {
		dslengine.IncompatibleDSL(dslengine.Caller())
	}
	return m, ok
}

// docsDefinition returns true and current context if it is a DocsDefinition,
// nil and false otherwise.
func docsDefinition(failIfNotDocs bool) (*design.DocsDefinition, bool) {
	a, ok := dslengine.CurrentDefinition().(*design.DocsDefinition)
	if !ok && failIfNotDocs {
		dslengine.IncompatibleDSL(dslengine.Caller())
	}
	return a, ok
}

// licenseDefinition returns true and current context if it is an APIDefinition,
// nil and false otherwise.
func licenseDefinition(failIfNotLicense bool) (*design.LicenseDefinition, bool) {
	l, ok := dslengine.CurrentDefinition().(*design.LicenseDefinition)
	if !ok && failIfNotLicense {
		dslengine.IncompatibleDSL(dslengine.Caller())
	}
	return l, ok
}

// Scope defines an authorization scope. Used within SecurityScheme, a description may be provided
// explaining what the scope means. Within a Security block, only a scope is needed.
func Scope(name string, desc ...string) {
	switch current := dslengine.CurrentDefinition().(type) {
	case *design.SecurityDefinition:
		if len(desc) >= 1 {
			dslengine.ReportError("too many arguments")
			return
		}
		current.Scopes = append(current.Scopes, name)
	case *design.SecuritySchemeDefinition:
		if len(desc) > 1 {
			dslengine.ReportError("too many arguments")
			return
		}
		if current.Scopes == nil {
			current.Scopes = make(map[string]string)
		}
		d := "no description"
		if len(desc) == 1 {
			d = desc[0]
		}
		current.Scopes[name] = d
	default:
		dslengine.IncompatibleDSL()
	}
}

// encodingDefinition returns true and current context if it is an EncodingDefinition,
// nil and false otherwise.
func encodingDefinition(failIfNotEnc bool) (*design.EncodingDefinition, bool) {
	e, ok := dslengine.CurrentDefinition().(*design.EncodingDefinition)
	if !ok && failIfNotEnc {
		dslengine.IncompatibleDSL(dslengine.Caller())
	}
	return e, ok
}

// responseDefinition returns true and current context if it is a ResponseDefinition,
// nil and false otherwise.
func responseDefinition() (*design.ResponseDefinition, bool) {
	r, ok := dslengine.CurrentDefinition().(*design.ResponseDefinition)
	if !ok {
		dslengine.IncompatibleDSL()
	}
	return r, ok
}

// Metadata is a set of key/value pairs that can be assigned to an object. Each value consists of a
// slice of strings so that multiple invocation of the Metadata function on the same target using
// the same key builds up the slice. Metadata may be set on attributes, media types, actions,
// responses, resources and API definitions.
//
// While keys can have any value the following names are handled explicitly by goagen when set on
// attributes.
//
// `struct:field:name`: overrides the Go struct field name generated by default by goagen.
// Applicable to attributes only.
//
//        Metadata("struct:field:name", "MyName")
//
// `struct:tag:xxx`: sets the struct field tag xxx on generated Go structs.  Overrides tags that
// goagen would otherwise set.  If the metadata value is a slice then the strings are joined with
// the space character as separator.
// Applicable to attributes only.
//
//        Metadata("struct:tag:json", "myName,omitempty")
//        Metadata("struct:tag:xml", "myName,attr")
//
// `swagger:generate`: specifies whether Swagger specification should be generated. Defaults to
// true.
// Applicable to resources, actions and file servers.
//
//        Metadata("swagger:generate", "false")
//
// `swagger:summary`: sets the Swagger operation summary field.
// Applicable to actions.
//
//        Metadata("swagger:summary", "Short summary of what action does")
//
// `swagger:tag:xxx`: sets the Swagger object field tag xxx.
// Applicable to resources and actions.
//
//        Metadata("swagger:tag:Backend")
//        Metadata("swagger:tag:Backend:desc", "Quick description of what 'Backend' is")
//        Metadata("swagger:tag:Backend:url", "http://example.com")
//        Metadata("swagger:tag:Backend:url:desc", "See more docs here")
//
// `swagger:extension:xxx`: sets the Swagger extensions xxx. It can have any valid JSON format value.
// Applicable to
// api as within the info and tag object,
// resource as within the paths object,
// action as within the path-item object,
// route as within the operation object,
// param as within the parameter object,
// response as within the response object
// and security as within the security-scheme object.
// See https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/EXTENSIONS.md.
//
//        Metadata("swagger:extension:x-api", `{"foo":"bar"}`)
//
// The special key names listed above may be used as follows:
//
//        var Account = Type("Account", func() {
//                Attribute("service", String, "Name of service", func() {
//                        // Override default name to avoid clash with built-in 'Service' field.
//                        Metadata("struct:field:name", "ServiceName")
//                })
//        })
//
func Metadata(name string, value ...string) {
	appendMetadata := func(metadata dslengine.MetadataDefinition, name string, value ...string) dslengine.MetadataDefinition {
		if metadata == nil {
			metadata = make(map[string][]string)
		}
		metadata[name] = append(metadata[name], value...)
		return metadata
	}

	switch def := dslengine.CurrentDefinition().(type) {
	case design.ContainerDefinition:
		att := def.Attribute()
		att.Metadata = appendMetadata(att.Metadata, name, value...)
	case *design.AttributeDefinition:
		def.Metadata = appendMetadata(def.Metadata, name, value...)
	case *design.MediaTypeDefinition:
		def.Metadata = appendMetadata(def.Metadata, name, value...)
	case *design.ActionDefinition:
		def.Metadata = appendMetadata(def.Metadata, name, value...)
	case *design.FileServerDefinition:
		def.Metadata = appendMetadata(def.Metadata, name, value...)
	case *design.ResourceDefinition:
		def.Metadata = appendMetadata(def.Metadata, name, value...)
	case *design.ResponseDefinition:
		def.Metadata = appendMetadata(def.Metadata, name, value...)
	case *design.APIDefinition:
		def.Metadata = appendMetadata(def.Metadata, name, value...)
	case *design.RouteDefinition:
		def.Metadata = appendMetadata(def.Metadata, name, value...)
	case *design.SecurityDefinition:
		def.Scheme.Metadata = appendMetadata(def.Scheme.Metadata, name, value...)
	default:
		dslengine.IncompatibleDSL()
	}
}

// actionDefinition returns true and current context if it is an ActionDefinition,
// nil and false otherwise.
func actionDefinition() (*design.ActionDefinition, bool) {
	a, ok := dslengine.CurrentDefinition().(*design.ActionDefinition)
	if !ok {
		dslengine.IncompatibleDSL()
	}
	return a, ok
}

// corsDefinition returns true and current context if it is a CORSDefinition, nil And
// false otherwise.
func corsDefinition() (*design.CORSDefinition, bool) {
	cors, ok := dslengine.CurrentDefinition().(*design.CORSDefinition)
	if !ok {
		dslengine.IncompatibleDSL()
	}
	return cors, ok
}

// typeDefinition returns true and current context if it is a UserTypeDefinition,
// nil and false otherwise.
func typeDefinition() (*design.UserTypeDefinition, bool) {
	m, ok := dslengine.CurrentDefinition().(*design.UserTypeDefinition)
	if !ok {
		dslengine.IncompatibleDSL()
	}
	return m, ok
}

// buildSourceDefinition returns true and current context if it is an BuildSource
// nil and false otherwise.
func buildSourceDefinition(failIfNotSD bool) (*gorma.BuildSource, bool) {
	a, ok := dslengine.CurrentDefinition().(*gorma.BuildSource)
	if !ok && failIfNotSD {
		dslengine.IncompatibleDSL()
	}
	return a, ok
}

// contactDefinition returns true and current context if it is an ContactDefinition,
// nil and false otherwise.
func contactDefinition(failIfNotContact bool) (*design.ContactDefinition, bool) {
	a, ok := dslengine.CurrentDefinition().(*design.ContactDefinition)
	if !ok && failIfNotContact {
		dslengine.IncompatibleDSL(dslengine.Caller())
	}
	return a, ok
}

// attributeDefinition returns true and current context if it is an AttributeDefinition
// nil and false otherwise.
func attributeDefinition(failIfNotSD bool) (*design.AttributeDefinition, bool) {
	a, ok := dslengine.CurrentDefinition().(*design.AttributeDefinition)
	if !ok && failIfNotSD {
		dslengine.IncompatibleDSL()
	}
	return a, ok
}

// relationalModelDefinition returns true and current context if it is an RelationalModelDefinition,
// nil and false otherwise.
func relationalModelDefinition(failIfNotSD bool) (*gorma.RelationalModelDefinition, bool) {
	a, ok := dslengine.CurrentDefinition().(*gorma.RelationalModelDefinition)
	if !ok && failIfNotSD {
		dslengine.IncompatibleDSL()
	}
	return a, ok
}

// encodingDefinition returns true and current context if it is an EncodingDefinition,
// nil and false otherwise.
func encodingDefinition() (*design.EncodingDefinition, bool) {
	e, ok := dslengine.CurrentDefinition().(*design.EncodingDefinition)
	if !ok {
		dslengine.IncompatibleDSL()
	}
	return e, ok
}

// relationalFieldDefinition returns true and current context if it is an RelationalFieldDefinition,
// nil and false otherwise.
func relationalFieldDefinition(failIfNotSD bool) (*gorma.RelationalFieldDefinition, bool) {
	a, ok := dslengine.CurrentDefinition().(*gorma.RelationalFieldDefinition)
	if !ok && failIfNotSD {
		incompatibleDSL(caller())
	}
	return a, ok
}