{Begin SubSec Functions for Manipulating File Command Lists}
{Title Functions for Manipulating File Command Lists}
{Text

{Tag ManipulatingFileComs}

{index *BEGIN* file package functions}


The following functions may be used to manipulate filecoms.  Note that the argument {arg COMS} does {it not} have to correspond to the filecoms for some file.  For example, {arg COMS} can be the list of commands generated as a result of expanding a user defined file package command.



{FnDef {FnName INFILECOMS?} {FnArgs NAME TYPE COMS {anonarg}}
{Text
{arg COMS} is a list of file package commands, or a variable whose value is  a list of file package commands.  {arg TYPE} is a file package type.  {fn INFILECOMS?} returns {lisp T} if {arg NAME} of type {arg TYPE} is "contained" in {arg COMS}.

If {arg NAME}={lisp NIL}, {fn INFILECOMS?} returns a list of all elements of type {arg TYPE}.

If {arg NAME}={lisp T}, {fn INFILECOMS?} returns {lisp T} if there are {it any} elements of type {arg TYPE} in {arg COMS}.
}}


{FnDef {FnName ADDTOFILE} {FnArgs NAME TYPE FILE NEAR LISTNAME}
{Text
Adds {arg NAME} of type {arg TYPE} to the file package commands for {arg FILE}.  If {arg NEAR} is given and it is the name of an item of type {arg TYPE} already on {arg FILE}, then {arg NAME} is added to the command that dumps {arg NEAR}.  If {arg LISTNAME} is given and is the name of a list of items of {arg TYPE} items on {arg FILE}, then {arg NAME} is added to that list.  Uses {fn ADDTOCOMS} and {fn MAKENEWCOM}.  Returns {arg FILE}.  {fn ADDTOFILE} is undoable.
}}


{FnDef {FnName DELFROMFILES} {FnArgs NAME TYPE FILES}
{Text
Deletes all instances of {arg NAME} of type {arg TYPE} from the filecoms for each of the files on {arg FILES}.  If {arg FILES} is a non-{lisp NIL} litatom, {lisp (LIST {arg FILES})} is used.  {arg FILES}={lisp NIL} defaults to {var FILELST}.  Returns a list of files from which {arg NAME} was actually removed.  Uses {fn DELFROMCOMS}.  {fn DELFROMFILES} is undoable.

Note:  Deleting a function will also remove the function from any {lisp BLOCKS} declarations in the filecoms.

{note DELFROMFILE is synonym}
}}



{FnDef {FnName ADDTOCOMS} {FnArgs COMS NAME TYPE NEAR LISTNAME}
{Text
Adds {arg NAME} as a {arg TYPE} to {arg COMS}, a list of file package commands or a variable whose value is a list of file package commands.  Returns {lisp NIL} if {fn ADDTOCOMS} was unable to find a command appropriate for adding {arg NAME} to {arg COMS}.  {arg NEAR} and {arg LISTNAME} are described in the discussion of {fn ADDTOFILE}.  {fn ADDTOCOMS} is undoable.


Note that the exact algorithm for adding commands depends the particular command itself.  See discussion of the {lisp ADD} property, in the description of {fn FILEPKGCOM}, {PageRef Fn FILEPKGCOM}.



Note:  {fn ADDTOCOMS} will not attempt to add an item to any command which is inside of a {filecom DECLARE:} unless the user specified a specific name via the {lisp LISTNAME} or {lisp NEAR} option of {fn ADDTOFILES?}.

{Begin Note}
Personal Opinion:  I'm sure its much too late to change, but it certainly would be nice if ADDTOCOMS' arg order was, NAME TYPE COMS, to make it more consistant with ADDTOFILE.   ---mjs
{End Note}
}}


{FnDef {FnName DELFROMCOMS} {FnArgs COMS NAME TYPE}
{Text
Deletes {arg NAME} as a {arg TYPE} from {arg COMS}.  Returns {lisp NIL} if {fn DELFROMCOMS} was unable to modify {arg COMS} to delete {arg NAME}.  {fn DELFROMCOMS} is undoable.
}}


{FnDef {FnName MAKENEWCOM} {FnArgs NAME TYPE {anonarg} {anonarg}}
{Text
Returns a file package command for dumping {arg NAME} of type {arg TYPE}. Uses the procedure described in the discussion of {lisp NEWCOM}, {PageRef Fn FILEPKGTYPE}.
}}


{FnDef {FnName MOVETOFILE} {FnArgs TOFILE NAME TYPE FROMFILE}
{Text
Moves the definition of {arg NAME} as a {arg TYPE} from {arg FROMFILE} to
{arg TOFILE} by modifying the file commands in the appropriate way
(with {fn DELFROMFILES} and {fn ADDTOFILE}).

Note that if {arg FROMFILE} is specified, the definition will be retrieved from that file, even if there is another definition currently in the user's environment.

{Begin Note}
<<<MOVEITEM is still a synonym for MOVETOFILE>>>>

Date: 19 NOV 1978 1607-PST
From: MASINTER

The new name for what the manual calls MOVEITEM is MOVETOFILE.
I wish I had thought of the better name before the manual went to press.
{End Note}


{Begin Note}
Date:  8 FEB 1981 2346-PST
From: KAPLAN
Subject: MOVEITEM problem

In a recent message to Teitelman, you complained about the behavior of MOVEITEM.  In particular, you found that if the latest version of the function was in core, it would ignore that definition and retrieve an older definition from a file, clobber the in-core def with that one, and move the older one to the new file.

This is how the function behaves when you specify a particular file for the FROMFILE argument.  By specifying that file, you are indicating that the definition you want is NOT the in-core definition, but rather the one from that file.  If, however, you don't specify a file, you are indicating that you want either the current in-core def, a saved definition, or one from some file known to WHEREIS.  Thus, if you hadn't specified a FROMFILE in your call, you would have gotten what you expected.

I don't think this is a bug in the logic of MOVEITEM.  Perhaps a caveat in the manual about the significance of the FROMFILE argument is in order.
{End Note}
}}


{FnDef {FnName FILECOMSLST} {FnArgs FILE TYPE {anonarg}}
{Text
Returns a list of all objects of type {arg TYPE} in {arg FILE}.

{arg TYPE} can also be the name of a file package command.  For example, {lisp (FILECOMSLST {arg FILE} 'BLOCKS)} will return the list of all {filecom BLOCKS} declaration in {arg FILE}.  {fn FILECOMSLST} knows about expanding user defined file package commands.
}}


{FnDef {FnName FILEFNSLST} {FnArgs FILE}
{Text
Same as {lisp (FILECOMSLST {arg FILE} 'FNS)}.
}}


{FnDef {FnName FILECOMS} {FnArgs FILE TYPE}
{Text
Returns {lisp (PACK* {arg FILE} (OR {arg TYPE} 'COMS))}.
Note that {lisp (FILECOMS 'FOO)} returns the litatom {lisp FOOCOMS}, not the value of {lisp FOOCOMS}.
}}


{FnDef {FnName SMASHFILECOMS} {FnArgs FILE}
{Text
Maps down {lisp (FILECOMSLST {arg FILE} 'FILEVARS)} and sets to {lisp NOBIND} all filevars{index filevars} (see {PageRef Tag FileVars}), i.e. any variable used in a command of the form {lisp ({arg COMMAND} * {arg VARIABLE})}.  Also sets {lisp (FILECOMS {arg FILE})} to {lisp NOBIND}.  Returns {arg FILE}.
}}

{index *END* file package functions}

}{End SubSec Functions for Manipulating File Command Lists}